Add location helper reference outputs

H3_LONG_VIDEOS_GUIDE.md

@@ -1149,81 +1149,42 @@ These two belong together.
 
 If you change `shift_video`, you usually need to change `shift_audio` in proportion.
 
-## Group 8: Detail Pass
+## Group 8: Latent Upscale
 
-This is the optional second pass.
+This is the optional latent refinement stage, used before decode.
 
-### `detail_pass`
-
-Enables the refinement pass.
+The long-video node now expects a separate `Dumas H3 Latent Upscale Params` node for this stage.
+Wire that node into the `latent_upscale_param` input when you want the shot to be upscaled and lightly
+re-sampled before decode.
 
 What this really means:
 
 - the node renders the beat once
-- then runs a second sampler pass over that result
-- the goal is to polish, not to invent a whole different shot
-
-### `detail_sampler_name`
-
-Sampler for the refinement pass.
-
-### `detail_scheduler`
-
-Scheduler for the refinement pass.
-
-### `detail_steps`
-
-Extra steps for the refinement pass.
-
-What this really means:
-
-- more steps gives the second pass more opportunity to change the image
-- that can help detail
-- but after a point it stops being "cleanup" and starts becoming "rewrite"
-
-### `detail_denoise`
-
-How strongly the refinement pass is allowed to rewrite the beat.
-
-What this really means:
-
-- low denoise = polish what is already there
-- high denoise = let the second pass substantially alter what is already there
-
-### How The Detail-Pass Settings Work Together
-
-The detail pass starts from the first-pass result and tries to polish it.
-
-Gentle settings:
-
-- low to medium `detail_steps`
-- low `detail_denoise`
-
-Aggressive settings:
-
-- high `detail_steps`
-- high `detail_denoise`
-
-Aggressive settings can improve texture, but they can also:
-
-- change faces
-- pull away from references
-- break continuity
-
-That is why this group should be read as one combined strength control:
-
-- `detail_pass` decides whether the second pass exists
-- `detail_steps` decides how long it keeps working
-- `detail_denoise` decides how free it is to change things
-- `detail_sampler_name` and `detail_scheduler` shape how that rewrite behaves
+- the sampled latent is upscaled in latent space to the target size
+- the conditioning is rebuilt at that target size
+- the node then runs a short refinement pass over the upscaled latent with the sampler, scheduler, step count, denoise, and megapixel target you picked on the latent-upscale params node
+- if the target is larger than the spatial tile size, that refinement pass is processed in spatial batches using the same tile defaults as the upstream latent-split node
+- the spatial stitch mode follows the upstream overlap controls, including `linear`, `smoothstep`, `overwrite`, and `midpoint`
+- the node also carries the upstream split compatibility knobs (`chunk_length`, `temporal_overlap`, `resize_conditioning`, and `anchor_strength`) so the control surface stays in one place
 
 Good starting point:
 
-- `detail_pass = on`
-- `detail_sampler_name = euler`
-- `detail_scheduler = beta`
-- `detail_steps = 4` to `8`
-- `detail_denoise = 0.20` to `0.35`
+- use the `model` mode when you want the strongest latent detail recovery
+- use the interpolation mode when you want a cheaper resize-only path
+- start with `euler_ancestral`, `simple`, `2` steps, and `0.2` denoise
+- leave width and height at `0` unless you want an exact override; otherwise `megapixels` drives the target size
+- for long shots on smaller cards, start with `chunk_length = 85` and `temporal_overlap = 17` so the latent upscaler works in shorter temporal passes
+- leave the spatial tile inputs at their defaults first: `512x512` tiles, `64` overlap, `0` fade width, `earlier` overlap mode
+- keep `linear` blend first unless you want to reproduce a specific upstream stitch style
+- leave the split compatibility knobs alone unless you specifically need to mirror the upstream node behavior
+
+The important part is that this stage is still a latent pass, not a pixel-space resize:
+
+- it happens before decode
+- it can change structure more than a normal image upscale
+- it is the place to recover detail without adding another full detail-pass toggle
+
+If you do not wire the helper node, the long-video node skips latent upscale entirely and renders as before.
 
 ## Group 9: Performance, Decode, And Upscale
 

README.md

@@ -43,13 +43,26 @@
   - Prompt `<Picture N>` tags now map to the actual ref socket numbers you wire, even with gaps such as only `ref_2` and `ref_7` connected.
   - Character refs now contribute appearance and wardrobe context from the same structured object, while location refs contribute environment context from theirs.
   - The default ref2v bias is now stronger: `ref_mode` defaults to `auto ref2v` so untagged prompts condition every shot instead of only shot 1, and `ref_noise_aug` defaults to `0.95` rather than the upstream-literal `0.999`.
+  - `Dumas H3 Latent Upscale Params` provides the optional pre-decode latent refinement stage for the long-video node.
   - Per-shot directives now support `continuity:`, `ref_mode:`, `ref_noise_aug:`, `anchor_add:`, `soundscape:`, and `music:` in addition to the existing timing and wardrobe directives.
 
+- `Dumas H3 Latent Upscale Params`
+  - Inputs: `mode`, `model_name`, `method`, `width`, `height`, `device`, `precision`, `sampler_name`, `scheduler`, `steps`, `denoise`, `megapixels`, `tile_width`, `tile_height`, `overlap`, `fade_width`, `fade_height`, `overlap_mode`, `overlap_blend`, `tile_size_mode`, `grid_rows`, `grid_cols`, `spatial_w_overlap`, `spatial_h_overlap`, `min_tile_size`, `masked_area_noise`, `brightness_match`, `dynamic_fade`, `dynamic_fade_min`, `chunk_length`, `temporal_overlap`, `resize_conditioning`, `anchor_strength`
+  - Output: `latent_upscale_param`
+  - Bundles the optional latent-space upscaler settings used by `Dumas H3 Long Videos` before decode, so the main node can rebuild conditioning at the target size and run a short refinement pass with your chosen sampler, scheduler, step count, denoise, and the full upstream spatial split controls.
+
 - `Dumas H3 Beat Prompt`
   - Inputs: authored through the custom front-end beat editor
   - Output: `prompt`
   - Builds one H3 prompt block per beat, with quick controls for per-shot timing, continuity, ref behavior, anchor additions, soundscape, and music while staying compatible with direct text editing.
 
+- `Dumas H3 Prompt Curator`
+  - Inputs: `action_prompt`, `anatomy_guard`, `subject_count_guard`, optional `anchor`, optional `soundscape`, optional `ref_1` through `ref_9`
+  - Outputs: `prompt`, `ref_image_1` through `ref_image_9`, `reference_count`, `debug`
+  - Builds one standalone MiniMax H3 prompt from your final action text plus structured character/location references.
+  - The action text can mention references by character/location name, alias, `<Picture N>`, or `<refN>`. Only mentioned references are emitted, and the output images are compacted/renumbered so skipped inputs do not leave gaps.
+  - Adds curated reference context, anatomy guard text, optional subject-count guard text, anchor/style text, and `overall_soundscape:` text while respecting MiniMax H3's reference-generation shape: one prompt plus up to nine reference images.
+
 - `Dumas H3 Shot Length`
   - Inputs: `shot_seconds`, `fps`, optional `cap_to_h3_max`
   - Outputs: `seconds`, `frames`, `info`
@@ -70,6 +83,18 @@
   - Output: `reference`
   - Builds one structured `REFERENCE` object for a location/environment so H3 can use the same socket type for both character and scenic refs.
 
+- `Dumas Character Helper`
+  - Inputs: `image1`, `image2`, picture IDs, character identity fields, `general`, `wardrobe`
+  - Outputs: `image1`, `image2`, `reference_prompt`, `wardrobe`, `reference1`, `reference2`
+  - Restores the original general-purpose helper shape while also emitting two structured `REFERENCE` objects for the prompt curator.
+  - The structured references carry the same character name, alias, age, height, gender, nationality, occupation, accent, wardrobe, and notes, so mentioning the character name in `Dumas H3 Prompt Curator` can include both helper images and the character facts automatically.
+
+- `Dumas Location Helper`
+  - Inputs: `image1`, `image2`, picture IDs, `location_id`, `name`, `alias`, `description`, `general`
+  - Outputs: `image1`, `image2`, `reference_prompt`, `reference1`, `reference2`
+  - Matching general-purpose helper for environments/locations: pass two images through unchanged, emit location reference prompt text, and provide two structured `REFERENCE` objects for the prompt curator.
+  - The structured references carry the same location name, alias, description, and notes, so mentioning the location name in `Dumas H3 Prompt Curator` can include both helper images and the location context automatically.
+
 - `Dumas Anchor Style`
   - Inputs: `anchor_style`, `style_description`
   - Output: `anchor`
@@ -77,6 +102,11 @@
   - The preset wording is tuned for H3-safe persistent anchors: camera language, lighting, texture, production treatment, and tone, without naming characters or describing one-off actions.
   - Selecting a preset fills the editable description field, and the edited multiline description is the `STRING` value passed downstream into H3 anchor sockets such as `anchor_override`.
 
+- `Dumas Soundscape Helper`
+  - Inputs: `soundscape`, `soundscape_description`
+  - Output: `soundscape`
+  - Matching soundscape helper for standalone H3 prompts. Pick a preset such as quiet interior, rainy street, cafe, city night, forest, industrial, or silent, then edit the text that flows into `Dumas H3 Prompt Curator`.
+
 - `Dumas JSON String to Object`
   - Input: `json_string`
   - Output: parsed `JSON`
@@ -233,7 +263,7 @@ decr  -> use index - 1
 
 `Dumas H3 Plan Attach Scene Images` and `Dumas H3 Plan Extract Scene Images` are a companion pair for `ComfyUI-MiniMaxH3-Contex-Loop` and the local `ref2v` lane. The upstream H3 plan node cannot dynamically grow nine new image sockets for every JSON-defined scene, so Dumas stores scene image bindings beside the plan using a lightweight token and an in-memory registry. That keeps `plan.json` archiving intact while still letting you wire up nine IMAGE sockets per scene through chained helper nodes.
 
-`Dumas Character Reference` and `Dumas Location Reference` live in `Dumas/MiniMax`. Both output a structured `REFERENCE` object that carries the image plus its semantic payload. `Dumas H3 Long Videos` accepts those `REFERENCE` sockets directly on `ref_1`..`ref_9`, resolves `<Picture N>` against the wired slot positions, and can also pull character wardrobe context from the structured ref data when `character_memory` is left blank.
+`Dumas Character Helper` is the restored two-image/text helper for general H3 workflows, and `Dumas Location Helper` mirrors it for scene/environment references. Both helpers also emit structured `REFERENCE` sockets for the curator. The structured `Dumas Character Reference` and `Dumas Location Reference` nodes remain available separately for workflows that want a single `REFERENCE` socket. `Dumas H3 Prompt Curator` consumes those structured references, assigns the final `<Picture N>` numbering, and outputs only the compacted images the prompt actually mentions.
 
 `Dumas Strip Iteration Suffix` keeps the part before the first underscore and drops the rest. Names like `char123_pose_final.png` become `char123.png`, while names with no underscore such as `char123.png` are left untouched.
 

__init__.py

@@ -14,6 +14,10 @@ from .dumas_h3_longvideos import (
     NODE_CLASS_MAPPINGS as H3_LONGVIDEO_NODE_CLASS_MAPPINGS,
     NODE_DISPLAY_NAME_MAPPINGS as H3_LONGVIDEO_NODE_DISPLAY_NAME_MAPPINGS,
 )
+from .dumas_h3_latent_upscale import (
+    NODE_CLASS_MAPPINGS as H3_LATENT_UPSCALE_NODE_CLASS_MAPPINGS,
+    NODE_DISPLAY_NAME_MAPPINGS as H3_LATENT_UPSCALE_NODE_DISPLAY_NAME_MAPPINGS,
+)
 from .dumas_h3_shot_length import (
     NODE_CLASS_MAPPINGS as H3_SHOT_LENGTH_NODE_CLASS_MAPPINGS,
     NODE_DISPLAY_NAME_MAPPINGS as H3_SHOT_LENGTH_NODE_DISPLAY_NAME_MAPPINGS,
@@ -31,6 +35,7 @@ NODE_CLASS_MAPPINGS = {}
 NODE_CLASS_MAPPINGS.update(JSON_NODE_CLASS_MAPPINGS)
 NODE_CLASS_MAPPINGS.update(IMAGE_NODE_CLASS_MAPPINGS)
 NODE_CLASS_MAPPINGS.update(H3_LONGVIDEO_NODE_CLASS_MAPPINGS)
+NODE_CLASS_MAPPINGS.update(H3_LATENT_UPSCALE_NODE_CLASS_MAPPINGS)
 NODE_CLASS_MAPPINGS.update(H3_SHOT_LENGTH_NODE_CLASS_MAPPINGS)
 NODE_CLASS_MAPPINGS.update(H3_INSPECTOR_NODE_CLASS_MAPPINGS)
 NODE_CLASS_MAPPINGS.update(H3_BEAT_PROMPT_NODE_CLASS_MAPPINGS)
@@ -39,6 +44,7 @@ NODE_DISPLAY_NAME_MAPPINGS = {}
 NODE_DISPLAY_NAME_MAPPINGS.update(JSON_NODE_DISPLAY_NAME_MAPPINGS)
 NODE_DISPLAY_NAME_MAPPINGS.update(IMAGE_NODE_DISPLAY_NAME_MAPPINGS)
 NODE_DISPLAY_NAME_MAPPINGS.update(H3_LONGVIDEO_NODE_DISPLAY_NAME_MAPPINGS)
+NODE_DISPLAY_NAME_MAPPINGS.update(H3_LATENT_UPSCALE_NODE_DISPLAY_NAME_MAPPINGS)
 NODE_DISPLAY_NAME_MAPPINGS.update(H3_SHOT_LENGTH_NODE_DISPLAY_NAME_MAPPINGS)
 NODE_DISPLAY_NAME_MAPPINGS.update(H3_INSPECTOR_NODE_DISPLAY_NAME_MAPPINGS)
 NODE_DISPLAY_NAME_MAPPINGS.update(H3_BEAT_PROMPT_NODE_DISPLAY_NAME_MAPPINGS)

dumas_h3_inspector.py

@@ -150,7 +150,16 @@ class H3ModelInspector:
 
     @classmethod
     def INPUT_TYPES(cls):
-        return {"required": {"model": ("MODEL",)}}
+        return {
+            "required": {
+                "model": (
+                    "MODEL",
+                    {
+                        "tooltip": "MiniMax / H3 model to inspect for quantization and tensor format."
+                    },
+                )
+            }
+        }
 
     def inspect(self, model):
         label, _counts, report = _detect(model)

dumas_h3_longvideos.py

@@ -32,9 +32,10 @@ and your VRAM, chains them, and returns the finished video + audio.
 
 Requirements: H3 is CFG-free (cfg 1) and needs no negative prompt -- the node
 makes an empty one internally. The main pass keeps denoise fixed at 1.0: a
-partial denoise desyncs the joint audio/video schedule. An optional refinement
-pass can use its own denoise later, before any upscale, while keeping the output
-video-only.
+partial denoise desyncs the joint audio/video schedule. An optional latent
+upscale stage can rebuild the conditioning at a target size, run a short
+refinement pass with its own sampler controls, and keep the output video-only
+before the final pixel-space upscale options.
 
 Verified against ComfyUI core (comfy_extras/nodes_minimax_h3.py, model_base.py,
 ldm/minimax/model.py, text_encoders/minimax.py, sd.py).
@@ -59,6 +60,7 @@ import node_helpers
 
 try:
     from . import dumas_h3_overlay as _overlay
+    from .dumas_h3_latent_upscale import upscale_latent_video as _upscale_latent_video
     from . import dumas_image_nodes as _image_nodes
 except ImportError:      # loaded as a bare file (test_prompt_logic.py), not as a package
     import importlib.util as _ilu
@@ -70,6 +72,13 @@ except ImportError:      # loaded as a bare file (test_prompt_logic.py), not as
     )
     _overlay = _ilu.module_from_spec(_spec)
     _spec.loader.exec_module(_overlay)
