Bypass learned latent upscaler on low VRAM

This reverts commit 00985b73b3.

README.md

@@ -38,12 +38,19 @@
   - Outputs: `images`, `audio`, `info`, `script`, `frames_per_shot`, `total_frames`, `shots`, `video_seconds`, `fps`, `fps_int`, `latent`, `soundscape`
   - First-pass Dumas port of the `MiniMax-H3-Longvideos` sampler, brought in as a local starting point for long-form H3 chaining work.
   - Keeps the upstream split-beats / handoff / ref-routing behavior close to source so future Dumas-specific improvements can be compared against a known baseline.
+  - Full user guide: [`H3_LONG_VIDEOS_GUIDE.md`](./H3_LONG_VIDEOS_GUIDE.md)
   - Only the canonical `DumasH3LongVideos` node key is exposed now; the older FL2VA/REF2VA alias entries are no longer duplicated in the Add Node menu.
   - 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`
@@ -60,12 +67,12 @@
   - Reports the detected H3 base precision / quant format and the relevant compute-capability hints for the current card.
 
 - `Dumas Character Reference`
-  - Inputs: `image`, `picture_id`, `character_id`, `name`, `alias`, `gender`, `age`, `nationality`, `occupation`, `height_feet`, `height_inches`, `accent`, `description`, `general`, `wardrobe`
+  - Inputs: `image`, `character_id`, `name`, `alias`, `gender`, `age`, `nationality`, `occupation`, `height_feet`, `height_inches`, `accent`, `description`, `general`, `wardrobe`
   - Output: `reference`
   - Builds one structured `REFERENCE` object carrying the conditioning image, identity description, wardrobe, general notes, and simple facts together.
 
 - `Dumas Location Reference`
-  - Inputs: `image`, `picture_id`, `location_id`, `name`, `alias`, `description`, `general`
+  - Inputs: `image`, `location_id`, `name`, `alias`, `description`, `general`
   - 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.
 

REFERENCE_SYSTEM_SPEC.md

@@ -119,8 +119,10 @@ For locations:
   - Optional list of alternate match names.
 
 - `picture_id`
-  - Optional integer representing the intended `<Picture N>` identity.
-  - This is authoring metadata, not the final socket position.
+  - Optional integer representing the effective `<Picture N>` identity.
+  - It is inferred by consumer nodes such as `Dumas H3 Long Videos` from the
+    connected socket position when that position is known.
+  - Producer nodes do not need a manual `picture_id` input.
 
 - `picture_label`
   - Derived convenience text like `<Picture 1>`.
@@ -167,7 +169,6 @@ Recommended name:
 Inputs:
 
 - `image`
-- `picture_id`
 - `character_id`
 - `name`
 - `alias`
@@ -202,7 +203,6 @@ Recommended name:
 Inputs:
 
 - `image`
-- `picture_id`
 - `location_id`
 - `name`
 - `alias`
@@ -383,4 +383,3 @@ That is the change that removes the current ambiguity between:
 - character identity
 - wardrobe data
 - location / environment description
-

__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_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

@@ -26,10 +26,7 @@ _H3_PLAN_IMAGE_BINDINGS = OrderedDict()
 _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 = (
-    " Keep this anchor focused on persistent camera language, lighting, texture, environment treatment, and tone; "
-    "do not name characters or describe one-off actions."
-)
+_ANCHOR_STYLE_H3_NOTE = ""
 _ANCHOR_STYLE_PRESETS = OrderedDict(
     [
         (
@@ -889,6 +886,8 @@ def normalize_reference(value, picture_id=None, allow_image_fallback=True):
         if image is None and allow_image_fallback:
             image = value
         reference["image"] = image
+        existing_picture_id = _coerce_picture_id(reference.get("picture_id"))
+        previous_summary = _ensure_sentence(reference.get("summary") or "")
         if picture_id is not None and not reference.get("picture_id"):
             reference["picture_id"] = _coerce_picture_id(picture_id)
         reference["picture_label"] = _reference_label(reference.get("picture_id"))
@@ -896,10 +895,16 @@ def normalize_reference(value, picture_id=None, allow_image_fallback=True):
         reference.setdefault("id", _reference_id("", reference.get("name"), reference["kind"]))
         reference.setdefault("name", "")
         reference["aliases"] = _parse_aliases(reference.get("aliases"))
-        reference["summary"] = _ensure_sentence(
-            reference.get("summary")
-            or _reference_summary(reference["kind"], reference.get("name"), reference.get("picture_id"))
+        auto_summary_before = _ensure_sentence(
+            _reference_summary(reference["kind"], reference.get("name"), existing_picture_id)
         )
+        auto_summary_after = _ensure_sentence(
+            _reference_summary(reference["kind"], reference.get("name"), reference.get("picture_id"))
+        )
+        if not previous_summary or previous_summary == auto_summary_before:
+            reference["summary"] = auto_summary_after
+        else:
+            reference["summary"] = previous_summary
         reference["description"] = _normalize_free_text(reference.get("description"))
         reference["wardrobe"] = _normalize_free_text(reference.get("wardrobe"))
         reference["general"] = _normalize_free_text(reference.get("general"))
@@ -1614,13 +1619,6 @@ class DumasCharacterReferenceNode:
         return {
             "required": {
                 "image": ("IMAGE", {"tooltip": "Character reference image."}),
-                "picture_id": (
-                    ["1", "2", "3", "4", "5", "6", "7", "8", "9"],
-                    {
-                        "default": "1",
-                        "tooltip": "Authoring picture number for this reference.",
-                    },
-                ),
                 "character_id": (
                     "STRING",
                     {
@@ -1729,7 +1727,6 @@ class DumasCharacterReferenceNode:
     def build_reference(
         self,
         image,
-        picture_id,
         character_id,
         name,
         alias,
@@ -1750,7 +1747,6 @@ class DumasCharacterReferenceNode:
             explicit_id=character_id,
             name=name,
             aliases=alias,
-            picture_id=picture_id,
             description=description,
             wardrobe=wardrobe,
             general=general,
@@ -1782,13 +1778,6 @@ class DumasLocationReferenceNode:
         return {
             "required": {
                 "image": ("IMAGE", {"tooltip": "Location or environment reference image."}),
-                "picture_id": (
-                    ["1", "2", "3", "4", "5", "6", "7", "8", "9"],
-                    {
-                        "default": "1",
-                        "tooltip": "Authoring picture number for this reference.",
-                    },
-                ),
                 "location_id": (
                     "STRING",
                     {
@@ -1832,7 +1821,7 @@ class DumasLocationReferenceNode:
             }
         }
 
-    def build_reference(self, image, picture_id, location_id, name, alias, description, general):
+    def build_reference(self, image, location_id, name, alias, description, general):
         return (
             make_reference(
                 kind="location",
@@ -1840,7 +1829,6 @@ class DumasLocationReferenceNode:
                 explicit_id=location_id,
                 name=name,
                 aliases=alias,
-                picture_id=picture_id,
                 description=description,
                 general=general,
                 facts={},

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

@@ -0,0 +1,375 @@
+import { app } from "/scripts/app.js";
+import { applyAdaptiveCanvasOnly } from "../shared/nodes2.mjs";
+
+const COMFY_CLASS = "DumasH3LongVideos";
+const STATE_PROPERTY = "dumas_h3_longvideos_section_state";
+const DOM_WIDGET_NAME = "dumas_h3_longvideos_sections";
+const MIN_WIDTH = 520;
+const MIN_HEIGHT = 280;
+
+const GROUPS = [
+  {
+    id: "prompt",
+    label: "Prompt",
+    defaultCollapsed: false,
+    widgets: ["prompt", "resolution", "megapixels", "beat_split", "anchor_override", "shot_seconds", "plan_only", "fps"],
+  },
+  {
+    id: "refs",
+    label: "Refs",
+    defaultCollapsed: true,
+    widgets: ["ref_mode", "ref_image_size", "ref_noise_aug", "character_memory", "trim_seam", "vary_seed_per_shot", "handoff_offset"],
+  },
+  {
+    id: "sampling",
+    label: "Sampling",
+    defaultCollapsed: true,
+    widgets: [
+      "steps", "cfg", "sampler_name", "scheduler", "seed",
+      "apply_model_sampling", "shift_video", "shift_audio",
+      "vram_headroom_gb", "allow_res_backoff",
+      "decode_tile_frames", "decode_tile_size",
+    ],
+  },
+  {
+    id: "audio",
+    label: "Audio",
+    defaultCollapsed: true,
+    widgets: [
+      "global_soundscape", "non_diegetic_music", "auto_soundscape",
+      "auto_silence_nonspeech", "allow_nonspeech_vocals",
+      "mute_nonspeech_audio", "mute_fade_ms",
+    ],
+  },
+  {
+    id: "scene",
+    label: "Scene Logic",
+    defaultCollapsed: true,
+    widgets: [
+      "auto_wardrobe", "auto_props", "prevent_nudity", "exposed_terms",
+      "anatomy_guard", "subject_count_guard", "lock_restraints",
+      "contact_guard", "motion_guard", "solidity_guard",
+    ],
+  },
+  {
+    id: "finish",
+    label: "Upscale",
+    defaultCollapsed: true,
+    widgets: [
+      "upscale", "upscale_model", "upscale_target_short_edge", "upscale_batch",
+    ],
+  },
+  {
+    id: "overlay",
+    label: "Overlays",
+    defaultCollapsed: true,
+    widgets: [
+      "watermark_text", "watermark_position", "watermark_size", "watermark_opacity", "watermark_margin",
+      "intro_text", "intro_position", "intro_seconds", "intro_fade", "intro_size",
+      "overlay_font", "overlay_stroke",
+    ],
+  },
+];
+
+function injectCSS() {
+  if (document.getElementById("dumas-h3lv-sections-css")) return;
+  const style = document.createElement("style");
+  style.id = "dumas-h3lv-sections-css";
+  style.textContent = `
+    .dh3lv-sections {
+      box-sizing: border-box;
+      width: 100%;
+      padding: 8px 10px 6px;
+      color: #e6e7eb;
+      font: 12px/1.35 "Segoe UI", sans-serif;
+      pointer-events: auto;
+      background: linear-gradient(180deg, rgba(33, 36, 42, 0.96), rgba(22, 24, 29, 0.96));
+      border-bottom: 1px solid rgba(255, 255, 255, 0.06);
+    }
+    .dh3lv-sections-head {
+      display: flex;
+      align-items: center;
+      justify-content: space-between;
+      gap: 8px;
+      margin-bottom: 8px;
+    }
+    .dh3lv-sections-title {
+      font-size: 11px;
+      text-transform: uppercase;
+      letter-spacing: 0.08em;
+      color: #9da5b1;
+    }
+    .dh3lv-sections-actions {
+      display: flex;
+      gap: 6px;
+    }
+    .dh3lv-sections-list {
+      display: flex;
+      flex-wrap: wrap;
+      gap: 6px;
+    }
+    .dh3lv-chip,
+    .dh3lv-action {
+      appearance: none;
+      border: 1px solid #464d59;
+      background: #262c35;
+      color: #d7dce3;
+      border-radius: 999px;
+      padding: 5px 9px;
+      cursor: pointer;
+      font: inherit;
+      line-height: 1.1;
+    }
+    .dh3lv-chip[data-open="true"] {
+      background: #d96f2b;
+      border-color: #f09358;
+      color: #fff7f0;
+    }
+    .dh3lv-chip:hover,
+    .dh3lv-action:hover {
+      filter: brightness(1.06);
+    }
+    .dh3lv-count {
+      opacity: 0.78;
+      margin-left: 4px;
+      font-size: 11px;
+    }
+  `;
+  document.head.appendChild(style);
+}
+
+function defaultState() {
+  const state = {};
+  for (const group of GROUPS) state[group.id] = !group.defaultCollapsed;
+  return state;
+}
+
+function parseState(value) {
+  let parsed = value;
+  if (typeof parsed === "string") {
+    try {
+      parsed = JSON.parse(parsed);
+    } catch (_error) {
+      parsed = null;
+    }
+  }
+  const base = defaultState();
+  if (!parsed || typeof parsed !== "object") return base;
+  for (const group of GROUPS) {
+    if (typeof parsed[group.id] === "boolean") base[group.id] = parsed[group.id];
+  }
+  return base;
+}
+
+function readState(node) {
+  return parseState(node.properties?.[STATE_PROPERTY] || node._dh3lvSectionState || "");
+}
+
+function writeState(node, state) {
+  const normalized = parseState(state);
+  const serialized = JSON.stringify(normalized);
+  node._dh3lvSectionState = serialized;
+  node.properties = node.properties || {};
+  node.properties[STATE_PROPERTY] = serialized;
+}
+
+function findWidget(node, name) {
+  return (node.widgets || []).find((widget) => widget?.name === name) || null;
+}
+
+function isInteractiveTarget(target) {
+  return !!target?.closest?.("button, input, textarea, select, label");
+}
+
+function stopCanvasEvent(event) {
+  if (isInteractiveTarget(event.target)) event.stopPropagation();
+}
+
+function stopCanvasKeyboard(event) {
+  if (isInteractiveTarget(event.target)) event.stopImmediatePropagation();
+}
+
+function setWidgetHidden(widget, hidden) {
+  if (!widget) return;
+  if (!widget._dh3lvOriginal) {
+    widget._dh3lvOriginal = {
+      type: widget.type,
+      computeSize: widget.computeSize,
+      hidden: widget.hidden,
+    };
+  }
+  if (hidden) {
+    widget.type = "hidden";
+    widget.hidden = true;
+    widget.computeSize = () => [0, -4];
+    return;
+  }
+  widget.type = widget._dh3lvOriginal.type;
+  widget.hidden = !!widget._dh3lvOriginal.hidden;
+  widget.computeSize = widget._dh3lvOriginal.computeSize;
+}
+
+function applyVisibility(node) {
+  const state = readState(node);
+  for (const group of GROUPS) {
+    for (const name of group.widgets) {
+      const widget = findWidget(node, name);
+      if (!widget || widget.name === DOM_WIDGET_NAME) continue;
+      setWidgetHidden(widget, !state[group.id]);
+    }
+  }
+}
+
+function resizeNode(node) {
+  requestAnimationFrame(() => {
+    const size = node.computeSize?.();
+    if (Array.isArray(size)) {
+      node.size[0] = Math.max(MIN_WIDTH, size[0] || 0, node.size?.[0] || 0);
+      node.size[1] = Math.max(MIN_HEIGHT, size[1] || 0);
+    }
+    node.setDirtyCanvas?.(true, true);
+  });
+}
+
+function renderToolbar(node) {
+  const ui = node._dh3lvUI;
+  if (!ui) return;
+  const state = readState(node);
+  ui.list.innerHTML = "";
+  for (const group of GROUPS) {
+    const button = document.createElement("button");
+    button.type = "button";
+    button.className = "dh3lv-chip";
+    button.dataset.open = state[group.id] ? "true" : "false";
+    button.textContent = state[group.id] ? `Hide ${group.label}` : `Show ${group.label}`;
+
+    const count = document.createElement("span");
+    count.className = "dh3lv-count";
+    count.textContent = String(group.widgets.filter((name) => findWidget(node, name)).length);
+    button.appendChild(count);
+
+    button.addEventListener("click", () => {
+      const next = readState(node);
+      next[group.id] = !next[group.id];
+      writeState(node, next);
+      applyVisibility(node);
+      renderToolbar(node);
+      resizeNode(node);
+    });
+    ui.list.appendChild(button);
+  }
+}
+
+function setAll(node, open) {
+  const next = {};
+  for (const group of GROUPS) next[group.id] = !!open;
+  writeState(node, next);
+  applyVisibility(node);
+  renderToolbar(node);
+  resizeNode(node);
+}
+
+function setupNode(node) {
+  if (node._dh3lvUI) return;
+  injectCSS();
+  writeState(node, readState(node));
+
+  const root = document.createElement("div");
+  root.className = "dh3lv-sections";
+
+  const head = document.createElement("div");
+  head.className = "dh3lv-sections-head";
+
+  const title = document.createElement("div");
+  title.className = "dh3lv-sections-title";
+  title.textContent = "Sections";
+
+  const actions = document.createElement("div");
+  actions.className = "dh3lv-sections-actions";
+
+  const expandAll = document.createElement("button");
+  expandAll.type = "button";
+  expandAll.className = "dh3lv-action";
+  expandAll.textContent = "Expand All";
+  expandAll.addEventListener("click", () => setAll(node, true));
+
+  const collapseAll = document.createElement("button");
+  collapseAll.type = "button";
+  collapseAll.className = "dh3lv-action";
+  collapseAll.textContent = "Collapse Extras";
+  collapseAll.addEventListener("click", () => {
+    const next = defaultState();
+    writeState(node, next);
+    applyVisibility(node);
+    renderToolbar(node);
+    resizeNode(node);
+  });
+
+  actions.append(expandAll, collapseAll);
+  head.append(title, actions);
+
+  const list = document.createElement("div");
+  list.className = "dh3lv-sections-list";
+  root.append(head, list);
+  root.addEventListener("pointerdown", stopCanvasEvent);
+  root.addEventListener("mousedown", stopCanvasEvent);
+  root.addEventListener("click", stopCanvasEvent);
+  root.addEventListener("dblclick", stopCanvasEvent);
+  root.addEventListener("keydown", stopCanvasKeyboard, true);
+
+  node._dh3lvUI = { root, list };
+  const widget = node.addDOMWidget(DOM_WIDGET_NAME, "custom", root, {
+    getValue: () => null,
+    setValue: () => {},
+    serialize: false,
+    getMinHeight: () => 52,
+    hideOnZoom: false,
+  });
+  applyAdaptiveCanvasOnly(widget);
+  const widgets = node.widgets || [];
+  const index = widgets.indexOf(widget);
+  if (index > 0) {
+    widgets.splice(index, 1);
+    widgets.unshift(widget);
+  }
+
+  applyVisibility(node);
+  renderToolbar(node);
+  resizeNode(node);
+}
+
+app.registerExtension({
+  name: "Dumas.H3LongVideosSections",
+  async beforeRegisterNodeDef(nodeType, nodeData) {
+    if (nodeData?.name !== COMFY_CLASS) return;
+
+    const originalOnNodeCreated = nodeType.prototype.onNodeCreated;
+    nodeType.prototype.onNodeCreated = function onNodeCreated() {
+      const result = originalOnNodeCreated?.apply(this, arguments);
+      setupNode(this);
+      return result;
+    };
+
+    const originalConfigure = nodeType.prototype.onConfigure;
+    nodeType.prototype.onConfigure = function onConfigure() {
+      const result = originalConfigure?.apply(this, arguments);
+      setupNode(this);
+      writeState(this, readState(this));
+      applyVisibility(this);
+      renderToolbar(this);
+      resizeNode(this);
+      return result;
+    };
+
+    const originalSerialize = nodeType.prototype.onSerialize;
+    nodeType.prototype.onSerialize = function onSerialize(o) {
+      writeState(this, readState(this));
+      const result = originalSerialize?.apply(this, arguments);
+      if (o && this.properties?.[STATE_PROPERTY]) {
+        o.properties = o.properties || {};
+        o.properties[STATE_PROPERTY] = this.properties[STATE_PROPERTY];
+      }
+      return result;
+    };
+  },
+});

pyproject.toml

@@ -1,7 +1,7 @@
 [project]
 name = "dumasnodes"
 description = "Dumas-branded generic utility nodes for ComfyUI, starting with JSON helpers."
-version = "0.1.0"
+version = "0.1.1"
 license = { file = "LICENSE" }
 
 [project.urls]

tests/test_dumas_image_nodes.py

@@ -245,7 +245,6 @@ class DumasImageNodeTests(unittest.TestCase):
 
         result = node.build_reference(
             image=image,
-            picture_id="2",
             character_id="char_dave",
             name="Dave",
             alias="The Locksmith",
@@ -270,10 +269,10 @@ class DumasImageNodeTests(unittest.TestCase):
                 "id": "char-dave",
                 "name": "Dave",
                 "aliases": ["The Locksmith"],
-                "picture_id": 2,
-                "picture_label": "<Picture 2>",
+                "picture_id": None,
+                "picture_label": "",
                 "image": image,
-                "summary": "Dave shown in <Picture 2>.",
+                "summary": "Dave reference.",
                 "description": "Square jaw, tired eyes, cropped brown hair.",
                 "wardrobe": "weathered red flight jacket, grey cargo shorts, black boots",
                 "general": "wears a long grey coat",
@@ -289,13 +288,16 @@ class DumasImageNodeTests(unittest.TestCase):
             },
         )
 
+    def test_character_reference_input_types_do_not_expose_picture_id(self):
+        required = self.image_nodes.DumasCharacterReferenceNode.INPUT_TYPES()["required"]
+        self.assertNotIn("picture_id", required)
+
     def test_character_reference_handles_missing_optional_fields(self):
         node = self.image_nodes.DumasCharacterReferenceNode()
         image = FakeTensorBatch()
 
         result = node.build_reference(
             image=image,
-            picture_id="4",
             character_id="",
             name="",
             alias="",
@@ -313,8 +315,8 @@ class DumasImageNodeTests(unittest.TestCase):
 
         reference = result[0]
         self.assertEqual(reference["kind"], "character")
-        self.assertEqual(reference["picture_id"], 4)
-        self.assertEqual(reference["picture_label"], "<Picture 4>")
+        self.assertIsNone(reference["picture_id"])
+        self.assertEqual(reference["picture_label"], "")
         self.assertEqual(reference["wardrobe"], "")
         self.assertEqual(reference["general"], "")
         self.assertEqual(reference["facts"]["age"], "")
@@ -325,7 +327,6 @@ class DumasImageNodeTests(unittest.TestCase):
 
         result = node.build_reference(
             image=image,
-            picture_id="9",
             location_id="coffee-shop-01",
             name="Coffee Shop",
             alias="Cafe Interior",
@@ -340,10 +341,10 @@ class DumasImageNodeTests(unittest.TestCase):
                 "id": "coffee-shop-01",
                 "name": "Coffee Shop",
                 "aliases": ["Cafe Interior"],
-                "picture_id": 9,
-                "picture_label": "<Picture 9>",
+                "picture_id": None,
+                "picture_label": "",
                 "image": image,
-                "summary": "Coffee Shop shown in <Picture 9>.",
+                "summary": "Coffee Shop reference.",
                 "description": "Warm tungsten lighting, narrow counter, rainy front window.",
                 "wardrobe": "",
                 "general": "Evening ambience, cramped but cozy.",
@@ -351,6 +352,45 @@ class DumasImageNodeTests(unittest.TestCase):
             },
         )
 
+    def test_location_reference_input_types_do_not_expose_picture_id(self):
+        required = self.image_nodes.DumasLocationReferenceNode.INPUT_TYPES()["required"]
+        self.assertNotIn("picture_id", required)
+
+    def test_normalize_reference_upgrades_generic_summary_with_socket_picture_id(self):
+        image = FakeTensorBatch()
+
+        reference = self.image_nodes.normalize_reference(
+            {
+                "kind": "character",
+                "name": "Dave",
+                "image": image,
+                "summary": "Dave reference.",
+            },
+            picture_id=3,
+            allow_image_fallback=False,
+        )
+
+        self.assertEqual(reference["picture_id"], 3)
+        self.assertEqual(reference["picture_label"], "<Picture 3>")
+        self.assertEqual(reference["summary"], "Dave shown in <Picture 3>.")
+
+    def test_normalize_reference_keeps_custom_summary_when_socket_picture_id_is_added(self):
+        image = FakeTensorBatch()
+
+        reference = self.image_nodes.normalize_reference(
+            {
+                "kind": "character",
+                "name": "Dave",
+                "image": image,
+                "summary": "Primary hero look for the opening close-up.",
+            },
+            picture_id=3,
+            allow_image_fallback=False,
+        )
+
+        self.assertEqual(reference["picture_id"], 3)
+        self.assertEqual(reference["summary"], "Primary hero look for the opening close-up.")
+
     def test_anchor_style_node_exposes_requested_presets(self):
         input_types = self.image_nodes.DumasAnchorStyleNode.INPUT_TYPES()
         options = input_types["required"]["anchor_style"][0]
@@ -375,7 +415,7 @@ class DumasImageNodeTests(unittest.TestCase):
 
         self.assertIn("found-footage", result[0])
         self.assertIn("real time", result[0])
-        self.assertIn("persistent camera language", result[0])
+        self.assertNotIn("persistent camera language", result[0])
 
     def test_anchor_style_node_prefers_manual_description_edits(self):
         node = self.image_nodes.DumasAnchorStyleNode()