+    _latent_spec = _ilu.spec_from_file_location(
+        "dumas_h3_latent_upscale",
+        _os.path.join(_os.path.dirname(_os.path.abspath(__file__)), "dumas_h3_latent_upscale.py"),
+    )
+    _latent_upscale = _ilu.module_from_spec(_latent_spec)
+    _latent_spec.loader.exec_module(_latent_upscale)
+    _upscale_latent_video = _latent_upscale.upscale_latent_video
     _image_nodes = _sys.modules.get("dumas_image_nodes")
     if _image_nodes is None:
         _img_spec = _ilu.spec_from_file_location(
@@ -279,8 +288,6 @@ ADDED_WIDGETS = (
     "exposed_terms", "anatomy_guard", "lock_restraints", "solidity_guard",
     "motion_guard", "contact_guard",
     "auto_soundscape", "allow_nonspeech_vocals",
-    "detail_pass", "detail_sampler_name", "detail_scheduler",
-    "detail_steps", "detail_denoise",
 )
 
 NL = "\n"
@@ -4033,6 +4040,88 @@ def _copy_sample_latent(out_latent):
         return None
 
 
+def _retarget_conditioning_spatial(cond, latent_h, latent_w):
+    """Resize H3 keyframe latents in existing conditioning to a new latent grid."""
+    latent_h = int(latent_h)
+    latent_w = int(latent_w)
+    if latent_h <= 0 or latent_w <= 0:
+        raise RuntimeError("conditioning target latent size must be positive")
+    out = []
+    for item in cond:
+        try:
+            tensor, data = item
+        except Exception:
+            out.append(item)
+            continue
+        nd = dict(data)
+        keyframes = nd.get("minimax_keyframes")
+        if keyframes:
+            resized_keyframes = []
+            for keyframe in keyframes:
+                nkf = dict(keyframe)
+                latent_value = nkf.get("latent")
+                if latent_value is not None and len(getattr(latent_value, "shape", ())) >= 5:
+                    if latent_value.shape[3] != latent_h or latent_value.shape[4] != latent_w:
+                        b, c, t, h, w = latent_value.shape
+                        resized = torch.nn.functional.interpolate(
+                            latent_value.to(torch.float32).reshape(b * t, c, h, w),
+                            size=(latent_h, latent_w),
+                            mode="bilinear",
+                            align_corners=False,
+                        ).reshape(b, c, t, latent_h, latent_w)
+                        nkf["latent"] = resized.to(device=latent_value.device, dtype=latent_value.dtype)
+                resized_keyframes.append(nkf)
+            nd["minimax_keyframes"] = resized_keyframes
+        out.append([tensor, nd])
+    return out
+
+
+def _pad_to_h3_patch_size(tensor):
+    try:
+        import comfy.ldm.common_dit as common_dit
+        return common_dit.pad_to_patch_size(tensor, (1, 2, 2))
+    except Exception:
+        return tensor
+
+
+def _crop_conditioning_to_tile(cond, source_h, source_w, row, col, tile_h, tile_w):
+    """Crop H3 keyframe latents in existing conditioning for a spatial tile."""
+    out = []
+    for item in cond:
+        try:
+            tensor, data = item
+        except Exception:
+            out.append(item)
+            continue
+        nd = dict(data)
+        keyframes = nd.get("minimax_keyframes")
+        if keyframes:
+            cropped_keyframes = []
+            for keyframe in keyframes:
+                nkf = dict(keyframe)
+                latent_value = nkf.get("latent")
+                if latent_value is not None and len(getattr(latent_value, "shape", ())) >= 5:
+                    kh, kw = latent_value.shape[3], latent_value.shape[4]
+                    if kh != source_h or kw != source_w:
+                        b, c, t, h, w = latent_value.shape
+                        latent_value = torch.nn.functional.interpolate(
+                            latent_value.to(torch.float32).reshape(b * t, c, h, w),
+                            size=(source_h, source_w),
+                            mode="bilinear",
+                            align_corners=False,
+                        ).reshape(b, c, t, source_h, source_w).to(
+                            device=latent_value.device,
+                            dtype=latent_value.dtype,
+                        )
+                    nkf["latent"] = _pad_to_h3_patch_size(
+                        latent_value[:, :, :, row:row + tile_h, col:col + tile_w].contiguous()
+                    )
+                cropped_keyframes.append(nkf)
+            nd["minimax_keyframes"] = cropped_keyframes
+        out.append([tensor, nd])
+    return out
+
+
 def _latent_with_replaced_samples(template_latent, sampled_latent):
     """Reuse the original latent payload, but swap in freshly sampled tensors."""
     if not isinstance(template_latent, dict):
@@ -4066,6 +4155,237 @@ def _video_only_refined_latent(base_latent, refined_latent):
     return refined_latent
 
 
+def _latent_upscale_target_size(base_w, base_h, param):
+    width = int(param.get("width", 0) or 0)
+    height = int(param.get("height", 0) or 0)
+    if width > 0 and height > 0:
+        return width, height
+    megapixels = float(param.get("megapixels", 0.0) or 0.0)
+    if megapixels > 0:
+        return scale_to_megapixels(base_w, base_h, megapixels)
+    return int(base_w), int(base_h)
+
+
+def _latent_upscale_mode(param):
+    if not isinstance(param, dict):
+        return "off"
+    mode = str(param.get("mode") or "").strip()
+    if mode:
+        return mode
+    if "model_name" in param and str(param.get("model_name") or "").strip() not in ("", "none"):
+        return "model"
+    if "method" in param:
+        return "interp"
+    return "off"
+
+
+def _latent_spatial_grid(h, w, th, tw, ol_h, ol_w):
+    if th <= 0 or tw <= 0:
+        raise ValueError("tile dimensions must be positive")
+    if ol_h >= th or ol_w >= tw:
+        raise ValueError("overlap must be smaller than the tile size")
+    sh = th - ol_h
+    sw = tw - ol_w
+    nrows = 1 if h <= th else math.ceil((h - ol_h) / sh)
+    if (nrows - 1) * sh + th < h:
+        nrows += 1
+    ncols = 1 if w <= tw else math.ceil((w - ol_w) / sw)
+    if (ncols - 1) * sw + tw < w:
+        ncols += 1
+    rows = [i * sh for i in range(nrows)]
+    cols = [j * sw for j in range(ncols)]
+    trows = [min(th, h - r) for r in rows]
+    tcols = [min(tw, w - c) for c in cols]
+    return rows, cols, trows, tcols
+
+
+def _latent_spatial_blend_weights(t, overlap_mode, overlap_blend="linear"):
+    if overlap_blend == "overwrite":
+        return torch.ones_like(t) if overlap_mode == "later" else torch.zeros_like(t)
+    if overlap_blend == "midpoint":
+        base = (t >= 0.5).to(t.dtype)
+    elif overlap_blend == "smoothstep":
+        base = t * t * (3.0 - 2.0 * t)
+    else:
+        base = t
+    if overlap_mode == "later":
+        return base
+    return 1.0 - base
+
+
+def _param_value(mapping, key, default):
+    value = mapping.get(key, default)
+    return default if value is None else value
+
+
+def _tag_oom_stage(exc, stage):
+    if _is_oom(exc):
+        exc._h3_stage = stage
+    return exc
+
+
+def _grid_1d(size, tile, ol, min_tile):
+    if size <= tile:
+        return [0], [size], [0]
+    sh = tile - ol
+    n = math.ceil((size - ol) / sh)
+    if (n - 1) * sh + tile < size:
+        n += 1
+    rows = [i * sh for i in range(n)]
+    trows = [min(tile, size - r) for r in rows]
+    if min_tile > 0 and n >= 2:
+        edge = size - rows[-1]
+        if edge < min_tile:
+            new_last = size - min_tile
+            if rows[-2] < new_last < rows[-2] + trows[-2]:
+                rows[-1] = new_last
+                trows[-1] = size - new_last
+    ovl = [0] * n
+    for i in range(1, n):
+        ovl[i] = max(0, rows[i - 1] + trows[i - 1] - rows[i])
+    return rows, trows, ovl
+
+
+def compute_spatial_grid(h, w, th, tw, ol_h, ol_w, min_th=0, min_tw=0):
+    if th <= 0 or tw <= 0:
+        raise ValueError("tile dimensions must be positive")
+    if ol_h >= th or ol_w >= tw:
+        raise ValueError("overlap must be smaller than the tile size")
+    if min_th < 0 or min_tw < 0:
+        raise ValueError("minimum tile size must be non-negative")
+    if min_th > th or min_tw > tw:
+        raise ValueError("minimum tile size must not exceed the tile size")
+    rows, trows, row_ovl = _grid_1d(h, th, ol_h, min_th)
+    cols, tcols, col_ovl = _grid_1d(w, tw, ol_w, min_tw)
+    return rows, cols, trows, tcols, row_ovl, col_ovl
+
+
+def spatial_fade_mask(tile_h, tile_w, ol_h, ol_w, done_top, done_left, fade_h=0, fade_w=0):
+    mask = torch.ones(tile_h, tile_w, dtype=torch.float32)
+    if done_left and ol_w > 0:
+        if fade_w == 0:
+            mask[:, :ol_w] = 0.0
+        else:
+            f = min(fade_w, ol_w)
+            frozen_w = ol_w - f
+            w = torch.linspace(0.0, 1.0, f)
+            mask[:, :frozen_w] = 0.0
+            mask[:, frozen_w:ol_w] = torch.minimum(mask[:, frozen_w:ol_w], w[None, :])
+    if done_top and ol_h > 0:
+        if fade_h == 0:
+            mask[:ol_h, :] = 0.0
+        else:
+            f = min(fade_h, ol_h)
+            frozen_h = ol_h - f
+            w = torch.linspace(0.0, 1.0, f)
+            mask[:frozen_h, :] = 0.0
+            mask[frozen_h:ol_h, :] = torch.minimum(mask[frozen_h:ol_h, :], w[:, None])
+    return mask
+
+
+def _fade_band(band, fade, axis):
+    n = band.shape[axis]
+    f = min(int(fade), n)
+    if f == 0:
+        band[:] = 0.0
+        return
+    w = torch.linspace(0.0, 1.0, f, dtype=band.dtype, device=band.device)
+    frozen = n - f
+    if axis == 1:
+        w = w[None, :]
+        band[:, :frozen] = torch.minimum(
+            band[:, :frozen], torch.zeros(frozen, dtype=band.dtype, device=band.device)
+        )
+        band[:, frozen:] = torch.minimum(band[:, frozen:], w)
+    else:
+        w = w[:, None]
+        band[:frozen, :] = torch.minimum(
+            band[:frozen, :], torch.zeros((frozen, 1), dtype=band.dtype, device=band.device)
+        )
+        band[frozen:, :] = torch.minimum(band[frozen:, :], w)
+
+
+def make_fade_mask(tile_h, tile_w, ol_h, ol_w, done_top, done_left, fade_h=0, fade_w=0):
+    mask = torch.ones(tile_h, tile_w, dtype=torch.float32)
+    if done_left and ol_w > 0:
+        _fade_band(mask[:, :ol_w], fade_w, 1)
+    if done_top and ol_h > 0:
+        _fade_band(mask[:ol_h, :], fade_h, 0)
+    return mask
+
+
+def bright_match_tile(tile, ref, clamp=0.05):
+    d = (tile - ref).float().reshape(tile.shape[0], tile.shape[1], tile.shape[2], -1)
+    dc = d.median(dim=-1).values.clamp(-clamp, clamp)
+    return tile - dc.to(tile.dtype).view(tile.shape[0], tile.shape[1], tile.shape[2], 1, 1)
+
+
+def _dynamic_fade_closure(sp, fw, fh, tr, tc, tr_s, tc_s, ovh, ovw, done_top, done_left, video_flat, mn=0.0):
+    schedule = sp.get("dynamic_fade", "off")
+    if schedule == "off":
+        return None
+    fmin_w = int(sp.get("dynamic_fade_min", 0)) // 16
+    fmin_h = int(sp.get("dynamic_fade_min", 0)) // 16
+    if fw <= fmin_w and fh <= fmin_h:
+        return None
+    fw_start, fh_start = max(fw, 0), max(fh, 0)
+    fmin_w, fmin_h = min(fmin_w, fw_start), min(fmin_h, fh_start)
+    done_top = done_top and ovh > 0
+    done_left = done_left and ovw > 0
+    s_tok = tr_s * tc_s
+    n_frames = video_flat // s_tok
+
+    def fade_at(p):
+        if schedule == "widening":
+            return fmin_w + (fw_start - fmin_w) * p, fmin_h + (fh_start - fmin_h) * p
+        return fw_start - (fw_start - fmin_w) * p, fh_start - (fh_start - fmin_h) * p
+
+    cache = {}
+
+    def step_fn(sigma, denoise_mask, **kwargs):
+        sigmas = kwargs.get("extra_options", {}).get("sigmas")
+        n_sigmas = int(sigmas.numel()) if sigmas is not None else 0
+        masks = cache.get(n_sigmas)
+        if masks is None:
+            step_count = max(n_sigmas - 1, 1)
+            masks = []
+            for i in range(n_sigmas - 1):
+                p = i / (step_count - 1) if step_count > 1 else 0.0
+                cw, ch = fade_at(p)
+                m = make_fade_mask(tr_s, tc_s, ovh, ovw, done_top, done_left,
+                                   fade_h=round(ch), fade_w=round(cw))
+                m[tr:tr_s, :] = 0.0
+                m[:, tc:tc_s] = 0.0
+                if mn > 0:
+                    m = m + mn * (1.0 - m)
+                masks.append(m)
+            cache[n_sigmas] = masks
+        idx = 0
+        if sigmas is not None:
+            idx = int((sigmas > sigma + 1e-6).sum())
+        m = masks[min(idx, len(masks) - 1)]
+        flat = denoise_mask.clone()
+        flat.reshape(denoise_mask.shape[0], -1)[:, :video_flat] = \
+            m.reshape(1, -1).repeat(denoise_mask.shape[0], n_frames)
+        return flat
+
+    return step_fn
+
+
+def _nested_tensor_parts(samples):
+    if samples is None:
+        return ()
+    parts = getattr(samples, "tensors", None)
+    if parts is not None:
+        return tuple(parts)
+    if hasattr(samples, "unbind"):
+        try:
+            return tuple(samples.unbind())
+        except Exception:
+            return ()
+    return ()
+
+
 def _coerce_bool_flag(value):
     if isinstance(value, str):
         text = value.strip().lower()
@@ -4097,7 +4417,7 @@ def _format_timing_note(shot_timings):
         "total": 0.0,
         "retry_elapsed": 0.0,
         "sample": 0.0,
-        "detail_sample": 0.0,
+        "latent_upscale_sample": 0.0,
         "decode_video": 0.0,
         "decode_audio": 0.0,
         "cleanup": 0.0,
@@ -4108,7 +4428,7 @@ def _format_timing_note(shot_timings):
         totals["total"] += float(shot.get("total", 0.0) or 0.0)
         totals["retry_elapsed"] += float(shot.get("retry_elapsed", 0.0) or 0.0)
         totals["sample"] += float(shot.get("sample", 0.0) or 0.0)
-        totals["detail_sample"] += float(shot.get("detail_sample", 0.0) or 0.0)
+        totals["latent_upscale_sample"] += float(shot.get("latent_upscale_sample", 0.0) or 0.0)
         totals["decode_video"] += float(shot.get("decode_video", 0.0) or 0.0)
         totals["decode_audio"] += float(shot.get("decode_audio", 0.0) or 0.0)
         totals["cleanup"] += float(shot.get("cleanup", 0.0) or 0.0)
@@ -4124,8 +4444,8 @@ def _format_timing_note(shot_timings):
     ]
     if totals["retry_elapsed"]:
         pieces.append(f"retry elapsed {_format_elapsed_seconds(totals['retry_elapsed'])}")
-    if totals["detail_sample"]:
-        pieces.append(f"detail {_format_elapsed_seconds(totals['detail_sample'])}")
+    if totals["latent_upscale_sample"]:
+        pieces.append(f"latent upscale {_format_elapsed_seconds(totals['latent_upscale_sample'])}")
     if totals["retries"]:
         pieces.append(f"retries {totals['retries']}")
     if slowest is not None:
@@ -5847,6 +6167,29 @@ def _evict_all_but(keep_model):
             pass
 
 
+def _evict_for_latent_upscale(model):
+    """Clear the sampler model before loading the auxiliary latent upscaler."""
+    try:
+        unload_clones = getattr(mm, "unload_model_and_clones", None)
+        if callable(unload_clones):
+            try:
+                unload_clones(model, unload_additional_models=False)
+                mm.soft_empty_cache()
+                return
+            except Exception:
+                pass
+        mm.unload_all_models()
+    except Exception:
+        pass
+    try:
+        mm.soft_empty_cache(True)
+    except Exception:
+        try:
+            mm.soft_empty_cache()
+        except Exception:
+            pass
+
+
 
 
 
@@ -6084,6 +6427,12 @@ class H3LongVideos:
                 "decode_tile_size": ("INT", {"default": 0, "min": 0, "max": 1024, "step": 32,
                     "tooltip": "Spatial tile size for the VAE decode (tile_x/tile_y). 0 = ComfyUI default. "
                                "Try 256 on a tight card at 1344x768."}),
+                "latent_upscale_param": ("DUMAS_H3_LATENT_UPSCALE_PARAM", {
+                    "tooltip": "Output of 'Dumas H3 Latent Upscale Params'. When connected, the first-pass "
+                               "latent is upscaled and run through a short refinement pass before decode, "
+                               "using the sampler, scheduler, steps, denoise, megapixel target, and optional "
+                               "spatial batching from that node. "
+                               "Leave unconnected to skip latent upscaling entirely."}),
                 "upscale": (["off", "rtx", "model", "lanczos"], {"default": "off",
                     "tooltip": "Optional post-pass on the finished frames. 'rtx' = NVIDIA RTX Video Super "
                                "Resolution (Tensor Cores -- fastest and best for video; needs the "
@@ -6363,26 +6712,6 @@ class H3LongVideos:
                                "the jacket, 'wardrobe: += sunglasses' adds one. TWO+ PEOPLE: name them -- "
                                "'Maya = grey shorts, red jacket; Jon = navy overalls', then edit one at a "
                                "time: 'wardrobe: Maya -= jacket' leaves Jon untouched."}),
-                "detail_pass": ("BOOLEAN", {"default": False,
-                    "tooltip": "Run a second refinement sampler on each beat BEFORE any upscale. "
-                               "It reuses the same conditioning and keeps the output video-only by "
-                               "preserving the first pass's audio latent. Use it for detail cleanup, not "
-                               "for huge rewrites: too many steps or too much denoise can pull identity or "
-                               "continuity away from the main pass."}),
-                "detail_sampler_name": (comfy.samplers.KSampler.SAMPLERS, {"default": "euler",
-                    "tooltip": "Sampler for the optional refinement pass. Euler is the maintained default "
-                               "direction for this lane."}),
-                "detail_scheduler": (comfy.samplers.KSampler.SCHEDULERS, {"default": "beta",
-                    "tooltip": "Scheduler for the optional refinement pass. Beta is the maintained default "
-                               "direction for the H3 enhancement lane."}),
-                "detail_steps": ("INT", {"default": 8, "min": 1, "max": 200,
-                    "tooltip": "Extra steps for the refinement pass only. Start around 4-8. More is not "
-                               "automatically better; once the pass starts rewriting instead of polishing, "
-                               "identity and continuity can drift."}),
-                "detail_denoise": ("FLOAT", {"default": 0.4, "min": 0.0, "max": 1.0, "step": 0.01,
-                    "tooltip": "How hard the refinement pass is allowed to rewrite the beat latent. Start "
-                               "around 0.20-0.35 for gentle cleanup; 0.4+ is stronger and can noticeably "
-                               "change faces, motion or composition."}),
             },
             # Read-only graph access, for SLA-LoRA detection: a LoRA's filename is
             # the only thing that identifies an SLA build, and the graph is the only
@@ -6407,9 +6736,8 @@ class H3LongVideos:
     def _render(self, model, clip, vae, audio_vae, negative, prompt, w, h, ln, fps, tiled, sa,
                 handoff, decode_tile_frames=0, decode_tile_size=0,
                 refs=None, ref_image_size="match", ref_noise_aug=None, silent=False,
-                detail_pass=False, detail_sampler_name="euler", detail_scheduler="beta",
-                detail_steps=8, detail_denoise=0.4, timing_sink=None):
-        timing = {"sample": 0.0, "detail_sample": 0.0, "decode_video": 0.0, "decode_audio": 0.0, "cleanup": 0.0}
+                latent_upscale_param=None, timing_sink=None):
+        timing = {"sample": 0.0, "latent_upscale_sample": 0.0, "decode_video": 0.0, "decode_audio": 0.0, "cleanup": 0.0}
         positive, latent = _build_shot_conditioning(clip, vae, prompt, w, h, ln, fps, handoff,
                                                     ref_images=refs, ref_image_size=ref_image_size,
                                                     ref_noise_aug=ref_noise_aug,
@@ -6428,43 +6756,213 @@ class H3LongVideos:
             # OOM retry cannot help an OOM raised here -- it just re-runs the whole
             # sampling pass and fails the same way, which on a 362-frame shot is four
             # more minutes for nothing.
-            if _is_oom(e):
-                e._h3_stage = "sampling"
-            raise
+            raise _tag_oom_stage(e, "sampling")
         refined_out = out
-        detail_pass = _coerce_bool_flag(detail_pass)
-        if detail_pass:
-            detail_latent = _latent_with_replaced_samples(latent, out)
+        latent_upscale_param = latent_upscale_param or None
+        latent_upscale_mode = _latent_upscale_mode(latent_upscale_param)
+        if latent_upscale_mode != "off":
             try:
-                detail_start = time.perf_counter()
+                latent_start = time.perf_counter()
+                out_samples = out["samples"]
+                parts = _nested_tensor_parts(out_samples)
+                if not getattr(out_samples, "is_nested", False) or len(parts) < 2:
+                    raise RuntimeError("latent upscale expects a nested AV latent")
+                if latent_upscale_mode == "model" and str(latent_upscale_param.get("device", "cuda")) == "cuda":
+                    _evict_for_latent_upscale(model)
+                upscaled_video, up_h, up_w = _upscale_latent_video(parts[0], latent_upscale_param)
+                full_audio = parts[1]
+                # Drop the first-pass sampling state before we start the refinement
+                # pass; otherwise the 12-step base latent and the upscale latent sit
+                # in memory together and can trigger a retry loop.
+                out["samples"] = comfy.nested_tensor.NestedTensor((upscaled_video, full_audio))
+                del out_samples, parts
+                mm.soft_empty_cache()
+                target_w = int(up_w) * 16
+                target_h = int(up_h) * 16
+                if target_w <= 0 or target_h <= 0:
+                    raise RuntimeError("latent upscale target size must be positive")
+                try:
+                    upscale_cond = _retarget_conditioning_spatial(positive, int(up_h), int(up_w))
+                    upscale_latent = dict(latent) if isinstance(latent, dict) else {}
+                except Exception:
+                    upscale_cond, upscale_latent = _build_shot_conditioning(
+                        clip, vae, prompt, target_w, target_h, ln, fps, handoff,
+                        ref_images=refs, ref_image_size=ref_image_size,
+                        ref_noise_aug=ref_noise_aug, audio_vae=audio_vae, silent=silent)
+                upscale_latent["samples"] = comfy.nested_tensor.NestedTensor((upscaled_video, full_audio))
+                del positive, latent
+                refine_steps = int(latent_upscale_param.get("steps", 2) or 2)
+                refine_sampler = latent_upscale_param.get("sampler_name", sn)
+                refine_scheduler = latent_upscale_param.get("scheduler", sch)
+                refine_denoise_value = latent_upscale_param.get("denoise", latent_upscale_param.get("refine_denoise", 0.2))
+                refine_denoise = 0.2 if refine_denoise_value is None else float(refine_denoise_value)
+                tile_size_mode = str(latent_upscale_param.get("tile_size_mode", "specific_size"))
+                tile_w_px = int(latent_upscale_param.get("tile_width", 512) or 512)
+                tile_h_px = int(latent_upscale_param.get("tile_height", 512) or 512)
+                overlap_px = max(0, int(_param_value(latent_upscale_param, "overlap", 64)))
+                fade_w_px = max(0, int(_param_value(latent_upscale_param, "fade_width", 32)))
+                fade_h_px = max(0, int(_param_value(latent_upscale_param, "fade_height", 32)))
+                overlap_mode = str(latent_upscale_param.get("overlap_mode", "earlier"))
+                overlap_blend = str(latent_upscale_param.get("overlap_blend", "linear"))
+                grid_rows = max(1, int(_param_value(latent_upscale_param, "grid_rows", 2)))
+                grid_cols = max(1, int(_param_value(latent_upscale_param, "grid_cols", 2)))
+                spatial_w_overlap_px = max(0, int(_param_value(latent_upscale_param, "spatial_w_overlap", overlap_px)))
+                spatial_h_overlap_px = max(0, int(_param_value(latent_upscale_param, "spatial_h_overlap", overlap_px)))
+                min_tile_size_px = max(0, int(_param_value(latent_upscale_param, "min_tile_size", 256)))
+                masked_area_noise = float(_param_value(latent_upscale_param, "masked_area_noise", 0.0))
+                brightness_match = bool(latent_upscale_param.get("brightness_match", False))
+                dynamic_fade = str(latent_upscale_param.get("dynamic_fade", "off"))
+                dynamic_fade_min_px = max(0, int(_param_value(latent_upscale_param, "dynamic_fade_min", 32)))
+                if tile_size_mode == "rows_cols":
+                    tile_w_px, spatial_w_overlap_px = _solve_equal_tiles(target_w, grid_cols, spatial_w_overlap_px, 16)
+                    tile_h_px, spatial_h_overlap_px = _solve_equal_tiles(target_h, grid_rows, spatial_h_overlap_px, 16)
+                    if tile_w_px < min_tile_size_px or tile_h_px < min_tile_size_px:
+                        raise ValueError(
+                            f"rows_cols mode: solved tile size is {tile_h_px}x{tile_w_px}px "
+                            f"(grid {grid_rows}x{grid_cols} over {target_h}x{target_w}px), "
+                            f"which is smaller than min_tile_size ({min_tile_size_px}px). "
+                            f"Reduce grid_rows/grid_cols, or lower min_tile_size to at most "
+                            f"{min(tile_w_px, tile_h_px)}px."
+                        )
+                    fade_w_px = min(fade_w_px, spatial_w_overlap_px)
+                    fade_h_px = min(fade_h_px, spatial_h_overlap_px)
+                else:
+                    for name, value in (
+                        ("tile_width", tile_w_px),
+                        ("tile_height", tile_h_px),
+                        ("overlap", overlap_px),
+                        ("fade_width", fade_w_px),
+                        ("fade_height", fade_h_px),
+                        ("min_tile_size", min_tile_size_px),
+                    ):
+                        if value % 32 != 0:
+                            raise ValueError(f"'{name}' must be a multiple of 32 pixels; got {value}.")
+                    if overlap_px >= tile_w_px:
+                        raise ValueError("overlap must be smaller than tile_width")
+                    if overlap_px >= tile_h_px:
+                        raise ValueError("overlap must be smaller than tile_height")
+                    if fade_w_px > spatial_w_overlap_px:
+                        raise ValueError("fade_width must not exceed spatial_w_overlap")
+                    if fade_h_px > spatial_h_overlap_px:
+                        raise ValueError("fade_height must not exceed spatial_h_overlap")
+                    if min_tile_size_px > tile_w_px or min_tile_size_px > tile_h_px:
+                        raise ValueError("min_tile_size must not exceed the tile size")
+                tile_tw = max(1, tile_w_px // 16)
+                tile_th = max(1, tile_h_px // 16)
+                ol_tw = max(0, min(tile_tw - 1, spatial_w_overlap_px // 16))
+                ol_th = max(0, min(tile_th - 1, spatial_h_overlap_px // 16))
+                fw_tw = max(0, min(ol_tw, fade_w_px // 16))
+                fw_th = max(0, min(ol_th, fade_h_px // 16))
+                min_tile_tw = max(0, min_tile_size_px // 16)
+                rows, cols, trows, tcols, row_ovl, col_ovl = compute_spatial_grid(
+                    int(up_h), int(up_w), tile_th, tile_tw, ol_th, ol_tw, min_tile_tw, min_tile_tw
+                )
+                logging.info(
+                    "H3 latent refine: %s spatial sampler tiles, target=%sx%s tile_mode=%s tile=%sx%s overlap=%sx%s",
+                    len(rows) * len(cols), target_w, target_h, tile_size_mode, tile_w_px, tile_h_px,
+                    spatial_w_overlap_px, spatial_h_overlap_px,
+                )
+                if len(rows) == 1 and len(cols) == 1:
                     (refined_out,) = nodes.common_ksampler(
-                    model, seed, int(detail_steps), cfg, detail_sampler_name, detail_scheduler,
-                    positive, negative, detail_latent, denoise=float(detail_denoise))
-                timing["detail_sample"] += time.perf_counter() - detail_start
+                        model, seed, refine_steps, cfg, refine_sampler, refine_scheduler, upscale_cond, negative, upscale_latent,
+                        denoise=refine_denoise)
+                else:
+                    refined_video = upscaled_video.clone()
+                    for row_index, r0 in enumerate(rows):
+                        tr = trows[row_index]
+                        ovh = row_ovl[row_index]
+                        for col_index, c0 in enumerate(cols):
+                            tc = tcols[col_index]
+                            ovw = col_ovl[col_index]
+                            tile_cond = _crop_conditioning_to_tile(
+                                upscale_cond, int(up_h), int(up_w), r0, c0, tr, tc
+                            )
+                            tile_latent = dict(upscale_latent) if isinstance(upscale_latent, dict) else {}
+                            tile_video = upscaled_video[:, :, :, r0:r0 + tr, c0:c0 + tc].contiguous()
+                            tr_s = tr + (tr % 2)
+                            tc_s = tc + (tc % 2)
+                            tile = torch.zeros((1, tile_video.shape[1], tile_video.shape[2], tr_s, tc_s),
+                                               device=tile_video.device, dtype=tile_video.dtype)
+                            tile[:, :, :, :tr, :tc] = tile_video
+                            if col_index > 0 and ovw > 0:
+                                tile[:, :, :, :tr, :ovw] = refined_video[:, :, :, r0:r0 + tr, c0:c0 + ovw]
+                            if row_index > 0 and ovh > 0:
+                                tile[:, :, :, :ovh, :tc] = refined_video[:, :, :, r0:r0 + ovh, c0:c0 + tc]
+                            mask = make_fade_mask(tr_s, tc_s, ovh, ovw, row_index > 0, col_index > 0,
+                                                  fade_h=fw_th, fade_w=fw_tw)
+                            mask[tr:tr_s, :] = 0.0
+                            mask[:, tc:tc_s] = 0.0
+                            mv = (mask + masked_area_noise * (1.0 - mask))[None, None, None].to(tile.dtype)
+                            ma = torch.zeros((1, 32, 2, full_audio.shape[-1]), device=full_audio.device, dtype=full_audio.dtype)
+                            tile_latent["samples"] = comfy.nested_tensor.NestedTensor((tile, full_audio))
+                            tile_latent["noise_mask"] = comfy.nested_tensor.NestedTensor((mv, ma))
+                            dynamic = _dynamic_fade_closure(
+                                latent_upscale_param, fw_tw, fw_th, tr, tc, tr_s, tc_s, ovh, ovw,
+                                row_index > 0, col_index > 0, math.prod(tile.shape[1:]), mn=masked_area_noise
+                            )
+                            if dynamic is not None:
+                                model.set_model_denoise_mask_function(dynamic)
+                            try:
+                                tile_out, = nodes.common_ksampler(
+                                    model, seed, refine_steps, cfg, refine_sampler, refine_scheduler, tile_cond, negative, tile_latent,
+                                    denoise=refine_denoise)
+                            finally:
+                                if dynamic is not None:
+                                    model.model_options.pop("denoise_mask_function", None)
+                            tile_out = _video_only_refined_latent(
+                                {"samples": comfy.nested_tensor.NestedTensor((tile_video, full_audio))},
+                                tile_out)
+                            tile_video_out = tile_out["samples"].tensors[0]
+                            if brightness_match:
+                                tile_video_out = bright_match_tile(
+                                    tile_video_out,
+                                    upscaled_video[:, :, :, r0:r0 + tr, c0:c0 + tc]
+                                )
+                            region = refined_video[:, :, :, r0:r0 + tr, c0:c0 + tc]
+                            base_region = region.clone()
+                            region.copy_(tile_video_out)
+                            if col_index > 0 and ol_tw > 0:
+                                t = torch.linspace(0.0, 1.0, ol_tw, device=region.device, dtype=region.dtype)
+                                w = _latent_spatial_blend_weights(t, overlap_mode, overlap_blend)
+                                if fw_tw > 0:
+                                    w = w.clone()
+                                    w[:fw_tw] = 0.0
+                                region[:, :, :, :, :ol_tw] = (
+                                    base_region[:, :, :, :, :ol_tw] * (1.0 - w[None, None, None, None, :]) +
+                                    tile_video_out[:, :, :, :, :ol_tw] * w[None, None, None, None, :]
+                                )
+                            if row_index > 0 and ol_th > 0:
+                                t = torch.linspace(0.0, 1.0, ol_th, device=region.device, dtype=region.dtype)
+                                w = _latent_spatial_blend_weights(t, overlap_mode, overlap_blend)
+                                if fw_th > 0:
+                                    w = w.clone()
+                                    w[:fw_th] = 0.0
+                                region[:, :, :, :ol_th, :] = (
+                                    base_region[:, :, :, :ol_th, :] * (1.0 - w[None, None, None, :, None]) +
+                                    tile_video_out[:, :, :, :ol_th, :] * w[None, None, None, :, None]
+                                )
+                    refined_out = {"samples": comfy.nested_tensor.NestedTensor((refined_video, full_audio))}
+                timing["latent_upscale_sample"] += time.perf_counter() - latent_start
+                refined_out = _video_only_refined_latent(upscale_latent, refined_out)
+                del upscale_latent, upscaled_video, full_audio
+                mm.soft_empty_cache()
             except Exception as e:
-                if _is_oom(e):
-                    e._h3_stage = "sampling"
-                raise
-            refined_out = _video_only_refined_latent(out, refined_out)
-            del detail_latent
+                raise _tag_oom_stage(e, "latent_upscale")
         # Keep a CPU copy of the sampled latent BEFORE decoding, for the `latent`
         # output. Latents are ~1000x smaller than the frames they decode to (a
         # 1344x768 124f shot is ~1.5MB against ~1.5GB), so carrying one per shot for
         # the whole chain is free. Detached and moved off the card immediately, for
         # the same reason the decoded frames are.
-        decode_video_start = time.perf_counter()
-        shot_latent = _copy_sample_latent(refined_out)
         decode_audio_start = time.perf_counter()
         audio = _decode_audio(audio_vae, out)
         timing["decode_audio"] += time.perf_counter() - decode_audio_start
-        # Audio is much smaller than the video decode. Drop the first-pass
-        # conditioning before the VAE work so the optional detail pass does not
-        # keep both sampled latents resident across the heaviest allocation.
-        del out, positive, latent
+        decode_video_start = time.perf_counter()
+        shot_latent = _copy_sample_latent(refined_out)
         video = _decode_video(vae, refined_out, tiled, free_first=model,
                               tile_t=decode_tile_frames, tile_xy=decode_tile_size)
         timing["decode_video"] += time.perf_counter() - decode_video_start
         cleanup_start = time.perf_counter()
+        del out
         del refined_out
         _deep_cleanup()
         timing["cleanup"] += time.perf_counter() - cleanup_start
@@ -6500,8 +6998,7 @@ class H3LongVideos:
             ref_5=None, ref_6=None, ref_7=None, ref_8=None,
             ref_9=None,
             ref_mode="auto ref2v", ref_image_size="match", ref_noise_aug=0.95,
-            detail_pass=False, detail_sampler_name="euler", detail_scheduler="beta",
-            detail_steps=8, detail_denoise=0.4,
+            latent_upscale_param=None,
             graph=None, node_id=None):
 
         # FIRST: detect a checkpoint swap since the previous execution and hard-flush.
@@ -6565,12 +7062,42 @@ class H3LongVideos:
         ms_note = ""
         if apply_model_sampling:
             model, ms_note = apply_h3_model_sampling(model, shift_video, shift_audio)
-        detail_note = ""
-        if detail_pass:
-            detail_note = (f" detail pass: {int(detail_steps)} step(s) via "
-                           f"{detail_sampler_name}/{detail_scheduler} at denoise "
-                           f"{float(detail_denoise):.2f}; video-only refinement keeps "
-                           f"audio from the first pass")
+        latent_upscale_note = ""
+        latent_upscale_mode = _latent_upscale_mode(latent_upscale_param)
+        if latent_upscale_mode != "off":
+            target_w, target_h = _latent_upscale_target_size(w, h, latent_upscale_param)
+            mode = latent_upscale_mode
+            detail = f" via {mode}"
+            if mode == "model":
+                detail += f"/{latent_upscale_param.get('model_name', 'none')}"
+            else:
+                detail += f"/{latent_upscale_param.get('method', 'bilinear')}"
+            denoise_value = latent_upscale_param.get("denoise", latent_upscale_param.get("refine_denoise", 0.2))
+            denoise = 0.2 if denoise_value is None else float(denoise_value)
+            refine_sampler = latent_upscale_param.get("sampler_name", "euler_ancestral")
+            refine_scheduler = latent_upscale_param.get("scheduler", "simple")
+            batch_note = ""
+            tile_size_mode = str(latent_upscale_param.get("tile_size_mode", "specific_size"))
+            tile_w_px = int(latent_upscale_param.get("tile_width", 512) or 512)
+            tile_h_px = int(latent_upscale_param.get("tile_height", 512) or 512)
+            overlap_px = max(0, int(_param_value(latent_upscale_param, "overlap", 64)))
+            overlap_blend = str(latent_upscale_param.get("overlap_blend", "linear"))
+            grid_rows = max(1, int(_param_value(latent_upscale_param, "grid_rows", 2)))
+            grid_cols = max(1, int(_param_value(latent_upscale_param, "grid_cols", 2)))
+            if tile_size_mode == "rows_cols":
+                batch_note = f"; spatial batches {grid_rows}x{grid_cols} rows_cols over {target_w}x{target_h}px"
+            elif tile_w_px > 0 and tile_h_px > 0 and (tile_w_px < target_w or tile_h_px < target_h):
+                spatial_w_overlap_px = max(0, int(_param_value(latent_upscale_param, "spatial_w_overlap", overlap_px)))
+                spatial_h_overlap_px = max(0, int(_param_value(latent_upscale_param, "spatial_h_overlap", overlap_px)))
+                batch_note = (
+                    f"; spatial batches {tile_w_px}x{tile_h_px}px "
+                    f"overlap {spatial_w_overlap_px}x{spatial_h_overlap_px}px {overlap_blend}"
+                )
+            latent_upscale_note = (
+                f" latent upscale: target {target_w}x{target_h}px{detail}; "
+                f"{int(latent_upscale_param.get('steps', 2) or 2)}-step refinement "
+                f"{refine_sampler}/{refine_scheduler} denoise {denoise:.2f}{batch_note}"
+            )
 
         paras = split_paragraphs(prompt, "##")
         if anchor_override.strip():
@@ -6881,6 +7408,7 @@ class H3LongVideos:
                     + (" ANCHOR: " + "; ".join(anchor_hazards) + "."
                        if anchor_hazards else "")
                     + (f"{anatomy_note}." if anatomy_note else "")
+                    + (f"{latent_upscale_note}." if latent_upscale_note else "")
                     + (f"{plan_audio}." if plan_audio else "")
                     + (" EXPOSURE -- " + "; ".join(wardrobe_notes) + "."
                        if wardrobe_notes else "")
@@ -7029,13 +7557,18 @@ class H3LongVideos:
                             model, clip, vae, audio_vae, negative, gen_prompt, w, h, ln_i, fps,
                             tiled, sa, shot_handoff, decode_tile_frames, decode_tile_size,
                             shot_refs, ref_image_size, shot_aug, shot_silent,
-                            detail_pass, detail_sampler_name, detail_scheduler,
-                            detail_steps, detail_denoise, timing_sink=shot_timing)
+                            latent_upscale_param=latent_upscale_param, timing_sink=shot_timing)
                         break
                     except (torch.cuda.OutOfMemoryError, RuntimeError) as e:
                         shot_retry_elapsed += time.perf_counter() - attempt_start
                         if not _is_oom(e):
                             raise
+                        if getattr(e, "_h3_stage", "") == "latent_upscale":
+                            raise RuntimeError(
+                                f"H3 Long Videos: shot {i + 1} of {len(gens)} ran out of VRAM "
+                                f"during latent upscale. The latent-upscale stage is too large "
+                                f"for this card at {w}x{h} with the current spatial settings."
+                            ) from e
                         mm.soft_empty_cache(True)
                         if not tiled:
                             tiled = True; backoff.append("tiled decode")
@@ -7052,10 +7585,16 @@ class H3LongVideos:
                         model, clip, vae, audio_vae, negative, gen_prompt, w, h, ln_i, fps,
                         tiled, sa, shot_handoff, decode_tile_frames, decode_tile_size,
                         shot_refs, ref_image_size, shot_aug, shot_silent,
-                        detail_pass, detail_sampler_name, detail_scheduler,
-                        detail_steps, detail_denoise, timing_sink=shot_timing)
+                        latent_upscale_param=latent_upscale_param, timing_sink=shot_timing)
                 except (torch.cuda.OutOfMemoryError, RuntimeError) as e:
                     shot_retry_elapsed += time.perf_counter() - attempt_start
+                    stage = getattr(e, "_h3_stage", "")
+                    if _is_oom(e) and stage == "latent_upscale":
+                        raise RuntimeError(
+                            f"H3 Long Videos: shot {i + 1} of {len(gens)} ran out of VRAM "
+                            f"during latent upscale. The latent-upscale stage is too large "
+                            f"for this card at {w}x{h} with the current spatial settings."
+                        ) from e
                     if _is_oom(e) and getattr(e, "_h3_stage", "") == "sampling":
                         # Retrying with tiles would re-run the whole sampling pass and
                         # fail identically. Fail now, and say what actually shrinks it.
@@ -7072,8 +7611,7 @@ class H3LongVideos:
                         model, clip, vae, audio_vae, negative, gen_prompt, w, h, ln_i, fps,
                         tiled, sa, shot_handoff, decode_tile_frames, decode_tile_size,
                         shot_refs, ref_image_size, shot_aug, shot_silent,
-                        detail_pass, detail_sampler_name, detail_scheduler,
-                        detail_steps, detail_denoise, timing_sink=shot_timing)
+                        latent_upscale_param=latent_upscale_param, timing_sink=shot_timing)
                     shot_retry_elapsed += time.perf_counter() - attempt_start
 
             shot_total = time.perf_counter() - shot_total_start
@@ -7343,7 +7881,7 @@ class H3LongVideos:
                    f"shot before them ended on dialogue." if mouth_settled else "")
                 + (f"{anatomy_note}." if anatomy_note else "")
                 + (f"{latent_note}." if latent_note else "")
-                + (f"{detail_note}." if detail_note else "")
+                + (f"{latent_upscale_note}." if latent_upscale_note else "")
                 + (f" SLA LoRA '{os.path.basename(str(sla_name))}' paired with sparse attention."
                    if sla_name and sparse_on else "")
                 + (f" {beats_note}." if beats_note else "")

dumas_h3_shot_length.py

@@ -39,10 +39,11 @@ class H3ShotLength:
     def INPUT_TYPES(cls):
         return {
             "required": {
-                "shot_seconds": ("FLOAT", {"default": 5.0, "min": 0.2, "max": 15.1, "step": 0.5,
+                "shot_seconds": ("FLOAT", {"default": 3.0, "min": 0.2, "max": 15.1, "step": 0.5,
                     "tooltip": "Length of each shot. Feeds the sampler's shot_seconds AND (as frames) "
-                               "the preview override. Max ~15s (362 frames)."}),
-                "fps": ("INT", {"default": 24, "min": 1, "max": 60}),
+                               "the preview override. Default 3s matches the common one-beat H3 test shot. Max ~15s (362 frames)."}),
+                "fps": ("INT", {"default": 24, "min": 1, "max": 60,
+                    "tooltip": "Frame rate used for the seconds->frames conversion. H3 itself renders at 24fps, so 24 is the realistic default."}),
             },
             "optional": {
                 "cap_to_h3_max": ("BOOLEAN", {"default": True,

dumas_image_nodes.py

@@ -27,6 +27,19 @@ _H3_PLAN_IMAGE_BINDINGS_CAP = 128
 _H3_PLAN_IMAGE_SLOTS = 9
 _FOLDER_IMAGE_EXTS = (".png", ".jpg", ".jpeg", ".webp", ".bmp", ".gif", ".tiff", ".tif")
 _ANCHOR_STYLE_H3_NOTE = ""
+_H3_PROMPT_REF_SLOTS = 9
+_H3_PROMPT_MAX_CHARS = 7000
+_PICTURE_TAG_RE = re.compile(r"<\s*picture[\s_\-]*(\d+)\s*>", re.I)
+_REF_TAG_RE = re.compile(r"<\s*ref[\s_\-]*(\d+)\s*>", re.I)
+_ANATOMY_GUARD_TEXT = (
+    "Each person has one head, two arms, two hands with five fingers on each hand, "
+    "and two legs with two feet. Limbs stay attached to the correct body and move "
+    "only with the person they belong to."
+)
+_SUBJECT_COUNT_FALLBACK_TEXT = (
+    "Only include the people explicitly described in the action. Do not invent "
+    "extra people, doubles, duplicate bodies, background performers, or extra faces."
+)
 _ANCHOR_STYLE_PRESETS = OrderedDict(
     [
         (
@@ -346,6 +359,47 @@ _ANCHOR_STYLE_PRESETS = OrderedDict(
         ),
     ]
 )
+_SOUNDSCAPE_PRESETS = OrderedDict(
+    [
+        (
+            "quiet interior",
+            "quiet indoor room tone, faint ventilation and distant household ambience",
+        ),
+        (
+            "rainy street",
+            "steady rain, wet pavement, distant traffic hum",
+        ),
+        (
+            "cafe",
+            "low room tone, faint glassware, cutlery, and muted conversation",
+        ),
+        (
+            "city night",
+            "distant traffic hum, occasional horn, night air",
+        ),
+        (
+            "forest",
+            "wind in leaves, distant birds, soft natural ambience",
+        ),
+        (
+            "industrial",
+            "large interior reverb, distant metal ticks, low machine hum",
+        ),
+        (
+            "silent",
+            "no dialogue, no vocals, only the natural ambient bed of the scene",
+        ),
+        ("custom", ""),
+    ]
+)
+
+
+def _soundscape_options():
+    return list(_SOUNDSCAPE_PRESETS.keys())
+
+
+def _soundscape_description(soundscape_name):
+    return _SOUNDSCAPE_PRESETS.get(soundscape_name, "")
 _LOAD_IMAGES_FOLDER_DEFAULT_STATE = {
     "version": 1,
     "folder": "",
@@ -920,6 +974,248 @@ def normalize_reference(value, picture_id=None, allow_image_fallback=True):
     )
 
 
+def _reference_text(value):
+    return " ".join(str(value or "").split()).strip()
+
+
+def _reference_sentence(value):
+    text = _reference_text(value)
+    if text and text[-1] not in ".!?":
+        text += "."
+    return text
+
+
+def _reference_name_keys(ref):
+    names = []
+    for key in ("name", "id"):
+        value = _reference_text(ref.get(key))
+        if value:
+            names.append(value)
+    for alias in ref.get("aliases") or []:
+        value = _reference_text(alias)
+        if value:
+            names.append(value)
+    seen = set()
+    out = []
+    for name in names:
+        key = name.lower()
+        if key in seen:
+            continue
+        seen.add(key)
+        out.append(name)
+    return out
+
+
+def _reference_image(ref):
+    if not isinstance(ref, dict):
+        return None
+    return ref.get("image")
+
+
+def _normalize_prompt_refs(raw_refs):
+    refs = []
+    for slot_number, raw in enumerate(raw_refs or (), 1):
+        if raw is None:
+            refs.append(None)
+            continue
+        try:
+            ref = normalize_reference(raw, picture_id=slot_number, allow_image_fallback=False)
+        except Exception:
+            refs.append(None)
+            continue
+        if _reference_image(ref) is None:
+            refs.append(None)
+        else:
+            refs.append(ref)
+    return refs
+
+
+def _explicit_reference_tags(text):
+    return sorted(
+        {
+            int(match.group(1))
+            for pattern in (_PICTURE_TAG_RE, _REF_TAG_RE)
+            for match in pattern.finditer(text or "")
+        }
+    )
+
+
+def _name_matches_reference(text, ref):
+    haystack = str(text or "")
+    for name in _reference_name_keys(ref):
+        if re.search(r"\b" + re.escape(name) + r"\b", haystack, re.I):
+            return True
+    return False
+
+
+def _selected_prompt_refs(action_prompt, refs):
+    selected = []
+    seen_slots = set()
+    for slot_number in _explicit_reference_tags(action_prompt):
+        if not (1 <= slot_number <= len(refs)):
+            continue
+        ref = refs[slot_number - 1]
+        if ref is None:
+            continue
+        selected.append((slot_number, ref))
+        seen_slots.add(slot_number)
+    for slot_number, ref in enumerate(refs, 1):
+        if slot_number in seen_slots or ref is None:
+            continue
+        if _name_matches_reference(action_prompt, ref):
+            selected.append((slot_number, ref))
+            seen_slots.add(slot_number)
+    return selected
+
+
+def _replace_reference_tags(text, picture_map):
+    def repl(match):
+        original = int(match.group(1))
+        compacted = picture_map.get(original)
+        if compacted is None:
+            return ""
+        return f"<Picture {compacted}>"
+
+    rewritten = _PICTURE_TAG_RE.sub(repl, str(text or ""))
+    rewritten = _REF_TAG_RE.sub(repl, rewritten)
+    return re.sub(r"[ \t]{2,}", " ", rewritten).strip()
+
+
+def _reference_fact_sentence(ref, label):
+    if ref.get("kind") != "character":
+        return ""
+    facts = dict(ref.get("facts") or {})
+    bits = []
+    aliases = [_reference_text(alias) for alias in (ref.get("aliases") or []) if _reference_text(alias)]
+    if aliases:
+        bits.append(f"also known as {aliases[0]}")
+    for key in ("gender", "nationality", "occupation"):
+        value = _reference_text(facts.get(key))
+        if value:
+            bits.append(value if key != "occupation" else f"works as {value}")
+    age = _parse_positive_int(facts.get("age"))
+    if age is not None:
+        bits.append(f"{age} years old")
+    feet = _reference_text(facts.get("height_feet"))
+    inches = _reference_text(facts.get("height_inches"))
+    if feet and inches:
+        bits.append(f"{feet} foot {inches} tall")
+    elif feet:
+        bits.append(f"{feet} foot tall")
+    accent = _reference_text(facts.get("accent"))
+    if accent:
+        bits.append(f"speaks with a {accent} accent")
+    if not bits:
+        return ""
+    return f"Character facts for {label}: " + ", ".join(bits) + "."
+
+
+def _reference_context(ref, compact_picture_number):
+    label_name = _reference_text(ref.get("name")) or _reference_text(ref.get("id")) or "this reference"
+    label = f"<Picture {compact_picture_number}> {label_name}"
+    parts = [_reference_sentence(_reference_summary(ref.get("kind"), label_name, compact_picture_number))]
+    description = _reference_sentence(ref.get("description"))
+    wardrobe = _reference_sentence(ref.get("wardrobe"))
+    general = _reference_sentence(ref.get("general"))
+    facts = _reference_fact_sentence(ref, label)
+    if ref.get("kind") == "location":
+        if description:
+            parts.append(f"Location context for {label}: {description}")
+        if general:
+            parts.append(f"Location notes for {label}: {general}")
+    else:
+        if facts:
+            parts.append(facts)
+        if description:
+            parts.append(f"Persistent appearance for {label}: {description}")
+        if wardrobe:
+            parts.append(f"Persistent wardrobe/style for {label}: {wardrobe}")
+        if general:
+            parts.append(f"Character notes for {label}: {general}")
+    return " ".join(part for part in parts if part).strip()
+
+
+def _subject_count_guard_text(selected_refs):
+    character_labels = []
+    seen_characters = set()
+    for picture_number, (_slot, ref) in enumerate(selected_refs or (), 1):
+        if ref.get("kind") != "character":
+            continue
+        name = _reference_text(ref.get("name")) or _reference_text(ref.get("id"))
+        key = (_reference_text(ref.get("id")) or name or f"picture-{picture_number}").lower()
+        if key in seen_characters:
+            continue
+        seen_characters.add(key)
+        label = f"<Picture {picture_number}>"
+        if name:
+            label = f"{label} {name}"
+        character_labels.append(label)
+    if not character_labels:
+        return _SUBJECT_COUNT_FALLBACK_TEXT
+    if len(character_labels) == 1:
+        return (
+            f"The shot contains exactly one named character: {character_labels[0]}. "
+            "Do not create any extra people, doubles, duplicate bodies, background "
+            "performers, or extra faces."
+        )
+    return (
+        f"The shot contains exactly {len(character_labels)} named characters: "
+        + ", ".join(character_labels)
+        + ". Do not create any extra people, doubles, duplicate bodies, background "
+          "performers, or extra faces."
+    )
+
+
+def _append_prompt_section(parts, label, text):
+    clean = _reference_text(text)
+    if clean:
+        parts.append(f"{label}: {clean}")
+
+
+def curate_h3_prompt(
+    action_prompt,
+    anchor="",
+    soundscape="",
+    refs=(),
+    anatomy_guard="auto",
+    subject_count_guard="auto",
+):
+    normalized_refs = _normalize_prompt_refs(refs)
+    selected = _selected_prompt_refs(action_prompt, normalized_refs)
+    picture_map = {slot_number: index for index, (slot_number, _ref) in enumerate(selected, 1)}
+    action = _replace_reference_tags(action_prompt, picture_map)
+
+    prompt_parts = []
+    _append_prompt_section(prompt_parts, "Scene anchor", anchor)
+    if selected:
+        contexts = [_reference_context(ref, picture_number) for picture_number, (_slot, ref) in enumerate(selected, 1)]
+        _append_prompt_section(prompt_parts, "Reference context", " ".join(contexts))
+    _append_prompt_section(prompt_parts, "Action", action)
+    if anatomy_guard == "on" or (anatomy_guard == "auto" and any(ref.get("kind") == "character" for _slot, ref in selected)):
+        _append_prompt_section(prompt_parts, "Anatomy guard", _ANATOMY_GUARD_TEXT)
+    if subject_count_guard == "on" or (
+        subject_count_guard == "auto" and any(ref.get("kind") == "character" for _slot, ref in selected)
+    ):
+        _append_prompt_section(prompt_parts, "Subject count guard", _subject_count_guard_text(selected))
+    _append_prompt_section(prompt_parts, "overall_soundscape", soundscape)
+
+    prompt = "\n\n".join(prompt_parts).strip()
+    if len(prompt) > _H3_PROMPT_MAX_CHARS:
+        prompt = prompt[: _H3_PROMPT_MAX_CHARS - 3].rstrip() + "..."
+    images = [_reference_image(ref) for _slot, ref in selected]
+    images.extend([None] * (_H3_PROMPT_REF_SLOTS - len(images)))
+    debug = (
+        f"Selected {len(selected)} reference(s): "
+        + ", ".join(
+            f"input {slot}-><Picture {index}> {_reference_text(ref.get('name')) or ref.get('id')}"
+            for index, (slot, ref) in enumerate(selected, 1)
+        )
+        if selected
+        else "Selected 0 references."
+    )
+    return (prompt, *images[:_H3_PROMPT_REF_SLOTS], len(selected), debug)
+
+
 def _parse_positive_int(value):
     text = str(value or "").strip()
     if not text:
@@ -1042,6 +1338,65 @@ def _build_character_wardrobe_text(wardrobe, character_id, name, alias):
     return text
 
 
+def _label_for_location(name, location_id):
+    return _normalize_free_text(name) or _normalize_free_text(location_id) or "the location"
+
+
+def _build_location_helper_text(
+    primary_picture_id,
+    secondary_picture_id,
+    location_id,
+    name,
+    alias,
+    description,
+    general,
+):
+    primary_picture = int(primary_picture_id)
+    secondary_picture = int(secondary_picture_id)
+    location_name = _normalize_free_text(name)
+    location_id = _normalize_free_text(location_id)
+    alias = _normalize_free_text(alias)
+    description = _ensure_sentence(description)
+    general = _ensure_sentence(general)
+    location_label = _label_for_location(location_name, location_id)
+
+    if location_name:
+        first_line = (
+            f"<Picture {primary_picture}> and <Picture {secondary_picture}> reference "
+            f"the same location called {location_name}."
+        )
+    elif location_id:
+        first_line = (
+            f"<Picture {primary_picture}> and <Picture {secondary_picture}> reference "
+            f'the same location with ID "{location_id}".'
+        )
+    else:
+        first_line = (
+            f"<Picture {primary_picture}> and <Picture {secondary_picture}> reference "
+            "the same location."
+        )
+
+    lines = [
+        first_line,
+        f"<Picture {primary_picture}> is the primary wide/environment reference for {location_label}.",
+        f"<Picture {secondary_picture}> is the secondary detail/angle reference for {location_label}.",
+    ]
+
+    facts = []
+    if alias:
+        facts.append(f"is also known as {alias}")
+    if description:
+        facts.append(description)
+
+    if facts:
+        lines.append(f"{location_label} {', '.join(facts)}")
+
+    if general:
+        lines.append(general)
+
+    return "\n".join(lines)
+
+
 class DumasImageCompareNode:
     DESCRIPTION = (
         "Dumas Image Compare shows the difference between two images directly on "
@@ -1604,6 +1959,322 @@ class DumasH3PlanExtractSceneImagesNode:
         return (passthrough_plan, *images, _connected_image_count(images))
 
 
+class DumasCharacterHelperNode:
+    DESCRIPTION = (
+        "Build a general character reference prompt and wardrobe sheet from two "
+        "IMAGE sockets plus simple identity fields, while passing both images "
+        "through unchanged."
+    )
+    RETURN_TYPES = ("IMAGE", "IMAGE", "STRING", "STRING", _REFERENCE_TYPE, _REFERENCE_TYPE)
+    RETURN_NAMES = ("image1", "image2", "reference_prompt", "wardrobe", "reference1", "reference2")
+    FUNCTION = "build_character_text"
+    CATEGORY = "Dumas/MiniMax"
+
+    @classmethod
+    def INPUT_TYPES(cls):
+        return {
+            "required": {
+                "image1": ("IMAGE", {"tooltip": "Primary image to pass through and describe."}),
+                "image2": ("IMAGE", {"tooltip": "Secondary image to pass through and describe."}),
+                "image1_picture_id": (
+                    ["1", "2", "3", "4", "5", "6", "7", "8", "9"],
+                    {
+                        "default": "1",
+                        "tooltip": "Picture number to mention for image1 in the reference prompt.",
+                    },
+                ),
+                "image2_picture_id": (
+                    ["1", "2", "3", "4", "5", "6", "7", "8", "9"],
+                    {
+                        "default": "2",
+                        "tooltip": "Picture number to mention for image2 in the reference prompt.",
+                    },
+                ),
+                "character_id": (
+                    "STRING",
+                    {
+                        "default": "",
+                        "multiline": False,
+                        "tooltip": "Optional character ID string to include in the output text.",
+                    },
+                ),
+                "name": (
+                    "STRING",
+                    {
+                        "default": "",
+                        "multiline": False,
+                        "tooltip": "Character name used in the main reference sentences.",
+                    },
+                ),
+                "alias": (
+                    "STRING",
+                    {
+                        "default": "",
+                        "multiline": False,
+                        "tooltip": "Optional alternate name, codename, or nickname.",
+                    },
+                ),
+                "gender": (
+                    "STRING",
+                    {
+                        "default": "",
+                        "multiline": False,
+                        "tooltip": "Optional gender field for non-visual character facts.",
+                    },
+                ),
+                "age": (
+                    "STRING",
+                    {
+                        "default": "",
+                        "multiline": False,
+                        "tooltip": "Optional numeric age. Invalid values are omitted.",
+                    },
+                ),
+                "nationality": (
+                    "STRING",
+                    {
+                        "default": "",
+                        "multiline": False,
+                        "tooltip": "Optional nationality, origin, or cultural background.",
+                    },
+                ),
+                "occupation": (
+                    "STRING",
+                    {
+                        "default": "",
+                        "multiline": False,
+                        "tooltip": "Optional job, role, or function that is not visually obvious.",
+                    },
+                ),
+                "height_feet": (
+                    ["", "3", "4", "5", "6", "7", "8"],
+                    {
+                        "default": "",
+                        "tooltip": "Optional feet component for the character's height.",
+                    },
+                ),
+                "height_inches": (
+                    ["", "0", "1", "2", "3", "4", "5", "6", "7", "8", "9", "10", "11"],
+                    {
+                        "default": "",
+                        "tooltip": "Optional inches component for the character's height.",
+                    },
+                ),
+                "accent": (
+                    "STRING",
+                    {
+                        "default": "",
+                        "multiline": False,
+                        "tooltip": "Optional short accent description.",
+                    },
+                ),
+                "general": (
+                    "STRING",
+                    {
+                        "default": "",
+                        "multiline": True,
+                        "tooltip": "Optional non-clothing details appended as the last sentence of the reference prompt.",
+                    },
+                ),
+                "wardrobe": (
+                    "STRING",
+                    {
+                        "default": "",
+                        "multiline": True,
+                        "tooltip": "Optional wardrobe/channel text. Plain clothing lists are auto-wrapped as 'Name = ...' when a name, alias, or character ID is present.",
+                    },
+                ),
+            }
+        }
+
+    def build_character_text(
+        self,
+        image1,
+        image2,
+        image1_picture_id,
+        image2_picture_id,
+        character_id,
+        name,
+        alias,
+        gender,
+        age,
+        nationality,
+        occupation,
+        height_feet,
+        height_inches,
+        accent,
+        general,
+        wardrobe,
+    ):
+        text = _build_character_helper_text(
+            image1_picture_id,
+            image2_picture_id,
+            character_id,
+            name,
+            alias,
+            gender,
+            age,
+            nationality,
+            occupation,
+            height_feet,
+            height_inches,
+            accent,
+            general,
+        )
+        wardrobe_text = _build_character_wardrobe_text(
+            wardrobe,
+            character_id,
+            name,
+            alias,
+        )
+        facts = {
+            "gender": _normalize_free_text(gender),
+            "age": str(_parse_positive_int(age) or ""),
+            "nationality": _normalize_free_text(nationality),
+            "occupation": _normalize_free_text(occupation),
+            "height_feet": str(height_feet or "").strip(),
+            "height_inches": str(height_inches or "").strip(),
+            "accent": _normalize_free_text(accent),
+        }
+        common = {
+            "kind": "character",
+            "explicit_id": character_id,
+            "name": name,
+            "aliases": alias,
+            "description": general,
+            "wardrobe": wardrobe,
+            "general": general,
+            "facts": facts,
+        }
+        reference1 = make_reference(
+            image=image1,
+            summary="Primary full-body character reference.",
+            **common,
+        )
+        reference2 = make_reference(
+            image=image2,
+            summary="Secondary facial character reference.",
+            **common,
+        )
+        return (image1, image2, text, wardrobe_text, reference1, reference2)
+
+
+class DumasLocationHelperNode:
+    DESCRIPTION = (
+        "Build a general location reference prompt from two IMAGE sockets plus "
+        "simple environment fields, while passing both images through unchanged."
+    )
+    RETURN_TYPES = ("IMAGE", "IMAGE", "STRING", _REFERENCE_TYPE, _REFERENCE_TYPE)
+    RETURN_NAMES = ("image1", "image2", "reference_prompt", "reference1", "reference2")
+    FUNCTION = "build_location_text"
+    CATEGORY = "Dumas/MiniMax"
+
+    @classmethod
+    def INPUT_TYPES(cls):
+        return {
+            "required": {
+                "image1": ("IMAGE", {"tooltip": "Primary location image to pass through and describe."}),
+                "image2": ("IMAGE", {"tooltip": "Secondary location image to pass through and describe."}),
+                "image1_picture_id": (
+                    ["1", "2", "3", "4", "5", "6", "7", "8", "9"],
+                    {
+                        "default": "1",
+                        "tooltip": "Picture number to mention for image1 in the reference prompt.",
+                    },
+                ),
+                "image2_picture_id": (
+                    ["1", "2", "3", "4", "5", "6", "7", "8", "9"],
+                    {
+                        "default": "2",
+                        "tooltip": "Picture number to mention for image2 in the reference prompt.",
+                    },
+                ),
+                "location_id": (
+                    "STRING",
+                    {
+                        "default": "",
+                        "multiline": False,
+                        "tooltip": "Optional location ID string to include in the output text.",
+                    },
+                ),
+                "name": (
+                    "STRING",
+                    {
+                        "default": "",
+                        "multiline": False,
+                        "tooltip": "Location name used in the main reference sentences.",
+                    },
+                ),
+                "alias": (
+                    "STRING",
+                    {
+                        "default": "",
+                        "multiline": False,
+                        "tooltip": "Optional alternate name, label, or area name.",
+                    },
+                ),
+                "description": (
+                    "STRING",
+                    {
+                        "default": "",
+                        "multiline": True,
+                        "tooltip": "Persistent environment, layout, and atmosphere description.",
+                    },
+                ),
+                "general": (
+                    "STRING",
+                    {
+                        "default": "",
+                        "multiline": True,
+                        "tooltip": "Optional extra notes appended as the last sentence of the reference prompt.",
+                    },
+                ),
+            }
+        }
+
+    def build_location_text(
+        self,
+        image1,
+        image2,
+        image1_picture_id,
+        image2_picture_id,
+        location_id,
+        name,
+        alias,
+        description,
+        general,
+    ):
+        text = _build_location_helper_text(
+            image1_picture_id,
+            image2_picture_id,
+            location_id,
+            name,
+            alias,
+            description,
+            general,
+        )
+        common = {
+            "kind": "location",
+            "explicit_id": location_id,
+            "name": name,
+            "aliases": alias,
+            "description": description,
+            "general": general,
+            "facts": {},
+        }
+        reference1 = make_reference(
+            image=image1,
+            summary="Primary location reference.",
+            **common,
+        )
+        reference2 = make_reference(
+            image=image2,
+            summary="Secondary location reference.",
+            **common,
+        )
+        return (image1, image2, text, reference1, reference2)
+
+
 class DumasCharacterReferenceNode:
     DESCRIPTION = (
         "Build one structured REFERENCE object for a character so H3 can carry "
@@ -1836,6 +2507,166 @@ class DumasLocationReferenceNode:
         )
 
 
+class DumasSoundscapeHelperNode:
+    DESCRIPTION = (
+        "Choose a soundscape preset, auto-fill its editable description, and pass "
+        "the final soundscape text downstream for MiniMax H3 prompts."
+    )
+    RETURN_TYPES = ("STRING",)
+    RETURN_NAMES = ("soundscape",)
+    FUNCTION = "build_soundscape"
+    CATEGORY = "Dumas/MiniMax"
+
+    @classmethod
+    def INPUT_TYPES(cls):
+        default_soundscape = "quiet interior"
+        return {
+            "required": {
+                "soundscape": (
+                    _soundscape_options(),
+                    {
+                        "default": default_soundscape,
+                        "tooltip": "Preset title used to seed the editable soundscape description.",
+                    },
+                ),
+                "soundscape_description": (
+                    "STRING",
+                    {
+                        "default": _soundscape_description(default_soundscape),
+                        "multiline": True,
+                        "tooltip": (
+                            "Editable environmental audio description. Whatever text is here "
+                            "is what the node outputs to the soundscape socket."
+                        ),
+                    },
+                ),
+            }
+        }
+
+    def build_soundscape(self, soundscape, soundscape_description):
+        text = str(soundscape_description or "").strip()
+        if not text:
+            text = _soundscape_description(soundscape)
+        return (text,)
+
+
+class DumasH3PromptCuratorNode:
+    DESCRIPTION = (
+        "Curate one MiniMax H3 prompt from an action textbox, anchor text, "
+        "soundscape text, and up to nine structured references. References are "
+        "compacted so only mentioned names, aliases, or explicit <Picture N>/<refN> "
+        "tags are sent onward."
+    )
+    RETURN_TYPES = ("STRING",) + ("IMAGE",) * _H3_PROMPT_REF_SLOTS + ("INT", "STRING")
+    RETURN_NAMES = (
+        "prompt",
+        "ref_image_1",
+        "ref_image_2",
+        "ref_image_3",
+        "ref_image_4",
+        "ref_image_5",
+        "ref_image_6",
+        "ref_image_7",
+        "ref_image_8",
+        "ref_image_9",
+        "reference_count",
+        "debug",
+    )
+    FUNCTION = "curate_prompt"
+    CATEGORY = "Dumas/MiniMax"
+
+    @classmethod
+    def INPUT_TYPES(cls):
+        optional = {
+            "anchor": (
+                "STRING",
+                {
+                    "forceInput": True,
+                    "tooltip": "Optional anchor/style text, usually from Dumas Anchor Style.",
+                },
+            ),
+            "soundscape": (
+                "STRING",
+                {
+                    "forceInput": True,
+                    "tooltip": "Optional soundscape text, usually from Dumas Soundscape Helper.",
+                },
+            ),
+        }
+        for slot in range(1, _H3_PROMPT_REF_SLOTS + 1):
+            optional[f"ref_{slot}"] = (
+                _REFERENCE_TYPE,
+                {
+                    "tooltip": (
+                        f"Optional structured reference {slot}. The curator only outputs "
+                        "it if the action prompt mentions its name/alias or an explicit "
+                        f"<Picture {slot}>/<ref{slot}> tag."
+                    )
+                },
+            )
+        return {
+            "required": {
+                "action_prompt": (
+                    "STRING",
+                    {
+                        "default": "",
+                        "multiline": True,
+                        "tooltip": (
+                            "Write the final shot action here using character/location names. "
+                            "Mention a reference by name, alias, <Picture N>, or <refN> to use it."
+                        ),
+                    },
+                ),
+                "anatomy_guard": (
+                    ["auto", "on", "off"],
+                    {
+                        "default": "on",
+                        "tooltip": (
+                            "Add the anatomy guard. Auto adds it when a character reference is used."
+                        ),
+                    },
+                ),
+                "subject_count_guard": (
+                    ["auto", "on", "off"],
+                    {
+                        "default": "auto",
+                        "tooltip": (
+                            "Add a guard against extra people, duplicate bodies, or extra faces. "
+                            "Auto adds it when a character reference is used."
+                        ),
+                    },
+                ),
+            },
+            "optional": optional,
+        }
+
+    def curate_prompt(
+        self,
+        action_prompt,
+        anatomy_guard,
+        subject_count_guard,
+        anchor="",
+        soundscape="",
+        ref_1=None,
+        ref_2=None,
+        ref_3=None,
+        ref_4=None,
+        ref_5=None,
+        ref_6=None,
+        ref_7=None,
+        ref_8=None,
+        ref_9=None,
+    ):
+        return curate_h3_prompt(
+            action_prompt,
+            anchor=anchor,
+            soundscape=soundscape,
+            refs=(ref_1, ref_2, ref_3, ref_4, ref_5, ref_6, ref_7, ref_8, ref_9),
+            anatomy_guard=anatomy_guard,
+            subject_count_guard=subject_count_guard,
+        )
+
+
 class DumasAnchorStyleNode:
     DESCRIPTION = (
         "Choose an anchor-style preset, auto-fill its full description, and pass "
@@ -1887,9 +2718,12 @@ NODE_CLASS_MAPPINGS = {
     "DumasH3PlanExtractSceneImages": DumasH3PlanExtractSceneImagesNode,
     "DumasCharacterReference": DumasCharacterReferenceNode,
     "DumasLocationReference": DumasLocationReferenceNode,
+    "DumasSoundscapeHelper": DumasSoundscapeHelperNode,
+    "DumasH3PromptCurator": DumasH3PromptCuratorNode,
     "DumasAnchorStyle": DumasAnchorStyleNode,
-    "DumasCharacterHelper": DumasCharacterReferenceNode,
-    "DumasH3CharacterHelper": DumasCharacterReferenceNode,
+    "DumasCharacterHelper": DumasCharacterHelperNode,
+    "DumasLocationHelper": DumasLocationHelperNode,
+    "DumasH3CharacterHelper": DumasCharacterHelperNode,
 }
 
 NODE_DISPLAY_NAME_MAPPINGS = {
@@ -1900,7 +2734,10 @@ NODE_DISPLAY_NAME_MAPPINGS = {
     "DumasH3PlanExtractSceneImages": "Dumas H3 Plan Extract Scene Images",
     "DumasCharacterReference": "Dumas Character Reference",
     "DumasLocationReference": "Dumas Location Reference",
+    "DumasSoundscapeHelper": "Dumas Soundscape Helper",
+    "DumasH3PromptCurator": "Dumas H3 Prompt Curator",
     "DumasAnchorStyle": "Dumas Anchor Style",
-    "DumasCharacterHelper": "Dumas Character Reference",
-    "DumasH3CharacterHelper": "Dumas Character Reference",
+    "DumasCharacterHelper": "Dumas Character Helper",
+    "DumasLocationHelper": "Dumas Location Helper",
+    "DumasH3CharacterHelper": "Dumas Character Helper",
 }

dumas_json_nodes.py

@@ -277,7 +277,14 @@ class DumasJSONStringToObjectNode:
     def INPUT_TYPES(cls):
         return {
             "required": {
-                "json_string": ("STRING", {"multiline": True}),
+                "json_string": (
+                    "STRING",
+                    {
+                        "multiline": True,
+                        "default": '{\n  "shots": [\n    {\n      "prompt": "Francine stands by the window."\n    }\n  ]\n}',
+                        "tooltip": "Raw JSON text to parse into a structured JSON object."
+                    },
+                ),
             }
         }
 
@@ -299,7 +306,14 @@ class DumasStripIterationSuffixNode:
     def INPUT_TYPES(cls):
         return {
             "required": {
-                "filename": ("STRING", {"default": "", "multiline": False}),
+                "filename": (
+                    "STRING",
+                    {
+                        "default": "francine_pose_final.png",
+                        "multiline": False,
+                        "tooltip": "Filename to normalize by removing everything after the first underscore in the stem."
+                    },
+                ),
             }
         }
 
@@ -316,7 +330,14 @@ class DumasSlugifyStringNode:
     def INPUT_TYPES(cls):
         return {
             "required": {
-                "text": ("STRING", {"default": "", "multiline": False}),
+                "text": (
+                    "STRING",
+                    {
+                        "default": "Francine Coffee Shop",
+                        "multiline": False,
+                        "tooltip": "Text to slugify into lowercase ASCII words joined with hyphens."
+                    },
+                ),
             }
         }
 
@@ -334,8 +355,8 @@ class DumasJSONObjectToStringNode:
         return {
             "required": {
                 "json_object": ("JSON",),
-                "pretty": ("BOOLEAN", {"default": True}),
-                "sort_keys": ("BOOLEAN", {"default": False}),
+                "pretty": ("BOOLEAN", {"default": True, "tooltip": "Pretty-print the JSON with indentation."}),
+                "sort_keys": ("BOOLEAN", {"default": False, "tooltip": "Sort object keys alphabetically before serializing."}),
             }
         }
 
@@ -355,7 +376,7 @@ class DumasJSONGetValueNode:
         return {
             "required": {
                 "json_object": ("JSON",),
-                "path": ("STRING", {"default": "", "multiline": False}),
+                "path": ("STRING", {"default": "shots.0.prompt", "multiline": False, "tooltip": "Dot-path to read, such as 'shots.0.prompt'."}),
             }
         }
 
@@ -373,8 +394,8 @@ class DumasJSONSetValueNode:
         return {
             "required": {
                 "json_object": ("JSON",),
-                "path": ("STRING", {"default": "", "multiline": False}),
-                "value_json": ("STRING", {"multiline": True, "default": "null"}),
+                "path": ("STRING", {"default": "shots.0.prompt", "multiline": False, "tooltip": "Dot-path to write, such as 'shots.0.prompt' or 'shots.1.duration'."}),
+                "value_json": ("STRING", {"multiline": True, "default": '"Francine stands by the window."', "tooltip": "JSON value to store at the path. Must be valid JSON, so strings need quotes."}),
             }
         }
 
@@ -398,7 +419,7 @@ class DumasJSONHasKeyNode:
         return {
             "required": {
                 "json_object": ("JSON",),
-                "path": ("STRING", {"default": "", "multiline": False}),
+                "path": ("STRING", {"default": "shots.0.prompt", "multiline": False, "tooltip": "Dot-path to test for existence."}),
             }
         }
 
@@ -416,7 +437,7 @@ class DumasJSONRemoveKeyNode:
         return {
             "required": {
                 "json_object": ("JSON",),
-                "path": ("STRING", {"default": "", "multiline": False}),
+                "path": ("STRING", {"default": "shots.0.prompt", "multiline": False, "tooltip": "Dot-path to remove from the object."}),
             }
         }
 
@@ -434,7 +455,7 @@ class DumasJSONPickFieldsNode:
         return {
             "required": {
                 "json_object": ("JSON",),
-                "paths": ("STRING", {"multiline": True, "default": ""}),
+                "paths": ("STRING", {"multiline": True, "default": "shots.0.prompt\nshots.0.duration", "tooltip": "One dot-path per line. Only those fields are copied into the output object."}),
             }
         }
 
@@ -463,8 +484,8 @@ class DumasJSONMergeObjectsNode:
     def INPUT_TYPES(cls):
         return {
             "required": {
-                "base_object": ("JSON",),
-                "overlay_object": ("JSON",),
+                "base_object": ("JSON", {"tooltip": "Base JSON object to start from."}),
+                "overlay_object": ("JSON", {"tooltip": "Overlay JSON object whose keys replace or merge into the base object."}),
             }
         }
 
@@ -482,7 +503,7 @@ class DumasJSONKeysNode:
     def INPUT_TYPES(cls):
         return {
             "required": {
-                "json_object": ("JSON",),
+                "json_object": ("JSON", {"tooltip": "JSON object whose top-level keys should be listed."}),
             }
         }
 
@@ -502,7 +523,7 @@ class DumasJSONArrayLengthNode:
     def INPUT_TYPES(cls):
         return {
             "required": {
-                "json_array": ("JSON",),
+                "json_array": ("JSON", {"tooltip": "JSON array whose length should be measured."}),
             }
         }
 
@@ -521,8 +542,8 @@ class DumasJSONArrayAppendNode:
     def INPUT_TYPES(cls):
         return {
             "required": {
-                "json_array": ("JSON",),
-                "value_json": ("STRING", {"multiline": True, "default": "null"}),
+                "json_array": ("JSON", {"tooltip": "JSON array to append to."}),
+                "value_json": ("STRING", {"multiline": True, "default": '{"prompt":"Francine looks toward the door."}', "tooltip": "JSON value to append. Must be valid JSON."}),
             }
         }
 
@@ -548,10 +569,10 @@ class DumasJSONArraySliceNode:
     def INPUT_TYPES(cls):
         return {
             "required": {
-                "json_array": ("JSON",),
-                "start": ("INT", {"default": 0, "step": 1}),
-                "end": ("INT", {"default": 0, "step": 1}),
-                "step": ("INT", {"default": 1, "step": 1, "min": 1}),
+                "json_array": ("JSON", {"tooltip": "JSON array to slice."}),
+                "start": ("INT", {"default": 0, "step": 1, "tooltip": "Zero-based start index."}),
+                "end": ("INT", {"default": 0, "step": 1, "tooltip": "Zero-based end index. Use 0 to mean 'to the end'."}),
+                "step": ("INT", {"default": 1, "step": 1, "min": 1, "tooltip": "Slice step size."}),
             }
         }
 
@@ -572,9 +593,9 @@ class DumasJSONArrayIteratorNode:
     def INPUT_TYPES(cls):
         return {
             "required": {
-                "json_input": ("JSON",),
-                "index": ("INT", {"default": 0, "min": 0, "step": 1}),
-                "mode": (["fixed", "incr", "decr"], {"default": "fixed"}),
+                "json_input": ("JSON", {"tooltip": "JSON array to iterate over."}),
+                "index": ("INT", {"default": 0, "min": 0, "step": 1, "tooltip": "Current zero-based index."}),
+                "mode": (["fixed", "incr", "decr"], {"default": "fixed", "tooltip": "Keep the index fixed, increment it, or decrement it before reading."}),
             }
         }
 
@@ -600,9 +621,9 @@ class DumasJSONObjectIteratorNode:
     def INPUT_TYPES(cls):
         return {
             "required": {
-                "json_input": ("JSON",),
-                "index": ("INT", {"default": 0, "min": 0, "step": 1}),
-                "mode": (["fixed", "incr", "decr"], {"default": "fixed"}),
+                "json_input": ("JSON", {"tooltip": "JSON object whose key/value pairs should be iterated in insertion order."}),
+                "index": ("INT", {"default": 0, "min": 0, "step": 1, "tooltip": "Current zero-based index into the object's items."}),
+                "mode": (["fixed", "incr", "decr"], {"default": "fixed", "tooltip": "Keep the index fixed, increment it, or decrement it before reading."}),
             }
         }
 
@@ -628,7 +649,7 @@ class DumasJSONFlattenNode:
     def INPUT_TYPES(cls):
         return {
             "required": {
-                "json_input": ("JSON",),
+                "json_input": ("JSON", {"tooltip": "Nested JSON value to flatten into dot-path keys."}),
             }
         }
 
@@ -645,7 +666,7 @@ class DumasJSONUnflattenNode:
     def INPUT_TYPES(cls):
         return {
             "required": {
-                "flat_json_object": ("JSON",),
+                "flat_json_object": ("JSON", {"tooltip": "Flat JSON object whose keys are dot-paths to rebuild into nested JSON."}),
             }
         }
 

js/h3_longvideos/index.js

@@ -53,11 +53,10 @@ const GROUPS = [
   },
   {
     id: "finish",
-    label: "Upscale/Detail",
+    label: "Upscale",
     defaultCollapsed: true,
     widgets: [
       "upscale", "upscale_model", "upscale_target_short_edge", "upscale_batch",
-      "detail_pass", "detail_sampler_name", "detail_scheduler", "detail_steps", "detail_denoise",
     ],
   },
   {

tests/test_dumas_h3_longvideos.py

@@ -24,6 +24,7 @@ class DumasH3LongVideosHelperTests(unittest.TestCase):
                 "PIL.Image",
                 "folder_paths",
                 "dumas_image_nodes",
+                "dumas_h3_latent_upscale",
                 "dumas_h3_longvideos",
             )
         }
@@ -207,7 +208,7 @@ class DumasH3LongVideosHelperTests(unittest.TestCase):
                 "retry_elapsed": 1.2,
                 "attempts": 2,
                 "sample": 8.0,
-                "detail_sample": 0.5,
+                "latent_upscale_sample": 0.5,
                 "decode_video": 2.1,
                 "decode_audio": 0.4,
                 "cleanup": 0.2,
@@ -230,11 +231,11 @@ class DumasH3LongVideosHelperTests(unittest.TestCase):
         self.assertIn("decode audio 0.7s", note)
         self.assertIn("cleanup 0.3s", note)
         self.assertIn("retry elapsed 1.2s", note)
-        self.assertIn("detail 0.5s", note)
+        self.assertIn("latent upscale 0.5s", note)
         self.assertIn("retries 1", note)
         self.assertIn("slowest shot 1 12.4s", note)
 
-    def test_detail_pass_refines_video_but_preserves_audio(self):
+    def test_latent_upscale_refines_video_but_preserves_audio(self):
         class FakeTensor:
             def __init__(self, name):
                 self.name = name
@@ -263,6 +264,8 @@ class DumasH3LongVideosHelperTests(unittest.TestCase):
         original_decode_video = self.module._decode_video
         original_decode_audio = self.module._decode_audio
         original_cleanup = self.module._deep_cleanup
+        original_upscale = self.module._upscale_latent_video
+        original_copy_sample = self.module._copy_sample_latent
         original_nested = getattr(self.module.comfy.nested_tensor, "NestedTensor", None)
         try:
             self.module.comfy.nested_tensor.NestedTensor = FakeNestedTensor
@@ -277,6 +280,8 @@ class DumasH3LongVideosHelperTests(unittest.TestCase):
                 {"samples": FakeNestedTensor((FakeTensor("basev"), FakeTensor("basea")))},
             )
             self.module._evict_all_but = lambda *_args, **_kwargs: None
+            self.module._upscale_latent_video = lambda video, param: (FakeTensor("upv"), 8, 16)
+            self.module._copy_sample_latent = lambda sampled: sampled["samples"].unbind()
             self.module._decode_video = lambda _vae, out_latent, *_args, **_kwargs: out_latent
             self.module._decode_audio = lambda _vae, out_latent: out_latent
             self.module._deep_cleanup = lambda: None
@@ -298,18 +303,25 @@ class DumasH3LongVideosHelperTests(unittest.TestCase):
                 tiled=False,
                 sa=(123, 20, 1.0, "res_multistep", "simple", 1.0),
                 handoff=None,
-                detail_pass=True,
-                detail_sampler_name="euler",
-                detail_scheduler="beta",
-                detail_steps=5,
-                detail_denoise=0.4,
+                latent_upscale_param={
+                    "mode": "model",
+                    "model_name": "upscale.safetensors",
+                    "device": "cpu",
+                    "precision": "fp16",
+                    "sampler_name": "euler_ancestral",
+                    "scheduler": "simple",
+                    "steps": 2,
+                    "denoise": 0.4,
+                    "megapixels": 1.5,
+                },
             )
 
             self.assertEqual(len(calls), 2)
             self.assertIsNot(calls[1][0][8], first_out)
-            self.assertIs(calls[1][0][8]["samples"], first_out["samples"])
-            self.assertEqual(calls[1][0][4], "euler")
-            self.assertEqual(calls[1][0][5], "beta")
+            self.assertEqual(calls[1][0][8]["samples"].unbind()[0].name, "upv")
+            self.assertEqual(calls[1][0][2], 2)
+            self.assertEqual(calls[1][0][4], "euler_ancestral")
+            self.assertEqual(calls[1][0][5], "simple")
             self.assertAlmostEqual(calls[1][1]["denoise"], 0.4)
             self.assertEqual(result[1], first_out)
             self.assertEqual(result[2][0].name, "v2")
@@ -323,12 +335,14 @@ class DumasH3LongVideosHelperTests(unittest.TestCase):
             self.module._decode_video = original_decode_video
             self.module._decode_audio = original_decode_audio
             self.module._deep_cleanup = original_cleanup
+            self.module._upscale_latent_video = original_upscale
+            self.module._copy_sample_latent = original_copy_sample
             if original_nested is None:
                 delattr(self.module.comfy.nested_tensor, "NestedTensor")
             else:
                 self.module.comfy.nested_tensor.NestedTensor = original_nested
 
-    def test_detail_pass_decodes_audio_before_video_and_cleans_up(self):
+    def test_latent_upscale_decodes_audio_before_video_and_cleans_up(self):
         class FakeTensor:
             def __init__(self, name):
                 self.name = name
@@ -348,6 +362,7 @@ class DumasH3LongVideosHelperTests(unittest.TestCase):
                 return self._parts
 
         order = []
+        build_calls = []
         first_out = {"samples": FakeNestedTensor((FakeTensor("v1"), FakeTensor("a1")))}
         second_out = {"samples": FakeNestedTensor((FakeTensor("v2"), FakeTensor("a2")))}
 
@@ -357,12 +372,16 @@ class DumasH3LongVideosHelperTests(unittest.TestCase):
         original_decode_video = self.module._decode_video
         original_decode_audio = self.module._decode_audio
         original_cleanup = self.module._deep_cleanup
+        original_upscale = self.module._upscale_latent_video
+        original_copy_sample = self.module._copy_sample_latent
+        original_unload = getattr(self.module.mm, "unload_model_and_clones", None)
+        original_unload_all = self.module.mm.unload_all_models
         original_nested = getattr(self.module.comfy.nested_tensor, "NestedTensor", None)
         try:
             self.module.comfy.nested_tensor.NestedTensor = FakeNestedTensor
 
             def common_ksampler(*args, **kwargs):
-                order.append("detail_sample" if len(order) else "sample")
+                order.append("latent_upscale_sample" if len(order) else "sample")
                 return (first_out if len([x for x in order if x.endswith("sample")]) == 1 else second_out,)
 
             def decode_audio(_vae, out_latent):
@@ -379,12 +398,31 @@ class DumasH3LongVideosHelperTests(unittest.TestCase):
             def cleanup():
                 order.append("cleanup")
 
-            self.module.nodes.common_ksampler = common_ksampler
-            self.module._build_shot_conditioning = lambda *_args, **_kwargs: (
-                "cond",
+            def unload_model_and_clones(*_args, **_kwargs):
+                order.append("unload_h3_failed")
+                raise RuntimeError("model wrapper does not expose clone metadata")
+
+            def unload_all_models(*_args, **_kwargs):
+                order.append("unload_all")
+
+            def upscale_latent_video(video, param):
+                order.append("upscale")
+                return FakeTensor("upv"), 8, 16
+
+            def build_conditioning(*_args, **_kwargs):
+                build_calls.append(True)
+                return (
+                    [["cond", {}]],
                     {"samples": FakeNestedTensor((FakeTensor("basev"), FakeTensor("basea")))},
                 )
+
+            self.module.nodes.common_ksampler = common_ksampler
+            self.module._build_shot_conditioning = build_conditioning
             self.module._evict_all_but = lambda *_args, **_kwargs: None
+            self.module.mm.unload_model_and_clones = unload_model_and_clones
+            self.module.mm.unload_all_models = unload_all_models
+            self.module._upscale_latent_video = upscale_latent_video
+            self.module._copy_sample_latent = lambda sampled: sampled["samples"].unbind()
             self.module._decode_video = decode_video
             self.module._decode_audio = decode_audio
             self.module._deep_cleanup = cleanup
@@ -406,17 +444,25 @@ class DumasH3LongVideosHelperTests(unittest.TestCase):
                 tiled=False,
                 sa=(123, 20, 1.0, "res_multistep", "simple", 1.0),
                 handoff=None,
-                detail_pass=True,
-                detail_sampler_name="euler",
-                detail_scheduler="beta",
-                detail_steps=5,
-                detail_denoise=0.4,
+                latent_upscale_param={
+                    "mode": "model",
+                    "model_name": "upscale.safetensors",
+                    "device": "cuda",
+                    "precision": "fp16",
+                    "sampler_name": "euler_ancestral",
+                    "scheduler": "simple",
+                    "steps": 2,
+                    "denoise": 0.4,
+                    "megapixels": 1.5,
+                },
             )
 
             self.assertEqual(order[0], "sample")
-            self.assertEqual(order[1], "detail_sample")
+            self.assertLess(order.index("unload_all"), order.index("upscale"))
+            self.assertLess(order.index("upscale"), order.index("latent_upscale_sample"))
             self.assertLess(order.index("audio"), order.index("video"))
             self.assertEqual(order[-1], "cleanup")
+            self.assertEqual(len(build_calls), 1)
         finally:
             self.module.nodes.common_ksampler = original_common_ksampler
             self.module._build_shot_conditioning = original_build
@@ -424,12 +470,25 @@ class DumasH3LongVideosHelperTests(unittest.TestCase):
             self.module._decode_video = original_decode_video
             self.module._decode_audio = original_decode_audio
             self.module._deep_cleanup = original_cleanup
+            self.module._upscale_latent_video = original_upscale
+            self.module._copy_sample_latent = original_copy_sample
+            if original_unload is None:
+                delattr(self.module.mm, "unload_model_and_clones")
+            else:
+                self.module.mm.unload_model_and_clones = original_unload
+            self.module.mm.unload_all_models = original_unload_all
             if original_nested is None:
                 delattr(self.module.comfy.nested_tensor, "NestedTensor")
             else:
                 self.module.comfy.nested_tensor.NestedTensor = original_nested
 
-    def test_detail_pass_treats_falsey_strings_as_disabled(self):
+    def test_latent_refine_tiles_do_not_rebuild_conditioning(self):
+        source = inspect.getsource(self.module.H3LongVideos._render)
+        tile_branch = source[source.index("for col_index, c0 in enumerate(cols):"):]
+        self.assertIn("_crop_conditioning_to_tile", tile_branch)
+        self.assertNotIn("_build_shot_conditioning(", tile_branch)
+
+    def test_latent_upscale_off_skips_second_pass(self):
         calls = []
         original_common_ksampler = self.module.nodes.common_ksampler
         original_build = self.module._build_shot_conditioning
@@ -437,6 +496,8 @@ class DumasH3LongVideosHelperTests(unittest.TestCase):
         original_decode_video = self.module._decode_video
         original_decode_audio = self.module._decode_audio
         original_cleanup = self.module._deep_cleanup
+        original_upscale = self.module._upscale_latent_video
+        original_copy_sample = self.module._copy_sample_latent
         try:
             self.module.nodes.common_ksampler = lambda *args, **kwargs: (calls.append((args, kwargs)) or {"samples": "latent"},)
             self.module._build_shot_conditioning = lambda *_args, **_kwargs: ("cond", {"samples": "base"})
@@ -444,6 +505,8 @@ class DumasH3LongVideosHelperTests(unittest.TestCase):
             self.module._decode_video = lambda _vae, out_latent, *_args, **_kwargs: out_latent
             self.module._decode_audio = lambda _vae, out_latent: out_latent
             self.module._deep_cleanup = lambda: None
+            self.module._upscale_latent_video = lambda *_args, **_kwargs: (_ for _ in ()).throw(RuntimeError("should not run"))
+            self.module._copy_sample_latent = lambda sampled: sampled
 
             self.module.H3LongVideos()._render(
                 model=object(),
@@ -459,7 +522,7 @@ class DumasH3LongVideosHelperTests(unittest.TestCase):
                 tiled=False,
                 sa=(123, 20, 1.0, "res_multistep", "simple", 1.0),
                 handoff=None,
-                detail_pass="false",
+                latent_upscale_param={"mode": "off"},
             )
 
             self.assertEqual(len(calls), 1)
@@ -470,6 +533,8 @@ class DumasH3LongVideosHelperTests(unittest.TestCase):
             self.module._decode_video = original_decode_video
             self.module._decode_audio = original_decode_audio
             self.module._deep_cleanup = original_cleanup
+            self.module._upscale_latent_video = original_upscale
+            self.module._copy_sample_latent = original_copy_sample
 
     def test_distribute_generations_canonicalizes_per_shot_audio_and_anchor_directives(self):
         generations = self.module.distribute_generations(
@@ -736,6 +801,12 @@ class DumasH3LongVideosHelperTests(unittest.TestCase):
             self.assertNotIn(f"ref_image_{index}", optional)
         self.assertNotIn("per_beat_length", optional)
         self.assertNotIn("cleanup_between_shots", optional)
+        self.assertNotIn("detail_pass", optional)
+        self.assertNotIn("detail_sampler_name", optional)
+        self.assertNotIn("detail_scheduler", optional)
+        self.assertNotIn("detail_steps", optional)
+        self.assertNotIn("detail_denoise", optional)
+        self.assertIn("latent_upscale_param", optional)
 
     def test_shot_seconds_tooltip_describes_ceiling_behavior(self):
         optional = self.module.H3LongVideos.INPUT_TYPES()["optional"]
@@ -743,7 +814,7 @@ class DumasH3LongVideosHelperTests(unittest.TestCase):
 
         self.assertIn("GLOBAL per-shot maximum", tooltip)
         self.assertIn("A beat's own `seconds:` directive can still ask for less", tooltip)
-        self.assertIn("honoring it; may spill to system RAM (slow) or OOM", tooltip)
+        self.assertIn("let the render fail instead of shrinking it", tooltip)
 
     def test_resolve_shot_frames_honors_forced_request_over_budget(self):
         original_estimate_shot_frames = self.module.estimate_shot_frames
@@ -928,12 +999,23 @@ class DumasH3LongVideosHelperTests(unittest.TestCase):
                 plan_only=True,
                 ref_1={"image": "live-1"},
                 ref_3={"image": "live-3"},
+                latent_upscale_param={
+                    "mode": "interp",
+                    "method": "bilinear",
+                    "sampler_name": "euler_ancestral",
+                    "scheduler": "simple",
+                    "steps": 2,
+                    "denoise": 0.2,
+                    "megapixels": 1.5,
+                },
             )
 
             self.assertEqual(calls["refs"][0]["image"], "live-1")
             self.assertIsNone(calls["refs"][1])
             self.assertEqual(calls["refs"][2]["image"], "live-3")
             self.assertEqual(result[2].count("ref2va: 2 reference image(s)"), 1)
+            self.assertIn("latent upscale:", result[2])
+            self.assertIn("euler_ancestral/simple", result[2])
         finally:
             self.module.parse_resolution = original_parse_resolution
             self.module._connected_refs = original_connected_refs
@@ -1061,6 +1143,389 @@ class DumasH3LongVideosHelperTests(unittest.TestCase):
             {"DumasH3LongVideos": "Dumas H3 Long Videos (FL2VA + REF2VA)"},
         )
 
+    def test_latent_upscale_params_node_is_exposed(self):
+        latent = importlib.import_module("dumas_h3_latent_upscale")
+        required = latent.H3LatentUpscaleParams.INPUT_TYPES()["required"]
+
+        self.assertEqual(
+            latent.NODE_CLASS_MAPPINGS,
+            {"DumasH3LatentUpscaleParams": latent.H3LatentUpscaleParams},
+        )
+        self.assertEqual(
+            latent.NODE_DISPLAY_NAME_MAPPINGS,
+            {"DumasH3LatentUpscaleParams": "Dumas H3 Latent Upscale Params"},
+        )
+        self.assertEqual(required["sampler_name"][1]["default"], "euler_ancestral")
+        self.assertEqual(required["scheduler"][1]["default"], "simple")
+        self.assertEqual(required["steps"][1]["default"], 2)
+        self.assertEqual(required["denoise"][1]["default"], 0.2)
+        self.assertEqual(required["megapixels"][1]["default"], 1.0)
+        self.assertEqual(required["tile_width"][1]["default"], 512)
+        self.assertEqual(required["tile_height"][1]["default"], 512)
+        self.assertEqual(required["overlap"][1]["default"], 64)
+        self.assertEqual(required["fade_width"][1]["default"], 32)
+        self.assertEqual(required["fade_height"][1]["default"], 32)
+        self.assertEqual(required["overlap_mode"][1]["default"], "earlier")
+        self.assertEqual(required["overlap_blend"][1]["default"], "linear")
+        self.assertEqual(required["tile_size_mode"][1]["default"], "specific_size")
+        self.assertEqual(required["grid_rows"][1]["default"], 2)
+        self.assertEqual(required["grid_cols"][1]["default"], 2)
+        self.assertEqual(required["spatial_w_overlap"][1]["default"], 128)
+        self.assertEqual(required["spatial_h_overlap"][1]["default"], 128)
+        self.assertEqual(required["min_tile_size"][1]["default"], 256)
+        self.assertEqual(required["masked_area_noise"][1]["default"], 0.0)
+        self.assertFalse(required["brightness_match"][1]["default"])
+        self.assertEqual(required["dynamic_fade"][1]["default"], "off")
+        self.assertEqual(required["dynamic_fade_min"][1]["default"], 32)
+        self.assertEqual(required["chunk_length"][1]["default"], 85)
+        self.assertEqual(required["temporal_overlap"][1]["default"], 17)
+        self.assertFalse(required["resize_conditioning"][1]["default"])
+        self.assertEqual(required["anchor_strength"][1]["default"], 0.999)
+
+    def test_latent_upscale_mode_infers_legacy_model_payloads(self):
+        self.assertEqual(self.module._latent_upscale_mode({"model_name": "foo.safetensors"}), "model")
+        self.assertEqual(self.module._latent_upscale_mode({"method": "bilinear"}), "interp")
+        self.assertEqual(self.module._latent_upscale_mode({"mode": "model"}), "model")
+        self.assertEqual(self.module._latent_upscale_mode({}), "off")
+
+    def test_tag_oom_stage_marks_oom_exceptions(self):
+        exc = RuntimeError("CUDA out of memory")
+        tagged = self.module._tag_oom_stage(exc, "latent_upscale")
+        self.assertIs(tagged, exc)
+        self.assertEqual(getattr(tagged, "_h3_stage", ""), "latent_upscale")
+
+    def test_shrink_model_tile_param_reduces_tile_size(self):
+        latent = importlib.import_module("dumas_h3_latent_upscale")
+        smaller = latent._shrink_model_tile_param({
+            "tile_size_mode": "specific_size",
+            "tile_width": 512,
+            "tile_height": 512,
+            "overlap": 64,
+            "fade_width": 32,
+            "fade_height": 32,
+        })
+        self.assertIsNotNone(smaller)
+        self.assertEqual(smaller["tile_size_mode"], "rows_cols")
+        self.assertEqual(smaller["grid_rows"], 4)
+        self.assertEqual(smaller["grid_cols"], 4)
+        self.assertEqual(smaller["spatial_w_overlap"], 0)
+        self.assertEqual(smaller["spatial_h_overlap"], 0)
+        self.assertEqual(smaller["fade_width"], 0)
+        self.assertEqual(smaller["fade_height"], 0)
+        self.assertEqual(smaller["min_tile_size"], 32)
+
+    def test_shrink_model_tile_param_rows_cols_resets_overlap(self):
+        latent = importlib.import_module("dumas_h3_latent_upscale")
+        smaller = latent._shrink_model_tile_param({
+            "tile_size_mode": "rows_cols",
+            "grid_rows": 4,
+            "grid_cols": 4,
+            "spatial_w_overlap": 128,
+            "spatial_h_overlap": 128,
+            "fade_width": 64,
+            "fade_height": 64,
+            "min_tile_size": 256,
+        })
+        self.assertIsNotNone(smaller)
+        self.assertEqual(smaller["grid_rows"], 8)
+        self.assertEqual(smaller["grid_cols"], 8)
+        self.assertEqual(smaller["spatial_w_overlap"], 0)
+        self.assertEqual(smaller["spatial_h_overlap"], 0)
+        self.assertEqual(smaller["fade_width"], 0)
+        self.assertEqual(smaller["fade_height"], 0)
+        self.assertEqual(smaller["min_tile_size"], 32)
+
+    def test_shrink_model_tile_param_rows_cols_can_reach_thirty_two(self):
+        latent = importlib.import_module("dumas_h3_latent_upscale")
+        smaller = latent._shrink_model_tile_param({
+            "tile_size_mode": "rows_cols",
+            "grid_rows": 16,
+            "grid_cols": 16,
+            "spatial_w_overlap": 0,
+            "spatial_h_overlap": 0,
+            "fade_width": 0,
+            "fade_height": 0,
+            "min_tile_size": 32,
+        })
+        self.assertIsNotNone(smaller)
+        self.assertEqual(smaller["grid_rows"], 32)
+        self.assertEqual(smaller["grid_cols"], 32)
+
+    def test_temporal_segments_split_long_sequences(self):
+        latent = importlib.import_module("dumas_h3_latent_upscale")
+        bounds = latent._temporal_segments(36, 85, 17)
+        self.assertGreater(len(bounds), 1)
+        self.assertEqual(bounds[0][0], 0)
+        self.assertEqual(bounds[-1][2], 36)
+
+    def test_shrink_temporal_param_reduces_chunk_length(self):
+        latent = importlib.import_module("dumas_h3_latent_upscale")
+        smaller = latent._shrink_temporal_param({
+            "chunk_length": 85,
+            "temporal_overlap": 17,
+        })
+        self.assertIsNotNone(smaller)
+        self.assertEqual(smaller["chunk_length"], 17)
+        self.assertEqual(smaller["temporal_overlap"], 0)
+
+    def test_cuda_model_temporal_params_keep_splitting_saved_workflows(self):
+        latent = importlib.import_module("dumas_h3_latent_upscale")
+        chunk_length, temporal_overlap = latent._effective_temporal_params({
+            "mode": "model",
+            "device": "cuda",
+            "chunk_length": 85,
+            "temporal_overlap": 17,
+        }, frame_count=124)
+        self.assertEqual(chunk_length, 85)
+        self.assertEqual(temporal_overlap, 17)
+
+    def test_cuda_model_temporal_params_keep_short_saved_workflows_until_oom(self):
+        latent = importlib.import_module("dumas_h3_latent_upscale")
+        chunk_length, temporal_overlap = latent._effective_temporal_params({
+            "mode": "model",
+            "device": "cuda",
+            "chunk_length": 85,
+            "temporal_overlap": 17,
+        }, frame_count=85)
+        self.assertEqual(chunk_length, 85)
+        self.assertEqual(temporal_overlap, 17)
+
+    def test_cuda_model_oom_retries_temporal_before_spatial_fallback(self):
+        latent = importlib.import_module("dumas_h3_latent_upscale")
+
+        calls = []
+        original_tiled = latent._upscale_video_model_tiled
+        original_shrink_model = latent._shrink_model_tile_param
+        try:
+            def tiled(_video, param):
+                calls.append(("tiled", param.get("chunk_length"), param.get("tile_size_mode")))
+                raise RuntimeError("out of memory")
+
+            latent._upscale_video_model_tiled = tiled
+            latent._shrink_model_tile_param = (
+                lambda param: calls.append(("shrink_spatial", param.get("tile_size_mode"))) or None
+            )
+
+            with self.assertRaisesRegex(RuntimeError, "smaller temporal chunk"):
+                latent.upscale_video_model(
+                    "video",
+                    {
+                        "mode": "model",
+                        "device": "cuda",
+                        "model_name": "upscale.safetensors",
+                        "chunk_length": 85,
+                        "temporal_overlap": 17,
+                    },
+                )
+
+            self.assertEqual(calls[0], ("tiled", 85, None))
+            self.assertNotIn(("shrink_spatial", None), calls)
+        finally:
+            latent._upscale_video_model_tiled = original_tiled
+            latent._shrink_model_tile_param = original_shrink_model
+
+    def test_interp_temporal_params_preserve_upstream_defaults(self):
+        latent = importlib.import_module("dumas_h3_latent_upscale")
+        chunk_length, temporal_overlap = latent._effective_temporal_params({
+            "mode": "interp",
+            "device": "cuda",
+            "chunk_length": 85,
+            "temporal_overlap": 17,
+        })
+        self.assertEqual(chunk_length, 85)
+        self.assertEqual(temporal_overlap, 17)
+
+    def test_unload_upscale_model_defers_while_held(self):
+        latent = importlib.import_module("dumas_h3_latent_upscale")
+
+        class FakeParam:
+            device = "cuda"
+
+        class FakeModel:
+            def __init__(self):
+                self.moves = []
+
+            def parameters(self):
+                return iter((FakeParam(),))
+
+            def to(self, device):
+                self.moves.append(device)
+                return self
+
+        cache_key = "upscale.safetensors::cuda::fp16"
+        original_cache_value = latent._MODEL_CACHE.get(cache_key)
+        original_hold_depth = latent._MODEL_HOLD_DEPTH
+        fake_model = FakeModel()
+        try:
+            latent._MODEL_CACHE[cache_key] = fake_model
+            latent._MODEL_HOLD_DEPTH = 0
+            with latent._hold_upscale_model_loaded():
+                latent.unload_upscale_model("upscale.safetensors", "cuda", "fp16")
+            self.assertEqual(fake_model.moves, [])
+
+            latent.unload_upscale_model("upscale.safetensors", "cuda", "fp16")
+            self.assertEqual(fake_model.moves, ["cpu"])
+        finally:
+            latent._MODEL_HOLD_DEPTH = original_hold_depth
+            if original_cache_value is None:
+                latent._MODEL_CACHE.pop(cache_key, None)
+            else:
+                latent._MODEL_CACHE[cache_key] = original_cache_value
+
+    def test_model_upscale_releases_cached_model_after_pass(self):
+        latent = importlib.import_module("dumas_h3_latent_upscale")
+        calls = []
+
+        original_temporal = latent._upscale_video_temporal_chunks
+        original_unload_now = latent._unload_upscale_model_now
+        original_cuda = latent.torch.cuda
+        original_device = getattr(latent.torch, "device", None)
+        try:
+            latent.torch.cuda = types.SimpleNamespace(is_available=lambda: True)
+            latent.torch.device = lambda value: value
+
+            def temporal(video, param, upscaler):
+                calls.append(("temporal", latent._MODEL_HOLD_DEPTH))
+                return "video", 8, 16
+
+            def unload_now(name, device, precision):
+                calls.append(("unload", name, device, precision, latent._MODEL_HOLD_DEPTH))
+
+            latent._upscale_video_temporal_chunks = temporal
+            latent._unload_upscale_model_now = unload_now
+
+            result = latent.upscale_latent_video("source", {
+                "mode": "model",
+                "model_name": "upscale.safetensors",
+                "device": "cuda",
+                "precision": "fp16",
+            })
+
+            self.assertEqual(result, ("video", 8, 16))
+            self.assertEqual(calls[0], ("temporal", 1))
+            self.assertEqual(calls[1], ("unload", "upscale.safetensors", "cuda", "fp16", 1))
+            self.assertEqual(latent._MODEL_HOLD_DEPTH, 0)
+        finally:
+            latent._upscale_video_temporal_chunks = original_temporal
+            latent._unload_upscale_model_now = original_unload_now
+            latent.torch.cuda = original_cuda
+            if original_device is None:
+                delattr(latent.torch, "device")
+            else:
+                latent.torch.device = original_device
+
+    def test_model_upscale_oom_falls_back_to_interp(self):
+        latent = importlib.import_module("dumas_h3_latent_upscale")
+        calls = []
+
+        original_temporal = latent._upscale_video_temporal_chunks
+        original_interp = latent.upscale_video_interp
+        original_unload_now = latent._unload_upscale_model_now
+        original_cuda = latent.torch.cuda
+        original_device = getattr(latent.torch, "device", None)
+        try:
+            latent.torch.cuda = types.SimpleNamespace(
+                is_available=lambda: True,
+                empty_cache=lambda: calls.append(("empty_cache",)),
+            )
+            latent.torch.device = lambda value: value
+
+            def temporal(_video, _param, _upscaler):
+                calls.append(("temporal", latent._MODEL_HOLD_DEPTH))
+                raise RuntimeError("H3 latent upscale exhausted its GPU spatial fallbacks")
+
+            def interp(video, param):
+                calls.append(("interp", video, param.get("mode"), param.get("method")))
+                return "interp_video", 8, 16
+
+            def unload_now(name, device, precision):
+                calls.append(("unload", name, device, precision, latent._MODEL_HOLD_DEPTH))
+
+            latent._upscale_video_temporal_chunks = temporal
+            latent.upscale_video_interp = interp
+            latent._unload_upscale_model_now = unload_now
+
+            result = latent.upscale_latent_video("source", {
+                "mode": "model",
+                "model_name": "upscale.safetensors",
+                "method": "bilinear",
+                "device": "cuda",
+                "precision": "fp16",
+            })
+
+            self.assertEqual(result, ("interp_video", 8, 16))
+            self.assertEqual(calls[0], ("temporal", 1))
+            self.assertEqual(calls[1], ("unload", "upscale.safetensors", "cuda", "fp16", 1))
+            self.assertIn(("empty_cache",), calls)
+            self.assertEqual(calls[-1], ("interp", "source", "interp", "bilinear"))
+            self.assertEqual(latent._MODEL_HOLD_DEPTH, 0)
+        finally:
+            latent._upscale_video_temporal_chunks = original_temporal
+            latent.upscale_video_interp = original_interp
+            latent._unload_upscale_model_now = original_unload_now
+            latent.torch.cuda = original_cuda
+            if original_device is None:
+                delattr(latent.torch, "device")
+            else:
+                latent.torch.device = original_device
+
+    def test_model_upscale_skips_learned_model_on_8gb_cuda(self):
+        latent = importlib.import_module("dumas_h3_latent_upscale")
+        calls = []
+
+        original_temporal = latent._upscale_video_temporal_chunks
+        original_interp = latent.upscale_video_interp
+        original_cuda = latent.torch.cuda
+        try:
+            latent.torch.cuda = types.SimpleNamespace(
+                is_available=lambda: True,
+                mem_get_info=lambda: (1 * 1024 * 1024 * 1024, 8 * 1024 * 1024 * 1024),
+                empty_cache=lambda: calls.append(("empty_cache",)),
+            )
+
+            def temporal(_video, _param, _upscaler):
+                calls.append(("temporal",))
+                raise AssertionError("learned model path should be skipped on 8GB CUDA")
+
+            def interp(video, param):
+                calls.append(("interp", video, param.get("mode"), param.get("method")))
+                return "interp_video", 8, 16
+
+            latent._upscale_video_temporal_chunks = temporal
+            latent.upscale_video_interp = interp
+
+            result = latent.upscale_latent_video("source", {
+                "mode": "model",
+                "model_name": "upscale.safetensors",
+                "method": "bilinear",
+                "device": "cuda",
+                "precision": "fp16",
+            })
+
+            self.assertEqual(result, ("interp_video", 8, 16))
+            self.assertNotIn(("temporal",), calls)
+            self.assertIn(("empty_cache",), calls)
+            self.assertEqual(calls[-1], ("interp", "source", "interp", "bilinear"))
+        finally:
+            latent._upscale_video_temporal_chunks = original_temporal
+            latent.upscale_video_interp = original_interp
+            latent.torch.cuda = original_cuda
+
+    def test_upscale_video_model_raises_when_gpu_cannot_shrink(self):
+        latent = importlib.import_module("dumas_h3_latent_upscale")
+
+        original_tiled = latent._upscale_video_model_tiled
+        original_shrink = latent._shrink_model_tile_param
+        try:
+            latent._shrink_model_tile_param = lambda _param: None
+            latent._upscale_video_model_tiled = lambda *_args, **_kwargs: (_ for _ in ()).throw(RuntimeError("out of memory"))
+
+            with self.assertRaisesRegex(RuntimeError, "H3 latent upscale exhausted its GPU spatial fallbacks"):
+                latent.upscale_video_model("video", {"device": "cuda", "precision": "fp16"})
+        finally:
+            latent._upscale_video_model_tiled = original_tiled
+            latent._shrink_model_tile_param = original_shrink
+
     def test_compose_persistent_does_not_expand_ambiguous_plural_to_full_cast(self):
         active = self.module.parse_wardrobe(
             "Maya = she, red jacket\n"

tests/test_dumas_image_nodes.py

@@ -356,6 +356,277 @@ class DumasImageNodeTests(unittest.TestCase):
         required = self.image_nodes.DumasLocationReferenceNode.INPUT_TYPES()["required"]
         self.assertNotIn("picture_id", required)
 
+    def test_character_helper_restores_image_and_text_outputs(self):
+        node = self.image_nodes.DumasCharacterHelperNode()
+        image1 = FakeTensorBatch()
+        image2 = FakeTensorBatch()
+
+        result = node.build_character_text(
+            image1=image1,
+            image2=image2,
+            image1_picture_id="1",
+            image2_picture_id="2",
+            character_id="char_dave",
+            name="Dave",
+            alias="The Locksmith",
+            gender="male",
+            age="41",
+            nationality="English",
+            occupation="a detective",
+            height_feet="6",
+            height_inches="2",
+            accent="English",
+            general="Moves carefully and notices every exit",
+            wardrobe="weathered red flight jacket, grey cargo shorts, black boots",
+        )
+
+        self.assertIs(result[0], image1)
+        self.assertIs(result[1], image2)
+        self.assertIn("<Picture 1> and <Picture 2> reference the same character", result[2])
+        self.assertIn("Dave is also known as The Locksmith", result[2])
+        self.assertIn("is 41 years old", result[2])
+        self.assertEqual(result[3], "Dave = weathered red flight jacket, grey cargo shorts, black boots")
+        self.assertIs(result[4]["image"], image1)
+        self.assertIs(result[5]["image"], image2)
+        self.assertEqual(result[4]["id"], "char-dave")
+        self.assertEqual(result[5]["id"], "char-dave")
+        self.assertEqual(result[4]["name"], "Dave")
+        self.assertEqual(result[4]["aliases"], ["The Locksmith"])
+        self.assertEqual(result[4]["facts"]["age"], "41")
+        self.assertEqual(result[4]["facts"]["height_feet"], "6")
+        self.assertEqual(result[4]["facts"]["height_inches"], "2")
+        self.assertEqual(result[4]["wardrobe"], "weathered red flight jacket, grey cargo shorts, black boots")
+        self.assertEqual(len(result), 6)
+
+    def test_location_helper_matches_character_helper_shape_without_wardrobe(self):
+        node = self.image_nodes.DumasLocationHelperNode()
+        image1 = FakeTensorBatch()
+        image2 = FakeTensorBatch()
+
+        result = node.build_location_text(
+            image1=image1,
+            image2=image2,
+            image1_picture_id="3",
+            image2_picture_id="4",
+            location_id="coffee-shop-01",
+            name="Coffee Shop",
+            alias="Cafe Interior",
+            description="Warm tungsten lighting, narrow counter, rainy front window",
+            general="Evening ambience, cramped but cozy",
+        )
+
+        self.assertIs(result[0], image1)
+        self.assertIs(result[1], image2)
+        self.assertIn("<Picture 3> and <Picture 4> reference the same location", result[2])
+        self.assertIn("Coffee Shop is also known as Cafe Interior", result[2])
+        self.assertIn("Warm tungsten lighting, narrow counter, rainy front window.", result[2])
+        self.assertIn("Evening ambience, cramped but cozy.", result[2])
+        self.assertIs(result[3]["image"], image1)
+        self.assertIs(result[4]["image"], image2)
+        self.assertEqual(result[3]["kind"], "location")
+        self.assertEqual(result[4]["kind"], "location")
+        self.assertEqual(result[3]["id"], "coffee-shop-01")
+        self.assertEqual(result[4]["id"], "coffee-shop-01")
+        self.assertEqual(result[3]["name"], "Coffee Shop")
+        self.assertEqual(result[3]["aliases"], ["Cafe Interior"])
+        self.assertEqual(result[3]["description"], "Warm tungsten lighting, narrow counter, rainy front window")
+        self.assertEqual(result[3]["general"], "Evening ambience, cramped but cozy")
+        self.assertEqual(len(result), 5)
+
+    def test_soundscape_helper_defaults_to_selected_preset_description(self):
+        node = self.image_nodes.DumasSoundscapeHelperNode()
+
+        result = node.build_soundscape("rainy street", "")
+
+        self.assertEqual(result[0], "steady rain, wet pavement, distant traffic hum")
+
+    def test_h3_prompt_curator_compacts_named_references(self):
+        node = self.image_nodes.DumasH3PromptCuratorNode()
+        dave_image = FakeTensorBatch()
+        cafe_image = FakeTensorBatch()
+        van_image = FakeTensorBatch()
+        dave = self.image_nodes.make_reference(
+            kind="character",
+            image=dave_image,
+            name="Dave",
+            aliases="The Locksmith",
+            description="tired eyes, cropped brown hair",
+            wardrobe="red flight jacket",
+        )
+        cafe = self.image_nodes.make_reference(
+            kind="location",
+            image=cafe_image,
+            name="Coffee Shop",
+            description="warm tungsten lighting and rainy windows",
+        )
+        van = self.image_nodes.make_reference(
+            kind="location",
+            image=van_image,
+            name="Blue Van",
+            description="scuffed blue delivery van",
+        )
+
+        result = node.curate_prompt(
+            action_prompt="Dave runs from the Coffee Shop into the rain.",
+            anatomy_guard="auto",
+            subject_count_guard="auto",
+            anchor="grounded handheld thriller",
+            soundscape="steady rain",
+            ref_1=dave,
+            ref_2=van,
+            ref_3=cafe,
+        )
+
+        prompt = result[0]
+        self.assertIn("<Picture 1> Dave", prompt)
+        self.assertIn("<Picture 2> Coffee Shop", prompt)
+        self.assertIn("Action: Dave runs from the Coffee Shop into the rain.", prompt)
+        self.assertIn("Anatomy guard:", prompt)
+        self.assertIn("Subject count guard:", prompt)
+        self.assertIn("exactly one named character: <Picture 1> Dave", prompt)
+        self.assertIs(result[1], dave_image)
+        self.assertIs(result[2], cafe_image)
+        self.assertIsNone(result[3])
+        self.assertEqual(result[10], 2)
+        self.assertIn("input 3-><Picture 2> Coffee Shop", result[11])
+
+    def test_h3_prompt_curator_renumbers_explicit_reference_tags(self):
+        node = self.image_nodes.DumasH3PromptCuratorNode()
+        image1 = FakeTensorBatch()
+        image3 = FakeTensorBatch()
+        unused = FakeTensorBatch()
+        first = self.image_nodes.make_reference(kind="character", image=image1, name="Maya")
+        second = self.image_nodes.make_reference(kind="location", image=unused, name="Lobby")
+        third = self.image_nodes.make_reference(kind="location", image=image3, name="Rooftop")
+
+        result = node.curate_prompt(
+            action_prompt="<Picture 1> Maya crosses to <ref3> as the wind rises.",
+            anatomy_guard="off",
+            subject_count_guard="off",
+            ref_1=first,
+            ref_2=second,
+            ref_3=third,
+        )
+
+        prompt = result[0]
+        self.assertIn("<Picture 1> Maya crosses to <Picture 2>", prompt)
+        self.assertNotIn("<Picture 3>", prompt)
+        self.assertIs(result[1], image1)
+        self.assertIs(result[2], image3)
+        self.assertIsNone(result[3])
+        self.assertEqual(result[10], 2)
+
+    def test_h3_prompt_curator_can_force_subject_count_without_character_refs(self):
+        node = self.image_nodes.DumasH3PromptCuratorNode()
+
+        result = node.curate_prompt(
+            action_prompt="A locked-off shot of the empty corridor.",
+            anatomy_guard="off",
+            subject_count_guard="on",
+        )
+
+        self.assertIn("Subject count guard:", result[0])
+        self.assertIn("Only include the people explicitly described", result[0])
+        self.assertEqual(result[10], 0)
+
+    def test_h3_prompt_curator_treats_helper_image_pair_as_one_character(self):
+        helper = self.image_nodes.DumasCharacterHelperNode()
+        curator = self.image_nodes.DumasH3PromptCuratorNode()
+        image1 = FakeTensorBatch()
+        image2 = FakeTensorBatch()
+        helper_result = helper.build_character_text(
+            image1=image1,
+            image2=image2,
+            image1_picture_id="1",
+            image2_picture_id="2",
+            character_id="char_dave",
+            name="Dave",
+            alias="The Locksmith",
+            gender="male",
+            age="41",
+            nationality="English",
+            occupation="detective",
+            height_feet="6",
+            height_inches="2",
+            accent="English",
+            general="Tired eyes, cropped brown hair",
+            wardrobe="weathered red flight jacket",
+        )
+
+        result = curator.curate_prompt(
+            action_prompt="Dave checks the locked door.",
+            anatomy_guard="on",
+            subject_count_guard="auto",
+            ref_1=helper_result[4],
+            ref_2=helper_result[5],
+        )
+
+        self.assertIs(result[1], image1)
+        self.assertIs(result[2], image2)
+        self.assertEqual(result[10], 2)
+        self.assertIn("Character facts for <Picture 1> Dave", result[0])
+        self.assertIn("41 years old", result[0])
+        self.assertIn("6 foot 2 tall", result[0])
+        self.assertIn("exactly one named character: <Picture 1> Dave", result[0])
+        self.assertNotIn("exactly 2 named characters", result[0])
+
+    def test_h3_prompt_curator_uses_location_helper_references_by_name(self):
+        helper = self.image_nodes.DumasLocationHelperNode()
+        curator = self.image_nodes.DumasH3PromptCuratorNode()
+        image1 = FakeTensorBatch()
+        image2 = FakeTensorBatch()
+        helper_result = helper.build_location_text(
+            image1=image1,
+            image2=image2,
+            image1_picture_id="1",
+            image2_picture_id="2",
+            location_id="coffee_shop",
+            name="Coffee Shop",
+            alias="Cafe Interior",
+            description="Warm tungsten lighting, narrow counter, rainy front window",
+            general="Evening ambience, cramped but cozy",
+        )
+
+        result = curator.curate_prompt(
+            action_prompt="A slow push through the Coffee Shop as rain streaks the windows.",
+            anatomy_guard="on",
+            subject_count_guard="auto",
+            ref_1=helper_result[3],
+            ref_2=helper_result[4],
+        )
+
+        self.assertIs(result[1], image1)
+        self.assertIs(result[2], image2)
+        self.assertEqual(result[10], 2)
+        self.assertIn("<Picture 1> Coffee Shop", result[0])
+        self.assertIn("<Picture 2> Coffee Shop", result[0])
+        self.assertIn("Location context for <Picture 1> Coffee Shop", result[0])
+        self.assertIn("Warm tungsten lighting", result[0])
+        self.assertNotIn("Subject count guard:", result[0])
+
+    def test_h3_prompt_curator_defaults_anatomy_guard_to_on(self):
+        required = self.image_nodes.DumasH3PromptCuratorNode.INPUT_TYPES()["required"]
+
+        self.assertEqual(required["anatomy_guard"][1]["default"], "on")
+
+    def test_helper_node_mappings_use_general_purpose_helpers(self):
+        mappings = self.image_nodes.NODE_CLASS_MAPPINGS
+        display = self.image_nodes.NODE_DISPLAY_NAME_MAPPINGS
+
+        self.assertIs(mappings["DumasCharacterHelper"], self.image_nodes.DumasCharacterHelperNode)
+        self.assertIs(mappings["DumasLocationHelper"], self.image_nodes.DumasLocationHelperNode)
+        self.assertIs(mappings["DumasSoundscapeHelper"], self.image_nodes.DumasSoundscapeHelperNode)
+        self.assertIs(mappings["DumasH3PromptCurator"], self.image_nodes.DumasH3PromptCuratorNode)
+        self.assertEqual(display["DumasCharacterHelper"], "Dumas Character Helper")
+        self.assertEqual(display["DumasLocationHelper"], "Dumas Location Helper")
+        self.assertEqual(display["DumasSoundscapeHelper"], "Dumas Soundscape Helper")
+        self.assertEqual(display["DumasH3PromptCurator"], "Dumas H3 Prompt Curator")
+
+    def test_h3_prompt_curator_uses_documented_reference_limits(self):
+        node = self.image_nodes.DumasH3PromptCuratorNode()
+        self.assertEqual(len(node.RETURN_TYPES), 12)
+        self.assertEqual(node.RETURN_NAMES[1:10], tuple(f"ref_image_{i}" for i in range(1, 10)))
+
     def test_normalize_reference_upgrades_generic_summary_with_socket_picture_id(self):
         image = FakeTensorBatch()