Hand Tie Clips 0.3.3

ComfyUI node pack for MiniMax H3 Reference-to-Video. Chains several
generations into one continuous clip with held identity across hops.

First commit of an existing pack. Until now every edit was guarded by a
.bak sibling -- 89 of them accumulated -- which is what this replaces.
Those files stay on disk and are gitignored rather than deleted.

Contents: the four nodes, the on-node editor, the shot_plan / ref_plan
authoring format, the prompt pack for getting a local model to write
plans, two example workflows, and CLAUDE.md -- the engineering log of
what the model actually does, which is where most of the authoring rules
come from.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_015MGjcAV8bDy93qJfmLi9kw

.gitattributes

@@ -0,0 +1,11 @@
+# Every source file in this pack is written LF. Without this, a clone on
+# Windows checks out CRLF and the next commit shows every line of every file
+# as changed -- which would bury real diffs in a pack whose whole value is
+# being able to see what changed between renders.
+* text=auto eol=lf
+
+# Keep binary-ish assets out of the text pipeline.
+*.png binary
+*.jpg binary
+*.mp4 binary
+*.safetensors binary

.gitignore

@@ -0,0 +1,7 @@
+__pycache__/
+*.py[cod]
+
+# Every source in this pack has .bak siblings -- the reflex that stands in for
+# version control here. They are working files, not releases.
+*.bak
+*.bak*

CLAUDE.md

@@ -0,0 +1,1020 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## What this is
+
+`ComfyUI-Hand-Tie-Clips` chains multiple MiniMax H3 Reference-to-Video generates into one longer clip. Each hop after the first is guided by the previous hop's last overlap frames + audio via stock `MiniMaxH3AddGuide` (requires a ComfyUI build with `MiniMaxH3AddGuide`, ComfyUI PR #15439). It is explicitly **not** the H3-Multishot/airlock pack; do not merge that pack's syntax in here.
+
+Two nodes ship: `HandTieClips` (**H3 Ref2VA Chain**, the whole pipeline) and `HTCContinuityState` (legacy continuity text, superseded — see below).
+
+It lives inside a full ComfyUI checkout (`D:\ComfyUI\custom_nodes\ComfyUI-Hand-Tie-Clips`) and imports directly from ComfyUI internals (`comfy.model_management`, `comfy.samplers`, `comfy.utils`, `comfy_extras.nodes_minimax_h3`, `comfy_extras.nodes_custom_sampler`, `comfy_extras.nodes_audio`, `nodes`, `folder_paths`). It only runs as a loaded custom node inside that ComfyUI instance — there is no standalone entrypoint, package manager, or test harness.
+
+## The target sampling regime
+
+**Turbo LoRA at 4-8 steps.** That is what the node is built for and what the shipped workflow uses (8 steps, `minimax_h3_ref2v_turbo_4step`). High-step runs (14+) are diagnostic instruments to check whether an effect exists at all; **any change must be re-validated at 8 steps before it counts as working**, because at low step counts seed structure dominates and can swamp conditioning differences. Never report a 14-step result as validation on its own.
+
+## Development workflow
+
+No build step, linter config, or test suite (`pyproject.toml` declares zero dependencies beyond ComfyUI). The dev loop is:
+
+- **Python changes**: restart ComfyUI to reload the node.
+- **JS changes** (anything under `js/`): hard-refresh the ComfyUI browser tab.
+- Validate by loading `workflows/HandTieClips_Starter.json` and queuing a run. Two signals:
+  - the `[HandTieClips]`-prefixed console lines (hop count, shot plan table, reference register table, model-patch log, cache hits, overlap drop, final frame/duration summary);
+  - the node's third output, **`info`**, which carries the fully assembled per-hop prompts. Wire it to a Preview Text node to read exactly what each hop sent to the text encoder. The editor shows what you wrote; `info` shows what the compiler made of it, which is not the same thing.
+
+## Architecture
+
+Python modules feed four nodes, plus a DOM editor in `js/`. `h3_ref_chain.py` holds `HandTieClips.run()` and the prompt-assembly helpers; `plan.py`, `directives.py`, `refs.py`, `store.py` and `tone.py` are parsers, compilers and estimators with no ComfyUI imports in their math, which is what makes them testable outside a running server. `routes.py` serves the editor its vocabulary. `preview_node.py` and `tone.py` each register a standalone side node.
+
+### Two independent reference channels — do not conflate them
+
+The core invariant, and the thing most likely to be broken by a careless change:
+
+1. **References** (files in `<ComfyUI input>/h3_refs`, named by each ref's `file`) → bound into the tokenizer as `<Picture 1..N>` *and* into the DiT as `minimax_refs`. Identity/place stills. On `hop_script=next`, they ride **hop 1** unless a ref's `shots` lists later hops. They are never the join pin. Riding a face/outfit plate of a different room on hop 2+ opens a new Ref2VA generate (chain_00030..00034: commercial-kitchen face+outfit beat the residential pin; hop 2 dropped the apron).
+2. **The AddGuide pin** (`MiniMaxH3AddGuide.execute`, once per hop after 0) → DiT `minimax_keyframes` at t=0 only. **The text encoder never sees this pin.** The master throws the overlapped frames away after decode.
+
+`pin_to_qwen` (`_attach_pin_to_qwen`) optionally makes the *text encoder* aware of the incoming state, since channel 2 is otherwise invisible to it: `last frame` is **`<Picture 1>`** of the previous hop's last frame (identity stills that still ride shift to Picture 2+), `pin clip` appends the overlap frames as an extra `<Video>` (~2 fps, no audio), `both` does both, `off` neither. Additive to channel 1's slots (max 9 images / 3 videos). **`last frame` is the default and stays that way.** Appending the pin after the stills made it Picture 4 against three stills (chain_00034).
+
+**DiT pin (hop 2+):** keep the previous hop’s **sampler AV latent** and call `MiniMaxH3MotionContext` (already installed) with `context_length` matching overlap (22) and `audio_context_length=24`. That is the Multishot `context_pin` path: no pixel VAE round trip, audio end-aligned on this clip’s timeline. If the node is missing, fall back to `MiniMaxH3AddGuide` on decoded frames and log it. A cache hit no longer forces that fallback: the sampler latent is stored beside the frames and restored on a hit (see the hop store below). Hop 1 `start_image` still uses AddGuide.
+
+**5 s is not a join-validation canvas.** Multishot: 124 f drops the airlock. `00028` 1→2 joined at 8 s. Verify after this pass is 2 × **8 s**. `join=continuous` at 5 s logs a note. A different seed on the 5 s pin-only graph did join (not a strict pass) — 777777 was join-hostile; `seed_per_shot` stays ON. Seed is not a substitute for the latent pin or an 8 s airlock budget.
+
+### 1. Shot plan (`plan.py`)
+
+A plan is one JSON string in the `shot_plan` widget: an ordered list of shots, one per hop. **The shot count IS the hop count**, which removes the whole class of "3 blocks but chains=4" mismatches — when `shot_plan` is non-empty it is authoritative, `hop_script` is forced to `next`, and `chains` is ignored with a log line (`h3_ref_chain.py`, `run()`; search `shot_plan present -> hop_script=next`).
+
+Shot fields (all optional except `beat`): `beat`, `directives`, `prose`, `seed`, `steps`, `duration`, `locked`, `id`. There is no shot-level `refs` field -- a reference activates itself through its own `shots` list in `ref_plan`, and the shot-level one was removed 2026-08-27 (parsed and printed, read by nothing, and silently dropped by the editor). Per-shot `seed`/`steps`/`duration` really are per-shot — sigmas are built per distinct step count behind `sigma_cache` and durations are validated up front so a bad value fails before any sampling.
+
+**`refs` on a shot is parsed and printed but not consumed.** Ref activation comes only from each ref's own `shots` field in `refs.py`. The editor deliberately does not expose it, so nothing implies it works. Either wire it up or drop the field.
+
+`prompt` is the legacy path, read only when `shot_plan` is empty (`_parse_shots`/`_expand_shots` + `hop_script=verbatim|next`).
+
+### 2. Directive compiler (`directives.py`) — the differentiator
+
+`join` / `camera` / `framing` / `pace` / `tail` compile to vetted prose from `VOCAB`, so improving a phrase improves every existing plan at once. `join` is skipped on hop 0, which has nothing to join to; `tail` is the only axis with a default (`ongoing`).
+
+**Phrasing rules — read before editing VOCAB:**
+
+1. **AFFIRMATIVE ONLY.** Sampling runs through `BasicGuider` at cfg 1.0 with no negative branch, so every concept named is additive and cannot be subtracted. "no cut" puts `cut` in front of the encoder. This is not a style preference — it is the load-bearing finding the whole rework was built on.
+2. **NO PRONOUNS.** The beat text owns the subject; plural "they" has been observed rendering two people from one reference.
+3. **NO ENUMERATED DETAIL.** Naming a prop or garment to control it adds it. Directives cover camera, join, framing, pace, tail only.
+4. **ONE SENTENCE PER ENTRY.** These get concatenated; long entries crowd the beat.
+
+`check_coherence` warns (never raises) when `join=continuous` is asked for alongside a framing change with a held camera — that combination implies a cut, so the model picks one.
+
+### 3. Reference register (`refs.py`)
+
+Fixes two real bugs:
+
+- **Ordinal instability.** Core assigns `<Picture N>` 1-based in list order (`comfy/text_encoders/minimax.py:148-202`) and refs are dense-packed, so unplugging a `Load Image` silently renumbers every later one, and any prompt naming a literal ordinal then points at the wrong picture. Here each ref carries a stable `@tag` and a **filename**; ordinals are **derived per hop** and `resolve_tags` rewrites the prose.
+- **Subject collapse.** Declaring every picture as a photo of `<Subject 1>` makes the model render the average of two different people. `subject` numbers group pictures per person; `retention` (`fully_preserved` / `partially_copy` / `reference`) generates the carry-over prose.
+
+`run()` keeps a raw `slot -> tensor` map *before* `_collect_ref_images` dense-packs it, because a `@tag` is pinned to one picture. Since 2026-08-28 `slot` is **derived from the ref's position in the rail**, not authored — it is an ordering index, not a socket number. The image dict and the cited ordinals are built from the same `hop_active` list, so they cannot drift apart.
+
+**Only subject-bearing refs are identities.** `_identity_lock` takes `identity_ordinals` and `n_subjects` from the register; without them it falls back to "every wired still is an identity", which is right when nothing better is known but wrong the moment a register is wired — it told the encoder a photograph of a kitchen had a face and hairstyle to match exactly, on every hop. `n_subjects` also drives number agreement: two photographs of one person is one identity, and plural phrasing has been observed rendering two people from one reference.
+
+**`HTCContinuityState` was meant to be retired by this and has not been.** It is still registered, still wireable, still parsed (`_parse_state` / `_state_header`). It cannot express two people at all (one `character_id`, one `characters` key) and names people by an arbitrary id while `<Picture N>` is positional, with nothing joining the two — precisely the subject-collapse setup. Prefer `ref_plan`; the `setting_*` half is the only part `ref_plan` does not cover. `run()` warns when both define identity text, but only when a character field actually holds content — the node emits a `characters` entry for its `character_id` even when every field is blank, so the key's presence means nothing.
+
+### 4. Hop store (`store.py`)
+
+Lossless FFV1 (`rgb48le`) video + a float32 `.npy` waveform + a `.latent.pt` sidecar per hop under ComfyUI's temp dir, enabled by `cache_hops`, LRU-evicted above `cache_budget_gb`. **Needs `ffmpeg` on PATH** or it raises.
+
+**The latent sidecar is what makes the cache useful past hop 1** (added 2026-08-27). It stores this hop's sampler output so a hit can seed the *next* hop's Motion-Context pin. Without it, a hit left `prev_sampled` empty, the next hop predicted the AddGuide fallback, and because the mechanism is in the per-hop key that key no longer matched what was on disk -- so **nothing past hop 1 could ever hit, and the hop after a hit was joined by the weaker mechanism.** `cache_hops=on` was measurably worse than off. Verified in-browser: hop 1 hit, hop 2 logged `previous hop has no sampler latent (cache hit); AddGuide pixel pin`, hops 2-3 re-rendered.
+
+The sidecar is optional in both directions: `has()` ignores it, so entries written before this change still hit (returning `latent=None` and the old fallback), and a latent that will not serialise is logged and skipped rather than failing the hop. It is `torch.save`/`torch.load(weights_only=False)` because `samples` is a `comfy.nested_tensor.NestedTensor` -- a plain Python class holding a tensor list, which `weights_only=True` refuses. Cost is ~2.9% of the entry (measured: 8.4 MB against a ~285 MB video at 0.3 MP / 243f). **Verified end to end 2026-08-27:** fresh render 186.9 s writing three sidecars, then a `cache_budget_gb` nudge re-queue at 17.97 s with all three hops logging `loaded from cache`, zero DiT loads, zero SLA passes, and the same `drift -80 ms` as the fresh run. Invalidation confirmed in the same sitting: LoRA strength 0.800 -> 1.000 produced **zero** cache hits and re-rendered every hop, so `_model_fingerprint` does see a strength change.
+
+**The key chains**: each hop's key mixes in the previous hop's key plus a `chain_salt` of everything constant across the run — canvas, sampler, scheduler, shifts, `pin_to_qwen`, tensor digests of every wired ref / voice / reference video / start image, **and `_model_fingerprint`**, because a hop rendered under different LoRAs or a different attention path is not the same hop. The *pin mechanism* is keyed per hop rather than chain-wide (Motion-Context vs the AddGuide fallback produce different frames, and which one runs depends on whether the previous hop was a cache hit). So editing shot 1 correctly invalidates 2..N. That is correct behaviour and must be surfaced in any UI, or it reads as a bug.
+
+**Anti-ratchet levers were dead until 2026-08-27.** `pin_renorm` and `pin_noise` both ran through `_condition_pin_latent`, which called `.std()` on `latent["samples"]` — a `comfy.nested_tensor.NestedTensor`, which has no `.std()`. Every hop logged `pin conditioning skipped (AttributeError(...))` and both widgets did nothing; the line looked like routine noise next to the other per-hop output. `NestedTensor` is a trap to write against: it *does* have `.float()`, `.cpu()` and `.shape`, but `.shape` returns `tensors[0].shape` — the video component's, silently speaking for both — so the noise draw would have been sized to the video and broadcast onto the audio.
+
+Now conditioned **per component** via `_latent_parts` / `_rebuild_latent_samples`, with `anchor_std` a list of one sigma per stream. Per-stream is also the correct semantics, not just the working one: in a synthetic hop-3 case with video inflated 1.60x and audio 2.51x, the per-stream corrections were 0.6365 and 0.3988 — one global scale would have left the audio ~60% hot. Verified offline against the real class; not yet exercised in a render, because both levers ship off.
+
+**Why 16-bit:** a cached hop's last frame becomes the next hop's Qwen pin and its AddGuide guide, so an 8-bit round trip would make a resumed chain diverge from an uninterrupted one — the cache would change the output, defeating the point.
+
+A shot's `locked` flag pins it to its last render regardless of hash, resolved through `set_pointer`/`get_pointer` keyed on the shot `id` (the content key has moved by definition, so only the pointer can find it).
+
+The master is **preallocated** — `total_frames` is known up front — and slice-written, rather than grown with `torch.cat`, which allocates a fresh full-size tensor every hop while `prev_imgs` and `imgs` are also live. Only the overlap tail stays resident between hops.
+
+### 5. The MODEL wire stays drawn
+
+The speed stack is **four separate nodes in the graph**, not a widget on this one:
+
+    UNETLoader → LTX_lora_loader → H3AdaLNLoRAFix → MiniMaxLowVRAMAttention → H3SLAAttention → HandTieClips
+
+CLIP comes off `LTX_lora_loader`'s second output, not straight from the encoder, or the text-side keys H3 LoRAs carry (`condition_proj`, `token_refiner`) are silently discarded.
+
+A `model_patches` widget that folded all four into this node existed briefly and was **reverted by decision**: it made the graph shorter and the node harder to read, and legibility is the point. Do not re-collapse them. If it ever comes back it belongs behind the editor's advanced section, not as a bare JSON widget.
+
+Note the wire order differs from the pre-rework graph, which ran SLA *before* low-VRAM. SLA's own documentation puts it last; that ordering was researched and is deliberate.
+
+**`_model_fingerprint` exists because of this revert.** With the patches drawn upstream, this node cannot see their settings, so a hop cached under one LoRA stack would be served under another — silently wrong frames. The fingerprint hashes `sorted(model.patches.keys())`, the per-key `strength_patch` / `strength_model` scalars, and the scalar half of `model_options["transformer_options"]`, and that goes into `chain_salt`.
+
+- Patch **values** are tensors and are deliberately not hashed.
+- `model.patches_uuid` is *not* usable: `add_patches` assigns a fresh `uuid4()` on every call, so it would bust the cache every run.
+- **Known collision:** two different LoRAs touching an identical key set at identical strengths fingerprint the same. Rare; the alternative is a full state-dict walk per run.
+
+### Prompt assembly
+
+`hop_script=next` (forced under a shot plan): hop 1's block is the only full prompt; later hops get the new beat plus a live-frame citation. Register `subject_prose` stays off hop 2+ (it is a `subject_definitions` block). Unscheduled stills stay off hop 2+; `@tag` of a person still resolves to `<Subject N>`. `_assemble_next` composes `state_header` ahead of the beat when `HTCContinuityState` is wired.
+
+**Official H3 tags and prompt methods still work here** (user 2026-08-26). This pack is a hop compiler and a join pin, not a new prompt language. Do not invent beat-keywords or pack-specific interpretation (`Silence.` as a spell, “still talking”, “says one short line”, folklore about leftover duration). Use the MiniMax H3 Ref2VA contract the encoder already knows:
+
+- six fields in order: `subject_definitions` / `summary` / `retention_analysis` / `detailed_description` / `overall_soundscape` / `non_diegetic_music`
+- labels `<Subject N>`, `<Picture N>`, `<Video N>`, `<Audio N>`
+- speakers `(S1)` and dialogue `<d>[English] …</d>` (exact words; `<cutoff>` if the line overruns the hop; `<scenetrans>` if a line crosses a join)
+- `[Shot N]` / `At MM:SS.mmm` inside `detailed_description`
+- `overall_soundscape` = ambience + physical + non-verbal only; `N/A` only when the hop is requested silent throughout; do not put dialogue there
+- `non_diegetic_music: N/A` when there is no score
+
+`_is_full_h3_prompt` already detects `subject_definitions:` / `integrated_multimodal_description:` and routes through `_continue_prompt`. A shot-card beat may *be* that official block. Short prose on a card is a convenience path, not a dialect. When a hop is a full H3 prompt, do not wrap it in invented closer sentences that fight the official fields.
+
+Hop 2+ carries **no identity header at all**. `_assemble_next` has no `identity_header` parameter (removed 2026-08-27 along with the dead `_extract_identity_header`/`_section_block` pair). Register `subject_prose` is a `subject_definitions` block, and putting one on hop 2+ made it a second Ref2VA generate -- `chain_00033_`.
+
+### 6. The editor (`js/editor/*`, `routes.py`)
+
+The node is driven by a DOM panel, not by hand-written JSON. Five files:
+
+| file | job |
+|---|---|
+| `js/h3_ref_chain_ui.js` | extension entry, the sample preview, mounts the panel |
+| `js/editor/widget_utils.js` | widget hiding, the height guard, vocab fetch, DOM helpers |
+| `js/editor/plan_editor.js` | Simple/Shots toggle, shot cards, JSON escape hatch |
+| `js/editor/ref_rail.js` | reference register rows and subject blocks |
+| `js/editor/run_panel.js` | the shot-independent dials, grouped (added 2026-08-27) |
+
+**`shot_plan` and `ref_plan` remain the only source of truth.** The panel reads them and writes straight back, so a workflow authored in the editor and one typed by hand are the same file. Never add a parallel store.
+
+**The run panel is the same rendering-layer contract, applied to the native widgets.** Every control writes to `widget.value` and then fires `widget.callback` — that callback is not optional decoration, it is how `control_after_generate` stays bound to `seed`. Four groups (`output`, `sampling`, `join & pin`, `cache`) in `GROUPS`; a name the build does not define is skipped, so the list can carry a widget that only exists on a newer Python side. Four things worth knowing before editing it:
+
+- **Ownership decides hiding, not the group list.** `ownedNames()` reports the widgets the panel actually *drew*, and `applyVisibility` hides exactly those. A dial whose type the panel cannot render therefore stays visible as a native widget instead of vanishing off the node. `sync()` must run **before** `setWidgetVisibility`, or a stale build hides something the panel stopped drawing.
+- **`chains` and `hop_script` are dropped in Shots mode**, with a note saying why. `run()` ignores `chains` and forces `hop_script=next` the moment a shot plan is present, so drawing them would be two controls that do nothing. The digest reads the hop count from the plan for the same reason.
+- **Never read `w.type` or `w.options` directly — use `widgetType(w)` / `widgetOptions(w)`.** `hideWidget` overwrites `w.type` with `"hidden"` and swaps `w.options` for a flagged copy, stashing the originals in `w._h3Saved`. The run panel hid the twenty dials it owned on its first build; when a shot plan loaded and flipped the mode to Shots, the suppression key changed, `build()` re-ran, and every widget now reported type `"hidden"` — so `fieldFor` rejected all of them and the panel emptied itself. It only reproduces on a workflow that *arrives* in Shots mode, since a fresh node builds once and never rebuilds. An empty build also clears `builtFor`, so `sync()` retries instead of caching the failure for the life of the node.
+- **Help text is `widget.options.tooltip`**, i.e. the `tooltip` from `INPUT_TYPES`. Do not retype those sentences in JS — same rule as the vocab route, same reason.
+
+The summary line deliberately omits the seed: `control_after_generate` rewrites it after every queue without telling the panel, so a seed shown there would be wrong more often than right. That staleness is also why the panel re-reads every field when it is opened.
+
+Two recipes here are load-bearing and both are ported from `PromptMasterLD/js/claude_prompt.js`:
+
+- **Four-flag widget hiding.** Classic LiteGraph only needed `computeSize = [0,-4]`. Vue Nodes 2.0 filters on `options.hidden | hideInPanel | canvasOnly`; without those flags every hidden dial reappears as a raw form. Invisible in packs with three widgets, unmissable at 21. Multiline STRING widgets are real DOM textareas, so their element has to be hidden too or it floats over the panel.
+- **The `_h` fixpoint height guard.** `_arrangeWidgets` runs every frame and grows the node when `panelTop + panelH + 4 > size[1]`; reporting a height derived from `node.size[1]` makes that true forever (~130 px of growth per frame). Report from an independent stored `_h`, updated in `onResize`. `chromeCompute`'s `_measuring` flag measures the frontend's own `computeSize` rather than re-deriving it.
+
+**Dropdown options come from `routes.py`, never from a copy in JS.** `GET /h3_ref_chain/vocab` serves `directives.VOCAB` *with its prose*, so hovering an option shows the exact sentence it will put in the prompt. A second copy in JavaScript would defeat the reason `directives.py` exists. The route is read-only — no writes, no filesystem; the reference-upload route is a separate unbuilt thing.
+
+Simple mode clears `shot_plan` (stashing it in `node.properties.h3_plan_backup` first) so `run()` cannot silently prefer a stale plan over the visible prompt.
+
+### 7. Tone compensation (`tone.py`)
+
+The H3 denoiser applies a tone bias to each generated segment, so the master steps in brightness at every seam. The estimator is ported from [`rkfg/ComfyUI-MiniMaxH3-ToneCompensate`](https://github.com/rkfg/ComfyUI-MiniMaxH3-ToneCompensate) (MIT, as is this pack). Three modes: `frame_shift` (per-frame per-channel additive), `gain_bias` (global affine), `lut` (tone curve). `frame_shift` is the one that suits our case, because the target's first frames are the model's *regeneration* of the source's last frames — same content, not a pixel-wise transform.
+
+**A downstream node cannot do this job, and that is the whole reason `tone_compensate` is a widget on the chain node.** The estimate needs both copies of the overlap: hop N's tail and hop N+1's regeneration of it. The join drops the second (`master_imgs[write_pos:...] = imgs[overlap_n:]`). By the time images leave `run()`, only one copy survives, and a node there would be comparing frames ~0.9 s apart in scene time — measuring content change as much as tone. `HTCToneCompensate` ships anyway for hand-built chains and for A/B work; it is not the fix for this node.
+
+**The call site is the design.** It sits in `run()` where the render and cache-hit paths converge, and its position relative to three neighbours is deliberate:
+
+- **After `hop_store.put`** — the cache holds *raw* hops, so the mode stays out of the hop key. Switching modes costs nothing instead of invalidating ~285 MB per entry. Correct on the way out, hit or miss.
+- **Before the master write** — the delivered video is corrected.
+- **Before `prev_imgs = imgs[-tail_n:].clone()`** — so hop N+1 is measured against hop N's *corrected* tail, which is what makes each hop's shift cumulative and lands the whole chain on hop 1's tone. **This does not stop the generator drifting, and an earlier version of this note wrongly claimed it did.** Measured 2026-08-28: with tone on and all three hops rendering fresh, hop 3 was generated from a corrected `prev_imgs` and still came out +3.48/255 above raw hop 2 — so it needed a `2d` correction, not `d`. `prev_sampled`, the Motion-Context latent, dominates the conditioning and is never touched by a pixel fix. Correcting here is still right (it is free, and it keeps `prev_imgs` consistent with the master), but the benefit is a clean cumulative repaint, not a cure for the drift at source.
+
+**Two consequences, both deliberate:**
+
+- **Enabling any mode clamps the master to 0..1**, including hop 1, which is otherwise unclamped VAE output. Correcting hops 2+ and not hop 1 would make the master inconsistent with itself.
+- **The latent path is untouched.** Motion-Context forwards `prev_sampled`, a latent; pixel correction never reaches it. `_condition_pin_latent` matches per-stream **std**, not mean — and a brightness shift is a shift in the *mean*. So nothing currently anchors latent mean. Known gap; do not build a latent-mean anchor speculatively.
+
+**Measured, 2026-08-28 — the real number, off the hop cache** (`chain_00052`, 3 hops x 243f, overlap 22, 7 steps res_multistep, Motion-Context pin on both joins). `tools/tone_probe.py` pairs hop N's last 22 frames with hop N+1's first 22 -- the model's regeneration of the same content, which survives only in the cache:
+
+| pair | r | g | b | luma |
+|---|---|---|---|---|
+| hop 1 -> 2 | +0.00995 | +0.00973 | +0.00914 | **+2.45/255** |
+| hop 2 -> 3 | +0.01003 | +0.01129 | +0.01085 | **+2.73/255** |
+| cumulative | +0.01998 | +0.02103 | +0.01999 | **+5.18/255** |
+
+Three facts follow, and they are the justification for the feature. It is **achromatic** -- r/g/b move together within ~0.001, so it is a luma bias, not a colour cast. It **accumulates linearly** -- ~2.5/255 per hop with nothing pulling it back, so a 5-hop chain lands near +10/255. And it is **brighter**, the opposite sign to the upstream README's "runs darker"; likely because we pin with a Motion-Context latent and never take the decode->encode round trip his workflow does.
+
+**Verified end to end, 2026-08-28** (seed `700637295460319`, `chain_00053` = `frame_shift`, `chain_00054` = `off`, both served from the same raw cache so content is identical):
+
+- **The mode is not in the hop key.** The `off` run hit all three keys written by the `frame_shift` run (`c442d296`, `4854c20f`, `2e4c1e14`) — 17.5 s against 171 s, zero re-renders. Switching modes costs nothing, which is the whole reason the call site sits after `hop_store.put`.
+- **Chain drift 5.57/255 -> 0.29/255**, a 95% reduction, and it stops accumulating. Applied shifts measured in the delivered video were `0`, `-1.71/255`, `-5.26/255`, matching the logged notes exactly. Segment 1 came out byte-identical, so hop 1's clamp was a no-op on this render.
+- **Do not use "seam -> 0" as the success metric.** It is wrong and it will make you overcorrect. Seam steps went `+1.40 -> -0.16` and `+1.41 -> -2.06`; the second is not an overshoot, it is the scene's own darkening across the cut, which correction should leave alone. The arithmetic closes: uncorrected seam minus true tone bias predicts `-0.31` and `-2.28` against measured `-0.16` and `-2.06`. Judge on cumulative drift, via `tone_probe`.
+- **Hop N needs a correction of N-1 times the per-hop bias** (hop 2 got `d`, hop 3 got `2d`), because `prev_sampled` — the Motion-Context latent the next hop is actually generated from — is never corrected. This is a pixel fix for a latent drift, so the required shift grows linearly: ~5/255 by hop 3, ~10/255 by hop 5, ~23/255 by hop 10. Since a positive drift is *subtracted*, the far-end failure is **crushed blacks** clipping at 0. Fine over the 3-5 hops this pack recommends; not a fix for long chains, and the first hard cost attached to the latent-mean gap below.
+- **The per-frame drift is not flat across the overlap.** It ramps in over ~6 frames, plateaus, then dips sharply at frame 17 in *both* joins — likely a VAE temporal chunk boundary. `frame_shift` uses `drift[-1]`, which sits in that dip and under-corrects by ~0.38/255; the mean of the last 4 overlap frames would be marginally better and is the obvious tuning knob if the residual ever matters. Upstream's reason for `drift[-1]` (an exact internal join) does not apply here, because the master drops the overlap.
+
+**All three modes measured, 2026-08-28** (seed `700637295460319`, four masters over identical cached pixels: `chain_00054` off, `00053` frame_shift, `00055` gain_bias, `00056` lut):
+
+| mode | worst residual drift | dark-clipped px, seg 3 | notes |
+|---|---|---|---|
+| off | — | 0.32% | |
+| `frame_shift` | +0.38/255 | **0.96%** | `rx-0.0076`, then `-0.0207` |
+| `gain_bias` | **0.20/255** | 0.56% | `rx0.9854-0.0035`, then `rx0.9674-0.0071` |
+| `lut` | 0.27/255 | **0.07%** | mean `0.4372->0.4284`, then `0.4520->0.4291` |
+
+**On drift removal there is nothing to choose between them** -- all three land inside 0.4/255, below this measurement's noise. Pick on failure mode instead, and `frame_shift` wins on one argument: **every `gain_bias` slope came out below 1 and moving further away (0.985 -> 0.967), which is attenuation bias, not tone compression.** Fitting `s = A*g + C` where `g = s + delta + noise` yields `A = var(s)/(var(s)+var(noise)) < 1`, driven purely by content mismatch between the source and its regeneration. The drift is a *pure level shift* (r/g/b within 0.001), so any slope != 1 is fitting artifact, and it lands in the output as a contrast reduction that deepens along the chain. `lut` has the same defect with 64 free parameters per channel instead of one -- its dark clipping coming out *below* the uncorrected reference means it is reshaping the tone curve, not correcting level. `frame_shift` cannot make that class of error; it can only shift.
+
+The cost is `frame_shift`'s alone: **dark clipping tripled, 0.32% -> 0.96%**, because subtracting a flat 5.26/255 pushes near-black pixels through zero. That is the crushed-blacks endgame already visible at hop 3. A gain-only mode anchored at black (`out = g * mean(src)/mean(tgt)`, no bias term) would fix it without introducing a fitted slope, and is the obvious next mode if long chains ever need one.
+
+**Seam measurements understate it by about a third, so never use them to decide.** `tools/seam_probe.py` on the same master reads `+1.56/255` and `+1.83/255` (sum `+3.39/255`) against the cache's `+5.18/255`: the frames either side of a cut are ~0.9 s apart in scene time and the content change partly cancels the drift. Earlier estimates of `≈2/255` from `chain_00047`/`00050`/`00051` were this same floor, mistaken for the value. Seam numbers are still the right *after* instrument -- `tone_probe` reads the cache, which stores raw pre-correction hops by design -- but only as an A/B between two masters from the same seed and cache, where the contamination is identical in both and cancels. **Note `temp/` is wiped on ComfyUI start, so probe before restarting.**
+
+Offline results (`frame_shift`, synthetic): recovers a planted additive shift to <1e-5; `gain_bias` recovers 0.92/+0.04 as 1.0870/−0.0435 exactly. A simulated 4-hop chain drifts +1.95/255 uncorrected and −0.13/255 corrected, with each hop's fitted shift staying at the planted per-hop bias rather than accumulating. That validates the mechanism, not the real-world magnitude.
+
+### Progress preview (Python ↔ JS)
+
+`_push_preview` sends a `h3_refchain_preview` websocket event (via `PromptServer.instance.send_sync`) with hop status and an optional base64 JPEG of the latest frame. `js/h3_ref_chain_ui.js` listens, resolves the target node (`findNodeByQualifiedId`, subgraph-aware), and updates a DOM widget it mounts on the node. If you change the preview payload shape in Python, update the JS listener in the same change.
+
+**Status is a short label only.** First stress run ended by passing the full `info` dump (summary + every hop prompt) as `status`, so the preview strip became the prompt. Final push is `done · Nf · Ts`. Assembled prompts stay on the `info` output (Preview Text). The JS strip also ellipsizes anything over 80 chars so this cannot happen again from a long status.
+
+**Next (user 2026-08-26, during first stress run):** the in-node preview should become a KJNodes `Model Preview Override`–shaped panel — large “waiting for sample…” frame, idle/status strip, optional a/Δ and step-time strip — not a 260 px strip at the bottom of the chain node. **OK to split it off** as its own node / sidebar on the MODEL (or IMAGE) wire **before** CreateVideo / SaveVideo. Do not fold more chrome onto `HandTieClips`. Reference implementation: `ComfyUI-KJNodes/nodes/preview_override_node.py` + `web/js/preview_override/preview_override.js`. Not built yet; current `mountPreview` stays until this lands.
+
+### First 8-step stress run (user 2026-08-26)
+
+4 hops × 8 s, seed 777777, turbo. Shipped plan: s1 `says one short line` / s2 `still talking` + `join=continuous` `pan_follow` `keep` / s3 drink + `continuous` `push_in` `close` / s4 `match_cut` `pull_back` `wide`.
+
+- **1→2 continuous + keep: clean.** The join directive is doing work; this is the success case.
+- **2→3 continuous + push_in + close: small jump.** `check_coherence` does **not** warn here (it only flags continuous + framing change + *held* camera). The jump is still expected at 8 steps: VOCAB concatenates “carry straight on from the pinned frames” with “A close shot, head and shoulders filling the frame,” so `framing: close` asserts the destination as the opening state while AddGuide is still the medium pin from s2. Next compiler pass should compose camera-move + framing as a *landing*, not as the opening, when `join=continuous`.
+- **3→4 match_cut: ok.** Control cut is distinguishable from 1→2. Do not treat all three seams as identical.
+- **Speech audio outlived the mouth.** s1–s2 ask for talking; s3–s4 do not (drink / lower mug). Picture followed the later beats (mouth busy, then quiet); soundtrack kept the line going for roughly the second half of the master. This is a pack gap, not a seam bug:
+  1. AddGuide pins the previous hop’s overlap **audio** at t=0 (`nodes_minimax_h3.py` crops it to remaining duration — the pin is ~0.9 s of *speech*, which seeds the rest of the hop).
+  2. cfg 1.0 cannot subtract speech. Omitting “talking” from s3/s4 is a no-op.
+  3. Shot-plan compilation emits no `overall_soundscape`. There is no speech/soundtrack axis on `AXES`.
+  4. `tail: ongoing` plus `_assemble_next`’s closer (“that action is still underway as the clip ends”) keep whatever the pin started, including a line.
+  5. s1’s “says one short line” names speech without giving the words, inside an 8 s hop. H3 invents a line and pads the leftover duration with more speech.
+  6. Vague leftover time is what H3 fills. User correction (2026-08-26): **every hop in a chain must carry either enough actual dialogue or a specific mention of silence.** Omitting both is gibberish, especially on hops 2+. “Says one short line” / “still talking” is vague and under-fills an 8 s hop. “No speech” / “no dialogue” is the negation form and also gibberish. The quiet word is **silence**, named in the beat. Spoken hops put the real words in the beat, enough to occupy the duration.
+- **End-of-run preview became the prompt dump.** `_push_preview(unique_id, info, …)` stuffed `info` into the status strip. Fixed to a short `done · Nf · Ts`; dump stays on the `info` output.
+- **Hop-1 compile order.** ~~`tail` sits before the beat~~ **Fixed.** `compile_shot` splits `lead` (join/camera/framing/pace) from `tail` and appends `tail` last, on hop 1 and hop 2+ alike (`directives.py`, `compile_shot`). Verified 2026-08-27. Two residuals survive: ESTABLISH still prepends “Live-action, natural light, one continuous take.” on hop 1 even when the beat already opens “Live-action…”, and a hop-1 beat that *is* a full six-field H3 block returns early and drops every directive including `tail`.
+
+**Contract (confirmed 2026-08-26, chain_00030..00032):** a complete six-field H3 / Ref2VA prompt is one generate. `[Shot 1]` is the opening of *that* generate. Hop 1 may be official. Hop 2+ must be a continuation beat only — pin-open + new action + sound. Wrapping hop 2 as another full official block (join splice, pin-open first, `keyframe completion`, “first frame of [Shot 1]”) still hard-cut at f124 onto the outfit still. `compile_shot` / `_assemble_next` flatten an official hop 2+ block to action + `overall_soundscape` + `non_diegetic_music` and drop `subject_definitions` / `summary` / `retention_analysis` / leading `[Shot 1]`.
+
+**Join pass (user 2026-08-27, chain_00037_.mp4).** Smooth chain. Console: `2 hop(s), 192f (8.0s) @ 960x544`, `8 steps res_multistep/beta`, hop 2 `Qwen last frame -> <Picture 1>`, `0 identity stills`, `Motion-Context pin: previous hop latent (22f picture, 24f audio, trim 22)`, master **362 f / 15.1 s**. Register: all three stills `shots 1`. That is the working join recipe at 0.5 MP / 8 step: latent pin + pin-only hop 2 + 8 s airlock budget + hop-2 paragraph (no official fields). Native mask (Phase 2) is not needed for this seam.
+
+**Next tests** (pack, not kitchen beats):
+
+1. **Cache fingerprint.** LoRA strength 1.0 → 0.9, re-queue. Both hops re-render. (Before the latent sidecar, a hop-1 hit made hop 2 log `AddGuide pixel pin`; that line now means the entry predates the sidecar or its latent failed to load.)
+   **Note ComfyUI's own node cache sits in front of this one:** re-queueing with *nothing* changed skips `run()` entirely (no `[HandTieClips]` lines at all, ~9 s), so it tests nothing. Nudge `cache_budget_gb` to force re-execution -- it is in neither `chain_salt` nor the hop key, so every key stays byte-identical.
+2. **Chained re-roll.** Revert strength. Change one word in hop 2 only. Hop 1 cache hit, hop 2 renders.
+3. Confirm the same join at **1.0 MP** (`1280×736`) before calling it shipped. Keep `seed_per_shot`. 777777 was join-hostile on the old 5 s pin-only graph; do not treat that seed as the only one.
+
+**chain_00030_.mp4 / chain_00031_.mp4 / the keyframe-completion re-queue.** Hard cut at hop 2, f124, onto the outfit still’s commercial kitchen. Drink beat ran; pin did not. Official hop 2 cannot join at 8 steps.
+
+**chain_00033_.mp4.** Short hop-2 drink beat, flatten did not fire (card was already short). Still hard-cut. Two findings: (1) `_assemble_next` still prepended register `subject_prose` (`subject_definitions:` + `retention_analysis:`), so hop 2 was a Ref2VA generate again. (2) Console: `8 steps euler/simple`, not `res_multistep/beta`. `tail: settle` also led the compiled beat, so hop 2 opened on “eases to a rest.” Header stripped; tail moved after the beat.
+
+**chain_00034_.mp4.** Header-stripped hop 2, `8 steps res_multistep/beta`. Still hard-cut; apron gone on hop 2. Console: `Qwen last frame -> <Picture 4>`, `3 identity stills`. Face still (`h3_stress_hero_face.jpg`) is the same commercial kitchen as the outfit plate, grey shirt, **no apron in the crop**. Outfit still has the apron. Hop 2 followed the face plate (place + wardrobe), not the pin. Stills without `shots` stay off hop 2+ continue; live frame is Picture 1.
+
+**H3 soundtrack (official methods, user 2026-08-26):** do not invent a pack dialect for quiet vs speech. Dialogue belongs in `detailed_description` as `(S1)` + `<d>[English] …</d>` with the actual words. Ambience/physical/non-verbal belong in `overall_soundscape`. Requested silence throughout a hop is `overall_soundscape: N/A` (the official complete-silence token), not the English word “Silence” stuffed into a beat. “No speech” / “no dialogue” is still negation and still gibberish. `_assemble_next` currently does not emit these fields; when the beat already contains them, leave them alone.
+
+**Iteration canvas (user 2026-08-26):** further tests run at **0.5 MP** (`960×544` landscape) for speed. 8 steps, seed 777777, 4×8 s, overlap 0.9 s stay. Seam times do not move (still master frames 192 / 362 / 532). Resolution is in `chain_salt`, so the 1.0 MP cache will not hit. A 0.5 MP pass validates join / speech / cache behaviour, not 1.0 MP texture. Confirm anything that ships at 1.0 MP (`1280×736`) on that canvas before calling it done.
+
+**chain_00028_.mp4 (0.5 MP, 960×544, 702 f / 29.25 s, 8 step).** Same stress plan. Frame-walked.
+
+- 1→2 at f192: continuous. Then **an inside-hop cut at f220–228 (~9.2–9.5 s, ~1.3 s after the join)** — over-shoulder + mug → frontal talking head, mug leaves frame. Same class as the old 1.8 s inside-hop cut. Shot 2’s `still talking` beat beat `pan_follow` + the walk.
+- 2→3 at f362: join itself is continuous (window, mug out). Close-up lands later inside hop 3 (~f432–456) on the drink, not at the seam.
+- 3→4 at f532: still the drink CU. `match_cut` + `wide` does **not** cut at the seam; pull-back to wide is ~f576–624. Control cut is late / soft.
+- Soundtrack is speech-level for almost the whole clip (integrated ~−11 LUFS). Brief dip at the 1→2 join; no quiet second half. Mouth can drink (f456–504) while the track keeps talking.
+- Mug survives hops 1, 3, 4; missing during the hop-2 talking-head. Identity holds at 0.5 MP (cross necklace from locked text rendered).
+- A/V: audio 29.131 s vs video 29.250 s (~119 ms short, ~40 ms × 3 hops).
+
+**chain_00029_.mp4 (0.5 MP, explicit beats + silence).** Same 702 f / 29.25 s.
+
+- Soundtrack: wall-to-wall speech is gone. Hop 1 line-burst ~4.4–7.3 s (mouth open at f120). **Random line at 15.41–16.71 s** (user-confirmed): 0.33 s after the 2→3 seam, 1.3 s of speech inside hop 3’s *kept* audio — the 0.9 s pin was already trimmed, so this is hop 3 inventing a line, not hop-2 leak. Hop 3 beat names Silence once, then “a swallow”, then `_assemble_next` still *ends* on “that action is still underway as the clip ends.” One silence mention in the middle of the prompt does not occupy an 8 s hop. Later hops also have a late spike (~23 s).
+- Mug path: chest height on the walk; lifts to the mouth only on hop 3; no reach to the glass. Opening frame still has the mug **on the counter** because the kitchen still itself shows it there (`h3_stress_kitchen.jpg`) — the photograph is additive, not only the desc.
+- 1→2 at f192: continuous, mug at chest. Camera swings toward the face ~f216 (mug stays). **Not** the 00028 talking-head cut.
+- Place break inside hop 2, f240→f270 (~10.0–11.25 s): residential window kitchen → the **outfit still’s commercial kitchen** (stainless, SANITIZER buckets, range). `h3_stress_hero_outfit.jpg` is that room. Kitchen ref is `retention: reference` (weak); outfit is a subject-bearing still of a *different set*. Walking off the pin lets the outfit photograph’s room take over. Hops 3–4 stay there. 2→3 join is continuous *in the wrong room*. 3→4 is again a delayed pull-back, not a match_cut at f532.
+
+## Writing beats (verified against live renders, 2026-08-27)
+
+The first end-to-end runs of v1.1 produced three failures that all trace to the
+same root: **sampling runs at cfg 1.0 with no negative branch, so the prompt is
+purely additive.** Nothing can be subtracted by naming it. Each was diagnosed
+from the assembled prompt and fixed by rewriting a beat, not by changing code.
+
+**1. A reference is only used where the action line points.**
+`retention_analysis` described `<Picture 3>` correctly ("the layout, surfaces,
+and light carry over as the setting") and the model still took its background
+from `<Picture 2>`, a full-length person still that carries its own room. The
+register is a static header; the beat is what drives the frame. Writing the tag
+into the action line fixed it:
+
+> The cook stands at the counter in **@kitchen**, looks up from the chopping board...
+
+Phrase the tag as a depicted place, not a container. `in @kitchen` alone once
+produced a literal composite -- the figure pasted onto the reference photo with
+the counter cutting through the body.
+
+**2. Naming the thing you want to end adds it.**
+`The cook stops talking, ...` kept her talking. "stops talking" and "talking"
+condition on nearly the same thing. Describe the wanted state as a pose plus a
+sound: `with her lips closed` gives the video branch something renderable, and
+naming room tone ("the hum of the refrigerator") gives the *audio* branch a
+target that is not a voice. H3 always generates audio for the full hop -- silence
+has to be described as a sound, never as an absence. This is the same finding as
+the "No speech / no dialogue is negation" bullet below, reached independently.
+
+**4. `tail` now reaches hop 2+ (fixed 2026-08-27).**
+`_assemble_next`'s closer used to end unconditionally on *"that action is still
+underway as the clip ends"*, and being the last sentence it overrode the shot's
+own `tail` directive -- `settle` and `hold` were unreachable on every hop after
+the first. On the final hop nothing absorbs that instruction, so the model
+invented late action to satisfy it: a line of dialogue in the last second of a
+3-hop chain, and the ~23 s spike noted further down this file. The closer now
+selects its terminal clause from `tail`, and every variant still ends on the
+clip's terminal *state* rather than on the photographs, preserving the ordering
+rule documented at the `return`. An absent or unrecognised `tail` keeps the old
+"still underway" wording.
+
+**5. `overall_soundscape` is hop-1 only.**
+`_assemble_next` strips `^(overall_soundscape|non_diegetic_music):` on hop 2+,
+leaving the value inline as prose, because official field names there made the
+model start a new Ref2VA generate (`chain_00030..00034`). So ambience on
+continuation hops is prose-only and is tuned by word choice. Choose narrowband,
+specific sources: "faint street noise through the window" is broadband and
+renders as a 5-second hiss; "the low hum of the refrigerator" does not.
+
+**3. A state change belongs at the END of the previous hop.**
+Affirmative phrasing alone did not stop the dialogue. Hop 2 was configured
+`tail=ongoing` with the beat `...turns toward the window, still talking`, and
+`_assemble_next` opens every hop 2+ with *"The clip opens already in progress
+from the pinned frames... holds for a short beat... and only then the next
+action begins."* With `audio_pin_frames=24`, the pin hop 3 inherits is literally
+mid-sentence. No wording in hop 3 can undo a boundary defined as mid-speech.
+
+The fix was in **shot 2**, not shot 3:
+
+> The cook sets the knife down, turns toward the window, and **finishes her last word** as she looks out.
+
+Generalises: to be silent/still/elsewhere in hop N, arrive at that state before
+hop N-1 ends. Hop N opens by holding what it was handed.
+
+## Known constraints (don't "fix" without reading this)
+- **The join pin is a latent slice, not a VAE round trip** (corrected 2026-08-27). Hop 2+ passes the previous hop's sampler AV latent to `MiniMaxH3MotionContext` as `context_latent`, which never decodes and end-aligns the audio window. Core's `MiniMaxH3AddGuide` does take `IMAGE`, not `LATENT` (`nodes_minimax_h3.py:177`), so it remains the *fallback* -- used when Motion-Context is absent, the overlap has no matching `context_length`, or the cached entry has no latent sidecar (pre-2026-08-27 entries only; the latent is stored now). Do not "simplify" back to AddGuide-only: it is what `chain_00037_`/`chain_00038_` were pinned against.
+- Overlap is fixed per-run to 22 f / 5 f / 39 f. A longer overlap does not fix continuity and can instead pin whatever content is in that longer tail — "increase overlap" is not a general fix for join artifacts.
+- Each join hard-cuts video but crossfades audio ~40 ms, accumulating ~40 ms/hop of A/V desync. Known and deliberately deferred.
+- `ref_image_size="max"` (2048 short-edge) is slower per step than `"match"` — an explicit tradeoff, not a default to silently upgrade.
+- Fewer than 3 wired reference stills triggers a warning log; unconnected `Load Image` nodes do not count as wired.
+- Soundtrack is official H3, not a pack dialect: `(S1)` + `<d>…</d>` for lines, `overall_soundscape` for ambience/physical (or `N/A` for requested silence). Do not invent beat-keywords. “No speech” / “no dialogue” remains negation/gibberish.
+
+## 8. References are files, not wires (2026-08-28)
+
+The node had **16 sockets** and twelve of them were user media: `ref_image_1..9`,
+`reference_video`, `voice`, `start_image`. They occupied roughly 340px down the
+left of the node before the editor started, each needing its own `Load Image`.
+They are gone. The node now has **five**: `model`, `clip`, `vae`, `audio_vae`,
+`continuity_state`.
+
+A reference names a **file** under `<ComfyUI input>/h3_refs`. `media.py` owns
+both halves of that:
+
+- **`resolve(name)` is the only thing that turns a name into a path**, and it is
+  used by the upload route and the loaders alike. Basename only, `normpath`,
+  then a prefix check against the reference directory, then an extension
+  whitelist. Verified against absolute paths, `../` traversal, and traversal
+  carrying a legal extension — all refused.
+- **The loaders return exactly what the sockets delivered** — float `[N,H,W,3]`
+  in 0..1 — so `_ref_frames`' resize, `_collect_ref_images`' dense-pack and
+  `store.tensor_digest`'s cache keying are all unchanged. That is why this was a
+  small diff rather than a rewrite.
+
+**Pixels never enter a widget.** Only the basename is stored. PromptMasterLD
+measured 1.68 MB of widget value for nine base64 thumbnails and ComfyUI then
+failed to save the workflow at all; previews are `/view?...&subfolder=h3_refs`
+URLs, which cost nothing to rebuild and survive a reload. `/view` also brings
+Range support, which a `<video>` needs to seek — so no thumbnail route was
+needed.
+
+**`IS_CHANGED` is new and load-bearing.** ComfyUI caches a node's output on its
+inputs, and a filename is a stable input even when the bytes behind it change:
+overwrite `face.png` and the previous render would be served. It hashes
+`name:mtime` for every referenced file. Deliberately **not** `float("nan")` —
+that is the blunt version PromptMasterLD's studio node uses, and it would force
+a full re-render of an expensive node on every queue.
+
+**Widget order is part of the saved-workflow format.** `widgets_values` is a
+**positional array** -- ComfyUI restores `value[i]` into `widget[i]` and never
+looks at the name. The three `*_file` widgets were first added at the *top* of
+`optional`, which shifted `hop_script`..`tone_compensate` by +3; every workflow
+saved before that change then loaded `audio_pin_frames`' integer into `ref_plan`
+and the editor died with `(text || "").trim is not a function` on load. That
+throw was the lucky part -- `hop_script`, `shot_plan` and `tone_compensate` were
+being silently misassigned too, and only the type mismatch made any of it
+visible.
+
+**New widgets go at the bottom of `optional`, always.** Old workflows are then
+*short* rather than *misaligned*, and the new widget takes its default. There is
+an append-only marker comment in `INPUT_TYPES` saying so. Note `seed` costs
+**two** array slots, not one: the frontend appends `control_after_generate`
+right after it.
+
+Both plan parsers now coerce (`String(text ?? "")`) and reject non-object JSON
+instead of dereferencing it, so a future misalignment shows an empty JSON tab
+rather than aborting the whole workflow load.
+
+**The hop cache needed no change at all.** `chain_salt` already digests the
+actual tensors, so different pixels behind the same filename still move the key.
+
+**Legacy plans cannot be migrated automatically.** An old `ref_image_N` held a
+tensor from a `Load Image`; there is no filename to recover. `refs.py` keeps the
+authored slot as `legacy_slot`, `parse_ref_plan` does **not** raise on it, and
+both the rail row and `check()` say *"was wired to ref_image_3 — pick its
+picture"*. Failing the parse would have stopped the editor opening the very plan
+the author needs to repair.
+
+## 9. Presentation (2026-08-28)
+
+**The node collapsed on first click and stayed collapsed.** Two causes, both in
+`installHeightGuard` (`js/editor/widget_utils.js`), both ported from
+`PromptMasterLD/js/claude_prompt.js:6285-6370`:
+
+- `computeLayoutSize().minWidth` reported a **constant**. The layout pass
+  re-reads it on every recompute — selecting the node is enough — and
+  faithfully re-declares the node at its stated minimum. It now tracks
+  `node.size[0]`. Safe against feedback: `max()` against a constant is a
+  fixpoint, not an accumulator, and width never feeds height.
+- A stale `widget.width` shadows `node.width` forever after load, because
+  ComfyUI's DOM-widget position updater reads `(widget.width ?? node.width)`. A
+  live getter with a dropped setter makes the stale value unrepresentable.
+
+Two more fixes alongside: `node.computeSize()[0]` is floored at the panel width
+(with no widget declaring one, LiteGraph falls back to `NODE_WIDTH * 1.5 = 210`
+and every resize command is free to crush the panel), and `domWidget.computeSize`
+now answers a **width-passing** caller with the minimum height and a
+**no-argument** caller with the live height. Reporting the live height to both
+pins the resize-drag floor to the current height, so the node could only ever
+grow.
+
+**`chrome()`'s memo key was stale by construction.** It keyed on
+`inputs|outputs|widgets.length`, none of which change when a widget is *hidden*
+— so every panel height computed after `applyVisibility` used a chrome
+measurement taken before it. The hidden count is now part of the key.
+
+**The reference rail was permanently crushed, and its rescue was dead code.**
+The 7-track grid needs ~536px and the node offers ~510px at `NODE_WIDTH 560`.
+There was a `@container (max-width: 460px)` block written to relieve it — but
+**nothing in the codebase declared `container-type`**, so the query had no
+containment context and never matched. `.h3e-section` now declares
+`container-type: inline-size`, and there are two breakpoints.
+
+**The palette committed to one look.** It used to derive surfaces from the host
+theme via `color-mix()` while hardcoding every accent — the intent was
+light-theme safety, but `--h3-bg` mixed toward `#111827` and `--h3-sunken`
+toward `#000`, so a light theme got dark blue-grey islands anyway. It is now the
+PromptMasterLD `.ldp-root` system: `#0a0a0a`, one hairline `#2a2a2a`, zero
+radius, one accent `#e8ff47`. **Changing `--h3-accent` moves the whole panel.**
+Emphasis **inverts** (accent fill, `--h3-on-accent` ink) rather than tinting,
+because an acid accent at 30% behind unchanged text is olive mud.
+
+A cascade trap worth remembering: the override block was first inserted *before*
+the reference-rail section, so `.h3e-chip-on`, `.h3e-inactive .h3e-ord` and
+`.h3e-subj-badge` all kept winning on source order. Overrides live at the end of
+the sheet now. Without a browser, a token audit script is the only thing that
+catches this class of bug.
+
+**The panel did not fill the node, and the mirror was why.** `installHeightGuard`
+kept an independent `_h`, updated through an `onResize` hook, so that the
+arrange pass could not feed its own growth. Measured during a drag: `onResize`
+and `setSize` each fired 57 times while `_h` sat at 876 and `node.size[1]`
+climbed past 1400. `measuring` was not stuck, which left one gate --
+`Array.isArray(size)`. **This frontend's `node.size` is not a plain Array**, so
+every write was skipped and `_h` held the install-time height forever. A 1911px
+node had a 742px panel.
+
+The repair was to delete the mirror, not fix the hook. `_h` existed only to
+break the arrange loop, and
+
+    panelHeight() = max(minHeight, node.size[1] - chrome() - SLACK)   // SLACK 8
+
+breaks it outright: the pass wants `panelTop + panelHeight + 4`, and `panelTop`
+is chrome minus the node's bottom padding, so a panel of exactly `size - chrome`
+asks for up to 4px more than the node has on every frame -- the ~130px/frame
+runaway the header comment records. With slack the inequality holds, the loop
+settles, and the node's height simply *is* the panel's height. Nothing to keep
+in sync, no hook to get wrong. `sync()` now only ever grows a too-short node;
+the height is the user's to choose.
+
+**RUN is pinned and always open.** `.h3e-root` used to be the scroll container
+with all four sections inside it, which put RUN below the script -- out of view
+on any workflow with more than two shots, and it is the section touched on every
+queue. The root is now a flex column holding `.h3e-scroll` (the authoring
+sections) and RUN outside it.
+
+Two flex details, both of which cost a round trip to learn:
+
+- **`.h3e-scroll` needs `min-height: 0`.** A flex item defaults to
+  `min-height: auto` and refuses to shrink below its content, which pushes RUN
+  off the bottom of the node instead of scrolling.
+- **`.h3e-run` must be `flex: 0 0 auto`, never `0 1 auto`.** Flex divides a
+  deficit in proportion to each item's content height. The scroller's content is
+  far taller, so a shrinkable RUN loses most of the contest and clips its lower
+  groups. The scroller absorbs all the shrinking; its `min-height: 160px` is the
+  floor that stops RUN owning the panel and RUN's `max-height: 55%` is the
+  ceiling.
+
+Always-open removed the only moment RUN re-read its widgets, so it now resyncs
+on `api`'s `promptQueued` -- the client-side event that fires after
+`control_after_generate` has bumped the seed, and the same one ComfyUI's own
+change tracker uses. The listener is dropped in `node.onRemoved`.
+
+**Not done:** PromptMasterLD's `--fsc` UI-scale multiplier, which makes every
+dimension `calc(Npx * var(--fsc))` and puts a zoom slider on the panel. It is
+mechanical churn across every rule in the sheet and was not worth doing blind.
+
+## 10. Ported for public use (2026-08-29)
+
+The prompting craft was written down and the pack was made installable by a
+stranger. Four things, in the order they mattered.
+
+**The shipped example workflows were broken.** All four in `workflows/` predated
+the 2026-08-28 socket removal: twelve dead media inputs each, three `LoadImage`
+nodes, and 21 widget values against a 28-widget node. Loading one is a new
+user's *first* action, so this outranked any amount of documentation. They are
+quarantined in `_disabled_custom_nodes/h3_legacy_workflows/` (the pack is not
+under its own version control -- deleting would have been unrecoverable) and
+replaced by two built from the verified `H3_Stress_6x7` structure:
+
+- **`HandTieClips_Starter.json`** -- two hops, **no references at all**, runs the
+  moment the loaders are pointed at files. The empty register is deliberate: an
+  `@tag` whose picture is missing is a *hard* error in `resolve_tags`, so a
+  starter that shipped with tags would fail on first queue for everyone.
+- **`HandTieClips_Showcase.json`** -- the six-hop continuity test, with the three
+  reference filenames generalised.
+
+Both use **core ComfyUI plus this pack only**. The dev workflow reaches KJNodes
+(`ModelPreviewOverrideKJ`, `MiniMaxLowVRAMAttention`) and PlagueKind
+(`LTX_lora_loader`, `H3SLAAttention`, `H3AdaLNLoRAFix`); an example that fails
+to load because of a pack the reader never asked for teaches nothing. The
+speed stack is documented, not shipped.
+
+**A declared-but-inactive `@tag` reported the wrong cause.** `check()` already
+warned correctly that a picture was missing, but the run then died on
+`resolve_tags` with *"unknown reference '@kitchen'"* -- pointing at the beat's
+spelling, the one thing that was right. `resolve_tags` now takes `declared`
+(every tag in the register, active this hop or not) and separates the two
+failures. The old two-argument behaviour is unchanged when `declared` is
+omitted.
+
+**`PROMPTING.md` and `prompt_pack/`.** The craft rules were spread through
+README prose; they are now a standalone guide, and a copy-paste system prompt
+that gets a language model to emit valid plans. Two files under `prompt_pack/`
+are **generated, never hand-written**:
+
+- `tools/gen_schema.py` builds `SCHEMA.json` from `directives.VOCAB`,
+  `refs.RETENTION` and the duration table, and **asserts** against
+  `plan._SHOT_KEYS`, `refs.REF_FIELDS` and `refs.SUBJECT_FIELDS`. Add a camera
+  move and the schema follows; add a shot field and the generator fails loudly
+  rather than emitting a stale schema. `--check` is the CI form.
+- `tools/gen_example.py` builds `EXAMPLE_6_HOP.md` from the showcase workflow,
+  including its hop/reference table, so the worked example and the shipped
+  workflow cannot disagree.
+
+**Template patterns in the editor.** `js/editor/templates.js` plus a
+**Templates** button in the SCRIPT header. They **append**, never replace --
+replacing would be the one destructive control on the node, and stacking is how
+a chain is actually built. `freeId()` mints the lowest unused `sN` because `id`
+is the hop cache's pointer and two shots sharing one would make `locked` reuse
+the wrong render.
+
+No template contains an `@tag`, for the same reason the starter workflow has no
+references. `tools/check_templates.py` extracts the patterns *out of the JS*
+and runs them through `plan.parse_plan` and `plan.check_coherence`, and lints
+every beat for negation -- a template that produced a plan the node rejects
+would be worse than no templates, because a first-time author would blame their
+own writing. It caught two: a beat reading "They stop at the window" (naming a
+cessation, which is law 2) and a line of dialogue containing "did not".
+
+That second one is worth recording as an open question: **whether the additive
+prompt bites inside quoted dialogue was never tested.** The templates avoid it,
+and `PROMPTING.md` says plainly that this is untested rather than inventing a
+rule.
+
+## 11. What chain_00057 taught (2026-08-29)
+
+The six-hop showcase was rendered for the first time. Three failures, and the
+one that mattered was a code gap the documentation had already claimed was
+fixed.
+
+**`locked` and `context` reached hop 1 only.** The register's whole promise is
+that a subject's continuity text carries identity across a hop where the
+photograph is absent. It did not. `subject_prose` is called under `if i == 0`,
+and `_identity_lock` returns `""` when no subject-bearing ref is active -- so on
+the showcase, hops 2, 3, 5 and 6 carried **no identity text of any kind**, and
+hop 5, scheduled with no references at all, lost the character entirely.
+Identity was riding on the pinned frames alone, which is the exact failure the
+register exists to prevent.
+
+`refs.continuity_line()` now emits that text on every hop 2+, and
+`_assemble_next` injects it between the lock and the live-frame citation. The
+reason it was suppressed in the first place is real and is preserved: naming
+*pictures* on a pin-only hop sent the encoder back to the plates (chain_00034 --
+commercial kitchen, grey shirt, no apron). So the new line carries **no
+`<Picture N>` and no `<Subject N>`**. It is a description of what stays the
+same, not a citation of anything. `<Subject N>` is excluded specifically because
+there is no `subject_definitions` block on a continuation hop to bind it to.
+
+Note this changes the assembled block on hop 2+ of every chain with a register,
+so it invalidates the hop cache. That is correct, not a regression.
+
+**Dialogue propagated through five hops.** Shot 1 ended on its spoken line with
+`tail: ongoing`. The audio pin carries the previous hop's tail, so the last
+second of hop 1 -- speech -- opened hop 2, and "action is still underway" was
+the closing instruction; the model satisfied it with the action it could hear.
+Nothing in hops 2-6 gave the audio anywhere else to go.
+
+This is the guide's own law 3, broken by the plan written to demonstrate it. The
+fix is authorial, not code: land the line **mid-hop** and leave a non-verbal
+action running into the seam (the knife on the board), and give every
+dialogue-free hop a narrowband sound of its own. Both `PROMPTING.md` and the
+authoring prompt now carry this as a named rule, and the shipped templates were
+rewritten to obey it.
+
+**`join: continuous` across a location change morphed one room into the other.**
+Hop 6 walked back from the hallway and the kitchen appeared mid-turn. A
+continuous join asks for one unbroken take between two different rooms, which
+is not a thing. `match_cut` is what a walk through a doorway is. The beat also
+read "steps into @kitchen" -- the container phrasing the README warns produces a
+composite of the photograph -- and now names the counter *in* the kitchen.
+
+Hop 5's beat is unchanged in the revised plan **on purpose**: it is the
+measurement, and changing it would forfeit the comparison.
+
+The revised plan is in the shipped showcase and in
+`user/default/workflows/H3_Stress_6x7_v2.json`; the original that produced
+chain_00057 is left alone so the A/B survives.
+
+
+## 12. Renamed to Hand Tie Clips (2026-08-29)
+
+The pack was `ComfyUI-H3-Ref-Chain`. It is now `ComfyUI-Hand-Tie-Clips`, and the
+four registered ids moved with it:
+
+| was | is |
+|---|---|
+| `H3RefChain` | `HandTieClips` |
+| `H3ContinuityState` | `HTCContinuityState` |
+| `H3ChainPreview` | `HTCChainPreview` |
+| `H3ToneCompensate` | `HTCToneCompensate` |
+
+Display names are unchanged (`H3 Ref2VA Chain`, `H3 Chain Preview`, ...) because
+the pack only drives MiniMax H3 checkpoints and a name that hides that costs
+somebody an afternoon. The menu category is `Hand Tie Clips`. `TAG` -- and so the
+console prefix -- is `[HandTieClips]`.
+
+**The old ids are still registered, as `DEPRECATED` subclasses.** A type id is
+what every saved `.json` carries, and an unregistered one is a red missing-node
+box, not a warning. A plain alias in `NODE_CLASS_MAPPINGS` would have worked but
+listed each node twice in search: ComfyUI falls back to the mapping key when
+`NODE_DISPLAY_NAME_MAPPINGS` has no entry for it. Subclassing and setting
+`DEPRECATED = True` gets both -- `server.py:783` publishes `deprecated: True`,
+and the frontend's `Comfy.Node.ShowDeprecated` (off by default) keeps it out of
+search while leaving it fully functional in workflows that name it.
+
+**The JS had to learn both ids or the aliases would have been worse than
+useless.** `js/h3_ref_chain_ui.js` and `js/h3_chain_preview.js` each compared
+`nodeData.name` against a single string; a legacy node would have loaded with no
+editor at all, which looks exactly like the rename having broken the pack. Both
+now test membership of a `Set`. `js/h3_chain_preview.js` needs it twice: once
+for its own type, once for `CHAIN_TYPES`, which is how a preview walks back up
+`images` to find the chain feeding it.
+
+**What deliberately kept the `h3` naming**, and must not be "finished" later:
+module filenames (`h3_ref_chain.py`), the `h3e-` CSS class prefix and `--h3-`
+tokens (515 occurrences -- one missed class silently breaks styling), the
+`/h3_ref_chain/*` routes, the `h3_refchain_preview` event name, and
+`input/h3_refs`. Renaming that folder would orphan every reference photo already
+on disk.
+
+The two shipped workflows moved to `HandTieClips_Starter.json` /
+`HandTieClips_Showcase.json` and were rewritten onto the new ids, with their
+`SaveVideo` prefix now `video/HANDTIECLIPS/chain`. The three under
+`user/default/workflows/` were left on the legacy ids on purpose: re-running
+`H3_Stress_6x7_v2.json` is then a live test of the alias path, and their existing
+renders stay together under `output/video/H3REFCHAIN/`.
+
+
+## 13. The on-canvas board (2026-08-29)
+
+`workflows/HandTieClips_Starter.json` carries six `MarkdownNote` cards to the
+left of the loaders, wrapped in a group titled READ ME. The text lives in
+`tools/notes.py` and is written into the workflow by `tools/build_notes.py`.
+
+Why on the canvas: the craft was in `PROMPTING.md`, `prompt_pack/` and the
+Templates panel, and all three require leaving the graph. The rules that decide
+whether a first render works are needed while beats are being written, which is
+on the canvas. The cards are a **condensation**, not a copy -- `PROMPTING.md`
+stays the authority and every card says so.
+
+Mechanics worth not rediscovering:
+
+- `MarkdownNote` is a core virtual node. The frontend renders it with `marked`
+  at `gfm: true` and sanitises with DOMPurify, so headings, GFM tables, bold and
+  code fences all work. It needs frontend >= ~1.16.
+- Cards are identified by `properties.htc_card`, which is what makes
+  `build_notes.py` idempotent -- it drops marked nodes before writing, so
+  re-running replaces the board instead of stacking a second copy.
+- `extra.ds` is **restored** on load, not fitted. Without setting it, a board at
+  negative x sits off-screen and is never found. Screen is
+  `(world + offset) * scale`, so the offset is what brings it into view.
+- Group serialisation is `{id?, title, bounding:[x,y,w,h], color?, font_size?,
+  locked?}` -- confirmed against the frontend's own zod schema, not guessed.
+
+**`widgets_values_named`, found while doing this.** Both shipped workflows
+carried a stale copy: `chains: 3`, `duration: 10 s`,
+`control_after_generate: randomize`, and a legacy `ref_plan` naming pictures that
+do not ship -- 25 entries against a 28-widget node. It came from the builder
+deep-copying nodes out of the dev workflow and overwriting only
+`widgets_values`. Dormant while `Comfy.Workflow.NamedValuesRestore` stays off
+(experimental, default false), but anyone who turned that on would have loaded a
+Starter that randomizes its seed and dies on a missing reference.
+`build_notes.py` strips it from both, and `tools/check_workflows.py` now fails if
+it ever comes back.
+
+`tools/check_workflows.py` is the promoted version of the validator that guarded
+the shipped workflows against socket/widget drift. It also checks the board:
+every card marked and non-empty, exactly one group, the group enclosing every
+card, and no card reaching past x=0 onto the loaders.
+
+
+## 14. The turbo stack ships in the examples (2026-08-29)
+
+Both shipped workflows now carry the dev graph's full MODEL wire:
+
+    UNETLoader -> LTX_lora_loader -> H3AdaLNLoRAFix -> MiniMaxLowVRAMAttention
+               -> H3SLAAttention -> ModelPreviewOverrideKJ -> HandTieClips
+
+and **CLIP reaches the chain from the LoRA loader, not the encoder** -- that is
+what makes the text half of every LoRA land, and it is the wire most likely to
+get quietly "fixed" back to the encoder by someone tidying the graph.
+
+This reverses the earlier "core ComfyUI and this pack only" rule for the
+examples, at the user's direction: `steps` is 7, which only works with a turbo
+LoRA, so an example without the LoRA stack is not a graph anyone can run at the
+settings it ships with. PlagueKind supplies the loader, the AdaLN fix and SLA;
+KJNodes supplies Low VRAM Attention and the preview override.
+
+`tools/build_speed_stack.py` inserts and rewires the five nodes idempotently
+(marker `properties.htc_speed`), rebuilding the plain loader -> chain shape
+first so it is reentrant from either state. `tools/check_workflows.py` walks
+**both** wires link by link -- a patch node that is present but bypassed round
+the side looks right on the canvas and does nothing.
+
+`H3SLAAttention` widget values are written out in full including
+`reference_protection`, which post-dates the dev workflow's saved values. That
+workflow has 10 entries against an 11-widget node, which is the positional rule
+working as intended: the new widget was appended last, so old values still line
+up and the missing one falls back to its default. The trailing `""` on the LoRA
+loader and the preview override is carried over verbatim for the same reason --
+a value past the last widget is ignored, and dropping one that turns out to
+belong to a widget would shift every value after it.
+
+`head_chunks` ships at 4 (the node's own default, safer on unknown VRAM) rather
+than the 2 used here. Two files have to be on disk as well: the turbo LoRA the
+loader names, and `taeh3.safetensors` for the preview override's `tiny_vae`.
+
+## 15. What a shipped diagnosis looked like (2026-08-29)
+
+The editor UI vanished after the folder rename -- raw widget boxes, no panel.
+Not a code fault. ComfyUI had been restarted while the pack was still
+`ComfyUI-H3-Ref-Chain`, so the running process held
+`python_module: custom_nodes.ComfyUI-H3-Ref-Chain` and served its web assets
+from a path the move had deleted. `/object_info` had all eight node types;
+`/extensions` listed none of the pack's JS and a direct fetch 404'd.
+
+Worth knowing for next time: `/object_info` carries `python_module`, which is
+the fastest way to find out **which copy of a pack a running server actually
+loaded**, and `/extensions` plus a direct fetch of one script separates "the JS
+is broken" from "the JS is not being served at all".
+
+## 16. What the Rain Kitchen renders taught (2026-08-29)
+
+Three six-hop renders of the same 6x7 s chain, each isolating one variable. All
+three findings are now in `PROMPTING.md`, the troubleshooting table, the
+authoring prompt and the on-canvas board.
+
+**Identity drift is permanent, and the old advice was backwards.** This file and
+`PROMPTING.md` used to say a face plate riding a later hop *beats the pin* and
+that `shots` should therefore be kept tight. chain_00059 falsified it: hop 4
+carried a face plate photographed in a *different kitchen* through a walking
+medium shot and held cleanly, while hop 5 — scheduled with no references at
+all — came back a different person, and hop 6 never recovered even though a
+place plate rode it and restored the room instantly. `locked` holds a face that
+is still right; only a plate rebuilds one that is gone. **Face refs go on every
+hop.** The old advice survives for *place* plates only.
+
+**A beat must survive an over-delivered hop.** A hop routinely does more than it
+was asked. Shot 3 asked for "a first slow step along the counter" and delivered
+the whole walk; shot 4 was then handed an instruction its own live frame had
+already satisfied, and the only way to obey was to reset the scene — a hard
+cut 1.5 s *into* the hop, not at the seam, because `_assemble_next` holds the
+incoming frames for a short beat first. Give one hop the whole movement, and
+write the next beat true from either ending ("she *reaches* the window", "she
+takes up the bowl *again*").
+
+**A noun with no adjective drifts.** Three hops said only "the bowl"; it came
+back stainless steel. Naming it "the white bowl" everywhere *and* stating it in
+`context` as a property (never a location — "stays in her hands" fights the
+beat the moment she puts it down) held it for six hops. The re-run then proved
+the rule by accident: `context` read "the apron stays tied over the **grey**
+t-shirt", and the t-shirt held all six hops while the apron, one clause away
+with no colour, had turned denim blue by hop 6.
+
+### The code change this bought
+
+`refs.resolve_tags` now takes `subject_names` and the node passes it on
+continuation hops only. `<Subject N>` is bound by `subject_definitions:`, which
+is hop-1 material — so on hop 4 the ordinal dangled, exactly the same defect
+as the undescribed bowl. From hop 2 a person tag resolves to the subject's
+`name` instead ("The cook walks down the hallway"), which binds to the
+`continuity_line` sentence every continuation hop already carries. No name means
+the old `<Subject N>` fallback, so nothing regresses.
+
+`tools/check_prompts.py` mirrors the new call, and gained the banned-word check
+that previously ran only against `templates.js`. That gap is how the shipped
+Showcase carried "**None** of the kitchen is visible" (law 1 — it *adds* a
+kitchen at cfg 1.0) and "She **stops** at the window" (law 2) through six
+versions. Both are fixed, and the Showcase's face ref now rides all six hops.
+
+## 17. The pre-beta audit (2026-08-29)
+
+Read for what a stranger hits, not for what we already check. Six findings; the
+first two would each have cost a tester a run.
+
+**The docs promised a stop the code never did.** `refs.check()` is *"warn, never
+raise"*, and its caller only printed. A ref naming a file that is not in
+`h3_refs` had its slot skipped and the chain rendered on — all six hops, with
+the reference silently inactive, which is precisely the uncontrolled output the
+register exists to prevent. Four shipped surfaces said otherwise, including the
+Showcase's own note: *"the run stops and names the reference it could not find.
+Nothing guesses."*
+
+Fixed in the code rather than the docs, because there is no reading under which
+rendering without a named-but-absent picture is what the author meant. New
+`refs.missing_files()` returns `(tag, file)` for every ref whose named file did
+not load; `h3_ref_chain.py` raises on it, after printing the register table so
+the error arrives with its context. **The distinction that matters:** a ref with
+*no* `file` stays a warning — the Starter ships that way on purpose so it runs
+before any pictures exist. Only a *named* file that is absent is fatal.
+
+**The on-canvas board never got §16's corrections.** `tools/notes.py` still
+carried the row chain_00059 falsified — *"a plate riding a hop it does not
+belong on, beating the pin → tighten `shots`"* — and was missing all three rows
+`PROMPTING.md` gained. The board is what a beginner actually reads, so it was
+shipping the inverse of the rule. Lesson: `PROMPTING.md` is the authority, but
+`tools/notes.py` is a **second copy** of the same craft, and a correction is not
+finished until both move. `build_notes.py` regenerates the Starter's cards *and*
+the Showcase's `Note` from `notes.SHOWCASE_NOTE`, so one rebuild covers both.
+
+The rest were packaging, not craft: the MIT `LICENSE` named no copyright holder;
+`pyproject.toml` lacks both fields a Registry publish needs (`PublisherId` and a
+`[project.urls] Repository`), now commented in place; the `README` had **no
+install section at all**; `ComfyUI-H3-Motion-Context` was absent from Needs
+despite the intro calling it the primary guidance path, so testers land on the
+`MiniMaxH3AddGuide` fallback without knowing they changed code paths; and the
+example workflows name quantised checkpoints by filename with no note that they
+are one valid set among many, which reads as a broken graph rather than a
+missing file.
+
+Clean on the same pass, worth not re-checking: no personal data anywhere, no
+hardcoded local paths in runtime code (only two dev-tool docstrings), 3.10-safe
+syntax, no third-party dependencies, Motion-Context absence handled with fork
+detection, `WEB_DIRECTORY` present, `h3_refs` auto-created.
+
+## 18. What a 27B model got wrong, and what the prompt taught it (2026-08-29)
+
+Qwen3 27B at temperature 0.3 was given an 8 x 15 s concept. The `ref_plan` came
+back structurally perfect -- both subjects named, face plate on all eight hops,
+places scheduled off the hops they do not belong on, zero register warnings. The
+`shot_plan` carried four defects, and tracing each one back to
+`prompt_pack/AUTHORING_PROMPT.md` found more than four gaps.
+
+**The prompt taught one of the bugs.** Rule 9 illustrated a beat as
+``"stands at the counter in `@kitchen`"`` -- backticks and all, because it was
+the one place a tag appeared inside a beat. The model copied the formatting, and
+literal backticks reach the encoder. Fixed, plus a rule that a beat is plain
+prose.
+
+**Beat length had no guidance at all.** The only budget in the file was for
+dialogue, so a no-dialogue plan had nothing to size against and every beat came
+back at 22-28 words regardless of a 15 s hop. There is now a word table -- and
+an honest note on it: the shipped plans run 37-39 words at *both* 5 s and 7 s,
+so beat length is near-constant across the only two hop lengths ever rendered.
+The words-per-second reading that gives 70-100 for a 15 s hop is a reasoned
+extrapolation, not a measurement, and the table says so.
+
+**Two rules were simply missing.** Nothing told the model to state a visual style
+-- for a "2D anime, Ufotable" concept neither returned block contained the word
+anime, so the text asked for photoreal while the pictures asked for anime. And
+the over-delivery rule from section 16 had never been carried into the prompt at
+all, only into `PROMPTING.md` and the board.
+
+**Two statements were wrong.** The prompt said "at most 9 pictures on any one
+hop"; `parse_ref_plan` counts `len(refs)` over the **whole plan**. The code's own
+error message said "on one hop" too, and has been corrected to match what it
+checks. And the `file` bullet still told the model to invent placeholder
+filenames without noting that, as of 0.3.1, a named file absent from `h3_refs`
+**stops the run**.
+
+Law 2 is the interesting non-fix. It is stated plainly, with the exact example
+"The cook stops talking", and the model wrote "stops and looks up" anyway. A
+principle is not something a 27B reliably applies to its own output; the literal
+word list `check_prompts.py` enforces now appears in the prompt, because a word
+list is checkable and a principle is not.
+
+## 19. What 114 seconds of rendered film and two 27B models taught (2026-08-29)
+
+Three sources landed together: a rendered 8 x 15 s anime chain (`chain_00003`,
+2742 frames, 114.25 s), and Qwen and Gemma each answering two test prompts
+written to trip specific rules. Shipped as **0.3.3**.
+
+### The node was fighting every stylised plan
+
+`directives.py` prepended `ESTABLISH = "Live-action, natural light, one
+continuous take."` to hop 1 **unconditionally**. At cfg 1.0 with no negative
+branch that is additive, and it landed *ahead* of the style declaration rule 12
+requires. A stop-motion puppet plan compiled to "Live-action, natural light,
+one continuous take. ... Hand-drawn stop-motion puppet animation in felt and
+painted wood", and the two fought.
+
+It also explains the anime chain's opening: hop 1 rendered as bright
+naturalistic daylight (**mean luma 72**) against a night plan *and* a night
+place plate, then fell to 46 on hop 2 the moment ESTABLISH stopped riding. That
+had been read as drift; it was the node.
+
+Never surfaced because both shipped workflows are live-action.
+
+Fixed twice over, because either alone leaves a hole: an `establish` widget
+(appended **last** in `optional`, per the positional-widget rule in section 8),
+and `directives.declares_own_medium()` / `establish_for()`, which drop the
+default when shot 1's opening names a medium. A model-authored plan never
+touches a widget, which is why the automatic arm is the one that matters.
+
+### Luminance drifts, and it only goes one way
+
+Mean luma per hop across the eight: **72, 46, 35, 17, 11, 11, 19, 14**. Setting
+the ESTABLISH artefact aside, hops 2-6 still slide 46 -> 11. The combat, the
+point of the film, plays at the bottom of it.
+
+This is the colour law one level up. `locked` holds a face; nothing holds an
+exposure. Each hop inherits the last frame and darkens it slightly and the
+error compounds. **Restate the light as a positive property in every beat** --
+naming a light *source* ("pale moonlight") does not set a level, and at cfg 1.0
+it only adds a moon.
+
+### The seams were never the problem
+
+7 of 7 hop joins are invisible: largest frame-to-frame difference at any seam is
+13.6, inside the range of ordinary in-shot motion, and two seams score below the
+film's own mean. Identity held 114 seconds on face plates riding every hop.
+
+The one hard cut in the film is **inside** hop 4, 3.25 s in, at 7.1 sd -- more
+than double any other jump. Shot 3 ended "ahead the trunks begin to thin toward
+open ground"; shot 4 opened "Across the flat moonlit stone of @arena_clearing
+the two of them square off". Hop 4 was handed a live frame of a man among trees
+and a beat asserting he stood on open stone, held the forest for 3.25 s, then
+reset the scene. The plan was clean under `check_coherence` and the banned-word
+scan. Hence `plan.check_place_handoff()`.
+
+### What the two models did
+
+Near-identical answers from Qwen and Gemma on the same prompt -- same beats to
+the word in 5 of 6 shots, same defects, same invented justification. The prompt
+is prescriptive enough to collapse two models onto one answer; a shared blind
+spot is then invisible from output alone.
+
+**The word table was inert.** Both models, asked for six 15 s hops, returned
+beats averaging **54 words** against a 70-100 band -- every beat under the floor
+-- and the same models on much shorter hops returned 40-48. Beat length is
+near-invariant to hop length in model output, now measured in a third setting.
+A reference table does not move a model with a prior on paragraph length; the
+rule is now an instruction to count, with a worked 74-word example.
+
+**The banned-word list beat the principle, and made things worse.** Zero literal
+banned words in all four plans -- and "The storm's roar begins to fade...
+raindrops strike the glass with decreasing force" and "The storm has passed".
+The list taught token avoidance and handed them a box to tick. It is now framed
+as crude examples of an idea, with the test stated as: is this happening, or has
+it finished happening?
+
+**Both abandoned the second location.** Each plated the opening place, moved the
+story elsewhere, gave the new place no plate, and justified it with a rule that
+does not exist ("to avoid conflicting with the frame pin of the new space");
+Qwen cited "rule 8/9", which does not say that. In the lighthouse plan that left
+the lamp room -- four of six hops -- on beat text alone.
+
+### `check_place_handoff` has two arms, and both were narrowed by real plans
+
+1. **Handoff.** Shot N names a place tag shot N-1 never mentions, and shot N's
+   own beat does not carry the journey. The arrival vocabulary had to widen: the
+   Showcase's shot 6 ("walks back along the hallway and through the doorway to
+   the counter in @kitchen") is correct and was being flagged.
+2. **Abandonment**, not gaps. Warning on any unplated hop also flagged the
+   Showcase, which deliberately walks her down an unplated hallway on 4-5 and
+   returns the kitchen plate on 6. The rule that survives contact: warn only
+   when the plates stop and **never resume**, so the film ends somewhere no
+   picture describes.
+
+Both shipped workflows are clean under the final version; the anime plan raises
+exactly one warning, on shot 4.
+
+### Audio, for the record
+
+No background music and no speech, confirmed on the spectrogram: broadband
+transients and noise, no harmonic bands. Seam levels hold within +/-2 dB on five
+of seven joins, and the two exceptions are drops the beats themselves ask for.
+The real audio issue is range, not seams: peaks reach -1.2 dBFS during the fight
+while hop 8 averages -42 dBFS. There is no audio equivalent of
+`HTCToneCompensate`. Left open.

LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Sandpies
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

PROMPTING.md

@@ -0,0 +1,511 @@
+# Writing for Hand Tie Clips
+
+Everything in this file was confirmed against renders, not reasoned from the
+code. Where a rule exists because of something the model actually did, that is
+said out loud — the reasons are more useful than the rules.
+
+If you only read one section, read [The three laws](#the-three-laws).
+
+---
+
+## What you are actually writing
+
+Two JSON documents, both living in widgets on the node, both editable as cards
+in the panel or as raw JSON under the **JSON** tab.
+
+| | |
+|---|---|
+| **`shot_plan`** | An ordered list of shots. **One shot per hop** — the shot count *is* the hop count. |
+| **`ref_plan`** | The reference register: which pictures exist, what each one is for, who they are photographs *of*, and which hops each belongs on. |
+
+The node writes a great deal that you do not: the identity lock, the citation of
+the live frame carried over from the previous hop, the join sentence, and the
+per-hop `<Picture N>` numbering. Your job is the **beat** — what happens this
+hop — plus the register that tells the node who is in it.
+
+---
+
+## The three laws
+
+### 1. The prompt is additive
+
+Sampling runs at **cfg 1.0 with no negative branch**. There is nothing to push
+against. Every concept you name is added to the conditioning and nothing can be
+removed by mentioning it.
+
+```
+BAD   No cut, no camera shake, don't change the lighting.
+GOOD  One unbroken take. The camera holds its position. The light stays as it is.
+```
+
+The bad version puts `cut`, `camera shake` and `change the lighting` in front of
+the encoder, which is precisely the opposite of the intent. Write what the shot
+*is* doing. This is also why the directive vocabulary is phrased affirmatively
+throughout, and why an unset axis emits nothing at all rather than asserting a
+default — an unset axis costs zero tokens.
+
+**Whether this bites inside quoted dialogue has not been tested.** A line like
+*'I did not think you would come'* is speech, not a stage direction, and the
+model may well treat it as such — but nothing here was confirmed against a
+render, so the shipped templates avoid negation in dialogue rather than assume
+either answer. Your own lines are your call.
+
+### 2. Never name the thing you want to end
+
+```
+BAD   The cook stops talking and stands still.
+GOOD  The cook leans back against the counter with her lips closed, and lets her
+      eyes move slowly across the room. The kitchen is quiet apart from the low
+      hum of the refrigerator.
+```
+
+`stops talking` keeps her talking. Describe the state you want as **a pose plus
+a sound**. This follows directly from law 1 but it is the single most common
+mistake, so it gets its own rule.
+
+**Silence has to be written as a sound.** H3 generates audio for the whole hop
+whether or not you asked for any. Written as an absence, you get speech — the
+model fills the track with the most likely thing. Written as room tone, a
+refrigerator, a distant car, you get room tone.
+
+### 3. Put state changes at the end of the *previous* shot
+
+Every hop after the first opens by holding the frames it was handed, and the
+audio pin carries the tail of the previous hop across the join. If shot 2 ends
+mid-sentence, **no wording in shot 3 will make shot 3 start quiet.**
+
+```
+shot 2:  The cook sets the knife down, turns toward the window, and finishes her
+         last word as she looks out.
+shot 3:  The cook leans back against the counter with her lips closed...
+```
+
+To be silent, still, or somewhere else in a shot, **arrive there before the
+previous shot ends.**
+
+### The other half of law 3: a beat must survive an over-delivered hop
+
+Law 3 says put a state change at the end of the *previous* shot. Its mirror is
+just as load-bearing: **never write a beat that assumes where the previous hop
+stopped.** A hop routinely does more than you asked. Give it a walk that was
+meant to be a first step and it will finish the whole walk — seven steps of
+turbo sampling has no reason to stop halfway.
+
+If the next beat then instructs an action its own live frame has already carried
+out, there is exactly one way for the model to satisfy it: reset the scene and
+do it again. That reads as a hard cut about a second and a half *into* the hop,
+not at the seam, because `_assemble_next` holds the incoming frames for a short
+beat first.
+
+Observed on a six-hop chain. Shot 3 asked for *"takes a first slow step along
+the counter"* and delivered the entire walk to the window in a tight close.
+Shot 4 was then handed *"carries the bowl the length of the counter to the
+window and sets it down on the sill"* — already true. It cut at 21.8 s.
+
+Two fixes, and use both:
+
+- **Give one hop the whole movement.** Splitting a walk across two hops is what
+  creates the impossible second instruction.
+- **Write the next beat so it is true from either ending.** *"She reaches the
+  window and sets the bowl down"* is satisfiable whether she arrived last hop or
+  is still arriving. *"She takes up the bowl again"* asserts no location for the
+  bowl, so a hop that never saw it set down still has something legal to do.
+
+The rewritten chain rendered 39 s with no cut detectable at a 0.08 scene
+threshold.
+
+### Dialogue propagates, and `tail: ongoing` compounds it
+
+Observed on a six-hop chain: shot 1 ended on its spoken line, and the character
+**went on talking through all five remaining hops**, none of which had any
+dialogue written.
+
+Two things caused it together. The audio pin carries the previous hop's tail, so
+the last second of hop 1 — speech — became the opening of hop 2. And
+`tail: ongoing` closes the prompt with *action is still underway*, which the
+model satisfied with the action it could hear.
+
+The fix is not to write "she is silent" in the later shots. It is to **land the
+line early in the hop and leave a non-verbal action running into the seam**:
+
+```
+BAD   ...looks up from the chopping board and says, 'You are early.'
+      tail: ongoing
+
+GOOD  ...looks up from the chopping board and says, 'You are early. I have
+      barely started.' She turns back to the board and goes on slicing, the
+      knife tapping steadily against the wood.
+      tail: ongoing
+```
+
+The knife is what is still underway when the frames stop, so that is what the
+pin carries. Then **give every dialogue-free hop a sound bed of its own** —
+footsteps, a refrigerator, rain on glass — or the audio has nowhere to go but
+back to speech.
+
+---
+
+## Templates
+
+The **Templates** button in the SCRIPT header appends ready-made patterns —
+*Dialogue, held*, *Cross the room*, *Leave for an unseen space*, *Return to the
+room*, *Quiet close*. They append rather than replace, so a chain is built by
+stacking them.
+
+Each one exists to demonstrate a rule on this page in a form you can edit rather
+than read, and each carries a note about how to schedule references around it.
+None of them contains an `@tag`: a template that named a reference you had not
+created would turn one click into a run-time error.
+
+## Writing a beat
+
+**Shot 1 is the whole opening.** Establish the person, the place, the light, what
+they are doing. **Every later shot is only the new beat** — do not re-describe
+the face, the clothes, or the room. The photographs, the register and the pin
+already carry all three, and re-asserting them competes with the pin rather than
+reinforcing it.
+
+```
+shot 1:  @hero_face stands at the counter in @kitchen, an apron over a grey
+         t-shirt. She looks up from the chopping board and says one short line,
+         then turns back to the board and goes on slicing, the knife tapping
+         against the wood.
+shot 2:  She sets the knife down and walks the length of the counter to the
+         window, looking out at the street. Her steps are soft on the tiles and
+         the refrigerator hums behind her.
+```
+
+Shot 2 says nothing about her face, her apron or the kitchen. It does not need
+to. It *does* name a sound, because shot 2 has no dialogue and the audio needs
+somewhere to go that is not the previous hop's speech.
+
+### Point the action line at the reference you want used
+
+Describing a reference in the register is **not enough**. The beat is what drives
+the frame. Write the tag into the action:
+
+```
+The cook stands at the counter in @kitchen, looks up from the chopping board,
+and speaks one short line to someone off-frame.
+```
+
+`@kitchen` resolves to whatever `<Picture N>` that reference happens to be on
+this hop, so adding, removing or rescheduling references never breaks your text.
+
+A **person** tag behaves differently on each side of the first hop, and the node
+handles the difference for you. On hop 1 `@hero_face` becomes `<Subject 1>`,
+bound by the `subject_definitions:` block that only hop 1 carries. From hop 2 on
+that block is gone, so an ordinal would dangle — and the node substitutes the
+subject's `name` instead:
+
+```
+hop 1:  <Subject 1> stands at the counter in <Picture 2>...
+hop 4:  The cook walks down a narrow hallway...
+```
+
+"The cook" binds to the identity sentence `continuity_line` puts on every
+continuation hop. **So give every subject a `name`** — without one the node
+falls back to `<Subject N>`, which points at nothing on that hop. Capitalisation
+is handled at sentence starts.
+
+Phrase a place as **a place that is depicted**, not as a container to be placed
+inside — "in @kitchen", not "inside the image of @kitchen". The latter can
+produce a literal composite of the photograph.
+
+### Dialogue
+
+Write the line, in quotes, inside the beat:
+
+```
+@hero_face looks up from the chopping board and says, "You are early. I have
+barely started." She turns back to the board and goes on slicing.
+```
+
+Land the line in the **middle** of the hop, never at its end — see
+[Dialogue propagates](#dialogue-propagates-and-tail-ongoing-compounds-it).
+
+Keep it to roughly one line per 5–7 seconds of hop. A long speech in a short hop
+gets truncated mid-word, and that truncation is then pinned into the next hop's
+audio.
+
+If you are pasting a plan into the **JSON** tab rather than typing into the
+cards, single quotes around dialogue survive the round trip more reliably than
+escaped double quotes, and read identically to the encoder.
+
+### Ambience: narrowband and specific
+
+After shot 1 the official soundscape fields are stripped and ambience is plain
+prose, so the exact words carry all the weight.
+
+| | |
+|---|---|
+| `faint street noise through the window` | broadband — renders as a five-second hiss |
+| `the low hum of the refrigerator` | narrowband — renders as a refrigerator |
+| `a single click from the refrigerator, then stillness` | a discrete event — the fallback when a continuous bed still misbehaves |
+
+---
+
+## Directives
+
+Five axes, all optional. Set on a shot as `"directives": {...}`.
+
+| axis | values | notes |
+|---|---|---|
+| `join` | `continuous`, `match_cut`, `hard_cut` | **Ignored on shot 1**, which has nothing to join to. |
+| `camera` | `hold`, `pan_follow`, `push_in`, `pull_back`, `orbit`, `handheld` | |
+| `framing` | `keep`, `wide`, `medium`, `close` | |
+| `pace` | `slow`, `steady`, `brisk` | |
+| `tail` | `ongoing`, `settle`, `hold` | Defaults to `ongoing`. The only axis with a default. |
+
+They compile in that order, `join` first, because `join` describes how this hop
+meets the previous one.
+
+### `tail` is not decoration — set it on your last shot
+
+This axis exists because of an observed failure. A beat whose action completes
+before the frames run out leaves the model with nothing to render, and it settles
+onto its strongest remaining conditioning — **the identity photograph**. The last
+few seconds of a chain would cut to the reference still.
+
+`ongoing` is the default for exactly that reason: it gives the tail somewhere to
+go that is not the reference. But on your **final** shot, `ongoing` tells the
+model action is still underway at the final frame, and it will invent something
+to satisfy that — a stray gesture, or a stray line of dialogue in the closing
+second. Use `settle` or `hold` there.
+
+### Two combinations the node will warn about
+
+**`join: continuous` + a framing change + `camera: hold`.** A framing change asks
+the audience to be somewhere new. With the camera still, the only way to get
+there is a cut — so the join and the framing are asking for opposite things and
+the model picks one. Earn the framing on the move (`push_in`, `pull_back`,
+`pan_follow`) or set `framing: keep`.
+
+**`push_in` + `wide`, or `pull_back` + `close`.** The move points the opposite way
+from the destination. Physically contradictory at any join value.
+
+Both are warnings, not errors — they are legitimate things to want. They just
+rarely read the way you meant.
+
+> When `join: continuous` and the camera *is* moving, the framing sentence
+> compiles as a **landing** ("The move settles into a close shot…") rather than
+> as the shot's opening state, so it does not fight the pin that still holds the
+> previous framing. You do not have to do anything to get this; it is worth
+> knowing it happens.
+
+---
+
+## The reference register
+
+```json
+{
+  "refs": [
+    {"tag": "hero_face",   "file": "cook_face.jpg",    "subject": 1,
+     "retention": "fully_preserved", "shots": [1, 4],
+     "desc": "head-and-shoulders, even light"},
+    {"tag": "hero_outfit", "file": "cook_apron.jpg",   "subject": 1,
+     "retention": "partially_copy",  "shots": [1]},
+    {"tag": "kitchen",     "file": "kitchen_wide.jpg",
+     "retention": "reference",       "shots": [1, 2, 3, 6]}
+  ],
+  "subjects": {
+    "1": {
+      "name": "the cook",
+      "locked": "the same face, the same short dark hair, the same silver stud earrings",
+      "context": "the apron stays tied over the grey t-shirt"
+    }
+  }
+}
+```
+
+### Fields
+
+| ref field | |
+|---|---|
+| `tag` | **Required.** Short, stable, what you write in beats as `@tag`. Must be unique. |
+| `file` | A basename in `ComfyUI/input/h3_refs`. Set for you when you drop a picture on the rail. Never a path. |
+| `subject` | Integer ≥ 1. Groups pictures **of the same person**. |
+| `retention` | `fully_preserved`, `partially_copy`, `reference`. Defaults to `fully_preserved` when `subject` is set, `reference` otherwise. |
+| `desc` | Free text about the picture. |
+| `shots` | 1-based hop numbers this picture rides on. See below — this is the important one. |
+
+| retention | what carries over |
+|---|---|
+| `fully_preserved` | face, bone structure and hairstyle, exactly |
+| `partially_copy` | the garment and its cut, moving naturally with the body |
+| `reference` | the layout, surfaces and light, i.e. a place |
+
+| subject field | |
+|---|---|
+| `name` | What to call them in prose. |
+| `locked` | What must not change. **This is what survives when the photograph is off the hop.** |
+| `context` | Situational state that should persist — wardrobe, what they are holding. |
+
+At most **9 pictures on any one hop**.
+
+### `subject` is not optional decoration
+
+Declaring two photographs of two *different* people as the same subject makes
+the model render the **average of two faces**. Group photos per person, always.
+
+Conversely, a subject block that no ref claims is an error, not a warning: it
+would ride every hop describing someone who never appears, and at cfg 1.0 that
+is purely additive noise.
+
+Give every subject a `locked`. Pictures alone put a face in front of the encoder;
+`locked` is what carries the identity across a seam where the picture is absent.
+
+> This was **not true before 2026-08-29**. `locked` and `context` reached hop 1
+> only, and a hop scheduled with no references carried no identity text at all
+> — which is exactly how a six-hop test lost its character on the one hop that
+> had no pictures. They now ride every hop, phrased with no `<Picture N>` or
+> `<Subject N>` citation so they cannot send the encoder back to the plates.
+
+### Name a colour, or it drifts
+
+`locked` and `context` ride every hop, but they only protect what they actually
+describe. A noun with no adjective is exactly as unanchored as a `<Subject N>`
+with no antecedent — each hop is an independent encode, and *"the bowl"* on
+hop 4 gives that encode nothing to bind to.
+
+Two renders of the same chain settled it. In the first, three hops said only
+*"the bowl"*; it came back stainless steel on hop 4 and a different ceramic one
+on hop 6. Adding the colour to every mention **and** stating it as a property in
+`context` — *"the bowl she is using is white porcelain"* — held one white bowl
+through all six hops of the re-run.
+
+The second render then made the rule sharper than a designed test would have.
+This `context` line ran on every hop:
+
+> the apron stays tied over the **grey** t-shirt
+
+The t-shirt has its colour named and is grey in all six hops. The apron is one
+clause away in the same sentence, has no colour, and had turned denim blue by
+hop 6. One sentence, one variable.
+
+So:
+
+- Put persistent properties in `context` as **properties, never locations**.
+  *"the bowl is white porcelain"* is true wherever she puts it; *"the bowl stays
+  in her hands"* becomes additive text fighting the beat the moment she sets it
+  down.
+- Repeat the adjective in the beats too. *"the white bowl"*, every time.
+- This applies to anything the register does not photograph on that hop. A ref
+  with `shots: [1]` stops defending its garment at hop 2; from there the only
+  thing holding it is the words.
+
+### `shots` is how you schedule references — and the default will surprise you
+
+> **On a continuation chain, a reference with no `shots` list rides hop 1 only.**
+
+That is deliberate for **place** plates: a room still riding a hop set
+somewhere else beats the pin, because the model holds a crisp well-lit picture
+of one room and a noisy carried-over frame of another, and it follows the still.
+List every hop a picture should appear on, explicitly.
+
+> **For a face plate, schedule it on every hop.** This page used to warn that a
+> face plate riding a later hop beats the pin the same way. A six-hop render
+> contradicted it flatly: hop 4 carried the face plate through a walking medium
+> shot in a space the plate had never seen — it was photographed in a different
+> kitchen — and held cleanly, while hop 5, scheduled with no refs at all, came
+> back a **different person**, and hop 6 never recovered.
+>
+> Identity drift is permanent. The room came back the instant a place plate rode
+> hop 6; nothing brought the face back, because no face plate rode anything.
+> `locked` holds a face that is already right. Only a plate rebuilds one that is
+> gone, so do not let it go. Putting the face on `[1,2,3,4,5,6]` fixed it and
+> cost nothing visible.
+
+The useful consequence: you can take references *away* deliberately. A hop with
+no room reference is a hop the model must invent a room for, which is exactly
+what you want when the character walks somewhere the register has never seen.
+
+---
+
+## A worked six-hop plan
+
+This is `workflows/HandTieClips_Showcase.json`, and it is built to be hard.
+
+| hop | beat | refs active | what it tests |
+|---|---|---|---|
+| 1 | kitchen, dialogue | face, outfit, kitchen | establishment |
+| 2 | walks to the window | kitchen | lateral movement, held identity |
+| 3 | exits through the doorway | kitchen | leaving the referenced space |
+| 4 | hallway | face | **an unseen space** — no room reference exists for it |
+| 5 | dialogue at the far window | **none** | **identity, wardrobe and voice on the pin + `locked` alone** |
+| 6 | returns to the kitchen | kitchen | re-entry after three hops away, on a `match_cut` |
+
+Hop 6 joins on `match_cut`, not `continuous`. Asking for one unbroken take
+between two different rooms is asking the impossible, and the first run of this
+plan got what it deserved: the hallway morphed into the kitchen mid-turn. A walk
+through a doorway *is* a cut on a matched movement.
+
+Hop 5 is the point of the exercise. If the cook is the same person, in the same
+apron, with the same voice, **with no picture in front of the encoder at all**,
+the register is doing its job. Hop 6 then asks whether the room survived three
+hops of absence.
+
+The face plate returns on hop 4 and not on 5 on purpose: hop 4 is where the
+character enters a space the register cannot describe, which is where identity
+drift is most likely to start, and re-asserting the face there is cheaper than
+recovering from drift on 5 and 6.
+
+---
+
+## Duration
+
+The label on the widget and the frames the model actually renders agree to a
+tenth of a second, because every offered value satisfies the model's own frame
+alignment (`n % 17 == 5` at 24 fps).
+
+| label | frames |
+|---|---|
+| `5 s` | 124 |
+| `7 s` | 175 |
+| `8 s` | 192 |
+| `10 s` | 243 |
+| `15 s` | 362 |
+
+A shot may override the chain with `"duration": "7 s"`, using the same labels.
+
+---
+
+## When it goes wrong
+
+| symptom | cause | fix |
+|---|---|---|
+| The clip cuts to the reference photo in its last seconds | The beat finished before the frames did, and the model settled onto its strongest remaining conditioning | Set `tail`, and give the beat enough to do |
+| A stray gesture or line in the closing second | `tail: ongoing` on the final shot | `settle` or `hold` |
+| She keeps talking after you asked for quiet | You named the ending (`stops talking`) — law 2 | Pose plus a sound |
+| Dialogue continues into hops that have none written | The hop before ended on speech, and the audio pin carried it | Land the line early; leave a non-verbal action running into the seam; give every quiet hop its own sound bed |
+| A character walks between two rooms and one morphs into the other | `join: continuous` across a real location change | `match_cut` |
+| Silence renders as speech | Silence written as an absence | Name room tone, a fridge, a distant car |
+| Ambience is a five-second hiss | Broadband wording | Narrowband, or a single discrete event |
+| Two characters' faces merge | Both declared as the same `subject` | One subject number per person |
+| The face becomes a different person partway through | A hop scheduled with no face plate. `locked` holds a face that is still right; only a plate rebuilds one that is gone, and the drift never self-corrects | Put the face ref on every hop |
+| A hard cut ~1.5 s into a hop, mid-scene | The previous hop over-delivered, so this beat instructs something its own live frame already did. The only way to obey is to reset the scene | Give one hop the whole movement; write the next beat so it is true from either ending |
+| An animated or stylised plan renders photoreal, and hop 1 most of all | The node prepends an establishing line to hop 1 and its default asserts **live action**, so "Live-action, natural light" was added ahead of your style. Fixed in 0.3.3: the default is dropped when shot 1 names a medium | Name the medium in shot 1's **first sentence**, or clear the `establish` widget |
+| The film gets steadily darker hop after hop | Luminance drifts like colour, in one direction, and nothing pushes back. Measured at 72 -> 11 mean luma across six hops of a night chain | Restate the light as a positive property in every beat: "the clearing reads bright under the full moon, pale stone, open detail in the shadows" |
+| A location introduced mid-plan drifts | It has no place plate. Tightening a plate to its own shots does not mean the next location goes without one | Add a plate for it, riding the hop it arrives and every hop after. `check_place_handoff` warns when the plan ends with no plate riding |
+| A prop or garment changes material or colour | It is named with no adjective, so each hop's encode is free to invent one | Repeat the adjective in every beat, and state it as a property in `context` |
+| A continuous join reads as a cut | Framing change with `camera: hold` | Earn it on the move, or `framing: keep` |
+| The run stops naming a reference | That row's picture is not in `h3_refs`. A named file that is not on disk is fatal -- rendering the chain without it is never what was meant | Drop the file on the row in the REFERENCES rail, or clear its picture to run without it |
+| A reference has no effect on some hop | Its `shots` list leaves that hop out. This is silent, not an error -- it is a legitimate schedule | List every hop the picture should ride |
+| A pasted plan is rejected as invalid JSON | Usually escaped double quotes mangled in transit | Use single quotes around dialogue |
+
+---
+
+## Having a model write the plan
+
+The whole vocabulary, schema and rule set fits in one prompt. `prompt_pack/`
+holds a copy-paste system prompt that turns a plain description of a scene into
+a `shot_plan` and `ref_plan` this node accepts:
+
+- **[`prompt_pack/AUTHORING_PROMPT.md`](prompt_pack/AUTHORING_PROMPT.md)** — paste
+  into any chat model, describe your scene, paste the two JSON blocks back into
+  the node.
+- **[`prompt_pack/SCHEMA.json`](prompt_pack/SCHEMA.json)** — the machine-readable
+  version, for anyone wiring this into their own tooling.
+
+The node still validates everything, so a model that gets it wrong is caught
+rather than obeyed.

README.md

@@ -0,0 +1,337 @@
+# Hand Tie Clips
+
+One node. Write a shot plan, drop in your reference stills, queue.
+
+> **Renamed 2026-08-29.** This pack was `ComfyUI-H3-Ref-Chain`. The nodes now
+> live under the **Hand Tie Clips** category and register as `HandTieClips`,
+> `HTCChainPreview`, `HTCToneCompensate` and `HTCContinuityState`. The old ids
+> are still registered as deprecated aliases, so **every workflow saved before
+> the rename keeps loading** — they are just hidden from node search. Nothing
+> needs migrating.
+
+**Writing for it:** [PROMPTING.md](PROMPTING.md) is the authoring guide — the rules that come from what this model actually does, not from taste. [prompt_pack/](prompt_pack/) has a copy-paste prompt that gets a language model to write plans for you.
+
+Each hop is native **MiniMax H3 Reference-to-Video**. Hops after the first are guided by the **previous hop's sampler AV latent** via `ComfyUI-H3-Motion-Context` when that pack is installed (22 picture frames + 24-frame end-aligned audio). Stock `MiniMaxH3AddGuide` is the fallback when Motion-Context is missing or the previous hop was a pixel cache hit. Voice stays as a reference every hop. Identity stills ride hop 1; later hops use the pin for wardrobe and room unless a ref lists those hops in `shots`. A 5 s hop drops the airlock on a continuous join — validate seams at 8 s or 15 s.
+
+This is not the seamless-chain pack. No airlock script, no Motion-Context, no interior patch.
+
+## What v1.0 changed
+
+The prompt is no longer a wall of `---`-delimited text, and the MODEL wire is no longer four extra nodes.
+
+| | |
+|---|---|
+| **`shot_plan`** | The script, as JSON. One shot per hop — **the shot count is the hop count**, so `chains` can no longer disagree with it. |
+| **`directives`** | `join` / `camera` / `framing` / `pace` / `tail` per shot, compiled to vetted prose. Improving a phrase improves every plan you have ever written. |
+| **`ref_plan`** | Stable `@tags` for reference stills, grouped into subjects, each naming a picture file. Removing one can no longer silently renumber `<Picture N>`. |
+| **`cache_hops`** | Lossless per-hop cache. Re-roll one shot, resume after a crash, and hold roughly one hop in RAM instead of the whole clip. |
+| **the editor** | Cards on the node, not JSON in a textarea. Hover any directive to read the exact sentence it puts in the prompt, or hit **Templates** for a ready-made pattern. |
+
+Simple mode keeps the old one-prompt workflow; the speed stack (LoRAs, AdaLN fix, low-VRAM, SLA) stays as four ordinary nodes on the MODEL wire, where you can see it.
+
+## Install
+
+Unzip the folder into `ComfyUI/custom_nodes/`, so that it lands as:
+
+```
+ComfyUI/custom_nodes/ComfyUI-Hand-Tie-Clips/
+    __init__.py
+    h3_ref_chain.py
+    js/
+    workflows/
+```
+
+One folder level too deep (`custom_nodes/ComfyUI-Hand-Tie-Clips/ComfyUI-Hand-Tie-Clips/`) is the usual mistake, and the pack simply will not appear.
+
+No dependencies to install. Everything it imports -- `torch`, `numpy`, `PIL`, `av`, `aiohttp` -- already ships with ComfyUI, which is why `dependencies` in `pyproject.toml` is empty.
+
+Then:
+
+1. **Restart ComfyUI.** Python changed.
+2. **Hard-refresh the browser** (Ctrl+Shift+R / Cmd+Shift+R). The editor is served from `/extensions/ComfyUI-Hand-Tie-Clips/`, and a stale cache is the single most common reason the node mounts with no UI on a fresh install.
+
+It is installed correctly when all three are true:
+
+- the startup log carries a line beginning `[HandTieClips]`
+- the browser console says `[HandTieClips] editor ui v1.5.0 loaded`
+- node search shows a **Hand Tie Clips** category with four nodes, each listed once
+
+Workflows saved before the 2026-08-29 rename keep loading: the old ids are still registered as deprecated aliases. Nothing needs migrating.
+
+The two example graphs are in `workflows/` inside the pack folder -- open them with the **Workflow > Open** menu, or copy them into `ComfyUI/user/default/workflows/` to have them in the sidebar. Start with `HandTieClips_Starter.json`; it ships with no references on purpose, so it runs before you have supplied any pictures.
+
+## Needs
+
+- ComfyUI new enough to include **Add Guide for MiniMax H3** (`MiniMaxH3AddGuide`)
+- A **ref2va** (or hybrid ref2va) checkpoint — fl2va has no reference rows
+- Video VAE + audio VAE + MiniMax text encoder
+- `ffmpeg` on PATH, if you turn `cache_hops` on
+- **Optional but recommended:** [ComfyUI-H3-Motion-Context](https://github.com/NikoDemon80/ComfyUI-H3-Motion-Context). Hops after the first are guided by the previous hop's sampler AV latent through it. Without it the node falls back to stock `MiniMaxH3AddGuide`, which still works and still chains -- it is a different join, so a seam you are comparing against someone else's render may not be the same code path. The node detects it at runtime and prints which one it took.
+
+The two shipped workflows wire the **turbo stack** this node is actually run with, because an example without it is not the graph anyone uses:
+
+```
+UNETLoader -> LoRA Loader Stack -> H3 AdaLN LoRA Fix -> MiniMax H3 Low VRAM
+           -> H3 SLA Attention -> Model Preview Override -> Hand Tie Clips
+```
+
+| pack | nodes |
+|---|---|
+| [ComfyUI-PlagueKind-Nodes](https://github.com/PlagueKind/ComfyUI-PlagueKind-Nodes) | LoRA Loader Stack, H3 AdaLN LoRA Fix, H3 SLA Attention |
+| [ComfyUI-KJNodes](https://github.com/kijai/ComfyUI-KJNodes) | MiniMax H3 Low VRAM Attention (experimental), Model Preview Override |
+
+On disk as well: the **turbo LoRA** named in the loader stack, and `taeh3.safetensors` for the live preview (or set `tiny_vae` to `none`).
+
+Both shipped workflows are saved pointing at the exact files they were rendered with. These are quantised builds and are **not** the only ones that work -- any ref2va or hybrid ref2va set will do. Repoint the loaders at what you have; a loader showing an empty or red filename is naming a file you do not have, not a broken workflow.
+
+| loader | file the example names |
+|---|---|
+| `UNETLoader` | `minimax_h3_hybrid_fl2va_ref2va_b30-49-int8.safetensors` |
+| `CLIPLoader` | `qwen3vl_32b_minimax_h3_int8_convrot.safetensors` |
+| `VAELoader` (video) | `minimax_h3_video_vae_int8_convrot.safetensors` |
+| `VAELoader` (audio) | `minimax_h3_audio_vae_fp32.safetensors` |
+| LoRA Loader Stack | `minimax_h3_ref2v_turbo_4step_v0.1_comfyui_bf16.safetensors` |
+| `tiny_vae` | `taeh3.safetensors` (or `none`) |
+
+**CLIP reaches the node from the LoRA loader, not from the encoder** — that is what makes the text half of every LoRA land. Do not rewire it back.
+
+None of it is required by the node itself. Missing a pack, its nodes load as red boxes: delete them, wire the loader straight into `model` and the encoder into `clip`, and raise `steps` from 7 to around 20.
+
+## Use
+
+1. Restart ComfyUI and load **`workflows/HandTieClips_Starter.json`** — two hops, no references, runs as soon as the loaders are pointed at your files. It carries a six-card **READ ME** board on its own canvas, to the left of the loaders: the three laws, the directive table, the reference rules and the failure table, where you need them rather than in another file. `workflows/HandTieClips_Showcase.json` is the six-hop version and needs three pictures of your own. Both carry the turbo stack listed above.
+2. Point the loaders at your ref2va DiT, encoder, and both VAEs
+3. Add a row per identity still in the **REFERENCES** rail, then **drop a picture onto its thumbnail** (or click to browse, or pick one already uploaded). Give it a `@tag` and group photos of the same person under one subject number. There are no `Load Image` nodes to wire — files land in `ComfyUI/input/h3_refs`.
+4. In **SHOTS**, write one card per hop. Shot 1 is the whole opening; every later card is only the new beat.
+5. Optional: a `voice_file`, a `start_image_file`, a look `reference_video_file` — all picked in the **MEDIA** strip, all files under `input/h3_refs`
+6. Queue, and wire the **`info`** output to a Preview Text node — it prints the fully assembled prompt for every hop
+
+Keep later-hop beats on **what happens next**. Do not re-describe the face; the photos, the register and the pin already carry it.
+
+Two modes:
+
+- **Simple** — one prompt box and a hop count, the way it always worked. Later hops advance the same action rather than replaying the opening.
+- **Shots** — one card per hop with directives. Switching from Simple carries your prompt over and splits it on `---`.
+
+Only one of them is on screen at a time, so there is never a text box quietly doing nothing.
+
+Under the script sits **RUN**, collapsed, holding everything that is not per-shot: output size and length, sampling, the join and pin controls, and the hop cache. Its title line summarises the run — `1.0 MP 16:9 · 10s ×3 · 14 steps res_multistep · cache off` — so you can read the setup without opening it. In Shots mode `chains` and `hop_script` are not offered there, because the shot list already decides both.
+
+**`tone_compensate`** lives in that panel's *join & pin* group. The H3 denoiser biases each hop's tone, so a chain gets steadily brighter; this measures the bias on the overlap each hop regenerated and undoes it, correcting each hop against the previous **corrected** one so the whole chain lands on hop 1's tone. `frame_shift` is the mode to reach for: all three modes remove the drift equally well (within 0.4/255 of each other), but `gain_bias` and `lut` pair pixels between a frame and its *regeneration*, which fits a slope that is not really there and flattens contrast a little more with every hop. `frame_shift` uses frame averages only, so it can shift but never distort. **Measured on a 3-hop render: chain drift 5.6/255 without it, 0.3/255 with it.** Worth turning on for anything past two hops. It ships off because enabling it also clamps the master to 0..1, and because the correction grows with hop count — by hop 10 it is subtracting ~23/255 and will start crushing blacks. Switching modes never invalidates the hop cache, so it is free to A/B. Do **not** judge it by whether the seams flatten to zero: real scene brightness changes across a cut should survive, and they do.
+
+## Shot plan
+
+The cards write this; you rarely see it. It is under **JSON** on the node if you want to copy a plan between workflows.
+
+```json
+{
+  "shots": [
+    {
+      "beat": "The cook stands at the counter, looks up, and speaks one short line.",
+      "directives": {"camera": "hold", "framing": "medium", "pace": "steady", "tail": "ongoing"}
+    },
+    {
+      "beat": "The cook sets the knife down and turns toward the window, still talking.",
+      "directives": {"join": "continuous", "camera": "push_in", "framing": "close"}
+    }
+  ]
+}
+```
+
+Shot 1 is the whole opening. Every later shot is **only the new beat** — the node supplies the identity lock, the live-frame citation and the join itself.
+
+Fields, all optional except `beat`:
+
+| | |
+|---|---|
+| `beat` | What happens this hop. |
+| `directives` | The five axes below. |
+| `prose` | Free text appended verbatim, for anything the vocabulary lacks. |
+| `seed`, `steps`, `duration` | Per-shot overrides. `duration` takes the same labels as the widget (`"8 s"`). |
+| `locked` | Reuse this shot's cached render even when its inputs changed. Needs `cache_hops=on`. |
+| `id` | Stable name, used as the cache pointer. Generated if absent. |
+
+### Directives
+
+| axis | options |
+|---|---|
+| `join` | `continuous`, `match_cut`, `hard_cut` — ignored on shot 1, which has nothing to join to |
+| `camera` | `hold`, `pan_follow`, `push_in`, `pull_back`, `orbit`, `handheld` |
+| `framing` | `keep`, `wide`, `medium`, `close` |
+| `pace` | `slow`, `steady`, `brisk` |
+| `tail` | `ongoing` (default), `settle`, `hold` |
+
+An unset axis emits nothing rather than asserting a default, so it costs no tokens.
+
+**Everything is phrased affirmatively, on purpose.** Sampling runs at cfg 1.0 with no negative branch, so every concept named is additive — "no cut" puts the word `cut` in front of the encoder. If you add prose of your own, say what the shot *is* doing.
+
+`join=continuous` together with a framing change and a held camera will warn: with the camera still, the only way to reach a new framing is a cut, so the two are asking for opposite things. Use `push_in` / `pull_back` / `pan_follow` to earn the framing on the move, or `framing: keep`.
+
+A camera move that points the opposite way from the framing (`push_in` with `wide`, `pull_back` with `close`) warns too -- those are physically contradictory whatever the join.
+
+When `join=continuous` and the camera *is* moving, the framing sentence is compiled as a **landing** ("The move settles into a close shot...") rather than as the shot's opening state, so it does not fight the pin that still holds the previous framing.
+
+## Writing beats
+
+> The full authoring guide, including how to have a model write plans for you, is **[PROMPTING.md](PROMPTING.md)**. What follows is the short version.
+
+Sampling runs at cfg 1.0 with no negative branch, so **the prompt is additive:
+anything you name is added, and nothing can be removed by mentioning it.** Three
+rules follow, each confirmed against renders rather than reasoned from the code.
+
+**Point the action line at the reference you want used.** Describing a reference
+in the register is not enough -- the beat is what drives the frame. Write the tag
+into the action:
+
+```
+The cook stands at the counter in @kitchen, looks up from the chopping board,
+and speaks one short line to someone off-frame.
+```
+
+`@kitchen` resolves to the right `<Picture N>` on every hop it is active, so
+rewiring references never breaks the text. Phrase it as a place that is depicted,
+not as a container to be placed inside -- otherwise you can get a literal
+composite of the photograph.
+
+**Never name the thing you want to end.** `The cook stops talking` keeps her
+talking. Describe the state you want as a pose plus a sound:
+
+```
+The cook leans back against the counter with her lips closed, and lets her eyes
+move slowly across the room. The kitchen is quiet apart from the hum of the
+refrigerator and faint street noise through the window.
+```
+
+H3 generates audio for the whole hop no matter what, so silence must be written
+as a sound -- room tone, a fridge, traffic. Written as an absence, you get speech.
+
+**Put a state change at the end of the previous shot.** Every hop after the first
+opens by holding the frames it was handed, and the audio pin carries the tail of
+the previous hop across the join. If shot 2 ends mid-sentence, no wording in shot
+3 will make it start quiet. Finish the line where it actually finishes:
+
+```
+shot 2: The cook sets the knife down, turns toward the window, and finishes her
+        last word as she looks out.
+shot 3: The cook leans back against the counter with her lips closed...
+```
+
+To be silent, still, or somewhere else in a shot, arrive there before the
+previous shot ends.
+
+**Pick ambience that is narrowband and specific.** After the first shot, official
+soundscape fields are stripped and ambience is plain prose, so the exact words
+matter. "faint street noise through the window" is broadband and renders as a
+five-second hiss; "the low hum of the refrigerator" does not. If a continuous bed
+still misbehaves, name a single discrete event instead -- "a single click from the
+refrigerator, then stillness".
+
+**Set `tail` on your last shot.** `settle` and `hold` change the final sentence of
+the prompt, which governs the terminal state of the clip. Left on `ongoing`, the
+model is told action is still underway at the final frame and will invent
+something to satisfy it -- on a last shot that means a stray gesture or a stray
+line of dialogue in the closing second.
+
+## Reference register
+
+```json
+{
+  "refs": [
+    {"tag": "hero_face",   "file": "cook_face.jpg",   "subject": 1, "retention": "fully_preserved"},
+    {"tag": "hero_outfit", "file": "cook_apron.jpg",  "subject": 1, "retention": "partially_copy"},
+    {"tag": "kitchen",     "file": "kitchen_wide.jpg", "retention": "reference"}
+  ],
+  "subjects": {
+    "1": {"name": "the cook", "locked": "the same face, the same short dark hair"}
+  }
+}
+```
+
+`file` is a picture in `ComfyUI/input/h3_refs`, set by the rail. `tag` is what you write in your beats — `@hero_face` — and the node resolves it to the right `<Picture N>` **per hop**, so pulling a still out of the middle no longer breaks every later reference.
+
+`subject` groups pictures per person. This matters: declaring every picture as a photo of `<Subject 1>` makes the model render the *average* of two different people.
+
+`retention` says how much of a picture carries over — `fully_preserved` (face and bone structure exactly), `partially_copy` (the garment and its cut), `reference` (layout, surfaces and light, i.e. a place). Refs with a subject default to `fully_preserved`; everything else defaults to `reference`.
+
+Add `"shots": [1, 2]` to a ref to keep it out of the hops it does not belong in. On a continuation chain (`hop_script=next` / a shot plan), omitting `shots` means **hop 1 only** — right for a place plate, which beats the pin if it rides a hop set somewhere else. **Put face plates on every hop:** a hop with no face reference comes back a different person and no later hop recovers.
+
+## Hop cache
+
+`cache_hops=on` writes every rendered hop to ComfyUI's temp dir as lossless FFV1 video plus a float32 `.npy` waveform, evicting least-recently-used above `cache_budget_gb`. The key is chained and includes the model fingerprint and, per hop, which pin mechanism was used -- a hop pinned by the AddGuide fallback is not the same render as one pinned by Motion-Context.
+
+The key **chains** — each hop's key includes the previous hop's — because hops are causally dependent. So:
+
+- edit shot 3 and re-queue → shots 1 and 2 load from cache, only 3 renders;
+- edit shot 1 → all three re-render, which is correct, not a bug;
+- change resolution, sampler, a reference still, a LoRA, or an attention setting → the whole chain re-renders.
+
+That last one is worth knowing about. The node cannot read the settings on your LoRA and attention nodes, so instead it fingerprints what they *did* to the model — which weight keys were patched, at what strengths, and the attention overrides. Change a LoRA strength and the cache correctly invalidates. Two different LoRAs touching exactly the same keys at exactly the same strengths would look identical to it; that is the one gap.
+
+Set `locked: true` on a shot to pin it to its last render regardless. Needs `ffmpeg` on PATH.
+
+## The MODEL wire
+
+Four ordinary nodes, in this order:
+
+    UNETLoader → LoRA stack (mode=minimax) → H3 AdaLN Fix → MiniMax Low VRAM Attention → H3 SLA Attention → H3 Ref2VA Chain
+
+**Take CLIP from the LoRA loader's second output**, not straight from the encoder, or the text-side keys H3 LoRAs carry are silently dropped.
+
+They briefly lived inside this node as a `model_patches` JSON widget. That made the graph shorter and the node harder to read, so it was reverted — these belong where you can see them.
+
+## Pinning the previous hop
+
+Three widgets tune the pin, all defaulting to their pre-existing behaviour:
+
+| widget | default | what it does |
+|---|---|---|
+| `audio_pin_frames` | `24` | Audio context handed to the pin, in frames. 24 is one second on the model's 40 Hz grid. Longer audio context costs conditioning rows but **no delivered frames**, so it is the cheap lever on speech that breaks across a join — try `96` (4 s) for continuous dialogue. |
+| `pin_renorm` | `off` | Rescales each pinned latent so its spread matches the one hop 2 established. The pin's own sigma climbs hop over hop and that inflated pin conditions the next one, so texture ratchets along a long chain. A scalar rescale moves no structure, so it cannot blur detail. Video and audio are corrected separately — their sigmas drift by different amounts. Worth turning on for 3+ hops. |
+| `pin_noise` | `0.0` | Mixes seeded noise into the pin — the other half of the same fix. Small values only; measured gains reverse above `0.10`, which is why the range stops there. |
+
+The DiT pin is the previous hop’s **sampler latent** through Motion-Context when present (no decode/re-encode; audio window ends at the join). AddGuide on decoded frames is the fallback. `pin_to_qwen` still shows the incoming state to the text encoder:
+
+| | |
+|---|---|
+| `off` | Pin stays DiT-only. |
+| `last frame` (default) | Previous hop's last frame is `<Picture 1>`. Identity stills that still ride this hop shift to Picture 2+. |
+| `pin clip` | Overlap frames become an extra `<Video>` at ~2 fps. No soundtrack on it, so `voice` stays `<Audio 1>`. |
+| `both` | Last frame + pin clip. |
+
+`@tags` in beats resolve per hop, so stills shifting to Picture 2+ does not break prose. Literal `<Picture N>` in hop 2+ beats would.
+
+## Defaults
+
+| | |
+|---|---|
+| resolution | 1.0 MP (1280×736 landscape) |
+| duration | 10 s (243 frames) |
+| overlap | 0.9 s (22 frames) |
+| steps | 8, with a 4-step turbo LoRA — the regime this node targets |
+| sampler / scheduler | `res_multistep` / `beta` |
+| seed per hop | on |
+| sigma shift | 12 / 3 |
+| cache budget | 20 GB |
+
+Three shots at 10 s with a 0.9 s overlap is about 28 s of master after the overlap is dropped.
+
+## Limits
+
+- **A workflow saved before 2026-08-28 loses its reference pictures.** The old `ref_image_N` sockets carried tensors, so there is no filename to recover. The rail names each affected ref and asks you to pick its picture; nothing else about the plan is lost.
+- There is no shot-level `refs` field. Activation lives on the reference: give a ref a `shots` list, or use the per-hop chips on its row in the rail.
+- The reference `desc` and subject `locked` text go to the encoder verbatim, every hop. At cfg 1.0 there is no negative branch, so a detail that is not in the photograph is **asked for**, not ignored. Describe what you actually wired.
+- `HTCContinuityState` is **setting only**. Characters live in the reference register; the node's `characters_*` fields were removed because filling in both injected identity text twice.
+- Each join hard-cuts video but crossfades audio ~40 ms, so A/V drifts ~40 ms per hop.
+- Texture still ratchets on long chains. Stay around 3–5 hops until that is handled.
+- A 22-frame pin clip is ~2 Qwen frames at 2 fps. It is a live-state hint, not a full previous-clip watch.
+- A longer overlap does not fix continuity — it can pin whatever content happens to be in that longer tail.
+
+## Nodes
+
+**H3 Ref2VA Chain** — `images`, `audio`, `info` out. Wire `CreateVideo` + `SaveVideo` as in the example workflow, and `info` to a Preview Text node.
+
+**H3 Chain Preview** — a passthrough panel for the IMAGE (and optionally AUDIO) wire, placed **between the chain and `CreateVideo`**. Images and audio come out unchanged, so adding or removing it changes no pixels. It shows the live sample, the seam (the previous hop's last frame beside this hop's first), a chain-wide progress bar, cache hit / seed / steps per hop, **which pin mechanism each hop actually used** — a latent Motion-Context pin or the AddGuide pixel fallback — and end-of-run A/V drift. Drag the grip to resize the stats panel; double-click it to reset.
+
+**H3 Tone Compensate** — `images` out. Corrects a generated segment's tone against the previous one, estimated on the overlap they share. **For hand-built chains only.** It cannot fix `H3 Ref2VA Chain`'s output: that node joins its hops internally and drops each hop's first `overlap` frames at the seam, so the regenerated copies this needs are already gone by the time images leave it. Use the chain node's `tone_compensate` widget instead. Estimator ported from [rkfg/ComfyUI-MiniMaxH3-ToneCompensate](https://github.com/rkfg/ComfyUI-MiniMaxH3-ToneCompensate) (MIT).
+
+**H3 Continuity State** — `continuity_state` (STRING) out. **Setting only**: `setting_locked` / `setting_context` / `setting_mutable`. Characters belong in `ref_plan`.

__init__.py

@@ -0,0 +1,28 @@
+"""Hand Tie Clips — native MiniMax H3 Ref2VA continuation for ComfyUI."""
+from .h3_ref_chain import NODE_CLASS_MAPPINGS, NODE_DISPLAY_NAME_MAPPINGS
+from .preview_node import (
+    NODE_CLASS_MAPPINGS as _PREVIEW_NODES,
+    NODE_DISPLAY_NAME_MAPPINGS as _PREVIEW_NAMES,
+)
+from .tone import (
+    NODE_CLASS_MAPPINGS as _TONE_NODES,
+    NODE_DISPLAY_NAME_MAPPINGS as _TONE_NAMES,
+)
+
+NODE_CLASS_MAPPINGS.update(_PREVIEW_NODES)
+NODE_DISPLAY_NAME_MAPPINGS.update(_PREVIEW_NAMES)
+NODE_CLASS_MAPPINGS.update(_TONE_NODES)
+NODE_DISPLAY_NAME_MAPPINGS.update(_TONE_NAMES)
+
+# The editor's dropdowns are served from directives.VOCAB rather than copied
+# into JS. A failure here costs the dropdowns their tooltips, not the node, so
+# it must never stop the pack from loading.
+try:
+    from . import routes as _routes
+    _routes.register()
+except Exception as _exc:  # noqa: BLE001
+    print(f"[HandTieClips] vocab route not registered: {_exc!r}", flush=True)
+
+WEB_DIRECTORY = "./js"
+
+__all__ = ["NODE_CLASS_MAPPINGS", "NODE_DISPLAY_NAME_MAPPINGS", "WEB_DIRECTORY"]

directives.py

@@ -0,0 +1,344 @@
+"""Directive vocabulary for H3 Ref Chain shot plans.
+
+WHY THIS MODULE EXISTS
+----------------------
+MiniMax H3 output is overwhelmingly carried by the prompt text, not by the
+conditioning channels. Hand-writing continuity prose per shot does not scale and
+drifts: every chain re-invents its own phrasing, so nothing learned on one chain
+carries to the next. Structured directives compile to vetted prose instead, and
+because every string lives in VOCAB below, improving the phrasing improves every
+existing shot plan at once.
+
+PHRASING RULES -- read before editing VOCAB
+-------------------------------------------
+1. AFFIRMATIVE ONLY. Sampling runs through BasicGuider at cfg 1.0 with no
+   negative branch, so every concept named is additive and cannot be subtracted.
+   "no cut" puts `cut` in front of the encoder. Say what the shot IS doing.
+2. NO PRONOUNS. The beat text owns the subject. A pronoun here can disagree with
+   it -- plural "they" has been observed rendering two people from one reference.
+3. NO ENUMERATED DETAIL. Naming a prop or garment to control it adds it. Keep
+   directives about camera, join, framing, and pace only.
+4. ONE SENTENCE PER ENTRY. These get concatenated; long entries crowd the beat.
+"""
+
+import re
+
+# axis -> option -> prose. An option of "" (unset) emits nothing, deliberately:
+# an unset axis should cost no tokens rather than assert a default.
+VOCAB = {
+    "join": {
+        "continuous": "The camera and the action carry straight on from the pinned "
+                      "frames in one unbroken take.",
+        "match_cut":  "The shot changes on a matched movement, the new framing "
+                      "picking up the same gesture already underway.",
+        "hard_cut":   "A clean cut opens a new setup, the same place a moment later.",
+    },
+    "camera": {
+        "hold":       "The camera holds its position throughout.",
+        "pan_follow": "The camera pans smoothly to follow the movement, holding it in frame.",
+        "push_in":    "The camera pushes slowly in.",
+        "pull_back":  "The camera draws slowly back, opening the frame.",
+        "orbit":      "The camera arcs slowly around the action.",
+        "handheld":   "The camera carries a light handheld float.",
+    },
+    "framing": {
+        "keep":   "The framing stays as it is.",
+        "wide":   "A wide shot with the full room in view.",
+        "medium": "A medium shot from the waist up.",
+        "close":  "A close shot, head and shoulders filling the frame.",
+    },
+    "pace": {
+        "slow":   "Everything moves at an unhurried pace.",
+        "steady": "The action moves at a steady, even pace.",
+        "brisk":  "The action moves briskly.",
+    },
+    # How the clip ENDS. This axis exists because a beat whose action
+    # completes before the frames run out leaves the model with nothing to
+    # render, and it settles onto its strongest remaining conditioning --
+    # the identity photograph. Observed as the last ~3s of a chain cutting
+    # to the reference still. `ongoing` is the default for exactly that
+    # reason: it gives the tail somewhere to go that is not the ref.
+    "tail": {
+        "ongoing": "The action is still underway as the clip ends.",
+        "settle":  "The movement eases to a rest and stays there.",
+        "hold":    "The final position holds steady through the last moments.",
+    },
+}
+
+# B2 (2026-08-27). When `join=continuous` and the camera is moving, the framing
+# sentence has to describe where the move ENDS, not what the shot opens on.
+# Asserting the destination as the opening state while the pin still holds the
+# previous hop's framing is what put the jump at the 2->3 seam of chain_00028:
+# the compile read "...carry straight on from the pinned frames. The camera
+# pushes slowly in. A close shot, head and shoulders filling the frame."
+#
+# Affirmative, one sentence, no pronouns -- same rules as the rest of VOCAB.
+# Set FRAMING_AS_LANDING = False to restore the pre-2026-08-27 phrasing; that
+# is the A/B against chain_00038.
+FRAMING_AS_LANDING = True
+_FRAMING_LANDING = {
+    "wide":   "The move settles into a wide shot with the full room in view.",
+    "medium": "The move settles into a medium shot from the waist up.",
+    "close":  "The move settles into a close shot, head and shoulders filling the frame.",
+}
+# "hold" is not a move, and "keep" needs no landing -- it already says the
+# framing does not change.
+_CAMERA_MOVES = ("pan_follow", "push_in", "pull_back", "orbit", "handheld")
+
+# Order matters: this is the order the compiled sentences appear in the prompt.
+# `join` leads because it describes how this hop meets the previous one.
+AXES = ("join", "camera", "framing", "pace", "tail")
+
+# Applied when a shot names no value for the axis. Only `tail` carries one:
+# every other axis is legitimately "unspecified", but an unspecified tail is
+# what lets the clip settle onto the reference image.
+DEFAULTS = {"tail": "ongoing"}
+
+# Opening line for hop 1, which has no previous hop to join to.
+#
+# 2026-08-29. This is the DEFAULT, not a constant. It used to be prepended to
+# every hop-1 prompt unconditionally, which is correct for the live-action
+# plans the pack shipped with and actively wrong for anything else: at cfg 1.0
+# with no negative branch "Live-action" and "natural light" are ADDED, ahead of
+# whatever style the beat declares. A stop-motion puppet plan compiled to
+#
+#     Live-action, natural light, one continuous take.
+#     ...
+#     Hand-drawn stop-motion puppet animation in felt and painted wood ...
+#
+# and the two fought. It is also the reason hop 1 of the 8x15 s anime chain
+# rendered as bright naturalistic daylight (mean luma 72) against a night plan
+# and a night place plate, then dropped to 46 on hop 2 the moment this line
+# stopped riding.
+#
+# Two fixes, because either alone leaves a hole. The node exposes an
+# `establish` widget so a human can set or clear it; and `establish_for` below
+# drops it automatically when the beat names a medium of its own, because a
+# model-authored plan never touches a widget.
+ESTABLISH = "Live-action, natural light, one continuous take."
+
+# Media that contradict ESTABLISH's "Live-action". Matched against the opening
+# of shot 1 only -- a beat that says "a photograph of a painting" later on is
+# describing a prop, not declaring its own medium.
+_STYLE_WORDS = (
+    "anime", "animation", "animated", "cartoon", "cel ", "cel-",
+    "stop-motion", "stop motion", "claymation", "clay-mation", "puppet",
+    "watercolour", "watercolor", "gouache", "oil-painted", "oil painted",
+    "hand-drawn", "hand drawn", "illustrated", "illustration", "storyboard",
+    "pixel art", "cgi", "3d render", "3d-render", "rendered in", "rotoscope",
+    "comic", "manga", "woodcut", "linocut", "papercraft", "paper-craft",
+)
+# How far into the beat to look. Rule 12 asks for the style in the first
+# sentence; 220 characters covers a generous one without reaching the action.
+_STYLE_WINDOW = 220
+
+
+def declares_own_medium(beat):
+    """True when shot 1 opens by naming a medium that is not live action.
+
+    Deliberately narrow. It reads only the opening of the beat, and it defers
+    to an explicit "live-action" there, so a plan that means live action keeps
+    the establishing line even when it also mentions, say, an animated sign in
+    the background.
+    """
+    head = (beat or "")[:_STYLE_WINDOW].lower()
+    if "live-action" in head or "live action" in head:
+        return False
+    return any(w in head for w in _STYLE_WORDS)
+
+
+def establish_for(beat, establish=None):
+    """The establishing line to prepend to hop 1, or "" for none.
+
+    `establish=None` means "the node did not say", which is every caller that
+    predates the widget -- those keep the historical default.
+    """
+    line = ESTABLISH if establish is None else str(establish or "").strip()
+    if line and declares_own_medium(beat):
+        return ""
+    return line
+
+
+def validate(axis, value, where=""):
+    """Raise ValueError naming the offending shot and the valid options."""
+    v = str(value or "").strip()
+    if not v:
+        return ""
+    if v not in VOCAB[axis]:
+        valid = ", ".join(sorted(VOCAB[axis]))
+        raise ValueError(
+            f"HandTieClips: {where}directive {axis}='{v}' is not valid. Use one of: {valid}"
+        )
+    return v
+
+
+def directive_prose(directives, hop_index, axes=None):
+    """Compile a shot's directives into prose. Hop 1 has nothing to join to."""
+    d = directives or {}
+    out = []
+    for axis in (axes or AXES):
+        if axis == "join" and hop_index == 0:
+            continue
+        value = str(d.get(axis) or "").strip() or DEFAULTS.get(axis, "")
+        line = VOCAB.get(axis, {}).get(value)
+        if (axis == "framing" and FRAMING_AS_LANDING and hop_index > 0
+                and str(d.get("join") or "").strip() == "continuous"
+                and str(d.get("camera") or "").strip() in _CAMERA_MOVES
+                and value in _FRAMING_LANDING):
+            line = _FRAMING_LANDING[value]
+        if line:
+            out.append(line)
+    return " ".join(out)
+
+
+_OFFICIAL_FIELDS = (
+    "subject_definitions:",
+    "summary:",
+    "retention_analysis:",
+    "detailed_description:",
+    "integrated_multimodal_description:",
+    "overall_soundscape:",
+    "non_diegetic_music:",
+)
+
+def append_section_line(text, name, line):
+    """Append a line to the end of an official field. No-op when absent.
+
+    Carries a hop-1 `tail` directive into a complete six-field block: `tail`
+    describes how the clip *ends*, so it belongs at the end of
+    detailed_description rather than wrapped around the outside, where it
+    would fight the official fields.
+    """
+    t = text or ""
+    line = str(line or "").strip()
+    if not line or line in t:
+        return t
+    marker = name if name.endswith(":") else name + ":"
+    start = t.find(marker)
+    if start < 0:
+        marker = "integrated_multimodal_description:"
+        start = t.find(marker)
+        if start < 0:
+            return t
+    end = len(t)
+    for other in _OFFICIAL_FIELDS:
+        if other == marker:
+            continue
+        i = t.find(other, start + len(marker))
+        if i != -1:
+            end = min(end, i)
+    return t[:end].rstrip() + "\n" + line + "\n\n" + t[end:].lstrip()
+
+
+def is_full_h3_prompt(text):
+    t = text or ""
+    return "subject_definitions:" in t or "integrated_multimodal_description:" in t
+
+
+def field_body(text, name):
+    """Inner text of one official field, or ''."""
+    t = text or ""
+    marker = name if str(name).endswith(":") else str(name) + ":"
+    start = t.find(marker)
+    if start < 0:
+        return ""
+    end = len(t)
+    for other in _OFFICIAL_FIELDS:
+        if other == marker:
+            continue
+        i = t.find(other, start + len(marker))
+        if i != -1:
+            end = min(end, i)
+    return t[start + len(marker):end].strip()
+
+
+def flatten_official_continue(body):
+    """Hop 2+ cannot be a complete Ref2VA generate (chain_00030..00032).
+
+    Keep the action + soundscape. Drop subject_definitions / summary /
+    retention_analysis and a leading [Shot 1] — those start a new scene.
+    """
+    if not is_full_h3_prompt(body):
+        return body
+    dd = (field_body(body, "detailed_description")
+          or field_body(body, "integrated_multimodal_description")
+          or "")
+    dd = re.sub(r"^\[Shot 1\]\s*", "", dd.strip())
+    for prefix in (
+        "The clip opens already in progress from the pinned frames, "
+        "continuing the scene they leave off. ",
+        "The clip opens already in progress from the pinned frames. ",
+        "The clip opens on the action already in progress from the pinned frames. ",
+    ):
+        if dd.startswith(prefix):
+            dd = dd[len(prefix):].lstrip()
+            break
+    parts = []
+    if dd:
+        parts.append(dd)
+    sound = field_body(body, "overall_soundscape")
+    if sound:
+        parts.append("overall_soundscape:\n" + sound)
+    music = field_body(body, "non_diegetic_music")
+    if music:
+        parts.append("non_diegetic_music:\n" + music)
+    return "\n\n".join(parts)
+
+
+def compile_shot(shot, hop_index, establish=None):
+    """Build the body text for one hop.
+
+    Returns the *beat* portion only. For hop 2+ the caller wraps this with the
+    identity lock and live-frame citation via _assemble_next, so this must not
+    duplicate either of those.
+
+    Hop 1 may be a complete official H3 block and is returned intact. Hop 2+
+    of a complete block is flattened to a continuation beat — a second full
+    Ref2VA generate is a new scene (chain_00030..00032).
+    """
+    beat = str((shot or {}).get("beat") or "").strip()
+    prose = str((shot or {}).get("prose") or "").strip()
+    body = "\n\n".join(p for p in (beat, prose) if p)
+    dirs = (shot or {}).get("directives")
+    if is_full_h3_prompt(body):
+        if hop_index == 0:
+            # A complete six-field block is one generate and is returned
+            # intact -- lead directives would fight its own field text. `tail`
+            # is the exception: one affirmative sentence about how the clip
+            # ends, which is what stops the last seconds settling onto a
+            # reference still, so it is appended inside detailed_description
+            # rather than dropped. The rest are reported, because silently
+            # ignoring dropdowns the editor still renders is how this went
+            # unnoticed.
+            body = append_section_line(
+                body, "detailed_description",
+                directive_prose(dirs, hop_index, axes=("tail",)))
+            ignored = sorted(
+                a for a in ("join", "camera", "framing", "pace")
+                if str((dirs or {}).get(a) or "").strip())
+            if ignored:
+                print("[HandTieClips] shot 1 is a complete H3 block; its own fields "
+                      "win, so these directives are not applied: " + ", ".join(ignored),
+                      flush=True)
+            return body
+        beat = flatten_official_continue(body)
+        prose = ""
+    lead = directive_prose(dirs, hop_index, axes=("join", "camera", "framing", "pace"))
+    tail = directive_prose(dirs, hop_index, axes=("tail",))
+
+    parts = []
+    if hop_index == 0:
+        # `beat` is shot 1's own text, so a plan that declares its own medium
+        # suppresses the live-action default rather than fighting it.
+        opening = establish_for(beat, establish)
+        if opening:
+            parts.append(opening)
+    if lead:
+        parts.append(lead)
+    if beat:
+        parts.append(beat)
+    if prose:
+        parts.append(prose)
+    if tail:
+        parts.append(tail)
+    return "\n\n".join(parts)

h3_ref_chain.py

@@ -0,0 +1,1943 @@
+"""Native MiniMax H3 Ref2VA chain: several generates joined into one clip.
+
+Hop 1 is a full Ref2VA generate and may carry an official six-field H3 prompt.
+Hop 2+ is a *continuation*, not a second generate: a continuation beat with the
+previous hop pinned in front of it.
+
+The pin is the whole point. Hop 2+ slices the previous hop's sampler AV latent
+through MiniMaxH3MotionContext, which keeps the join in the latent domain and
+end-aligns the audio window. MiniMaxH3AddGuide on decoded pixels is the
+fallback -- taken when Motion-Context is missing, or when the previous hop came
+from the cache and so has no sampler latent to slice.
+
+Authoring is `shot_plan` + `ref_plan`, both JSON strings, both edited by the DOM
+panel in js/ and both the single source of truth. The legacy `prompt` widget
+(optional --- / JSON blocks) still runs for `hop_script=verbatim`.
+"""
+from __future__ import annotations
+
+import base64
+import hashlib
+import queue
+import threading
+import io as pyio
+import json
+import math
+import os
+import re
+
+import torch
+
+try:
+    from server import PromptServer
+except Exception:
+    PromptServer = None
+
+import comfy.model_management as mm
+import comfy.samplers
+import comfy.utils
+from comfy_extras.nodes_audio import vae_decode_audio
+from comfy_extras.nodes_custom_sampler import (
+    BasicGuider,
+    BasicScheduler,
+    KSamplerSelect,
+    RandomNoise,
+    SamplerCustomAdvanced,
+)
+try:
+    from comfy_extras.nodes_minimax_h3 import (
+        MiniMaxH3AddGuide,
+        MiniMaxH3ReferenceToVideo,
+        MiniMaxH3SigmaShift,
+        align_frame_count,
+    )
+except ImportError as _exc:  # pragma: no cover - depends on the host build
+    # The one failure a first-time installer is actually likely to hit. Left
+    # bare it surfaces as "cannot import name 'MiniMaxH3AddGuide'", which says
+    # nothing about what to do. The pack cannot work without these, so it still
+    # refuses to load -- it just says why.
+    raise ImportError(
+        "Hand Tie Clips needs MiniMax H3 support in ComfyUI itself "
+        "(comfy_extras/nodes_minimax_h3.py, ComfyUI PR #15439). Update ComfyUI "
+        "to a build that ships it, then restart. Original error: %s" % _exc
+    ) from _exc
+from nodes import VAEDecode
+
+from . import directives as _d
+from . import plan as _plan
+from . import refs as _refs
+from . import store as _store
+from . import media as _media
+from . import tone as _tone
+# One definition, in refs.py -- routes.py publishes that copy to the editor, so
+# a second constant here meant the node's slot count and the number the UI was
+# told could drift apart.
+from .refs import MAX_REF_IMAGES
+
+FPS = 24
+TAG = "HandTieClips"
+
+# H3 canvas: multiples of 32, short-edge ~768, area cap 768*1344.
+CANVAS = {
+    "0.2 MP": {
+        "16:9 landscape": (608, 352),
+        "9:16 portrait": (352, 608),
+        "1:1 square": (448, 448),
+    },
+    "0.3 MP": {
+        "16:9 landscape": (736, 416),
+        "9:16 portrait": (416, 736),
+        "1:1 square": (544, 544),
+    },
+    "0.5 MP": {
+        "16:9 landscape": (960, 544),
+        "9:16 portrait": (544, 960),
+        "1:1 square": (704, 704),
+    },
+    "0.7 MP": {
+        "16:9 landscape": (1120, 640),
+        "9:16 portrait": (640, 1120),
+        "1:1 square": (832, 832),
+    },
+    "1.0 MP": {
+        "16:9 landscape": (1280, 736),
+        "9:16 portrait": (736, 1280),
+        "1:1 square": (992, 992),
+    },
+}
+DURATION_FRAMES = {
+    # Every value satisfies align_frame_count (n % 17 == 5) at FPS 24, so the
+    # label and the frames the model actually renders agree to a tenth.
+    "5 s": 124,
+    "7 s": 175,
+    "8 s": 192,
+    "10 s": 243,
+    "15 s": 362,
+}
+OVERLAP_FRAMES = {
+    "0.9 s": 22,
+    "0.2 s": 5,
+    "1.6 s": 39,
+}
+# MiniMaxH3MotionContext.apply takes `context_length` as a *string* combo and
+# accepts only these values. Derived from OVERLAP_FRAMES so the two cannot
+# drift: add an overlap without a matching context_length and the pin would
+# silently clamp to 22 while the master trims the real value -- a misaligned
+# seam with no error. _pin_continue logs and falls back instead.
+MC_CONTEXT_LENGTHS = frozenset(str(v) for v in OVERLAP_FRAMES.values())
+
+
+def _canvas(resolution, aspect):
+    try:
+        return CANVAS[str(resolution)][str(aspect)]
+    except KeyError:
+        return (1280, 736)
+
+
+def _duration_frames(duration):
+    return int(DURATION_FRAMES.get(str(duration), 243))
+
+
+def _overlap_frames(overlap):
+    key = str(overlap)
+    if key in OVERLAP_FRAMES:
+        return OVERLAP_FRAMES[key]
+    return int(overlap)
+
+# Prompt phrasing rule: AFFIRMATIVE ONLY.
+# Sampling runs through BasicGuider at cfg 1.0 with no negative branch, so every
+# concept named in the prompt is additive and cannot be subtracted -- "Do not
+# restart the scene" puts `restart` in front of the encoder. State what the shot
+# IS doing, never what it must not do. Keep this rule when editing below.
+CONTINUE_PREFIX = (
+    "The clip opens on the action already in progress from the pinned frames. "
+    "The same people continue from where the pinned frames leave off, in the same "
+    "wardrobe, the same room, and the same lighting. "
+    "After a brief hold, the action carries forward from its current point.\n\n"
+)
+
+ADVANCE_BEAT = (
+    "The action already in progress carries forward from its current point."
+)
+
+MAX_REF_VIDEOS = 3
+
+
+def _result(out):
+    if hasattr(out, "args"):
+        return out.args
+    if isinstance(out, (tuple, list)):
+        return tuple(out)
+    return (out,)
+
+
+def _model_fingerprint(model):
+    """Identify the incoming MODEL by what has been patched onto it.
+
+    The hop cache has to notice when a hop was rendered under a different LoRA
+    stack or a different attention path, or it will happily serve frames that
+    do not belong to the current graph -- silently wrong output, which is worse
+    than no cache at all. When the patch nodes were a widget on this node the
+    parsed plan went into the key directly; with them drawn upstream the only
+    thing available is the ModelPatcher itself.
+
+    Cheap and content-derived: the set of weight keys any LoRA touched plus the
+    per-key strength scalars, and the scalar half of `transformer_options`,
+    which is where the SLA and low-VRAM attention overrides land. Patch *values*
+    are tensors and are deliberately not hashed.
+
+    `patches_uuid` is not usable here: `ModelPatcher.add_patches` assigns a
+    fresh `uuid4()` on every call, so it would change every run and bust the
+    cache even when nothing about the graph moved.
+
+    Known collision: two different LoRAs touching an identical key set at
+    identical strengths fingerprint the same. Rare, and the alternative costs a
+    full state-dict walk per run.
+    """
+    h = hashlib.sha256()
+    patches = getattr(model, "patches", None) or {}
+    for key in sorted(patches):
+        h.update(str(key).encode())
+        for entry in patches[key]:
+            # (strength_patch, weights, strength_model, offset, function)
+            try:
+                h.update(f"{float(entry[0]):.6g}".encode())
+                if len(entry) > 2 and isinstance(entry[2], (int, float)):
+                    h.update(f"{float(entry[2]):.6g}".encode())
+            except (TypeError, ValueError, IndexError):
+                h.update(b"?")
+
+    opts = getattr(model, "model_options", None) or {}
+    transformer = opts.get("transformer_options") or {}
+
+    def _closure_scalars(fn):
+        """The scalar settings a callable closed over.
+
+        H3-SLA-Attention installs its config by closure --
+        `_make_override(state, float(sparsity_ratio), blkq, blkk,
+        int(min_seq_len), bool(protect_audio))` -- so a callable rendered as
+        `type(fn).__name__` hashes to the bare string "function" and SLA's
+        settings vanish from the key. Changing sparsity 0.90 -> 0.50 then left
+        the fingerprint unmoved and the cache served hops rendered under a
+        different attention path.
+
+        Scalars only, deliberately: the first cell is a mutable `state` dict the
+        sampler counts into during the run, and hashing that would change the
+        fingerprint on every queue and never hit the cache at all.
+        """
+        parts = [getattr(fn, "__qualname__", "") or getattr(fn, "__name__", "")]
+        for cell in (getattr(fn, "__closure__", None) or ()):
+            try:
+                v = cell.cell_contents
+            except ValueError:  # empty cell, e.g. a recursive closure
+                parts.append("?")
+                continue
+            parts.append(repr(v)
+                         if isinstance(v, (str, int, float, bool)) or v is None
+                         else type(v).__name__)
+        return "fn(" + ",".join(parts) + ")"
+
+    def _scalars(obj, depth=0):
+        """Only names and scalars -- tensors and mutable state are not stable."""
+        if depth > 3:
+            return "..."
+        if isinstance(obj, dict):
+            # sorted(obj, key=str), not sorted(map(str, obj)): stringifying the
+            # keys first drops every non-str key from the hash, because the
+            # `k in obj` guard then fails against the real key.
+            return "{" + ",".join(
+                f"{k}:{_scalars(obj[k], depth + 1)}" for k in sorted(obj, key=str)
+            ) + "}"
+        if isinstance(obj, (list, tuple)):
+            return "[" + ",".join(_scalars(v, depth + 1) for v in obj) + "]"
+        if isinstance(obj, (str, int, float, bool)) or obj is None:
+            return repr(obj)
+        if callable(obj):
+            return _closure_scalars(obj)
+        return type(obj).__name__
+
+    h.update(_scalars(transformer).encode())
+    return h.hexdigest()[:16]
+
+
+def _parse_shots(text):
+    text = (text or "").strip()
+    if not text:
+        raise ValueError(f"{TAG}: prompt is empty")
+    if text.startswith("{") or text.startswith("["):
+        try:
+            data = json.loads(text)
+        except json.JSONDecodeError as e:
+            raise ValueError(f"{TAG}: prompt looks like JSON but does not parse ({e})") from e
+        if isinstance(data, dict):
+            shots = [str(p).strip() for p in data.get("prompts", []) if str(p).strip()]
+        elif isinstance(data, list):
+            shots = [str(p).strip() for p in data if str(p).strip()]
+        else:
+            shots = []
+        if shots:
+            return shots
+    parts = [b.strip() for b in re.split(r"(?m)^---\s*$", text) if b.strip()]
+    return parts or [text]
+
+
+def _parse_state(text):
+    """continuity_state input: blank -> no-op, else a JSON object (from HTCContinuityState)."""
+    text = (text or "").strip()
+    if not text:
+        return {}
+    try:
+        data = json.loads(text)
+    except json.JSONDecodeError as e:
+        raise ValueError(f"{TAG}: continuity_state looks like JSON but does not parse ({e})") from e
+    if not isinstance(data, dict):
+        raise ValueError(f"{TAG}: continuity_state must be a JSON object")
+    return data
+
+
+def _continue_prompt(block):
+    """Wrap a verbatim-mode block as a continuation.
+
+    Never rewrite the official summary task types here. This used to replace
+    `[keyframe completion]` with `[video continuation + reference generation]`,
+    which is what made hop 2 of chain_00030/00031 a new stills generate instead
+    of a first-frame continue. Combine types with ` + `; never drop one that is
+    already present.
+    """
+    text = (block or "").strip()
+    if _d.is_full_h3_prompt(text):
+        text = _d.flatten_official_continue(text)
+    return CONTINUE_PREFIX + (text or ADVANCE_BEAT)
+
+
+def _expand_shots(blocks, chains, hop_script="verbatim"):
+    original = list(blocks)
+    if len(blocks) > chains:
+        print(f"[{TAG}] dropping {len(blocks) - chains} extra --- block(s)", flush=True)
+        blocks = blocks[:chains]
+    unique = len(original) if len(original) <= chains else chains
+    while len(blocks) < chains:
+        if hop_script == "next" and unique == 1:
+            blocks.append("")
+        else:
+            blocks.append(blocks[-1])
+    if hop_script == "next":
+        return blocks, unique
+    out = []
+    for i, block in enumerate(blocks):
+        wrap = i > 0 and (unique == 1 or i >= unique)
+        out.append(_continue_prompt(block) if wrap else block)
+    return out, unique
+
+
+def _state_entry_text(entry, hop_index):
+    """locked (verbatim) + context (current-state) + this hop's mutable beat."""
+    if not isinstance(entry, dict):
+        return ""
+    locked = str(entry.get("locked") or "").strip()
+    context = str(entry.get("context") or "").strip()
+    mutable = entry.get("mutable") or []
+    if isinstance(mutable, str):
+        mutable = _parse_shots(mutable) if mutable.strip() else []
+    mutable = [str(b).strip() for b in mutable if str(b).strip()]
+    beat = ""
+    if mutable:
+        idx = hop_index if hop_index < len(mutable) else len(mutable) - 1
+        beat = mutable[idx]
+    return "\n".join(p for p in (locked, context, beat) if p)
+
+
+def _state_header(state, hop_index):
+    """Compose the continuity_state block for this hop (locked/context every hop, mutable indexed)."""
+    if not state:
+        return ""
+    sections = []
+    setting_text = _state_entry_text(state.get("setting") or {}, hop_index)
+    if setting_text:
+        sections.append("setting:\n" + setting_text)
+    for char_id, entry in (state.get("characters") or {}).items():
+        char_text = _state_entry_text(entry, hop_index)
+        if char_text:
+            sections.append(f"character {char_id}:\n" + char_text)
+    return "\n\n".join(sections)
+
+
+def _identity_lock(n_stills, live_picture, identity_ordinals=None, n_subjects=None):
+    """Name the pictures that are people, and only those.
+
+    `identity_ordinals` comes from the reference register, which is the only
+    thing that knows a picture is a face rather than a room. Without it this
+    falls back to "every wired still is an identity", which is what it always
+    did and is right when nothing better is known -- but with a register wired
+    that fallback tells the encoder a photograph of a kitchen has a face and a
+    hairstyle to match exactly. At cfg 1.0 there is no negative branch, so that
+    is additive noise on every hop.
+
+    `n_subjects` drives number agreement, not the picture count: two
+    photographs of one person is still one identity.
+    """
+    ords = (list(identity_ordinals) if identity_ordinals is not None
+            else list(range(1, int(n_stills) + 1)))
+    if not ords:
+        # A register with no subject-bearing refs -- setting plates only. There
+        # is no identity to lock, and _live_cite still cites the live frame.
+        return ""
+    pics = ", ".join(f"<Picture {i}>" for i in ords)
+    count = int(n_subjects) if n_subjects is not None else len(ords)
+    # Qwen3-VL is a language encoder, so number agreement is not cosmetic:
+    # "<Picture 1> are the only identities" is what a single wired ref produced.
+    if count == 1:
+        line = (
+            f"{pics} is the only identity. That face, bone structure, and hairstyle "
+            "match the photograph exactly."
+        ) if len(ords) == 1 else (
+            f"{pics} are the same one person, and the only identity. That face, bone "
+            "structure, and hairstyle match those photographs exactly."
+        )
+    else:
+        line = (
+            f"{pics} are the only identities. Each face, bone structure, and hairstyle "
+            "matches its photograph exactly."
+        )
+    if live_picture and live_picture not in ords:
+        who = ("that same person as they stand" if count == 1
+               else "those same people as they stand")
+        line += f" <Picture {live_picture}> shows {who} right now, mid-action."
+    return line
+
+
+def _live_cite(live_picture, live_video):
+    bits = []
+    if live_picture:
+        bits.append(
+            f"<Picture {live_picture}> is the live frame at the start of this clip, "
+            "already in progress from the pinned tail."
+        )
+    if live_video:
+        bits.append(
+            f"<Video {live_video}> is the pinned tail of the previous clip and the first "
+            "moments of this generate. The motion continues at the speed it already has."
+        )
+    return " ".join(bits)
+
+
+def _assemble_next(beat, live_picture=None, live_video=None,
+                   n_stills=0, state_header="",
+                   identity_ordinals=None, n_subjects=None, tail=None,
+                   continuity=""):
+    """Hop 2+ in `next` mode: user text is only the new beat."""
+    text = (beat or "").strip() or ADVANCE_BEAT
+    cite = _live_cite(live_picture, live_video)
+    lock = _identity_lock(n_stills, live_picture,
+                          identity_ordinals=identity_ordinals,
+                          n_subjects=n_subjects)
+    solo = (n_subjects == 1) or (n_subjects is None and identity_ordinals is not None
+                                 and len(identity_ordinals) == 1)
+    whoever = "The same person holds" if solo else "The same people hold"
+    if _d.is_full_h3_prompt(text):
+        print(
+            f"[{TAG}] hop 2+ full H3 block flattened to a continuation beat "
+            "(a complete Ref2VA prompt on hop 2+ starts a new scene)",
+            flush=True,
+        )
+        text = _d.flatten_official_continue(text) or ADVANCE_BEAT
+    # No identity header on hop 2+ at all: register subject_prose is a
+    # subject_definitions block, and putting one here made hop 2 a second
+    # Ref2VA generate (chain_00033, the short drink beat). The call site passes
+    # nothing, and there is no parameter to pass.
+    header = str(state_header or "").strip()
+    top = header + "\n\n" if header else ""
+    # Order: who the pictures are, then what stays the same, then which
+    # frame is live. `continuity` carries no ordinals, so it is safe on a
+    # pin-only hop where `lock` is deliberately empty.
+    inject = " ".join(p for p in (lock, str(continuity or "").strip(), cite) if p)
+    inject = (inject + "\n\n") if inject else "\n"
+    # Pin-only hops have no identity photographs. Naming them (chain_00034)
+    # sent the encoder back to the face/outfit stills — commercial kitchen,
+    # grey shirt, no apron.
+    # The closer used to end on "still underway" unconditionally, which made it
+    # the last sentence of the prompt and so overrode the shot's own `tail`
+    # directive -- `settle` and `hold` were unreachable on hop 2+. On the final
+    # hop nothing absorbs that instruction and the model invents late action to
+    # satisfy it (observed: a line of dialogue in the last second of a 3-hop
+    # chain, and the ~23 s spike noted in CLAUDE.md). Each variant below still
+    # ends on the clip's terminal *state*, never on the photographs, so the
+    # ordering rule documented at the return is preserved.
+    terminal = {
+        "settle": "and that action eases to a rest and stays there through the "
+                  "final frames.",
+        "hold": "and the final position holds steady through the last moments.",
+    }.get(str(tail or "").strip(), "and that action is still underway as the clip ends.")
+
+    if lock:
+        hold = (
+            f"{whoever} their current pose, room, lighting, and camera side, "
+            "and the shot continues from exactly there. "
+        )
+        closer = (
+            "Faces and hair follow the identity photographs. Clothing follows "
+            "whatever is already on them in the live frame. After a brief hold "
+            "on the incoming action, the shot advances through what the "
+            f"next-beat describes, {terminal}"
+        )
+    else:
+        hold = (
+            "The incoming frame holds the current pose, room, lighting, and "
+            "camera side, and the shot continues from exactly there. "
+        )
+        closer = (
+            "Wardrobe, room, and lighting stay as they are in the live frame. "
+            "After a brief hold on the incoming action, the shot advances "
+            f"through what the next-beat describes, {terminal}"
+        )
+    # Official field names on hop 2+ start a new Ref2VA generate
+    # (chain_00030..00034). One paragraph: airlock, then the beat.
+    text = re.sub(
+        r"(?m)^(overall_soundscape|non_diegetic_music):\s*", "", text).strip()
+    return (
+        f"{top}"
+        "The clip opens already in progress from the pinned frames. "
+        "The incoming arrangement holds for a short beat -- breath, a weight "
+        "shift, an eyeline -- and only then the next action begins. "
+        f"{hold}"
+        f"{inject}"
+        "What happens next:\n"
+        f"{text}\n\n"
+        # Ordering rule: the prompt must END on ongoing motion, never on the
+        # photographs. The final sentence governs the terminal state of the clip,
+        # and when the beat action finishes before the frames run out the model
+        # renders whatever the prompt last pointed it at. Ending on "follow the
+        # identity photographs" made the tail settle onto the reference image --
+        # observed as the last ~3s of a 3-hop chain cutting to the ref still.
+        # Hops 1..N-1 hide this because the pin consumes their tail; the final
+        # hop has no successor, so its drift is what you see.
+        f"{closer}"
+    )
+
+
+def _attach_pin_to_qwen(pin_mode, hop_images, hop_videos, last_frame, pin_clip):
+    """AddGuide is invisible to Qwen. Optionally put the incoming state in ref slots.
+
+    The live frame is <Picture 1>. Identity stills shift up. Appending it after
+    the stills (chain_00034) made the pin Picture 4 against a commercial-kitchen
+    face and outfit as Pictures 1–2; hop 2 hard-cut and dropped the apron.
+    """
+    images = dict(hop_images or {})
+    videos = dict(hop_videos or {})
+    live_p = live_v = None
+    if pin_mode in ("last frame", "both") and last_frame is not None:
+        used = len(images)
+        if used >= MAX_REF_IMAGES:
+            print(f"[{TAG}] pin_to_qwen last frame skipped: already {MAX_REF_IMAGES} stills",
+                  flush=True)
+        else:
+            # Insertion order IS Picture order (core walks .values()).
+            # Put the live frame in the dict first or it becomes the last picture.
+            ordered = {"ref_image_1": last_frame[:1].contiguous()}
+            for key, tensor in images.items():
+                n = int(str(key).rsplit("_", 1)[-1])
+                ordered[f"ref_image_{n + 1}"] = tensor
+            images = ordered
+            live_p = 1
+            extra = f", {used} still(s) -> Picture 2+" if used else ""
+            print(f"[{TAG}] Qwen last frame -> <Picture 1>{extra}", flush=True)
+    if pin_mode in ("pin clip", "both") and pin_clip is not None:
+        if pin_clip.shape[0] < 5:
+            print(f"[{TAG}] pin clip too short for a video ref "
+                  f"({int(pin_clip.shape[0])}f)", flush=True)
+        elif len(videos) >= MAX_REF_VIDEOS:
+            print(f"[{TAG}] pin_to_qwen pin clip skipped: already {MAX_REF_VIDEOS} videos",
+                  flush=True)
+        else:
+            live_v = len(videos) + 1
+            videos[f"ref_video_{live_v}"] = pin_clip.contiguous()
+            print(
+                f"[{TAG}] Qwen pin clip -> <Video {live_v}> "
+                f"({int(pin_clip.shape[0])}f, no soundtrack — voice stays <Audio 1>)",
+                flush=True,
+            )
+    return images, live_p, videos, live_v
+
+
+def _latent_cpu(lat):
+    """Keep the previous hop's sampler output off GPU between hops."""
+    if not isinstance(lat, dict) or "samples" not in lat:
+        return lat
+    out = dict(lat)
+    samples = lat["samples"]
+    try:
+        out["samples"] = samples.cpu()
+    except Exception as e:
+        # Falling back to the GPU tensor is correct -- the pin still works --
+        # but it is also a per-hop VRAM leak, so it must not be silent.
+        print(f"[{TAG}] could not move the hop latent to CPU ({e!r}); "
+              f"keeping it on device", flush=True)
+        out["samples"] = samples
+    return out
+
+
+def _motion_context_cls():
+    """Upstream MiniMaxH3MotionContext, skipping forks with a different apply()."""
+    try:
+        import inspect
+        import nodes as nodes_mod
+    except Exception:
+        return None
+    cls = getattr(nodes_mod, "NODE_CLASS_MAPPINGS", {}).get("MiniMaxH3MotionContext")
+
+    def compatible(c):
+        try:
+            params = inspect.signature(c.apply).parameters
+            need = [k for k, v in params.items()
+                    if v.default is inspect.Parameter.empty and k != "self"]
+            return "context_frames" not in need
+        except Exception:
+            return False
+
+    if cls is not None and compatible(cls):
+        return cls
+    import sys
+    for mod in list(sys.modules.values()):
+        cand = getattr(mod, "MiniMaxH3MotionContext", None)
+        if cand is not None and compatible(cand):
+            if cls is not None:
+                print(
+                    f"[{TAG}] MiniMaxH3MotionContext registry entry is a fork; "
+                    f"using upstream class from {getattr(mod, '__name__', '?')}",
+                    flush=True,
+                )
+            return cand
+    return None
+
+
+def _latent_parts(x):
+    """The component tensors inside a sampler `samples`, as a flat list.
+
+    H3 hands back a `comfy.nested_tensor.NestedTensor` -- the video and audio
+    latents in one object -- and it is not a Tensor. It has no `.std()`, and
+    the attributes it *does* expose are traps: `.shape` returns
+    `tensors[0].shape`, i.e. the video component's shape while silently
+    speaking for both. Reading the components is the only honest way to touch
+    the numbers. Returns None for anything unrecognised, which callers treat as
+    "leave this latent alone".
+    """
+    if isinstance(x, torch.Tensor):
+        return [x]
+    if getattr(x, "is_nested", False) and hasattr(x, "unbind"):
+        parts = list(x.unbind())
+        if parts and all(isinstance(t, torch.Tensor) for t in parts):
+            return parts
+    return None
+
+
+def _rebuild_latent_samples(x, parts):
+    """Put conditioned components back into the container they came from."""
+    if isinstance(x, torch.Tensor):
+        return parts[0]
+    return type(x)(parts)
+
+
+def _condition_pin_latent(lat, anchor_std, renorm=False, noise=0.0, seed=0):
+    """Anti-ratchet preprocessing for the latent handed to Motion-Context.
+
+    MiniMaxH3MotionContext.apply() takes `context_latent` as-is and exposes no
+    hook, so both levers have to be applied to the latent before it goes in.
+
+    `renorm` rescales this pin so its standard deviation matches hop 2's. The
+    pin's own sigma climbs hop over hop, and because that inflated pin is what
+    conditions the next hop the growth compounds upstream of anything a master
+    pass can reach. A scalar rescale moves no structure, so it cannot blur
+    detail. `noise` mixes in a seeded perturbation, which attacks the same
+    ratchet from the other side; measured gains reverse above 0.10, hence the
+    widget cap.
+
+    **Per component, not per latent** (fixed 2026-08-27). Video and audio are
+    two tensors in one NestedTensor and their sigmas drift independently, so
+    each carries its own anchor. Before this, `.std()` raised on the nested
+    object and both levers were dead -- the failure announced itself once per
+    hop as `pin conditioning skipped` and was easy to read as routine noise.
+    A single global scale would also have been wrong on its own terms, letting
+    the much larger video component dictate the audio's correction.
+
+    Returns `(latent, new_anchor_std)` where the anchor is a list, one sigma
+    per component -- hop 2 establishes what hops 3+ are matched against. Both
+    levers default off, in which case the latent is returned untouched.
+    """
+    if not isinstance(lat, dict) or "samples" not in lat:
+        return lat, anchor_std
+    x = lat["samples"]
+    parts = _latent_parts(x)
+    if parts is None:
+        print(f"[{TAG}] pin conditioning skipped: unrecognised latent "
+              f"({type(x).__name__})", flush=True)
+        return lat, anchor_std
+    try:
+        cur = [float(t.float().std()) for t in parts]
+    except Exception as e:  # noqa: BLE001
+        print(f"[{TAG}] pin conditioning skipped ({e!r})", flush=True)
+        return lat, anchor_std
+    if not all(c == c and c for c in cur):  # zero or NaN in any stream
+        return lat, anchor_std
+    if anchor_std is None:
+        anchor_std = cur
+    if len(anchor_std) != len(cur):
+        # Stream count changed mid-chain. Nothing sensible to match against.
+        print(f"[{TAG}] pin conditioning skipped: latent has {len(cur)} "
+              f"component(s), anchor has {len(anchor_std)}", flush=True)
+        return lat, anchor_std
+    if not renorm and noise <= 0.0:
+        return lat, anchor_std
+    out_parts, notes = [], []
+    for idx, (t, c, a) in enumerate(zip(parts, cur, anchor_std)):
+        o = t
+        if renorm:
+            scale = a / c
+            o = o * scale
+            notes.append(f"renorm[{idx}] x{scale:.4f} (sigma {c:.4f} -> {a:.4f})")
+        if noise > 0.0:
+            # Per component: `.shape` on the nested object reports only the
+            # first component's shape, so one draw for the whole latent would
+            # size its noise to the video and broadcast that onto the audio.
+            g = torch.Generator(device="cpu").manual_seed((int(seed) + idx) & 0x7FFFFFFF)
+            n = torch.randn(o.shape, generator=g, dtype=torch.float32)
+            o = o + n.to(dtype=o.dtype, device=o.device) * (float(noise) * a)
+            notes.append(f"noise[{idx}] {float(noise):.3f}")
+        out_parts.append(o)
+    if notes:
+        print(f"[{TAG}] pin conditioning: " + ", ".join(notes), flush=True)
+    new = dict(lat)
+    new["samples"] = _rebuild_latent_samples(x, out_parts)
+    return new, anchor_std
+
+
+def _pin_mech_for(hop_index, overlap_n, prev_sampled):
+    """Which mechanism `_pin_continue` will pick, without doing the work.
+
+    The hop cache key has to be built *before* the pin runs, and the two
+    mechanisms produce different frames, so the key needs the mechanism up
+    front. Every condition here mirrors _pin_continue; the one thing it cannot
+    predict is Motion-Context raising at call time, which the caller catches by
+    comparing this against the mechanism actually used and declining to cache
+    that hop.
+    """
+    if hop_index == 0:
+        return "none"
+    if _motion_context_cls() is None:
+        return "addguide_pixels"
+    if str(overlap_n) not in MC_CONTEXT_LENGTHS:
+        return "addguide_pixels"
+    if prev_sampled is None:
+        return "addguide_pixels"
+    return "motion_context"
+
+
+def _pin_continue(cond, latent, vae, audio_vae, overlap_n,
+                  prev_sampled, prev_imgs, prev_audio, audio_ctx=24):
+    """Hop 2+ motion pin. Latent Motion-Context when possible; AddGuide otherwise.
+
+    AddGuide re-encodes decoded pixels and anchors audio forwards from frame 0
+    (cover-band soundtrack). Motion-Context slices the previous sampler AV
+    latent and end-aligns the audio window on this clip's timeline.
+
+    Returns `(conditioning, mech)` where mech is one of "motion_context",
+    "addguide_pixels" or "none". The caller puts mech in the *per-hop* cache
+    key: the two mechanisms produce different frames, so a hop rendered under
+    the AddGuide fallback must not be served later to a run where the latent
+    pin was available.
+    """
+    ctx_label = str(overlap_n)
+    mc = _motion_context_cls()
+    if mc is not None and ctx_label not in MC_CONTEXT_LENGTHS:
+        print(
+            f"[{TAG}] overlap {overlap_n}f has no Motion-Context context_length "
+            f"(accepts {sorted(MC_CONTEXT_LENGTHS, key=int)}); AddGuide pixel pin",
+            flush=True,
+        )
+        mc = None
+    if mc is not None and prev_sampled is not None:
+        try:
+            a_ctx = int(audio_ctx)
+            cond, trim = mc().apply(
+                conditioning=cond, vae=vae, latent=latent,
+                context_length=ctx_label, audio_context_length=a_ctx,
+                context_latent=prev_sampled,
+            )
+            print(
+                f"[{TAG}] Motion-Context pin: previous hop latent "
+                f"({ctx_label}f picture, {a_ctx}f audio, trim {trim})",
+                flush=True,
+            )
+            return cond, "motion_context"
+        except Exception as e:
+            # This downgrade changes the join, so it is logged with the real
+            # exception rather than swallowed -- repr(), because a bare
+            # TypeError from a renamed upstream kwarg stringifies to nothing
+            # useful.
+            print(
+                f"[{TAG}] Motion-Context pin failed ({e!r}); AddGuide pixel pin",
+                flush=True,
+            )
+    if mc is None:
+        print(
+            f"[{TAG}] Motion-Context not available; AddGuide pixel pin "
+            f"({overlap_n}f). Install ComfyUI-H3-Motion-Context for a latent join.",
+            flush=True,
+        )
+    elif prev_sampled is None:
+        print(
+            f"[{TAG}] previous hop has no sampler latent (cache hit); "
+            f"AddGuide pixel pin ({overlap_n}f)",
+            flush=True,
+        )
+    pin_image = prev_imgs[-overlap_n:] if prev_imgs is not None else None
+    pin_audio = _tail_audio(prev_audio, overlap_n) if prev_audio is not None else None
+    if pin_image is None and pin_audio is None:
+        return cond, "none"
+    return _result(MiniMaxH3AddGuide.execute(
+        cond, latent, 0,
+        vae=vae if pin_image is not None else None,
+        audio_vae=audio_vae if pin_audio is not None else None,
+        image=pin_image,
+        audio=pin_audio,
+    ))[0], "addguide_pixels"
+
+
+def _collect_ref_images(slot_images):
+    """Dense-pack the wired slots into <Picture N> order.
+
+    Takes the slot -> tensor map the caller already built, rather than reading
+    the nine node inputs a second time. Gathering them twice -- once here, once
+    for `slot_images` -- is how a slot goes missing from one of the two and
+    silently renumbers every later <Picture N>, which is the exact failure
+    refs.py exists to prevent.
+    """
+    frames = [slot_images[s] for s in sorted(slot_images)]
+    if not frames:
+        return None
+    bits = []
+    for i, im in enumerate(frames):
+        bits.append(f"<Picture {i + 1}> {int(im.shape[2])}x{int(im.shape[1])}")
+    print(f"[{TAG}] {len(frames)} reference image(s) -> " + ", ".join(bits), flush=True)
+    if len(frames) < 3:
+        print(f"[{TAG}] warning: fewer than 3 stills. A reference with no "
+              "picture chosen does not count.", flush=True)
+    return {f"ref_image_{i + 1}": frames[i] for i in range(len(frames))}
+
+
+def _audio_samples(frames, sr):
+    return max(1, int(round(frames / float(FPS) * int(sr))))
+
+
+def _tail_audio(audio, frames):
+    wav = audio["waveform"]
+    sr = int(audio["sample_rate"])
+    n = min(_audio_samples(frames, sr), int(wav.shape[-1]))
+    return {"waveform": wav[..., -n:].contiguous(), "sample_rate": sr}
+
+
+def _trim_audio_head(audio, frames):
+    wav = audio["waveform"]
+    sr = int(audio["sample_rate"])
+    n = min(_audio_samples(frames, sr), int(wav.shape[-1]))
+    return {"waveform": wav[..., n:].contiguous(), "sample_rate": sr}, n
+
+
+def _xfade_audio(left, right, sr, ms=40):
+    n = max(1, int(sr * ms / 1000.0))
+    k = min(n, int(left.shape[-1]), int(right.shape[-1]))
+    if k < 8:
+        return torch.cat([left, right], dim=-1)
+    t = torch.linspace(0, 1, k, dtype=left.dtype, device=left.device)
+    fade_out = torch.cos(t * math.pi / 2)
+    fade_in = torch.sin(t * math.pi / 2)
+    while fade_out.ndim < left.ndim:
+        fade_out = fade_out.unsqueeze(0)
+        fade_in = fade_in.unsqueeze(0)
+    seam = left[..., -k:] * fade_out + right[..., :k] * fade_in
+    return torch.cat([left[..., :-k], seam, right[..., k:]], dim=-1)
+
+
+def _frame_to_jpeg_b64(frame, max_side=512, quality=80):
+    from PIL import Image
+    arr = (frame.detach().float().cpu().numpy() * 255.0).clip(0, 255).astype("uint8")
+    if arr.ndim == 3 and arr.shape[-1] > 3:
+        arr = arr[..., :3]
+    img = Image.fromarray(arr)
+    w, h = img.size
+    scale = min(1.0, float(max_side) / float(max(w, h)))
+    if scale < 1.0:
+        img = img.resize((max(1, int(w * scale)), max(1, int(h * scale))), Image.LANCZOS)
+    buf = pyio.BytesIO()
+    img.save(buf, format="JPEG", quality=int(quality))
+    return base64.b64encode(buf.getvalue()).decode("ascii"), img.size
+
+
+class _PreviewEncoder:
+    """Encode preview JPEGs off the sampling thread.
+
+    Encoding inline cost the sampler a PIL resize plus a JPEG write at every
+    push. The queue is bounded and *drops* when full: a preview frame is worth
+    nothing if delivering it slows the render that produced it.
+    """
+
+    def __init__(self, depth=2):
+        self._q = queue.Queue(maxsize=depth)
+        self._t = None
+
+    def _run(self):
+        while True:
+            job = self._q.get()
+            if job is None:
+                return
+            payload, frames = job
+            try:
+                for key, frame in frames.items():
+                    b64, (w, h) = _frame_to_jpeg_b64(frame)
+                    payload[key] = b64
+                    if key == "image":
+                        payload["w"], payload["h"] = w, h
+            except Exception as e:
+                print(f"[{TAG}] preview encode skipped: {e!r}", flush=True)
+            try:
+                PromptServer.instance.send_sync(
+                    "h3_refchain_preview", payload, PromptServer.instance.client_id)
+            except Exception as e:
+                print(f"[{TAG}] preview send skipped: {e!r}", flush=True)
+
+    def submit(self, payload, frames):
+        if self._t is None:
+            self._t = threading.Thread(target=self._run, name="h3rc-preview",
+                                       daemon=True)
+            self._t.start()
+        try:
+            self._q.put_nowait((payload, frames))
+        except queue.Full:
+            pass  # deliberate: never block the sampler for a preview
+
+
+_PREVIEW = _PreviewEncoder()
+
+
+def _push_preview(unique_id, status, frame=None, hop=0, total=0,
+                  pin_mech=None, frac=None, seam_frame=None, meta=None):
+    """Send one preview update.
+
+    `status` stays a SHORT label. The full per-hop prompt dump belongs on the
+    `info` output -- passing it here once turned the status strip into the
+    prompt. Everything structured goes in its own field instead, which is what
+    a panel can actually lay out.
+    """
+    if not unique_id or PromptServer is None:
+        return
+    payload = {
+        "node_id": unique_id,
+        "status": status,
+        "hop": int(hop),
+        "total": int(total),
+    }
+    if pin_mech:
+        payload["pin_mech"] = str(pin_mech)
+    if frac is not None:
+        payload["frac"] = max(0.0, min(1.0, float(frac)))
+    if meta:
+        payload.update(meta)
+    frames = {}
+    if frame is not None:
+        frames["image"] = frame
+    if seam_frame is not None:
+        frames["seam_image"] = seam_frame
+    _PREVIEW.submit(payload, frames)
+
+
+def _offload_text_encoder(clip, model):
+    te_dev = getattr(clip.patcher, "load_device", None)
+    dit_dev = getattr(model, "load_device", None)
+    if te_dev is not None and dit_dev is not None and str(te_dev) != str(dit_dev):
+        return
+    try:
+        clip.patcher.model.to(mm.text_encoder_offload_device())
+    except Exception as e:
+        print(f"[{TAG}] TE offload skipped: {e}", flush=True)
+        return
+    try:
+        dev = mm.get_torch_device()
+        mm.free_memory(mm.get_total_memory(dev) * 0.9, dev)
+        mm.soft_empty_cache()
+        free = mm.get_free_memory(dev) / (1024 ** 3)
+        print(f"[{TAG}] TE evicted; {free:.1f} GB free for the DiT", flush=True)
+    except Exception as e:
+        print(f"[{TAG}] VRAM purge skipped: {e}", flush=True)
+
+
+def _decode_av(video_vae, audio_vae, latent):
+    imgs = VAEDecode().decode(video_vae, latent)[0]
+    audio = vae_decode_audio(audio_vae, latent)
+    return imgs, audio
+
+
+class HandTieClips:
+    """Refs + shot plan + N hops, assembled into one clip.
+
+    Each hop after the first pins the previous hop's sampler latent through
+    Motion-Context, falling back to an AddGuide pixel pin when that is not
+    available. See the module docstring.
+    """
+
+    @classmethod
+    def INPUT_TYPES(cls):
+        return {
+            "required": {
+                "model": ("MODEL",),
+                "clip": ("CLIP",),
+                "vae": ("VAE",),
+                "audio_vae": ("VAE",),
+                "prompt": ("STRING", {
+                    "multiline": True,
+                    "dynamicPrompts": False,
+                    "default": (
+                        "Live-action, natural indoor light. The person looks exactly "
+                        "as in the reference photographs.\n\n"
+                        "They sit at a table, look up, and speak one short line. "
+                        "Then they settle, watching the room."
+                    ),
+                    "tooltip": (
+                        "Hop 1 prompt. Separate hops with --- on its own line, "
+                        "or JSON {\"prompts\": [...]}. hop_script=verbatim: one block "
+                        "+ chains>1 wraps later hops. hop_script=next: later --- blocks "
+                        "are only 'what happens next'."
+                    ),
+                }),
+                "chains": (["1", "2", "3", "4", "5", "6", "7", "8"], {
+                    "default": "3",
+                    "tooltip": "How many generates to run and join. 3 at 10 s is about 28 s of master after the overlap trim.",
+                }),
+                "resolution": (["0.2 MP", "0.3 MP", "0.5 MP", "0.7 MP", "1.0 MP"], {
+                    "default": "1.0 MP",
+                    "tooltip": "Output area. 1.0 MP landscape is 1280x736 (the verified H3 size). Snapped to H3's 32 px grid.",
+                }),
+                "aspect": (["16:9 landscape", "9:16 portrait", "1:1 square"], {
+                    "default": "16:9 landscape",
+                    "tooltip": "Frame shape. Combined with resolution to set width and height.",
+                }),
+                "duration": (["5 s", "7 s", "8 s", "10 s", "15 s"], {
+                    "default": "10 s",
+                    "tooltip": "Length of each hop at 24 fps (H3 17k+5 grid: 124 / 192 / 243 / 362 frames). 5 s (124f) drops the airlock on a continuous join; use 8 s or 15 s to validate a seam.",
+                }),
+                "overlap": (["0.9 s", "0.2 s", "1.6 s"], {
+                    "default": "0.9 s",
+                    "tooltip": "Pinned clip from the previous hop at frame 0. 0.9 s (22 frames) is the native continuation length.",
+                }),
+                "seed": ("INT", {
+                    "default": 0, "min": 0, "max": 0xffffffffffffffff,
+                    "control_after_generate": True,
+                }),
+                "seed_per_shot": ("BOOLEAN", {
+                    "default": True,
+                    "label_on": "vary per hop",
+                    "label_off": "same seed every hop",
+                }),
+                "steps": ("INT", {"default": 14, "min": 1, "max": 50}),
+                "sampler_name": (comfy.samplers.KSampler.SAMPLERS, {"default": "res_multistep"}),
+                "scheduler": (comfy.samplers.KSampler.SCHEDULERS, {"default": "beta"}),
+                "shift_video": ("FLOAT", {"default": 12.0, "min": 0.01, "max": 100.0, "step": 0.01}),
+                "shift_audio": ("FLOAT", {"default": 3.0, "min": 0.01, "max": 100.0, "step": 0.01}),
+                "ref_image_size": (["match", "max"], {
+                    "tooltip": "match = faster. max = 2048 short-edge identity, slower every step.",
+                }),
+            },
+            "optional": {
+                # The nine ref_image_N sockets, plus reference_video, voice
+                # and start_image, used to live at the TOP of this block --
+                # twelve of a sixteen-socket column that occupied a third of
+                # the node before the editor started. They are files now, and
+                # their replacements are appended at the BOTTOM of `optional`
+                # instead. See the note beside them: widget ORDER is part of
+                # the saved-workflow format.
+                "hop_script": (["verbatim", "next"], {
+                    "default": "verbatim",
+                    "tooltip": (
+                        "verbatim: your text is the hop prompt. next: hop 1 is the first "
+                        "block; every later block is only the new beat. One block + next: "
+                        "hops 2+ advance without replaying the opening."
+                    ),
+                }),
+                "pin_to_qwen": (["off", "last frame", "pin clip", "both"], {
+                    "default": "last frame",
+                    "tooltip": (
+                        "AddGuide is invisible to the text encoder. last frame = "
+                        "<Picture 1> of the previous hop's last frame (identity stills "
+                        "shift to Picture 2+). pin clip = overlap as extra <Video>. "
+                        "Voice stays <Audio 1>."
+                    ),
+                }),
+                "continuity_state": ("STRING", {
+                    "multiline": True,
+                    "default": "",
+                    "forceInput": True,
+                    "tooltip": (
+                        "Optional JSON continuity state from HTCContinuityState (or a String "
+                        "Primitive node for hand-typed JSON). hop_script=next only: locked + "
+                        "context text rides every hop 2+, mutable beats are indexed per hop. "
+                        "Unwired = no effect."
+                    ),
+                }),
+                "shot_plan": ("STRING", {
+                    "multiline": True,
+                    "default": "",
+                    "tooltip": (
+                        "Shot plan JSON: {\"shots\":[{\"beat\":\"...\","
+                        "\"directives\":{\"join\":\"continuous\"}}, ...]}. "
+                        "The shot count is the hop count, so `chains` is ignored. "
+                        "Directives compile to vetted continuity prose; `prose` per shot "
+                        "is appended verbatim. Blank = use the `prompt` widget instead."
+                    ),
+                }),
+                "ref_plan": ("STRING", {
+                    "multiline": True,
+                    "default": "",
+                    "tooltip": (
+                        "Reference register JSON: {'refs':[{'tag':'hero_face',"
+                        "'file':'face.png','subject':1,'retention':'fully_preserved'}]}. "
+                        "'file' is a picture in the reference folder, chosen in the panel. "
+                        "Beats refer to refs by @tag, resolved to the correct "
+                        "<Picture N> per hop, so removing or scheduling off a ref "
+                        "never renumbers the others. Refs sharing a 'subject' are "
+                        "the same person; different numbers stay different people. "
+                        "Blank = today's positional behaviour."
+                    ),
+                }),
+                "cache_hops": (["off", "on"], {
+                    "default": "off",
+                    "tooltip": (
+                        "Store each hop losslessly on disk, keyed by a chained "
+                        "content hash. Unchanged hops load instead of re-rendering, "
+                        "so editing only the last shot re-renders only that shot, "
+                        "and an interrupted chain resumes. Editing an early shot "
+                        "correctly invalidates every hop after it."
+                    ),
+                }),
+                "cache_budget_gb": ("FLOAT", {
+                    "default": 20.0, "min": 1.0, "max": 500.0, "step": 1.0,
+                    "tooltip": "Least-recently-used hops are evicted above this size.",
+                }),
+                "audio_pin_frames": ("INT", {
+                    "default": 24, "min": 0, "max": 240, "step": 24,
+                    "tooltip": (
+                        "Audio context handed to the Motion-Context pin, in frames. "
+                        "24 is one second and lands on the model's 40 Hz audio grid; "
+                        "multiples of 24 keep whole seconds. Longer audio context "
+                        "costs conditioning rows but NO delivered frames, so it is "
+                        "the cheap lever on speech that breaks across a join -- try "
+                        "96 (4 s) for continuous dialogue. 0 follows the picture "
+                        "overlap. Video pin length is not adjustable here: it "
+                        "follows the overlap widget."
+                    ),
+                }),
+                "pin_renorm": (["off", "on"], {
+                    "default": "off",
+                    "tooltip": (
+                        "Rescale each pinned latent so its spread matches hop 1's. "
+                        "The pin's own sigma climbs every hop and that inflated pin "
+                        "conditions the next one, so texture ratchets up along a "
+                        "long chain. A scalar rescale moves no structure, so it "
+                        "cannot blur detail. Off reproduces chain_00038 exactly; "
+                        "turn it on for chains of 3+ hops."
+                    ),
+                }),
+                "pin_noise": ("FLOAT", {
+                    "default": 0.0, "min": 0.0, "max": 0.10, "step": 0.005,
+                    "tooltip": (
+                        "Mix seeded noise into the pinned latent before it "
+                        "conditions the next hop -- the other half of the texture "
+                        "ratchet fix. Small values only: measured gains fall off "
+                        "and reverse above 0.10, which is why the range stops "
+                        "there. 0.0 reproduces chain_00038 exactly; 0.05 is the "
+                        "documented starting point."
+                    ),
+                }),
+                "tone_compensate": (_tone.MODES, {
+                    "default": "off",
+                    "tooltip": (
+                        "Undo the denoiser's tone bias on each hop, measured on the "
+                        "overlap that hop regenerated. The estimate needs both copies "
+                        "of the overlap, which only exist inside this node -- a "
+                        "downstream node cannot do this. frame_shift is the mode that "
+                        "suits regenerated content; gain_bias is more robust; lut "
+                        "overfits. Enabling any mode also clamps the master to 0..1."
+                    ),
+                }),
+                # ---------------------------------------------------------
+                # APPEND-ONLY ZONE. `widgets_values` in a saved workflow is a
+                # POSITIONAL array -- ComfyUI restores value[i] into widget[i]
+                # and never checks the name. A widget inserted anywhere but the
+                # end renumbers everything after it, and every previously saved
+                # workflow silently loads its values into the wrong widgets.
+                #
+                # These three were first added at the top of `optional`, which
+                # shifted hop_script..tone_compensate by +3. `ref_plan` then
+                # received audio_pin_frames' integer and the editor threw
+                # `(text || "").trim is not a function` on load -- the only
+                # visible symptom of a much wider silent corruption.
+                #
+                # Add new widgets HERE, at the bottom. Old workflows are then
+                # short rather than misaligned, and the new widget takes its
+                # default.
+                # ---------------------------------------------------------
+                "start_image_file": ("STRING", {
+                    "default": "",
+                    "tooltip": "First-frame pin for hop 1 only. Set in the panel.",
+                }),
+                "reference_video_file": ("STRING", {
+                    "default": "",
+                    "tooltip": "Motion/look plate. Not the previous hop. Set in the panel.",
+                }),
+                "voice_file": ("STRING", {
+                    "default": "",
+                    "tooltip": "Voice or timbre reference, riding every hop as <Audio 1>. Set in the panel.",
+                }),
+                # Appended here on 2026-08-29, per the note above: LAST, so
+                # every saved workflow keeps its widget alignment and simply
+                # takes the default.
+                "establish": ("STRING", {
+                    # Single line on purpose. The editor hides only the widgets
+                    # it explicitly owns, so this one renders as a native widget
+                    # on the node body -- and one sentence in a one-line box is
+                    # discoverable where a multiline textarea would be a slab.
+                    "default": _d.ESTABLISH,
+                    "tooltip": (
+                        "Opening line prepended to hop 1 only, before the beat. "
+                        "The default asserts live action; clear it, or replace it "
+                        "with your own medium, for anything else. Dropped "
+                        "automatically when shot 1 already names a medium."
+                    ),
+                }),
+            },
+            "hidden": {
+                "unique_id": "UNIQUE_ID",
+            },
+        }
+
+    RETURN_TYPES = ("IMAGE", "AUDIO", "STRING")
+    RETURN_NAMES = ("images", "audio", "info")
+    FUNCTION = "run"
+    CATEGORY = "Hand Tie Clips"
+    DESCRIPTION = (
+        "MiniMax H3 Ref2VA chain. Hop 1 is a full generate; every later hop is a "
+        "continuation pinned to the previous hop's sampler latent via "
+        "Motion-Context, falling back to an AddGuide pixel pin when that is "
+        "unavailable. Author with shot_plan + ref_plan; hop_script=next treats "
+        "later blocks as what-happens-next; pin_to_qwen shows the incoming frame "
+        "to the text encoder; continuity_state (from HTCContinuityState) carries "
+        "locked/context setting text forward."
+    )
+
+    @classmethod
+    def IS_CHANGED(cls, ref_plan="", start_image_file="",
+                   reference_video_file="", voice_file="", **_):
+        """Re-run when a reference file changes underneath its name.
+
+        Every picture now arrives as a basename, and a basename is a stable
+        input: overwrite `face.png` with a different face and ComfyUI would
+        happily serve the previous render. Hashing path+mtime is the fix.
+
+        Deliberately NOT `float("nan")` -- that is the blunt version of this and
+        would force a full re-render of an expensive node on every queue.
+        """
+        names = [start_image_file, reference_video_file, voice_file]
+        try:
+            for r in (_refs.parse_ref_plan(ref_plan).get("refs") or []):
+                if r.get("file"):
+                    names.append(r["file"])
+        except Exception:
+            # A malformed plan is run()'s error to report, with a message that
+            # names the field. Raising here would surface as a cache failure.
+            pass
+        return _media.stamp(names)
+
+    def run(self, model, clip, vae, audio_vae, prompt,
+            chains, resolution,
+            aspect, duration, overlap, seed, seed_per_shot, steps,
+            sampler_name, scheduler, shift_video, shift_audio, ref_image_size,
+            start_image_file="", reference_video_file="", voice_file="",
+            hop_script="verbatim", pin_to_qwen="last frame", continuity_state="",
+            shot_plan="", ref_plan="", cache_hops="off", cache_budget_gb=20.0,
+            audio_pin_frames=24, pin_renorm="off", pin_noise=0.0,
+            tone_compensate="off", establish=None,
+            unique_id=None):
+        width, height = _canvas(resolution, aspect)
+        length = align_frame_count(_duration_frames(duration))
+        overlap_n = _overlap_frames(overlap)
+
+        # A shot plan is authoritative when present: its shot count is the hop
+        # count, and every shot after the first is a beat, so `next` semantics
+        # are the only correct reading of it.
+        shots = _plan.parse_plan(shot_plan)
+        if shots:
+            if str(hop_script) != "next":
+                print(f"[{TAG}] shot_plan present -> hop_script=next", flush=True)
+            hop_script = "next"
+            if int(chains) != len(shots):
+                print(f"[{TAG}] shot_plan has {len(shots)} shot(s); "
+                      f"chains={chains} ignored", flush=True)
+            # The place-handoff check needs to know which tags are places,
+            # which only the ref plan says. Parsed defensively here: the
+            # authoritative parse (and its error) is still the one below, so a
+            # malformed ref_plan fails in the same place it always did.
+            try:
+                _rp_for_check = _refs.parse_ref_plan(ref_plan)
+            except Exception:
+                _rp_for_check = None
+            blocks = _plan.compile_blocks(shots, establish, _rp_for_check)
+            unique = len(shots)
+            print(f"[{TAG}] shot plan:\n" + _plan.describe(shots), flush=True)
+            for i, sh in enumerate(shots):
+                if i > 0 and _d.is_full_h3_prompt((sh or {}).get("beat")):
+                    print(
+                        f"[{TAG}] hop {i + 1}: full H3 prompt flattened to a "
+                        "continuation beat (a complete Ref2VA block on hop 2+ "
+                        "starts a new scene)",
+                        flush=True,
+                    )
+        else:
+            shots = [None] * int(chains)
+            blocks, unique = _expand_shots(
+                _parse_shots(prompt), int(chains), hop_script=str(hop_script))
+        n = len(blocks)
+
+        # Per-shot duration overrides, validated up front so a bad value fails
+        # before any sampling happens rather than three hops in.
+        lengths = []
+        for i, sh in enumerate(shots):
+            dur = (sh or {}).get("duration") if sh else None
+            if dur and str(dur) not in DURATION_FRAMES:
+                raise ValueError(
+                    f"{TAG}: shot {i + 1}: duration '{dur}' is not valid. "
+                    f"Use one of: {', '.join(DURATION_FRAMES)}"
+                )
+            lengths.append(align_frame_count(_duration_frames(dur or duration)))
+        if str(hop_script) == "next":
+            for i, sh in enumerate(shots):
+                if i == 0:
+                    continue
+                join = ((sh or {}).get("directives") or {}).get("join")
+                dur = ((sh or {}).get("duration") if sh else None) or duration
+                if join == "continuous" and str(dur) == "5 s":
+                    print(
+                        f"[{TAG}] note: shot {i + 1} is join=continuous at 5 s "
+                        "(124f). That budget drops the airlock; 8 s / 15 s is "
+                        "the join-validation canvas. A lucky seed can still "
+                        "join at 5 s.",
+                        flush=True,
+                    )
+        for i, ln in enumerate(lengths):
+            if overlap_n >= ln:
+                raise ValueError(
+                    f"{TAG}: shot {i + 1}: overlap {overlap} ({overlap_n} frames) must "
+                    f"be smaller than duration ({ln} frames)"
+                )
+        state = _parse_state(continuity_state)
+        # The three singles first, so a name that does not resolve is reported
+        # before anything expensive starts. Each returns exactly what the socket
+        # it replaced delivered, so everything downstream is unchanged.
+        start_image = _media.load_image(start_image_file) if start_image_file else None
+        reference_video = (_media.load_video(reference_video_file)
+                           if reference_video_file else None)
+        voice = _media.load_audio(voice_file) if voice_file else None
+        for _name, _got in (("start_image", start_image_file and start_image is None),
+                            ("reference_video", reference_video_file and reference_video is None),
+                            ("voice", voice_file and voice is None)):
+            if _got:
+                print(f"[{TAG}] note: {_name} file could not be read; continuing "
+                      f"without it", flush=True)
+
+        ref_plan_obj = _refs.parse_ref_plan(ref_plan)
+        ref_plan_refs = ref_plan_obj["refs"]
+        ref_subjects = ref_plan_obj["subjects"]
+        # Derived slot -> tensor. The register still needs to know which picture
+        # a @tag is pinned to; the slot is now the ref's position in the rail
+        # rather than a socket number, and _collect_ref_images below dense-packs
+        # and throws it away.
+        slot_images = {}
+        for _r in ref_plan_refs:
+            if not _r["file"]:
+                continue
+            _im = _media.load_image(_r["file"])
+            if _im is not None and _im.shape[0] > 0:
+                slot_images[_r["slot"]] = _im[:1]
+        if ref_plan_refs:
+            print(f"[{TAG}] reference register:", flush=True)
+            print(_refs.describe(ref_plan_obj), flush=True)
+            # A named picture that is not on disk stops the queue. Warning and
+            # continuing renders the whole chain with that reference silently
+            # inactive, which is the failure the register exists to prevent --
+            # and the docs have always promised a stop here.
+            _absent = _refs.missing_files(ref_plan_obj, set(slot_images))
+            if _absent:
+                raise ValueError(
+                    f"[{TAG}] reference picture not found in "
+                    f"ComfyUI/input/h3_refs: "
+                    + "; ".join(f"@{_t} names '{_f}'" for _t, _f in _absent)
+                    + ". Drop the file onto that row in the REFERENCES rail, or "
+                      "clear the row's picture to render without it.")
+            for _w in _refs.check(ref_plan_obj, set(slot_images)):
+                print(f"[{TAG}] note: {_w}", flush=True)
+            # ref_plan subjects and a `characters` block in continuity_state
+            # both feed the prompt header, so filling in both injects identity
+            # prose twice. HTCContinuityState no longer emits characters, so this
+            # can only come from hand-authored JSON -- still worth warning about
+            # rather than raising, since the setting half stays useful.
+            _chars = sorted(
+                cid for cid, c in (state.get("characters") or {}).items()
+                if (c or {}).get("locked") or (c or {}).get("context")
+                or (c or {}).get("mutable")
+            )
+            if ref_subjects and _chars:
+                print(f"[{TAG}] note: ref_plan defines subject(s) "
+                      f"{sorted(ref_subjects)} and continuity_state also carries "
+                      f"character(s) {_chars}. Both inject identity text -- drop "
+                      f"the characters block and keep setting only.", flush=True)
+        ref_images = _collect_ref_images(slot_images)
+        base_videos = None if reference_video is None else {"ref_video_1": reference_video}
+        ref_audios = None if voice is None else {"ref_audio_1": voice}
+
+        # Fingerprint the model as it arrives -- after whatever LoRA and
+        # attention nodes are drawn upstream, before this node touches it.
+        model_fp = _model_fingerprint(model)
+
+        model = _result(MiniMaxH3SigmaShift.execute(model, float(shift_video), float(shift_audio)))[0]
+        sampler = _result(KSamplerSelect.execute(sampler_name))[0]
+        base_sigmas = _result(BasicScheduler.execute(model, scheduler, int(steps), 1.0))[0]
+        sigma_cache = {int(steps): base_sigmas}
+
+        print(
+            f"[{TAG}] {n} hop(s), {length}f ({length / FPS:.1f}s) @ {width}x{height} "
+            f"({resolution}, {aspect}), overlap {overlap_n}f, "
+            f"hop_script={hop_script}, pin_to_qwen={pin_to_qwen}, "
+            f"{unique} authored block(s), {steps} steps {sampler_name}/{scheduler}",
+            flush=True,
+        )
+
+        # Preallocate the master instead of growing it with torch.cat. cat
+        # allocates a fresh full-size tensor every hop, so at hop N the old and
+        # new masters are briefly live *together* alongside prev_imgs and imgs.
+        # Total length is known up front, so one allocation plus slice-writes
+        # removes that doubling.
+        total_frames = sum(lengths) - overlap_n * (n - 1)
+        master_imgs = torch.empty(
+            (total_frames, int(height), int(width), 3), dtype=torch.float32)
+        write_pos = 0
+        master_wav = None
+        sr = None
+        prev_imgs = None
+        prev_audio = None
+        prev_sampled = None
+        pbar = comfy.utils.ProgressBar(n)
+
+        hop_store = None
+        pin_renorm_on = str(pin_renorm) == "on"
+        pin_noise_v = max(0.0, min(0.10, float(pin_noise)))
+        audio_ctx = int(audio_pin_frames) if int(audio_pin_frames) > 0 else int(overlap_n)
+        pin_anchor_std = None   # hop 2's pin sets the sigma hops 3+ match
+        if pin_renorm_on or pin_noise_v > 0.0:
+            print(f"[{TAG}] pin conditioning enabled: "
+                  f"renorm={'on' if pin_renorm_on else 'off'} "
+                  f"noise={pin_noise_v:.3f}", flush=True)
+        tone_mode = str(tone_compensate)
+        tone_on = tone_mode != "off" and tone_mode in _tone.MODES
+        if tone_on:
+            print(f"[{TAG}] tone compensation: {tone_mode} "
+                  f"(overlap {overlap_n}f)", flush=True)
+        if str(cache_hops) == "on":
+            import folder_paths
+            hop_store = _store.HopStore(
+                os.path.join(folder_paths.get_temp_directory(), "h3_ref_chain_hops"),
+                budget_gb=float(cache_budget_gb), fps=FPS)
+            print(f"[{TAG}] hop cache: {hop_store.root} "
+                  f"(budget {float(cache_budget_gb):.0f} GB)", flush=True)
+        # Everything constant across the chain, mixed into every hop key so a
+        # resolution or sampler change invalidates the whole cache.
+        chain_salt = {
+            "w": int(width), "h": int(height), "overlap": overlap_n,
+            "sampler": str(sampler_name), "scheduler": str(scheduler),
+            "shift_v": float(shift_video), "shift_a": float(shift_audio),
+            "ref_size": str(ref_image_size), "pin": str(pin_to_qwen),
+            # No "pin_mech" here: the mechanism is decided per hop at runtime
+            # in _pin_continue (Motion-Context when a sampler latent exists,
+            # AddGuide pixels otherwise), so it belongs in the per-hop key
+            # below, not in the chain-wide salt.
+            "refs": {s: _store.tensor_digest(t)
+                     for s, t in sorted(slot_images.items())},
+            "voice": _store.audio_digest(voice),
+            "refvid": _store.tensor_digest(reference_video),
+            "start": _store.tensor_digest(start_image),
+            # A cached hop rendered under different LoRAs or a different
+            # attention path is not the same hop, so what has been patched onto
+            # the incoming model is part of the key. See _model_fingerprint.
+            "model": model_fp,
+        }
+        prev_key = None
+        hop_keys = []
+
+        assembled = []
+        for i, block in enumerate(blocks):
+            mm.throw_exception_if_processing_interrupted()
+            shot = shots[i] or {}
+            hop_length = lengths[i]
+            print(f"[{TAG}] hop {i + 1}/{n}...", flush=True)
+            _push_preview(unique_id, f"hop {i + 1}/{n} sampling…", hop=i + 1, total=n,
+                           frac=(write_pos / float(total_frames)) if total_frames else None)
+
+            # With a register, this hop's refs are only the ones active on it,
+            # re-packed in slot order. The image dict and the ordinals the prompt
+            # cites are built from the same list, so they cannot drift apart.
+            hop_active = []
+            hop_subject_prose = ""
+            if ref_plan_refs:
+                hop_active = _refs.active_refs(ref_plan_refs, i, set(slot_images))
+                # Continuation: omit shots[] = hop 1 only. Face/outfit plates
+                # of a different room (chain_00034) beat the pin as Pictures 1–3
+                # and hop 2 opened a new Ref2VA generate — commercial kitchen,
+                # apron gone. List hop numbers on a ref to ride later hops.
+                if i > 0 and str(hop_script) == "next":
+                    dropped = [r["tag"] for r in hop_active if r.get("shots") is None]
+                    hop_active = [r for r in hop_active if r.get("shots") is not None]
+                    if dropped:
+                        print(
+                            f"[{TAG}] hop {i + 1}: unscheduled stills stay off "
+                            f"this continue ({', '.join('@' + t for t in dropped)}); "
+                            f"pin carries wardrobe and room",
+                            flush=True,
+                        )
+                base_images = {
+                    f"ref_image_{k + 1}": slot_images[r["slot"]]
+                    for k, r in enumerate(hop_active)
+                } or None
+            else:
+                base_images = ref_images
+                if i > 0 and str(hop_script) == "next":
+                    print(
+                        f"[{TAG}] hop {i + 1}: identity stills stay off this "
+                        "continue (no shots[] schedule); pin carries wardrobe "
+                        "and room",
+                        flush=True,
+                    )
+                    base_images = None
+
+            hop_images = base_images
+            hop_videos = base_videos
+            live_p = live_v = None
+            still_shift = 0
+            if i > 0:
+                hop_images, live_p, hop_videos, live_v = _attach_pin_to_qwen(
+                    str(pin_to_qwen), base_images, base_videos,
+                    prev_imgs[-1:], prev_imgs[-overlap_n:],
+                )
+                if live_p == 1:
+                    still_shift = 1
+                if not hop_images:
+                    hop_images = None
+                if not hop_videos:
+                    hop_videos = None
+
+            # One ordinal map for this hop. The prompt's <Picture N> citations
+            # and the identity lock's ordinals have to agree, and computing the
+            # same shift twice is exactly how they drift apart. `p`, not `n` --
+            # `n` is the hop count in the enclosing scope.
+            hop_ords = _refs.ordinals(hop_active)
+            if still_shift:
+                hop_ords = {t: p + still_shift for t, p in hop_ords.items()}
+            if ref_plan_refs:
+                # Plan-wide subjects so @hero_face still resolves when that
+                # photograph is off this hop.
+                # Names, not ordinals, from hop 2 on. `subject_definitions:`
+                # is hop-1 material, so a `<Subject N>` reaching hop 4 has no
+                # antecedent in its own encode -- the dangling-token defect
+                # that turned an undescribed "the bowl" into a steel one.
+                # `continuity_line` rides every continuation hop and is what
+                # the name binds to.
+                block = _refs.resolve_tags(
+                    block, hop_ords, _refs.subjects(ref_plan_refs),
+                    where=f"shot {i + 1}",
+                    declared={r["tag"] for r in ref_plan_refs},
+                    subject_names=({k: (v or {}).get("name")
+                                    for k, v in (ref_subjects or {}).items()}
+                                   if i > 0 else None))
+                if i == 0:
+                    # Hop 1 only: subject_prose derives its own ordinals with no
+                    # still_shift, correct only because hop 1 has no pin.
+                    # Computing it on hop 2+ invites an off-by-one against the
+                    # live frame.
+                    hop_subject_prose = _refs.subject_prose(hop_active, ref_subjects)
+            if i == 0 and hop_subject_prose and not _d.is_full_h3_prompt(block):
+                block = hop_subject_prose + "\n\n" + block
+            if str(hop_script) == "next" and i > 0:
+                n_stills = len(base_images or {})
+                hop_state_header = _state_header(state, i)
+                # With a register wired, only the subject-bearing refs are
+                # identities; a setting or prop plate must not be declared one.
+                id_ords = None
+                n_subj = None
+                if hop_active:
+                    id_ords = [hop_ords[r["tag"]] for r in hop_active
+                               if r["subject"] is not None]
+                    # Counted over this hop, not the whole plan. Counting
+                    # plan-wide while listing only this hop's ordinals is how a
+                    # single scheduled still produced "<Picture 2> are the only
+                    # identities" -- the plural that has rendered two people
+                    # from one reference.
+                    n_subj = len({r["subject"] for r in hop_active
+                                  if r["subject"] is not None}) or None
+                elif ref_plan_refs:
+                    # Pin-only hop: no identity to lock. _identity_lock returns
+                    # "" on an empty ordinal list whatever the count says.
+                    id_ords = []
+                # Plan-wide, not per-hop: a character in the chain is in
+                # the chain whether or not their photograph rides this hop.
+                # This is the text that has to survive hop 5 of the showcase,
+                # which schedules no references at all.
+                hop_continuity = _refs.continuity_line(
+                    ref_subjects,
+                    {r["subject"] for r in ref_plan_refs
+                     if r["subject"] is not None}) if ref_plan_refs else ""
+                block = _assemble_next(
+                    block,
+                    live_picture=live_p,
+                    live_video=live_v,
+                    n_stills=n_stills,
+                    state_header=hop_state_header,
+                    identity_ordinals=id_ords,
+                    n_subjects=n_subj,
+                    tail=(shot.get("directives") or {}).get("tail"),
+                    continuity=hop_continuity,
+                )
+                print(f"[{TAG}] hop {i + 1} next-beat assembled "
+                      f"(Picture {live_p}, Video {live_v}, "
+                      f"{n_stills} identity stills, "
+                      f"state_header {len(hop_state_header)} chars, "
+                      f"continuity {len(hop_continuity)} chars)", flush=True)
+
+            assembled.append((i + 1, block))
+
+            # Key this hop. prev_key makes the key chained, so editing shot 1
+            # invalidates every hop after it -- correct, and the reason the UI
+            # must show staleness before queuing or it reads as a bug.
+            hop_key = None
+            cached = None
+            pin_mech_pred = _pin_mech_for(i, overlap_n, prev_sampled)
+            pin_mech_used = pin_mech_pred
+            if hop_store is not None:
+                hop_key = _store.hop_key(prev_key, {
+                    "chain": chain_salt,
+                    "block": block,
+                    "len": hop_length,
+                    "steps": int(shot.get("steps") or steps),
+                    "seed": (int(shot["seed"]) if shot.get("seed") is not None
+                             else ((int(seed) + i) if seed_per_shot else int(seed))),
+                    "tags": [r["tag"] for r in hop_active],
+                    # Per hop, not chain-wide: hop 2 after a hop-1 cache hit
+                    # has no sampler latent and falls back to AddGuide, which
+                    # is a different render of the same inputs.
+                    "pin_mech": pin_mech_pred,
+                    "pin_cond": (pin_renorm_on, round(pin_noise_v, 4), audio_ctx),
+                })
+                # A locked shot reuses its last render even though its inputs
+                # changed -- that is the point of locking. The content key would
+                # have moved, so the pointer is what finds it.
+                shot_name = str(shot.get("id") or f"shot{i + 1}")
+                if shot.get("locked"):
+                    pinned = hop_store.get_pointer(shot_name)
+                    if pinned:
+                        if pinned != hop_key:
+                            print(f"[{TAG}] hop {i + 1} is locked: reusing its "
+                                  f"earlier render (inputs changed)", flush=True)
+                        hop_key = pinned
+                    else:
+                        print(f"[{TAG}] hop {i + 1} is locked but has no cached "
+                              f"render yet; rendering it once", flush=True)
+                hop_keys.append(hop_key)
+                cached = hop_store.get(hop_key)
+
+            this_sampled = None
+            if cached is not None:
+                imgs, wav, sr, cached_latent = cached
+                audio = {"waveform": wav, "sample_rate": sr}
+                # Carry the stored sampler latent forward exactly as a render
+                # would. Without this the next hop sees no latent, predicts the
+                # AddGuide fallback, and its key stops matching what is on disk
+                # -- so nothing past hop 1 could ever hit, and the hop after a
+                # hit was joined by the weaker mechanism.
+                this_sampled = cached_latent
+                print(f"[{TAG}] hop {i + 1}: loaded from cache "
+                      f"({int(imgs.shape[0])}f, key {hop_key[:8]}"
+                      f"{'' if cached_latent is not None else ', no latent'})",
+                      flush=True)
+            else:
+                packed = MiniMaxH3ReferenceToVideo.execute(
+                    clip, vae, audio_vae, block, int(width), int(height), hop_length,
+                    ref_image_size=ref_image_size,
+                    ref_images=hop_images,
+                    ref_videos=hop_videos,
+                    ref_audios=ref_audios,
+                )
+                cond, latent = _result(packed)[0], _result(packed)[1]
+
+                if i == 0 and start_image is not None:
+                    cond = _result(MiniMaxH3AddGuide.execute(
+                        cond, latent, 0, vae=vae, audio_vae=None,
+                        image=start_image[:1], audio=None,
+                    ))[0]
+                elif i > 0:
+                    pin_latent = prev_sampled
+                    if pin_latent is not None:
+                        pin_latent, pin_anchor_std = _condition_pin_latent(
+                            pin_latent, pin_anchor_std,
+                            renorm=pin_renorm_on, noise=pin_noise_v,
+                            seed=(int(seed) + i))
+                    cond, pin_mech_used = _pin_continue(
+                        cond, latent, vae, audio_vae, overlap_n,
+                        pin_latent, prev_imgs, prev_audio,
+                        audio_ctx=audio_ctx,
+                    )
+
+                _offload_text_encoder(clip, model)
+
+                guider = _result(BasicGuider.execute(model, cond))[0]
+                if shot.get("seed") is not None:
+                    shot_seed = int(shot["seed"])
+                else:
+                    shot_seed = (int(seed) + i) if seed_per_shot else int(seed)
+                hop_steps = int(shot.get("steps") or steps)
+                if hop_steps not in sigma_cache:
+                    sigma_cache[hop_steps] = _result(
+                        BasicScheduler.execute(model, scheduler, hop_steps, 1.0))[0]
+                hop_sigmas = sigma_cache[hop_steps]
+                if hop_steps != int(steps) or shot.get("seed") is not None:
+                    print(f"[{TAG}] hop {i + 1} override: seed={shot_seed} "
+                          f"steps={hop_steps}", flush=True)
+                noise = _result(RandomNoise.execute(shot_seed))[0]
+                sampled = _result(SamplerCustomAdvanced.execute(
+                    noise, guider, sampler, hop_sigmas, latent
+                ))[0]
+
+                imgs, audio = _decode_av(vae, audio_vae, sampled)
+                imgs = imgs.contiguous().cpu()
+                wav = audio["waveform"].contiguous().cpu()
+                sr = int(audio["sample_rate"])
+                audio = {"waveform": wav, "sample_rate": sr}
+                this_sampled = _latent_cpu(sampled)
+
+                del sampled, latent, cond, guider, noise
+                mm.soft_empty_cache()
+
+                if (hop_store is not None and hop_key is not None
+                        and pin_mech_used != pin_mech_pred):
+                    print(f"[{TAG}] hop {i + 1} pinned by {pin_mech_used} but its "
+                          f"cache key says {pin_mech_pred}; not caching this hop",
+                          flush=True)
+                elif hop_store is not None and hop_key is not None:
+                    hop_store.put(hop_key, imgs, wav, sr,
+                                  {"hop": i + 1, "of": n, "block": block[:400],
+                                   "pin_mech": pin_mech_used},
+                                  latent=this_sampled)
+                    hop_store.set_pointer(
+                        str(shot.get("id") or f"shot{i + 1}"), hop_key)
+
+            # Tone compensation, at the one point both the render and the
+            # cache-hit paths have converged.
+            #
+            # It sits AFTER hop_store.put on purpose, so the cache holds raw
+            # hops and the mode stays out of the hop key -- switching modes
+            # then costs nothing instead of invalidating ~285 MB an entry.
+            # It sits BEFORE the master write and before `prev_imgs` is taken,
+            # which is the half that matters: `prev_imgs` is what feeds the next
+            # hop's Qwen <Picture 1> pin and the AddGuide guide image, so
+            # correcting here is what stops the drift compounding rather than
+            # merely repainting the master. Each hop is measured against the
+            # previous hop's ALREADY CORRECTED tail, so the whole chain lands on
+            # hop 1's tone.
+            tone_note = ""
+            if tone_on:
+                if i > 0 and prev_imgs is not None:
+                    imgs, tone_note = _tone.compensate(
+                        prev_imgs, imgs, tone_mode, overlap_n)
+                else:
+                    # Hop 1 has nothing to match against, but the corrected hops
+                    # come back clamped and an unclamped hop 1 beside them would
+                    # make the master inconsistent with itself.
+                    imgs = imgs.clamp(0.0, 1.0)
+                if tone_note:
+                    print(f"[{TAG}] hop {i + 1} tone: {tone_note}", flush=True)
+
+            if i == 0:
+                master_imgs[0:imgs.shape[0]] = imgs
+                write_pos = int(imgs.shape[0])
+                master_wav = wav
+            else:
+                if imgs.shape[0] <= overlap_n:
+                    raise ValueError(
+                        f"{TAG}: hop {i + 1} decoded {int(imgs.shape[0])} frames; "
+                        f"need more than overlap {overlap_n}"
+                    )
+                keep_n = int(imgs.shape[0]) - overlap_n
+                if write_pos + keep_n > total_frames:
+                    raise ValueError(
+                        f"{TAG}: hop {i + 1} overruns the preallocated master "
+                        f"({write_pos + keep_n} > {total_frames}). A hop decoded a "
+                        f"different length than planned.")
+                master_imgs[write_pos:write_pos + keep_n] = imgs[overlap_n:]
+                write_pos += keep_n
+                trimmed, dropped = _trim_audio_head(audio, overlap_n)
+                master_wav = _xfade_audio(master_wav, trimmed["waveform"], sr)
+                print(
+                    f"[{TAG}] hop {i + 1}: dropped {overlap_n} frames / {dropped} audio samples",
+                    flush=True,
+                )
+                del trimmed
+
+            # The join, as two pictures: the previous hop's last delivered frame
+            # and this hop's first. Sent together so the panel can show the
+            # actual seam rather than one frame per hop.
+            seam_frame = imgs[0] if i > 0 else None
+            # Overlap tail for Qwen; full sampler latent for Motion-Context.
+            tail_n = overlap_n if overlap_n else 1
+            prev_imgs = imgs[-tail_n:].clone()
+            prev_audio = {"waveform": _tail_audio(audio, overlap_n)["waveform"].clone(),
+                          "sample_rate": sr}
+            prev_sampled = this_sampled
+            prev_key = hop_key
+            _push_preview(
+                unique_id, f"hop {i + 1}/{n} done",
+                frame=prev_imgs[-1], hop=i + 1, total=n,
+                pin_mech=(pin_mech_used if i > 0 else None),
+                frac=(write_pos / float(total_frames) if total_frames else None),
+                seam_frame=seam_frame,
+                meta={"cached": cached is not None,
+                      "key": (hop_key[:8] if hop_key else None),
+                      "frames": int(write_pos), "of_frames": int(total_frames),
+                      "seed": int(shot_seed) if cached is None else None,
+                      "steps": int(hop_steps) if cached is None else None,
+                      "tone": tone_note or None})
+            del imgs, wav, audio
+            pbar.update(1)
+
+        if write_pos != total_frames:
+            print(f"[{TAG}] note: wrote {write_pos} of {total_frames} planned "
+                  f"frames; trimming", flush=True)
+            master_imgs = master_imgs[:write_pos]
+        if hop_store is not None:
+            hop_store.sweep(keep=hop_keys)
+        # lengths[0], not `length`: when every shot overrides duration to the
+        # same value the set is still size 1, but `length` is the chain default.
+        span = str(lengths[0]) if len(set(lengths)) == 1 else "/".join(str(v) for v in lengths)
+        info = (
+            f"{n} hops x {span}f overlap {overlap_n} -> "
+            f"{int(master_imgs.shape[0])} frames ({master_imgs.shape[0] / FPS:.1f}s) "
+            f"{int(master_imgs.shape[2])}x{int(master_imgs.shape[1])}"
+        )
+        print(f"[{TAG}] {info}", flush=True)
+        # The assembled prompts being inspectable is the whole point of the
+        # directive layer -- wire `info` to a Preview Text node to read exactly
+        # what each hop sent to the text encoder.
+        _sep = '\n\n'
+        info = info + _sep + _sep.join('===== hop %d prompt =====\n%s' % (k, t) for k, t in assembled)
+        # `info` is the third return (Preview Text). Never send it as the
+        # preview status — that strip is ~22 px and will render the dump.
+        _v_secs = float(master_imgs.shape[0]) / FPS
+        _a_secs = float(master_wav.shape[-1]) / float(sr) if sr else 0.0
+        _push_preview(
+            unique_id,
+            f"done · {int(master_imgs.shape[0])}f · {_v_secs:.1f}s",
+            frame=master_imgs[-1], hop=n, total=n, frac=1.0,
+            meta={"video_s": round(_v_secs, 3), "audio_s": round(_a_secs, 3),
+                  "drift_ms": round((_a_secs - _v_secs) * 1000.0, 1),
+                  "hops": int(n), "frames": int(master_imgs.shape[0]),
+                  "done": True})
+        master_audio = {"waveform": master_wav, "sample_rate": sr}
+        return (master_imgs, master_audio, info)
+
+
+class HTCContinuityState:
+    """Author locked/context/mutable *setting* text once; HandTieClips consumes it per hop.
+
+    locked and context ride every hop 2+ unchanged. mutable is --- delimited like the
+    prompt field: one beat per hop, padded by repeating the last block if there are
+    fewer blocks than hops.
+
+    Setting only. Characters live in `ref_plan`'s reference register, which is
+    the only thing that knows a photograph is a face rather than a room. This
+    node used to carry `characters_*` as well, so filling in both it and the
+    register injected identity prose twice into every hop 2+ -- run() warned
+    about that collision rather than preventing it. With the character half
+    gone the collision is structurally impossible.
+    """
+
+    @classmethod
+    def INPUT_TYPES(cls):
+        return {
+            "required": {},
+            "optional": {
+                "setting_locked": ("STRING", {
+                    "multiline": True, "default": "",
+                    "tooltip": "Verbatim setting text (location, lighting). Injected unchanged into every hop 2+.",
+                }),
+                "setting_context": ("STRING", {
+                    "multiline": True, "default": "",
+                    "tooltip": "Current-state setting text, less rigid than locked. Injected every hop 2+.",
+                }),
+                "setting_mutable": ("STRING", {
+                    "multiline": True, "default": "",
+                    "tooltip": "Per-hop setting beat text, --- delimited like characters_mutable.",
+                }),
+            },
+        }
+
+    RETURN_TYPES = ("STRING",)
+    RETURN_NAMES = ("continuity_state",)
+    FUNCTION = "run"
+    CATEGORY = "Hand Tie Clips"
+    DESCRIPTION = (
+        "Builds a JSON continuity-state blob (locked/context/mutable) for the "
+        "*setting* only, feeding HandTieClips's continuity_state input. "
+        "hop_script=next only. Characters belong in ref_plan's register."
+    )
+
+    def run(self, setting_locked="", setting_context="", setting_mutable=""):
+        state = {
+            "setting": {
+                "locked": setting_locked.strip(),
+                "context": setting_context.strip(),
+                "mutable": _parse_shots(setting_mutable) if setting_mutable.strip() else [],
+            },
+        }
+        return (json.dumps(state),)
+
+
+
+
+# -- pre-rename ids ----------------------------------------------------------
+# A plain alias in NODE_CLASS_MAPPINGS keeps old workflows loading, but it also
+# lists the node a second time in search: ComfyUI falls back to the mapping key
+# when NODE_DISPLAY_NAME_MAPPINGS has no entry. Subclassing and setting
+# DEPRECATED gets both -- server.py publishes `deprecated: True`, and the
+# frontend's `Comfy.Node.ShowDeprecated` (off by default) hides it from search
+# while leaving it fully functional in workflows that name it.
+
+
+class _LegacyH3RefChain(HandTieClips):
+    DEPRECATED = True
+
+
+class _LegacyH3ContinuityState(HTCContinuityState):
+    DEPRECATED = True
+
+
+NODE_CLASS_MAPPINGS = {
+    "HandTieClips": HandTieClips,
+    "HTCContinuityState": HTCContinuityState,
+    "H3RefChain": _LegacyH3RefChain,
+    "H3ContinuityState": _LegacyH3ContinuityState,
+}
+NODE_DISPLAY_NAME_MAPPINGS = {
+    "HandTieClips": "H3 Ref2VA Chain",
+    "HTCContinuityState": "H3 Continuity State",
+}

js/editor/media_picker.js

@@ -0,0 +1,259 @@
+/**
+ * Files in, without an IMAGE socket.
+ *
+ * A reference used to be a wire: nine `ref_image_N` sockets, nine `Load Image`
+ * nodes, and a sixteen-socket column eating a third of the node. A reference is
+ * now a *filename* under `<ComfyUI input>/h3_refs`, and this is the control that
+ * puts one there.
+ *
+ * Two rules, both learned by PromptMasterLD the expensive way:
+ *
+ *   1. **Pixels never enter a widget.** Only the basename is stored. Nine
+ *      base64 thumbnails measured 1.68 MB of widget value and ComfyUI then
+ *      failed to save the workflow at all. Previews are URLs, which cost
+ *      nothing to rebuild and survive a reload.
+ *   2. **Reads go through ComfyUI's own `/view`.** It already serves the input
+ *      directory with a guessed MIME type and Range support, which a `<video>`
+ *      needs in order to seek. A second thumbnail route would buy nothing.
+ *
+ * The upload is multipart rather than JSON+base64 so a batch of stills is not
+ * inflated by a third and held in memory twice on the way through the browser.
+ */
+
+import { el, button } from "./widget_utils.js";
+
+const UPLOAD_URL = "/h3_ref_chain/upload";
+const FILES_URL = "/h3_ref_chain/files";
+const SUBDIR = "h3_refs";
+
+/** Accept attributes, by what a control is for. */
+export const ACCEPT = {
+    image: "image/*",
+    video: "video/*",
+    audio: "audio/*",
+};
+
+/* -- the file list, cached and shared ------------------------------------ */
+
+let _files = null;
+let _pending = null;
+const _listeners = new Set();
+
+/** Everything currently in the reference folder. Cached; refresh() invalidates. */
+export function files() {
+    if (_files) return Promise.resolve(_files);
+    if (!_pending) {
+        _pending = fetch(FILES_URL)
+            .then((r) => (r.ok ? r.json() : Promise.reject(new Error(`HTTP ${r.status}`))))
+            .then((j) => {
+                _files = Array.isArray(j.files) ? j.files : [];
+                return _files;
+            })
+            .catch((err) => {
+                console.error("[HandTieClips] reference list unavailable:", err);
+                _files = [];
+                return _files;
+            })
+            .finally(() => { _pending = null; });
+    }
+    return _pending;
+}
+
+/** Re-read the folder and tell every mounted picker. */
+export function refresh() {
+    _files = null;
+    return files().then((list) => {
+        for (const fn of _listeners) {
+            try {
+                fn(list);
+            } catch (err) {
+                console.error("[HandTieClips] picker refresh failed:", err);
+            }
+        }
+        return list;
+    });
+}
+
+export function onFilesChanged(fn) {
+    _listeners.add(fn);
+    return () => _listeners.delete(fn);
+}
+
+/**
+ * The URL a preview is drawn from.
+ *
+ * Cache-busted because a filename can be reused: upload `face.png` twice and
+ * the second one collision-suffixes, but an *overwritten* file keeps its name
+ * and the browser would happily show the old bytes.
+ */
+export function viewUrl(name) {
+    const q = `filename=${encodeURIComponent(name)}`
+        + `&subfolder=${encodeURIComponent(SUBDIR)}&type=input&t=${Date.now()}`;
+    return `/view?${q}`;
+}
+
+/** Push files at the upload route. -> [{name, kind, width, height}] */
+export async function upload(fileList) {
+    const list = [...(fileList || [])];
+    if (!list.length) return [];
+    const fd = new FormData();
+    for (const f of list) fd.append("files", f, f.name);
+    const r = await fetch(UPLOAD_URL, { method: "POST", body: fd });
+    const j = await r.json().catch(() => ({}));
+    if (!r.ok || !j.ok) throw new Error(j.error || `upload failed (HTTP ${r.status})`);
+    for (const note of j.skipped || []) console.warn("[HandTieClips] upload skipped:", note);
+    await refresh();
+    return j.files || [];
+}
+
+/* -- one picker ---------------------------------------------------------- */
+
+/**
+ * A thumbnail that takes a drop, plus a list of what is already on disk.
+ *
+ * `get()` returns the current basename, `set(name)` stores a new one. The
+ * control owns no state of its own -- same rendering-layer contract as the rest
+ * of the editor, so undo and the JSON tab keep working.
+ */
+export function createPicker({ kind = "image", get, set, onChange, title } = {}) {
+    const root = el("div", "h3e-pick");
+
+    const thumb = el("div", "h3e-thumb");
+    thumb.title = title || "Drop a file here, or click to browse.";
+    root.appendChild(thumb);
+
+    const input = el("input");
+    input.type = "file";
+    input.accept = ACCEPT[kind] || "";
+    input.style.display = "none";
+    root.appendChild(input);
+
+    const picker = el("select", "h3e-select h3e-pickfile");
+    root.appendChild(picker);
+
+    let busy = false;
+
+    function paint() {
+        const name = String(get() || "");
+        thumb.textContent = "";
+        thumb.classList.toggle("h3e-has", Boolean(name));
+        if (busy) {
+            thumb.appendChild(el("span", "h3e-thumb-hint", "uploading…"));
+        } else if (!name) {
+            thumb.appendChild(el("span", "h3e-thumb-hint", "drop\nor click"));
+        } else if (kind === "image") {
+            const img = el("img", "h3e-thumb-img");
+            img.src = viewUrl(name);
+            img.alt = name;
+            // A file deleted from the folder behind our back must not leave a
+            // broken-image glyph with no explanation.
+            img.addEventListener("error", () => {
+                thumb.textContent = "";
+                thumb.appendChild(el("span", "h3e-thumb-hint h3e-thumb-bad", "missing"));
+            });
+            thumb.appendChild(img);
+        } else {
+            thumb.appendChild(el("span", "h3e-thumb-hint",
+                kind === "video" ? "▶ clip" : "♪ audio"));
+        }
+        if (name) {
+            thumb.title = `${name}\nClick to replace, or drop a new file.`;
+            const x = button("×", "Clear this picture", (e) => {
+                e.stopPropagation();
+                set("");
+                paint();
+                onChange?.();
+            }, "h3e-btn h3e-thumb-x");
+            thumb.appendChild(x);
+        } else {
+            thumb.title = title || "Drop a file here, or click to browse.";
+        }
+    }
+
+    function paintList(list) {
+        const name = String(get() || "");
+        picker.textContent = "";
+        const blank = el("option", null, "— none —");
+        blank.value = "";
+        picker.appendChild(blank);
+        let found = false;
+        for (const f of list || []) {
+            if (f.kind !== kind) continue;
+            const o = el("option", null, f.name);
+            o.value = f.name;
+            if (f.name === name) found = true;
+            picker.appendChild(o);
+        }
+        // A name that is no longer on disk still has to be selectable, or
+        // switching away from it would look like the value was never set.
+        if (name && !found) {
+            const o = el("option", null, `${name} (missing)`);
+            o.value = name;
+            picker.appendChild(o);
+        }
+        picker.value = name;
+    }
+
+    async function take(fileList) {
+        const list = [...(fileList || [])];
+        if (!list.length) return;
+        busy = true;
+        paint();
+        try {
+            const got = await upload(list.slice(0, 1));
+            if (got.length) {
+                set(got[0].name);
+                onChange?.();
+            }
+        } catch (err) {
+            console.error("[HandTieClips] upload failed:", err);
+            alert(`Upload failed: ${err.message || err}`);
+        } finally {
+            busy = false;
+            paint();
+        }
+    }
+
+    thumb.addEventListener("click", (e) => {
+        if (e.target.closest(".h3e-thumb-x")) return;
+        input.click();
+    });
+    input.addEventListener("change", () => {
+        take(input.files);
+        input.value = "";            // so re-picking the same file still fires
+    });
+    thumb.addEventListener("dragover", (e) => {
+        // Only light up for an actual file drag. Without this check, dragging a
+        // node across the canvas highlights every picker it passes over.
+        if (!e.dataTransfer?.types?.includes("Files")) return;
+        e.preventDefault();
+        e.stopPropagation();
+        thumb.classList.add("h3e-hot");
+    });
+    thumb.addEventListener("dragleave", () => thumb.classList.remove("h3e-hot"));
+    thumb.addEventListener("drop", (e) => {
+        if (!e.dataTransfer?.files?.length) return;
+        e.preventDefault();
+        e.stopPropagation();
+        thumb.classList.remove("h3e-hot");
+        take(e.dataTransfer.files);
+    });
+    picker.addEventListener("change", () => {
+        set(picker.value);
+        paint();
+        onChange?.();
+    });
+
+    const stop = onFilesChanged(paintList);
+    files().then(paintList);
+    paint();
+
+    return {
+        root,
+        render() {
+            paint();
+            files().then(paintList);
+        },
+        destroy: stop,
+    };
+}

js/editor/media_strip.js

@@ -0,0 +1,98 @@
+/**
+ * The three single media inputs: first frame, reference clip, voice.
+ *
+ * These were `start_image`, `reference_video` and `voice` IMAGE/AUDIO sockets.
+ * Together with the nine `ref_image_N` slots they were twelve of a sixteen
+ * socket column that occupied a third of the node before the editor started.
+ * They are filenames now, in `start_image_file` / `reference_video_file` /
+ * `voice_file`, and this strip is what sets them.
+ *
+ * Same rendering-layer contract as the rest of the editor: the widget is the
+ * store, this only draws it and writes back through `widget.callback`.
+ */
+
+import { el, widgetByName } from "./widget_utils.js";
+import { createPicker } from "./media_picker.js";
+
+/* Widget name -> what it is, in the order they are drawn. */
+const SLOTS = [
+    ["start_image_file", "image", "first frame",
+     "Pins hop 1's opening frame. Ignored on later hops -- they are pinned by the join."],
+    ["reference_video_file", "video", "reference clip",
+     "A motion or look plate the whole chain reads. NOT the previous hop; the join handles that."],
+    ["voice_file", "audio", "voice",
+     "Voice or timbre reference. Rides every hop as <Audio 1>."],
+];
+
+/** The widget names this strip owns, so the caller hides exactly those. */
+export const MEDIA_WIDGETS = SLOTS.map(([name]) => name);
+
+function commit(node, w, value) {
+    w.value = value;
+    try {
+        // Same reason as the run panel: setting `.value` alone leaves anything
+        // bound to this widget unaware that it changed.
+        w.callback?.(value, node.graph?.canvas, node, undefined, undefined);
+    } catch (err) {
+        console.error(`[HandTieClips] widget callback for ${w.name} failed:`, err);
+    }
+    node.graph?.setDirtyCanvas?.(true, true);
+}
+
+export function createMediaStrip(node, { onChange } = {}) {
+    const root = el("div", "h3e-section h3e-media");
+
+    const head = el("div", "h3e-head");
+    head.appendChild(el("span", "h3e-title", "MEDIA"));
+    const count = el("span", "h3e-count");
+    head.appendChild(count);
+    root.appendChild(head);
+
+    const grid = el("div", "h3e-media-grid");
+    root.appendChild(grid);
+
+    const pickers = [];
+    let missing = 0;
+
+    for (const [name, kind, label, tip] of SLOTS) {
+        const w = widgetByName(node, name);
+        if (!w) {
+            // A widget this build does not define is skipped, not warned about,
+            // so the strip survives an older Python side. Same rule as the run
+            // panel's group list.
+            missing += 1;
+            continue;
+        }
+        const cell = el("label", "h3e-media-cell");
+        cell.appendChild(el("span", "h3e-media-label", label));
+        const pick = createPicker({
+            kind,
+            get: () => String(w.value || ""),
+            set: (v) => commit(node, w, v),
+            onChange,
+            title: tip,
+        });
+        cell.title = tip;
+        cell.appendChild(pick.root);
+        grid.appendChild(cell);
+        pickers.push(pick);
+    }
+
+    if (missing === SLOTS.length) {
+        grid.appendChild(el("div", "h3e-note h3e-note-error",
+            "No media widgets found — restart ComfyUI so the Python side matches."));
+    }
+
+    function render() {
+        let set = 0;
+        for (const [name] of SLOTS) {
+            if (String(widgetByName(node, name)?.value || "")) set += 1;
+        }
+        count.textContent = set ? `${set} set` : "none set";
+        for (const p of pickers) p.render();
+    }
+
+    render();
+
+    return { root, render, ownedNames: () => MEDIA_WIDGETS.slice() };
+}

js/editor/plan_editor.js

@@ -0,0 +1,580 @@
+/**
+ * The shot plan editor.
+ *
+ * `shot_plan` (a hidden STRING widget) stays the ONLY source of truth. Every
+ * control here reads from it and writes straight back, so a workflow authored
+ * with the editor and one typed by hand are the same file, and anything the
+ * editor cannot express is still reachable through the JSON tab.
+ *
+ * Structure follows ComfyUI-MiniMaxH3-Contex-Loop's h3_chain_plan_editor.js,
+ * which solved this shape already. What is ours: the directive axes come from
+ * the server (see routes.py) rather than a second copy, the coherence rule is
+ * mirrored from plan.check_coherence, and the timing summary uses the real
+ * overlap arithmetic instead of a nominal per-shot duration.
+ */
+
+import {
+    el, button, select, vocab, widgetByName, refreshVocab, onVocabRefresh,
+} from "./widget_utils.js";
+import { createTemplatePanel } from "./templates.js";
+
+const MODE_PROP = "h3_editor_mode";        // "simple" | "shots"
+const FOLD_PROP = "h3_plan_folded";        // shot id -> collapsed
+const BACKUP_PROP = "h3_plan_backup";      // shot_plan stashed while in Simple
+
+/* -- plan model ---------------------------------------------------------- */
+
+export function parsePlan(text) {
+    // A widget value is not guaranteed to be a string. ComfyUI restores
+    // `widgets_values` POSITIONALLY, so a node whose widget list changed can
+    // hand this an int or a bool from a neighbouring widget. Coerce rather
+    // than throw: a wrong-typed plan should show the JSON tab, not abort the
+    // whole workflow load.
+    const t = String(text ?? "").trim();
+    if (!t) return [];
+    let data;
+    try {
+        data = JSON.parse(t);
+    } catch (_) {
+        return null; // signals "unparseable"; the JSON tab takes over
+    }
+    // Valid JSON that is not a plan (a bare `null`, a stray int from a
+    // misaligned widget) would otherwise be dereferenced below.
+    if (data === null || typeof data !== "object") return null;
+    const shots = Array.isArray(data) ? data : (data.shots || []);
+    if (!Array.isArray(shots)) return null;
+    return shots.map((s, i) => ({
+        id: String(s.id || `s${i + 1}`),
+        beat: String(s.beat || ""),
+        directives: Object.assign({}, s.directives || {}),
+        prose: String(s.prose || ""),
+        seed: s.seed == null ? null : Number(s.seed),
+        steps: s.steps == null ? null : Number(s.steps),
+        duration: s.duration || null,
+        locked: Boolean(s.locked),
+    }));
+}
+
+export function planToJson(shots) {
+    if (!shots || !shots.length) return "";
+    const out = shots.map((s) => {
+        const o = { id: s.id, beat: s.beat };
+        const dirs = {};
+        for (const [k, v] of Object.entries(s.directives || {})) if (v) dirs[k] = v;
+        if (Object.keys(dirs).length) o.directives = dirs;
+        if (s.prose) o.prose = s.prose;
+        if (s.seed != null) o.seed = s.seed;
+        if (s.steps != null) o.steps = s.steps;
+        if (s.duration) o.duration = s.duration;
+        if (s.locked) o.locked = true;
+        return o;
+    });
+    return JSON.stringify({ shots: out }, null, 2);
+}
+
+/**
+ * Mirrors plan.check_coherence. A framing change asks the audience to be
+ * somewhere new; with a held camera the only way to get there is a cut, so
+ * `continuous` and the framing change want opposite things.
+ */
+function coherenceWarning(shot, index) {
+    if (index === 0) return null;
+    const d = shot.directives || {};
+    const framing = d.framing || "";
+    const camera = d.camera || "";
+    if (d.join === "continuous" && framing && framing !== "keep" && (!camera || camera === "hold")) {
+        return `join=continuous with framing=${framing} and a held camera implies a cut. `
+             + "Use push_in / pull_back / pan_follow to reach that framing on the move, or framing=keep.";
+    }
+    return null;
+}
+
+/**
+ * Mirrors the direction check in plan.check_coherence: push_in narrows the
+ * frame and pull_back opens it, so naming the opposite destination is a
+ * physical contradiction at any join value.
+ */
+function directionWarning(shot) {
+    const d = shot.directives || {};
+    const pair = `${d.camera || ""}|${d.framing || ""}`;
+    if (pair === "push_in|wide" || pair === "pull_back|close") {
+        return `camera=${d.camera} moves the opposite way from framing=${d.framing}. `
+             + "Pick the framing the move actually lands on.";
+    }
+    return null;
+}
+
+/* -- editor -------------------------------------------------------------- */
+
+export function createPlanEditor(node, { onChange }) {
+    const planWidget = widgetByName(node, "shot_plan");
+    const promptWidget = widgetByName(node, "prompt");
+    const chainsWidget = widgetByName(node, "chains");
+    const durationWidget = widgetByName(node, "duration");
+    const overlapWidget = widgetByName(node, "overlap");
+
+    let V = null;
+    const initial = parsePlan(planWidget?.value);
+    let broken = initial === null;
+    let shots = initial || [];
+
+    const root = el("div", "h3e-section");
+
+    /* mode toggle */
+    const head = el("div", "h3e-head");
+    head.appendChild(el("span", "h3e-title", "SCRIPT"));
+    const summary = el("span", "h3e-count");
+    head.appendChild(summary);
+    head.appendChild(el("span", "h3e-spacer"));
+
+    const modeWrap = el("div", "h3e-modes");
+    const simpleBtn = button("Simple", "One prompt, repeated across N hops", () => setMode("simple"), "h3e-mode");
+    const shotsBtn = button("Shots", "One card per hop, with directives", () => setMode("shots"), "h3e-mode");
+    modeWrap.appendChild(simpleBtn);
+    modeWrap.appendChild(shotsBtn);
+    head.appendChild(modeWrap);
+    const blankShot = (i) => ({
+        id: `s${i + 1}`, beat: "", directives: {}, prose: "",
+        seed: null, steps: null, duration: null, locked: false,
+    });
+    const addBtn = button("+ shot", "Append a shot", () => {
+        shots.push(blankShot(shots.length));
+        commit();
+    });
+    head.appendChild(addBtn);
+
+    /* Templates append patterns rather than replacing the script. Replacing
+     * would be the one destructive button on the node, and appending is what
+     * you actually want -- a chain is built by stacking these. */
+    const templates = createTemplatePanel({
+        onPick: (picked) => {
+            if (mode() !== "shots") setMode("shots");
+            for (const sh of picked) shots.push({ ...sh, id: freeId() });
+            templates.hide();
+            tplBtn.classList.remove("h3e-on");
+            commit();
+        },
+    });
+    const tplBtn = button("Templates", "Insert a ready-made shot pattern", () => {
+        tplBtn.classList.toggle("h3e-on", templates.toggle());
+    });
+    head.appendChild(tplBtn);
+    root.appendChild(head);
+    root.appendChild(templates.root);
+
+    /** The lowest `sN` no shot is using. Appending a template onto a plan whose
+     *  ids are already s1..s3 must not mint a second s1: `id` is the hop
+     *  cache's pointer, and two shots sharing one would make `locked` reuse the
+     *  wrong render. */
+    function freeId() {
+        const used = new Set(shots.map((sh) => sh.id).filter(Boolean));
+        for (let n = 1; ; n += 1) {
+            const id = `s${n}`;
+            if (!used.has(id)) return id;
+        }
+    }
+
+    const simpleNote = el("div", "h3e-empty",
+        "Simple mode: the prompt widget below drives the run, repeated across `chains` hops "
+        + "(set under RUN). Switch to Shots to write one beat per hop with camera and "
+        + "join directives.");
+    root.appendChild(simpleNote);
+
+    const list = el("div", "h3e-shots");
+    root.appendChild(list);
+
+    /* JSON escape hatch */
+    const jsonWrap = el("details", "h3e-json-wrap");
+    const jsonSum = el("summary", null, "JSON");
+    jsonSum.title = "The literal shot_plan value. Editing here updates the cards.";
+    jsonWrap.appendChild(jsonSum);
+    const jsonArea = el("textarea", "h3e-json");
+    jsonArea.spellcheck = false;
+    jsonWrap.appendChild(jsonArea);
+    const jsonErr = el("div", "h3e-note");
+    jsonErr.style.display = "none";
+    jsonWrap.appendChild(jsonErr);
+    jsonArea.addEventListener("input", () => {
+        const parsed = parsePlan(jsonArea.value);
+        if (parsed === null) {
+            jsonErr.textContent = "Not valid JSON — the cards are showing the last good version.";
+            jsonErr.style.display = "";
+            return;
+        }
+        jsonErr.style.display = "none";
+        shots = parsed;
+        writeWidget();
+        renderCards();
+        onChange?.();
+    });
+    root.appendChild(jsonWrap);
+
+    /* The vocabulary is fetched once per browser session. When it fails the
+     * editor used to render with no directive controls at all and no
+     * explanation -- `_failed` was set and never read. Surface it, with a
+     * retry, and re-render every mounted editor when the retry succeeds. */
+    const offline = el("div", "h3e-offline");
+    offline.style.display = "none";
+    root.insertBefore(offline, root.firstChild);
+
+    function loadVocab() {
+        return vocab().then((v) => {
+            V = v;
+            offline.textContent = "";
+            if (v?._failed) {
+                offline.style.display = "";
+                const note = el("div", "h3e-note h3e-note-error",
+                    "Directive vocabulary unavailable"
+                    + (v._error ? ` (${v._error})` : "")
+                    + " — dropdowns are empty until it loads. Beats and JSON still work.");
+                offline.appendChild(note);
+                offline.appendChild(button("Retry", "Re-fetch /h3_ref_chain/vocab",
+                    () => { refreshVocab(); loadVocab(); }));
+            } else {
+                offline.style.display = "none";
+            }
+            renderCards();
+        });
+    }
+    loadVocab();
+    onVocabRefresh(() => { loadVocab(); });
+
+    /* -- state plumbing -- */
+
+    /* Collapsed cards persist in node.properties so the state survives both a
+     * re-render and a workflow reload. This is presentation state only -- it
+     * never affects what run() sees, so it is not a second source of truth for
+     * the plan itself. */
+    function foldState() {
+        const v = node.properties?.[FOLD_PROP];
+        return (v && typeof v === "object") ? v : {};
+    }
+    function setFoldState(next) {
+        if (!node.properties) node.properties = {};
+        node.properties[FOLD_PROP] = next;
+    }
+
+    function mode() {
+        const stored = node.properties?.[MODE_PROP];
+        if (stored === "simple" || stored === "shots") return stored;
+        // No stored preference: a saved plan means Shots, otherwise Simple.
+        return shots.length ? "shots" : "simple";
+    }
+
+    function setMode(next) {
+        node.properties ??= {};
+        if (next === "simple" && shots.length) {
+            // Simple mode has to clear shot_plan, or run() would ignore the
+            // prompt and use a stale plan. Stash it first -- silently losing an
+            // authored script to a toggle would be indefensible.
+            node.properties[BACKUP_PROP] = planToJson(shots);
+        }
+        if (next === "shots" && !shots.length && node.properties[BACKUP_PROP]) {
+            const restored = parsePlan(node.properties[BACKUP_PROP]);
+            if (restored && restored.length) {
+                shots = restored;
+                node.properties[MODE_PROP] = next;
+                commit();
+                return;
+            }
+        }
+        if (next === "shots" && !shots.length) {
+            // Offer the migration plan.py already implements rather than
+            // writing a second one here: one block + chains -> N shots.
+            const text = String(promptWidget?.value || "").trim();
+            const n = Math.max(1, parseInt(chainsWidget?.value, 10) || 1);
+            if (text) {
+                const blocks = text.split(/^\s*---\s*$/m).map((b) => b.trim()).filter(Boolean);
+                const use = blocks.length > 1 ? blocks.slice(0, n) : [text];
+                while (use.length < n) use.push("");
+                shots = use.map((b, i) => ({
+                    id: `s${i + 1}`, beat: b, directives: {}, prose: "",
+                    seed: null, steps: null, duration: null, locked: false,
+                }));
+            } else {
+                shots = [{ id: "s1", beat: "", directives: {}, prose: "",
+                           seed: null, steps: null, duration: null, locked: false }];
+            }
+        }
+        node.properties[MODE_PROP] = next;
+        commit();
+    }
+
+    function writeWidget() {
+        if (!planWidget) return;
+        // In Simple mode the plan must be empty, or run() would ignore `prompt`
+        // and silently use a stale plan — exactly the confusion this replaces.
+        planWidget.value = mode() === "shots" ? planToJson(shots) : "";
+        if (document.activeElement !== jsonArea) jsonArea.value = planWidget.value;
+    }
+
+    function commit() {
+        writeWidget();
+        renderCards();
+        onChange?.();
+    }
+
+    /* -- timing -- */
+
+    function timing() {
+        const durs = V?.durations || {};
+        const overs = V?.overlaps || {};
+        const fps = V?.fps || 24;
+        const baseDur = durationWidget?.value;
+        const ov = overs[overlapWidget?.value] ?? 0;
+        const lengths = shots.map((s) => durs[s.duration || baseDur] ?? durs[baseDur] ?? 0);
+        const total = lengths.reduce((a, b) => a + b, 0) - ov * Math.max(0, shots.length - 1);
+        return { lengths, ov, fps, total: Math.max(0, total) };
+    }
+
+    function clock(sec) {
+        if (!Number.isFinite(sec) || sec <= 0) return "—";
+        return `${sec.toFixed(1)}s`;
+    }
+
+    /* -- rendering -- */
+
+    function renderCard(shot, index) {
+        const card = el("div", "h3e-card");
+        card.dataset.index = String(index);
+
+        const bar = el("div", "h3e-card-head");
+        const drag = el("span", "h3e-drag", "⠿");
+        drag.title = "Drag to reorder";
+        drag.draggable = true;
+        drag.addEventListener("dragstart", (e) => {
+            e.dataTransfer.setData("text/plain", String(index));
+            e.dataTransfer.effectAllowed = "move";
+        });
+        bar.appendChild(drag);
+
+        // Collapse state is keyed by shot id, not index, so it survives a
+        // reorder as well as a re-render.
+        const key = shot.id || `s${index + 1}`;
+        const folded = Boolean(foldState()[key]);
+        if (folded) card.classList.add("h3e-collapsed");
+        const fold = button("", folded ? "Expand this shot" : "Collapse this shot", () => {
+            const st = foldState();
+            st[key] = !st[key];
+            setFoldState(st);
+            card.classList.toggle("h3e-collapsed");
+            fold.title = card.classList.contains("h3e-collapsed")
+                ? "Expand this shot" : "Collapse this shot";
+        }, "h3e-btn h3e-fold");
+        fold.appendChild(el("span", "h3e-fold-mark", "▾"));
+        bar.appendChild(fold);
+
+        bar.appendChild(el("span", "h3e-num", String(index + 1)));
+
+        const t = timing();
+        const frames = t.lengths[index] || 0;
+        const delivered = index === 0 ? frames : Math.max(0, frames - t.ov);
+        const badge = el("span", "h3e-timing", `${clock(delivered / t.fps)}`);
+        badge.title = index === 0
+            ? `${frames} frames.`
+            : `${frames} frames, ${t.ov} dropped into the previous hop's tail.`;
+        bar.appendChild(badge);
+
+        // Collapsed cards still need to say which shot they are.
+        const peekText = (shot.beat || "").replace(/\s+/g, " ").trim();
+        const peek = el("span", "h3e-peek", peekText.length > 70
+            ? peekText.slice(0, 67) + "…" : (peekText || "(continues)"));
+        peek.title = peekText;
+        bar.appendChild(peek);
+
+        if (shot.locked) {
+            const lock = el("span", "h3e-lock", "locked");
+            lock.title = "Reuses this shot's cached render even when its inputs changed. Needs cache_hops=on.";
+            bar.appendChild(lock);
+        }
+        bar.appendChild(button("×", "Delete this shot", () => {
+            shots.splice(index, 1);
+            commit();
+        }, "h3e-btn h3e-x"));
+        card.appendChild(bar);
+
+        card.addEventListener("dragover", (e) => { e.preventDefault(); card.classList.add("h3e-drop"); });
+        card.addEventListener("dragleave", () => card.classList.remove("h3e-drop"));
+        card.addEventListener("drop", (e) => {
+            e.preventDefault();
+            card.classList.remove("h3e-drop");
+            const from = parseInt(e.dataTransfer.getData("text/plain"), 10);
+            if (!Number.isFinite(from) || from === index) return;
+            const [moved] = shots.splice(from, 1);
+            shots.splice(index, 0, moved);
+            commit();
+        });
+
+        const body = el("div", "h3e-card-body");
+        const beat = el("textarea", "h3e-beat");
+        beat.value = shot.beat || "";
+        beat.rows = 3;
+        beat.placeholder = index === 0
+            ? "The whole opening: who, where, what they are doing."
+            : "Only what is NEW this hop. The identity lock and the join are added for you.";
+        beat.title = index === 0
+            ? "Shot 1 is the full establishing prompt."
+            : "Shots after the first are the new beat only — do not re-describe the face or replay the scene.";
+        // Write on every keystroke, not on "change". A textarea only fires
+        // "change" on blur, so saving the workflow with the caret still in the
+        // box silently discarded everything typed since the last blur.
+        beat.addEventListener("input", () => { shot.beat = beat.value; writeWidget(); });
+        beat.addEventListener("change", () => { writeWidget(); onChange?.(); });
+        body.appendChild(beat);
+
+        // directive row
+        const dirs = el("div", "h3e-dirs");
+        for (const axis of (V?.axes || [])) {
+            // join has nothing to attach to on hop 1 — directive_prose skips it.
+            if (axis === "join" && index === 0) continue;
+            const opts = Object.keys(V.vocab[axis] || {});
+            const wrap = el("label", "h3e-dir");
+            wrap.appendChild(el("span", "h3e-dir-label", axis));
+            const def = V.defaults?.[axis];
+            const sel = select(opts, shot.directives[axis] || "", (v) => {
+                shot.directives[axis] = v;
+                commit();
+            }, {
+                blankLabel: def ? `${def.replace(/_/g, " ")} (default)` : "—",
+                titles: V.vocab[axis] || {},
+            });
+            sel.title = `Hover an option to read the exact sentence it puts in the prompt.`;
+            wrap.appendChild(sel);
+            dirs.appendChild(wrap);
+        }
+        body.appendChild(dirs);
+
+        for (const [text, cls] of [[coherenceWarning(shot, index), "h3e-note h3e-note-hint"],
+                                   [directionWarning(shot), "h3e-note"]]) {
+            if (text) body.appendChild(el("div", cls, text));
+        }
+        if (directionWarning(shot)) card.classList.add("h3e-invalid");
+
+        // advanced
+        const adv = el("details", "h3e-adv");
+        adv.appendChild(el("summary", null, "advanced"));
+        const grid = el("div", "h3e-grid");
+
+        const num = (label, key, placeholder, hint) => {
+            const l = el("label", "h3e-field");
+            l.appendChild(el("span", null, label));
+            const i = el("input", "h3e-input");
+            i.type = "number";
+            i.value = shot[key] == null ? "" : String(shot[key]);
+            i.placeholder = placeholder;
+            i.title = hint;
+            i.addEventListener("input", () => {
+                shot[key] = i.value === "" ? null : Number(i.value);
+                writeWidget();
+            });
+            i.addEventListener("change", () => {
+                shot[key] = i.value === "" ? null : Number(i.value);
+                commit();
+            });
+            l.appendChild(i);
+            return l;
+        };
+        grid.appendChild(num("seed", "seed", "chain seed", "Override the seed for this hop only."));
+        grid.appendChild(num("steps", "steps", "chain steps", "Override the step count for this hop only."));
+
+        const durL = el("label", "h3e-field");
+        durL.appendChild(el("span", null, "duration"));
+        const durSel = select(Object.keys(V?.durations || {}), shot.duration || "", (v) => {
+            shot.duration = v || null;
+            commit();
+        }, { blankLabel: `${durationWidget?.value || "chain"} (default)` });
+        durSel.title = "Override this hop's length. Must be longer than the overlap.";
+        durL.appendChild(durSel);
+        grid.appendChild(durL);
+
+        const lockL = el("label", "h3e-field h3e-check");
+        const cb = el("input");
+        cb.type = "checkbox";
+        cb.checked = Boolean(shot.locked);
+        cb.title = "Pin this hop to its cached render regardless of what changed. Needs cache_hops=on.";
+        cb.addEventListener("change", () => { shot.locked = cb.checked; commit(); });
+        lockL.appendChild(cb);
+        lockL.appendChild(el("span", null, "locked"));
+        grid.appendChild(lockL);
+
+        const idL = el("label", "h3e-field");
+        idL.appendChild(el("span", null, "id"));
+        const idI = el("input", "h3e-input");
+        idI.type = "text";
+        idI.value = shot.id || "";
+        idI.title = "Stable name, used as the cache pointer for `locked`.";
+        idI.addEventListener("input", () => { shot.id = idI.value.trim() || `s${index + 1}`; writeWidget(); });
+        idI.addEventListener("change", () => { shot.id = idI.value.trim() || `s${index + 1}`; commit(); });
+        idL.appendChild(idI);
+        grid.appendChild(idL);
+        adv.appendChild(grid);
+
+        const prose = el("textarea", "h3e-beat");
+        prose.rows = 2;
+        prose.value = shot.prose || "";
+        prose.placeholder = "prose appended verbatim (for anything the directives lack)";
+        prose.title = "Added to the end of this hop's body, unmodified. Affirmative phrasing only — "
+            + "sampling runs at cfg 1.0, so anything named is added, never subtracted.";
+        prose.addEventListener("input", () => { shot.prose = prose.value; writeWidget(); });
+        prose.addEventListener("change", () => { writeWidget(); onChange?.(); });
+        adv.appendChild(prose);
+        body.appendChild(adv);
+        card.appendChild(body);
+
+        return card;
+    }
+
+    function renderCards() {
+        const m = mode();
+        simpleBtn.classList.toggle("h3e-on", m === "simple");
+        shotsBtn.classList.toggle("h3e-on", m === "shots");
+        simpleNote.style.display = m === "simple" ? "" : "none";
+        list.style.display = m === "simple" ? "none" : "";
+        jsonWrap.style.display = m === "simple" ? "none" : "";
+        addBtn.style.display = m === "simple" ? "none" : "";
+        tplBtn.style.display = m === "simple" ? "none" : "";
+        if (m === "simple") {
+            templates.hide();
+            tplBtn.classList.remove("h3e-on");
+        }
+
+        if (m === "simple") {
+            summary.textContent = `${chainsWidget?.value || 1} hop(s)`;
+            return;
+        }
+
+        list.textContent = "";
+        if (broken) {
+            const note = el("div", "h3e-note h3e-note-error",
+                "shot_plan is not valid JSON. Fix it in the JSON section below and the cards will come back.");
+            list.appendChild(note);
+            return;
+        }
+        if (!shots.length) {
+            const empty = el("div", "h3e-empty",
+                "No shots yet. Shot 1 is the whole opening; every shot after it is only what happens next.");
+            empty.appendChild(button("+ Add shot 1", "Add the opening shot", () => {
+                shots.push(blankShot(shots.length));
+                commit();
+            }, "h3e-btn h3e-empty-cta"));
+            list.appendChild(empty);
+        }
+        shots.forEach((s, i) => list.appendChild(renderCard(s, i)));
+
+        const t = timing();
+        summary.textContent = shots.length
+            ? `${shots.length} shots · ${clock(t.total / t.fps)} master`
+            : "empty";
+    }
+
+    /** Re-read the widget after an external change (workflow load, undo). */
+    function reload() {
+        const parsed = parsePlan(planWidget?.value);
+        broken = parsed === null;
+        if (!broken) shots = parsed;
+        if (document.activeElement !== jsonArea) jsonArea.value = planWidget?.value || "";
+        renderCards();
+    }
+
+    return { root, render: renderCards, reload, mode };
+}

js/editor/ref_rail.js

@@ -0,0 +1,408 @@
+/**
+ * The reference rail: what each wired still is, and what it is for.
+ *
+ * Mirrors `refs.py`. Two things it surfaces that the console only told you
+ * about after you queued:
+ *
+ *   - a ref whose picture is missing or never chosen (refs.check)
+ *   - duplicate tags (parse_ref_plan raises on these, so a typo used to cost
+ *     you a failed run instead of a red row)
+ *   - a ref carried over from when references were wired to ref_image_N
+ *     sockets, which cannot be migrated automatically: the socket held a
+ *     tensor and there is no filename to recover, so the row says which
+ *     slot it used to be and asks for the picture.
+ *
+ * The ordinal badge is the point of the whole module. Core assigns
+ * `<Picture N>` by position, so pulling a Load Image out renumbers everything
+ * after it; here the ordinal is derived and shown live, and prose refers to the
+ * stable @tag instead.
+ */
+
+import { el, button, select, vocab, onVocabRefresh } from "./widget_utils.js";
+import { createPicker } from "./media_picker.js";
+
+const MAX_SLOTS = 9;
+
+function blankRef(existing) {
+    let n = existing.length + 1;
+    const tags = new Set(existing.map((r) => r.tag));
+    while (tags.has(`ref_${n}`)) n += 1;
+    // No slot: the ordinal is the row's position now, and the picture is
+    // chosen in the row itself.
+    return { tag: `ref_${n}`, file: "", subject: null, retention: "", desc: "" };
+}
+
+export function parseRefPlan(text) {
+    // A widget value is not guaranteed to be a string. ComfyUI restores
+    // `widgets_values` POSITIONALLY, so a node whose widget list changed can
+    // hand this an int or a bool from a neighbouring widget. Coerce rather
+    // than throw: a wrong-typed plan should show the JSON tab, not abort the
+    // whole workflow load.
+    const t = String(text ?? "").trim();
+    if (!t) return { refs: [], subjects: {} };
+    let data;
+    try {
+        data = JSON.parse(t);
+    } catch (_) {
+        return null; // caller keeps the raw text and shows the JSON tab
+    }
+    // Same guard as plan_editor: valid JSON that is not a plan.
+    if (data === null || typeof data !== "object") return null;
+    const refs = Array.isArray(data) ? data : (data.refs || []);
+    const subjects = (Array.isArray(data) ? {} : (data.subjects || {})) || {};
+    return {
+        refs: refs.map((r, i) => ({
+            tag: String(r.tag || "").replace(/^@/, ""),
+            file: String(r.file || ""),
+            // A plan authored against the sockets carries a slot and no file.
+            // Kept only so the row can say what it used to be plugged into.
+            legacy_slot: (!r.file && r.slot != null) ? Number(r.slot) : null,
+            // Derived, never authored -- mirrors refs.py.
+            slot: i + 1,
+            subject: r.subject == null ? null : Number(r.subject),
+            retention: r.retention || "",
+            desc: r.desc || "",
+            shots: Array.isArray(r.shots) ? r.shots.slice() : null,
+        })),
+        subjects,
+    };
+}
+
+export function refPlanToJson(plan) {
+    if (!plan.refs.length && !Object.keys(plan.subjects).length) return "";
+    const refs = plan.refs.map((r) => {
+        // `slot` is deliberately not written back: it is derived from row
+        // order on both sides, and persisting it would resurrect the socket
+        // number a legacy plan is trying to leave behind.
+        const out = { tag: r.tag };
+        if (r.file) out.file = r.file;
+        else if (r.legacy_slot) out.slot = r.legacy_slot;
+        if (r.subject != null) out.subject = r.subject;
+        if (r.retention) out.retention = r.retention;
+        if (r.desc) out.desc = r.desc;
+        if (r.shots && r.shots.length) out.shots = r.shots;
+        return out;
+    });
+    const body = { refs };
+    if (Object.keys(plan.subjects).length) body.subjects = plan.subjects;
+    return JSON.stringify(body, null, 2);
+}
+
+/** Rows that actually name a picture. Only these take a <Picture N> ordinal. */
+function wiredSlots(plan) {
+    const out = new Set();
+    (plan.refs || []).forEach((r, i) => {
+        if (r.file) out.add(i + 1);
+    });
+    return out;
+}
+
+/**
+ * Per-hop ordinals, exactly as `refs.active_refs` + `refs.ordinals` compute
+ * them: slot order, restricted to slots with an image.
+ */
+function ordinalsFor(plan, wired) {
+    const active = plan.refs
+        .filter((r) => wired.has(r.slot))
+        .sort((a, b) => a.slot - b.slot);
+    const ords = new Map();
+    active.forEach((r, i) => ords.set(r.tag, i + 1));
+    return ords;
+}
+
+function validate(plan, wired) {
+    const problems = new Map(); // tag -> message
+    const seenTag = new Map();
+    const seenSlot = new Map();
+    for (const r of plan.refs) {
+        if (!r.tag) {
+            problems.set(r, "a tag is required — prose refers to it as @tag");
+            continue;
+        }
+        if (seenTag.has(r.tag)) {
+            problems.set(r, `@${r.tag} is already used — tags must be unique`);
+        }
+        seenTag.set(r.tag, r);
+        if (seenSlot.has(r.slot)) {
+            problems.set(r, `slot ${r.slot} is already taken by @${seenSlot.get(r.slot).tag}`);
+        }
+        seenSlot.set(r.slot, r);
+        if (!wired.has(r.slot)) {
+            problems.set(r, r.legacy_slot
+                ? `was wired to ref_image_${r.legacy_slot}, which no longer exists `
+                  + `— pick its picture to bring this ref back`
+                : "no picture chosen — this ref is inactive");
+        }
+    }
+    // A subject block nothing points at is continuity prose for someone who
+    // never appears; parse_ref_plan rejects it outright.
+    const used = new Set(plan.refs.filter((r) => r.subject != null).map((r) => String(r.subject)));
+    const orphans = Object.keys(plan.subjects).filter((k) => !used.has(String(k)));
+    return { problems, orphans };
+}
+
+export function createRefRail(node, { getPlan, setPlan, onChange, hopCount,
+                                      getRaw, isBad }) {
+    const root = el("div", "h3e-section");
+    const head = el("div", "h3e-head");
+    const title = el("span", "h3e-title", "REFERENCES");
+    const count = el("span", "h3e-count");
+    head.appendChild(title);
+    head.appendChild(count);
+    head.appendChild(el("span", "h3e-spacer"));
+    head.appendChild(button("+ ref", "Add a reference row", () => {
+        const plan = getPlan();
+        plan.refs.push(blankRef(plan.refs));
+        setPlan(plan);
+        render();
+        onChange?.();
+    }));
+    root.appendChild(head);
+
+    const list = el("div", "h3e-refs");
+    root.appendChild(list);
+
+    /* JSON escape hatch, mirroring the one in the SCRIPT section.
+     *
+     * Without it the rail was the ONLY editor for `ref_plan`, which made a
+     * model-authored register unpastable: prompt_pack hands the author two
+     * JSON documents and only `shot_plan` had a box to paste into.
+     *
+     * It also closes a quieter bug. `parseRefPlan` returns null on text it
+     * cannot read, and the caller swapped in an empty plan -- so the next rail
+     * edit wrote "" over the very text the author was trying to repair. The
+     * paste was destroyed by the act of fixing it. Now the raw value stays in
+     * the widget until something parses, and this box is where it shows.
+     */
+    const jsonWrap = el("details", "h3e-json-wrap");
+    const jsonSum = el("summary", null, "JSON");
+    jsonSum.title = "The literal ref_plan value. Editing here updates the rows.";
+    jsonWrap.appendChild(jsonSum);
+    const jsonArea = el("textarea", "h3e-json");
+    jsonArea.spellcheck = false;
+    jsonArea.placeholder = '{"refs": [{"tag": "hero_face", "file": "face.jpg", '
+        + '"subject": 1, "retention": "fully_preserved", "shots": [1, 2]}], '
+        + '"subjects": {"1": {"name": "the cook", "locked": "..."}}}';
+    jsonWrap.appendChild(jsonArea);
+    const jsonErr = el("div", "h3e-note");
+    jsonErr.style.display = "none";
+    jsonWrap.appendChild(jsonErr);
+    jsonArea.addEventListener("input", () => {
+        const parsed = parseRefPlan(jsonArea.value);
+        if (parsed === null) {
+            jsonErr.textContent =
+                "Not valid JSON -- the rows are showing the last good version.";
+            jsonErr.classList.add("h3e-note-error");
+            jsonErr.style.display = "";
+            return;
+        }
+        jsonErr.style.display = "none";
+        jsonErr.classList.remove("h3e-note-error");
+        setPlan(parsed);
+        onChange?.();
+        render();
+    });
+    root.appendChild(jsonWrap);
+
+    let V = null;
+    vocab().then((v) => { V = v; render(); });
+    // Re-render when a retry in the plan editor reloads the vocabulary.
+    onVocabRefresh(() => vocab().then((v) => { V = v; render(); }));
+
+    function commit() {
+        setPlan(getPlan());
+        onChange?.();
+        render();
+    }
+
+    function renderSubject(num) {
+        const plan = getPlan();
+        const s = plan.subjects[num] || (plan.subjects[num] = { name: "", locked: "", context: "" });
+        const box = el("div", "h3e-subject");
+        box.appendChild(el("span", "h3e-subj-badge", `Subject ${num}`));
+
+        const mk = (key, placeholder, hint) => {
+            const i = el("input", "h3e-input");
+            i.type = "text";
+            i.value = s[key] || "";
+            i.placeholder = placeholder;
+            i.title = hint;
+            i.addEventListener("input", () => { s[key] = i.value; setPlan(plan); onChange?.(); });
+            return i;
+        };
+        box.appendChild(mk("name", "what to call them",
+            "Used as “<Subject N> is <name>, the person in <Picture …>”. A role works better than a proper name."));
+        box.appendChild(mk("locked", "traits that must not drift",
+            "Injected verbatim on every hop. Only put things that are actually in the photograph here — at cfg 1.0 every word is additive."));
+        box.appendChild(mk("context", "current standing state",
+            "Same as locked but less rigid: what they are wearing right now, current mood."));
+        return box;
+    }
+
+    function render() {
+        list.textContent = "";
+        // Never while focused: it would reformat mid-keystroke and steal the caret.
+        if (document.activeElement !== jsonArea) jsonArea.value = getRaw?.() ?? "";
+        const plan = getPlan();
+        if (!plan) return;
+        if (isBad?.()) {
+            jsonWrap.open = true;
+            list.appendChild(el("div", "h3e-note h3e-note-error",
+                "ref_plan is not valid JSON. Fix it in the JSON section below "
+                + "and the rows will come back."));
+        }
+        const wired = wiredSlots(plan);
+        const ords = ordinalsFor(plan, wired);
+        const { problems, orphans } = validate(plan, wired);
+        count.textContent = `${plan.refs.length} · ${wired.size} with a picture`;
+
+        if (!plan.refs.length) {
+            const empty = el("div", "h3e-empty",
+                "No references. Add one per picture, then write @tag in your beats.");
+            list.appendChild(empty);
+        }
+
+        const bySubject = new Map();
+        for (const r of plan.refs) {
+            const row = el("div", "h3e-ref");
+            const bad = problems.get(r);
+            if (bad) row.classList.add("h3e-bad");
+            if (!wired.has(r.slot)) row.classList.add("h3e-inactive");
+
+            const ord = ords.get(r.tag);
+            const badge = el("span", "h3e-ord", ord ? String(ord) : "–");
+            badge.title = ord
+                ? `Resolves to <Picture ${ord}> on every hop this ref is active.`
+                : "No picture, so it takes no ordinal this run.";
+            row.appendChild(badge);
+
+            const tag = el("input", "h3e-input h3e-tag");
+            tag.type = "text";
+            tag.value = "@" + r.tag;
+            tag.title = "Stable name. Write this in a beat and it resolves to the right picture per hop.";
+            // Push to the widget per keystroke; commit() re-renders and would
+            // steal the caret, so only the blur handler may call it.
+            tag.addEventListener("input", () => {
+                r.tag = tag.value.trim().replace(/^@/, "").replace(/[^A-Za-z0-9_]/g, "_");
+                setPlan(plan);
+            });
+            tag.addEventListener("change", commit);
+            row.appendChild(tag);
+
+            // Was a `slot N` dropdown naming one of nine IMAGE sockets. The
+            // picture itself lives here now: drop a file on it, click to
+            // browse, or choose one already in the reference folder.
+            const pick = createPicker({
+                kind: "image",
+                get: () => r.file || "",
+                set: (v) => {
+                    r.file = v;
+                    // Choosing a picture is what retires a legacy row, so the
+                    // "was wired to slot N" note has to go with it.
+                    if (v) r.legacy_slot = null;
+                },
+                onChange: () => { commit(); render(); },
+                title: "The picture this reference stands for. Drop a file, or click to browse.",
+            });
+            pick.root.classList.add("h3e-slot");
+            row.appendChild(pick.root);
+
+            const subj = el("select", "h3e-select h3e-subj");
+            const none = el("option", null, "setting/prop");
+            none.value = "";
+            subj.appendChild(none);
+            for (let i = 1; i <= 4; i += 1) {
+                const o = el("option", null, `Subject ${i}`);
+                o.value = String(i);
+                subj.appendChild(o);
+            }
+            subj.value = r.subject == null ? "" : String(r.subject);
+            subj.title = "Group pictures of the SAME person under one subject number. "
+                + "Two different people sharing a number makes the model render the average of their faces.";
+            subj.addEventListener("change", () => {
+                r.subject = subj.value === "" ? null : Number(subj.value);
+                if (!r.retention) r.retention = r.subject ? "fully_preserved" : "reference";
+                commit();
+            });
+            row.appendChild(subj);
+
+            const retOpts = Object.keys(V?.retention || {});
+            const ret = select(retOpts, r.retention, (v) => { r.retention = v; commit(); }, {
+                blankLabel: r.subject ? "fully preserved" : "reference",
+                titles: V?.retention || {},
+            });
+            ret.classList.add("h3e-ret");
+            ret.title = "How much of this picture carries over. Hover an option for the exact sentence.";
+            row.appendChild(ret);
+
+            const desc = el("input", "h3e-input h3e-desc");
+            desc.type = "text";
+            desc.value = r.desc || "";
+            desc.placeholder = "describe this photo";
+            desc.title = "Goes into retention_analysis verbatim. Describe the picture you actually wired — "
+                + "at cfg 1.0 a detail that is not there is asked for, not ignored.";
+            desc.addEventListener("input", () => { r.desc = desc.value; setPlan(plan); });
+            desc.addEventListener("change", commit);
+            row.appendChild(desc);
+
+            row.appendChild(button("×", "Remove this reference", () => {
+                const p = getPlan();
+                p.refs.splice(p.refs.indexOf(r), 1);
+                setPlan(p);
+                onChange?.();
+                render();
+            }, "h3e-btn h3e-x"));
+
+            /* Which hops this photograph rides. An empty schedule means hop 1
+             * only on a `next` chain -- that is the pin-only recipe
+             * chain_00037/00038 were rendered with, and until now it could
+             * only be set by hand in the JSON. */
+            const hops = Math.max(1, Number(hopCount?.() || 1));
+            const chips = el("div", "h3e-chips");
+            chips.appendChild(el("span", "h3e-chips-label", "rides hops"));
+            for (let h = 1; h <= hops; h += 1) {
+                const on = Array.isArray(r.shots) && r.shots.includes(h);
+                const chip = el("span", "h3e-chip" + (on ? " h3e-chip-on" : ""), String(h));
+                chip.title = on
+                    ? `This photograph is sent to the encoder on hop ${h}. Click to remove it.`
+                    : `Click to also send this photograph on hop ${h}. `
+                      + "Leave every hop off to let the motion pin carry wardrobe and room.";
+                chip.addEventListener("click", () => {
+                    const cur = Array.isArray(r.shots) ? r.shots.slice() : [];
+                    const at = cur.indexOf(h);
+                    if (at >= 0) cur.splice(at, 1); else cur.push(h);
+                    cur.sort((a, b) => a - b);
+                    r.shots = cur.length ? cur : null;
+                    commit();
+                    render();
+                });
+                chips.appendChild(chip);
+            }
+            if (!Array.isArray(r.shots) || !r.shots.length) {
+                const note = el("span", "h3e-chips-label", "— unscheduled: hop 1 only");
+                note.title = "With no hops selected this still stays off hop 2+ of a `next` chain, "
+                    + "so the motion pin carries continuity instead of the photograph.";
+                chips.appendChild(note);
+            }
+            row.appendChild(chips);
+
+            list.appendChild(row);
+            if (bad) {
+                const note = el("div", "h3e-note h3e-note-error", bad);
+                list.appendChild(note);
+            }
+            if (r.subject != null) bySubject.set(r.subject, true);
+        }
+
+        for (const num of [...bySubject.keys()].sort((a, b) => a - b)) {
+            list.appendChild(renderSubject(num));
+        }
+        for (const num of orphans) {
+            const warn = el("div", "h3e-note",
+                `Subject ${num} has continuity text but no ref claims it. Give a ref that subject number, or clear the text — the run will refuse otherwise.`);
+            list.appendChild(warn);
+        }
+    }
+
+    return { root, render };
+}

js/editor/run_panel.js

@@ -0,0 +1,369 @@
+/**
+ * The run panel: every dial that is not per-shot, grouped and labelled.
+ *
+ * The shot cards made the *script* legible and left the other twenty-odd
+ * widgets stacked underneath as a wall of raw controls, in definition order,
+ * with no grouping -- so the node read as "a polished editor, then a heap".
+ * The dials with the least obvious semantics (`pin_renorm`, `pin_noise`,
+ * `cache_budget_gb`) were indistinguishable from the ones nobody touches.
+ *
+ * Same contract as the shot editor: this is a RENDERING LAYER over the native
+ * widgets, never a second source of truth. Every control writes straight back
+ * to `widget.value` and fires the widget's own callback, so the workflow JSON
+ * is byte-identical to one produced by the stock UI, and anything this panel
+ * cannot express is still reachable by dropping it from the group list.
+ *
+ * Help text is read from `widget.options.tooltip`, i.e. the `tooltip` written in
+ * INPUT_TYPES. Retyping those sentences here would be a second copy that goes
+ * stale, for exactly the reason routes.py exists.
+ */
+
+import { el, widgetByName, widgetType, widgetOptions } from "./widget_utils.js";
+
+const OPEN_PROP = "h3_run_open";
+
+/**
+ * Groups, in draw order; names are native widget names.
+ *
+ * A name this build does not define is skipped rather than warned about, so the
+ * list can carry a widget that only exists on a newer Python side. The flip
+ * side is that a *renamed* widget silently drops out of the panel and reappears
+ * as a raw dial below it -- the safe direction to fail, and visible the moment
+ * you look at the node.
+ */
+const GROUPS = [
+    ["output", ["resolution", "aspect", "duration", "overlap", "chains"]],
+    ["sampling", ["steps", "sampler_name", "scheduler", "seed",
+                  "control_after_generate", "seed_per_shot",
+                  "shift_video", "shift_audio"]],
+    ["join & pin", ["hop_script", "pin_to_qwen", "ref_image_size",
+                    "audio_pin_frames", "pin_renorm", "pin_noise",
+                    "tone_compensate"]],
+    ["cache", ["cache_hops", "cache_budget_gb"]],
+];
+
+/**
+ * Why a dial is not drawn in the current mode.
+ *
+ * `run()` ignores `chains` and forces `hop_script=next` the moment a shot plan
+ * is present (h3_ref_chain.py:1187-1192, which prints both overrides). Drawing
+ * them anyway would offer two controls that do nothing, which is worse than not
+ * offering them -- so the panel drops them in Shots mode and says why.
+ */
+/**
+ * Dials that need two grid cells.
+ *
+ * A seed is up to 19 digits and a truncated one cannot be read back to
+ * reproduce a render, which is the only reason to look at it.
+ */
+const WIDE = new Set(["seed"]);
+
+const SUPPRESSED_WHY = {
+    chains: "the shot list sets the hop count",
+    hop_script: "a shot plan forces it to `next`",
+};
+
+/* -- one field per native widget ----------------------------------------- */
+
+/**
+ * Push a value back through the widget.
+ *
+ * `callback` is how a ComfyUI widget tells the rest of the app it changed --
+ * `control_after_generate` binds to the seed through it, and setting `.value`
+ * alone would leave that link dead.
+ */
+function commitWidget(node, w, value, onChange) {
+    w.value = value;
+    try {
+        w.callback?.(value, node.graph?.canvas, node, undefined, undefined);
+    } catch (err) {
+        console.error(`[HandTieClips] widget callback for ${w.name} failed:`, err);
+    }
+    node.graph?.setDirtyCanvas?.(true, true);
+    onChange?.();
+}
+
+function labelFor(w) {
+    return String(w.name || "").replace(/_/g, " ");
+}
+
+function comboField(node, w, onChange) {
+    const values = widgetOptions(w).values;
+    const opts = typeof values === "function" ? values(w, node) : values;
+    if (!Array.isArray(opts)) return null;
+    const s = el("select", "h3e-select");
+    for (const opt of opts) {
+        const o = el("option", null, String(opt));
+        o.value = String(opt);
+        s.appendChild(o);
+    }
+    s.value = String(w.value ?? "");
+    s.addEventListener("change", () => commitWidget(node, w, s.value, onChange));
+    return { input: s, read: () => { s.value = String(w.value ?? ""); } };
+}
+
+function toggleField(node, w, onChange) {
+    const wrap = el("span", "h3e-run-toggle");
+    const cb = el("input");
+    cb.type = "checkbox";
+    cb.checked = Boolean(w.value);
+    const text = el("span", "h3e-run-togglabel");
+    const paint = () => {
+        // A BOOLEAN with label_on/label_off says what each state MEANS
+        // ("vary per hop" / "same seed every hop"); a bare on/off throws that away.
+        const o = widgetOptions(w);
+        text.textContent = cb.checked
+            ? (o.label_on || "on")
+            : (o.label_off || "off");
+    };
+    paint();
+    cb.addEventListener("change", () => {
+        paint();
+        commitWidget(node, w, cb.checked, onChange);
+    });
+    wrap.appendChild(cb);
+    wrap.appendChild(text);
+    return { input: wrap, read: () => { cb.checked = Boolean(w.value); paint(); } };
+}
+
+function numberField(node, w, onChange) {
+    const i = el("input", "h3e-input");
+    i.type = "number";
+    const o = widgetOptions(w);
+    if (o.min != null) i.min = String(o.min);
+    if (o.max != null) i.max = String(o.max);
+    // LiteGraph's `options.step` is ten times the author's step -- a legacy of
+    // the canvas drag increment. `step2` carries the real one when the frontend
+    // is new enough; divide as the fallback rather than showing a 10x arrow.
+    const step = o.step2 ?? (o.step != null ? o.step / 10 : null);
+    if (step != null) i.step = String(step);
+    // Whether to round on commit. Testing the step alone is not enough: if a
+    // frontend ever reports the true step in `step`, the /10 fallback turns an
+    // INT's step into 0.1 and `steps` would happily accept 7.5. Requiring the
+    // bounds and the current value to be integral too keeps pin_noise (max
+    // 0.10) and the shifts (min 0.01) out of it. `cache_budget_gb` is integral
+    // on every count and so gets rounded -- a whole-GB budget, which is what
+    // its 1.0 step already asks for.
+    const isInt = [o.min, o.max, w.value, step]
+        .every((v) => v == null || Number.isInteger(Number(v)));
+    i.value = String(w.value ?? "");
+    const push = () => {
+        if (i.value === "") return;               // mid-edit; wait for change
+        let v = Number(i.value);
+        if (!Number.isFinite(v)) return;
+        if (o.min != null) v = Math.max(o.min, v);
+        if (o.max != null) v = Math.min(o.max, v);
+        if (isInt) v = Math.round(v);
+        commitWidget(node, w, v, onChange);
+    };
+    // Commit on input as well as change: the shot editor learned the hard way
+    // that a field committing only on blur loses whatever was typed when the
+    // workflow is saved with the caret still in the box.
+    i.addEventListener("input", push);
+    i.addEventListener("change", () => {
+        push();
+        i.value = String(w.value ?? "");          // show the clamped value back
+    });
+    return { input: i, read: () => { i.value = String(w.value ?? ""); } };
+}
+
+function textField(node, w, onChange) {
+    const i = el("input", "h3e-input");
+    i.type = "text";
+    i.value = String(w.value ?? "");
+    i.addEventListener("input", () => commitWidget(node, w, i.value, onChange));
+    return { input: i, read: () => { i.value = String(w.value ?? ""); } };
+}
+
+/** null when this widget's type is not one the panel can draw. */
+function fieldFor(node, w, onChange) {
+    const t = widgetType(w);
+    if (t === "combo") return comboField(node, w, onChange);
+    if (t === "toggle" || t === "boolean") return toggleField(node, w, onChange);
+    if (t === "number" || t === "int" || t === "float") return numberField(node, w, onChange);
+    if (t === "string" || t === "text") {
+        // Multiline STRINGs are documents, not dials -- they belong to the shot
+        // editor or to their own widget, never squeezed into a 104px grid cell.
+        if (widgetOptions(w).multiline) return null;
+        return textField(node, w, onChange);
+    }
+    return null;
+}
+
+/* -- panel ---------------------------------------------------------------- */
+
+export function createRunPanel(node, { onChange, suppressed, hopCount } = {}) {
+    const root = el("details", "h3e-section h3e-run");
+    const sum = el("summary", "h3e-run-sum");
+    sum.appendChild(el("span", "h3e-title", "RUN"));
+    const digest = el("span", "h3e-count h3e-run-digest");
+    sum.appendChild(digest);
+    root.appendChild(sum);
+
+    const body = el("div", "h3e-run-body");
+    root.appendChild(body);
+
+    /** Widgets this panel actually drew, so the caller hides exactly those. */
+    const owned = [];
+    const readers = [];
+    let builtFor = null;   // the suppression set the current DOM was built for
+
+    function suppressedSet() {
+        try {
+            return new Set(suppressed?.() || []);
+        } catch (err) {
+            console.error("[HandTieClips] run panel suppression check failed:", err);
+            return new Set();
+        }
+    }
+
+    function build() {
+        body.textContent = "";
+        owned.length = 0;
+        readers.length = 0;
+        // Widgets found by name but whose type fieldFor could not draw. A
+        // frontend that renames widget types would empty this panel silently,
+        // and "silent" is exactly what made the last mount bug hard to find.
+        const rejected = [];
+
+        const skip = suppressedSet();
+        builtFor = [...skip].sort().join(",");
+
+        for (const [title, names] of GROUPS) {
+            const grid = el("div", "h3e-grid");
+            let n = 0;
+            for (const name of names) {
+                if (skip.has(name)) continue;
+                const w = widgetByName(node, name);
+                if (!w) continue;
+                const f = fieldFor(node, w, () => { paintDigest(); onChange?.(); });
+                if (!f) {                          // stays a native dial below
+                    rejected.push(`${name}:${widgetType(w) || "?"}`);
+                    continue;
+                }
+                const l = el("label",
+                    WIDE.has(name) ? "h3e-field h3e-run-wide" : "h3e-field");
+                l.appendChild(el("span", null, labelFor(w)));
+                l.appendChild(f.input);
+                // The tooltip is the widget's own, straight from INPUT_TYPES.
+                const tip = widgetOptions(w).tooltip;
+                if (tip) l.title = String(tip);
+                grid.appendChild(l);
+                owned.push(name);
+                readers.push(f.read);
+                n += 1;
+            }
+            if (!n) continue;                      // nothing found: draw nothing
+            const group = el("div", "h3e-run-group");
+            group.appendChild(el("div", "h3e-run-label", title));
+            group.appendChild(grid);
+            body.appendChild(group);
+        }
+
+        const why = [...skip]
+            .filter((name) => SUPPRESSED_WHY[name])
+            .map((name) => `${name} — ${SUPPRESSED_WHY[name]}`);
+        if (why.length) {
+            body.appendChild(el("div", "h3e-note h3e-note-hint",
+                `Not shown here: ${why.join("; ")}.`));
+        }
+
+        if (!owned.length) {
+            // Two very different failures, and the message has to say which:
+            // nothing found by name means a stale Python side; found but not
+            // drawable means this frontend reports widget types fieldFor does
+            // not know, which is a bug here rather than a version mismatch.
+            if (rejected.length) {
+                console.warn("[HandTieClips] run panel cannot draw these widget "
+                    + "types:", rejected.join(", "));
+            }
+            body.appendChild(el("div", "h3e-note h3e-note-error",
+                rejected.length
+                    ? `No drawable run widgets: this frontend reports types the `
+                      + `panel does not handle (${rejected.slice(0, 4).join(", ")}`
+                      + `${rejected.length > 4 ? ", …" : ""}). Native dials left `
+                      + `visible below; see the console.`
+                    : "No run widgets found — the Python side is probably a "
+                      + "different version. The native dials are left visible below."));
+        } else if (rejected.length) {
+            console.warn("[HandTieClips] run panel left these as native dials:",
+                rejected.join(", "));
+        }
+        // An empty build must not stick: builtFor is what stops sync() from
+        // rebuilding, so caching a failure would make it permanent for the
+        // life of the node.
+        if (!owned.length) builtFor = null;
+    }
+
+    /* The one-line summary, readable with the panel shut. Deliberately no seed:
+     * `control_after_generate` rewrites it after every queue without telling
+     * us, so a seed shown here would be wrong more often than right. */
+    function paintDigest() {
+        const v = (n) => widgetByName(node, n)?.value;
+        const bits = [];
+        const res = v("resolution");
+        const asp = String(v("aspect") || "").split(" ")[0];
+        if (res) bits.push(asp ? `${res} ${asp}` : String(res));
+        const dur = v("duration");
+        // The hop count, not `chains`: with a shot plan loaded the two disagree
+        // and the plan is the one run() obeys.
+        const ch = hopCount?.() || v("chains");
+        if (dur && ch) bits.push(`${String(dur).replace(/\s+/g, "")} ×${ch}`);
+        const steps = v("steps");
+        if (steps) bits.push(`${steps} steps ${v("sampler_name") || ""}`.trim());
+        const cache = v("cache_hops");
+        if (cache) bits.push(`cache ${cache}`);
+        digest.textContent = bits.join(" · ");
+    }
+
+    /** Re-read every field from its widget. */
+    function render() {
+        for (const read of readers) {
+            try {
+                read();
+            } catch (err) {
+                console.error("[HandTieClips] run field refresh failed:", err);
+            }
+        }
+        paintDigest();
+    }
+
+    /**
+     * Rebuild only when the suppression set actually changed.
+     *
+     * Called from the same place that recomputes widget visibility, and it has
+     * to run BEFORE that: `ownedNames()` is what decides which native dials get
+     * hidden, so a stale build would hide a dial the panel no longer draws.
+     */
+    function sync() {
+        const key = [...suppressedSet()].sort().join(",");
+        if (key !== builtFor) build();
+        render();
+    }
+
+    build();
+    render();
+
+    // Always open. Collapsing made sense while RUN was the last child of the
+    // scroller and cost a screenful; pinned to the bottom it is the one
+    // section you touch on every queue, so a toggle only ever hid it.
+    // `<details>` is kept for the summary bar's markup, forced open and with
+    // its disclosure suppressed -- see the CSS.
+    root.open = true;
+    root.addEventListener("toggle", () => { root.open = true; });
+    // A click on the summary would otherwise close it before that fires.
+    sum.addEventListener("click", (e) => e.preventDefault());
+    // Values change behind the panel's back -- `control_after_generate` bumps
+    // the seed on every queue, and undo rewrites widgets wholesale -- so what
+    // used to be re-read on open is now re-read whenever the node is drawn
+    // through sync(). node.properties[OPEN_PROP] is left alone: old workflows
+    // carry it and it costs nothing.
+
+    return {
+        root,
+        render,
+        sync,
+        /** Names the panel drew; the caller hides exactly these. */
+        ownedNames: () => owned.slice(),
+    };
+}

js/editor/templates.js

@@ -0,0 +1,147 @@
+/* Skeleton shot patterns, appended into the card list.
+ *
+ * These are not "example scenes" -- each one exists to demonstrate a rule from
+ * PROMPTING.md that a first-time author reliably gets wrong, in a form they can
+ * edit rather than read:
+ *
+ *   - an ending written as a pose plus a sound, never as "stops talking";
+ *   - a state change landing at the END of the shot before the one that needs
+ *     it, because every hop opens holding the frames it was handed;
+ *   - `tail` set to settle/hold wherever a clip actually finishes;
+ *   - a framing change earned on a camera move, so `join: continuous` and the
+ *     framing are not asking for opposite things;
+ *   - a spoken line landing MID-hop with a non-verbal action running into the
+ *     seam, and a named sound on every hop without dialogue, because the audio
+ *     pin otherwise carries speech down the whole chain (chain_00057);
+ *   - `match_cut` on a hop that changes location, because a continuous join
+ *     across two rooms morphs one into the other (chain_00057).
+ *
+ * No beat carries an `@tag`. A template that referred to a reference the user
+ * has not created would turn a helpful click into a hard error at run time.
+ * The `note` on each pattern is where reference scheduling is explained
+ * instead.
+ */
+
+import { el, button } from "./widget_utils.js";
+
+function shot(beat, directives) {
+    return {
+        id: "", beat, directives,
+        prose: "", seed: null, steps: null, duration: null, locked: false,
+    };
+}
+
+export const TEMPLATES = [
+    {
+        name: "Dialogue, held",
+        hint: "Someone speaks, then finishes. Two hops.",
+        note: "The line lands mid-hop and a non-verbal action runs into the "
+            + "seam, so the audio pin does not carry speech into the next hop.",
+        shots: [
+            shot("A person stands in the room, looks up at someone off-frame "
+                 + "and says, 'You are earlier than I expected.' They set both "
+                 + "hands on the counter, the refrigerator humming behind them.",
+                 { camera: "hold", framing: "medium", pace: "steady", tail: "ongoing" }),
+            shot("Their weight shifts onto one hip and their eyes move slowly "
+                 + "across the room. The refrigerator hums and a car passes "
+                 + "outside.",
+                 { join: "continuous", camera: "hold", framing: "keep", pace: "slow", tail: "settle" }),
+        ],
+    },
+    {
+        name: "Cross the room",
+        hint: "Movement across the space, camera following. Two hops.",
+        note: "The framing change is earned on the move -- a framing change "
+            + "with a held camera and a continuous join implies a cut.",
+        shots: [
+            shot("They set down what they are holding and walk the length of "
+                 + "the room to the window, looking out at the street. Their "
+                 + "steps are soft on the floor.",
+                 { join: "continuous", camera: "pan_follow", framing: "medium", pace: "steady", tail: "ongoing" }),
+            shot("They arrive at the window and rest one hand on the frame, "
+                 + "their weight settling onto one hip. Traffic passes faintly "
+                 + "on the other side of the glass.",
+                 { join: "continuous", camera: "push_in", framing: "close", pace: "slow", tail: "settle" }),
+        ],
+    },
+    {
+        name: "Leave for an unseen space",
+        hint: "Exit the referenced room into somewhere with no picture. Two hops.",
+        note: "Take the room reference OFF these hops in the register. A plate "
+            + "of the room riding them drags the character back into it.",
+        shots: [
+            shot("They turn from the window, cross the room and push through "
+                 + "the doorway into the corridor beyond, the room falling "
+                 + "away behind them, their footsteps carrying on the floor.",
+                 { join: "continuous", camera: "pan_follow", framing: "wide", pace: "brisk", tail: "ongoing" }),
+            shot("They walk down a narrow corridor hung with coats, one hand "
+                 + "trailing along the wall, their footsteps muffled on the "
+                 + "runner.",
+                 { join: "continuous", camera: "handheld", framing: "medium", pace: "steady", tail: "ongoing" }),
+        ],
+    },
+    {
+        name: "Return to the room",
+        hint: "Come back to an established space. One hop.",
+        note: "Put the room reference back on this hop, and join on "
+            + "match_cut -- a continuous join across a real location "
+            + "change morphs one room into the other.",
+        shots: [
+            shot("They walk back through the doorway to where they started, "
+                 + "picking up what they set down. The room is quiet apart "
+                 + "from the hum of the refrigerator.",
+                 { join: "match_cut", camera: "pull_back", framing: "wide", pace: "steady", tail: "hold" }),
+        ],
+    },
+    {
+        name: "Quiet close",
+        hint: "End a chain without a stray gesture. One hop.",
+        note: "A discrete sound rather than a continuous bed, and `tail: hold` "
+            + "so the model is not told action is still underway at the last "
+            + "frame.",
+        shots: [
+            shot("They lean back with their lips closed and let their eyes "
+                 + "move slowly across the room. A single click from the "
+                 + "refrigerator, then stillness.",
+                 { join: "continuous", camera: "hold", framing: "keep", pace: "slow", tail: "hold" }),
+        ],
+    },
+];
+
+/* A panel of one row per pattern. Hidden until the SCRIPT header's button asks
+ * for it, so it costs nothing on a node the author already knows their way
+ * around. `onPick` receives a fresh deep copy -- the caller renumbers ids, and
+ * handing out the module-level object would let one insertion mutate the
+ * template for the rest of the session. */
+export function createTemplatePanel({ onPick }) {
+    const root = el("div", "h3e-tpl");
+    root.style.display = "none";
+
+    root.appendChild(el("div", "h3e-note",
+        "Appended to the end of your script. Every beat is a starting point to "
+        + "rewrite, not a finished shot."));
+
+    for (const t of TEMPLATES) {
+        const row = el("div", "h3e-tpl-row");
+        const text = el("div", "h3e-tpl-text");
+        text.appendChild(el("div", "h3e-tpl-name", t.name));
+        text.appendChild(el("div", "h3e-tpl-hint", t.hint));
+        text.appendChild(el("div", "h3e-tpl-note", t.note));
+        row.appendChild(text);
+        row.appendChild(button(
+            `+ ${t.shots.length}`,
+            `Append ${t.shots.length} shot${t.shots.length > 1 ? "s" : ""}: ${t.note}`,
+            () => onPick(JSON.parse(JSON.stringify(t.shots))),
+        ));
+        root.appendChild(row);
+    }
+
+    return {
+        root,
+        toggle() {
+            root.style.display = root.style.display === "none" ? "" : "none";
+            return root.style.display !== "none";
+        },
+        hide() { root.style.display = "none"; },
+    };
+}

js/editor/widget_utils.js

@@ -0,0 +1,413 @@
+/**
+ * Foundations for the H3 Ref Chain node editor.
+ *
+ * Two things here are load-bearing and neither is obvious, so both are
+ * documented at the point of use rather than in a README nobody opens:
+ *
+ *   hideWidget()  - the four-flag recipe. Classic LiteGraph only needed
+ *                   computeSize = [0, -4]; Vue Nodes 2.0 filters on
+ *                   options.hidden | hideInPanel | canvasOnly, and without
+ *                   those flags every hidden dial reappears as a raw form.
+ *                   Invisible in packs with three widgets, unmissable at 21.
+ *
+ *   installHeightGuard() - the _h fixpoint. LiteGraph's _arrangeWidgets runs
+ *                   every frame; report a height derived from node.size[1] and
+ *                   the node grows forever.
+ *
+ * Both are ported from PromptMasterLD/js/claude_prompt.js, which paid for them.
+ */
+
+import { app } from "../../../scripts/app.js";
+
+const VOCAB_URL = "/h3_ref_chain/vocab";
+
+/* -- vocabulary ---------------------------------------------------------- */
+
+let _vocabPromise = null;
+const _vocabListeners = new Set();
+
+/**
+ * The directive vocabulary, fetched once per browser session.
+ *
+ * Deliberately NOT bundled into this file: `directives.py` is the single source
+ * of truth so that improving one sentence improves every plan already written.
+ * A copy here would go stale on the first edit.
+ */
+/** Drop the cached vocabulary so the next vocab() call refetches. */
+export function refreshVocab() {
+    _vocabPromise = null;
+    for (const fn of _vocabListeners) {
+        try { fn(); } catch (err) { console.error("[HandTieClips] vocab listener failed:", err); }
+    }
+}
+
+/** Register a mounted editor to be re-rendered when the vocabulary reloads. */
+export function onVocabRefresh(fn) {
+    _vocabListeners.add(fn);
+    return () => _vocabListeners.delete(fn);
+}
+
+export function vocab() {
+    if (!_vocabPromise) {
+        _vocabPromise = fetch(VOCAB_URL)
+            .then((r) => (r.ok ? r.json() : Promise.reject(new Error(`HTTP ${r.status}`))))
+            .catch((err) => {
+                console.error("[HandTieClips] vocabulary unavailable:", err);
+                // Degrade to free-text directives rather than an empty editor.
+                // `_failed` is read by the editors, which show a retry strip --
+                // it used to be set here and never looked at again, so a failed
+                // fetch just produced a mysteriously featureless panel.
+                return { axes: [], vocab: {}, defaults: {}, retention: {},
+                         durations: {}, overlaps: {}, max_ref_images: 9, fps: 24,
+                         _failed: true, _error: String(err && err.message || err) };
+            });
+    }
+    return _vocabPromise;
+}
+
+/* -- widget visibility --------------------------------------------------- */
+
+/**
+ * Hide a native widget without losing its value.
+ *
+ * The widget still serializes -- that is the entire point. The DOM editor is a
+ * rendering layer over `shot_plan` / `ref_plan`, and those widgets remain the
+ * only source of truth, so the workflow JSON is byte-identical in shape to one
+ * authored by hand.
+ */
+/* `widget.inputEl` is a deprecated alias on frontend 1.49.6: merely reading it
+ * logs a deprecation warning to the console. Prefer `element`, and only reach
+ * for the alias when it is absent, i.e. on an older frontend. */
+function widgetElements(w) {
+    if (w.element) return [w.element];
+    return w.inputEl ? [w.inputEl] : [];
+}
+
+/**
+ * The widget's type as the FRONTEND defined it, seeing past our own hiding.
+ *
+ * `hideWidget` overwrites `w.type` with "hidden" and stashes the real one in
+ * `_h3Saved`. Anything that renders a widget therefore has to ask for the type
+ * this way, or it reads back the hiding rather than the widget -- which is
+ * exactly how the run panel emptied itself: it hid the dials it owned on the
+ * first build, then found nothing but "hidden" on the rebuild.
+ */
+export function widgetType(w) {
+    const t = (w && w._h3Hidden) ? w._h3Saved?.type : w?.type;
+    return String(t ?? "").toLowerCase();
+}
+
+/** Ditto for options: `hideWidget` replaces the object with a flagged copy. */
+export function widgetOptions(w) {
+    const o = (w && w._h3Hidden) ? w._h3Saved?.options : w?.options;
+    return o || w?.options || {};
+}
+
+export function hideWidget(w) {
+    if (!w || w._h3Hidden) return;
+    w._h3Hidden = true;
+    w._h3Saved = {
+        type: w.type,
+        computeSize: w.computeSize,
+        computeLayoutSize: w.computeLayoutSize,
+        draw: w.draw,
+        options: w.options,
+    };
+
+    w.type = "hidden";
+    w.hidden = true;
+    w.options = Object.assign({}, w.options || {}, {
+        hidden: true,
+        hideInPanel: true,
+        // canvasOnly also drops it from the Vue widget list (shouldRenderAsVue).
+        canvasOnly: true,
+        // Never flip serialization off: the value IS the saved document.
+        serialize: w.options?.serialize !== false,
+    });
+    w.computeSize = () => [0, -4];
+    if (typeof w.computeLayoutSize === "function") {
+        w.computeLayoutSize = () => ({ minHeight: 0, maxHeight: 0, minWidth: 0 });
+    }
+    w.draw = () => {};
+
+    // A multiline STRING widget is a real DOM textarea. Collapsing only the
+    // LiteGraph geometry leaves it floating at its old coordinates, on top of
+    // the editor.
+    for (const el of widgetElements(w)) {
+        if (!el?.style) continue;
+        el.style.setProperty("display", "none", "important");
+        el.setAttribute?.("aria-hidden", "true");
+    }
+}
+
+/** Undo hideWidget. Used when the Simple/Shots toggle flips. */
+export function showWidget(w) {
+    if (!w?._h3Hidden) return;
+    const saved = w._h3Saved || {};
+    w.type = saved.type;
+    w.hidden = false;
+    w.options = saved.options || {};
+    if (saved.computeSize) w.computeSize = saved.computeSize;
+    else delete w.computeSize;
+    if (saved.computeLayoutSize) w.computeLayoutSize = saved.computeLayoutSize;
+    if (saved.draw) w.draw = saved.draw;
+    else delete w.draw;
+    for (const el of widgetElements(w)) {
+        if (!el?.style) continue;
+        el.style.removeProperty("display");
+        el.removeAttribute?.("aria-hidden");
+    }
+    w._h3Hidden = false;
+    delete w._h3Saved;
+}
+
+export function widgetByName(node, name) {
+    return node.widgets?.find((w) => w.name === name) || null;
+}
+
+/** Hide every widget in `names`, show the rest of `names`' complement set. */
+export function setWidgetVisibility(node, hiddenNames) {
+    const hide = new Set(hiddenNames);
+    for (const w of node.widgets || []) {
+        if (hide.has(w.name)) hideWidget(w);
+        else showWidget(w);
+    }
+}
+
+/* -- height guard -------------------------------------------------------- */
+
+/**
+ * Stop the node growing a little every frame.
+ *
+ * LiteGraph's _arrangeWidgets does, once per frame:
+ *
+ *     l = widgetsTop; for (w of widgets) l += w.computeSize()[1] + 4;
+ *     if (l > node.size[1]) node.setSize([node.size[0], l]);
+ *
+ * so a panel that reports `node.size[1]` makes l = top + size[1] + 4 > size[1]
+ * on EVERY frame. Observed at ~130px of growth per frame -- the workflow
+ * scrolls away from you while you watch it.
+ *
+ * Reporting `size[1] - chrome() - SLACK` makes l <= size[1] on every frame, so
+ * the arrange pass never asks to grow and the loop settles at the node's own
+ * height. SLACK is what buys the inequality: panelTop is chrome minus the
+ * node's bottom padding, so a panel of exactly `size - chrome` still asks for
+ * up to 4px more than the node has -- every frame, forever.
+ *
+ * This replaced an independent stored `_h`, updated through an onResize hook.
+ * The hook fired (57 times in one measured drag) but its `Array.isArray(size)`
+ * gate rejected every call -- this frontend's `node.size` is not a plain Array
+ * -- so `_h` kept the height the node had at install time and the panel stayed
+ * 742px inside a 1911px node. Reading the node directly has no such gate to get
+ * wrong.
+ *
+ * The second floor is the resize drag, which clamps up to
+ * LGraphNode.computeSize()[1]. Rather than re-derive that formula (and have it
+ * rot the next time the frontend changes), measure it: with `_measuring` set,
+ * panelHeight() reports 0, so computeSize() returns pure chrome. The flag also
+ * breaks the recursion, since computeSize() calls back into us.
+ */
+export function installHeightGuard(node, domWidget, { minHeight = 420, minWidth = 520 } = {}) {
+    if (node._h3HeightGuard) return node._h3HeightGuard;
+
+    let measuring = false;
+    let chromeVal = null;
+    let chromeKey = "";
+
+    const chrome = () => {
+        // The hidden count is part of the key because hiding a widget changes
+        // what computeSize() measures while leaving widgets.length alone --
+        // so without it the cached chrome height goes stale the moment
+        // applyVisibility runs, and every panel height after that is wrong.
+        const hidden = (node.widgets || []).reduce((n, w) => n + (w._h3Hidden ? 1 : 0), 0);
+        const key = `${node.inputs?.length}|${node.outputs?.length}|${node.widgets?.length}|${hidden}`;
+        if (key === chromeKey && chromeVal != null) return chromeVal;
+        measuring = true;
+        try {
+            chromeVal = +node.computeSize()[1] || 0;
+            chromeKey = key;
+        } catch (_) {
+            chromeVal = 0;
+        } finally {
+            measuring = false;
+        }
+        return chromeVal;
+    };
+
+    // The margin that keeps the arrange pass from asking for one more pixel
+    // than the node has. See the note above. Costs an invisible strip at the
+    // bottom of the panel; 4 would do, 8 leaves room for the frontend to
+    // change its mind about padding.
+    const SLACK = 8;
+    const nodeHeight = () => Math.max(minHeight, +(node.size?.[1]) || minHeight);
+    const nodeWidth = () => Math.max(minWidth, +(node.size?.[0]) || minWidth);
+
+    const guard = {
+        get minHeight() { return minHeight; },
+        /** The node's own height is the authority; nothing mirrors it. */
+        get _h() { return nodeHeight(); },
+        panelHeight() {
+            if (measuring) return 0;
+            return Math.max(minHeight, nodeHeight() - chrome() - SLACK);
+        },
+        /** Grow the node if it is too short to hold a minimum panel. Never
+         *  shrinks it -- the node's height is the user's to choose. */
+        sync() {
+            const need = chrome() + minHeight + SLACK;
+            if (nodeHeight() < need - 1) node.setSize([nodeWidth(), need]);
+            node.graph?.setDirtyCanvas?.(true, true);
+        },
+        /** Ask for a taller panel, e.g. after adding a card. */
+        grow(px) {
+            node.setSize([nodeWidth(), Math.max(minHeight, nodeHeight() + px)]);
+            node.graph?.setDirtyCanvas?.(true, true);
+        },
+    };
+    node._h3HeightGuard = guard;
+
+    if (domWidget) {
+        // The two callers want different answers and, helpfully, pass
+        // different arguments -- which is the only way to tell them apart:
+        //
+        //   LGraphNode.computeSize()  calls computeSize(size[0]), WITH a width.
+        //     Its result is used purely as a FLOOR (the resize-drag clamp,
+        //     expandToFitContent). Reporting the live height there pins the
+        //     floor to the current height, so the node can only ever grow --
+        //     drag it smaller and nothing happens. Report the MINIMUM.
+        //
+        //   _arrangeWidgets()         calls computeSize(), no argument.
+        //     The real layout pass. Report the live height.
+        domWidget.computeSize = (width) => [
+            Math.max(minWidth, +(node.size?.[0]) || minWidth),
+            measuring ? 0 : (width === undefined ? guard.panelHeight() : minHeight),
+        ];
+        if (typeof domWidget.computeLayoutSize === "function") {
+            // TRACK, DO NOT FREEZE. Reporting a constant `minWidth` here is
+            // what collapses the node: the layout pass re-reads it on every
+            // recompute -- selecting the node is enough -- and faithfully
+            // re-declares the node at its stated minimum, so a wide node
+            // becomes a 560px node on the first click and stays there.
+            // Safe against feedback: max() against a constant is a fixpoint,
+            // not an accumulator like the height chain, and width never feeds
+            // height.
+            domWidget.computeLayoutSize = () => ({
+                minHeight: measuring ? 0 : guard.panelHeight(),
+                maxHeight: measuring ? 0 : guard.panelHeight(),
+                minWidth: Math.max(minWidth, +(node.size?.[0]) || minWidth),
+            });
+        }
+        // The other half of the collapse. ComfyUI's DOM-widget position
+        // updater computes `size = [(widget.width ?? node.width) - margin*2, ...]`.
+        // Once anything writes a stale number onto widget.width, node.width is
+        // never consulted again -- which is why fixing only the layout size is
+        // not enough. A live getter makes the stale value unrepresentable:
+        // width always IS the node's width, and writes are dropped.
+        try {
+            Object.defineProperty(domWidget, "width", {
+                get: () => Math.max(minWidth, +(node.size?.[0]) || minWidth),
+                set: () => {},
+                configurable: true,
+            });
+        } catch (err) {
+            console.warn("[HandTieClips] width getter failed:", err);
+        }
+    }
+
+    // With no widget declaring a width, LiteGraph falls back to
+    // NODE_WIDTH * 1.5 = 210, and every resize command is then free to crush
+    // the panel. Floor it.
+    const prevComputeSize = node.computeSize;
+    if (typeof prevComputeSize === "function") {
+        node.computeSize = function (...args) {
+            const r = prevComputeSize.apply(this, args) || [0, 0];
+            if (r[0] < minWidth) r[0] = minWidth;
+            return r;
+        };
+    }
+
+    // No onResize hook any more. There is nothing to mirror: panelHeight()
+    // reads node.size[1] at the moment it is asked, so a resize is reflected
+    // by the very next arrange pass with nothing to keep in step.
+
+    return guard;
+}
+
+/* -- tiny DOM helpers ---------------------------------------------------- */
+
+export function el(tag, className, text) {
+    const node = document.createElement(tag);
+    if (className) node.className = className;
+    if (text != null) node.textContent = text;
+    return node;
+}
+
+export function button(label, title, onClick, className = "h3e-btn") {
+    const b = el("button", className, label);
+    b.type = "button";
+    if (title) b.title = title;
+    b.addEventListener("click", (e) => {
+        e.preventDefault();
+        e.stopPropagation();
+        onClick(e);
+    });
+    return b;
+}
+
+export function select(options, value, onChange, { blankLabel = "—", titles = {} } = {}) {
+    const s = el("select", "h3e-select");
+    const blank = el("option", null, blankLabel);
+    blank.value = "";
+    s.appendChild(blank);
+    for (const opt of options) {
+        const o = el("option", null, opt.replace(/_/g, " "));
+        o.value = opt;
+        if (titles[opt]) o.title = titles[opt];
+        s.appendChild(o);
+    }
+    s.value = value || "";
+    s.addEventListener("change", () => onChange(s.value));
+    return s;
+}
+
+/**
+ * Keep canvas gestures out of the panel.
+ *
+ * Without this a click inside a textarea also starts a node drag, and a scroll
+ * inside the shot list zooms the graph instead.
+ */
+export function isolateEvents(root) {
+    for (const name of ["pointerdown", "pointerup", "mousedown", "mouseup",
+                        "click", "dblclick", "contextmenu"]) {
+        root.addEventListener(name, (e) => e.stopPropagation());
+    }
+    root.addEventListener("keydown", (e) => e.stopPropagation());
+
+    // Wheel is NOT simply swallowed. Stopping it outright meant the graph could
+    // not be zoomed while the pointer was anywhere over the panel -- and the
+    // panel is most of the node. Scroll the nearest scrollable ancestor if
+    // there is somewhere left to scroll; otherwise hand the gesture to the
+    // canvas so zoom keeps working. Same approach as KJNodes' wheel passthrough.
+    root.addEventListener("wheel", (e) => {
+        let n = e.target;
+        while (n && n !== root.parentNode) {
+            if (n.scrollHeight > n.clientHeight + 1) {
+                const style = getComputedStyle(n).overflowY;
+                if (style === "auto" || style === "scroll") {
+                    const atTop = n.scrollTop <= 0;
+                    const atEnd = n.scrollTop + n.clientHeight >= n.scrollHeight - 1;
+                    if (!((e.deltaY < 0 && atTop) || (e.deltaY > 0 && atEnd))) {
+                        e.stopPropagation();
+                        return;
+                    }
+                }
+            }
+            n = n.parentNode;
+        }
+        const canvasEl = document.querySelector("#graph-canvas")
+            || app?.canvas?.canvas;
+        if (!canvasEl) return;
+        e.preventDefault();
+        e.stopPropagation();
+        canvasEl.dispatchEvent(new WheelEvent(e.type, e));
+    }, { passive: false });
+}

js/h3_chain_preview.js

@@ -0,0 +1,352 @@
+/**
+ * H3 Chain Preview -- the chain's progress panel, on its own node.
+ *
+ * Structure follows ComfyUI-KJNodes' preview_override panel (image area that
+ * absorbs slack, a fixed-height stats panel, a drag grip between them). The
+ * grip itself follows the sibling MiniMaxH3-Contex-Loop pack's review node
+ * instead: it uses pointer capture and reads the UNSCALED offsetHeight, because
+ * getBoundingClientRect() includes ComfyUI's canvas zoom and every release then
+ * compounds a smaller screen-space height into the saved value.
+ *
+ * Deliberately NOT overriding computeSize/computeLayoutSize the way the editor
+ * panel does. Frontend 1.49.6 distributes a node's spare vertical space across
+ * its widgets by growing each from minHeight toward maxHeight; pinning both to
+ * the same value opts the widget out of that entirely, which is why the editor
+ * panel does not respond to node resize. Here we let the frontend size it and
+ * do the internal layout in CSS.
+ *
+ * There is no JS runtime on the machine this was written on, so this file is
+ * static-checked only.
+ */
+
+import { app } from "../../scripts/app.js";
+import { api } from "../../scripts/api.js";
+
+/* Both ids. The pack registers the pre-rename id as a deprecated subclass so
+ * workflows saved before 2026-08-29 still load. If this check knew only the
+ * new id those nodes would come up with NO editor at all, which looks exactly
+ * like the rename having broken the pack. */
+const NODE_TYPES = new Set(["HTCChainPreview", "H3ChainPreview"]);
+const CHAIN_TYPES = new Set(["HandTieClips", "H3RefChain"]);
+const STYLE_ID = "h3rc-style";
+const PANEL_PROP = "h3rcPanelH";
+const _cssUrl = new URL("./h3_ref_chain.css", import.meta.url).href;
+
+function ensureStyles() {
+    if (document.getElementById(STYLE_ID)) return;
+    const link = document.createElement("link");
+    link.id = STYLE_ID;
+    link.rel = "stylesheet";
+    link.href = _cssUrl;
+    document.head.appendChild(link);
+}
+
+function el(tag, className, text) {
+    const n = document.createElement(tag);
+    if (className) n.className = className;
+    if (text != null) n.textContent = text;
+    return n;
+}
+
+/** Mirrors getNodeByExecutionId (not exported); subgraph-aware. */
+function findNodeByQualifiedId(rootGraph, qid) {
+    if (!rootGraph || qid == null) return null;
+    const parts = String(qid).split(":");
+    let graph = rootGraph;
+    for (let i = 0; i < parts.length - 1; i++) {
+        const parentId = parseInt(parts[i], 10);
+        if (!Number.isFinite(parentId)) return null;
+        const parentNode = graph?.getNodeById?.(parentId);
+        if (!parentNode?.subgraph) return null;
+        graph = parentNode.subgraph;
+    }
+    const leafId = parseInt(parts[parts.length - 1], 10);
+    if (!Number.isFinite(leafId)) return null;
+    return graph?.getNodeById?.(leafId) || null;
+}
+
+/**
+ * Walk back from this node's `images` input to the chain node feeding it.
+ *
+ * Live progress events carry the *chain's* node id, so a graph with two chains
+ * needs to know which one belongs to this panel. Returns null when the input is
+ * unwired or the upstream is something else, in which case the panel falls back
+ * to accepting any chain's events -- correct for the common single-chain graph,
+ * and labelled as such so it cannot silently mislead.
+ */
+function upstreamChainId(node) {
+    let hops = 0;
+    let current = node;
+    let slotName = "images";
+    while (current && hops < 12) {
+        const input = (current.inputs || []).find((s) => s.name === slotName);
+        if (!input || input.link == null) return null;
+        const link = current.graph?.links?.[input.link];
+        if (!link) return null;
+        const src = current.graph.getNodeById?.(link.origin_id);
+        if (!src) return null;
+        if (CHAIN_TYPES.has(src.type)) return String(src.id);
+        // Pass through anything that forwards images (reroutes, other previews).
+        const forwarded = (src.inputs || []).find((s) => s.type === "IMAGE");
+        if (!forwarded) return null;
+        current = src;
+        slotName = forwarded.name;
+        hops += 1;
+    }
+    return null;
+}
+
+function clock(seconds) {
+    if (!Number.isFinite(seconds)) return "–";
+    const m = Math.floor(seconds / 60);
+    const s = seconds - m * 60;
+    return m ? `${m}:${s.toFixed(1).padStart(4, "0")}` : `${s.toFixed(1)}s`;
+}
+
+function mountPanel(node) {
+    ensureStyles();
+
+    const root = el("div", "h3rc-preview");
+
+    const frame = el("div", "h3rc-frame");
+    const imgA = el("img", "h3rc-img");
+    const imgB = el("img", "h3rc-img h3rc-seam-b");
+    const placeholder = el("div", "h3rc-placeholder", "waiting for sample…");
+    const seamLine = el("div", "h3rc-seam-line");
+    const tagA = el("div", "h3rc-seam-tag h3rc-tag-a", "prev");
+    const tagB = el("div", "h3rc-seam-tag h3rc-tag-b", "this hop");
+    frame.append(imgA, imgB, seamLine, tagA, tagB, placeholder);
+    root.appendChild(frame);
+
+    const bar = el("div", "h3rc-bar");
+    const fill = el("div", "h3rc-bar-fill");
+    bar.appendChild(fill);
+    root.appendChild(bar);
+
+    const grip = el("div", "h3rc-grip");
+    grip.setAttribute("role", "separator");
+    grip.setAttribute("aria-orientation", "horizontal");
+    grip.title = "Drag to resize · double-click to reset";
+    root.appendChild(grip);
+
+    const panel = el("div", "h3rc-panel");
+    const line = el("div", "h3rc-line");
+    line.appendChild(el("span", "h3rc-status-label", "status"));
+    const statusValue = el("span", "h3rc-status-value", "idle");
+    line.appendChild(statusValue);
+    const mech = el("span", "h3rc-mech");
+    mech.style.display = "none";
+    line.appendChild(mech);
+    panel.appendChild(line);
+    const meta = el("div", "h3rc-meta");
+    panel.appendChild(meta);
+    root.appendChild(panel);
+
+    /* -- resize grip ----------------------------------------------------- */
+
+    const DEFAULT_PANEL_H = 62;
+    const applyPanelH = (px) => { panel.style.height = `${Math.max(40, px)}px`; };
+    if (typeof node.properties?.[PANEL_PROP] === "number") {
+        applyPanelH(node.properties[PANEL_PROP]);
+    }
+
+    let dragFrom = null;
+    grip.addEventListener("pointerdown", (e) => {
+        if (e.button !== 0) return;
+        e.preventDefault();
+        e.stopPropagation();
+        grip.setPointerCapture(e.pointerId);
+        dragFrom = { y: e.clientY, h: panel.offsetHeight };
+    });
+    grip.addEventListener("pointermove", (e) => {
+        if (!dragFrom) return;
+        // Divide by canvas zoom: clientY is screen space, offsetHeight is not.
+        const scale = app.canvas?.ds?.scale || 1;
+        const dy = (e.clientY - dragFrom.y) / scale;
+        const max = Math.max(40, root.clientHeight - 90);
+        applyPanelH(Math.min(max, dragFrom.h - dy));
+    });
+    const endDrag = (e) => {
+        if (!dragFrom) return;
+        dragFrom = null;
+        try { grip.releasePointerCapture(e.pointerId); } catch (_) { /* already released */ }
+        // offsetHeight, not getBoundingClientRect().height -- the latter is
+        // zoom-scaled and would shrink the saved height on every release.
+        if (!node.properties) node.properties = {};
+        node.properties[PANEL_PROP] = panel.offsetHeight;
+        node.graph?.change?.();
+    };
+    grip.addEventListener("pointerup", endDrag);
+    grip.addEventListener("pointercancel", endDrag);
+    grip.addEventListener("dblclick", (e) => {
+        e.preventDefault();
+        e.stopPropagation();
+        applyPanelH(DEFAULT_PANEL_H);
+        if (!node.properties) node.properties = {};
+        node.properties[PANEL_PROP] = DEFAULT_PANEL_H;
+    });
+
+    // Keep canvas gestures out of the panel, but let the wheel through so the
+    // graph still zooms with the pointer over the preview.
+    for (const name of ["pointerdown", "mousedown", "click", "dblclick", "contextmenu"]) {
+        root.addEventListener(name, (e) => e.stopPropagation());
+    }
+
+    /* -- state ------------------------------------------------------------ */
+
+    const setImage = (target, b64) => {
+        target.src = `data:image/jpeg;base64,${b64}`;
+        target.style.display = "block";
+        placeholder.style.display = "none";
+    };
+
+    const api_ = {
+        set(data) {
+            if (data?.status != null) {
+                const s = String(data.status).replace(/\s+/g, " ").trim();
+                // Hard clip: this strip is one line, and passing the prompt
+                // dump through it once already turned the panel into the prompt.
+                statusValue.textContent = s.length > 80 ? `${s.slice(0, 77)}…` : s;
+                statusValue.title = s;
+            }
+            if (typeof data?.image === "string") setImage(imgA, data.image);
+            if (typeof data?.seam_image === "string") {
+                setImage(imgB, data.seam_image);
+                frame.classList.add("h3rc-showing-seam");
+            } else if (data?.image) {
+                imgB.style.display = "none";
+                frame.classList.remove("h3rc-showing-seam");
+            }
+
+            if (typeof data?.frac === "number") {
+                fill.style.width = `${Math.round(data.frac * 100)}%`;
+                fill.classList.toggle("h3rc-done", data.frac >= 1);
+            } else if (data?.hop && data?.total) {
+                fill.style.width = `${Math.round((data.hop / data.total) * 100)}%`;
+            }
+
+            if (data?.pin_mech) {
+                mech.style.display = "";
+                mech.className = `h3rc-mech h3rc-mech-${data.pin_mech}`;
+                mech.textContent = data.pin_mech === "motion_context"
+                    ? "latent pin" : "pixel pin";
+                mech.title = data.pin_mech === "motion_context"
+                    ? "Motion-Context pinned the previous hop's sampler latent — the working join."
+                    : "AddGuide pinned decoded pixels. This is the fallback: Motion-Context was "
+                      + "unavailable, the overlap is not one of its context lengths, or the previous "
+                      + "hop was cached by a build older than the latent sidecar.";
+            }
+
+            const bits = [];
+            if (data?.hop && data?.total) bits.push(["hop", `${data.hop}/${data.total}`]);
+            if (data?.frames != null && data?.of_frames) bits.push(["frames", `${data.frames}/${data.of_frames}`]);
+            else if (data?.frames != null) bits.push(["frames", String(data.frames)]);
+            if (data?.cached) bits.push(["cache", `hit ${data.key || ""}`.trim()]);
+            if (data?.seed != null) bits.push(["seed", String(data.seed)]);
+            if (data?.steps != null) bits.push(["steps", String(data.steps)]);
+            if (data?.tone) bits.push(["tone", String(data.tone)]);
+            if (data?.video_s != null) bits.push(["video", clock(data.video_s)]);
+            if (data?.audio_s != null) bits.push(["audio", clock(data.audio_s)]);
+            if (data?.drift_ms != null) {
+                bits.push(["A/V drift", `${data.drift_ms > 0 ? "+" : ""}${data.drift_ms} ms`]);
+            }
+            if (data?.width && data?.height) bits.push(["size", `${data.width}x${data.height}`]);
+            if (bits.length) {
+                meta.textContent = "";
+                for (const [k, v] of bits) {
+                    const cell = el("span", null, `${k} `);
+                    cell.appendChild(el("b", null, v));
+                    meta.appendChild(cell);
+                }
+            }
+        },
+        reset() {
+            imgA.style.display = "none";
+            imgB.style.display = "none";
+            frame.classList.remove("h3rc-showing-seam");
+            placeholder.style.display = "";
+            placeholder.textContent = "waiting for sample…";
+            statusValue.textContent = "queued";
+            statusValue.title = "";
+            mech.style.display = "none";
+            meta.textContent = "";
+            fill.style.width = "0";
+            fill.classList.remove("h3rc-done");
+        },
+        error(msg) {
+            placeholder.style.display = "";
+            placeholder.textContent = msg;
+        },
+    };
+
+    node._h3ChainPreview = api_;
+    const widget = node.addDOMWidget("preview", "h3rc_chain_preview", root, {
+        serialize: false,
+        hideOnZoom: false,
+        getMinHeight: () => 180,
+        getMaxHeight: () => 4000,
+    });
+    return widget;
+}
+
+app.registerExtension({
+    name: "HandTieClips.ChainPreview",
+
+    async beforeRegisterNodeDef(nodeType, nodeData) {
+        if (!NODE_TYPES.has(nodeData?.name)) return;
+
+        const onCreated = nodeType.prototype.onNodeCreated;
+        nodeType.prototype.onNodeCreated = function () {
+            const r = onCreated?.apply(this, arguments);
+            mountPanel(this);
+            this.setSize([
+                Math.max(this.size?.[0] ?? 360, 360),
+                Math.max(this.size?.[1] ?? 420, 420),
+            ]);
+            return r;
+        };
+
+        const onRemoved = nodeType.prototype.onRemoved;
+        nodeType.prototype.onRemoved = function () {
+            delete this._h3ChainPreview;
+            return onRemoved?.apply(this, arguments);
+        };
+    },
+});
+
+/* Live events from the chain node carry the CHAIN's node id, so each panel takes
+ * the ones from the chain feeding it. With no resolvable upstream a lone panel
+ * still shows the only chain running rather than sitting blank. */
+function previewNodes(graph, out) {
+    for (const n of graph?._nodes || []) {
+        if (NODE_TYPES.has(n.type) && n._h3ChainPreview) out.push(n);
+        if (n.subgraph) previewNodes(n.subgraph, out);
+    }
+    return out;
+}
+
+api.addEventListener("h3_refchain_preview", (e) => {
+    const data = e.detail;
+    if (!data) return;
+    const panels = previewNodes(app.graph, []);
+    if (!panels.length) return;
+    const chainId = data.node_id == null ? null : String(data.node_id);
+    const matched = panels.filter((n) => upstreamChainId(n) === chainId);
+    const targets = matched.length ? matched
+        : (panels.length === 1 && upstreamChainId(panels[0]) === null ? panels : []);
+    for (const n of targets) n._h3ChainPreview.set(data);
+});
+
+/* The preview node's own execution: final frame count, size and A/V drift. */
+api.addEventListener("h3_chain_preview", (e) => {
+    const data = e.detail;
+    if (!data || data.node_id == null) return;
+    const node = findNodeByQualifiedId(app.graph, data.node_id);
+    node?._h3ChainPreview?.set(data);
+});
+
+/* A new run starts blank rather than showing the previous run's last frame --
+ * the old panel defined reset() and never called it. */
+api.addEventListener("execution_start", () => {
+    for (const n of previewNodes(app.graph, [])) n._h3ChainPreview.reset();
+});

js/h3_ref_chain.css

@@ -0,0 +1,872 @@
+/* H3 Ref Chain -- node panel styling.
+ *
+ * External stylesheet rather than a template literal in JS: the old inline
+ * sheet hardcoded every colour as a hex, so a light ComfyUI theme rendered the
+ * panel as dark-grey islands on a light node. Everything below derives from
+ * ComfyUI's own custom properties through color-mix(), which is the idiom the
+ * sibling MiniMaxH3-Contex-Loop pack already uses.
+ *
+ * Class prefixes: .h3e- editor, .h3rc- preview.
+ */
+
+.h3e-root,
+.h3rc-preview {
+    /* Black, one hairline, no radius -- the PromptMasterLD `.ldp-root` system.
+     *
+     * This used to derive every surface from the host theme with color-mix().
+     * The intent was light-theme safety; in practice --h3-bg mixed toward
+     * #111827 and --h3-sunken toward #000, so a light theme got dark blue-grey
+     * islands anyway while the accents stayed literal hex. Committing to one
+     * look is more honest than half-following two. */
+    --h3-bg:      #0a0a0a;
+    --h3-panel:   #111111;
+    --h3-sunken:  #0d0d0d;
+    --h3-border:  #2a2a2a;
+    --h3-border-soft: #1c1c1c;
+
+    --h3-text:    #e8e8e8;
+    --h3-muted:   #9a9a9a;
+    --h3-faint:   #6a6a6a;
+
+    /* One accent. Change this line and the whole panel follows. */
+    --h3-accent:  #e8ff47;
+    --h3-accent-soft: color-mix(in srgb, var(--h3-accent) 10%, transparent);
+    --h3-accent-wash: color-mix(in srgb, var(--h3-accent) 4%, transparent);
+    /* Text that sits ON the accent. Never white -- acid yellow needs ink. */
+    --h3-on-accent: #101010;
+    --h3-warn:    #ffb020;
+    --h3-error:   #ff3b30;
+    --h3-ok:      #5fbf7a;
+
+    /* One spacing scale. */
+    --h3-gap: 8px;
+    --h3-gap-sm: 5px;
+    /* Square. Kept as tokens rather than deleted so a rounded variant is one
+     * edit, and so no rule has to change to get there. */
+    --h3-radius: 0px;
+    --h3-radius-sm: 0px;
+    --h3-row-h: 28px;
+
+    /* A type scale, which this sheet did not have. Hierarchy was carried by
+     * four literal sizes plus alpha, with nothing bold anywhere, which is why
+     * it read flat. */
+    --h3-fs-xs: 9px;
+    --h3-fs-sm: 10px;
+    --h3-fs: 11px;
+    --h3-fs-lg: 12px;
+    --h3-weight-label: 700;
+    /* One label idiom. Seven different letter-spacings were doing this job. */
+    --h3-track: .14em;
+
+    box-sizing: border-box;
+    color: var(--h3-text);
+    font: var(--h3-fs-lg)/1.4 ui-sans-serif, system-ui, -apple-system, "Segoe UI", sans-serif;
+}
+
+.h3e-root *,
+.h3e-root *::before,
+.h3e-root *::after,
+.h3rc-preview *,
+.h3rc-preview *::before,
+.h3rc-preview *::after { box-sizing: border-box; }
+
+/* ---------------------------------------------------------------- editor -- */
+
+.h3e-root {
+    display: flex;
+    flex-direction: column;
+    gap: var(--h3-gap);
+    width: 100%;
+    height: 100%;
+    min-height: 0;
+    padding: 2px;
+    /* The root no longer scrolls -- .h3e-scroll does. See the note at the end
+     * of this sheet. */
+    overflow: hidden;
+}
+
+/* The containment context the rail's @container queries need. Without this the
+ * queries below never match -- see the note above them. */
+.h3e-section { container-type: inline-size; }
+
+.h3e-section {
+    background: var(--h3-bg);
+    border: 1px solid var(--h3-border);
+    border-radius: var(--h3-radius);
+    padding: var(--h3-gap);
+}
+
+/* Sticky header so "+ shot" stays reachable in a long plan. */
+.h3e-head {
+    position: sticky;
+    top: calc(var(--h3-gap) * -1);
+    z-index: 4;
+    display: flex;
+    align-items: center;
+    gap: var(--h3-gap-sm);
+    margin: 0 0 var(--h3-gap);
+    padding: 4px 0;
+    background: var(--h3-bg);
+}
+
+.h3e-title {
+    font-size: var(--h3-fs-sm);
+    font-weight: var(--h3-weight-label);
+    letter-spacing: var(--h3-track);
+    text-transform: uppercase;
+    color: var(--h3-text);
+}
+.h3e-count { font-size: var(--h3-fs-sm); color: var(--h3-faint); font-variant-numeric: tabular-nums; }
+.h3e-spacer { flex: 1; }
+
+/* -- controls ------------------------------------------------------------- */
+
+.h3e-root button,
+.h3e-root input,
+.h3e-root select,
+.h3e-root textarea {
+    font: inherit;
+    color: var(--h3-text);
+    background: var(--h3-sunken);
+    border: 1px solid var(--h3-border);
+    border-radius: var(--h3-radius-sm);
+    padding: 5px 7px;
+    min-width: 0;
+    transition: border-color .13s ease, background-color .13s ease, opacity .13s ease;
+}
+
+.h3e-root textarea { resize: vertical; line-height: 1.45; }
+
+.h3e-root button { cursor: pointer; white-space: nowrap; background: var(--h3-panel); }
+.h3e-root button:hover { border-color: var(--h3-accent); }
+.h3e-root button:active { background: color-mix(in srgb, var(--h3-accent) 22%, var(--h3-panel)); }
+.h3e-root button:disabled { cursor: not-allowed; opacity: .4; }
+
+.h3e-root input:hover,
+.h3e-root select:hover,
+.h3e-root textarea:hover { border-color: color-mix(in srgb, var(--h3-accent) 55%, var(--h3-border)); }
+
+/* Keyboard focus was completely invisible before -- ~8 controls per card. */
+.h3e-root :focus-visible {
+    outline: 2px solid var(--h3-accent);
+    outline-offset: 1px;
+    border-color: var(--h3-accent);
+}
+
+.h3e-btn { padding: 5px 9px; }
+.h3e-x {
+    padding: 4px 8px;
+    color: var(--h3-error);
+    background: transparent;
+    border-color: var(--h3-border-soft);
+}
+.h3e-x:hover { border-color: var(--h3-error); background: color-mix(in srgb, var(--h3-error) 14%, transparent); }
+
+/* -- Simple / Shots toggle ------------------------------------------------ */
+
+.h3e-modes { display: flex; border: 1px solid var(--h3-border); border-radius: var(--h3-radius-sm); overflow: hidden; }
+.h3e-root .h3e-mode {
+    border: 0;
+    border-radius: 0;
+    background: var(--h3-sunken);
+    color: var(--h3-muted);
+    padding: 5px 12px;
+    font-size: 11px;
+}
+.h3e-root .h3e-mode:hover { background: color-mix(in srgb, var(--h3-accent) 12%, var(--h3-sunken)); color: var(--h3-text); }
+.h3e-root .h3e-mode[aria-pressed="true"],
+.h3e-root .h3e-mode.h3e-on {
+    background: color-mix(in srgb, var(--h3-accent) 34%, var(--h3-sunken));
+    color: var(--h3-text);
+}
+
+.h3e-empty {
+    color: var(--h3-muted);
+    padding: 14px 10px;
+    line-height: 1.6;
+    text-align: center;
+    border: 1px dashed var(--h3-border-soft);
+    border-radius: var(--h3-radius-sm);
+}
+.h3e-empty-cta { display: block; margin: 8px auto 0; }
+
+/* -- shot cards ----------------------------------------------------------- */
+
+.h3e-card {
+    --h3-card-accent: var(--h3-accent);
+    background:
+        linear-gradient(90deg, color-mix(in srgb, var(--h3-card-accent) 7%, transparent), transparent 140px),
+        var(--h3-panel);
+    border: 1px solid color-mix(in srgb, var(--h3-card-accent) 46%, var(--h3-border));
+    border-left: 4px solid var(--h3-card-accent);
+    border-radius: var(--h3-radius);
+    padding: var(--h3-gap-sm) var(--h3-gap);
+    margin-bottom: var(--h3-gap-sm);
+    transition: border-color .13s ease, box-shadow .13s ease;
+}
+.h3e-card:hover { border-color: color-mix(in srgb, var(--h3-card-accent) 70%, var(--h3-border)); }
+.h3e-card.h3e-drop,
+.h3e-card.h3e-drag-over { outline: 2px solid var(--h3-accent); outline-offset: 1px; }
+.h3e-card.h3e-dragging { opacity: .45; }
+.h3e-card.h3e-invalid { border-left-color: var(--h3-error); }
+
+.h3e-card-head {
+    display: flex;
+    align-items: center;
+    gap: var(--h3-gap-sm);
+    min-height: var(--h3-row-h);
+}
+
+/* A one-character glyph is not a drag target. */
+.h3e-drag {
+    cursor: grab;
+    user-select: none;
+    padding: 4px 5px;
+    border-radius: 4px;
+    color: var(--h3-faint);
+    line-height: 1;
+}
+.h3e-drag:hover { color: var(--h3-text); background: var(--h3-accent-soft); }
+.h3e-drag:active { cursor: grabbing; }
+
+/* Collapse/expand affordance. */
+.h3e-root .h3e-fold {
+    padding: 3px 6px;
+    background: transparent;
+    border-color: transparent;
+    color: var(--h3-muted);
+    font-size: 10px;
+    line-height: 1;
+}
+.h3e-root .h3e-fold:hover { color: var(--h3-text); background: var(--h3-accent-soft); border-color: transparent; }
+.h3e-card.h3e-collapsed .h3e-card-body { display: none; }
+.h3e-card.h3e-collapsed { padding-bottom: var(--h3-gap-sm); }
+.h3e-fold-mark { display: inline-block; transition: transform .15s ease; }
+.h3e-card.h3e-collapsed .h3e-fold-mark { transform: rotate(-90deg); }
+
+.h3e-num,
+.h3e-ord {
+    background: color-mix(in srgb, var(--h3-accent) 28%, var(--h3-sunken));
+    color: var(--h3-text);
+    border-radius: 4px;
+    padding: 2px 8px;
+    font-size: 10px;
+    font-variant-numeric: tabular-nums;
+    white-space: nowrap;
+}
+.h3e-timing { font-size: 10px; color: var(--h3-muted); font-variant-numeric: tabular-nums; }
+.h3e-lock { font-size: 10px; color: var(--h3-warn); }
+.h3e-peek {
+    flex: 1;
+    min-width: 0;
+    overflow: hidden;
+    text-overflow: ellipsis;
+    white-space: nowrap;
+    font-size: 10px;
+    color: var(--h3-faint);
+}
+
+.h3e-beat { width: 100%; background: var(--h3-sunken); }
+
+/* -- directive row: grid, not fixed-width flex ---------------------------- */
+
+.h3e-dirs {
+    display: grid;
+    grid-template-columns: repeat(auto-fit, minmax(112px, 1fr));
+    gap: var(--h3-gap-sm);
+    margin-top: var(--h3-gap-sm);
+}
+.h3e-dir { display: flex; flex-direction: column; gap: 2px; min-width: 0; }
+.h3e-dir-label,
+.h3e-field > span:first-child {
+    font-size: var(--h3-fs-xs);
+    font-weight: var(--h3-weight-label);
+    letter-spacing: var(--h3-track);
+    text-transform: uppercase;
+    color: var(--h3-muted);
+}
+.h3e-select, .h3e-input { width: 100%; }
+
+/* -- notes: hint / warning / error are three different things ------------- */
+
+.h3e-note {
+    border-radius: var(--h3-radius-sm);
+    padding: 6px 8px;
+    margin-top: var(--h3-gap-sm);
+    line-height: 1.5;
+    border: 1px solid;
+    color: var(--h3-warn);
+    background: color-mix(in srgb, var(--h3-warn) 12%, transparent);
+    border-color: color-mix(in srgb, var(--h3-warn) 40%, transparent);
+}
+.h3e-note.h3e-note-error {
+    color: var(--h3-error);
+    background: color-mix(in srgb, var(--h3-error) 13%, transparent);
+    border-color: color-mix(in srgb, var(--h3-error) 45%, transparent);
+}
+.h3e-note.h3e-note-hint {
+    color: var(--h3-muted);
+    background: color-mix(in srgb, var(--h3-accent) 8%, transparent);
+    border-color: var(--h3-border-soft);
+}
+
+.h3e-adv { margin-top: var(--h3-gap-sm); }
+.h3e-adv > summary,
+.h3e-json-wrap > summary {
+    cursor: pointer;
+    color: var(--h3-muted);
+    font-size: 10px;
+    letter-spacing: .08em;
+    text-transform: uppercase;
+    padding: 3px 2px;
+    border-radius: 4px;
+}
+.h3e-adv > summary:hover,
+.h3e-json-wrap > summary:hover { color: var(--h3-text); background: var(--h3-accent-soft); }
+
+.h3e-grid {
+    display: grid;
+    grid-template-columns: repeat(auto-fit, minmax(104px, 1fr));
+    gap: var(--h3-gap-sm);
+    margin: var(--h3-gap-sm) 0;
+}
+.h3e-field { display: flex; flex-direction: column; gap: 2px; min-width: 0; }
+.h3e-field .h3e-input, .h3e-field .h3e-select { width: 100%; }
+.h3e-check { flex-direction: row; align-items: center; gap: 6px; }
+.h3e-check input { width: auto; }
+
+/* -- run panel ------------------------------------------------------------ */
+
+/* A <details> wearing .h3e-section, so it keeps the panel chrome whether it is
+ * open or shut. Collapsed by default: these dials are set once and then left,
+ * unlike the script above them, and the summary line carries enough of the
+ * state that opening it is a choice rather than a check. */
+.h3e-run { padding: var(--h3-gap); }
+.h3e-run > summary {
+    cursor: pointer;
+    display: flex;
+    align-items: baseline;
+    gap: var(--h3-gap-sm);
+    padding: 2px;
+    border-radius: 4px;
+    list-style: none;              /* the default triangle sits badly on a row */
+    min-width: 0;
+}
+.h3e-run > summary::-webkit-details-marker { display: none; }
+.h3e-run > summary::before {
+    content: "▸";
+    color: var(--h3-faint);
+    font-size: 9px;
+    transition: transform .12s ease;
+}
+.h3e-run[open] > summary::before { transform: rotate(90deg); }
+.h3e-run > summary:hover { background: var(--h3-accent-soft); }
+.h3e-run > summary:hover .h3e-title { color: var(--h3-text); }
+
+/* The digest is one line and must stay one line: it is read at a glance with
+ * the panel shut, and wrapping it would push the script off screen. */
+.h3e-run-digest {
+    flex: 1;
+    min-width: 0;
+    overflow: hidden;
+    text-overflow: ellipsis;
+    white-space: nowrap;
+    text-align: right;
+}
+
+.h3e-run-body { margin-top: var(--h3-gap-sm); }
+.h3e-run-group + .h3e-run-group {
+    margin-top: var(--h3-gap-sm);
+    padding-top: var(--h3-gap-sm);
+    border-top: 1px solid var(--h3-border-soft);
+}
+.h3e-run-label {
+    font-size: var(--h3-fs-xs);
+    font-weight: var(--h3-weight-label);
+    letter-spacing: var(--h3-track);
+    text-transform: uppercase;
+    color: var(--h3-muted);
+}
+/* auto-FILL, not auto-fit: auto-fit collapses the empty tracks, so the two
+ * dials in CACHE stretched to half the panel each while the four in OUTPUT sat
+ * at a quarter. Keeping the empty tracks lines every group up on one grid. */
+.h3e-run-group .h3e-grid {
+    margin-top: 4px;
+    grid-template-columns: repeat(auto-fill, minmax(104px, 1fr));
+}
+.h3e-run .h3e-run-wide { grid-column: span 2; }
+/* Digits line up column-wise, so a changed seed is visible at a glance. */
+.h3e-run input[type="number"] { font-variant-numeric: tabular-nums; }
+
+/* A checkbox plus the widget's own label_on/label_off, so the state reads as
+ * "vary per hop" rather than as a bare tick. */
+.h3e-run-toggle { display: flex; align-items: center; gap: 6px; min-width: 0; }
+.h3e-root .h3e-run-toggle input { width: auto; flex: none; }
+.h3e-run-togglabel {
+    overflow: hidden;
+    text-overflow: ellipsis;
+    white-space: nowrap;
+    color: var(--h3-muted);
+}
+
+
+/* -- reference rail ------------------------------------------------------- */
+
+/* Was fixed pixel widths in a non-wrapping flex row summing to ~406px, so the
+ * description got crushed and the row overflowed a narrow node. */
+.h3e-ref {
+    display: grid;
+    grid-template-columns: auto minmax(88px, 1.1fr) minmax(74px, .8fr) minmax(74px, .8fr) minmax(96px, 1fr) minmax(120px, 1.6fr) auto;
+    align-items: center;
+    gap: var(--h3-gap-sm);
+    padding: 4px;
+    margin-bottom: 4px;
+    min-height: var(--h3-row-h);
+    border: 1px solid transparent;
+    border-radius: var(--h3-radius-sm);
+    transition: background-color .13s ease, border-color .13s ease;
+}
+.h3e-ref:hover { background: var(--h3-panel); border-color: var(--h3-border-soft); }
+.h3e-ref.h3e-inactive { opacity: .55; }
+.h3e-ref.h3e-bad { border-color: color-mix(in srgb, var(--h3-error) 55%, transparent); }
+.h3e-ref.h3e-bad .h3e-tag { border-color: var(--h3-error); }
+.h3e-inactive .h3e-ord { background: var(--h3-sunken); color: var(--h3-faint); }
+.h3e-tag, .h3e-slot, .h3e-subj, .h3e-ret, .h3e-desc { width: 100%; }
+
+/* The rail's 7-track grid needs ~536px of content width and the node only ever
+ * offers ~510px at NODE_WIDTH 560, so it is crushed by default. These queries
+ * are the relief -- and until `container-type` was declared on .h3e-section
+ * (below) they matched nothing at all, because a @container query without a
+ * containment context is dead code. That is why the rail looked mangled at
+ * every node width. */
+@container (max-width: 560px) {
+    /* Drop the description to its own line first: it is the widest track and
+     * the least useful one to read mid-row. */
+    .h3e-ref {
+        grid-template-columns: auto minmax(88px, 1.2fr) minmax(74px, .9fr) minmax(74px, .9fr) minmax(96px, 1fr) auto;
+    }
+    .h3e-ref .h3e-desc { grid-column: 2 / -1; }
+}
+@container (max-width: 430px) {
+    /* Then stack: tag on the top row with the ordinal and the kill, the three
+     * selects sharing the next, description below that. */
+    .h3e-ref { grid-template-columns: auto 1fr auto; }
+    .h3e-ref .h3e-slot,
+    .h3e-ref .h3e-subj { grid-column: 2 / 3; }
+    .h3e-ref .h3e-ret,
+    .h3e-ref .h3e-desc { grid-column: 1 / -1; }
+}
+
+/* Per-hop schedule chips. */
+.h3e-chips { display: flex; flex-wrap: wrap; gap: 3px; grid-column: 1 / -1; padding: 2px 0 0 26px; }
+.h3e-chip {
+    font-size: 9px;
+    line-height: 1;
+    padding: 3px 6px;
+    border-radius: 999px;
+    border: 1px solid var(--h3-border-soft);
+    background: var(--h3-sunken);
+    color: var(--h3-faint);
+    cursor: pointer;
+    user-select: none;
+    transition: background-color .12s ease, color .12s ease, border-color .12s ease;
+}
+.h3e-chip:hover { border-color: var(--h3-accent); color: var(--h3-text); }
+.h3e-chip.h3e-chip-on {
+    background: color-mix(in srgb, var(--h3-accent) 30%, var(--h3-sunken));
+    color: var(--h3-text);
+    border-color: color-mix(in srgb, var(--h3-accent) 55%, transparent);
+}
+.h3e-chips-label { font-size: 9px; color: var(--h3-faint); align-self: center; margin-right: 2px; letter-spacing: .06em; }
+
+.h3e-subject {
+    display: flex;
+    align-items: center;
+    gap: var(--h3-gap-sm);
+    margin: 4px 0 var(--h3-gap-sm) 26px;
+}
+.h3e-subject .h3e-input { flex: 1; }
+.h3e-subj-badge {
+    /* Was a hardcoded #a98bd8 that appeared nowhere else in the sheet and read
+     * as an unexplained colour code beside the ordinal badge. A subject is a
+     * different KIND of thing, not a different priority: outline, not fill. */
+    background: transparent;
+    border: 1px solid var(--h3-accent);
+    color: var(--h3-accent);
+    border-radius: 4px;
+    padding: 2px 8px;
+    font-size: 10px;
+    white-space: nowrap;
+}
+
+.h3e-json {
+    width: 100%;
+    min-height: 120px;
+    background: var(--h3-sunken);
+    font-family: ui-monospace, SFMono-Regular, Menlo, monospace;
+    font-size: 10px;
+    margin-top: 4px;
+}
+
+/* -- vocabulary unavailable ----------------------------------------------- */
+
+.h3e-offline {
+    display: flex;
+    align-items: center;
+    gap: var(--h3-gap-sm);
+    margin-bottom: var(--h3-gap-sm);
+}
+.h3e-offline .h3e-btn { margin-left: auto; }
+
+/* --------------------------------------------------------------- preview -- */
+
+.h3rc-preview {
+    display: flex;
+    flex-direction: column;
+    width: 100%;
+    height: 100%;
+    min-height: 0;
+    background: var(--h3-bg);
+    border: 1px solid var(--h3-border);
+    border-radius: var(--h3-radius);
+    overflow: hidden;
+}
+
+.h3rc-frame { position: relative; flex: 1 1 auto; min-height: 60px; background: var(--h3-sunken); }
+.h3rc-img {
+    position: absolute; inset: 0;
+    width: 100%; height: 100%;
+    object-fit: contain;
+    display: none;
+}
+.h3rc-img.h3rc-seam-b { clip-path: inset(0 0 0 50%); }
+
+.h3rc-placeholder {
+    position: absolute; inset: 0;
+    display: flex; align-items: center; justify-content: center;
+    color: var(--h3-faint);
+    font-size: 12px;
+    letter-spacing: .02em;
+    user-select: none;
+    text-align: center;
+    padding: 0 12px;
+}
+
+/* Seam divider, only while two frames are shown. */
+.h3rc-seam-line {
+    position: absolute; top: 0; bottom: 0; left: 50%;
+    width: 1px;
+    background: color-mix(in srgb, var(--h3-accent) 70%, transparent);
+    display: none;
+}
+.h3rc-seam-tag {
+    position: absolute; bottom: 6px;
+    font-size: 9px; letter-spacing: .08em; text-transform: uppercase;
+    color: var(--h3-text);
+    background: color-mix(in srgb, #000 55%, transparent);
+    padding: 2px 6px; border-radius: 3px;
+    display: none;
+}
+.h3rc-seam-tag.h3rc-tag-a { left: 6px; }
+.h3rc-seam-tag.h3rc-tag-b { right: 6px; }
+.h3rc-showing-seam .h3rc-seam-line,
+.h3rc-showing-seam .h3rc-seam-tag { display: block; }
+
+/* Progress across the whole chain. */
+.h3rc-bar { flex: 0 0 3px; background: var(--h3-sunken); overflow: hidden; }
+.h3rc-bar-fill {
+    height: 100%;
+    width: 0;
+    background: var(--h3-accent);
+    transition: width .25s ease;
+}
+.h3rc-bar-fill.h3rc-done { background: var(--h3-ok); }
+
+.h3rc-panel {
+    flex: 0 0 auto;
+    display: flex;
+    flex-direction: column;
+    gap: 3px;
+    padding: 6px 9px;
+    background: var(--h3-panel);
+    border-top: 1px solid var(--h3-border-soft);
+}
+.h3rc-line { display: flex; align-items: center; gap: var(--h3-gap-sm); font-size: 11px; min-width: 0; }
+.h3rc-status-label { color: var(--h3-muted); flex: 0 0 auto; }
+.h3rc-status-value {
+    overflow: hidden; text-overflow: ellipsis; white-space: nowrap;
+    min-width: 0; flex: 1;
+    color: var(--h3-text);
+    font-variant-numeric: tabular-nums;
+}
+.h3rc-meta {
+    display: flex; flex-wrap: wrap; gap: 4px 10px;
+    font-size: 10px; color: var(--h3-muted);
+    font-variant-numeric: tabular-nums;
+}
+.h3rc-meta b { font-weight: 600; color: var(--h3-text); }
+.h3rc-mech { padding: 1px 6px; border-radius: 999px; font-size: 9px; letter-spacing: .04em; }
+.h3rc-mech-motion_context { background: color-mix(in srgb, var(--h3-ok) 26%, transparent); color: var(--h3-text); }
+.h3rc-mech-addguide_pixels { background: color-mix(in srgb, var(--h3-warn) 30%, transparent); color: var(--h3-text); }
+
+/* Resize grip -- pointer capture, unscaled offsetHeight. */
+.h3rc-grip {
+    flex: 0 0 11px;
+    position: relative;
+    cursor: ns-resize;
+    background: var(--h3-panel);
+    border-top: 1px solid var(--h3-border-soft);
+}
+.h3rc-grip::after {
+    content: "";
+    position: absolute;
+    left: calc(50% - 18px);
+    top: 4px;
+    width: 36px; height: 2px;
+    border-radius: 2px;
+    background: var(--h3-faint);
+}
+.h3rc-grip:hover::after { background: var(--h3-accent); }
+
+
+/* -- accent states, pickers, media strip ----------------------------------
+ *
+ * The old palette was a soft blue, so "active" could be a 28-34% tint sitting
+ * behind unchanged text. An acid accent cannot do that -- the result is olive
+ * mud -- so emphasis inverts instead: accent fill, ink text. Same rule
+ * PromptMasterLD uses, and the reason --h3-on-accent exists.
+ */
+.h3e-root .h3e-mode.h3e-on {
+    background: var(--h3-accent);
+    color: var(--h3-on-accent);
+    font-weight: 700;
+}
+.h3e-num,
+.h3e-ord {
+    background: var(--h3-accent);
+    color: var(--h3-on-accent);
+    font-weight: 700;
+}
+.h3e-inactive .h3e-ord {
+    background: var(--h3-sunken);
+    color: var(--h3-faint);
+}
+.h3e-chip.h3e-chip-on {
+    background: var(--h3-accent);
+    color: var(--h3-on-accent);
+    border-color: var(--h3-accent);
+    font-weight: 700;
+}
+
+/* Grouping by a left rule and a wash rather than an outlined box. */
+.h3e-section {
+    border: none;
+    border-left: 2px solid var(--h3-border);
+    background: var(--h3-bg);
+}
+.h3e-card { border-left-width: 2px; }
+.h3e-run-group {
+    border-left: 2px solid var(--h3-accent);
+    background: var(--h3-accent-wash);
+    padding-left: var(--h3-gap-sm);
+}
+
+/* -- media pickers --------------------------------------------------------
+ *
+ * Empty is dashed, filled is solid, so the border alone says whether a slot
+ * holds something -- readable at a glance across nine of them. `contain` and
+ * never `cover`: the whole job of this thumbnail is letting you identify the
+ * picture, and a cropped face is worse than a letterboxed one.
+ */
+.h3e-pick { display: flex; flex-direction: column; gap: 2px; min-width: 0; }
+.h3e-thumb {
+    position: relative;
+    width: 100%;
+    height: 46px;
+    border: 1px dashed var(--h3-border);
+    background: var(--h3-sunken);
+    display: flex;
+    align-items: center;
+    justify-content: center;
+    cursor: pointer;
+    overflow: hidden;
+    transition: border-color .12s ease, background-color .12s ease;
+}
+.h3e-thumb:hover { border-color: var(--h3-accent); }
+.h3e-thumb.h3e-has { border-style: solid; }
+.h3e-thumb.h3e-hot {
+    border-style: solid;
+    border-color: var(--h3-accent);
+    background: color-mix(in srgb, var(--h3-accent) 10%, var(--h3-sunken));
+}
+.h3e-thumb-img {
+    position: absolute;
+    inset: 0;
+    width: 100%;
+    height: 100%;
+    object-fit: contain;
+    pointer-events: none;
+}
+.h3e-thumb-hint {
+    font-size: var(--h3-fs-xs);
+    color: var(--h3-faint);
+    text-align: center;
+    line-height: 1.15;
+    white-space: pre-line;
+    pointer-events: none;
+}
+.h3e-thumb-bad { color: var(--h3-error); }
+/* Reveal on hover, and a destructive hover is a tinted ground rather than a
+ * red fill -- a clear button that shouts is one people misread. */
+.h3e-root .h3e-thumb-x {
+    position: absolute;
+    top: 2px;
+    right: 2px;
+    z-index: 5;
+    width: 16px;
+    height: 16px;
+    padding: 0;
+    line-height: 1;
+    display: none;
+    align-items: center;
+    justify-content: center;
+    background: color-mix(in srgb, #000 78%, transparent);
+    border: 1px solid var(--h3-border);
+    color: var(--h3-muted);
+}
+.h3e-thumb:hover .h3e-thumb-x { display: flex; }
+.h3e-root .h3e-thumb-x:hover {
+    color: var(--h3-error);
+    border-color: var(--h3-error);
+    background: color-mix(in srgb, var(--h3-error) 18%, #000);
+}
+.h3e-root .h3e-pickfile {
+    font-size: var(--h3-fs-xs);
+    padding: 2px 4px;
+}
+
+/* -- media strip ---------------------------------------------------------- */
+.h3e-media-grid {
+    display: grid;
+    grid-template-columns: repeat(auto-fill, minmax(104px, 1fr));
+    gap: var(--h3-gap-sm);
+    margin-top: 4px;
+}
+.h3e-media-cell { display: flex; flex-direction: column; gap: 2px; min-width: 0; }
+.h3e-media-label {
+    font-size: var(--h3-fs-xs);
+    font-weight: var(--h3-weight-label);
+    letter-spacing: var(--h3-track);
+    text-transform: uppercase;
+    color: var(--h3-muted);
+}
+
+
+/* -- pinned RUN ----------------------------------------------------------
+ *
+ * `.h3e-root` used to be the scroll container with all four sections as
+ * children, which put RUN below the script -- out of view on any workflow
+ * with more than a couple of shots, and it is the section you open on every
+ * queue. Split in two: the authoring sections scroll, RUN is pinned.
+ *
+ * `min-height: 0` on the scroller is what makes this work at all. A flex item
+ * defaults to `min-height: auto`, so the scroller would refuse to shrink below
+ * its content and push RUN off the bottom of the node instead of scrolling.
+ */
+.h3e-scroll {
+    flex: 1 1 auto;
+    /* Never let RUN crush the authoring sections to nothing. Below this the
+     * scroller stops shrinking and RUN scrolls internally instead. */
+    min-height: 160px;
+    overflow-y: auto;
+    scrollbar-gutter: stable;
+    display: flex;
+    flex-direction: column;
+    gap: var(--h3-gap);
+}
+.h3e-root > .h3e-run {
+    /* `0 0 auto`. It must NOT shrink: flex divides a deficit in proportion to
+     * each item's content height, and the scroller's content is far taller, so
+     * a shrinkable RUN loses most of the space and clips its lower groups. The
+     * scroller absorbs all the shrinking; its min-height is the floor that
+     * stops RUN taking the whole panel, and max-height below is the ceiling. */
+    flex: 0 0 auto;
+    max-height: 55%;
+    display: flex;
+    flex-direction: column;
+    min-height: 0;
+}
+/* Always open, so the disclosure triangle would be a control that does
+ * nothing. The summary stays as the header and digest bar. */
+.h3e-root > .h3e-run > .h3e-run-sum {
+    cursor: default;
+    list-style: none;
+}
+.h3e-root > .h3e-run > .h3e-run-sum::-webkit-details-marker { display: none; }
+.h3e-root > .h3e-run > .h3e-run-sum::marker { content: ""; }
+.h3e-root > .h3e-run > .h3e-run-body {
+    overflow-y: auto;
+    min-height: 0;
+}
+/* Pinned means it reads as chrome, not as another card in the stack. */
+.h3e-root > .h3e-run > .h3e-run-sum {
+    position: sticky;
+    top: 0;
+    z-index: 2;
+    background: var(--h3-bg);
+}
+
+/* -- template panel -------------------------------------------------------
+ * Sits between the SCRIPT header and the card list, hidden until asked for.
+ * Each row is text plus one button, so the whole thing survives the narrow
+ * container breakpoints without its own media query. */
+.h3e-tpl {
+    display: flex;
+    flex-direction: column;
+    gap: 1px;
+    margin-bottom: var(--h3-gap-sm);
+    border: 1px solid var(--h3-border-soft);
+    background: var(--h3-sunken);
+}
+
+.h3e-tpl > .h3e-note {
+    margin: 0;
+    border: 0;
+    border-bottom: 1px solid var(--h3-border-soft);
+    color: var(--h3-faint);
+}
+
+.h3e-tpl-row {
+    display: flex;
+    align-items: flex-start;
+    gap: var(--h3-gap);
+    padding: 7px 8px;
+}
+
+.h3e-tpl-row + .h3e-tpl-row { border-top: 1px solid var(--h3-border-soft); }
+.h3e-tpl-row:hover { background: var(--h3-accent-wash); }
+
+/* min-width: 0 or the text column refuses to wrap and pushes the button off
+ * the panel -- a flex item will not shrink below its content by default. */
+.h3e-tpl-text { flex: 1 1 auto; min-width: 0; }
+
+.h3e-tpl-name {
+    color: var(--h3-text);
+    font-size: var(--h3-fs);
+    font-weight: var(--h3-weight-label);
+}
+
+.h3e-tpl-hint {
+    color: var(--h3-muted);
+    font-size: var(--h3-fs-sm);
+    margin-top: 1px;
+}
+
+.h3e-tpl-note {
+    color: var(--h3-faint);
+    font-size: var(--h3-fs-sm);
+    line-height: 1.5;
+    margin-top: 3px;
+}
+
+.h3e-tpl-row > .h3e-btn { flex: 0 0 auto; }

js/h3_ref_chain_ui.js

@@ -0,0 +1,239 @@
+import { app } from "../../scripts/app.js";
+import { api } from "../../scripts/api.js";
+import {
+    el, isolateEvents, installHeightGuard, setWidgetVisibility, widgetByName,
+} from "./editor/widget_utils.js";
+import { createPlanEditor } from "./editor/plan_editor.js";
+import { createRefRail, parseRefPlan, refPlanToJson } from "./editor/ref_rail.js";
+import { createRunPanel } from "./editor/run_panel.js";
+import { createMediaStrip, MEDIA_WIDGETS } from "./editor/media_strip.js";
+
+const VERSION = "v1.5.0";
+/* Both ids. The pack registers the pre-rename id as a deprecated subclass so
+ * workflows saved before 2026-08-29 still load. If this check knew only the
+ * new id those nodes would come up with NO editor at all, which looks exactly
+ * like the rename having broken the pack. */
+const NODE_TYPES = new Set(["HandTieClips", "H3RefChain"]);
+const NODE_WIDTH = 560;
+const EDITOR_MIN_H = 460;
+const STYLE_ID = "h3rc-style";
+
+/* Widgets the editor owns. In Simple mode the plan is hidden instead.
+ *
+ * The run panel's share is NOT listed here: it reports the widgets it actually
+ * managed to draw, and only those are hidden. A dial the panel could not render
+ * -- a type it does not know, or one renamed on the Python side -- therefore
+ * stays visible as a native widget instead of vanishing from the node. */
+// MEDIA_WIDGETS are the three filename STRINGs that replaced the
+// start_image / reference_video / voice sockets. They are always hidden:
+// the media strip owns them in both modes, and shown raw they are three
+// text boxes inviting you to type a path that would not resolve.
+const SHOTS_HIDDEN = ["prompt", "chains", "hop_script", "shot_plan", "ref_plan"]
+    .concat(MEDIA_WIDGETS);
+const SIMPLE_HIDDEN = ["shot_plan", "ref_plan"].concat(MEDIA_WIDGETS);
+
+const _cssUrl = new URL("./h3_ref_chain.css", import.meta.url).href;
+
+/* External stylesheet, not a template literal. The old inline sheet hardcoded
+ * every colour, so a light ComfyUI theme rendered the panel as dark islands on
+ * a light node; the CSS file derives everything from the host theme's own
+ * custom properties. */
+function ensureStyles() {
+    if (document.getElementById(STYLE_ID)) return;
+    const link = document.createElement("link");
+    link.id = STYLE_ID;
+    link.rel = "stylesheet";
+    link.href = _cssUrl;
+    document.head.appendChild(link);
+}
+
+/* -- editor -------------------------------------------------------------- */
+
+function mountEditor(node) {
+    if (node._h3Editor) return;
+    if (typeof node.addDOMWidget !== "function") {
+        console.warn("[HandTieClips] no addDOMWidget on this frontend; editor not mounted");
+        return;
+    }
+    const planWidget = widgetByName(node, "shot_plan");
+    const refWidget = widgetByName(node, "ref_plan");
+    if (!planWidget || !refWidget) {
+        // Stale node definition: the Python side was not reloaded. Silent here
+        // is what made this hard to diagnose the first time.
+        console.warn(
+            "[HandTieClips] shot_plan/ref_plan widget missing -- restart ComfyUI. "
+            + "Widgets present:", (node.widgets || []).map((w) => w.name),
+        );
+        return;
+    }
+    ensureStyles();
+
+    const root = el("div", "h3e-root");
+    isolateEvents(root);
+
+    // A ref_plan that does not parse must NOT be silently replaced by an empty
+    // one: the rail would then write "" over it on the next edit, destroying a
+    // paste the author was in the middle of repairing. Keep the raw text in the
+    // widget, flag it, and let the rail's JSON section show and fix it.
+    let refBad = false;
+    const readRefPlan = () => {
+        const parsed = parseRefPlan(refWidget.value);
+        refBad = parsed === null;
+        return parsed || { refs: [], subjects: {} };
+    };
+    let refPlan = readRefPlan();
+
+    // How many hops this run will actually do. The shot plan is authoritative
+    // when present -- run() ignores `chains` the moment one is loaded -- so both
+    // the rail's schedule chips and the run panel's summary read it from here
+    // rather than from the widget that no longer decides.
+    const hopCount = () => {
+        const plan = widgetByName(node, "shot_plan")?.value;
+        try {
+            const parsed = JSON.parse((plan || "").trim() || "null");
+            const arr = Array.isArray(parsed) ? parsed : parsed?.shots;
+            if (Array.isArray(arr) && arr.length) return arr.length;
+        } catch (_) { /* unparseable plan: fall back to chains */ }
+        return Number(widgetByName(node, "chains")?.value) || 1;
+    };
+
+    const rail = createRefRail(node, {
+        getPlan: () => refPlan,
+        setPlan: (p) => { refPlan = p; refBad = false; refWidget.value = refPlanToJson(p); },
+        getRaw: () => refWidget.value,
+        isBad: () => refBad,
+        onChange: () => node.graph?.setDirtyCanvas?.(true, true),
+        hopCount,
+    });
+
+    const editor = createPlanEditor(node, {
+        onChange: () => {
+            applyVisibility();
+            node.graph?.setDirtyCanvas?.(true, true);
+        },
+    });
+
+    const runPanel = createRunPanel(node, {
+        onChange: () => node.graph?.setDirtyCanvas?.(true, true),
+        hopCount,
+        // In Shots mode these two are decided by the plan, not by the user:
+        // run() ignores `chains` and forces `hop_script=next`. They are already
+        // in SHOTS_HIDDEN, so dropping them here leaves them hidden rather than
+        // offering a control that does nothing.
+        suppressed: () => (editor.mode() === "shots" ? ["chains", "hop_script"] : []),
+    });
+
+    const mediaStrip = createMediaStrip(node, {
+        onChange: () => node.graph?.setDirtyCanvas?.(true, true),
+    });
+
+    // Authoring sections scroll; RUN does not. RUN is the one section touched
+    // on every queue, and it used to be the last child of the scroller -- so
+    // it sat below however many shot cards the script had and you had to
+    // scroll the panel just to reach the summary bar. It is pinned to the
+    // bottom of the panel now, collapsed to its ~28px summary until opened.
+    const scroll = el("div", "h3e-scroll");
+    scroll.appendChild(rail.root);
+    scroll.appendChild(mediaStrip.root);
+    scroll.appendChild(editor.root);
+    root.appendChild(scroll);
+    root.appendChild(runPanel.root);
+
+    const domWidget = node.addDOMWidget("h3_editor", "h3_editor", root, {
+        serialize: false,
+        hideOnZoom: false,
+        getMinHeight: () => EDITOR_MIN_H,
+    });
+    domWidget.serialize = false;
+
+    installHeightGuard(node, domWidget, { minHeight: EDITOR_MIN_H, minWidth: NODE_WIDTH });
+
+    function applyVisibility() {
+        // The rail always owns ref_plan; the plan widget's visibility follows
+        // the mode, so Simple mode never leaves an inert second text area up.
+        // sync() first: ownedNames() decides what gets hidden, so rebuilding
+        // after the hide would hide a dial the panel had stopped drawing.
+        runPanel.sync();
+        const base = editor.mode() === "shots" ? SHOTS_HIDDEN : SIMPLE_HIDDEN;
+        setWidgetVisibility(node, base.concat(runPanel.ownedNames()));
+    }
+
+    node._h3Editor = {
+        refresh() {
+            refPlan = readRefPlan();
+            editor.reload();
+            rail.render();
+            mediaStrip.render();
+            applyVisibility();   // syncs the run panel on the way through
+        },
+        rail,
+        editor,
+        runPanel,
+    };
+
+    applyVisibility();
+    rail.render();
+    mediaStrip.render();
+    editor.render();
+
+    // `control_after_generate` bumps the seed widget as the prompt is queued,
+    // and undo rewrites widgets wholesale -- both behind this panel's back.
+    // RUN used to re-read on open, which is no longer a moment that exists.
+    // `promptQueued` fires client-side after the bump has been applied.
+    const onQueued = () => {
+        try {
+            runPanel.sync();
+        } catch (err) {
+            console.warn("[HandTieClips] run panel resync failed:", err);
+        }
+    };
+    api.addEventListener("promptQueued", onQueued);
+    // Removing the node must drop the listener, or every add/remove cycle
+    // leaves another closure holding this node alive.
+    const prevRemoved = node.onRemoved;
+    node.onRemoved = function (...args) {
+        api.removeEventListener("promptQueued", onQueued);
+        return prevRemoved?.apply(this, args);
+    };
+
+    console.log(`[HandTieClips] ${VERSION} editor mounted on node ${node.id}`);
+}
+
+console.log(`[HandTieClips] editor ui ${VERSION} loaded`);
+
+app.registerExtension({
+    name: "HandTieClips.ui",
+    async beforeRegisterNodeDef(nodeType, nodeData) {
+        if (!NODE_TYPES.has(nodeData.name)) return;
+
+        const onNodeCreated = nodeType.prototype.onNodeCreated;
+        nodeType.prototype.onNodeCreated = function () {
+            const r = onNodeCreated?.apply(this, arguments);
+            mountEditor(this);
+            this.setSize([
+                Math.max(this.size[0], NODE_WIDTH),
+                Math.max(this.size[1], 640),
+            ]);
+            return r;
+        };
+
+        const onConfigure = nodeType.prototype.onConfigure;
+        nodeType.prototype.onConfigure = function () {
+            const r = onConfigure?.apply(this, arguments);
+            mountEditor(this);
+            // Widget values arrive with the workflow, after the mount, so the
+            // panel has to re-read them or a loaded graph shows an empty editor.
+            this._h3Editor?.refresh();
+            return r;
+        };
+
+        // Wiring or unwiring a ref_image_N input changes the ordinals and the
+        // wired/unwired dots, so the rail has to be told.
+        const onConnectionsChange = nodeType.prototype.onConnectionsChange;
+        nodeType.prototype.onConnectionsChange = function () {
+            const r = onConnectionsChange?.apply(this, arguments);
+            this._h3Editor?.rail?.render();
+            return r;
+        };
+    },
+});

media.py

@@ -0,0 +1,270 @@
+"""Files on disk -> tensors, plus the path safety that makes that survivable.
+
+The node used to take its pictures down nine `ref_image_N` IMAGE sockets, which
+meant nine `Load Image` nodes and a 16-socket column occupying a third of the
+node before the editor even started. References now live as *files* in
+`<ComfyUI input>/h3_refs`, and a reference carries a filename rather than a
+wire.
+
+Two rules this module exists to enforce:
+
+**Nothing from the browser is trusted as a path.** `resolve` normalises, then
+prefix-checks against the reference directory, then checks the extension. A
+POST route that writes files is only as safe as the function deciding where the
+bytes land, so that function lives here, is nine lines, and is used by both the
+route and the loaders.
+
+**Pixels never travel as base64.** Only the basename is stored in a widget.
+PromptMasterLD measured 1.68 MB of widget value for nine images and ComfyUI
+then failed to save the workflow at all; the filename is the whole payload.
+
+The loaders deliberately return exactly what a `Load Image` would -- float
+`[N,H,W,3]` in 0..1 -- so everything downstream of the old sockets is unchanged,
+including `_ref_frames`' resize and `store.tensor_digest`'s cache keying.
+
+No hard ComfyUI import: `input_dir()` falls back to a path relative to this
+file, so the loaders and the safety check are testable without a running server
+(same rule as `plan.py`, `refs.py` and `tone.py`).
+"""
+from __future__ import annotations
+
+import os
+
+TAG = "HandTieClips"
+
+# One flat folder under ComfyUI's input dir. Flat on purpose: `/view` takes a
+# basename plus one subfolder, and a tree would need a second lookup for no
+# benefit at the scale a chain uses (single digits of references).
+REFS_SUBDIR = "h3_refs"
+
+IMAGE_EXTS = {".png", ".jpg", ".jpeg", ".webp", ".bmp"}
+VIDEO_EXTS = {".mp4", ".mov", ".webm", ".mkv", ".avi", ".m4v"}
+AUDIO_EXTS = {".wav", ".mp3", ".flac", ".ogg", ".m4a", ".aac"}
+ALL_EXTS = IMAGE_EXTS | VIDEO_EXTS | AUDIO_EXTS
+
+# Anything past this is re-encoded on upload. A 12 MP phone photo is a
+# reference, not an asset: it costs decode RAM on every load and is about to be
+# resized to the canvas anyway.
+MAX_SIDE = 2048
+MAX_PIXELS = 1_500_000
+JPEG_QUALITY = 88
+
+
+def kind_of(name):
+    """'image' | 'video' | 'audio' | None, from the extension alone."""
+    ext = os.path.splitext(str(name or ""))[1].lower()
+    if ext in IMAGE_EXTS:
+        return "image"
+    if ext in VIDEO_EXTS:
+        return "video"
+    if ext in AUDIO_EXTS:
+        return "audio"
+    return None
+
+
+def input_dir():
+    """ComfyUI's input directory, or a sibling `input/` when it is absent."""
+    try:
+        import folder_paths  # noqa: PLC0415
+        return folder_paths.get_input_directory()
+    except Exception:
+        here = os.path.dirname(os.path.dirname(os.path.abspath(__file__)))
+        return os.path.join(os.path.dirname(here), "input")
+
+
+def refs_dir(create=False):
+    d = os.path.join(input_dir(), REFS_SUBDIR)
+    if create:
+        os.makedirs(d, exist_ok=True)
+    return d
+
+
+def resolve(name, kinds=None):
+    """Absolute path for a reference basename, or None.
+
+    Refuses anything that escapes the reference directory, carries an unknown
+    extension, or does not exist. `name` is treated as a bare filename -- any
+    directory component is a caller error, not a feature, so `..` cannot even be
+    expressed as a traversal.
+
+    `kinds` optionally restricts to {'image','video','audio'}.
+    """
+    raw = str(name or "").strip()
+    if not raw:
+        return None
+    kind = kind_of(raw)
+    if kind is None:
+        return None
+    if kinds and kind not in kinds:
+        return None
+    base = os.path.normpath(refs_dir())
+    full = os.path.normpath(os.path.join(base, raw.replace("/", os.sep)))
+    # The prefix check is the load-bearing line. normpath has already collapsed
+    # any `..`, so a path that still starts with the reference directory cannot
+    # be pointing outside it.
+    if full != base and not full.startswith(base + os.sep):
+        return None
+    return full if os.path.isfile(full) else None
+
+
+def listing(kinds=None):
+    """Reference filenames on disk, newest first, for the editor's dropdown."""
+    d = refs_dir()
+    if not os.path.isdir(d):
+        return []
+    rows = []
+    for name in os.listdir(d):
+        kind = kind_of(name)
+        if kind is None or (kinds and kind not in kinds):
+            continue
+        path = os.path.join(d, name)
+        if not os.path.isfile(path):
+            continue
+        try:
+            rows.append((os.path.getmtime(path), name, kind))
+        except OSError:
+            continue
+    rows.sort(reverse=True)
+    return [{"name": n, "kind": k} for _m, n, k in rows]
+
+
+def stamp(names):
+    """`name:mtime` for each file, for IS_CHANGED.
+
+    ComfyUI caches a node's output on its inputs, and a filename is a stable
+    input even when the bytes behind it change. Without this, replacing a
+    reference in place would serve the previous render.
+    """
+    bits = []
+    for name in names:
+        if not name:
+            continue
+        path = resolve(name)
+        try:
+            bits.append(f"{name}:{os.path.getmtime(path)}" if path else f"{name}:missing")
+        except OSError:
+            bits.append(f"{name}:missing")
+    return "|".join(bits)
+
+
+# -- loaders ---------------------------------------------------------------
+
+def _to_tensor(pil):
+    import numpy as np  # noqa: PLC0415
+    import torch  # noqa: PLC0415
+
+    arr = np.asarray(pil.convert("RGB"), dtype=np.float32) / 255.0
+    return torch.from_numpy(arr).unsqueeze(0)
+
+
+def load_image(name):
+    """One still as an IMAGE tensor `[1,H,W,3]`, or None.
+
+    Returns what a `Load Image` returns, so `_ref_frames` resizes it and
+    `tensor_digest` keys it exactly as before.
+    """
+    path = resolve(name, kinds={"image"})
+    if path is None:
+        return None
+    try:
+        from PIL import Image, ImageOps  # noqa: PLC0415
+        with Image.open(path) as im:
+            # EXIF orientation: a phone portrait otherwise loads on its side,
+            # and the model would be handed a rotated face.
+            return _to_tensor(ImageOps.exif_transpose(im))
+    except Exception as exc:
+        print(f"[{TAG}] could not read reference {name!r}: {exc!r}", flush=True)
+        return None
+
+
+def load_video(name, max_frames=None):
+    """A clip as an IMAGE batch `[N,H,W,3]`, or None."""
+    path = resolve(name, kinds={"video"})
+    if path is None:
+        return None
+    try:
+        import av  # noqa: PLC0415
+        import numpy as np  # noqa: PLC0415
+        import torch  # noqa: PLC0415
+
+        frames = []
+        with av.open(path) as container:
+            for frame in container.decode(video=0):
+                frames.append(frame.to_ndarray(format="rgb24"))
+                if max_frames and len(frames) >= int(max_frames):
+                    break
+        if not frames:
+            return None
+        arr = np.stack(frames).astype(np.float32) / 255.0
+        return torch.from_numpy(arr)
+    except Exception as exc:
+        print(f"[{TAG}] could not read video {name!r}: {exc!r}", flush=True)
+        return None
+
+
+def load_audio(name):
+    """A take as ComfyUI's AUDIO dict, or None.
+
+    Shape is `[batch, channels, samples]`, which is what every AUDIO consumer
+    in the graph expects.
+    """
+    path = resolve(name, kinds={"audio"})
+    if path is None:
+        return None
+    try:
+        import torch  # noqa: PLC0415
+        import torchaudio  # noqa: PLC0415
+
+        wav, sr = torchaudio.load(path)
+        if wav.dim() == 1:
+            wav = wav.unsqueeze(0)
+        return {"waveform": wav.unsqueeze(0).float(), "sample_rate": int(sr)}
+    except Exception as exc:
+        print(f"[{TAG}] could not read audio {name!r}: {exc!r}", flush=True)
+        return None
+
+
+# -- writing (used by the upload route) ------------------------------------
+
+def unique_path(directory, filename):
+    """A free path in `directory`, suffixing `_1`, `_2`... on collision."""
+    name = os.path.basename(str(filename or "").strip()) or "upload"
+    stem, ext = os.path.splitext(name)
+    path, i = os.path.join(directory, name), 1
+    while os.path.exists(path):
+        path = os.path.join(directory, f"{stem}_{i}{ext}")
+        i += 1
+    return path
+
+
+def shrink_image(path):
+    """Re-encode an oversized still in place. -> (final_path, w, h).
+
+    A 12 MP drop costs decode RAM on every single load and is about to be
+    resized to a 0.3 MP canvas regardless. Anything within budget is left
+    untouched, so a PNG the author cared about stays a PNG.
+    """
+    try:
+        from PIL import Image, ImageOps  # noqa: PLC0415
+        with Image.open(path) as im:
+            im = ImageOps.exif_transpose(im)
+            w, h = im.size
+            if w * h <= MAX_PIXELS and max(w, h) <= MAX_SIDE:
+                return path, w, h
+            scale = min(MAX_SIDE / max(w, h), (MAX_PIXELS / float(w * h)) ** 0.5, 1.0)
+            new = (max(1, int(w * scale)), max(1, int(h * scale)))
+            im = im.convert("RGB").resize(new, Image.Resampling.LANCZOS)
+            out = os.path.splitext(path)[0] + ".jpg"
+            out = out if out == path else unique_path(os.path.dirname(path),
+                                                      os.path.basename(out))
+            im.save(out, format="JPEG", quality=JPEG_QUALITY, optimize=False)
+        if out != path:
+            try:
+                os.remove(path)
+            except OSError:
+                pass
+        return out, new[0], new[1]
+    except Exception as exc:
+        print(f"[{TAG}] could not shrink {os.path.basename(path)}: {exc!r}",
+              flush=True)
+        return path, 0, 0

plan.py

@@ -0,0 +1,296 @@
+"""Shot-plan schema for H3 Ref Chain.
+
+A plan is the authored script for one chain: an ordered list of shots, one per
+hop. It is carried as a single JSON string so the whole plan lives in one widget
+and serializes with the workflow -- the DOM editor renders cards from this and
+writes back to the same string, so the JSON stays the source of truth whether it
+was typed by hand or clicked together.
+
+The shot count IS the hop count. There is no separate `chains` number to keep in
+sync, which removes a whole class of "3 blocks but chains=4" mismatches.
+
+Shot fields (all optional except `beat`):
+    beat        what happens this hop
+    directives  {join, camera, framing, pace, tail} -- see directives.VOCAB
+    prose       free text appended verbatim, for anything the vocabulary lacks
+    seed        int override, else the chain seed
+    steps       int override
+    duration    str override, e.g. "8 s"
+    locked      bool -- reuse this hop's cached render (hop store, step 4)
+    id          stable identifier, generated if absent
+"""
+
+import json
+
+from . import directives as _d
+
+TAG = "HandTieClips"
+
+# No "refs" here. A shot never activated a reference: activation is the ref's
+# own `shots` list in refs.py. The field was parsed, normalised and printed but
+# read by nothing -- and the editor neither loads nor writes it, so a
+# hand-authored shot_plan lost it the first time anyone touched a card. Leaving
+# it out means _norm_shot's unknown-field error names it and points at `shots`.
+_SHOT_KEYS = {"id", "beat", "directives", "prose",
+              "seed", "steps", "duration", "locked"}
+
+
+def _norm_shot(raw, i):
+    where = f"shot {i + 1}: "
+    if isinstance(raw, str):
+        raw = {"beat": raw}
+    if not isinstance(raw, dict):
+        raise ValueError(f"{TAG}: {where}each shot must be an object or a string")
+
+    unknown = set(raw) - _SHOT_KEYS
+    if unknown:
+        raise ValueError(
+            f"{TAG}: {where}unknown field(s) {sorted(unknown)}. "
+            f"Valid: {sorted(_SHOT_KEYS)}"
+        )
+
+    d_raw = raw.get("directives") or {}
+    if not isinstance(d_raw, dict):
+        raise ValueError(f"{TAG}: {where}directives must be an object")
+    bad = set(d_raw) - set(_d.AXES)
+    if bad:
+        raise ValueError(
+            f"{TAG}: {where}unknown directive axis/axes {sorted(bad)}. "
+            f"Valid: {list(_d.AXES)}"
+        )
+    dirs = {ax: _d.validate(ax, d_raw.get(ax), where=where) for ax in _d.AXES}
+    dirs = {k: v for k, v in dirs.items() if v}
+
+    def _int(name):
+        v = raw.get(name)
+        if v in (None, ""):
+            return None
+        try:
+            return int(v)
+        except (TypeError, ValueError):
+            raise ValueError(f"{TAG}: {where}{name} must be a whole number, got {v!r}")
+
+    return {
+        "id": str(raw.get("id") or f"s{i + 1}"),
+        "beat": str(raw.get("beat") or "").strip(),
+        "directives": dirs,
+        "prose": str(raw.get("prose") or "").strip(),
+        "seed": _int("seed"),
+        "steps": _int("steps"),
+        "duration": (str(raw["duration"]).strip() or None) if raw.get("duration") else None,
+        "locked": bool(raw.get("locked")),
+    }
+
+
+def parse_plan(text):
+    """Parse a shot-plan JSON string. Blank -> [] (caller falls back to `prompt`)."""
+    text = (text or "").strip()
+    if not text:
+        return []
+    try:
+        data = json.loads(text)
+    except json.JSONDecodeError as e:
+        raise ValueError(f"{TAG}: shot_plan does not parse as JSON ({e})") from e
+
+    if isinstance(data, dict):
+        shots = data.get("shots")
+        if shots is None:
+            raise ValueError(f'{TAG}: shot_plan object needs a "shots" array')
+    elif isinstance(data, list):
+        shots = data
+    else:
+        raise ValueError(f'{TAG}: shot_plan must be an object with "shots", or an array')
+
+    if not isinstance(shots, list) or not shots:
+        raise ValueError(f"{TAG}: shot_plan has no shots")
+
+    out = [_norm_shot(s, i) for i, s in enumerate(shots)]
+    if not any(s["beat"] or s["prose"] for s in out):
+        raise ValueError(f"{TAG}: shot_plan has no beat text in any shot")
+    return out
+
+
+def check_coherence(shots):
+    """Warn (never raise) about directive combinations that fight each other.
+
+    A framing change asks the audience to be somewhere new. With a moving camera
+    the move earns it; with a held camera the only way to get there is a cut, so
+    `join=continuous` and the framing change are asking for opposite things and
+    the model will pick one. Warn rather than raise -- it is a legitimate thing
+    to want, it just rarely reads as continuous.
+
+    Also warns when the camera move and the framing point opposite ways
+    (push_in + wide, pull_back + close), which is a contradiction regardless of
+    how the hop joins.
+    """
+    warnings = []
+    # push_in narrows the frame, pull_back opens it. Asking for one and naming
+    # the opposite destination is a physical contradiction at any join value,
+    # and nothing warned about it before.
+    _opposed = {("push_in", "wide"), ("pull_back", "close")}
+    for i, s in enumerate(shots):
+        d = s.get("directives") or {}
+        framing = d.get("framing", "")
+        camera = d.get("camera", "")
+        # Hop 1 has no previous hop, and directive_prose does not emit `join`
+        # there, so a join warning on shot 1 points at a sentence that is never
+        # compiled. The JS mirror already skips index 0.
+        if (i > 0 and d.get("join") == "continuous"
+                and framing not in ("", "keep")
+                and camera in ("", "hold")):
+            warnings.append(
+                f"shot {i + 1}: join=continuous with framing={framing} and a held "
+                f"camera implies a cut. Use camera=push_in/pull_back/pan_follow to "
+                f"reach that framing on the move, or framing=keep."
+            )
+        if (camera, framing) in _opposed:
+            warnings.append(
+                f"shot {i + 1}: camera={camera} moves the opposite way from "
+                f"framing={framing}. Pick the framing the move actually lands on."
+            )
+    return warnings
+
+
+def check_place_handoff(shots, ref_plan=None):
+    """Warn when a hop changes location without the previous beat arriving there.
+
+    This is the failure that put the one visible cut in the 8x15 s anime chain:
+    shot 3 ended "ahead the trunks begin to thin toward open ground" and shot 4
+    opened "Across the flat moonlit stone of @arena_clearing the two of them
+    square off". Hop 4 was handed a live frame of a man among trees and a beat
+    asserting he was already standing on open stone. It held the forest for
+    3.25 s and then reset the scene -- a hard cut 78 frames into the hop, the
+    single largest frame-to-frame jump in 114 seconds of film.
+
+    Nothing warned. `check_coherence` sees only directives, and the plan was
+    clean by every other check the pack has.
+
+    The rule the warning encodes: a beat must be true from ANY plausible ending
+    of the hop before it. When shot N names a place tag that shot N-1 never
+    mentions, shot N-1 has to do the arriving, or the model has to cut.
+
+    Two shapes are accepted as an arrival, because both work in practice:
+    shot N-1 naming the new place tag itself, or shot N's own beat carrying the
+    journey ("reaches the top of the stairs and pushes open the door"), which is
+    satisfiable from a live frame that is still on the stairs.
+
+    `ref_plan` is the parsed dict from refs.parse_ref_plan. Without it there is
+    no way to tell a place tag from a face tag, so the check no-ops.
+    """
+    warnings = []
+    if not ref_plan or len(shots) < 2:
+        return warnings
+    # A ref with no subject is a place plate. Faces ride people, not rooms.
+    places = {r["tag"] for r in (ref_plan.get("refs") or []) if not r.get("subject")}
+    if not places:
+        return warnings
+
+    # Phrases that mean the beat itself carries the journey, so it is
+    # satisfiable from a live frame still in the old location. The pack's own
+    # Showcase is the case to keep clean: shot 5 leaves her at a window in the
+    # hallway and shot 6 reads "She walks back along the hallway and through
+    # the doorway to the counter in @kitchen" -- the travelling is right there
+    # in the beat, and warning about it would be noise.
+    #
+    # Kept as travel language rather than a list of rooms: what makes a beat
+    # safe is that it starts where the last hop ended and moves, not which
+    # place it moves to.
+    _ARRIVES = (
+        "reach", "arriv", "enter", "emerg",
+        "step into", "steps into", "step through", "steps through",
+        "walk into", "walks into", "walk back", "walks back", "walking back",
+        "walk through", "walks through", "go back", "goes back",
+        "return", "returns", "returning", "head back", "heads back",
+        "head toward", "heads toward", "back along", "back through",
+        "push open", "pushes open", "through the door", "through the doorway",
+        "through the gate", "through the entrance", "across into",
+        "come out", "comes out", "break out", "breaks out",
+        "cross into", "crosses into", "climb", "climbs", "descend", "descends",
+        "makes her way", "makes his way", "makes their way",
+    )
+
+    for i in range(1, len(shots)):
+        prev = (shots[i - 1].get("beat") or "").lower()
+        here = shots[i].get("beat") or ""
+        low = here.lower()
+        new_places = [t for t in places
+                      if ("@" + t).lower() in low and ("@" + t).lower() not in prev]
+        for tag in sorted(new_places):
+            if any(v in low for v in _ARRIVES):
+                continue
+            warnings.append(
+                f"shot {i + 1}: @{tag} is a new place and shot {i} never goes there. "
+                f"The hop opens on a live frame of the old location, so the only way "
+                f"to obey is a cut. End shot {i} with the arrival, or have shot "
+                f"{i + 1} do the travelling."
+            )
+
+    # The same defect seen from the other side. Both LM Studio models plated
+    # the opening location, moved the story somewhere else, and gave the new
+    # place no plate at all -- then justified it with a rule that does not
+    # exist ("to avoid conflicting with the frame pin of the new space"). In
+    # the lighthouse plan that left the lamp room, the main setting of four of
+    # six hops, carried by beat text alone.
+    #
+    # The test is ABANDONMENT, not gaps. A plan is free to leave a transitional
+    # space unplated and come back: the pack's own Showcase plates the kitchen
+    # on shots 1-3, walks her down an unplated hallway for 4-5, and returns the
+    # plate on 6. What is always wrong is plating the opening and then letting
+    # the plan END with no plate riding, because that is the destination -- the
+    # place the film spends its last hops in -- with nothing holding it.
+    #
+    # A plan with no place plates at all is a legitimate shape and says nothing
+    # here: the Starter ships that way so it runs before any pictures exist.
+    covered = set()
+    for r in (ref_plan.get("refs") or []):
+        if r.get("subject"):
+            continue
+        covered |= set(r.get("shots") or range(1, len(shots) + 1))
+    n = len(shots)
+    if covered and n not in covered:
+        first_bare = n
+        while first_bare - 1 >= 1 and (first_bare - 1) not in covered:
+            first_bare -= 1
+        span = (f"shot {first_bare}" if first_bare == n
+                else f"shots {first_bare}-{n}")
+        warnings.append(
+            f"{span}: the plan's place plates stop riding and never resume, so "
+            f"the film ends somewhere no picture describes. A location "
+            f"introduced part way through needs its own plate on the hop it "
+            f"arrives and every hop after -- tightening a plate to its own "
+            f"shots does not mean the next location goes without one."
+        )
+    return warnings
+
+
+def compile_blocks(shots, establish=None, ref_plan=None):
+    """Compile a plan into one body string per hop, ready for the chain loop."""
+    for w in check_coherence(shots):
+        print(f"[{TAG}] note: {w}", flush=True)
+    for w in check_place_handoff(shots, ref_plan):
+        print(f"[{TAG}] note: {w}", flush=True)
+    return [_d.compile_shot(s, i, establish) for i, s in enumerate(shots)]
+
+
+def describe(shots):
+    """One-line-per-shot summary for the console, so the plan is auditable."""
+    rows = []
+    for i, s in enumerate(shots):
+        bits = [f"{k}={v}" for k, v in s["directives"].items()]
+        extra = []
+        if s["seed"] is not None:
+            extra.append(f"seed={s['seed']}")
+        if s["steps"] is not None:
+            extra.append(f"steps={s['steps']}")
+        if s["duration"]:
+            extra.append(f"duration={s['duration']}")
+        if s["locked"]:
+            extra.append("locked")
+        beat = (s["beat"] or "").replace(chr(10), " ")
+        if len(beat) > 60:
+            beat = beat[:57] + "..."
+        rows.append(
+            f"  shot {i + 1} [{s['id']}] {' '.join(bits + extra) or '(no directives)'}"
+            + chr(10) + f"      beat: {beat or '(continues)'}"
+        )
+    return chr(10).join(rows)

preview_node.py

@@ -0,0 +1,127 @@
+"""H3 Chain Preview -- the chain's progress panel, as its own node.
+
+Split off `HandTieClips` deliberately. That node already carries a 21-widget shot
+editor and a reference rail; folding a large media panel onto it as well makes
+an unreadable node, and the panel wants to be somewhere else in the graph
+anyway -- on the IMAGE wire, right before CreateVideo, where the thing being
+previewed actually flows.
+
+It is a passthrough: images and audio go straight out again, unchanged, so
+dropping it into an existing chain costs nothing and removing it changes no
+pixels. What it adds is a place for the live `h3_refchain_preview` events to
+land, and an end-of-run report of the two numbers the chain never surfaced --
+which pin mechanism each hop actually used, and how far the audio has drifted
+from the video.
+"""
+from __future__ import annotations
+
+try:
+    from server import PromptServer
+except Exception:  # noqa: BLE001 -- headless / API-only runs have no server
+    PromptServer = None
+
+TAG = "HTCChainPreview"
+FPS = 24
+
+
+def _send(payload):
+    if PromptServer is None:
+        return
+    try:
+        PromptServer.instance.send_sync(
+            "h3_chain_preview", payload, PromptServer.instance.client_id)
+    except Exception as e:  # noqa: BLE001
+        print(f"[{TAG}] preview send skipped: {e!r}", flush=True)
+
+
+class HTCChainPreview:
+    """Pass images and audio through, and report the join.
+
+    Wire between HandTieClips and CreateVideo.
+    """
+
+    @classmethod
+    def INPUT_TYPES(cls):
+        return {
+            "required": {
+                "images": ("IMAGE", {"tooltip": "From H3 Ref2VA Chain. Passed straight through."}),
+            },
+            "optional": {
+                "audio": ("AUDIO", {
+                    "tooltip": (
+                        "The chain's audio. Wire it and the panel reports A/V "
+                        "drift, which accumulates roughly 40 ms per hop from the "
+                        "audio crossfade at each join."
+                    ),
+                }),
+                "info": ("STRING", {
+                    "forceInput": True,
+                    "tooltip": "The chain's `info` output. Shown in the panel's detail view, never in the status strip.",
+                }),
+            },
+            "hidden": {"unique_id": "UNIQUE_ID"},
+        }
+
+    RETURN_TYPES = ("IMAGE", "AUDIO")
+    RETURN_NAMES = ("images", "audio")
+    FUNCTION = "run"
+    CATEGORY = "Hand Tie Clips"
+    OUTPUT_NODE = False
+    DESCRIPTION = (
+        "Preview panel for an H3 Ref2VA chain. Sits on the IMAGE wire before "
+        "CreateVideo and passes images and audio through untouched. Shows the "
+        "live sample, per-hop progress, which pin mechanism each hop used "
+        "(Motion-Context vs the AddGuide fallback), and end-of-run A/V drift."
+    )
+
+    def run(self, images, audio=None, info="", unique_id=None):
+        frames = int(images.shape[0]) if images is not None else 0
+        video_s = frames / float(FPS)
+        payload = {
+            "node_id": unique_id,
+            "frames": frames,
+            "video_s": round(video_s, 3),
+            "width": int(images.shape[2]) if frames else 0,
+            "height": int(images.shape[1]) if frames else 0,
+        }
+
+        if isinstance(audio, dict) and audio.get("waveform") is not None:
+            wav = audio["waveform"]
+            sr = int(audio.get("sample_rate") or 0)
+            if sr:
+                audio_s = float(wav.shape[-1]) / float(sr)
+                drift_ms = (audio_s - video_s) * 1000.0
+                payload["audio_s"] = round(audio_s, 3)
+                payload["sample_rate"] = sr
+                payload["drift_ms"] = round(drift_ms, 1)
+                # Worth a console line too: it is cumulative across a chain and
+                # nothing else in the pack reports it.
+                print(f"[{TAG}] {frames}f / {video_s:.2f}s video, "
+                      f"{audio_s:.2f}s audio, drift {drift_ms:+.0f} ms", flush=True)
+        if info:
+            payload["info"] = str(info)
+
+        _send(payload)
+        return (images, audio)
+
+
+
+
+# -- pre-rename ids ----------------------------------------------------------
+# A plain alias in NODE_CLASS_MAPPINGS keeps old workflows loading, but it also
+# lists the node a second time in search: ComfyUI falls back to the mapping key
+# when NODE_DISPLAY_NAME_MAPPINGS has no entry. Subclassing and setting
+# DEPRECATED gets both -- server.py publishes `deprecated: True`, and the
+# frontend's `Comfy.Node.ShowDeprecated` (off by default) hides it from search
+# while leaving it fully functional in workflows that name it.
+
+
+class _LegacyH3ChainPreview(HTCChainPreview):
+    DEPRECATED = True
+
+
+NODE_CLASS_MAPPINGS = {
+    "HTCChainPreview": HTCChainPreview,
+    "H3ChainPreview": _LegacyH3ChainPreview,
+}
+NODE_DISPLAY_NAME_MAPPINGS = {"HTCChainPreview": "H3 Chain Preview"}

prompt_pack/AUTHORING_PROMPT.md

@@ -0,0 +1,369 @@
+# Authoring prompt
+
+Paste everything between the rules below into any chat model, then describe your
+scene in plain language. It answers with two JSON blocks: paste the first into
+the **JSON** box under **SCRIPT** (`shot_plan`) and the second into the **JSON**
+box under **REFERENCES** (`ref_plan`). Each panel section has its own.
+
+The node validates everything it is given, so a model that gets this wrong is
+caught rather than obeyed. If a plan is rejected, paste the error back — every
+message names the shot or the reference it came from.
+
+---
+
+You are writing shot plans for **Hand Tie Clips**, a ComfyUI node that
+renders a multi-hop video-with-audio chain. Each hop is one continuous clip;
+consecutive hops are joined by pinning the previous hop's final frames and audio
+tail into the next hop's conditioning.
+
+You produce exactly two JSON documents: `shot_plan` and `ref_plan`.
+
+## How the renderer behaves
+
+These are not style preferences. They are how this model fails.
+
+1. **Sampling runs at cfg 1.0 with no negative branch, so the prompt is purely
+   additive.** Every concept named is added to the conditioning. Nothing can be
+   removed by mentioning it — "no cut" puts the word *cut* in front of the
+   encoder. **Never write a negation.** Write what the shot *is* doing.
+
+2. **Never name the thing you want to end.** "The cook stops talking" keeps her
+   talking. Write the state you want as **a pose plus a sound**: "leans back
+   against the counter with her lips closed, and lets her eyes move slowly
+   across the room. The kitchen is quiet apart from the low hum of the
+   refrigerator."
+
+   **The ban is on the idea, not on a list of words.** Two different models,
+   given a scene that ended *"the storm finally stops"*, avoided every banned
+   word below and still wrote *"The storm's roar begins to fade... raindrops
+   strike the glass with decreasing force"* and *"The storm has passed."* Both
+   name the ending. Both keep the storm. Fading, passing, waning, subsiding,
+   dying down, easing off, receding, growing quiet and dropping away are the
+   same move wearing different words, and every one of them adds the thing it
+   describes.
+
+   Test every sentence with one question: **is this a thing that is happening,
+   or a thing that has finished happening?** Only the first survives at cfg 1.0.
+   To end a storm, write the world that is left: *"Water runs down the glass in
+   slow threads. The mechanism turns with a low hum and the sea moves against
+   the rocks below."*
+
+   These words are rejected outright, in any beat: **no, not, never, n't,
+   without, none of, stop, stops, silent, silence.** They are the crudest
+   examples of the idea, not the whole of it -- a beat clean of all ten can
+   still break this rule, and usually does.
+
+3. **Audio is always generated.** Silence written as an absence produces speech,
+   because the model fills the track with the most likely thing. Silence must be
+   written **as a sound** — room tone, a refrigerator, a distant car.
+
+4. **Ambience must be narrowband and specific.** "faint street noise through the
+   window" is broadband and renders as a five-second hiss. "the low hum of the
+   refrigerator" renders as a refrigerator. When in doubt, name a single
+   discrete event: "a single click from the refrigerator, then stillness".
+
+5. **A state change belongs at the END of the previous shot.** Every hop opens
+   holding the frames it was handed, and the audio pin carries the previous
+   hop's tail across the join. If shot 2 ends mid-sentence, nothing you write in
+   shot 3 will make shot 3 start quiet. To be silent, still, or elsewhere in a
+   shot, arrive there before the previous shot ends.
+
+6. **A hop that ends on dialogue keeps talking into the next hop.** The audio
+   pin carries the previous hop's tail, so speech at the end of hop N becomes
+   the opening of hop N+1 and propagates down the whole chain. Land each spoken
+   line in the MIDDLE of its hop and leave a non-verbal action running into the
+   seam — slicing, walking, a hand on a doorframe. Give every hop with no
+   dialogue its own narrowband sound bed (footsteps, a refrigerator, rain on
+   glass), or the audio has nowhere to go but back to speech.
+
+7. **A beat must be true from any plausible ending of the hop before it.** A
+   hop routinely over-delivers -- given a movement it finishes it, and then some.
+   If the next beat instructs something its own opening frames have already done,
+   the only way to obey is to reset the scene, which reads as a hard cut about a
+   second and a half *into* the hop rather than at the seam. Give one hop the
+   whole of one movement, and write the next beat so it holds whether the
+   previous hop stopped short or ran ahead.
+
+8. **A walk between two different rooms is `match_cut`, not `continuous`.**
+   Asking for one unbroken take across a real location change makes the model
+   morph one room into the other mid-movement.
+
+9. **Shot 1 establishes everything. Every later shot carries ONLY the new
+   beat.** Never re-describe the face, the clothes or the room after shot 1 —
+   the reference photographs, the register and the frame pin already carry all
+   three, and repeating them competes with the pin instead of reinforcing it.
+
+10. **Write `@tags` into the action line.** Describing a reference in the register
+   does not make the model use it; the beat is what drives the frame. Write
+   "stands at the counter in @kitchen", not merely a `@kitchen` entry in the
+   register. Phrase a place as a place that is depicted, not as a container to
+   be placed inside. **A beat is plain prose.** A tag written inside a beat
+   carries no backticks, asterisks or other markdown -- every character you
+   write reaches the encoder literally, so formatting becomes noise in the
+   conditioning.
+
+11. **Every object that persists gets an adjective.** A bare noun is
+   unanchored: each hop encodes "the bowl" from scratch and is free to make it
+   steel in one hop and porcelain in the next. Name a colour or a material the
+   first time and repeat it every time -- "the white porcelain bowl", "the dark
+   blue wrapped hilt". State it in the subject's `context` as a **property**,
+   never as a location.
+
+12. **Name the visual style in shot 1, once.** Nothing else states it. If the
+   user asks for 2D anime, film noir, stop motion, watercolour or any look other
+   than live action, shot 1's beat opens with it: "Hand-drawn 2D anime in the
+   style of ..., crisp inked linework over painted backgrounds." Reference
+   pictures pull the look one way and unstated text pulls it back toward
+   photoreal video, and the text wins often enough to matter. Later shots do not
+   repeat it -- it belongs in `setting.locked` on the H3 Continuity State node,
+   which rides every hop from 2 on.
+
+   The node prepends an establishing line of its own to hop 1, and its default
+   asserts live action. When shot 1 opens by naming a medium, that default is
+   dropped automatically, so a styled plan needs nothing else from you. Name the
+   medium in the **first sentence** of shot 1 for that to happen.
+
+13. **Set `tail` on the final shot** to `settle` or `hold`. Left at its default
+   `ongoing`, the model is told action is still underway at the last frame and
+   will invent something to satisfy that — a stray gesture, or a stray line of
+   dialogue in the closing second.
+
+## `shot_plan`
+
+One shot per hop. **The number of shots is the number of hops.**
+
+```json
+{
+  "shots": [
+    {
+      "id": "s1",
+      "beat": "...",
+      "directives": {"camera": "hold", "framing": "medium", "pace": "steady", "tail": "ongoing"}
+    }
+  ]
+}
+```
+
+Valid shot fields, and no others: `id`, `beat`, `directives`, `prose`, `seed`,
+`steps`, `duration`, `locked`. Only `beat` is required. An unknown field is a
+hard error.
+
+Directive axes, and no others. Every axis is optional; an unset axis emits
+nothing at all, which costs no tokens.
+
+| axis | values |
+|---|---|
+| `join` | `continuous`, `match_cut`, `hard_cut` — **omit on shot 1**, which has nothing to join to |
+| `camera` | `hold`, `pan_follow`, `push_in`, `pull_back`, `orbit`, `handheld` |
+| `framing` | `keep`, `wide`, `medium`, `close` |
+| `pace` | `slow`, `steady`, `brisk` |
+| `tail` | `ongoing` (default), `settle`, `hold` |
+
+Two combinations are contradictions and will be flagged:
+
+- `join: continuous` + a framing change + `camera: hold`. With the camera still,
+  the only way to reach a new framing is a cut. Earn it on the move (`push_in`,
+  `pull_back`, `pan_follow`) or use `framing: keep`.
+- `push_in` with `wide`, or `pull_back` with `close`. The move points the
+  opposite way from the destination.
+
+`duration` may override the chain per shot, using exactly these labels:
+`"5 s"`, `"7 s"`, `"8 s"`, `"10 s"`, `"15 s"`.
+
+### How long a beat has to be
+
+A beat has to fill its whole hop. Written short, the model finishes the action
+early and invents something for the seconds left over -- most often a cut to the
+reference photograph in the closing moments. **Ask the user how long each hop is
+if they have not said**, and size every beat to it.
+
+**Count the words in each beat before you answer, and write the count down.**
+This is the instruction most often ignored, and ignoring it is not a small
+miss. Two different models asked for six 15 s hops both returned beats averaging
+**54 words** -- every single beat under the floor -- and the same two models,
+asked for much shorter hops, returned 40 to 48. Left to itself a model writes
+about fifty words whatever the hop length. Fifty words is right for a 7 s hop
+and is half of what 15 s needs. The table below is not a style note; it is the
+one part of this document you have to do arithmetic for.
+
+| hop | words in the beat |
+|---|---|
+| `5 s` | 30-45 |
+| `7 s` | 30-55 |
+| `8 s` | 35-60 |
+| `10 s` | 45-75 |
+| `15 s` | 70-100 |
+
+A worked `15 s` beat, at 74 words, from a rendered eight-hop chain:
+
+> They close the distance together and the blades meet at the centre of the clearing, white sparks bursting from the impact as the camera orbits around the lock. @warrior_face turns the heavier blade aside and cuts back across the body; @enemy_shadow catches it on the flat and steps in behind it. Steel rings sharp and resonant on every contact, armour plates grind against one another, and boots drag hard over stone between the exchanges.
+
+Read how the length is spent, because padding to a word count fails differently
+but just as badly. One continuous movement carries the whole hop -- they close,
+the blades meet, one turns the other aside, the other steps in. The camera move
+is named inside the action rather than after it. The last third is the sound bed
+and nothing else: three specific noises, each tied to a thing on screen. There
+is no second event and no scene change.
+
+The `5 s` and `7 s` rows are the measured spread of the two plans that ship with
+the node. Their thinnest beat is 28 words in a 7 s hop, carrying one simple
+action; their fullest is 56. The `15 s` row now has one measurement behind it --
+the chain the example above comes from ran 74 to 90 words a beat across eight
+hops and every hop delivered its beat in full, with no hop idling into the
+reference. **The `8 s` and `10 s` rows are still interpolated, not measured.**
+If the closing seconds drift or cut to the reference photograph, the beat was
+short.
+
+Fill that length with *continuous* material -- one movement that takes the whole
+hop, what the camera is doing while it happens, and the sound bed underneath --
+rather than with more separate events. Four events crammed into one hop is the
+over-delivery in rule 7, and it costs you the next hop's opening.
+
+### Dialogue
+
+Put the spoken line inside the beat, in **single** quotes:
+
+```
+@hero_face looks up from the chopping board and says, 'You are early. I have
+barely started.'
+```
+
+Single quotes survive copy-paste; escaped double quotes are the most common
+cause of a rejected plan. Budget roughly one line of dialogue per 5–7 seconds of
+hop — a long speech in a short hop is truncated mid-word, and that truncation is
+then pinned into the next hop's audio.
+
+## `ref_plan`
+
+```json
+{
+  "refs": [
+    {"tag": "hero_face", "file": "face.jpg", "subject": 1,
+     "retention": "fully_preserved", "shots": [1, 4],
+     "desc": "head-and-shoulders, even light"}
+  ],
+  "subjects": {
+    "1": {"name": "the cook",
+          "locked": "the same face, the same short dark hair",
+          "context": "the apron stays tied over the grey t-shirt"}
+  }
+}
+```
+
+Valid ref fields: `tag`, `file`, `subject`, `retention`, `desc`, `shots`. (There
+is also `slot`, which is derived from list position — never author it.)
+
+- **`tag`** is required, unique, `[A-Za-z0-9_]+`, and is what appears in beats
+  as `@tag`.
+- **`file`** is a bare filename in `ComfyUI/input/h3_refs`, never a path. A
+  filename that is not in that folder **stops the run** -- it is an error, not a
+  warning, so a placeholder you invent must be one the user then actually
+  supplies. If the user has not told you their filenames, use clear placeholders
+  and list every one of them at the end of your answer, with what each picture
+  should show.
+- **`subject`** is an integer ≥ 1 grouping pictures **of the same person**.
+  Declaring two different people under one subject number makes the model render
+  **the average of their faces**. One number per person, always.
+- **`retention`** is one of:
+  - `fully_preserved` — face, bone structure and hairstyle carry over exactly
+  - `partially_copy` — the garment and its cut carry over
+  - `reference` — layout, surfaces and light carry over, i.e. a place
+
+  It defaults to `fully_preserved` when `subject` is set, `reference` otherwise.
+- **`shots`** is the list of 1-based hops the picture rides on.
+
+Every subject that appears in `subjects` must be claimed by at least one ref, or
+the plan is rejected. Give every subject a **`locked`**: pictures put a face in
+front of the encoder, but `locked` is what carries the identity across a hop
+where the picture is absent. At most **9 references in the whole plan** -- the limit counts entries in
+`refs`, not pictures per hop.
+
+### Scheduling references is the part that decides whether continuity holds
+
+Write `@tag` for a person on any hop you like. Hop 1 resolves it to
+`<Subject N>` against its definitions block; hop 2 onward resolves it to the
+subject's `name`, which binds to the identity sentence every continuation hop
+carries. **Every subject therefore needs a `name`.**
+
+**A reference with no `shots` list rides hop 1 only.** That default is right
+for a **place** plate: a room still riding a hop set somewhere else beats the
+frame pin, because the model has a crisp picture of one room and a noisy
+carried-over frame of another, and it follows the still. **List every hop a
+picture belongs on, explicitly.**
+
+**A face plate is the opposite. Put it on every hop.** Two six-hop renders
+settled this. A face plate rode a hop set in a space it had never seen and held
+cleanly; the hop scheduled with no references came back a different person, and
+nothing after it recovered. Identity drift does not self-correct. `locked` holds
+a face that is still right; only a plate rebuilds one that is gone.
+
+- Put every **face** reference on every hop: `"shots": [1, 2, 3, 4, 5, 6]`.
+- Keep a **place** reference on every hop set in that place, and off every hop
+  that is not.
+- An **outfit** plate can ride hop 1 only, but then `context` is the only thing
+  holding the wardrobe from hop 2 on, so name its colours there.
+- Never let a place plate shot in one location ride a hop set somewhere else.
+- **The hop that changes location belongs entirely to the new place.** Put the
+  departure at the end of the *previous* beat, so that no place plate ever rides
+  a hop which opens somewhere it was not photographed.
+- **A location introduced part way through needs its own plate, on the hop it
+  arrives and every hop after.** Tightening a place plate to its own shots does
+  **not** mean the next location goes without one. This is the most common
+  mistake made on this rule: two models both plated the opening location, moved
+  the story to a second one, gave that second one no plate at all, and wrote a
+  confident justification for it. In one case that left the film's main setting
+  -- four of six hops -- held by beat text alone. Ask for the extra picture. If
+  the plan ends somewhere no picture describes, the plan is wrong.
+
+## What to produce
+
+1. A one-paragraph plan in prose: how many hops, what each covers, where the
+   references sit and why.
+2. ```json ``` block — the `shot_plan`.
+3. ```json ``` block — the `ref_plan`.
+4. A short list of any pictures the user still needs to supply, with the
+   filename you used for each and what the picture should show.
+
+Before you answer, check every one of these:
+
+- [ ] Shot count matches the hop count the user asked for.
+- [ ] Every beat's word count has been counted, written down, and falls inside
+      the band for its hop length. A 15 s hop needs 70-100 words; fifty is
+      what comes out when this check is skipped.
+- [ ] No shot contains a negation anywhere.
+- [ ] No beat contains any of: no, not, never, n't, without, none of, stop,
+      stops, silent, silence.
+- [ ] No beat describes a thing that has finished happening -- nothing fades,
+      passes, wanes, subsides, dies down, eases off, recedes or grows quiet.
+      Passing this check is not the same as passing the one above it.
+- [ ] No beat contains backticks, asterisks or any other markdown. Beats are
+      plain prose; a tag inside a beat is written bare, as @tag.
+- [ ] No shot names an action ending; endings are written as a pose plus a sound.
+- [ ] Any quiet moment names a specific narrowband sound.
+- [ ] No hop ends on a spoken line; every dialogue-free hop names a sound of its own.
+- [ ] Any hop that changes location joins on `match_cut` or `hard_cut`, not `continuous`.
+- [ ] Every state change lands at the end of the shot *before* the one that
+      needs it.
+- [ ] Shot 1 establishes; no later shot re-describes face, clothes or room.
+- [ ] Shot 1 names the visual style, if the user asked for anything other
+      than live action.
+- [ ] Every persistent object and garment carries an adjective, in the beat
+      and again in `context`.
+- [ ] Each beat holds true whether the hop before it stopped short or ran
+      ahead of its beat.
+- [ ] Every `@tag` used in a beat exists in `ref_plan`, spelled identically.
+- [ ] Every `@tag` used on hop N has that N in its ref's `shots` list.
+- [ ] Every location the film visits has a place plate covering the hops set
+      there, including any location introduced after hop 1. The final hop is
+      covered by one.
+- [ ] `join` is absent from shot 1.
+- [ ] The final shot sets `tail` to `settle` or `hold`.
+- [ ] Compare each shot's `framing` with the previous shot's: where it
+      changes on `join: continuous`, the camera is moving, not `hold`. And no
+      `push_in`+`wide`, no `pull_back`+`close`.
+- [ ] Every subject in `subjects` is claimed by a ref, and has both a `name`
+      and a `locked`.
+- [ ] `refs` holds at most 9 entries in total.
+- [ ] Dialogue uses single quotes.
+- [ ] Both blocks are valid JSON: no trailing commas, no comments, no smart
+      quotes, plain ASCII, and no field outside the lists above.

prompt_pack/EXAMPLE_6_HOP.md

@@ -0,0 +1,157 @@
+# Worked example: six hops, three pictures
+
+This is the plan inside `workflows/HandTieClips_Showcase.json`, reproduced here so
+it can be shown to a model as an example of the shape and the reasoning. It is
+generated from that workflow, so the two cannot drift apart.
+
+The scene: a cook in a kitchen speaks a line, crosses the room, leaves through a
+doorway into a hallway the register has no picture of, speaks again there, and
+comes back.
+
+## What each hop is for
+
+| hop | id | references active |
+|---|---|---|
+| 1 | s1 | @hero_face, @hero_outfit, @kitchen |
+| 2 | s2 | @kitchen |
+| 3 | s3 | @kitchen |
+| 4 | s4 | @hero_face |
+| 5 | s5 | **none** |
+| 6 | s6 | @kitchen |
+
+Three things in that table are the whole point:
+
+- **Hop 3** carries the kitchen while she is leaving it, and hop 4 does not.
+  The hallway is a space no reference describes, so the model must invent it —
+  and a kitchen plate riding hop 4 would drag her back into the kitchen.
+- **Hop 4** re-asserts the face. Entering an unseen space is where identity
+  drift starts, and re-asserting there is cheaper than recovering on 5 and 6.
+- **Hop 5 has no references at all.** Identity, wardrobe and voice ride on the
+  frame pin plus `subjects.1.locked` and `.context` alone. If she is still the
+  same person in the same apron with the same voice, the register works.
+
+Note also that the dialogue lands on hops 1 and 5 — the establishing shot and
+the one with no pictures — and that both use single quotes.
+
+## shot_plan
+
+```json
+{
+  "shots": [
+    {
+      "id": "s1",
+      "beat": "@hero_face stands at the counter in @kitchen, an apron over a grey t-shirt. She looks up from the chopping board and says, 'You are early. I have barely started.' She turns back to the board and goes on slicing, the knife tapping steadily against the wood.",
+      "directives": {
+        "camera": "hold",
+        "framing": "medium",
+        "pace": "steady",
+        "tail": "ongoing"
+      }
+    },
+    {
+      "id": "s2",
+      "beat": "She sets the knife down and walks the length of the counter to the window of @kitchen, looking out at the street. Her steps are soft on the tiles and the refrigerator hums behind her.",
+      "directives": {
+        "join": "continuous",
+        "camera": "pan_follow",
+        "framing": "medium",
+        "pace": "steady",
+        "tail": "ongoing"
+      }
+    },
+    {
+      "id": "s3",
+      "beat": "She turns from the window, crosses @kitchen and pushes through the doorway into the hallway beyond, the room falling away behind her. Her footsteps carry on the tiles.",
+      "directives": {
+        "join": "continuous",
+        "camera": "pan_follow",
+        "framing": "wide",
+        "pace": "brisk",
+        "tail": "ongoing"
+      }
+    },
+    {
+      "id": "s4",
+      "beat": "@hero_face walks down a narrow hallway hung with coats, one hand trailing along the wall, her footsteps muffled on the runner. None of the kitchen is visible.",
+      "directives": {
+        "join": "continuous",
+        "camera": "handheld",
+        "framing": "medium",
+        "pace": "steady",
+        "tail": "ongoing"
+      }
+    },
+    {
+      "id": "s5",
+      "beat": "She stops at the window at the end of the hall, half turns back over her shoulder and says, 'It is still raining. We will have to do it inside.' She looks back out at the glass with her lips closed, and the rain taps steadily on the pane.",
+      "directives": {
+        "join": "continuous",
+        "camera": "push_in",
+        "framing": "close",
+        "pace": "slow",
+        "tail": "settle"
+      }
+    },
+    {
+      "id": "s6",
+      "beat": "She walks back along the hallway and through the doorway to the counter in @kitchen, picking the knife up again. The refrigerator hums and the knife starts on the board.",
+      "directives": {
+        "join": "match_cut",
+        "camera": "pull_back",
+        "framing": "wide",
+        "pace": "steady",
+        "tail": "hold"
+      }
+    }
+  ]
+}
+```
+
+## ref_plan
+
+```json
+{
+  "refs": [
+    {
+      "tag": "hero_face",
+      "file": "ref_face.jpg",
+      "subject": 1,
+      "retention": "fully_preserved",
+      "shots": [
+        1,
+        4
+      ],
+      "desc": "head-and-shoulders photograph of the cook, even light"
+    },
+    {
+      "tag": "hero_outfit",
+      "file": "ref_outfit.jpg",
+      "subject": 1,
+      "retention": "partially_copy",
+      "shots": [
+        1
+      ],
+      "desc": "full-length photograph of the same cook, apron over a grey t-shirt"
+    },
+    {
+      "tag": "kitchen",
+      "file": "ref_room.jpg",
+      "retention": "reference",
+      "shots": [
+        1,
+        2,
+        3,
+        6
+      ],
+      "desc": "the kitchen: counter, window, and the light coming through it"
+    }
+  ],
+  "subjects": {
+    "1": {
+      "name": "the cook",
+      "locked": "the same face, the same short dark hair, the same silver stud earrings",
+      "context": "the apron stays tied over the grey t-shirt"
+    }
+  }
+}
+```

prompt_pack/README.md

@@ -0,0 +1,71 @@
+# prompt_pack
+
+Everything needed to have a language model write plans for this node.
+
+| file | what it is |
+|---|---|
+| **`AUTHORING_PROMPT.md`** | Paste into any chat model, describe your scene, paste the two JSON blocks it returns into the node. Start here. |
+| **`EXAMPLE_6_HOP.md`** | A worked six-hop plan with the reasoning behind its reference schedule. Useful as a second message to the model when you want it to match a shape. |
+| **`SYSTEM_PROMPT.md`** | The same thing with the human preamble stripped, for pasting into a *System Prompt* box. Select all, paste, done. |
+| **`SCHEMA.json`** | JSON Schema for both documents, for anyone wiring this into their own tooling. Carries the rule set under `x-rules` and the duration/frame table under `x-duration-frames`. |
+
+## Using it in LM Studio (or any local chat app)
+
+1. Load a model and set its **context length to 16384 or more**. The system
+   prompt is ~4,700 tokens and the reply is another 1,000-2,000; a small window
+   truncates the rules and you get invented directive names.
+2. Open `SYSTEM_PROMPT.md`, select all, paste it into the **System Prompt** box
+   in LM Studio's right-hand sidebar. Nothing else goes in that box.
+3. Set **temperature 0.3-0.5**. Higher and the JSON starts growing trailing
+   commas and smart quotes.
+4. In the chat, describe your scene in plain language, and say **how many hops**
+   and **what pictures you have**:
+
+   > Six hops. A cook in a kitchen; she says one line, walks out into a hallway,
+   > waits by a window, then comes back. I have a face photo, a photo of her
+   > apron, and a photo of the kitchen.
+
+5. It answers with a paragraph of reasoning and two ```json``` blocks. Each
+   section of the panel has its own **JSON** disclosure at the bottom:
+   - the first block goes in the **JSON** box under **SCRIPT** (`shot_plan`);
+   - the second goes in the **JSON** box under **REFERENCES** (`ref_plan`).
+
+   Both parse as you type. Bad JSON leaves the cards and rows showing the last
+   good version and says so, rather than throwing your paste away.
+6. Put your pictures in `ComfyUI/input/h3_refs` under the filenames the model
+   used, or drop them onto the reference thumbnails and fix the names.
+7. Queue. **If the node rejects the plan, paste the error straight back into the
+   chat** — every message names the shot or reference it came from, and one
+   round trip usually fixes it.
+
+Want it to match a particular shape? Paste `EXAMPLE_6_HOP.md` as a second
+message before describing your scene.
+
+Small local models (7B-8B) hold the JSON schema fine but drift on the prose
+rules — they will write negations. Read the plan before queueing; a beat that
+says "she stops talking" costs you a render.
+
+`SCHEMA.json`, `EXAMPLE_6_HOP.md` and `SYSTEM_PROMPT.md` are **generated**, not
+written:
+
+```
+python tools/gen_schema.py           # regenerate the schema from the node
+python tools/gen_schema.py --check   # exit 1 if it is out of date
+python tools/gen_example.py          # regenerate the example from the workflow
+sed -n '14,$p' prompt_pack/AUTHORING_PROMPT.md \n    > prompt_pack/SYSTEM_PROMPT.md   # re-strip the preamble
+```
+
+Both read the installed node and the shipped workflow, so they cannot describe a
+vocabulary or a plan that does not exist. Run `gen_schema.py` with ComfyUI's
+interpreter — importing the node pulls in torch. Re-run both after changing
+`directives.VOCAB`, `refs.RETENTION`, the shot fields, or the duration table;
+`gen_schema.py` asserts against `plan._SHOT_KEYS`, `refs.REF_FIELDS` and
+`refs.SUBJECT_FIELDS` and will fail loudly rather than emit a stale schema.
+
+The node validates every plan it is handed, so a model that gets this wrong is
+caught rather than obeyed. Errors name the shot or the reference they came from
+— pasting one back to the model is usually enough to fix it.
+
+The prose guide for humans is [`../PROMPTING.md`](../PROMPTING.md), and the
+Starter workflow carries a condensed version of it as a card board on its own
+canvas — including the LM Studio recipe above.

prompt_pack/SCHEMA.json

@@ -0,0 +1,223 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "title": "H3 Ref Chain plans",
+  "description": "Two documents. `shot_plan` goes in the shot_plan widget, `ref_plan` in the ref_plan widget. Generated by tools/gen_schema.py from the installed node -- do not edit by hand.",
+  "type": "object",
+  "properties": {
+    "shot_plan": {
+      "type": "object",
+      "required": [
+        "shots"
+      ],
+      "additionalProperties": false,
+      "properties": {
+        "shots": {
+          "type": "array",
+          "minItems": 1,
+          "items": {
+            "type": "object",
+            "required": [
+              "beat"
+            ],
+            "additionalProperties": false,
+            "properties": {
+              "id": {
+                "type": "string",
+                "description": "Stable name. Generated if absent."
+              },
+              "beat": {
+                "type": "string",
+                "description": "What happens THIS hop. Shot 1 is the whole opening; every later shot is only the new beat."
+              },
+              "directives": {
+                "type": "object",
+                "additionalProperties": false,
+                "properties": {
+                  "join": {
+                    "type": "string",
+                    "enum": [
+                      "continuous",
+                      "hard_cut",
+                      "match_cut"
+                    ],
+                    "description": "continuous: The camera and the action carry straight on from the pinned frames in one unbroken take. | match_cut: The shot changes on a matched movement, the new framing picking up the same gesture already underway. | hard_cut: A clean cut opens a new setup, the same place a moment later."
+                  },
+                  "camera": {
+                    "type": "string",
+                    "enum": [
+                      "handheld",
+                      "hold",
+                      "orbit",
+                      "pan_follow",
+                      "pull_back",
+                      "push_in"
+                    ],
+                    "description": "hold: The camera holds its position throughout. | pan_follow: The camera pans smoothly to follow the movement, holding it in frame. | push_in: The camera pushes slowly in. | pull_back: The camera draws slowly back, opening the frame. | orbit: The camera arcs slowly around the action. | handheld: The camera carries a light handheld float."
+                  },
+                  "framing": {
+                    "type": "string",
+                    "enum": [
+                      "close",
+                      "keep",
+                      "medium",
+                      "wide"
+                    ],
+                    "description": "keep: The framing stays as it is. | wide: A wide shot with the full room in view. | medium: A medium shot from the waist up. | close: A close shot, head and shoulders filling the frame."
+                  },
+                  "pace": {
+                    "type": "string",
+                    "enum": [
+                      "brisk",
+                      "slow",
+                      "steady"
+                    ],
+                    "description": "slow: Everything moves at an unhurried pace. | steady: The action moves at a steady, even pace. | brisk: The action moves briskly."
+                  },
+                  "tail": {
+                    "type": "string",
+                    "enum": [
+                      "hold",
+                      "ongoing",
+                      "settle"
+                    ],
+                    "description": "ongoing: The action is still underway as the clip ends. | settle: The movement eases to a rest and stays there. | hold: The final position holds steady through the last moments.",
+                    "default": "ongoing"
+                  }
+                },
+                "description": "Compiled in the order join, camera, framing, pace, tail. `join` is ignored on shot 1."
+              },
+              "prose": {
+                "type": "string",
+                "description": "Appended verbatim, for anything the vocabulary lacks. Phrase it affirmatively."
+              },
+              "seed": {
+                "type": "integer"
+              },
+              "steps": {
+                "type": "integer"
+              },
+              "duration": {
+                "type": "string",
+                "enum": [
+                  "5 s",
+                  "7 s",
+                  "8 s",
+                  "10 s",
+                  "15 s"
+                ]
+              },
+              "locked": {
+                "type": "boolean",
+                "description": "Reuse this hop's cached render even when its inputs changed. Needs cache_hops=on."
+              }
+            }
+          },
+          "description": "One shot per hop. The shot count IS the hop count."
+        }
+      }
+    },
+    "ref_plan": {
+      "type": "object",
+      "required": [
+        "refs"
+      ],
+      "additionalProperties": false,
+      "properties": {
+        "refs": {
+          "type": "array",
+          "items": {
+            "type": "object",
+            "required": [
+              "tag"
+            ],
+            "additionalProperties": false,
+            "properties": {
+              "tag": {
+                "type": "string",
+                "pattern": "^[A-Za-z0-9_]+$",
+                "description": "Unique. Written into beats as @tag."
+              },
+              "file": {
+                "type": "string",
+                "description": "Basename under ComfyUI/input/h3_refs. Never a path."
+              },
+              "slot": {
+                "type": "integer",
+                "description": "Derived from list position. Do not author it; present only for legacy plans."
+              },
+              "subject": {
+                "type": "integer",
+                "minimum": 1,
+                "description": "Groups pictures OF THE SAME PERSON. Two different people under one number makes the model render the average of their faces."
+              },
+              "retention": {
+                "type": "string",
+                "enum": [
+                  "fully_preserved",
+                  "partially_copy",
+                  "reference"
+                ],
+                "description": "fully_preserved: face, bone structure, and hairstyle carry over exactly | partially_copy: the garment and its cut carry over, moving naturally with the body | reference: the layout, surfaces, and light carry over as the setting"
+              },
+              "desc": {
+                "type": "string"
+              },
+              "shots": {
+                "type": "array",
+                "items": {
+                  "type": "integer",
+                  "minimum": 1
+                },
+                "minItems": 1,
+                "description": "1-based hops this picture rides on. OMITTING IT MEANS HOP 1 ONLY on a continuation chain -- a plate shot elsewhere riding a later hop beats the frame pin."
+              }
+            }
+          },
+          "maxItems": 9,
+          "description": "At most 9 pictures on any one hop."
+        },
+        "subjects": {
+          "type": "object",
+          "patternProperties": {
+            "^[0-9]+$": {
+              "type": "object",
+              "additionalProperties": false,
+              "properties": {
+                "name": {
+                  "type": "string"
+                },
+                "locked": {
+                  "type": "string",
+                  "description": "What must not change. This is what survives on a hop where the photograph is absent."
+                },
+                "context": {
+                  "type": "string",
+                  "description": "Situational state that should persist -- wardrobe, what they are holding."
+                }
+              }
+            }
+          },
+          "additionalProperties": false,
+          "description": "Keyed by subject number, as a STRING. Every subject here must be claimed by at least one ref, or the plan is rejected."
+        }
+      }
+    }
+  },
+  "x-duration-frames": {
+    "5 s": 124,
+    "7 s": 175,
+    "8 s": 192,
+    "10 s": 243,
+    "15 s": 362
+  },
+  "x-rules": [
+    "cfg is 1.0 with no negative branch: the prompt is ADDITIVE. Anything named is added; nothing can be removed by mentioning it. Never write a negation.",
+    "Never name the thing you want to end. 'stops talking' keeps them talking. Write the state as a pose plus a sound.",
+    "H3 always generates audio. Silence must be written AS a sound -- room tone, a refrigerator, a single click.",
+    "Ambience must be narrowband. 'faint street noise' renders as hiss; 'the low hum of the refrigerator' renders as a refrigerator.",
+    "A state change belongs at the END of the previous shot. Every hop opens holding the frames it was handed.",
+    "Shot 1 establishes everything. Later shots carry ONLY the new beat -- never re-describe the face, the clothes or the room.",
+    "Write @tags into the action line. Describing a reference in the register does not make the model use it.",
+    "Set `tail` to settle or hold on the FINAL shot, or the model is told action is still underway at the last frame and invents something to satisfy it."
+  ]
+}

prompt_pack/SYSTEM_PROMPT.md

@@ -0,0 +1,356 @@
+You are writing shot plans for **Hand Tie Clips**, a ComfyUI node that
+renders a multi-hop video-with-audio chain. Each hop is one continuous clip;
+consecutive hops are joined by pinning the previous hop's final frames and audio
+tail into the next hop's conditioning.
+
+You produce exactly two JSON documents: `shot_plan` and `ref_plan`.
+
+## How the renderer behaves
+
+These are not style preferences. They are how this model fails.
+
+1. **Sampling runs at cfg 1.0 with no negative branch, so the prompt is purely
+   additive.** Every concept named is added to the conditioning. Nothing can be
+   removed by mentioning it — "no cut" puts the word *cut* in front of the
+   encoder. **Never write a negation.** Write what the shot *is* doing.
+
+2. **Never name the thing you want to end.** "The cook stops talking" keeps her
+   talking. Write the state you want as **a pose plus a sound**: "leans back
+   against the counter with her lips closed, and lets her eyes move slowly
+   across the room. The kitchen is quiet apart from the low hum of the
+   refrigerator."
+
+   **The ban is on the idea, not on a list of words.** Two different models,
+   given a scene that ended *"the storm finally stops"*, avoided every banned
+   word below and still wrote *"The storm's roar begins to fade... raindrops
+   strike the glass with decreasing force"* and *"The storm has passed."* Both
+   name the ending. Both keep the storm. Fading, passing, waning, subsiding,
+   dying down, easing off, receding, growing quiet and dropping away are the
+   same move wearing different words, and every one of them adds the thing it
+   describes.
+
+   Test every sentence with one question: **is this a thing that is happening,
+   or a thing that has finished happening?** Only the first survives at cfg 1.0.
+   To end a storm, write the world that is left: *"Water runs down the glass in
+   slow threads. The mechanism turns with a low hum and the sea moves against
+   the rocks below."*
+
+   These words are rejected outright, in any beat: **no, not, never, n't,
+   without, none of, stop, stops, silent, silence.** They are the crudest
+   examples of the idea, not the whole of it -- a beat clean of all ten can
+   still break this rule, and usually does.
+
+3. **Audio is always generated.** Silence written as an absence produces speech,
+   because the model fills the track with the most likely thing. Silence must be
+   written **as a sound** — room tone, a refrigerator, a distant car.
+
+4. **Ambience must be narrowband and specific.** "faint street noise through the
+   window" is broadband and renders as a five-second hiss. "the low hum of the
+   refrigerator" renders as a refrigerator. When in doubt, name a single
+   discrete event: "a single click from the refrigerator, then stillness".
+
+5. **A state change belongs at the END of the previous shot.** Every hop opens
+   holding the frames it was handed, and the audio pin carries the previous
+   hop's tail across the join. If shot 2 ends mid-sentence, nothing you write in
+   shot 3 will make shot 3 start quiet. To be silent, still, or elsewhere in a
+   shot, arrive there before the previous shot ends.
+
+6. **A hop that ends on dialogue keeps talking into the next hop.** The audio
+   pin carries the previous hop's tail, so speech at the end of hop N becomes
+   the opening of hop N+1 and propagates down the whole chain. Land each spoken
+   line in the MIDDLE of its hop and leave a non-verbal action running into the
+   seam — slicing, walking, a hand on a doorframe. Give every hop with no
+   dialogue its own narrowband sound bed (footsteps, a refrigerator, rain on
+   glass), or the audio has nowhere to go but back to speech.
+
+7. **A beat must be true from any plausible ending of the hop before it.** A
+   hop routinely over-delivers -- given a movement it finishes it, and then some.
+   If the next beat instructs something its own opening frames have already done,
+   the only way to obey is to reset the scene, which reads as a hard cut about a
+   second and a half *into* the hop rather than at the seam. Give one hop the
+   whole of one movement, and write the next beat so it holds whether the
+   previous hop stopped short or ran ahead.
+
+8. **A walk between two different rooms is `match_cut`, not `continuous`.**
+   Asking for one unbroken take across a real location change makes the model
+   morph one room into the other mid-movement.
+
+9. **Shot 1 establishes everything. Every later shot carries ONLY the new
+   beat.** Never re-describe the face, the clothes or the room after shot 1 —
+   the reference photographs, the register and the frame pin already carry all
+   three, and repeating them competes with the pin instead of reinforcing it.
+
+10. **Write `@tags` into the action line.** Describing a reference in the register
+   does not make the model use it; the beat is what drives the frame. Write
+   "stands at the counter in @kitchen", not merely a `@kitchen` entry in the
+   register. Phrase a place as a place that is depicted, not as a container to
+   be placed inside. **A beat is plain prose.** A tag written inside a beat
+   carries no backticks, asterisks or other markdown -- every character you
+   write reaches the encoder literally, so formatting becomes noise in the
+   conditioning.
+
+11. **Every object that persists gets an adjective.** A bare noun is
+   unanchored: each hop encodes "the bowl" from scratch and is free to make it
+   steel in one hop and porcelain in the next. Name a colour or a material the
+   first time and repeat it every time -- "the white porcelain bowl", "the dark
+   blue wrapped hilt". State it in the subject's `context` as a **property**,
+   never as a location.
+
+12. **Name the visual style in shot 1, once.** Nothing else states it. If the
+   user asks for 2D anime, film noir, stop motion, watercolour or any look other
+   than live action, shot 1's beat opens with it: "Hand-drawn 2D anime in the
+   style of ..., crisp inked linework over painted backgrounds." Reference
+   pictures pull the look one way and unstated text pulls it back toward
+   photoreal video, and the text wins often enough to matter. Later shots do not
+   repeat it -- it belongs in `setting.locked` on the H3 Continuity State node,
+   which rides every hop from 2 on.
+
+   The node prepends an establishing line of its own to hop 1, and its default
+   asserts live action. When shot 1 opens by naming a medium, that default is
+   dropped automatically, so a styled plan needs nothing else from you. Name the
+   medium in the **first sentence** of shot 1 for that to happen.
+
+13. **Set `tail` on the final shot** to `settle` or `hold`. Left at its default
+   `ongoing`, the model is told action is still underway at the last frame and
+   will invent something to satisfy that — a stray gesture, or a stray line of
+   dialogue in the closing second.
+
+## `shot_plan`
+
+One shot per hop. **The number of shots is the number of hops.**
+
+```json
+{
+  "shots": [
+    {
+      "id": "s1",
+      "beat": "...",
+      "directives": {"camera": "hold", "framing": "medium", "pace": "steady", "tail": "ongoing"}
+    }
+  ]
+}
+```
+
+Valid shot fields, and no others: `id`, `beat`, `directives`, `prose`, `seed`,
+`steps`, `duration`, `locked`. Only `beat` is required. An unknown field is a
+hard error.
+
+Directive axes, and no others. Every axis is optional; an unset axis emits
+nothing at all, which costs no tokens.
+
+| axis | values |
+|---|---|
+| `join` | `continuous`, `match_cut`, `hard_cut` — **omit on shot 1**, which has nothing to join to |
+| `camera` | `hold`, `pan_follow`, `push_in`, `pull_back`, `orbit`, `handheld` |
+| `framing` | `keep`, `wide`, `medium`, `close` |
+| `pace` | `slow`, `steady`, `brisk` |
+| `tail` | `ongoing` (default), `settle`, `hold` |
+
+Two combinations are contradictions and will be flagged:
+
+- `join: continuous` + a framing change + `camera: hold`. With the camera still,
+  the only way to reach a new framing is a cut. Earn it on the move (`push_in`,
+  `pull_back`, `pan_follow`) or use `framing: keep`.
+- `push_in` with `wide`, or `pull_back` with `close`. The move points the
+  opposite way from the destination.
+
+`duration` may override the chain per shot, using exactly these labels:
+`"5 s"`, `"7 s"`, `"8 s"`, `"10 s"`, `"15 s"`.
+
+### How long a beat has to be
+
+A beat has to fill its whole hop. Written short, the model finishes the action
+early and invents something for the seconds left over -- most often a cut to the
+reference photograph in the closing moments. **Ask the user how long each hop is
+if they have not said**, and size every beat to it.
+
+**Count the words in each beat before you answer, and write the count down.**
+This is the instruction most often ignored, and ignoring it is not a small
+miss. Two different models asked for six 15 s hops both returned beats averaging
+**54 words** -- every single beat under the floor -- and the same two models,
+asked for much shorter hops, returned 40 to 48. Left to itself a model writes
+about fifty words whatever the hop length. Fifty words is right for a 7 s hop
+and is half of what 15 s needs. The table below is not a style note; it is the
+one part of this document you have to do arithmetic for.
+
+| hop | words in the beat |
+|---|---|
+| `5 s` | 30-45 |
+| `7 s` | 30-55 |
+| `8 s` | 35-60 |
+| `10 s` | 45-75 |
+| `15 s` | 70-100 |
+
+A worked `15 s` beat, at 74 words, from a rendered eight-hop chain:
+
+> They close the distance together and the blades meet at the centre of the clearing, white sparks bursting from the impact as the camera orbits around the lock. @warrior_face turns the heavier blade aside and cuts back across the body; @enemy_shadow catches it on the flat and steps in behind it. Steel rings sharp and resonant on every contact, armour plates grind against one another, and boots drag hard over stone between the exchanges.
+
+Read how the length is spent, because padding to a word count fails differently
+but just as badly. One continuous movement carries the whole hop -- they close,
+the blades meet, one turns the other aside, the other steps in. The camera move
+is named inside the action rather than after it. The last third is the sound bed
+and nothing else: three specific noises, each tied to a thing on screen. There
+is no second event and no scene change.
+
+The `5 s` and `7 s` rows are the measured spread of the two plans that ship with
+the node. Their thinnest beat is 28 words in a 7 s hop, carrying one simple
+action; their fullest is 56. The `15 s` row now has one measurement behind it --
+the chain the example above comes from ran 74 to 90 words a beat across eight
+hops and every hop delivered its beat in full, with no hop idling into the
+reference. **The `8 s` and `10 s` rows are still interpolated, not measured.**
+If the closing seconds drift or cut to the reference photograph, the beat was
+short.
+
+Fill that length with *continuous* material -- one movement that takes the whole
+hop, what the camera is doing while it happens, and the sound bed underneath --
+rather than with more separate events. Four events crammed into one hop is the
+over-delivery in rule 7, and it costs you the next hop's opening.
+
+### Dialogue
+
+Put the spoken line inside the beat, in **single** quotes:
+
+```
+@hero_face looks up from the chopping board and says, 'You are early. I have
+barely started.'
+```
+
+Single quotes survive copy-paste; escaped double quotes are the most common
+cause of a rejected plan. Budget roughly one line of dialogue per 5–7 seconds of
+hop — a long speech in a short hop is truncated mid-word, and that truncation is
+then pinned into the next hop's audio.
+
+## `ref_plan`
+
+```json
+{
+  "refs": [
+    {"tag": "hero_face", "file": "face.jpg", "subject": 1,
+     "retention": "fully_preserved", "shots": [1, 4],
+     "desc": "head-and-shoulders, even light"}
+  ],
+  "subjects": {
+    "1": {"name": "the cook",
+          "locked": "the same face, the same short dark hair",
+          "context": "the apron stays tied over the grey t-shirt"}
+  }
+}
+```
+
+Valid ref fields: `tag`, `file`, `subject`, `retention`, `desc`, `shots`. (There
+is also `slot`, which is derived from list position — never author it.)
+
+- **`tag`** is required, unique, `[A-Za-z0-9_]+`, and is what appears in beats
+  as `@tag`.
+- **`file`** is a bare filename in `ComfyUI/input/h3_refs`, never a path. A
+  filename that is not in that folder **stops the run** -- it is an error, not a
+  warning, so a placeholder you invent must be one the user then actually
+  supplies. If the user has not told you their filenames, use clear placeholders
+  and list every one of them at the end of your answer, with what each picture
+  should show.
+- **`subject`** is an integer ≥ 1 grouping pictures **of the same person**.
+  Declaring two different people under one subject number makes the model render
+  **the average of their faces**. One number per person, always.
+- **`retention`** is one of:
+  - `fully_preserved` — face, bone structure and hairstyle carry over exactly
+  - `partially_copy` — the garment and its cut carry over
+  - `reference` — layout, surfaces and light carry over, i.e. a place
+
+  It defaults to `fully_preserved` when `subject` is set, `reference` otherwise.
+- **`shots`** is the list of 1-based hops the picture rides on.
+
+Every subject that appears in `subjects` must be claimed by at least one ref, or
+the plan is rejected. Give every subject a **`locked`**: pictures put a face in
+front of the encoder, but `locked` is what carries the identity across a hop
+where the picture is absent. At most **9 references in the whole plan** -- the limit counts entries in
+`refs`, not pictures per hop.
+
+### Scheduling references is the part that decides whether continuity holds
+
+Write `@tag` for a person on any hop you like. Hop 1 resolves it to
+`<Subject N>` against its definitions block; hop 2 onward resolves it to the
+subject's `name`, which binds to the identity sentence every continuation hop
+carries. **Every subject therefore needs a `name`.**
+
+**A reference with no `shots` list rides hop 1 only.** That default is right
+for a **place** plate: a room still riding a hop set somewhere else beats the
+frame pin, because the model has a crisp picture of one room and a noisy
+carried-over frame of another, and it follows the still. **List every hop a
+picture belongs on, explicitly.**
+
+**A face plate is the opposite. Put it on every hop.** Two six-hop renders
+settled this. A face plate rode a hop set in a space it had never seen and held
+cleanly; the hop scheduled with no references came back a different person, and
+nothing after it recovered. Identity drift does not self-correct. `locked` holds
+a face that is still right; only a plate rebuilds one that is gone.
+
+- Put every **face** reference on every hop: `"shots": [1, 2, 3, 4, 5, 6]`.
+- Keep a **place** reference on every hop set in that place, and off every hop
+  that is not.
+- An **outfit** plate can ride hop 1 only, but then `context` is the only thing
+  holding the wardrobe from hop 2 on, so name its colours there.
+- Never let a place plate shot in one location ride a hop set somewhere else.
+- **The hop that changes location belongs entirely to the new place.** Put the
+  departure at the end of the *previous* beat, so that no place plate ever rides
+  a hop which opens somewhere it was not photographed.
+- **A location introduced part way through needs its own plate, on the hop it
+  arrives and every hop after.** Tightening a place plate to its own shots does
+  **not** mean the next location goes without one. This is the most common
+  mistake made on this rule: two models both plated the opening location, moved
+  the story to a second one, gave that second one no plate at all, and wrote a
+  confident justification for it. In one case that left the film's main setting
+  -- four of six hops -- held by beat text alone. Ask for the extra picture. If
+  the plan ends somewhere no picture describes, the plan is wrong.
+
+## What to produce
+
+1. A one-paragraph plan in prose: how many hops, what each covers, where the
+   references sit and why.
+2. ```json ``` block — the `shot_plan`.
+3. ```json ``` block — the `ref_plan`.
+4. A short list of any pictures the user still needs to supply, with the
+   filename you used for each and what the picture should show.
+
+Before you answer, check every one of these:
+
+- [ ] Shot count matches the hop count the user asked for.
+- [ ] Every beat's word count has been counted, written down, and falls inside
+      the band for its hop length. A 15 s hop needs 70-100 words; fifty is
+      what comes out when this check is skipped.
+- [ ] No shot contains a negation anywhere.
+- [ ] No beat contains any of: no, not, never, n't, without, none of, stop,
+      stops, silent, silence.
+- [ ] No beat describes a thing that has finished happening -- nothing fades,
+      passes, wanes, subsides, dies down, eases off, recedes or grows quiet.
+      Passing this check is not the same as passing the one above it.
+- [ ] No beat contains backticks, asterisks or any other markdown. Beats are
+      plain prose; a tag inside a beat is written bare, as @tag.
+- [ ] No shot names an action ending; endings are written as a pose plus a sound.
+- [ ] Any quiet moment names a specific narrowband sound.
+- [ ] No hop ends on a spoken line; every dialogue-free hop names a sound of its own.
+- [ ] Any hop that changes location joins on `match_cut` or `hard_cut`, not `continuous`.
+- [ ] Every state change lands at the end of the shot *before* the one that
+      needs it.
+- [ ] Shot 1 establishes; no later shot re-describes face, clothes or room.
+- [ ] Shot 1 names the visual style, if the user asked for anything other
+      than live action.
+- [ ] Every persistent object and garment carries an adjective, in the beat
+      and again in `context`.
+- [ ] Each beat holds true whether the hop before it stopped short or ran
+      ahead of its beat.
+- [ ] Every `@tag` used in a beat exists in `ref_plan`, spelled identically.
+- [ ] Every `@tag` used on hop N has that N in its ref's `shots` list.
+- [ ] Every location the film visits has a place plate covering the hops set
+      there, including any location introduced after hop 1. The final hop is
+      covered by one.
+- [ ] `join` is absent from shot 1.
+- [ ] The final shot sets `tail` to `settle` or `hold`.
+- [ ] Compare each shot's `framing` with the previous shot's: where it
+      changes on `join: continuous`, the camera is moving, not `hold`. And no
+      `push_in`+`wide`, no `pull_back`+`close`.
+- [ ] Every subject in `subjects` is claimed by a ref, and has both a `name`
+      and a `locked`.
+- [ ] `refs` holds at most 9 entries in total.
+- [ ] Dialogue uses single quotes.
+- [ ] Both blocks are valid JSON: no trailing commas, no comments, no smart
+      quotes, plain ASCII, and no field outside the lists above.

pyproject.toml

@@ -0,0 +1,19 @@
+[project]
+name = "comfyui-hand-tie-clips"
+version = "0.3.3"
+description = "Native MiniMax H3 Ref2VA chain: persistent references, previous-segment clip+audio pin, one queue."
+readme = "README.md"
+license = { file = "LICENSE" }
+requires-python = ">=3.10"
+dependencies = []
+
+[project.urls]
+Repository = "https://github.com/dntpi/ComfyUI-Hand-Tie-Clips"
+
+# `comfy node publish` needs PublisherId as well as the Repository above.
+# PublisherId comes from a registry.comfy.org account and is the last field
+# outstanding. Neither is needed to install the pack by hand or from a zip.
+[tool.comfy]
+PublisherId = ""
+DisplayName = "Hand Tie Clips"
+Icon = ""

refs.py

@@ -0,0 +1,501 @@
+"""Reference register: stable @tags, subject numbers, retention tiers.
+
+Two bugs this exists to fix.
+
+**Ordinal instability.** Core assigns `<Picture N>` 1-based in list order
+(`comfy/text_encoders/minimax.py:148-202`), and `_collect_ref_images` packs the
+wired slots densely. Wire slots 1/3/5 and they become `<Picture 1/2/3>`; unplug
+one and every later reference silently renumbers. Any prompt text naming a
+literal ordinal is then pointing at the wrong picture. Here a ref carries a
+stable `@tag` and the ordinal is *derived per hop*, so prompt prose refers to
+tags and the compiler resolves them.
+
+**Subject collapse.** H3-Multishot found that declaring every picture as a photo
+of `<Subject 1>` makes the model render the average of two different people.
+Subject numbers group pictures per person and state distinctness explicitly.
+
+Phrasing here follows the same rule as `directives.py`: AFFIRMATIVE ONLY.
+Sampling runs at cfg 1.0 with no negative branch, so every concept named is
+additive. State what each picture IS for.
+"""
+
+from os.path import basename as _basename
+
+TAG = "HandTieClips"
+
+MAX_REF_IMAGES = 9
+
+# What the model should do with a picture. Wording is deliberately about the
+# *carry-over*, not about the picture, because the model is being told how much
+# of it to reproduce.
+RETENTION = {
+    "fully_preserved": "face, bone structure, and hairstyle carry over exactly",
+    "partially_copy": "the garment and its cut carry over, moving naturally with the body",
+    "reference": "the layout, surfaces, and light carry over as the setting",
+}
+
+# `file` is the reference: a basename under <ComfyUI input>/h3_refs. `slot` is
+# still accepted, and still *emitted*, but it means something different now --
+# it is derived from the ref's position in the list rather than naming a socket,
+# and it exists only so the ordinal machinery below did not have to change.
+# A plan from before the sockets were removed carries an authored `slot` and no
+# `file`; that is detected, kept as `legacy_slot`, and reported by check().
+REF_FIELDS = ("tag", "file", "slot", "subject", "retention", "desc", "shots")
+
+# Per-subject continuity text -- the half `HTCContinuityState` owned, moved here
+# so it is keyed by the same subject number that owns the picture ordinals.
+#
+# The old node could not express a second character at all: `continuity_state`
+# is a single forceInput STRING and the node emits exactly one `characters` key
+# from one `character_id` widget, so two people were unrepresentable (its own
+# docstring says so). Worse, its prose named people by an arbitrary string while
+# `<Picture N>` was assigned positionally by slot order, with nothing joining
+# the two -- so with two people at two refs each, `_identity_lock` emitted one
+# undifferentiated pool of four "identities" and the model was free to average
+# the faces. Keying continuity text by subject number closes that join.
+SUBJECT_FIELDS = ("name", "locked", "context")
+
+
+def _fail(msg):
+    raise ValueError(f"{TAG}: {msg}")
+
+
+def _norm_subject(key, raw):
+    """Validate one subject entry. Errors name the subject and valid fields."""
+    try:
+        num = int(key)
+    except (TypeError, ValueError):
+        _fail(f"subject key {key!r} is not a number. Use the same subject numbers "
+              f"the refs use, e.g. \"1\".")
+    if num < 1:
+        _fail(f"subject {key}: subject numbers start at 1")
+    if not isinstance(raw, dict):
+        _fail(f"subject {num}: expected an object, got {type(raw).__name__}")
+    unknown = sorted(set(raw) - set(SUBJECT_FIELDS))
+    if unknown:
+        _fail(f"subject {num}: unknown field(s) {unknown}. "
+              f"Valid: {list(SUBJECT_FIELDS)}")
+    return num, {
+        "name": str(raw.get("name") or "").strip(),
+        "locked": str(raw.get("locked") or "").strip(),
+        "context": str(raw.get("context") or "").strip(),
+    }
+
+
+def _norm_ref(raw, i):
+    """Validate one ref entry. Errors name the ref and the valid options."""
+    where = f"ref {i + 1}"
+    if not isinstance(raw, dict):
+        _fail(f"{where}: expected an object, got {type(raw).__name__}")
+
+    unknown = sorted(set(raw) - set(REF_FIELDS))
+    if unknown:
+        _fail(f"{where}: unknown field(s) {unknown}. Valid: {list(REF_FIELDS)}")
+
+    tag = str(raw.get("tag") or "").strip().lstrip("@")
+    if not tag:
+        _fail(f"{where}: 'tag' is required (a short stable name like 'hero_face')")
+
+    # A bare filename, never a path: media.resolve refuses anything with a
+    # directory component, so accepting one here would only produce a ref that
+    # silently never loads.
+    file = _basename(str(raw.get("file") or "").strip())
+
+    # Legacy: a plan authored against the ref_image_N sockets. Not an error --
+    # failing here would stop the editor opening the very plan the author needs
+    # to repair, so it is carried through and reported by check().
+    legacy_slot = None
+    if not file and raw.get("slot") is not None:
+        try:
+            legacy_slot = int(raw["slot"])
+        except (TypeError, ValueError):
+            legacy_slot = None
+
+    subject = raw.get("subject")
+    if subject is not None:
+        try:
+            subject = int(subject)
+        except (TypeError, ValueError):
+            _fail(f"{where} (@{tag}): subject {subject!r} is not a number")
+        if subject < 1:
+            _fail(f"{where} (@{tag}): subject must be 1 or greater")
+
+    retention = str(raw.get("retention") or "").strip()
+    if not retention:
+        # A ref tied to a person defaults to identity; anything else is setting.
+        retention = "fully_preserved" if subject else "reference"
+    if retention not in RETENTION:
+        _fail(f"{where} (@{tag}): retention '{retention}' is not valid. "
+              f"Use one of: {', '.join(sorted(RETENTION))}")
+
+    shots = raw.get("shots")
+    if shots is not None:
+        if not isinstance(shots, (list, tuple)):
+            _fail(f"{where} (@{tag}): 'shots' must be a list of 1-based shot "
+                  f"numbers, e.g. [1, 2]")
+        clean = []
+        for s in shots:
+            try:
+                clean.append(int(s))
+            except (TypeError, ValueError):
+                _fail(f"{where} (@{tag}): shot number {s!r} is not a number")
+        if not clean:
+            _fail(f"{where} (@{tag}): 'shots' is empty. Omit it for every shot.")
+        shots = sorted(set(clean))
+
+    return {
+        "tag": tag,
+        "file": file,
+        "legacy_slot": legacy_slot,
+        # Filled in by parse_ref_plan from list position; see REF_FIELDS.
+        "slot": 0,
+        "subject": subject,
+        "retention": retention,
+        "desc": str(raw.get("desc") or "").strip(),
+        "shots": shots,
+    }
+
+
+def parse_ref_plan(text):
+    """Parse the ref_plan widget.
+
+    Returns {"refs": [...], "subjects": {n: {...}}}. Blank -> empty plan, and
+    the caller falls back to raw slot order.
+    """
+    import json
+
+    t = (text or "").strip()
+    if not t:
+        return {"refs": [], "subjects": {}}
+    try:
+        data = json.loads(t)
+    except json.JSONDecodeError as e:
+        _fail(f"ref_plan is not valid JSON: {e}")
+
+    raw_subjects = {}
+    if isinstance(data, list):
+        raw_refs = data
+    elif isinstance(data, dict):
+        raw_refs = data.get("refs")
+        if raw_refs is None:
+            _fail("ref_plan object needs a 'refs' array")
+        raw_subjects = data.get("subjects") or {}
+        if not isinstance(raw_subjects, dict):
+            _fail("ref_plan 'subjects' must be an object keyed by subject number, "
+                  "e.g. {\"1\": {\"name\": \"...\", \"locked\": \"...\"}}")
+    else:
+        _fail(f"ref_plan must be an object or array, got {type(data).__name__}")
+
+    if not isinstance(raw_refs, (list, tuple)):
+        _fail("ref_plan 'refs' must be an array")
+
+    refs = [_norm_ref(r, i) for i, r in enumerate(raw_refs)]
+    if len(refs) > MAX_REF_IMAGES:
+        _fail(f"ref_plan has {len(refs)} references; the encoder takes at most "
+              f"{MAX_REF_IMAGES} in one plan.")
+    # The ordinal is derived from list position, which is what the author sees
+    # in the rail. This keeps `active_refs`/`ordinals` unchanged while the
+    # authored identity moves from a socket number to a filename.
+    for i, r in enumerate(refs):
+        r["slot"] = i + 1
+    subjects = dict(_norm_subject(k, v) for k, v in raw_subjects.items())
+
+    # A subject block that no ref points at is continuity text for a person with
+    # no face wired -- it would ride every hop describing someone who never
+    # appears, which at cfg 1.0 is purely additive.
+    used = {r["subject"] for r in refs if r["subject"] is not None}
+    for num in sorted(set(subjects) - used):
+        _fail(f"subject {num} has continuity text but no ref claims subject "
+              f"{num}. Give one of the refs \"subject\": {num}, or remove the "
+              f"subject block.")
+
+    seen_tags = {}
+    for i, r in enumerate(refs):
+        if r["tag"] in seen_tags:
+            _fail(f"ref {i + 1}: tag '@{r['tag']}' is already used by ref "
+                  f"{seen_tags[r['tag']] + 1}. Tags must be unique.")
+        seen_tags[r["tag"]] = i
+    return {"refs": refs, "subjects": subjects}
+
+
+def active_refs(refs, hop_index, wired_slots):
+    """Refs live on this hop, in rail order, restricted to those whose file loaded.
+
+    `hop_index` is 0-based; `shots` in the plan is 1-based because that is what
+    the shot plan shows the author.
+    """
+    shot_no = hop_index + 1
+    out = []
+    for r in refs:
+        if r["slot"] not in wired_slots:
+            continue
+        if r["shots"] is not None and shot_no not in r["shots"]:
+            continue
+        out.append(r)
+    return sorted(out, key=lambda r: r["slot"])
+
+
+def ordinals(active):
+    """tag -> `<Picture N>` ordinal for this hop.
+
+    This is the whole point: the ordinal is derived from what is active on this
+    hop, so prose written against @tags stays correct when refs are added,
+    removed, or scheduled off.
+    """
+    return {r["tag"]: i + 1 for i, r in enumerate(active)}
+
+
+def resolve_tags(text, tag_map, subject_map=None, where="", declared=None,
+                 subject_names=None):
+    """Replace `@tag` in prose with what this hop calls that reference.
+
+    A ref tied to a person resolves to `<Subject N>`, not `<Picture N>`: beat
+    prose describes someone *acting*, and a picture cannot act. The
+    `subject_definitions:` block binds the subject to its pictures, so the
+    identity still lands. Setting and prop refs have no subject and resolve to
+    their picture ordinal.
+
+    `subject_map` may include people whose photograph is off this hop
+    (continuation: pin-only). Those tags still resolve to `<Subject N>`.
+
+    An unknown tag is a hard error -- silently leaving `@hero_face` in the
+    prompt would put the literal word in front of the encoder, which at cfg 1.0
+    is additive noise.
+
+    `subject_names` maps subject number -> the name to use in prose, and is
+    passed on **continuation hops only**. There, `<Subject N>` is a dangling
+    token: `subject_definitions:` is hop-1 material, so on hop 4 the ordinal has
+    nothing in its own encode to bind to -- the same defect that turned an
+    undescribed "the bowl" into a stainless steel one. A name binds to the
+    identity sentence `continuity_line` puts on every continuation hop, so the
+    prose reads "The cook walks down the hallway" and every word is anchored.
+    Without a name for that subject it falls back to `<Subject N>`, which is no
+    worse than before.
+
+    `declared` is every tag in the register, active on this hop or not. A tag
+    that is in it has been spelled correctly and the fault lies elsewhere --
+    a missing picture, or a `shots` list that leaves this hop out. Reporting
+    that as "unknown reference" sent authors hunting through their beats for a
+    typo that was never there.
+    """
+    import re
+
+    t = str(text or "")
+    if "@" not in t:
+        return t
+    subject_map = subject_map or {}
+    declared = declared or set()
+
+    def sub(m):
+        tag = m.group(1)
+        # A person tag stays <Subject N> even when that photograph is off this
+        # hop (continuation: the pin carries wardrobe and room, the still does
+        # not). Requiring the tag in tag_map first made @hero_face a hard error
+        # the moment hop 2 dropped the face plate.
+        if tag in subject_map:
+            num = subject_map[tag]
+            name = str((subject_names or {}).get(num) or "").strip()
+            if name:
+                # Sentence-initial gets a capital: "@hero_face walks" became
+                # "the cook walks" mid-paragraph, which reads as a fragment.
+                head = t[:m.start()].rstrip()
+                if not head or head[-1] in '.!?:;':
+                    return name[0].upper() + name[1:]
+                return name
+            return f"<Subject {num}>"
+        if tag in tag_map:
+            return f"<Picture {tag_map[tag]}>"
+        w = where + ": " if where else ""
+        if tag in declared:
+            _fail(f"{w}@{tag} is in the reference register but has no picture "
+                  f"on this hop. Either its file is not in the reference "
+                  f"folder, or its `shots` list leaves this hop out.")
+        known = ", ".join("@" + k for k in sorted(set(tag_map) | set(subject_map))) or "(none)"
+        _fail(f"{w}unknown reference '@{tag}'. Known: {known}")
+
+    return re.sub(r"@([A-Za-z0-9_]+)", sub, t)
+
+
+def subjects(active):
+    """tag -> subject number, for refs that name a person."""
+    return {r["tag"]: r["subject"] for r in active if r["subject"] is not None}
+
+
+def subject_prose(active, subjects=None):
+    """Build `subject_definitions:` and `retention_analysis:` for this hop.
+
+    Pictures are grouped by subject number so two people stay two people, and
+    each subject's continuity text is emitted *inside its own block*, directly
+    after the ordinals that subject owns. That adjacency is the whole fix: the
+    old split put identity prose in one place (keyed by an arbitrary string) and
+    picture ordinals in another (assigned positionally), so the encoder was
+    never told which face belonged to which description.
+
+    A ref with no subject is a setting or prop and appears only in retention.
+    """
+    if not active:
+        return ""
+
+    subjects = subjects or {}
+    ords = ordinals(active)
+    by_subject = {}
+    for r in active:
+        if r["subject"] is not None:
+            by_subject.setdefault(r["subject"], []).append(r)
+
+    parts = []
+    if by_subject:
+        lines = []
+        for subj in sorted(by_subject):
+            pics = ", ".join(f"<Picture {ords[r['tag']]}>" for r in by_subject[subj])
+            info = subjects.get(subj) or {}
+            name = info.get("name")
+            who = f"{name}, the person in {pics}" if name else f"the person in {pics}"
+            lines.append(f"<Subject {subj}> is {who}.")
+            for extra in (info.get("locked"), info.get("context")):
+                if extra:
+                    lines.append(f"<Subject {subj}>: {extra}")
+        if len(by_subject) > 1:
+            names = ", ".join(f"<Subject {s}>" for s in sorted(by_subject))
+            lines.append(
+                f"{names} are separate people. Each one keeps the face from its "
+                f"own pictures throughout."
+            )
+        parts.append("subject_definitions:\n" + "\n".join(lines))
+
+    ret = []
+    for r in active:
+        pic = f"<Picture {ords[r['tag']]}>"
+        detail = RETENTION[r["retention"]]
+        desc = f" ({r['desc']})" if r["desc"] else ""
+        ret.append(f"{pic}{desc}: {detail}.")
+    parts.append("retention_analysis:\n" + "\n".join(ret))
+
+    return "\n\n".join(parts)
+
+
+def continuity_line(subjects, subject_nums=None):
+    """Identity prose for a hop that cites no photographs.
+
+    `subject_prose` binds continuity text to picture ordinals, which makes it
+    hop-1 material: repeating a `<Subject N> is the person in <Picture M>`
+    block on a later hop makes that hop a second Ref2VA generate. But the text
+    itself -- `locked` and `context` -- is not about a photograph. It is what
+    must not change, and a hop with no reference scheduled is exactly where the
+    encoder has nothing else to go on.
+
+    So this emits the same text with **no ordinals of any kind**. No
+    `<Picture N>` (which sends the encoder back to the plates -- chain_00034)
+    and no `<Subject N>` (which would dangle, with no definitions block on this
+    hop to bind it). One person is "The same person"; several are named, and
+    fall back to "one person" only when a subject has no name.
+
+    Returns "" when nothing is worth saying, so callers can `if p` it away.
+    """
+    subjects = subjects or {}
+    nums = sorted(subject_nums if subject_nums is not None else subjects)
+    nums = [n for n in nums if (subjects.get(n) or {})]
+    if not nums:
+        return ""
+
+    solo = len(nums) == 1
+    lines = []
+    for num in nums:
+        info = subjects.get(num) or {}
+        bits = [t.strip() for t in (info.get("locked"), info.get("context"))
+                if t and t.strip()]
+        if not bits:
+            continue
+        # "The same person" reads as continuation; a bare name reads as an
+        # introduction, which on a continuation hop is a new scene. With more
+        # than one subject there is no way round naming them, and a `name`
+        # carries its own article in practice ("the cook") -- so it is used as
+        # written rather than glued behind "The same", which produced "The same
+        # the cook continues".
+        name = (info.get("name") or "").strip()
+        if solo or not name:
+            who = "The same person"
+        else:
+            who = name[0].upper() + name[1:]
+        body = "; ".join(b.rstrip(".") for b in bits)
+        lines.append(f"{who} continues, with {body}.")
+    return " ".join(lines)
+
+
+def describe(plan):
+    """Console-auditable summary, printed once at chain start."""
+    refs = plan.get("refs") or []
+    subjects = plan.get("subjects") or {}
+    if not refs:
+        return "(no ref plan)"
+    out = []
+    for num in sorted(subjects):
+        info = subjects[num]
+        label = info.get("name") or "(unnamed)"
+        out.append(f"  <Subject {num}> {label}")
+    for r in refs:
+        subj = f"subject {r['subject']}" if r["subject"] else "setting"
+        when = "all shots" if r["shots"] is None else "shots " + ",".join(
+            str(s) for s in r["shots"])
+        src = r["file"] or (f"(was slot {r['legacy_slot']}, no file)"
+                            if r["legacy_slot"] else "(no file)")
+        out.append(f"  @{r['tag']:<16} {src:<28} {subj:<10} "
+                   f"{r['retention']:<16} {when}")
+    return "\n".join(out)
+
+
+def missing_files(plan, wired_slots):
+    """Refs that name a picture which did not load. Fatal, unlike `check`.
+
+    A ref with no `file` at all is a legitimate half-built plan -- the Starter
+    ships that way on purpose, so it runs before you have supplied anything. A
+    ref that *names* `ref_face.jpg` when no such file is in `h3_refs` is a typo
+    or a missing asset, and there is no reading of it under which rendering six
+    hops without that picture is what the author wanted: it produces exactly the
+    uncontrolled output the register exists to prevent, and the only signal used
+    to be one console line under the sampler output.
+
+    Returns a list of `(tag, file)`. The caller raises; this stays free of disk
+    access, like `check`.
+    """
+    out = []
+    for r in plan.get("refs") or []:
+        if r["slot"] in wired_slots or not r["file"]:
+            continue
+        out.append((r["tag"], r["file"]))
+    return out
+
+
+def check(plan, wired_slots):
+    """Warn (never raise) about refs whose picture is missing or never chosen.
+
+    `wired_slots` is the set of derived slots whose file actually loaded, so
+    the caller does the resolving and this stays free of disk access.
+    """
+    refs = plan.get("refs") or []
+    subjects = plan.get("subjects") or {}
+    warnings = []
+    # A person with pictures but no continuity text still renders, but nothing
+    # carries their state across the seam -- which is the failure this register
+    # exists to fix, so it is worth naming.
+    for num in sorted({r["subject"] for r in refs if r["subject"] is not None}):
+        if num not in subjects:
+            warnings.append(
+                f"subject {num} has pictures but no continuity text. Add "
+                f"subjects.{num}.locked to carry their identity across seams.")
+    for r in refs:
+        if r["slot"] in wired_slots:
+            continue
+        if r["legacy_slot"]:
+            warnings.append(
+                f"@{r['tag']} was wired to ref_image_{r['legacy_slot']}, which no "
+                f"longer exists. Pick its picture in the REFERENCES rail -- this "
+                f"ref is inactive until you do.")
+        elif not r["file"]:
+            warnings.append(
+                f"@{r['tag']} has no picture chosen. This ref is inactive.")
+        else:
+            warnings.append(
+                f"@{r['tag']} names '{r['file']}', which is not in the reference "
+                f"folder or could not be read. This ref is inactive.")
+    return warnings

routes.py

@@ -0,0 +1,178 @@
+"""One read-only endpoint: the vocabulary the editor draws its dropdowns from.
+
+The alternative is a copy of `VOCAB` in JavaScript, and a copy is a second source
+of truth that goes stale the first time a phrase is improved. `directives.py`
+exists precisely so that improving a sentence improves every plan ever written;
+duplicating those strings in the UI would undo that.
+
+It also ships the *prose* each option compiles to, not just the option names, so
+the editor can show what a directive actually puts in front of the encoder. That
+is the whole answer to "I don't know how any of this works at a glance".
+
+Since 2026-08-28 this module also carries the reference *files*: `POST
+/h3_ref_chain/upload` streams dropped media into `<input>/h3_refs`, and `GET
+/h3_ref_chain/files` lists what is there. Those replaced the nine `ref_image_N`
+IMAGE sockets, which were most of a 16-socket column.
+
+Everything that decides *where bytes land* lives in `media.py`, not here: one
+prefix-checked resolver used by both the route and the loaders, so there is a
+single place to be wrong about it. The route itself never joins a path.
+"""
+
+import os as _os
+
+from . import directives as _d
+from . import media as _media
+from . import refs as _refs
+
+TAG = "HandTieClips"
+ROUTE = "/h3_ref_chain/vocab"
+UPLOAD_ROUTE = "/h3_ref_chain/upload"
+FILES_ROUTE = "/h3_ref_chain/files"
+
+# A batch of stills is a handful; this is a guard against a runaway multipart
+# body, not a considered product limit.
+MAX_UPLOAD_FILES = 32
+MAX_UPLOAD_BYTES = 256 * 1024 * 1024
+
+
+def _payload():
+    from .h3_ref_chain import DURATION_FRAMES, OVERLAP_FRAMES, CANVAS, FPS
+
+    return {
+        # axis -> option -> the sentence it compiles to. Order matters: AXES is
+        # the order directive_prose concatenates in, so the UI shows them in the
+        # order the encoder reads them.
+        "axes": list(_d.AXES),
+        "vocab": {axis: dict(opts) for axis, opts in _d.VOCAB.items()},
+        "defaults": dict(_d.DEFAULTS),
+        "establish": _d.ESTABLISH,
+        # join has nothing to attach to on the first hop; the editor hides it
+        # there to match directive_prose's hop_index == 0 skip.
+        "join_axis": "join",
+
+        "retention": dict(_refs.RETENTION),
+        "max_ref_images": _refs.MAX_REF_IMAGES,
+        "refs_subdir": _media.REFS_SUBDIR,
+        "image_exts": sorted(_media.IMAGE_EXTS),
+        "video_exts": sorted(_media.VIDEO_EXTS),
+        "audio_exts": sorted(_media.AUDIO_EXTS),
+        "ref_fields": list(_refs.REF_FIELDS),
+        "subject_fields": list(_refs.SUBJECT_FIELDS),
+
+        "durations": {k: v for k, v in DURATION_FRAMES.items()},
+        "overlaps": {k: v for k, v in OVERLAP_FRAMES.items()},
+        "canvas": {res: {asp: list(wh) for asp, wh in by_asp.items()}
+                   for res, by_asp in CANVAS.items()},
+        "fps": FPS,
+    }
+
+
+def register():
+    """Attach the route if a PromptServer exists. Never raises on import."""
+    try:
+        from aiohttp import web
+        from server import PromptServer
+    except ImportError:
+        return False
+    instance = getattr(PromptServer, "instance", None)
+    if instance is None or not hasattr(instance, "routes"):
+        return False
+
+    @instance.routes.get(ROUTE)
+    async def _vocab(_request):
+        try:
+            return web.json_response(_payload())
+        except Exception as exc:  # a broken payload must not take the server down
+            print(f"[{TAG}] vocab route failed: {exc!r}", flush=True)
+            return web.json_response({"error": str(exc)}, status=500)
+
+    @instance.routes.get(FILES_ROUTE)
+    async def _files(request):
+        """What is already in the reference folder, for the editor's picker."""
+        try:
+            kinds = request.rel_url.query.get("kinds") or ""
+            want = {k.strip() for k in kinds.split(",") if k.strip()} or None
+            return web.json_response({"ok": True, "files": _media.listing(want)})
+        except Exception as exc:
+            print(f"[{TAG}] files route failed: {exc!r}", flush=True)
+            return web.json_response({"ok": False, "error": str(exc)}, status=500)
+
+    @instance.routes.post(UPLOAD_ROUTE)
+    async def _upload(request):
+        """Stream dropped media into the reference folder.
+
+        Multipart, not JSON+base64: a batch of stills should not be inflated by
+        a third and held in memory twice on the way through the browser. The
+        destination is fixed -- `media.refs_dir()` -- so a filename can only
+        ever name a file *inside* it, and `media.resolve` re-checks that on the
+        way back out.
+        """
+        if not (request.content_type or "").startswith("multipart/"):
+            return web.json_response(
+                {"ok": False, "error": "expected multipart/form-data"}, status=400)
+        try:
+            reader = await request.multipart()
+        except Exception as exc:
+            return web.json_response(
+                {"ok": False, "error": f"bad multipart: {exc}"}, status=400)
+
+        dest = _media.refs_dir(create=True)
+        saved, skipped, total = [], [], 0
+        try:
+            while True:
+                part = await reader.next()
+                if part is None:
+                    break
+                if not getattr(part, "filename", None):
+                    continue
+                if len(saved) >= MAX_UPLOAD_FILES:
+                    skipped.append(f"{part.filename}: batch limit "
+                                   f"{MAX_UPLOAD_FILES} reached")
+                    break
+                # Basename only, and the extension has to be one we can open.
+                # Rejecting here means nothing unreadable is ever written.
+                name = _os.path.basename(part.filename or "")
+                kind = _media.kind_of(name)
+                if kind is None:
+                    skipped.append(f"{name}: not an image, video or audio file")
+                    continue
+                path = _media.unique_path(dest, name)
+                size = 0
+                try:
+                    with open(path, "wb") as fh:
+                        while True:
+                            chunk = await part.read_chunk()
+                            if not chunk:
+                                break
+                            size += len(chunk)
+                            total += len(chunk)
+                            if total > MAX_UPLOAD_BYTES:
+                                raise ValueError("upload too large")
+                            fh.write(chunk)
+                except Exception:
+                    # A partial file is worse than no file: it would list in
+                    # the picker and fail to open.
+                    try:
+                        _os.remove(path)
+                    except OSError:
+                        pass
+                    raise
+                w = h = 0
+                if kind == "image":
+                    path, w, h = _media.shrink_image(path)
+                saved.append({"name": _os.path.basename(path), "kind": kind,
+                              "width": w, "height": h, "bytes": size})
+        except Exception as exc:
+            print(f"[{TAG}] upload failed: {exc!r}", flush=True)
+            return web.json_response(
+                {"ok": False, "error": str(exc), "files": saved}, status=400)
+
+        if saved:
+            print(f"[{TAG}] uploaded {len(saved)} reference file(s) -> "
+                  + ", ".join(f["name"] for f in saved), flush=True)
+        for note in skipped:
+            print(f"[{TAG}] upload skipped {note}", flush=True)
+        return web.json_response({"ok": True, "files": saved, "skipped": skipped})
+
+    return True

store.py

@@ -0,0 +1,297 @@
+"""Disk-backed hop store: resume, single-shot re-roll, and lower peak RAM.
+
+Hops are causally dependent -- hop N is rendered from hop N-1's tail -- so the
+cache key **chains**: each hop's key mixes in the previous hop's key. Editing
+shot 1 therefore invalidates 2..N automatically, which is correct and must be
+surfaced in the UI, because otherwise it reads as a bug.
+
+**Why 16-bit.** A cached hop's last frame becomes the next hop's Qwen pin and
+its AddGuide guide. Round-tripping float32 through 8-bit would make a resumed
+chain diverge from an uninterrupted one -- the cache would change the output,
+which defeats the point. FFV1 at `rgb48le` keeps ~16 bits per channel, which is
+far below the VAE's own noise floor, so a resumed hop is indistinguishable from
+a fresh one. The cost is roughly 2x the bytes of an 8-bit lossless encode, and
+FFV1 still compresses it well.
+
+**On the RAM claim.** The node's IMAGE output is the whole clip, so the final
+tensor is unavoidably full size. What the store removes is the *double and
+triple buffering* during the loop: today `master_imgs` grows by concatenation
+(which allocates a new full-size tensor every hop) while `prev_imgs` and `imgs`
+are also live. Streaming to disk keeps one hop plus the overlap tail resident
+and concatenates once at the end.
+"""
+
+import hashlib
+import json
+import os
+import shutil
+import subprocess
+import time
+
+import numpy as np
+import torch
+
+TAG = "HandTieClips"
+
+VIDEO_EXT = ".mkv"
+AUDIO_EXT = ".npy"
+META_EXT = ".json"
+LATENT_EXT = ".latent.pt"
+
+
+def _ffmpeg():
+    exe = shutil.which("ffmpeg")
+    if not exe:
+        raise RuntimeError(
+            f"{TAG}: ffmpeg is not on PATH. The hop store needs it to write "
+            f"lossless FFV1. Install ffmpeg or set cache to off."
+        )
+    return exe
+
+
+def tensor_digest(t):
+    """Cheap, order-sensitive digest of a tensor's actual bytes."""
+    if t is None:
+        return "none"
+    a = t.detach().cpu().contiguous().numpy()
+    h = hashlib.sha256()
+    h.update(str(a.shape).encode())
+    h.update(str(a.dtype).encode())
+    h.update(a.tobytes())
+    return h.hexdigest()[:16]
+
+
+def audio_digest(a):
+    """Digest an AUDIO input -- ``{"waveform": Tensor, "sample_rate": int}``.
+
+    AUDIO is a dict, not a tensor, so `tensor_digest` cannot take it: `.detach`
+    on a dict raises AttributeError, which is what wiring `voice` with the hop
+    cache on used to do before hop 1 ever started. Sample rate is part of the
+    identity -- the same waveform at a different rate is different audio.
+    """
+    if a is None:
+        return "none"
+    if not isinstance(a, dict):
+        return tensor_digest(a)
+    h = hashlib.sha256()
+    h.update(tensor_digest(a.get("waveform")).encode())
+    h.update(str(a.get("sample_rate")).encode())
+    return h.hexdigest()[:16]
+
+
+def hop_key(prev_key, payload):
+    """Chained content key. `payload` must contain everything that changes pixels.
+
+    Anything omitted here is something the cache will fail to notice, so err
+    toward including it.
+    """
+    h = hashlib.sha256()
+    h.update((prev_key or "root").encode())
+    h.update(json.dumps(payload, sort_keys=True, default=str).encode())
+    return h.hexdigest()[:24]
+
+
+class HopStore:
+    def __init__(self, root, budget_gb=20.0, fps=24):
+        self.root = str(root)
+        self.budget = float(budget_gb) * (1024 ** 3)
+        self.fps = int(fps)
+        os.makedirs(self.root, exist_ok=True)
+
+    # -- paths ------------------------------------------------------------
+    def _p(self, key, ext):
+        return os.path.join(self.root, key + ext)
+
+    def has(self, key):
+        return all(os.path.exists(self._p(key, e))
+                   for e in (VIDEO_EXT, AUDIO_EXT, META_EXT))
+
+    # -- write ------------------------------------------------------------
+    def put(self, key, imgs, wav, sr, meta=None, latent=None):
+        """imgs: float [N,H,W,3] in 0..1 on cpu. wav: float [.., C, S].
+
+        `latent` is this hop's sampler output and is optional; see the comment
+        at the write below for why storing it is what makes the cache useful
+        past hop 1.
+        """
+        n, hgt, wid = int(imgs.shape[0]), int(imgs.shape[1]), int(imgs.shape[2])
+        vid_tmp = self._p(key, VIDEO_EXT + ".part")
+        cmd = [
+            _ffmpeg(), "-y", "-v", "error",
+            "-f", "rawvideo", "-pix_fmt", "rgb48le",
+            "-s", f"{wid}x{hgt}", "-r", str(self.fps),
+            "-i", "-",
+            "-c:v", "ffv1", "-level", "3", "-coder", "1", "-context", "1",
+            "-pix_fmt", "rgb48le",
+            # The .part suffix defeats extension-based format detection, so the
+            # muxer is named explicitly. Writing to .part and renaming on success
+            # keeps a killed render from leaving a half-file that `has()` trusts.
+            "-f", "matroska", vid_tmp,
+        ]
+        proc = subprocess.Popen(cmd, stdin=subprocess.PIPE,
+                                stdout=subprocess.DEVNULL, stderr=subprocess.PIPE)
+        try:
+            # Frame at a time: never materialise a second full-size copy.
+            for i in range(n):
+                f = (imgs[i].clamp(0, 1) * 65535.0).round().to(torch.int32)
+                proc.stdin.write(f.numpy().astype("<u2").tobytes())
+            proc.stdin.close()
+        except BrokenPipeError:
+            pass
+        err = proc.stderr.read().decode(errors="replace")
+        if proc.wait() != 0:
+            raise RuntimeError(f"{TAG}: FFV1 encode failed for hop {key}: {err.strip()}")
+        os.replace(vid_tmp, self._p(key, VIDEO_EXT))
+
+        np.save(self._p(key, AUDIO_EXT),
+                wav.detach().cpu().contiguous().numpy().astype(np.float32))
+
+        # The sampler latent, not just the decoded frames. Without it a cache
+        # hit leaves the caller's `prev_sampled` empty, so the *next* hop
+        # predicts the AddGuide pixel fallback instead of Motion-Context --
+        # which is part of its key, so that key stops matching what was stored.
+        # The cache could therefore never hit past hop 1, and the hop after a
+        # hit was joined by the inferior mechanism, making `cache_hops=on`
+        # actively worse than off. Optional and best-effort: a hop whose latent
+        # will not serialise is still worth caching for its frames, it just
+        # cannot seed a latent join.
+        if latent is not None:
+            tmp = self._p(key, LATENT_EXT + ".part")
+            try:
+                torch.save(latent, tmp)
+                os.replace(tmp, self._p(key, LATENT_EXT))
+            except Exception as e:  # noqa: BLE001
+                print(f"[{TAG}] hop {key[:8]}: latent not cached ({e!r}); a hit "
+                      f"on this hop will fall back to the pixel pin", flush=True)
+                try:
+                    os.remove(tmp)
+                except OSError:
+                    pass
+
+        info = dict(meta or {})
+        info.update({"frames": n, "height": hgt, "width": wid,
+                     "sample_rate": int(sr), "fps": self.fps,
+                     "written": time.time()})
+        with open(self._p(key, META_EXT), "w", encoding="utf-8") as fh:
+            json.dump(info, fh, indent=1)
+        return info
+
+    # -- read -------------------------------------------------------------
+    def _get_latent(self, key):
+        """The stored sampler latent, or None when this entry has none.
+
+        None is always safe: the caller falls back to the pixel pin, which is
+        what every cache hit did before latents were stored. Entries written by
+        an older build simply have no sidecar, so they keep working.
+        """
+        path = self._p(key, LATENT_EXT)
+        if not os.path.exists(path):
+            return None
+        try:
+            # weights_only=False: this is a latent *dict*, written by our own
+            # put() into ComfyUI's temp directory, not a downloaded checkpoint.
+            return torch.load(path, map_location="cpu", weights_only=False)
+        except Exception as e:  # noqa: BLE001
+            print(f"[{TAG}] hop {key[:8]}: cached latent unreadable ({e!r}); "
+                  f"falling back to the pixel pin", flush=True)
+            return None
+
+    def get(self, key):
+        """-> (imgs float32 [N,H,W,3], wav, sample_rate, latent|None) or None."""
+        if not self.has(key):
+            return None
+        with open(self._p(key, META_EXT), encoding="utf-8") as fh:
+            info = json.load(fh)
+        n, hgt, wid = int(info["frames"]), int(info["height"]), int(info["width"])
+        cmd = [
+            _ffmpeg(), "-v", "error", "-i", self._p(key, VIDEO_EXT),
+            "-f", "rawvideo", "-pix_fmt", "rgb48le", "-",
+        ]
+        want = n * hgt * wid * 3 * 2
+        # communicate(), not sequential reads: draining stdout to EOF while
+        # stderr is an unread pipe deadlocks the moment ffmpeg emits more than
+        # the pipe buffer on stderr -- which is exactly what a corrupt FFV1
+        # does, i.e. the one case where the error actually matters.
+        proc = subprocess.Popen(cmd, stdout=subprocess.PIPE, stderr=subprocess.PIPE)
+        raw, err_raw = proc.communicate()
+        err = err_raw.decode(errors="replace")
+        if proc.returncode != 0:
+            raise RuntimeError(f"{TAG}: FFV1 decode failed for hop {key}: {err.strip()}")
+        if len(raw) != want:
+            raise RuntimeError(
+                f"{TAG}: cached hop {key} is {len(raw)} bytes, expected {want}. "
+                f"Delete the cache entry and re-render.")
+        arr = np.frombuffer(raw, dtype="<u2").reshape(n, hgt, wid, 3)
+        imgs = torch.from_numpy(arr.astype(np.float32) / 65535.0)
+        wav = torch.from_numpy(np.load(self._p(key, AUDIO_EXT)))
+        os.utime(self._p(key, VIDEO_EXT), None)  # LRU touch
+        return imgs, wav, int(info["sample_rate"]), self._get_latent(key)
+
+    # -- shot locks -------------------------------------------------------
+    # A locked shot reuses whatever it last rendered even when its inputs
+    # change, so it needs a name that survives an edit -- the content key by
+    # definition does not. The pointer maps a stable shot name to the key that
+    # shot last produced.
+    def _ptr(self, name):
+        safe = "".join(c if c.isalnum() or c in "-_" else "_" for c in str(name))
+        return os.path.join(self.root, "ptr_" + safe + ".json")
+
+    def set_pointer(self, name, key):
+        with open(self._ptr(name), "w", encoding="utf-8") as fh:
+            json.dump({"key": key, "written": time.time()}, fh)
+
+    def get_pointer(self, name):
+        try:
+            with open(self._ptr(name), encoding="utf-8") as fh:
+                key = json.load(fh).get("key")
+        except (OSError, ValueError):
+            return None
+        return key if key and self.has(key) else None
+
+    # -- housekeeping -----------------------------------------------------
+    def entries(self):
+        out = []
+        for fn in os.listdir(self.root):
+            if not fn.endswith(VIDEO_EXT):
+                continue
+            key = fn[: -len(VIDEO_EXT)]
+            try:
+                st = os.stat(self._p(key, VIDEO_EXT))
+            except OSError:
+                continue
+            size = st.st_size
+            for e in (AUDIO_EXT, META_EXT, LATENT_EXT):
+                try:
+                    size += os.path.getsize(self._p(key, e))
+                except OSError:
+                    pass
+            out.append((key, size, st.st_mtime))
+        return out
+
+    def sweep(self, keep=()):
+        """Evict least-recently-used entries until under budget.
+
+        `keep` names hops this run still needs, so a budget smaller than one
+        chain cannot delete the hop that is about to be read back.
+        """
+        items = self.entries()
+        total = sum(s for _, s, _ in items)
+        if total <= self.budget:
+            return 0
+        keep = set(keep)
+        freed = 0
+        for key, size, _ in sorted(items, key=lambda r: r[2]):
+            if total - freed <= self.budget:
+                break
+            if key in keep:
+                continue
+            for e in (VIDEO_EXT, AUDIO_EXT, META_EXT, LATENT_EXT):
+                try:
+                    os.remove(self._p(key, e))
+                except OSError:
+                    pass
+            freed += size
+        if freed:
+            print(f"[{TAG}] cache: evicted {freed / 1024 ** 3:.2f} GB "
+                  f"(budget {self.budget / 1024 ** 3:.1f} GB)", flush=True)
+        return freed

tone.py

@@ -0,0 +1,276 @@
+"""Tone compensation for chained H3 segments.
+
+The H3 denoiser applies a tone bias to each generated segment, which shows up as
+a brightness step at the seam between hops. This module estimates that bias on
+the overlap -- the segment's first frames against the source frames they
+reconstruct -- and undoes it across the whole segment.
+
+The estimator, and the reasoning behind the three modes, is ported from
+`rkfg/ComfyUI-MiniMaxH3-ToneCompensate` (MIT). This pack is MIT too, so the code
+travels; the credit does not travel by itself, hence this paragraph. Changes
+from upstream: the overlap default is our 22 frames rather than his 48, `"off"`
+is a real mode so callers need no branch, and the math is split from the node so
+it can be tested without a running server (same reason `plan.py` and `refs.py`
+have no ComfyUI imports).
+
+The three modes, most to least specific:
+
+- frame_shift: per-frame per-channel additive shift. The target's first frames
+  are the model's regeneration of the source (similar content, not a pixel-wise
+  transform), so the bias is best captured as a per-frame shift of the mean.
+  Matches the overlap exactly and applies the last overlap frame's shift to the
+  continuation (no seam).
+- gain_bias:   global per-channel affine  s = A*g + C. Robust, extrapolates
+  cleanly; good when the drift is a roughly uniform shift/compression.
+- lut:         per-pixel piecewise-linear tone curve. Captures nonlinear drift;
+  flexible, but overfits when the target is regenerated content (pixels differ
+  from the source).
+
+Alignment: source's last `overlap` frames are paired with target's first
+`overlap` frames, so the whole previous segment can be passed as `source` and it
+auto-crops to the tail.
+"""
+from __future__ import annotations
+
+import torch
+
+TAG = "HTCTone"
+MODES = ["off", "frame_shift", "gain_bias", "lut"]
+
+_TABLE = 4096  # dense LUT resolution used when applying the lut mode
+
+# Our native overlap: 0.9 s at 24 fps, the H3 continuation length. Upstream
+# defaults to 48 (2 s) because that is what his workflow pins with.
+DEFAULT_OVERLAP = 22
+
+
+def _fit_affine(src, tgt):
+    """Regress source on generated per channel: s = A*g + C. Return (A, C) as [1,1,1,C]."""
+    c_out = src.shape[-1]
+    gain = torch.ones(1, 1, 1, c_out, dtype=torch.float32, device=src.device)
+    bias = torch.zeros(1, 1, 1, c_out, dtype=torch.float32, device=src.device)
+    for c in range(c_out):
+        s = src[..., c].reshape(-1).float()
+        g = tgt[..., c].reshape(-1).float()
+        gm = g.mean()
+        sm = s.mean()
+        dg = g - gm
+        den = (dg * dg).sum()
+        if den < 1e-12:
+            A, C = 1.0, float(sm - gm)
+        else:
+            A = float((dg * (s - sm)).sum() / den)
+            C = float(sm - A * gm)
+        if abs(A) < 1e-6:
+            A = 1.0
+        gain[0, 0, 0, c] = A
+        bias[0, 0, 0, c] = C
+    return gain, bias
+
+
+def _monotone(ys):
+    """Make ys non-decreasing (guards against bin-mean inversions from noise)."""
+    v = ys.tolist()
+    best = v[0]
+    out = []
+    for y in v:
+        if y > best:
+            best = y
+        out.append(best)
+    return torch.tensor(out, dtype=torch.float32, device=ys.device)
+
+
+def _lut_control(s, g, bins):
+    """Build per-channel control points from paired pixels.
+
+    For each generated-value bin that actually occurs, store (mean generated,
+    mean source). Using the means as x keeps boundary segments exact -- bin
+    centres would skew the outer slopes. Returns sorted (xs, ys).
+    """
+    dev = g.device
+    idx = torch.clamp(torch.floor(g * bins), 0, bins - 1).long()
+    sums_s = torch.zeros(bins, dtype=torch.float32, device=dev)
+    sums_g = torch.zeros(bins, dtype=torch.float32, device=dev)
+    counts = torch.zeros(bins, dtype=torch.float32, device=dev)
+    sums_s.index_add_(0, idx, s)
+    sums_g.index_add_(0, idx, g)
+    counts.index_add_(0, idx, torch.ones_like(idx, dtype=torch.float32))
+    nz = counts > 0
+    xs = (sums_g / counts)[nz]
+    ys = (sums_s / counts)[nz]
+    return xs, _monotone(ys)
+
+
+def _linfit(x, y):
+    """Least-squares line y = slope*x + intercept. Return (slope, intercept)."""
+    xm, ym = x.mean(), y.mean()
+    dx = x - xm
+    den = (dx * dx).sum()
+    if den < 1e-12:
+        return 0.0, ym.item()
+    slope = float((dx * (y - ym)).sum() / den)
+    return slope, float(ym - slope * xm)
+
+
+def _pwl(query, xs, ys):
+    """Piecewise-linear evaluation of the (xs, ys) control points at query.
+
+    The interior is interpolated; the ends extrapolate with a robust slope
+    (least-squares on the outermost K points) so a single noisy boundary bin
+    cannot skew the extrapolation.
+    """
+    n = xs.numel()
+    if n == 1:
+        return torch.full_like(query, ys.item())
+    k = min(5, n)
+    ls, lb = _linfit(xs[:k], ys[:k])
+    rs, rb = _linfit(xs[-k:], ys[-k:])
+    i = torch.clamp(torch.searchsorted(xs, query), 1, n - 1)
+    xl, xr = xs[i - 1], xs[i]
+    yl, yr = ys[i - 1], ys[i]
+    out = yl + (yr - yl) * (query - xl) / (xr - xl)
+    left, right = query < xs[0], query > xs[-1]
+    out = torch.where(left, ls * query + lb, out)
+    out = torch.where(right, rs * query + rb, out)
+    return out
+
+
+def _apply_lut(x, xs, ys, table=_TABLE):
+    """Apply a per-channel control LUT to x (values in [0,1])."""
+    dense = _pwl(torch.linspace(0, 1, table, device=x.device), xs, ys)
+    idx = torch.clamp(torch.floor(x * table), 0, table - 1).long()
+    return dense[idx]
+
+
+def compensate(source, target, mode, overlap=DEFAULT_OVERLAP, lut_bins=64):
+    """Correct `target`'s tone to match `source`. -> (images, note).
+
+    `source` is the previous segment (or just its tail); `target` is the whole
+    generated segment. Both float [N,H,W,3] in 0..1. Returns the corrected
+    target and a short human-readable note for the log, or (target, "") when
+    there is nothing to do.
+
+    `mode="off"` returns `target` untouched, so a caller can pass the widget
+    value straight through without branching on it. Anything unrecognised is
+    treated the same way rather than raising: a bad mode should not lose a
+    render that has already been sampled.
+    """
+    if mode is None or str(mode) == "off" or str(mode) not in MODES:
+        return target, ""
+    if source is None or target is None:
+        return target, ""
+
+    src = source.float()
+    tgt = target.float()
+    n = min(int(overlap), int(src.shape[0]), int(tgt.shape[0]))
+    if n <= 0:
+        return target, ""
+    fit_src = src[-n:]
+    fit_tgt = tgt[:n]
+
+    mode = str(mode)
+    if mode == "frame_shift":
+        # Per-frame per-channel drift (mean target - mean source), applied
+        # per-frame on the overlap and as the last overlap frame's value on the
+        # continuation -- which is what makes the seam itself exact.
+        drift = fit_tgt.mean(dim=(1, 2), keepdim=True) - fit_src.mean(dim=(1, 2), keepdim=True)
+        out = tgt.clone()
+        out[:n] = out[:n] - drift
+        out[n:] = out[n:] - drift[-1]
+        d = drift[-1].reshape(-1)
+        note = ("frame_shift " + " ".join(f"{c}{v:+.4f}" for c, v in zip("rgb", d.tolist())))
+    elif mode == "gain_bias":
+        gain, bias = _fit_affine(fit_src, fit_tgt)
+        out = gain * tgt + bias
+        g = gain.reshape(-1).tolist()
+        b = bias.reshape(-1).tolist()
+        note = ("gain_bias " + " ".join(f"{c}x{gv:.4f}{bv:+.4f}"
+                                        for c, gv, bv in zip("rgb", g, b)))
+    else:  # lut
+        out = torch.empty_like(tgt)
+        for c in range(tgt.shape[-1]):
+            xs, ys = _lut_control(fit_src[..., c].reshape(-1),
+                                  fit_tgt[..., c].reshape(-1), int(lut_bins))
+            out[..., c] = _apply_lut(tgt[..., c], xs, ys)
+        before = float(tgt.mean())
+        after = float(out.mean())
+        note = f"lut mean {before:.4f} -> {after:.4f} ({int(lut_bins)} bins)"
+
+    out = out.clamp_(0.0, 1.0).to(target.dtype)
+    return out, note
+
+
+class HTCToneCompensate:
+    """Undo the denoiser's tone bias on a generated H3 segment.
+
+    Wire it between two hand-chained H3 generations: `source` is the previous
+    segment, `target` the one to correct.
+
+    Note this cannot do the same job downstream of `HandTieClips`. That node joins
+    its hops internally and drops each hop's first `overlap` frames at the seam,
+    so the regenerated copies this estimator needs no longer exist by the time
+    images leave it. Use the chain node's own `tone_compensate` widget for that;
+    this node is for hand-built chains, and for A/B-ing the correction.
+    """
+
+    @classmethod
+    def INPUT_TYPES(cls):
+        return {
+            "required": {
+                "source": ("IMAGE", {"tooltip": "The previous segment. The whole thing is fine -- only its last `overlap` frames are read."}),
+                "target": ("IMAGE", {"tooltip": "The generated segment to correct."}),
+                "mode": (MODES, {
+                    "default": "frame_shift",
+                    "tooltip": (
+                        "frame_shift: per-frame additive shift; best when the target is "
+                        "regenerated content, which it is here. gain_bias: global affine, "
+                        "robust. lut: tone curve, captures nonlinear drift but overfits."
+                    ),
+                }),
+                "overlap": ("INT", {
+                    "default": DEFAULT_OVERLAP, "min": 1, "max": 4096,
+                    "tooltip": (
+                        "Number of keyframe frames: last `overlap` of source vs first "
+                        "`overlap` of target. Must equal the keyframe count used for "
+                        "generation (22 = 0.9 s @ 24 fps), NOT the whole segment."
+                    ),
+                }),
+                "lut_bins": ("INT", {
+                    "default": 64, "min": 16, "max": 512,
+                    "tooltip": "Aggregation bins for lut mode. Ignored otherwise.",
+                }),
+            }
+        }
+
+    RETURN_TYPES = ("IMAGE",)
+    RETURN_NAMES = ("images",)
+    FUNCTION = "run"
+    CATEGORY = "Hand Tie Clips"
+
+    def run(self, source, target, mode, overlap, lut_bins):
+        out, note = compensate(source, target, mode, overlap, lut_bins)
+        if note:
+            print(f"[{TAG}] {note}", flush=True)
+        return (out,)
+
+
+
+
+# -- pre-rename ids ----------------------------------------------------------
+# A plain alias in NODE_CLASS_MAPPINGS keeps old workflows loading, but it also
+# lists the node a second time in search: ComfyUI falls back to the mapping key
+# when NODE_DISPLAY_NAME_MAPPINGS has no entry. Subclassing and setting
+# DEPRECATED gets both -- server.py publishes `deprecated: True`, and the
+# frontend's `Comfy.Node.ShowDeprecated` (off by default) hides it from search
+# while leaving it fully functional in workflows that name it.
+
+
+class _LegacyH3ToneCompensate(HTCToneCompensate):
+    DEPRECATED = True
+
+
+NODE_CLASS_MAPPINGS = {
+    "HTCToneCompensate": HTCToneCompensate,
+    "H3ToneCompensate": _LegacyH3ToneCompensate,
+}
+NODE_DISPLAY_NAME_MAPPINGS = {"HTCToneCompensate": "H3 Tone Compensate"}

tools/build_notes.py

@@ -0,0 +1,119 @@
+"""Write the instruction board into the Starter workflow, in place.
+
+Idempotent: cards are identified by `properties.htc_card`, so re-running
+replaces the board rather than stacking a second copy beside it. Operates on the
+shipped `.json` itself rather than rebuilding from a private source workflow, so
+anyone with the pack can run it.
+
+It also strips `widgets_values_named` from every node. Both shipped workflows
+carried a stale copy inherited from the dev workflow they were cloned out of --
+`chains: 3`, `duration: 10 s`, `control_after_generate: randomize`, and a legacy
+`ref_plan` naming pictures that do not ship, 25 entries against a 28-widget node.
+It is dormant while `Comfy.Workflow.NamedValuesRestore` stays off (experimental,
+default false), but anyone who turns that on would load a Starter that randomizes
+its seed and dies on a missing reference. The frontend re-emits the block
+correctly on the next save.
+"""
+import io
+import json
+import os
+import shutil
+import sys
+
+HERE = os.path.dirname(os.path.dirname(os.path.abspath(__file__)))
+sys.path.insert(0, os.path.dirname(os.path.abspath(__file__)))
+
+import notes  # noqa: E402
+
+WF = os.path.join(HERE, "workflows", "HandTieClips_Starter.json")
+# The board is Starter-only, but the stale-named-values bug is in both shipped
+# workflows, so the strip runs over both.
+ALSO_STRIP = [os.path.join(HERE, "workflows", "HandTieClips_Showcase.json")]
+MARKER = "htc_card"
+FIRST_ID = 20
+
+
+def strip_named(path):
+    """Drop `widgets_values_named`, and refresh the Showcase's plain Note.
+
+    The Showcase carries one `Note` rather than the card board; its text lives
+    in `notes.SHOWCASE_NOTE` so there is still a single source for it.
+    """
+    wf = json.load(io.open(path, encoding="utf-8"))
+    n = sum(1 for node in wf["nodes"]
+            if node.pop("widgets_values_named", None) is not None)
+    for node in wf["nodes"]:
+        if node["type"] == "Note" and node.get("widgets_values") != [notes.SHOWCASE_NOTE]:
+            node["widgets_values"] = [notes.SHOWCASE_NOTE]
+            # The dependency block pushed it past what 400x700 shows without
+            # scrolling.
+            node["size"] = [440, 900]
+            n += 1
+    if n:
+        bak = path + ".bak-notes"
+        if not os.path.exists(bak):
+            shutil.copyfile(path, bak)
+        io.open(path, "w", encoding="utf-8", newline="\n").write(
+            json.dumps(wf, indent=2) + "\n")
+    return n
+
+
+def main():
+    wf = json.load(io.open(WF, encoding="utf-8"))
+
+    bak = WF + ".bak-notes"
+    if not os.path.exists(bak):
+        shutil.copyfile(WF, bak)
+
+    # Out with the old board, and with the single legacy `Note` whose text the
+    # cards now carry between them.
+    before = len(wf["nodes"])
+    wf["nodes"] = [n for n in wf["nodes"]
+                   if MARKER not in (n.get("properties") or {})
+                   and n["type"] != "Note"]
+    dropped = before - len(wf["nodes"])
+
+    order = max((n.get("order", 0) for n in wf["nodes"]), default=0)
+    for i, (key, title, pos, size, colour, text) in enumerate(notes.CARDS):
+        order += 1
+        wf["nodes"].append({
+            "id": FIRST_ID + i,
+            "type": "MarkdownNote",
+            "pos": list(pos),
+            "size": list(size),
+            "flags": {},
+            "order": order,
+            "mode": 0,
+            "inputs": [],
+            "outputs": [],
+            "title": title,
+            "properties": {MARKER: key},
+            "widgets_values": [text],
+            "color": colour[0],
+            "bgcolor": colour[1],
+        })
+
+    wf["groups"] = [dict(notes.GROUP)]
+    wf["extra"]["ds"] = dict(notes.DS)
+    wf["last_node_id"] = max(wf["last_node_id"], FIRST_ID + len(notes.CARDS) - 1)
+
+    stripped = 0
+    for n in wf["nodes"]:
+        if n.pop("widgets_values_named", None) is not None:
+            stripped += 1
+
+    io.open(WF, "w", encoding="utf-8", newline="\n").write(
+        json.dumps(wf, indent=2) + "\n")
+
+    print("%s\n  dropped %d old note/card node(s), wrote %d card(s)"
+          % (os.path.basename(WF), dropped, len(notes.CARDS)))
+    print("  stripped widgets_values_named from %d node(s)" % stripped)
+    print("  %d nodes, %d bytes" % (len(wf["nodes"]), os.path.getsize(WF)))
+
+    for path in ALSO_STRIP:
+        print("%s\n  stripped widgets_values_named from %d node(s)"
+              % (os.path.basename(path), strip_named(path)))
+
+
+if __name__ == "__main__":
+    main()

tools/build_speed_stack.py

@@ -0,0 +1,168 @@
+"""Wire the turbo stack onto both shipped workflows, matching the dev graph.
+
+    UNETLoader ->  LoRA Loader Stack  ->  H3 AdaLN LoRA Fix
+               ->  MiniMax H3 Low VRAM Attention
+               ->  H3 SLA Attention
+               ->  Model Preview Override (KJ)  ->  Hand Tie Clips
+
+and, off the same LoRA loader, **CLIP goes to the chain from the loader, not
+from the encoder** -- that is what makes the text half of every LoRA land.
+
+None of these five nodes belong to this pack. They are here because this is the
+graph the node is actually run with: `steps` is 7, which only works with a turbo
+LoRA, and the AdaLN fix exists because the LoRA needs it. Shipping the examples
+without them ships a graph nobody uses. Every dependency is named on the START
+HERE card, in the Showcase note and in the README.
+
+Idempotent: inserted nodes carry `properties.htc_speed`, so a re-run rewires
+rather than stacking a second copy. Widget values are POSITIONAL (CLAUDE.md) and
+are copied from the proven dev workflow rather than reconstructed.
+"""
+import io
+import json
+import os
+import shutil
+
+HERE = os.path.dirname(os.path.dirname(os.path.abspath(__file__)))
+WORKFLOWS = ["HandTieClips_Starter.json", "HandTieClips_Showcase.json"]
+MARKER = "htc_speed"
+
+TURBO_LORA = "minimax_h3_ref2v_turbo_4step_v0.1_comfyui_bf16.safetensors"
+LORA_STACK = json.dumps([{"on": True, "lora": TURBO_LORA,
+                          "str": 1, "v": 1, "a": 1, "t": 1}],
+                        separators=(",", ":"))
+
+# id, type, title, pos, size, widgets
+#
+# Widget order is INPUT_TYPES order with sockets skipped. The trailing "" on the
+# LoRA loader and the preview override is carried over from the dev workflow --
+# a value past the last widget is ignored, and dropping one that turns out to
+# belong to a widget would silently shift every value after it.
+STACK = [
+    ("lora", "LTX_lora_loader", "LoRA Loader Stack (turbo)",
+     [520, -40], [420, 240], ["minimax", LORA_STACK, ""]),
+    ("adaln", "H3AdaLNLoRAFix", "H3 AdaLN LoRA Fix",
+     [520, 240], [340, 150], ["port"]),
+    ("lowvram", "MiniMaxLowVRAMAttention", "MiniMax H3 Low VRAM Attention",
+     [520, 430], [330, 58], [4]),
+    # sparsity_ratio, block_size, min_seq_len, dense_last_steps, protect_audio,
+    # enabled, dense_steps, dense_backend, disable_fp16_accum, stabilize_motion,
+    # reference_protection -- the last one post-dates the dev workflow's saved
+    # values, so it is written out explicitly here.
+    ("sla", "H3SLAAttention", "H3 SLA Attention",
+     [520, 530], [340, 322],
+     [0.9, "64", 8192, 0, True, True, "0", "comfy_kitchen", True, True, "Light"]),
+    ("preview", "ModelPreviewOverrideKJ", "Model Preview Override",
+     [520, 900], [360, 480], [512, 80, True, 100, 8, "taeh3.safetensors", ""]),
+]
+FIRST_ID = 30
+
+MODEL_PATH = ["UNETLoader"] + [t for _, t, _, _, _, _ in STACK] + ["HandTieClips"]
+
+
+def main():
+    for fn in WORKFLOWS:
+        p = os.path.join(HERE, "workflows", fn)
+        bak = p + ".bak-speed"
+        if not os.path.exists(bak):
+            shutil.copyfile(p, bak)
+        wf = json.load(io.open(p, encoding="utf-8"))
+
+        # Drop any previous stack and every link that touched it.
+        old = {n["id"] for n in wf["nodes"]
+               if MARKER in (n.get("properties") or {})}
+        wf["nodes"] = [n for n in wf["nodes"] if n["id"] not in old]
+        wf["links"] = [l for l in wf["links"]
+                       if l[1] not in old and l[3] not in old]
+
+        unet = next(n for n in wf["nodes"] if n["type"] == "UNETLoader")
+        clipl = next(n for n in wf["nodes"] if n["type"] == "CLIPLoader")
+        chain = next(n for n in wf["nodes"] if n["type"] == "HandTieClips")
+        lid = max([l[0] for l in wf["links"]] or [0])
+
+        # Removing the stack also removed the wires that fed it, so rebuild the
+        # plain loader -> chain shape first. That makes this reentrant from
+        # either state: a fresh workflow or one already wired.
+        wf["links"] = [l for l in wf["links"]
+                       if not (l[3] == chain["id"] and l[4] in (0, 1))]
+        lid += 1
+        model_link = [lid, unet["id"], 0, chain["id"], 0, "MODEL"]
+        lid += 1
+        clip_link = [lid, clipl["id"], 0, chain["id"], 1, "CLIP"]
+        wf["links"] += [model_link, clip_link]
+
+        ids = {}
+        for i, (key, ntype, title, pos, size, widgets) in enumerate(STACK):
+            ids[key] = FIRST_ID + i
+            wf["nodes"].append({
+                "id": FIRST_ID + i, "type": ntype,
+                "pos": list(pos), "size": list(size),
+                "flags": {}, "order": 0, "mode": 0,
+                "inputs": [], "outputs": [],
+                "title": title,
+                "properties": {MARKER: key, "Node name for S&R": ntype},
+                "widgets_values": list(widgets),
+            })
+        byid = {n["id"]: n for n in wf["nodes"]}
+
+        def link(src, src_slot, dst, dst_slot, kind):
+            """Append one link and record it on both endpoints."""
+            nonlocal lid
+            lid += 1
+            wf["links"].append([lid, src, src_slot, dst, dst_slot, kind])
+            return lid
+
+        # MODEL, straight down the column.
+        model_link[3], model_link[4] = ids["lora"], 0
+        chain_model = model_link[0]
+        prev = ids["lora"]
+        for key in ("adaln", "lowvram", "sla", "preview"):
+            chain_model = link(prev, 0, ids[key], 0, "MODEL")
+            prev = ids[key]
+        chain_model = link(prev, 0, chain["id"], 0, "MODEL")
+
+        # CLIP through the LoRA loader, so the text half of every LoRA lands.
+        clip_link[3], clip_link[4] = ids["lora"], 1
+        chain_clip = link(ids["lora"], 1, chain["id"], 1, "CLIP")
+
+        # Sockets and slots, now that every link id exists.
+        byid[ids["lora"]]["inputs"] = [
+            {"name": "model", "type": "MODEL", "link": model_link[0]},
+            {"name": "clip", "type": "CLIP", "link": clip_link[0]},
+        ]
+        for key in ("adaln", "lowvram", "sla", "preview"):
+            byid[ids[key]]["inputs"] = [
+                {"name": "model", "type": "MODEL", "link": None}]
+        byid[ids["preview"]]["inputs"].append(
+            {"name": "vae", "type": "VAE", "link": None})
+
+        outs = {"lora": [("model", "MODEL"), ("clip", "CLIP")],
+                "adaln": [("MODEL", "MODEL")],
+                "lowvram": [("model", "MODEL")],
+                "sla": [("MODEL", "MODEL")],
+                "preview": [("MODEL", "MODEL")]}
+        for key, spec in outs.items():
+            byid[ids[key]]["outputs"] = [
+                {"name": nm, "type": ty, "links": []} for nm, ty in spec]
+
+        # Walk the finished link table back onto the endpoints.
+        for n in wf["nodes"]:
+            for o in n.get("outputs", []):
+                o["links"] = []
+        for l in wf["links"]:
+            src, sslot, dst, dslot = l[1], l[2], l[3], l[4]
+            byid[src]["outputs"][sslot]["links"].append(l[0])
+            byid[dst]["inputs"][dslot]["link"] = l[0]
+
+        wf["last_link_id"] = lid
+        wf["last_node_id"] = max(wf["last_node_id"], FIRST_ID + len(STACK) - 1)
+
+        io.open(p, "w", encoding="utf-8", newline="\n").write(
+            json.dumps(wf, indent=2) + "\n")
+        print("%s\n  MODEL: %s\n  CLIP : CLIPLoader -> LoRA Loader Stack -> "
+              "Hand Tie Clips (link %d)"
+              % (fn, " -> ".join(MODEL_PATH), chain_clip))
+
+
+if __name__ == "__main__":
+    main()

tools/check_prompts.py

@@ -0,0 +1,159 @@
+"""Pre-ship sanity: walk both shipped workflows' plans through the real code.
+
+Not a unit test -- it drives the same helpers `run()` drives, hop by hop, and
+asserts the invariants that have actually broken before:
+
+  * every `@tag` resolves, and nothing literal survives into the prompt;
+  * every `<Picture N>` on a hop is either the live frame or a plate that is
+    genuinely scheduled onto that hop;
+  * identity text is present on every hop 2+ of a chain with a register (the
+    chain_00057 failure);
+  * shot 1 carries subject definitions when there is a register, and no later
+    shot is a full H3 block;
+  * the last shot closes on settle/hold.
+
+It also REPORTS, without failing, any `<Subject N>` that reaches a continuation
+hop. `subject_definitions` is hop-1 material and each hop is an independent text
+encode, so such a token has no antecedent in its own conditioning.
+"""
+import io
+import json
+import os
+import re
+import sys
+import types
+
+PACK = os.path.dirname(os.path.dirname(os.path.abspath(__file__)))
+ROOT = os.path.dirname(os.path.dirname(PACK))
+sys.path.insert(0, ROOT)
+pkg = types.ModuleType("h3p")
+pkg.__path__ = [PACK]
+sys.modules["h3p"] = pkg
+
+from h3p import refs as R          # noqa: E402
+from h3p import plan as PL         # noqa: E402
+from h3p import directives as D    # noqa: E402
+from h3p import h3_ref_chain as H3  # noqa: E402
+
+FAIL = []
+NOTE = []
+
+
+def ck(label, ok, detail=""):
+    print("    %s %s%s" % ("ok  " if ok else "FAIL", label,
+                           ("  " + detail) if detail else ""))
+    if not ok:
+        FAIL.append(label)
+
+
+def widget_map(node):
+    names = [i["name"] for i in node["inputs"] if i.get("widget")]
+    names.insert(names.index("seed") + 1, "control_after_generate")
+    return dict(zip(names, node["widgets_values"]))
+
+
+for fn in ("HandTieClips_Starter.json", "HandTieClips_Showcase.json"):
+    p = os.path.join(PACK, "workflows", fn)
+    wf = json.load(io.open(p, encoding="utf-8"))
+    chain = next(n for n in wf["nodes"] if n["type"] == "HandTieClips")
+    wv = widget_map(chain)
+    print("\n%s" % fn)
+
+    plan = PL.parse_plan(wv["shot_plan"])
+    shots = plan["shots"] if isinstance(plan, dict) else plan
+    rp = R.parse_ref_plan(wv["ref_plan"])
+    refs, subs = rp["refs"], rp["subjects"]
+    wired = {r["slot"] for r in refs if r["file"]}
+    has_people = any(r["subject"] is not None for r in refs)
+
+    ck("shot count == chains", len(shots) == int(wv["chains"]),
+       "%d vs %s" % (len(shots), wv["chains"]))
+    warn = PL.check_coherence(shots)
+    ck("coherence clean", not warn, " | ".join(warn))
+    last_tail = (shots[-1].get("directives") or {}).get("tail")
+    ck("last shot closes", last_tail in ("settle", "hold"), repr(last_tail))
+
+    known = {r["tag"] for r in refs}
+    for i, shot in enumerate(shots):
+        beat = shot.get("beat") or ""
+        used = set(re.findall(r"@([A-Za-z0-9_]+)", beat))
+        active = R.active_refs(refs, i, wired)
+        ords = R.ordinals(active)
+        shift = 1 if i > 0 else 0            # live frame takes ordinal 1
+        hop_ords = {t: n + shift for t, n in ords.items()}
+        legal_pics = set(hop_ords.values()) | ({1} if i > 0 else set())
+
+        ck("hop %d every tag declared" % (i + 1), used <= known,
+           "unknown=%s" % sorted(used - known) if used - known else "")
+        try:
+            # Mirrors the node: names, not ordinals, from hop 2 on.
+            resolved = R.resolve_tags(
+                beat, hop_ords, R.subjects(refs), where="shot %d" % (i + 1),
+                declared=known,
+                subject_names=({k: (v or {}).get("name")
+                                for k, v in (subs or {}).items()}
+                               if i > 0 else None))
+        except Exception as exc:                      # noqa: BLE001
+            ck("hop %d tags resolve" % (i + 1), False, str(exc))
+            continue
+        ck("hop %d leaves no literal @tag" % (i + 1),
+           not re.search(r"@[A-Za-z0-9_]+", resolved))
+
+        # Same list tools/check_templates.py enforces. At cfg 1.0 with no
+        # negative branch every named concept is ADDED, so "None of the kitchen
+        # is visible" puts a kitchen in the encoder, and "she stops" is law 2.
+        hits = [w for w in (" no ", " not ", " never ", "n't", "without ",
+                            "stops ", "stop ", "silent", "silence", "none of ")
+                if w in (" " + beat.lower() + " ")]
+        ck("hop %d names nothing it wants absent" % (i + 1), not hits,
+           str(hits))
+
+        if i == 0:
+            prose = R.subject_prose(active, subs)
+            block = (prose + "\n\n" + resolved) if prose else resolved
+            if refs:
+                ck("hop 1 defines its subjects",
+                   ("subject_definitions:" in prose) if has_people else True,
+                   "%d chars of prose" % len(prose))
+        else:
+            id_ords = None
+            n_subj = None
+            if active:
+                id_ords = [hop_ords[r["tag"]] for r in active
+                           if r["subject"] is not None]
+                n_subj = len({r["subject"] for r in active
+                              if r["subject"] is not None}) or None
+            elif refs:
+                id_ords = []
+            cont = R.continuity_line(
+                subs, {r["subject"] for r in refs
+                       if r["subject"] is not None}) if refs else ""
+            block = H3._assemble_next(
+                resolved, live_picture=1, live_video=1,
+                n_stills=len(active), state_header="",
+                identity_ordinals=id_ords, n_subjects=n_subj,
+                tail=(shot.get("directives") or {}).get("tail"),
+                continuity=cont)
+
+            pics = {int(m) for m in re.findall(r"<Picture (\d+)>", block)}
+            ck("hop %d cites only scheduled plates" % (i + 1),
+               pics <= legal_pics,
+               "cited=%s legal=%s" % (sorted(pics), sorted(legal_pics)))
+            ck("hop %d is not a full H3 block" % (i + 1),
+               not D.is_full_h3_prompt(resolved))
+            if has_people:
+                ck("hop %d carries identity text" % (i + 1), bool(cont.strip()),
+                   "%d chars" % len(cont))
+            dangling = sorted(set(re.findall(r"<Subject (\d+)>", block)))
+            if dangling:
+                NOTE.append("%s hop %d: <Subject %s> with no definitions block "
+                            "on this hop" % (fn, i + 1, ">, <Subject ".join(dangling)))
+
+print()
+for n in NOTE:
+    print("NOTE  " + n)
+print()
+if FAIL:
+    print("%d FAILURE(S):\n  %s" % (len(FAIL), "\n  ".join(FAIL)))
+    raise SystemExit(1)
+print("SHIP CHECK: all clear (%d note%s)" % (len(NOTE), "" if len(NOTE) == 1 else "s"))

tools/check_templates.py

@@ -0,0 +1,110 @@
+"""Every shipped template must survive the real Python validators.
+
+A template that produced a plan the node rejects would be worse than no
+templates at all -- a first-time author would blame their own writing. This
+extracts the patterns out of templates.js rather than restating them, so the
+test cannot pass against a copy that has drifted.
+"""
+import io
+import json
+import re
+import sys
+import types
+
+import os
+HERE = os.path.dirname(os.path.dirname(os.path.abspath(__file__)))
+sys.path.insert(0, os.path.dirname(os.path.dirname(HERE)))
+pkg = types.ModuleType("h3p")
+pkg.__path__ = [HERE]
+sys.modules["h3p"] = pkg
+
+from h3p import plan as PL       # noqa: E402
+from h3p import directives as D  # noqa: E402
+
+SRC = io.open(os.path.join(HERE, "js", "editor", "templates.js"), encoding="utf-8").read()
+
+# shot("...beat, possibly + concatenated...", { key: "value", ... })
+# The required leading quote skips `function shot(beat, directives)`, which
+# otherwise matched and swallowed the first pattern's metadata as a beat.
+CALL = re.compile(r"\bshot\(\s*(\".+?)\s*,\s*(\{[^}]*\})\s*\)", re.S)
+STR = re.compile(r'"((?:[^"\\]|\\.)*)"')
+NAME = re.compile(r"([A-Za-z_][A-Za-z0-9_]*)\s*:")
+
+
+def js_string(expr):
+    """Join a run of concatenated double-quoted literals."""
+    parts = STR.findall(expr)
+    if not parts:
+        raise SystemExit("could not read a beat from: " + expr[:60])
+    return "".join(p.replace('\\"', '"').replace("\\\\", "\\") for p in parts)
+
+
+def js_object(expr):
+    return json.loads(NAME.sub(r'"\1":', expr))
+
+
+def main():
+    names = re.findall(r'name:\s*"([^"]+)"', SRC)
+    calls = CALL.findall(SRC)
+    print("templates.js: %d patterns, %d shots\n" % (len(names), len(calls)))
+    if not names or not calls:
+        print("FAIL: extracted nothing -- the file's shape changed")
+        return 1
+
+    fails = []
+    all_shots = []
+    for beat_expr, dir_expr in calls:
+        beat = js_string(beat_expr)
+        dirs = js_object(dir_expr)
+        all_shots.append({"beat": beat, "directives": dirs})
+
+        for axis, val in dirs.items():
+            if axis not in D.AXES:
+                fails.append("unknown axis %r" % axis)
+            elif val not in D.VOCAB[axis]:
+                fails.append("%s=%r is not in VOCAB" % (axis, val))
+
+        # Law 1: the prompt is additive, so a negation is never correct.
+        for bad in (" no ", " not ", " never ", "n't", "without ", "stops ",
+                    "stop ", "silent", "silence"):
+            if bad in beat.lower():
+                fails.append("beat contains %r: %s" % (bad, beat[:70]))
+
+    # Every pattern must parse as a plan on its own AND stacked together.
+    for label, shots in [("each pattern stacked", all_shots)]:
+        text = json.dumps({"shots": [
+            dict(s, id="s%d" % (i + 1)) for i, s in enumerate(shots)]})
+        try:
+            parsed = PL.parse_plan(text)
+            print("  ok    %s parses (%d shots)" % (label, len(parsed)))
+        except Exception as e:
+            fails.append("%s: %s" % (label, e))
+            print("  FAIL  %s: %s" % (label, e))
+            continue
+        warns = PL.check_coherence(parsed)
+        if warns:
+            print("  FAIL  coherence warnings:")
+            for w in warns:
+                print("        " + w)
+            fails.extend(warns)
+        else:
+            print("  ok    no coherence warnings across the whole stack")
+
+    # The last shot of any pattern that ends a chain must not be left `ongoing`.
+    closers = [s for s in all_shots
+               if (s["directives"].get("tail") in ("settle", "hold"))]
+    print("  ok    %d of %d shots close with settle/hold"
+          % (len(closers), len(all_shots)))
+
+    print()
+    if fails:
+        print("%d FAILURE(S):" % len(fails))
+        for f in fails:
+            print("  -", f)
+        return 1
+    print("all template checks passed")
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

tools/check_workflows.py

@@ -0,0 +1,233 @@
+"""Validate the two shipped workflows against the live node, not against a guess.
+
+Checks the things that actually break on someone else's machine: a node type
+that is not registered, a widget count that disagrees with INPUT_TYPES, a link
+that points at nothing, and a plan that does not survive the real parsers.
+"""
+import io
+import json
+import os
+import sys
+import types
+
+HERE = os.path.dirname(os.path.dirname(os.path.abspath(__file__)))
+# ComfyUI root is two levels above the pack. Derived, not hardcoded, so this
+# survives the folder being renamed or the checkout living somewhere else.
+sys.path.insert(0, os.path.dirname(os.path.dirname(HERE)))
+pkg = types.ModuleType("h3p")
+pkg.__path__ = [HERE]
+sys.modules["h3p"] = pkg
+
+from h3p import refs as R      # noqa: E402
+from h3p import plan as PL     # noqa: E402
+
+# The widget list straight from INPUT_TYPES, so this cannot drift from the node.
+from h3p import h3_ref_chain as H3   # noqa: E402
+
+CORE = {"UNETLoader", "CLIPLoader", "VAELoader", "CreateVideo", "SaveVideo",
+        "Note", "MarkdownNote"}
+OURS = {"HandTieClips", "HTCChainPreview"}
+# Declared dependencies, not accidents: the turbo stack this node is actually
+# run with. Anything outside these three sets is a pack the reader never asked
+# for and must not appear in a shipped example.
+DEPS = {"LTX_lora_loader": "ComfyUI-PlagueKind-Nodes",
+        "H3AdaLNLoRAFix": "ComfyUI-PlagueKind-Nodes",
+        "H3SLAAttention": "ComfyUI-PlagueKind-Nodes",
+        "MiniMaxLowVRAMAttention": "ComfyUI-KJNodes (experimental)",
+        "ModelPreviewOverrideKJ": "ComfyUI-KJNodes"}
+# The MODEL wire, in order, from the loader to the chain.
+MODEL_PATH = ["UNETLoader", "LTX_lora_loader", "H3AdaLNLoRAFix",
+              "MiniMaxLowVRAMAttention", "H3SLAAttention",
+              "ModelPreviewOverrideKJ", "HandTieClips"]
+# CLIP must reach the chain THROUGH the LoRA loader, or the text half of every
+# LoRA is silently dropped -- a wire that looks fine and costs you the LoRA.
+CLIP_PATH = ["CLIPLoader", "LTX_lora_loader", "HandTieClips"]
+FAIL = []
+
+
+def ck(label, ok, detail=""):
+    print("  %s  %s%s" % ("ok  " if ok else "FAIL", label,
+                          ("  " + detail) if detail else ""))
+    if not ok:
+        FAIL.append(label)
+
+
+SOCKET_TYPES = {"MODEL", "CLIP", "VAE", "IMAGE", "AUDIO", "LATENT",
+                "CONDITIONING", "VIDEO"}
+
+
+def widget_names():
+    """The flat widget list, in the order widgets_values is indexed by.
+
+    A widget is any input whose type is a primitive or a combo AND which is not
+    marked `forceInput` -- `continuity_state` is a STRING but arrives on a wire.
+    `seed` occupies TWO entries because the frontend appends
+    control_after_generate directly after it.
+    """
+    it = H3.HandTieClips.INPUT_TYPES()
+    names = []
+    for section in ("required", "optional"):
+        for name, spec in (it.get(section) or {}).items():
+            t = spec[0]
+            cfg = spec[1] if len(spec) > 1 else {}
+            if isinstance(t, str) and t in SOCKET_TYPES:
+                continue
+            if cfg.get("forceInput"):
+                continue
+            names.append(name)
+            if name == "seed":
+                names.append("control_after_generate")
+    return names
+
+
+def main():
+    expect = widget_names()
+    print("node declares %d widgets (control_after_generate included)\n"
+          % len(expect))
+
+    for fn in ("HandTieClips_Starter.json", "HandTieClips_Showcase.json"):
+        p = os.path.join(HERE, "workflows", fn)
+        print(fn)
+        wf = json.load(io.open(p, encoding="utf-8"))
+        nodes = wf["nodes"]
+        byid = {n["id"]: n for n in nodes}
+        types_used = {n["type"] for n in nodes}
+
+        allowed = CORE | OURS | set(DEPS)
+        ck("only core, this pack and declared deps", types_used <= allowed,
+           str(sorted(types_used - allowed)) if types_used - allowed
+           else "%d types" % len(types_used))
+        ck("no LoadImage", not any(n["type"] == "LoadImage" for n in nodes))
+
+        chain = next(n for n in nodes if n["type"] == "HandTieClips")
+
+        # The wires, walked link by link. A patch node that is present but
+        # bypassed round the side is the failure this catches -- it looks right
+        # on the canvas and does nothing.
+        def walk_wire(path, kind):
+            seen = [path[0]]
+            cur = next(n for n in nodes if n["type"] == path[0])
+            for _ in range(len(path)):
+                nxt = [l for l in wf["links"]
+                       if l[1] == cur["id"] and l[5] == kind]
+                if not nxt:
+                    break
+                cur = byid[nxt[0][3]]
+                seen.append(cur["type"])
+            return seen
+
+        m = walk_wire(MODEL_PATH, "MODEL")
+        ck("MODEL wire runs the whole turbo stack", m == MODEL_PATH,
+           " -> ".join(m))
+        c = walk_wire(CLIP_PATH, "CLIP")
+        ck("CLIP reaches the chain through the LoRA loader", c == CLIP_PATH,
+           " -> ".join(c))
+        ins = [i["name"] for i in chain["inputs"]]
+        dead = [i for i in ins
+                if i.startswith("ref_image_") and i != "ref_image_size"
+                or i in ("reference_video", "voice", "start_image")]
+        ck("no removed sockets", not dead, str(dead))
+        ck("widget count matches INPUT_TYPES",
+           len(chain["widgets_values"]) == len(expect),
+           "%d vs %d" % (len(chain["widgets_values"]), len(expect)))
+
+        wv = dict(zip(expect, chain["widgets_values"]))
+        ck("control_after_generate=fixed", wv["control_after_generate"] == "fixed")
+
+        # Links: every id referenced by a node must exist, and vice versa.
+        lids = {l[0] for l in wf["links"]}
+        used = set()
+        for n in nodes:
+            for i in n.get("inputs", []):
+                if i.get("link") is not None:
+                    used.add(i["link"])
+            for o in n.get("outputs", []):
+                used.update(o.get("links") or [])
+        ck("link table consistent", lids == used,
+           "table=%s used=%s" % (sorted(lids), sorted(used)))
+        ck("every link endpoint exists",
+           all(l[1] in byid and l[3] in byid for l in wf["links"]))
+        ck("all four sockets fed",
+           all(chain["inputs"][k]["link"] is not None for k in range(4)))
+
+        # The plans, through the real parsers.
+        shots = PL.parse_plan(wv["shot_plan"])
+        n_shots = len(shots["shots"]) if isinstance(shots, dict) else len(shots)
+        ck("shot plan parses", n_shots == int(wv["chains"]),
+           "%d shots, chains=%s" % (n_shots, wv["chains"]))
+
+        rp = R.parse_ref_plan(wv["ref_plan"])
+        refs = rp["refs"]
+        ck("ref plan parses", True, "%d refs" % len(refs))
+
+        # Every @tag in every beat must be declared, or the run dies at hop N.
+        declared = {r["tag"] for r in refs}
+        import re
+        body = [s["beat"] for s in (shots["shots"] if isinstance(shots, dict)
+                                    else shots)]
+        tags = set()
+        for b in body:
+            tags |= set(re.findall(r"@([A-Za-z0-9_]+)", b or ""))
+        ck("every @tag is declared", tags <= declared,
+           "undeclared=%s" % sorted(tags - declared) if tags - declared
+           else "tags=%s" % sorted(tags))
+
+        # And every declared tag must be active on the hops that use it.
+        bad = []
+        for hop, b in enumerate(body):
+            want = set(re.findall(r"@([A-Za-z0-9_]+)", b or ""))
+            active = R.active_refs(refs, hop, {r["slot"] for r in refs
+                                               if r["file"]})
+            have = set(R.ordinals(active)) | set(R.subjects(refs))
+            miss = want - have
+            if miss:
+                bad.append("hop %d: %s" % (hop + 1, sorted(miss)))
+        ck("every tag is scheduled onto the hops that use it", not bad,
+           "; ".join(bad))
+
+        warn = R.check(rp, {r["slot"] for r in refs if r["file"]})
+        ck("no register warnings", not warn, " | ".join(warn))
+
+        # Stale named values. Both shipped workflows once carried a copy
+        # inherited from the dev workflow they were cloned out of, describing a
+        # 3x10 s chain with a randomizing seed and references that do not ship.
+        # It is dormant while Comfy.Workflow.NamedValuesRestore stays off, which
+        # is exactly why it sat there unnoticed.
+        named = [n["type"] for n in nodes if "widgets_values_named" in n]
+        ck("no stale widgets_values_named", not named, str(sorted(set(named))))
+
+        # The on-canvas board, where there is one.
+        cards = [n for n in nodes if n["type"] == "MarkdownNote"]
+        if cards:
+            ck("every card is marked and non-empty",
+               all((n.get("properties") or {}).get("htc_card")
+                   and (n.get("widgets_values") or [""])[0].strip()
+                   for n in cards),
+               "%d cards" % len(cards))
+            groups = wf.get("groups") or []
+            ck("a group wraps the board", len(groups) == 1,
+               "%d groups" % len(groups))
+            if groups:
+                gx, gy, gw, gh = groups[0]["bounding"]
+                outside = [n["title"] for n in cards
+                           if not (gx <= n["pos"][0]
+                                   and gy <= n["pos"][1]
+                                   and n["pos"][0] + n["size"][0] <= gx + gw
+                                   and n["pos"][1] + n["size"][1] <= gy + gh)]
+                ck("the group encloses every card", not outside, str(outside))
+            # A card reaching past x=0 would sit on top of the loaders.
+            ck("the board stays left of the graph",
+               all(n["pos"][0] + n["size"][0] <= 0 for n in cards))
+
+        print("      %d nodes, %d links, %d KB\n"
+              % (len(nodes), len(wf["links"]), os.path.getsize(p) // 1024))
+
+    if FAIL:
+        print("%d FAILURE(S): %s" % (len(FAIL), ", ".join(FAIL)))
+        return 1
+    print("ALL PASS")
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

tools/gen_example.py

@@ -0,0 +1,83 @@
+"""Emit the prompt pack's worked example FROM the showcase workflow.
+
+Typing the example out by hand would give the pack a third copy of the same
+plan, free to drift from the one that is actually validated. This reads the
+shipped workflow, so the example and the example workflow are the same bytes.
+"""
+import io
+import json
+import os
+
+HERE = os.path.dirname(os.path.dirname(os.path.abspath(__file__)))
+WF = os.path.join(HERE, "workflows", "HandTieClips_Showcase.json")
+OUT = os.path.join(HERE, "prompt_pack", "EXAMPLE_6_HOP.md")
+
+wf = json.load(io.open(WF, encoding="utf-8"))
+# Both ids: the pack registers the pre-rename `HandTieClips` as an alias, so a
+# workflow saved before 2026-08-29 is still a legal input here.
+CHAIN_TYPES = ("HandTieClips", "HandTieClips")
+chain = next(n for n in wf["nodes"] if n["type"] in CHAIN_TYPES)
+names = [i["name"] for i in chain["inputs"] if i.get("widget")]
+names.insert(names.index("seed") + 1, "control_after_generate")
+wv = dict(zip(names, chain["widgets_values"]))
+
+shot = json.loads(wv["shot_plan"])
+ref = json.loads(wv["ref_plan"])
+
+# The schedule, derived rather than described, so the table cannot lie.
+rows = []
+for i, s in enumerate(shot["shots"], start=1):
+    active = [r["tag"] for r in ref["refs"]
+              if r.get("shots") is None or i in r["shots"]]
+    rows.append("| %d | %s | %s |" % (
+        i, s["id"], ", ".join("@" + t for t in active) or "**none**"))
+
+body = """# Worked example: six hops, three pictures
+
+This is the plan inside `workflows/HandTieClips_Showcase.json`, reproduced here so
+it can be shown to a model as an example of the shape and the reasoning. It is
+generated from that workflow, so the two cannot drift apart.
+
+The scene: a cook in a kitchen speaks a line, crosses the room, leaves through a
+doorway into a hallway the register has no picture of, speaks again there, and
+comes back.
+
+## What each hop is for
+
+| hop | id | references active |
+|---|---|---|
+%s
+
+Three things in that table are the whole point:
+
+- **Hop 3** carries the kitchen while she is leaving it, and hop 4 does not.
+  The hallway is a space no reference describes, so the model must invent it —
+  and a kitchen plate riding hop 4 would drag her back into the kitchen.
+- **Hop 4** re-asserts the face. Entering an unseen space is where identity
+  drift starts, and re-asserting there is cheaper than recovering on 5 and 6.
+- **Hop 5 has no references at all.** Identity, wardrobe and voice ride on the
+  frame pin plus `subjects.1.locked` and `.context` alone. If she is still the
+  same person in the same apron with the same voice, the register works.
+
+Note also that the dialogue lands on hops 1 and 5 — the establishing shot and
+the one with no pictures — and that both use single quotes.
+
+## shot_plan
+
+```json
+%s
+```
+
+## ref_plan
+
+```json
+%s
+```
+""" % ("\n".join(rows),
+       json.dumps(shot, indent=2, ensure_ascii=False),
+       json.dumps(ref, indent=2, ensure_ascii=False))
+
+io.open(OUT, "w", encoding="utf-8", newline="\n").write(body)
+print("wrote %s (%d bytes)" % (OUT, len(body)))
+non_ascii = [c for c in body if ord(c) > 127]
+print("non-ASCII in output:", sorted(set(non_ascii)) or "none")

tools/gen_schema.py

@@ -0,0 +1,240 @@
+"""Generate `prompt_pack/SCHEMA.json` from the node's own constants.
+
+A hand-written schema is a second source of truth that starts drifting the day
+someone adds a camera move. This one reads `directives.VOCAB`, `refs.RETENTION`,
+`plan._SHOT_KEYS` and the duration table directly, so it can only ever describe
+the node that is actually installed.
+
+    python tools/gen_schema.py            # write prompt_pack/SCHEMA.json
+    python tools/gen_schema.py --check    # exit 1 if it is out of date (CI)
+
+Run it with ComfyUI's interpreter -- importing the node pulls in torch.
+"""
+import argparse
+import io
+import json
+import os
+import sys
+import types
+
+HERE = os.path.dirname(os.path.dirname(os.path.abspath(__file__)))
+OUT = os.path.join(HERE, "prompt_pack", "SCHEMA.json")
+
+
+def _load():
+    """Import the pack as a package without needing it to be installed."""
+    root = os.path.dirname(os.path.dirname(HERE))   # .../ComfyUI
+    if root not in sys.path:
+        sys.path.insert(0, root)
+    name = "_h3schema"
+    pkg = types.ModuleType(name)
+    pkg.__path__ = [HERE]
+    sys.modules[name] = pkg
+    mod = __import__(name + ".directives", fromlist=["directives"])
+    d = sys.modules[name + ".directives"]
+    r = __import__(name + ".refs", fromlist=["refs"])
+    r = sys.modules[name + ".refs"]
+    p = __import__(name + ".plan", fromlist=["plan"])
+    p = sys.modules[name + ".plan"]
+    return d, r, p, mod
+
+
+def build():
+    d, r, p, _ = _load()
+
+    # The duration labels, read from the node so the two cannot disagree. The
+    # import is late and guarded because it pulls torch in.
+    try:
+        from _h3schema import h3_ref_chain as node   # noqa: F401
+        durations = list(node.DURATION_FRAMES)
+        frames = dict(node.DURATION_FRAMES)
+    except Exception:                                # pragma: no cover
+        durations, frames = [], {}
+
+    directives = {
+        axis: {
+            "type": "string",
+            "enum": sorted(vals),
+            "description": " | ".join(f"{k}: {v}" for k, v in vals.items()),
+        }
+        for axis, vals in d.VOCAB.items()
+    }
+    for axis, spec in directives.items():
+        if axis in d.DEFAULTS:
+            spec["default"] = d.DEFAULTS[axis]
+
+    shot = {
+        "type": "object",
+        "required": ["beat"],
+        "additionalProperties": False,
+        "properties": {
+            "id": {"type": "string",
+                   "description": "Stable name. Generated if absent."},
+            "beat": {"type": "string",
+                     "description": "What happens THIS hop. Shot 1 is the whole "
+                                    "opening; every later shot is only the new "
+                                    "beat."},
+            "directives": {
+                "type": "object", "additionalProperties": False,
+                "properties": directives,
+                "description": "Compiled in the order " + ", ".join(d.AXES) +
+                               ". `join` is ignored on shot 1.",
+            },
+            "prose": {"type": "string",
+                      "description": "Appended verbatim, for anything the "
+                                     "vocabulary lacks. Phrase it affirmatively."},
+            "seed": {"type": "integer"},
+            "steps": {"type": "integer"},
+            "duration": {"type": "string", "enum": durations},
+            "locked": {"type": "boolean",
+                       "description": "Reuse this hop's cached render even when "
+                                      "its inputs changed. Needs cache_hops=on."},
+        },
+    }
+    assert set(shot["properties"]) == set(p._SHOT_KEYS), (
+        "schema and plan._SHOT_KEYS disagree: "
+        f"{sorted(set(shot['properties']) ^ set(p._SHOT_KEYS))}")
+
+    ref = {
+        "type": "object",
+        "required": ["tag"],
+        "additionalProperties": False,
+        "properties": {
+            "tag": {"type": "string", "pattern": "^[A-Za-z0-9_]+$",
+                    "description": "Unique. Written into beats as @tag."},
+            "file": {"type": "string",
+                     "description": "Basename under ComfyUI/input/h3_refs. "
+                                    "Never a path."},
+            "slot": {"type": "integer",
+                     "description": "Derived from list position. Do not author "
+                                    "it; present only for legacy plans."},
+            "subject": {"type": "integer", "minimum": 1,
+                        "description": "Groups pictures OF THE SAME PERSON. Two "
+                                       "different people under one number makes "
+                                       "the model render the average of their "
+                                       "faces."},
+            "retention": {"type": "string", "enum": sorted(r.RETENTION),
+                          "description": " | ".join(f"{k}: {v}" for k, v
+                                                    in r.RETENTION.items())},
+            "desc": {"type": "string"},
+            "shots": {
+                "type": "array", "items": {"type": "integer", "minimum": 1},
+                "minItems": 1,
+                "description": "1-based hops this picture rides on. OMITTING IT "
+                               "MEANS HOP 1 ONLY on a continuation chain -- a "
+                               "plate shot elsewhere riding a later hop beats "
+                               "the frame pin.",
+            },
+        },
+    }
+    assert set(ref["properties"]) == set(r.REF_FIELDS), (
+        "schema and refs.REF_FIELDS disagree: "
+        f"{sorted(set(ref['properties']) ^ set(r.REF_FIELDS))}")
+
+    subject = {
+        "type": "object", "additionalProperties": False,
+        "properties": {
+            "name": {"type": "string"},
+            "locked": {"type": "string",
+                       "description": "What must not change. This is what "
+                                      "survives on a hop where the photograph "
+                                      "is absent."},
+            "context": {"type": "string",
+                        "description": "Situational state that should persist "
+                                       "-- wardrobe, what they are holding."},
+        },
+    }
+    assert set(subject["properties"]) == set(r.SUBJECT_FIELDS)
+
+    return {
+        "$schema": "https://json-schema.org/draft/2020-12/schema",
+        "title": "H3 Ref Chain plans",
+        "description":
+            "Two documents. `shot_plan` goes in the shot_plan widget, `ref_plan` "
+            "in the ref_plan widget. Generated by tools/gen_schema.py from the "
+            "installed node -- do not edit by hand.",
+        "type": "object",
+        "properties": {
+            "shot_plan": {
+                "type": "object",
+                "required": ["shots"],
+                "additionalProperties": False,
+                "properties": {
+                    "shots": {"type": "array", "minItems": 1, "items": shot,
+                              "description": "One shot per hop. The shot count "
+                                             "IS the hop count."},
+                },
+            },
+            "ref_plan": {
+                "type": "object",
+                "required": ["refs"],
+                "additionalProperties": False,
+                "properties": {
+                    "refs": {"type": "array", "items": ref,
+                             "maxItems": r.MAX_REF_IMAGES,
+                             "description": f"At most {r.MAX_REF_IMAGES} "
+                                            f"pictures on any one hop."},
+                    "subjects": {
+                        "type": "object",
+                        "patternProperties": {"^[0-9]+$": subject},
+                        "additionalProperties": False,
+                        "description": "Keyed by subject number, as a STRING. "
+                                       "Every subject here must be claimed by "
+                                       "at least one ref, or the plan is "
+                                       "rejected.",
+                    },
+                },
+            },
+        },
+        "x-duration-frames": frames,
+        "x-rules": [
+            "cfg is 1.0 with no negative branch: the prompt is ADDITIVE. "
+            "Anything named is added; nothing can be removed by mentioning it. "
+            "Never write a negation.",
+            "Never name the thing you want to end. 'stops talking' keeps them "
+            "talking. Write the state as a pose plus a sound.",
+            "H3 always generates audio. Silence must be written AS a sound -- "
+            "room tone, a refrigerator, a single click.",
+            "Ambience must be narrowband. 'faint street noise' renders as hiss; "
+            "'the low hum of the refrigerator' renders as a refrigerator.",
+            "A state change belongs at the END of the previous shot. Every hop "
+            "opens holding the frames it was handed.",
+            "Shot 1 establishes everything. Later shots carry ONLY the new "
+            "beat -- never re-describe the face, the clothes or the room.",
+            "Write @tags into the action line. Describing a reference in the "
+            "register does not make the model use it.",
+            "Set `tail` to settle or hold on the FINAL shot, or the model is "
+            "told action is still underway at the last frame and invents "
+            "something to satisfy it.",
+        ],
+    }
+
+
+def main():
+    ap = argparse.ArgumentParser()
+    ap.add_argument("--check", action="store_true",
+                    help="exit 1 if the file on disk is out of date")
+    args = ap.parse_args()
+
+    text = json.dumps(build(), indent=2, ensure_ascii=False) + "\n"
+
+    if args.check:
+        try:
+            have = io.open(OUT, encoding="utf-8").read()
+        except OSError:
+            print("SCHEMA.json is missing")
+            return 1
+        if have != text:
+            print("SCHEMA.json is out of date; run tools/gen_schema.py")
+            return 1
+        print("SCHEMA.json is current")
+        return 0
+
+    os.makedirs(os.path.dirname(OUT), exist_ok=True)
+    io.open(OUT, "w", encoding="utf-8", newline="\n").write(text)
+    print("wrote %s (%d bytes)" % (OUT, len(text)))
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

tools/notes.py

@@ -0,0 +1,376 @@
+"""The instruction board that ships on the Starter workflow's canvas.
+
+One source for six `MarkdownNote` cards laid out to the left of the loaders.
+`build_notes.py` writes them into `workflows/HandTieClips_Starter.json`.
+
+Why on the canvas at all: the craft lives in `PROMPTING.md`, `prompt_pack/` and
+the editor's Templates panel, and all three require leaving the graph. The rules
+that decide whether a first render works are needed at the moment beats are being
+written, which is on the canvas.
+
+This is a condensation, not a copy. `PROMPTING.md` stays the long-form authority
+and every card says so; what is here is the part needed to get a first render
+right. Keep the cards short enough to read at a glance -- a wall of text on the
+canvas is the same as no text on the canvas.
+
+Layout: two columns of three at x=-960 and x=-480, 440 wide, so the board ends at
+x=-40 and the loaders (which start at x=0) are untouched. Reading order is down
+column A, then down column B.
+"""
+
+YELLOW = ("#432", "#653")     # what the existing Note uses
+GREEN = ("#232", "#353")      # ComfyUI's green -- card 1 only, so the entry
+                              # point is unmistakable in a wall of yellow
+
+GROUP = {
+    "id": 1,
+    "title": "READ ME -- writing for this node",
+    "bounding": [-990, -465, 980, 2560],
+    "color": "#3f789e",
+    "font_size": 24,
+}
+
+# `extra.ds` is restored on load rather than fitted, so without this the board
+# sits off-screen to the left and is never found. Screen = (world + offset) *
+# scale, so an offset of 500 puts world x=-500 at the left edge: column B, the
+# loaders and the left of the chain node all in view at once.
+DS = {"scale": 0.8264462809917354, "offset": [500, -281.1386834420914]}
+
+
+START_HERE = """\
+## Start here
+
+Two hops of 5 s, joined into one 10 s clip.
+
+### Requires
+
+The MODEL wire is a turbo stack, not a bare loader:
+
+```
+UNETLoader
+  -> LoRA Loader Stack          (turbo LoRA)
+  -> H3 AdaLN LoRA Fix
+  -> MiniMax H3 Low VRAM Attention
+  -> H3 SLA Attention
+  -> Model Preview Override
+  -> this node
+```
+
+| pack | nodes |
+|---|---|
+| **ComfyUI-PlagueKind-Nodes** | LoRA Loader Stack, AdaLN Fix, SLA Attention |
+| **ComfyUI-KJNodes** | Low VRAM Attention (experimental), Model Preview Override |
+
+Also on disk: the **turbo LoRA** named in the loader, and `taeh3.safetensors`
+for the live preview (or set `tiny_vae` to `none`).
+
+**CLIP goes to this node from the LoRA loader, not from the encoder.** That is
+what makes the text half of every LoRA land. Do not rewire it back.
+
+`steps` is **7**, which only works with the turbo LoRA. Missing a pack? Its
+nodes load as red boxes -- delete them, wire the loader straight into `model`
+and the encoder into `clip`, and raise `steps` to 20 or so.
+
+1. Point the four **loaders** at your H3 files.
+2. Queue.
+3. Read the **SHOTS** cards on the node.
+
+**Shot 1 is the whole opening. Every later shot is only the new beat.** The node
+writes the identity lock, the live-frame citation and the join itself -- so
+re-describing the face, the clothes or the room after shot 1 competes with the
+frame pin instead of reinforcing it.
+
+This plan ships with **no references on purpose**, so it runs before you have
+supplied any pictures.
+
+### Adding pictures
+
+- Open **REFERENCES**, add a row, drop a photo on its thumbnail. Files land in
+  `ComfyUI/input/h3_refs`. There is no Load Image node to wire.
+- Give the row a `@tag`, and group photos of the same person under one subject.
+- Write the tag into the beat: `@hero_face stands at the counter in @kitchen`.
+
+The long-form guide is `PROMPTING.md` in the pack folder.\
+"""
+
+
+RULES = """\
+## The rules that decide whether it works
+
+Not style preferences. This is how this model fails.
+
+### 1. The prompt is additive
+
+Sampling runs at **cfg 1.0 with no negative branch**. Every concept you name is
+added, and nothing can be removed by mentioning it -- `no cut` puts the word
+*cut* in front of the encoder. **Never write a negation.**
+
+### 2. Never name the thing you want to end
+
+"The cook stops talking" keeps her talking. Write the state you want as **a pose
+plus a sound**:
+
+> leans back against the counter with her lips closed, and lets her eyes move
+> slowly across the room. The kitchen is quiet apart from the low hum of the
+> refrigerator.
+
+Audio is always generated. Silence written as an absence comes back as speech,
+so **silence has to be written as a sound** -- room tone, a fridge, a single
+click. Keep it narrowband: "faint street noise" renders as a five-second hiss.
+
+**The ban is on the idea, not on a word list.** *Fades, passes, wanes, subsides,
+dies down, eases off* all name an ending as surely as *stops* does, and all of
+them add the thing they describe. Ask of each sentence: is this happening, or
+has it finished happening?
+
+### 3. A state change belongs at the END of the previous shot
+
+Every hop opens holding the frames it was handed, and the audio pin carries the
+previous hop's tail across the join. Nothing you write in shot 3 can make shot 3
+start quiet. **Arrive there before the previous shot ends.**
+
+### 4. A hop that ends on dialogue keeps talking
+
+Speech at the end of hop N opens hop N+1 and propagates down the whole chain.
+Land each line **mid-hop** and leave a non-verbal action running into the seam --
+slicing, walking, a hand on a doorframe. Give every hop with no dialogue a sound
+bed of its own.
+
+### 5. A walk between two rooms is `match_cut`
+
+`join: continuous` across a real location change makes the model morph one room
+into the other mid-movement.
+
+### 6. Set `tail` on your last shot
+
+Left at `ongoing`, the model is told action is still underway at the final frame
+and will invent something to satisfy it. Use `settle` or `hold`.\
+"""
+
+
+REFERENCES = """\
+## References and @tags
+
+A picture in the register does not make the model use it. **The beat is what
+drives the frame** -- write the tag into the action line.
+
+Phrase a place as a place that is *depicted*, not as a container to be placed
+inside: "at the counter in `@kitchen`", not "steps into `@kitchen`".
+
+### Fields
+
+| field | what it does |
+|---|---|
+| `tag` | what you write in beats as `@tag` |
+| `file` | a bare filename in `input/h3_refs` |
+| `subject` | groups pictures **of the same person** |
+| `retention` | `fully_preserved` / `partially_copy` / `reference` |
+| `shots` | the 1-based hops this picture rides |
+
+**One subject number per person.** Two different people under one number makes
+the model render the average of their faces.
+
+### `shots` is the part that decides continuity
+
+**A reference with no `shots` list rides hop 1 only.** Right for a **place**
+plate: a room still riding a hop set somewhere else beats the frame pin, and the
+model follows the still. **List every hop a picture belongs on.**
+
+**A face plate is the opposite — put it on every hop.** A hop scheduled with no
+face reference came back a different person, and no later hop recovered.
+Identity drift does not self-correct.
+
+- Every **face** ref gets every hop: `"shots": [1, 2, 3, 4, 5, 6]`.
+- Keep a **place** ref on the hops set in that place, and off the rest.
+
+### `locked` and `context`
+
+Per-subject prose that rides **every hop**, with no picture citation, so it
+carries identity across a hop where the photograph is absent. Give every subject
+a `locked`, and a `name` -- from hop 2 on, `@tag` for a person resolves to that
+name.
+
+**Name a colour or it drifts.** A noun with no adjective is unanchored: each hop
+is an independent encode, so "the bowl" on hop 4 came back stainless steel. Put
+properties in `context` -- "the bowl is white porcelain" -- never locations, and
+repeat the adjective in every beat.\
+"""
+
+
+DIRECTIVES = """\
+## Directives
+
+Five axes, all optional, set per shot. An unset axis emits nothing at all and
+costs no tokens.
+
+| axis | values |
+|---|---|
+| `join` | `continuous`, `match_cut`, `hard_cut` -- **omit on shot 1** |
+| `camera` | `hold`, `pan_follow`, `push_in`, `pull_back`, `orbit`, `handheld` |
+| `framing` | `keep`, `wide`, `medium`, `close` |
+| `pace` | `slow`, `steady`, `brisk` |
+| `tail` | `ongoing` (default), `settle`, `hold` |
+
+They compile in that order -- `join` first, because it describes how this hop
+meets the previous one.
+
+### Two combinations the node warns about
+
+**`join: continuous` + a framing change + `camera: hold`.** A framing change asks
+the audience to be somewhere new; with the camera still, the only way there is a
+cut. Earn it on the move (`push_in`, `pull_back`, `pan_follow`) or use
+`framing: keep`.
+
+**`push_in` + `wide`, or `pull_back` + `close`.** The move points the opposite way
+from the destination.
+
+Both are warnings, not errors. They are legitimate things to want -- they just
+rarely read the way you meant.
+
+### Duration
+
+Per-shot `duration` overrides the chain, using exactly these labels:
+`"5 s"`, `"7 s"`, `"8 s"`, `"10 s"`, `"15 s"`.\
+"""
+
+
+TROUBLE = """\
+## When it goes wrong
+
+| symptom | cause | fix |
+|---|---|---|
+| The clip cuts to the reference photo in its last seconds | The beat finished before the frames did | Set `tail`, give the beat enough to do |
+| A stray gesture or line in the closing second | `tail: ongoing` on the final shot | `settle` or `hold` |
+| She keeps talking after you asked for quiet | You named the ending | Pose plus a sound |
+| Dialogue continues into hops that have none written | The hop before ended on speech | Land the line early; non-verbal action into the seam; a sound bed on every quiet hop |
+| A character walks between two rooms and one morphs into the other | `continuous` across a location change | `match_cut` |
+| Silence renders as speech | Silence written as an absence | Name room tone, a fridge, a distant car |
+| Ambience is a five-second hiss | Broadband wording | Narrowband, or one discrete event |
+| Two characters' faces merge | Both declared as the same `subject` | One subject number per person |
+| The face becomes a different person partway through | A hop scheduled with no face plate. `locked` holds a face that is still right; only a plate rebuilds one that is gone, and the drift never self-corrects | Put the face ref on **every** hop |
+| A stylised plan renders photoreal | The node's hop-1 establishing line asserts live action | Name the medium in shot 1's first sentence, or clear the `establish` widget |
+| The film gets darker every hop | Luminance drifts one way and nothing pushes back | Restate the light as a positive property in every beat |
+| A location introduced mid-plan drifts | It has no place plate of its own | Plate it, on the hop it arrives and every hop after |
+| A prop or garment changes colour or material | Named with no adjective, so each hop's encode is free to invent one | Repeat the adjective in every beat, and state it as a property in `context` |
+| A hard cut ~1.5 s into a hop, mid-scene | The previous hop over-delivered, so this beat instructs what its own live frame already did | One movement per hop; write the next beat so it is true from either ending |
+| A continuous join reads as a cut | Framing change with `camera: hold` | Earn it on the move, or `framing: keep` |
+| The run stops, naming a reference | That row's picture is not in `h3_refs` | Drop the file on the row, or clear its picture to run without it |
+| A reference has no effect on some hop | Its `shots` list leaves that hop out | List every hop the picture should ride |
+| A pasted plan is rejected as invalid JSON | Escaped double quotes mangled in transit | Single quotes around dialogue |
+
+Every error message names the shot or the reference it came from. Nothing
+guesses.\
+"""
+
+
+AUTHOR = """\
+## Let a model write your plan
+
+`prompt_pack/` in the pack folder turns any chat model into a plan writer. In
+LM Studio, or anything with a system-prompt box:
+
+1. Load a model with **context 8192 or more**. The prompt is ~2,600 tokens and
+   the reply another 1,000-2,000; a 4k window truncates the rules and you get
+   invented directive names.
+2. Paste **`prompt_pack/SYSTEM_PROMPT.md`** into the **System Prompt** box.
+   Nothing else goes in that box.
+3. **Temperature 0.3-0.5.** Higher and the JSON grows trailing commas and smart
+   quotes.
+4. Describe the scene, and say how many hops and what pictures you have:
+
+   > Six hops. A cook in a kitchen; she says one line, walks out into a hallway,
+   > waits by a window, then comes back. I have a face photo, a photo of her
+   > apron, and a photo of the kitchen.
+
+5. Each panel section has its own **JSON** disclosure at the bottom. The first
+   ```json``` block goes in the one under **SCRIPT** (`shot_plan`), the second
+   in the one under **REFERENCES** (`ref_plan`). Bad JSON keeps the last good
+   version on screen and says so, rather than discarding your paste.
+6. **If the node rejects it, paste the error straight back into the chat.** One
+   round trip usually fixes it.
+
+Want it to match a shape? Paste `prompt_pack/EXAMPLE_6_HOP.md` first.
+
+Small models (7B-8B) hold the JSON schema but drift on the prose rules -- they
+write negations. Skim the beats before queueing.\
+"""
+
+
+SHOWCASE_NOTE = """\
+Hand Tie Clips -- SHOWCASE (6 hops x 7 s = 39.2 s)
+
+A continuity stress test, and the honest demonstration of what the reference
+register buys you.
+
+REQUIRES a turbo stack on the MODEL wire, which is how this node is actually
+run here:
+
+    UNETLoader -> LoRA Loader Stack (turbo LoRA) -> H3 AdaLN LoRA Fix
+               -> MiniMax H3 Low VRAM Attention -> H3 SLA Attention
+               -> Model Preview Override -> this node
+
+    ComfyUI-PlagueKind-Nodes  ->  LoRA Loader Stack, AdaLN Fix, SLA Attention
+    ComfyUI-KJNodes           ->  Low VRAM Attention (experimental),
+                                  Model Preview Override
+
+On disk as well: the turbo LoRA named in the loader, and taeh3.safetensors for
+the live preview (or set tiny_vae to none).
+
+CLIP reaches this node FROM THE LORA LOADER, not from the encoder. That is what
+makes the text half of every LoRA land. Do not rewire it back.
+
+`steps` is 7, which only works with the turbo LoRA. Missing a pack? Its nodes
+load as red boxes -- delete them, wire the loader straight into `model` and the
+encoder into `clip`, and raise `steps` to 20 or so.
+
+BEFORE YOU RUN IT, supply three pictures. Open REFERENCES on the node and drop
+your own onto each thumbnail, or put files in ComfyUI/input/h3_refs named:
+
+    ref_face.jpg     head-and-shoulders, even light   -> @hero_face
+    ref_outfit.jpg   full length, same person         -> @hero_outfit
+    ref_room.jpg     the room, wide                   -> @kitchen
+
+Without them the run stops and names the reference it could not find. Nothing
+guesses.
+
+What each hop is testing:
+
+  1  kitchen, dialogue           all three references active
+  2  lateral move to the window  kitchen only
+  3  exits through the doorway   kitchen only
+  4  hallway - UNSEEN space      face re-asserted; no room reference exists
+  5  dialogue, ZERO references   identity, wardrobe and voice ride on the frame
+                                 pin plus subjects.1.locked/context alone
+  6  returns to the kitchen      on a MATCH CUT, not a continuous join -- one
+                                 unbroken take across two rooms makes the model
+                                 morph one into the other mid-movement
+
+Hop 5 is the point of the whole thing. If the cook is still the same person in
+the same apron with the same voice, with no picture in front of the encoder,
+the register is doing its job.
+
+`shots` on each reference is what schedules this. On a continuation chain,
+omitting `shots` means HOP 1 ONLY. Right for a place plate, wrong for a face:
+put every face reference on every hop, or the identity drifts and stays
+drifted. List every hop a still should appear on.
+
+Settings that are deliberate, not defaults:
+  control_after_generate = fixed   or no two runs are comparable
+  tone_compensate = frame_shift    counters the drift that accumulates over six
+                                   hops. Set it to `off` and re-queue for a
+                                   same-seed A/B: tone mode is not in the hop
+                                   key, so every hop replays from cache in
+                                   seconds instead of re-rendering.
+  cache_hops = on                  edit shot 4 and only shots 4-6 re-render
+"""
+
+
+CARDS = [
+    # key, title, pos, size, colour
+    ("start", "START HERE", [-960, -400], [440, 940], GREEN, START_HERE),
+    ("rules", "The rules", [-960, 600], [440, 760], YELLOW, RULES),
+    ("refs", "References and @tags", [-960, 1420], [440, 640], YELLOW, REFERENCES),
+    ("directives", "Directives", [-480, -400], [440, 640], YELLOW, DIRECTIVES),
+    ("trouble", "When it goes wrong", [-480, 280], [440, 760], YELLOW, TROUBLE),
+    ("author", "Let a model write it", [-480, 1080], [440, 620], YELLOW, AUTHOR),
+]

tools/seam_probe.py

@@ -0,0 +1,96 @@
+r"""Measure the brightness step at each seam of a finished master.
+
+This is the *after* instrument. `tone_probe.py` reads the hop cache, which
+stores raw pre-correction hops, so it always reports the same raw drift whether
+or not compensation is on -- by design (the mode stays out of the hop key).
+The correction is only visible in the delivered video, which is what this reads.
+
+A single file's seam step is contaminated by real content change across the cut:
+the frames either side are ~0.9 s apart in scene time. Pass two masters rendered
+from the same seed and cache and that contamination is identical in both, so the
+DIFFERENCE between them is a clean read on what the correction did.
+
+    D:\ComfyUI\venv\Scripts\python.exe tools\seam_probe.py --hops 3 before.mp4 after.mp4
+
+Seam positions are derived, not guessed: hop 1 contributes its whole length and
+every later hop contributes length - overlap, so
+    hop_len = (total_frames + (hops - 1) * overlap) / hops
+"""
+from __future__ import annotations
+
+import argparse
+import os
+
+import av
+import numpy as np
+
+
+def frame_means(path):
+    """Per-frame mean RGB. -> [N,3] float64."""
+    out = []
+    with av.open(path) as container:
+        for frame in container.decode(video=0):
+            out.append(frame.to_ndarray(format="rgb24").mean(axis=(0, 1)))
+    return np.asarray(out, dtype=np.float64) / 255.0
+
+
+def seams(total, hops, overlap):
+    """Frame index of the first frame belonging to each later hop."""
+    if hops < 2:
+        return []
+    hop_len = (total + (hops - 1) * overlap) / hops
+    return [int(round(hop_len + k * (hop_len - overlap))) for k in range(hops - 1)]
+
+
+def report(path, hops, overlap, window):
+    means = frame_means(path)
+    n = len(means)
+    cuts = seams(n, hops, overlap)
+    print(f"{os.path.basename(path)}: {n}f, seams at {cuts}")
+    steps = []
+    for k, c in enumerate(cuts, 1):
+        a = means[max(0, c - window):c]
+        b = means[c:c + window]
+        if not len(a) or not len(b):
+            print(f"  seam {k} @ {c}: too close to an edge, skipped")
+            continue
+        step = b.mean(axis=0) - a.mean(axis=0)
+        luma = float(step.mean())
+        steps.append(luma)
+        print(f"  seam {k} @ {c}: "
+              + " ".join(f"{ch}{v:+.5f}" for ch, v in zip("rgb", step))
+              + f"   luma {luma:+.5f} ({luma * 255:+.2f}/255)")
+    if steps:
+        tot = sum(steps)
+        print(f"  sum of steps: {tot:+.5f} ({tot * 255:+.2f}/255)   "
+              f"mean |step| {np.mean(np.abs(steps)) * 255:.2f}/255")
+    return steps
+
+
+def main():
+    ap = argparse.ArgumentParser(description=__doc__)
+    ap.add_argument("files", nargs="+", help="master mp4(s), oldest first")
+    ap.add_argument("--hops", type=int, required=True)
+    ap.add_argument("--overlap", type=int, default=22)
+    ap.add_argument("--window", type=int, default=6,
+                    help="Frames averaged either side of the cut.")
+    args = ap.parse_args()
+
+    all_steps = []
+    for p in args.files:
+        if not os.path.isfile(p):
+            print(f"{p}: not found")
+            return 1
+        all_steps.append(report(p, args.hops, args.overlap, args.window))
+        print()
+
+    if len(all_steps) == 2 and all_steps[0] and all_steps[1]:
+        print("A/B (same seed + cache, so content change cancels):")
+        for k, (a, b) in enumerate(zip(*all_steps), 1):
+            print(f"  seam {k}: {a * 255:+.2f}/255 -> {b * 255:+.2f}/255   "
+                  f"({(abs(b) - abs(a)) * 255:+.2f}/255 magnitude)")
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

tools/tone_probe.py

@@ -0,0 +1,141 @@
+"""Measure the real per-hop tone drift, from the hop cache.
+
+Why the cache and not the rendered master: the estimate has to pair hop N's last
+`overlap` frames with hop N+1's *first* `overlap` frames, which are the model's
+regeneration of the same content. The join drops that second copy
+(`h3_ref_chain.py`, `master_imgs[...] = imgs[overlap_n:]`), so it does not exist
+in the output video. It does exist in the hop cache, which stores each hop's
+full pre-trim frames as lossless 16-bit FFV1 -- which makes the cache the only
+honest instrument for this measurement.
+
+Comparing frames either side of the seam in a finished master is NOT the same
+measurement: those frames are ~0.9 s apart in scene time, so the number includes
+whatever the scene did in between.
+
+Usage, from the pack directory:
+
+    D:\\ComfyUI\\venv\\Scripts\\python.exe tools\\tone_probe.py [--overlap 22] [--root PATH]
+
+ComfyUI wipes `temp/` on startup, so this only sees a cache written by the
+currently running session: render with `cache_hops=on` and probe before you
+restart.
+
+Read-only apart from one side effect worth knowing: `HopStore.get()` touches
+each entry's mtime for LRU, so probing marks every hop as recently used.
+"""
+from __future__ import annotations
+
+import argparse
+import json
+import os
+import sys
+import types
+
+# Derived from this file's position (pack/tools/ -> custom_nodes/pack ->
+# ComfyUI root), so the probe works on a checkout that is not this machine's.
+# Matches the root h3_ref_chain.py builds from folder_paths.get_temp_directory().
+_COMFY_ROOT = os.path.dirname(os.path.dirname(os.path.dirname(
+    os.path.dirname(os.path.abspath(__file__)))))
+DEFAULT_ROOT = os.path.join(_COMFY_ROOT, "temp", "h3_ref_chain_hops")
+
+
+def _load_store():
+    """Import the pack's own store.py without installing the pack.
+
+    The directory has dashes, so it is not a legal module name; register a
+    synthetic package pointing at it. Same trick the offline tests use.
+    """
+    here = os.path.dirname(os.path.dirname(os.path.abspath(__file__)))
+    pkg = types.ModuleType("h3pack")
+    pkg.__path__ = [here]
+    sys.modules["h3pack"] = pkg
+    from h3pack import store  # noqa: PLC0415
+    return store
+
+
+def _hops(store, root):
+    """Cached hops as [(hop_index, key)], ordered, skipping unreadable meta."""
+    out = []
+    for key, _size, _mtime in store.HopStore(root).entries():
+        meta_path = os.path.join(root, key + store.META_EXT)
+        try:
+            with open(meta_path, encoding="utf-8") as fh:
+                meta = json.load(fh)
+        except (OSError, ValueError) as e:
+            print(f"  ! {key[:8]}: unreadable meta ({e!r}), skipped")
+            continue
+        hop = meta.get("hop")
+        if hop is None:
+            print(f"  ! {key[:8]}: meta has no hop index, skipped")
+            continue
+        out.append((int(hop), key))
+    return sorted(out)
+
+
+def main():
+    ap = argparse.ArgumentParser(description=__doc__)
+    ap.add_argument("--root", default=DEFAULT_ROOT)
+    ap.add_argument("--overlap", type=int, default=22,
+                    help="Frames pinned per join. Must match the render.")
+    args = ap.parse_args()
+
+    if not os.path.isdir(args.root):
+        print(f"No hop cache at {args.root}.\n"
+              f"Render with cache_hops=on and probe before restarting ComfyUI "
+              f"(temp/ is wiped on start).")
+        return 1
+
+    store = _load_store()
+    import torch  # noqa: PLC0415  -- after store, so the venv check fails first
+
+    hops = _hops(store, args.root)
+    if len(hops) < 2:
+        print(f"Found {len(hops)} cached hop(s) in {args.root}; need at least 2.")
+        return 1
+
+    print(f"{len(hops)} hops in {args.root}, overlap {args.overlap}f\n")
+    st = store.HopStore(args.root)
+    ov = int(args.overlap)
+
+    prev = None
+    cumulative = torch.zeros(3)
+    for hop, key in hops:
+        got = st.get(key)
+        if got is None:
+            print(f"hop {hop}: entry {key[:8]} incomplete, skipped")
+            continue
+        imgs = got[0]
+        if prev is None:
+            print(f"hop {hop} ({key[:8]}): {imgs.shape[0]}f  "
+                  f"mean {float(imgs.mean()):.4f}  [reference]")
+            prev = imgs
+            continue
+
+        n = min(ov, prev.shape[0], imgs.shape[0])
+        src = prev[-n:]           # what hop N ended on
+        tgt = imgs[:n]            # hop N+1's regeneration of it
+        # Per channel over the matched overlap: this is exactly what
+        # tone.compensate's frame_shift mode fits.
+        drift = tgt.mean(dim=(0, 1, 2)) - src.mean(dim=(0, 1, 2))
+        cumulative = cumulative + drift
+        luma = float(drift.mean())
+        print(f"hop {hop} ({key[:8]}): {imgs.shape[0]}f  "
+              f"mean {float(imgs.mean()):.4f}")
+        print(f"    drift vs hop {hop - 1} over {n}f: "
+              + " ".join(f"{c}{v:+.5f}" for c, v in zip("rgb", drift.tolist()))
+              + f"   luma {luma:+.5f} ({luma * 255:+.2f}/255)")
+        print(f"    cumulative from hop 1:            "
+              + " ".join(f"{c}{v:+.5f}" for c, v in zip("rgb", cumulative.tolist()))
+              + f"   luma {float(cumulative.mean()):+.5f} "
+                f"({float(cumulative.mean()) * 255:+.2f}/255)")
+        prev = imgs
+
+    total = float(cumulative.mean())
+    print(f"\nTotal drift across the chain: {total:+.5f} ({total * 255:+.2f}/255)")
+    print("Positive = later hops are brighter. A step below ~1/255 is not worth "
+          "correcting; the correction itself costs a clamp.")
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

workflows/HandTieClips_Showcase.json

@@ -0,0 +1,1213 @@
+{
+  "id": "h3-ref2va-chain",
+  "revision": 1,
+  "last_node_id": 34,
+  "last_link_id": 18,
+  "nodes": [
+    {
+      "id": 2,
+      "type": "UNETLoader",
+      "pos": [
+        0,
+        340
+      ],
+      "size": [
+        420,
+        82
+      ],
+      "flags": {},
+      "order": 0,
+      "mode": 0,
+      "inputs": [
+        {
+          "localized_name": "unet_name",
+          "name": "unet_name",
+          "type": "COMBO",
+          "widget": {
+            "name": "unet_name"
+          },
+          "link": null
+        },
+        {
+          "localized_name": "weight_dtype",
+          "name": "weight_dtype",
+          "type": "COMBO",
+          "widget": {
+            "name": "weight_dtype"
+          },
+          "link": null
+        }
+      ],
+      "outputs": [
+        {
+          "localized_name": "MODEL",
+          "name": "MODEL",
+          "type": "MODEL",
+          "slot_index": 0,
+          "links": [
+            11
+          ]
+        }
+      ],
+      "title": "DiT (ref2va)",
+      "properties": {
+        "cnr_id": "comfy-core",
+        "ver": "0.34.0",
+        "Node name for S&R": "UNETLoader"
+      },
+      "widgets_values": [
+        "minimax_h3_hybrid_fl2va_ref2va_b30-49-int8.safetensors",
+        "default"
+      ]
+    },
+    {
+      "id": 3,
+      "type": "CLIPLoader",
+      "pos": [
+        0,
+        460
+      ],
+      "size": [
+        420,
+        106
+      ],
+      "flags": {},
+      "order": 1,
+      "mode": 0,
+      "inputs": [
+        {
+          "localized_name": "clip_name",
+          "name": "clip_name",
+          "type": "COMBO",
+          "widget": {
+            "name": "clip_name"
+          },
+          "link": null
+        },
+        {
+          "localized_name": "type",
+          "name": "type",
+          "type": "COMBO",
+          "widget": {
+            "name": "type"
+          },
+          "link": null
+        },
+        {
+          "localized_name": "device",
+          "name": "device",
+          "shape": 7,
+          "type": "COMBO",
+          "widget": {
+            "name": "device"
+          },
+          "link": null
+        }
+      ],
+      "outputs": [
+        {
+          "localized_name": "CLIP",
+          "name": "CLIP",
+          "type": "CLIP",
+          "slot_index": 0,
+          "links": [
+            12
+          ]
+        }
+      ],
+      "title": "Text encoder",
+      "properties": {
+        "cnr_id": "comfy-core",
+        "ver": "0.34.0",
+        "Node name for S&R": "CLIPLoader"
+      },
+      "widgets_values": [
+        "qwen3vl_32b_minimax_h3_int8_convrot.safetensors",
+        "minimax",
+        "default"
+      ]
+    },
+    {
+      "id": 4,
+      "type": "VAELoader",
+      "pos": [
+        0,
+        600
+      ],
+      "size": [
+        420,
+        82
+      ],
+      "flags": {},
+      "order": 2,
+      "mode": 0,
+      "inputs": [
+        {
+          "localized_name": "vae_name",
+          "name": "vae_name",
+          "type": "COMBO",
+          "widget": {
+            "name": "vae_name"
+          },
+          "link": null
+        }
+      ],
+      "outputs": [
+        {
+          "localized_name": "VAE",
+          "name": "VAE",
+          "type": "VAE",
+          "slot_index": 0,
+          "links": [
+            3
+          ]
+        }
+      ],
+      "title": "Video VAE",
+      "properties": {
+        "cnr_id": "comfy-core",
+        "ver": "0.34.0",
+        "Node name for S&R": "VAELoader"
+      },
+      "widgets_values": [
+        "minimax_h3_video_vae_int8_convrot.safetensors"
+      ]
+    },
+    {
+      "id": 5,
+      "type": "VAELoader",
+      "pos": [
+        0,
+        720
+      ],
+      "size": [
+        420,
+        82
+      ],
+      "flags": {},
+      "order": 3,
+      "mode": 0,
+      "inputs": [
+        {
+          "localized_name": "vae_name",
+          "name": "vae_name",
+          "type": "COMBO",
+          "widget": {
+            "name": "vae_name"
+          },
+          "link": null
+        }
+      ],
+      "outputs": [
+        {
+          "localized_name": "VAE",
+          "name": "VAE",
+          "type": "VAE",
+          "slot_index": 0,
+          "links": [
+            4
+          ]
+        }
+      ],
+      "title": "Audio VAE",
+      "properties": {
+        "cnr_id": "comfy-core",
+        "ver": "0.34.0",
+        "Node name for S&R": "VAELoader"
+      },
+      "widgets_values": [
+        "minimax_h3_audio_vae_fp32.safetensors"
+      ]
+    },
+    {
+      "id": 7,
+      "type": "HandTieClips",
+      "pos": [
+        994,
+        427
+      ],
+      "size": [
+        968.3162169696975,
+        1426.2006199999998
+      ],
+      "flags": {},
+      "order": 4,
+      "mode": 0,
+      "inputs": [
+        {
+          "localized_name": "model",
+          "name": "model",
+          "type": "MODEL",
+          "link": 17
+        },
+        {
+          "localized_name": "clip",
+          "name": "clip",
+          "type": "CLIP",
+          "link": 18
+        },
+        {
+          "localized_name": "vae",
+          "name": "vae",
+          "type": "VAE",
+          "link": 3
+        },
+        {
+          "localized_name": "audio_vae",
+          "name": "audio_vae",
+          "type": "VAE",
+          "link": 4
+        },
+        {
+          "localized_name": "continuity_state",
+          "name": "continuity_state",
+          "shape": 7,
+          "type": "STRING",
+          "link": null
+        },
+        {
+          "localized_name": "prompt",
+          "name": "prompt",
+          "type": "STRING",
+          "widget": {
+            "name": "prompt"
+          },
+          "link": null
+        },
+        {
+          "localized_name": "chains",
+          "name": "chains",
+          "type": "COMBO",
+          "widget": {
+            "name": "chains"
+          },
+          "link": null
+        },
+        {
+          "localized_name": "resolution",
+          "name": "resolution",
+          "type": "COMBO",
+          "widget": {
+            "name": "resolution"
+          },
+          "link": null
+        },
+        {
+          "localized_name": "aspect",
+          "name": "aspect",
+          "type": "COMBO",
+          "widget": {
+            "name": "aspect"
+          },
+          "link": null
+        },
+        {
+          "localized_name": "duration",
+          "name": "duration",
+          "type": "COMBO",
+          "widget": {
+            "name": "duration"
+          },
+          "link": null
+        },
+        {
+          "localized_name": "overlap",
+          "name": "overlap",
+          "type": "COMBO",
+          "widget": {
+            "name": "overlap"
+          },
+          "link": null
+        },
+        {
+          "localized_name": "seed",
+          "name": "seed",
+          "type": "INT",
+          "widget": {
+            "name": "seed"
+          },
+          "link": null
+        },
+        {
+          "localized_name": "seed_per_shot",
+          "name": "seed_per_shot",
+          "type": "BOOLEAN",
+          "widget": {
+            "name": "seed_per_shot"
+          },
+          "link": null
+        },
+        {
+          "localized_name": "steps",
+          "name": "steps",
+          "type": "INT",
+          "widget": {
+            "name": "steps"
+          },
+          "link": null
+        },
+        {
+          "localized_name": "sampler_name",
+          "name": "sampler_name",
+          "type": "COMBO",
+          "widget": {
+            "name": "sampler_name"
+          },
+          "link": null
+        },
+        {
+          "localized_name": "scheduler",
+          "name": "scheduler",
+          "type": "COMBO",
+          "widget": {
+            "name": "scheduler"
+          },
+          "link": null
+        },
+        {
+          "localized_name": "shift_video",
+          "name": "shift_video",
+          "type": "FLOAT",
+          "widget": {
+            "name": "shift_video"
+          },
+          "link": null
+        },
+        {
+          "localized_name": "shift_audio",
+          "name": "shift_audio",
+          "type": "FLOAT",
+          "widget": {
+            "name": "shift_audio"
+          },
+          "link": null
+        },
+        {
+          "localized_name": "ref_image_size",
+          "name": "ref_image_size",
+          "type": "COMBO",
+          "widget": {
+            "name": "ref_image_size"
+          },
+          "link": null
+        },
+        {
+          "localized_name": "hop_script",
+          "name": "hop_script",
+          "shape": 7,
+          "type": "COMBO",
+          "widget": {
+            "name": "hop_script"
+          },
+          "link": null
+        },
+        {
+          "localized_name": "pin_to_qwen",
+          "name": "pin_to_qwen",
+          "shape": 7,
+          "type": "COMBO",
+          "widget": {
+            "name": "pin_to_qwen"
+          },
+          "link": null
+        },
+        {
+          "localized_name": "shot_plan",
+          "name": "shot_plan",
+          "shape": 7,
+          "type": "STRING",
+          "widget": {
+            "name": "shot_plan"
+          },
+          "link": null
+        },
+        {
+          "localized_name": "ref_plan",
+          "name": "ref_plan",
+          "shape": 7,
+          "type": "STRING",
+          "widget": {
+            "name": "ref_plan"
+          },
+          "link": null
+        },
+        {
+          "localized_name": "cache_hops",
+          "name": "cache_hops",
+          "shape": 7,
+          "type": "COMBO",
+          "widget": {
+            "name": "cache_hops"
+          },
+          "link": null
+        },
+        {
+          "localized_name": "cache_budget_gb",
+          "name": "cache_budget_gb",
+          "shape": 7,
+          "type": "FLOAT",
+          "widget": {
+            "name": "cache_budget_gb"
+          },
+          "link": null
+        },
+        {
+          "localized_name": "audio_pin_frames",
+          "name": "audio_pin_frames",
+          "shape": 7,
+          "type": "INT",
+          "widget": {
+            "name": "audio_pin_frames"
+          },
+          "link": null
+        },
+        {
+          "localized_name": "pin_renorm",
+          "name": "pin_renorm",
+          "shape": 7,
+          "type": "COMBO",
+          "widget": {
+            "name": "pin_renorm"
+          },
+          "link": null
+        },
+        {
+          "localized_name": "pin_noise",
+          "name": "pin_noise",
+          "shape": 7,
+          "type": "FLOAT",
+          "widget": {
+            "name": "pin_noise"
+          },
+          "link": null
+        },
+        {
+          "localized_name": "tone_compensate",
+          "name": "tone_compensate",
+          "shape": 7,
+          "type": "COMBO",
+          "widget": {
+            "name": "tone_compensate"
+          },
+          "link": null
+        },
+        {
+          "localized_name": "start_image_file",
+          "name": "start_image_file",
+          "shape": 7,
+          "type": "STRING",
+          "widget": {
+            "name": "start_image_file"
+          },
+          "link": null
+        },
+        {
+          "localized_name": "reference_video_file",
+          "name": "reference_video_file",
+          "shape": 7,
+          "type": "STRING",
+          "widget": {
+            "name": "reference_video_file"
+          },
+          "link": null
+        },
+        {
+          "localized_name": "voice_file",
+          "name": "voice_file",
+          "shape": 7,
+          "type": "STRING",
+          "widget": {
+            "name": "voice_file"
+          },
+          "link": null
+        }
+      ],
+      "outputs": [
+        {
+          "localized_name": "images",
+          "name": "images",
+          "type": "IMAGE",
+          "slot_index": 0,
+          "links": [
+            5
+          ]
+        },
+        {
+          "localized_name": "audio",
+          "name": "audio",
+          "type": "AUDIO",
+          "slot_index": 1,
+          "links": [
+            6
+          ]
+        },
+        {
+          "localized_name": "info",
+          "name": "info",
+          "type": "STRING",
+          "slot_index": 2,
+          "links": [
+            7
+          ]
+        }
+      ],
+      "properties": {
+        "Node name for S&R": "H3RefChain",
+        "h3_plan_backup": "{\n  \"shots\": [\n    {\n      \"id\": \"s1\",\n      \"beat\": \"Live-action, natural indoor light. The cook stands at the counter in @kitchen, looks up from the chopping board, and speaks one short line to someone off-frame.\",\n      \"directives\": {\n        \"camera\": \"hold\",\n        \"framing\": \"medium\",\n        \"pace\": \"steady\",\n        \"tail\": \"ongoing\"\n      }\n    },\n    {\n      \"id\": \"s2\",\n      \"beat\": \"The cook sets the knife down, turns toward the window, and finishes her last word as she looks out.\",\n      \"directives\": {\n        \"join\": \"continuous\",\n        \"camera\": \"push_in\",\n        \"framing\": \"close\",\n        \"pace\": \"steady\",\n        \"tail\": \"ongoing\"\n      }\n    },\n    {\n      \"id\": \"s3\",\n      \"beat\": \"The cook leans back against the counter with her lips closed, and lets her eyes move slowly across the room. The room is still, with only the low hum of the refrigerator.\",\n      \"directives\": {\n        \"join\": \"continuous\",\n        \"camera\": \"pull_back\",\n        \"framing\": \"medium\",\n        \"pace\": \"slow\",\n        \"tail\": \"settle\"\n      }\n    }\n  ]\n}",
+        "h3_editor_mode": "shots"
+      },
+      "widgets_values": [
+        "Live-action, natural indoor light. The person looks exactly as in the reference photographs.\n\nThey sit at a table, look up, and speak one short line. Then they settle, watching the room.",
+        "6",
+        "0.3 MP",
+        "16:9 landscape",
+        "7 s",
+        "0.9 s",
+        427058607873049,
+        "fixed",
+        true,
+        7,
+        "res_multistep",
+        "simple",
+        12,
+        3,
+        "match",
+        "next",
+        "last frame",
+        "{\n  \"shots\": [\n    {\n      \"id\": \"s1\",\n      \"beat\": \"@hero_face stands at the counter in @kitchen, a grey apron over a grey t-shirt. She looks up from the chopping board and says, 'You are early. I have barely started.' She turns back to the board and goes on slicing, the knife tapping steadily against the wood.\",\n      \"directives\": {\n        \"camera\": \"hold\",\n        \"framing\": \"medium\",\n        \"pace\": \"steady\",\n        \"tail\": \"ongoing\"\n      }\n    },\n    {\n      \"id\": \"s2\",\n      \"beat\": \"She sets the knife down and walks the length of the counter to the window of @kitchen, looking out at the street. Her steps are soft on the tiles and the refrigerator hums behind her.\",\n      \"directives\": {\n        \"join\": \"continuous\",\n        \"camera\": \"pan_follow\",\n        \"framing\": \"medium\",\n        \"pace\": \"steady\",\n        \"tail\": \"ongoing\"\n      }\n    },\n    {\n      \"id\": \"s3\",\n      \"beat\": \"She turns from the window, crosses @kitchen and pushes through the doorway into the hallway beyond, the room falling away behind her. Her footsteps carry on the tiles.\",\n      \"directives\": {\n        \"join\": \"continuous\",\n        \"camera\": \"pan_follow\",\n        \"framing\": \"wide\",\n        \"pace\": \"brisk\",\n        \"tail\": \"ongoing\"\n      }\n    },\n    {\n      \"id\": \"s4\",\n      \"beat\": \"@hero_face walks down a narrow hallway hung with coats, one hand trailing along the wall, her footsteps muffled on the runner. The hallway walls stand close on either side of her and the coats brush past her shoulder.\",\n      \"directives\": {\n        \"join\": \"continuous\",\n        \"camera\": \"handheld\",\n        \"framing\": \"medium\",\n        \"pace\": \"steady\",\n        \"tail\": \"ongoing\"\n      }\n    },\n    {\n      \"id\": \"s5\",\n      \"beat\": \"She reaches the window at the end of the hall and rests one hand on the frame, then half turns back over her shoulder and says, 'It is still raining. We will have to do it inside.' She looks back out at the glass with her lips closed, and the rain taps steadily on the pane.\",\n      \"directives\": {\n        \"join\": \"continuous\",\n        \"camera\": \"push_in\",\n        \"framing\": \"close\",\n        \"pace\": \"slow\",\n        \"tail\": \"settle\"\n      }\n    },\n    {\n      \"id\": \"s6\",\n      \"beat\": \"She walks back along the hallway and through the doorway to the counter in @kitchen, picking the knife up again. The refrigerator hums and the knife starts on the board.\",\n      \"directives\": {\n        \"join\": \"match_cut\",\n        \"camera\": \"pull_back\",\n        \"framing\": \"wide\",\n        \"pace\": \"steady\",\n        \"tail\": \"hold\"\n      }\n    }\n  ]\n}",
+        "{\n  \"refs\": [\n    {\n      \"tag\": \"hero_face\",\n      \"file\": \"ref_face.jpg\",\n      \"subject\": 1,\n      \"retention\": \"fully_preserved\",\n      \"shots\": [\n        1,\n        2,\n        3,\n        4,\n        5,\n        6\n      ],\n      \"desc\": \"head-and-shoulders photograph of the cook, even light\"\n    },\n    {\n      \"tag\": \"hero_outfit\",\n      \"file\": \"ref_outfit.jpg\",\n      \"subject\": 1,\n      \"retention\": \"partially_copy\",\n      \"shots\": [\n        1\n      ],\n      \"desc\": \"full-length photograph of the same cook, grey apron over a grey t-shirt\"\n    },\n    {\n      \"tag\": \"kitchen\",\n      \"file\": \"ref_room.jpg\",\n      \"retention\": \"reference\",\n      \"shots\": [\n        1,\n        2,\n        3,\n        6\n      ],\n      \"desc\": \"the kitchen: counter, window, and the light coming through it\"\n    }\n  ],\n  \"subjects\": {\n    \"1\": {\n      \"name\": \"the cook\",\n      \"locked\": \"the same face, the same short dark hair, the same silver stud earrings\",\n      \"context\": \"the grey apron stays tied over the grey t-shirt\"\n    }\n  }\n}",
+        "on",
+        19,
+        24,
+        "off",
+        0,
+        "frame_shift",
+        "",
+        "",
+        "",
+        "Live-action, natural light, one continuous take."
+      ],
+      "title": "H3 Ref2VA Chain - showcase 6x7s"
+    },
+    {
+      "id": 16,
+      "type": "HTCChainPreview",
+      "pos": [
+        2258.827272727274,
+        -90.16060606060621
+      ],
+      "size": [
+        400,
+        460
+      ],
+      "flags": {},
+      "order": 5,
+      "mode": 0,
+      "inputs": [
+        {
+          "localized_name": "images",
+          "name": "images",
+          "type": "IMAGE",
+          "link": 5
+        },
+        {
+          "localized_name": "audio",
+          "name": "audio",
+          "shape": 7,
+          "type": "AUDIO",
+          "link": 6
+        },
+        {
+          "localized_name": "info",
+          "name": "info",
+          "shape": 7,
+          "type": "STRING",
+          "link": 7
+        }
+      ],
+      "outputs": [
+        {
+          "localized_name": "images",
+          "name": "images",
+          "type": "IMAGE",
+          "slot_index": 0,
+          "links": [
+            8
+          ]
+        },
+        {
+          "localized_name": "audio",
+          "name": "audio",
+          "type": "AUDIO",
+          "slot_index": 1,
+          "links": [
+            9
+          ]
+        }
+      ],
+      "properties": {
+        "Node name for S&R": "H3ChainPreview",
+        "h3rcPanelH": 40
+      },
+      "widgets_values": [
+        ""
+      ]
+    },
+    {
+      "id": 8,
+      "type": "CreateVideo",
+      "pos": [
+        2991.7272727272743,
+        37.33939393939383
+      ],
+      "size": [
+        300,
+        130
+      ],
+      "flags": {},
+      "order": 6,
+      "mode": 0,
+      "inputs": [
+        {
+          "localized_name": "images",
+          "name": "images",
+          "type": "IMAGE",
+          "link": 8
+        },
+        {
+          "localized_name": "audio",
+          "name": "audio",
+          "shape": 7,
+          "type": "AUDIO",
+          "link": 9
+        },
+        {
+          "localized_name": "fps",
+          "name": "fps",
+          "type": "FLOAT",
+          "widget": {
+            "name": "fps"
+          },
+          "link": null
+        },
+        {
+          "localized_name": "bit_depth",
+          "name": "bit_depth",
+          "shape": 7,
+          "type": "COMBO",
+          "widget": {
+            "name": "bit_depth"
+          },
+          "link": null
+        },
+        {
+          "localized_name": "color_space",
+          "name": "color_space",
+          "shape": 7,
+          "type": "COMBO",
+          "widget": {
+            "name": "color_space"
+          },
+          "link": null
+        }
+      ],
+      "outputs": [
+        {
+          "localized_name": "VIDEO",
+          "name": "VIDEO",
+          "type": "VIDEO",
+          "slot_index": 0,
+          "links": [
+            10
+          ]
+        }
+      ],
+      "properties": {
+        "cnr_id": "comfy-core",
+        "ver": "0.34.0",
+        "Node name for S&R": "CreateVideo"
+      },
+      "widgets_values": [
+        24,
+        "auto",
+        "sRGB"
+      ]
+    },
+    {
+      "id": 9,
+      "type": "SaveVideo",
+      "pos": [
+        3032.515151515151,
+        714.542424242424
+      ],
+      "size": [
+        340,
+        106
+      ],
+      "flags": {},
+      "order": 7,
+      "mode": 0,
+      "inputs": [
+        {
+          "localized_name": "video",
+          "name": "video",
+          "type": "VIDEO",
+          "link": 10
+        },
+        {
+          "localized_name": "filename_prefix",
+          "name": "filename_prefix",
+          "type": "STRING",
+          "widget": {
+            "name": "filename_prefix"
+          },
+          "link": null
+        },
+        {
+          "localized_name": "format",
+          "name": "format",
+          "type": "COMFY_DYNAMICCOMBO_V3",
+          "widget": {
+            "name": "format"
+          },
+          "link": null
+        },
+        {
+          "localized_name": "format.codec",
+          "name": "format.codec",
+          "type": "COMFY_DYNAMICCOMBO_V3",
+          "widget": {
+            "name": "format.codec"
+          },
+          "link": null
+        },
+        {
+          "localized_name": "codec",
+          "name": "codec",
+          "shape": 7,
+          "type": "COMFY_DYNAMICCOMBO_V3",
+          "widget": {
+            "name": "codec"
+          },
+          "link": null
+        }
+      ],
+      "outputs": [
+        {
+          "localized_name": "video",
+          "name": "video",
+          "type": "VIDEO",
+          "links": []
+        }
+      ],
+      "title": "SAVE",
+      "properties": {
+        "cnr_id": "comfy-core",
+        "ver": "0.34.0",
+        "Node name for S&R": "SaveVideo"
+      },
+      "widgets_values": [
+        "video/HANDTIECLIPS/chain",
+        "auto",
+        "auto",
+        "auto"
+      ]
+    },
+    {
+      "id": 1,
+      "type": "Note",
+      "pos": [
+        -137.49999999999997,
+        -359.15000000000015
+      ],
+      "size": [
+        440,
+        900
+      ],
+      "flags": {},
+      "order": 8,
+      "mode": 0,
+      "inputs": [],
+      "outputs": [],
+      "title": "H3 Ref2VA Chain",
+      "properties": {},
+      "widgets_values": [
+        "Hand Tie Clips -- SHOWCASE (6 hops x 7 s = 39.2 s)\n\nA continuity stress test, and the honest demonstration of what the reference\nregister buys you.\n\nREQUIRES a turbo stack on the MODEL wire, which is how this node is actually\nrun here:\n\n    UNETLoader -> LoRA Loader Stack (turbo LoRA) -> H3 AdaLN LoRA Fix\n               -> MiniMax H3 Low VRAM Attention -> H3 SLA Attention\n               -> Model Preview Override -> this node\n\n    ComfyUI-PlagueKind-Nodes  ->  LoRA Loader Stack, AdaLN Fix, SLA Attention\n    ComfyUI-KJNodes           ->  Low VRAM Attention (experimental),\n                                  Model Preview Override\n\nOn disk as well: the turbo LoRA named in the loader, and taeh3.safetensors for\nthe live preview (or set tiny_vae to none).\n\nCLIP reaches this node FROM THE LORA LOADER, not from the encoder. That is what\nmakes the text half of every LoRA land. Do not rewire it back.\n\n`steps` is 7, which only works with the turbo LoRA. Missing a pack? Its nodes\nload as red boxes -- delete them, wire the loader straight into `model` and the\nencoder into `clip`, and raise `steps` to 20 or so.\n\nBEFORE YOU RUN IT, supply three pictures. Open REFERENCES on the node and drop\nyour own onto each thumbnail, or put files in ComfyUI/input/h3_refs named:\n\n    ref_face.jpg     head-and-shoulders, even light   -> @hero_face\n    ref_outfit.jpg   full length, same person         -> @hero_outfit\n    ref_room.jpg     the room, wide                   -> @kitchen\n\nWithout them the run stops and names the reference it could not find. Nothing\nguesses.\n\nWhat each hop is testing:\n\n  1  kitchen, dialogue           all three references active\n  2  lateral move to the window  kitchen only\n  3  exits through the doorway   kitchen only\n  4  hallway - UNSEEN space      face re-asserted; no room reference exists\n  5  dialogue, ZERO references   identity, wardrobe and voice ride on the frame\n                                 pin plus subjects.1.locked/context alone\n  6  returns to the kitchen      on a MATCH CUT, not a continuous join -- one\n                                 unbroken take across two rooms makes the model\n                                 morph one into the other mid-movement\n\nHop 5 is the point of the whole thing. If the cook is still the same person in\nthe same apron with the same voice, with no picture in front of the encoder,\nthe register is doing its job.\n\n`shots` on each reference is what schedules this. On a continuation chain,\nomitting `shots` means HOP 1 ONLY. Right for a place plate, wrong for a face:\nput every face reference on every hop, or the identity drifts and stays\ndrifted. List every hop a still should appear on.\n\nSettings that are deliberate, not defaults:\n  control_after_generate = fixed   or no two runs are comparable\n  tone_compensate = frame_shift    counters the drift that accumulates over six\n                                   hops. Set it to `off` and re-queue for a\n                                   same-seed A/B: tone mode is not in the hop\n                                   key, so every hop replays from cache in\n                                   seconds instead of re-rendering.\n  cache_hops = on                  edit shot 4 and only shots 4-6 re-render\n"
+      ],
+      "color": "#432",
+      "bgcolor": "#653"
+    },
+    {
+      "id": 30,
+      "type": "LTX_lora_loader",
+      "pos": [
+        520,
+        -40
+      ],
+      "size": [
+        420,
+        240
+      ],
+      "flags": {},
+      "order": 0,
+      "mode": 0,
+      "inputs": [
+        {
+          "name": "model",
+          "type": "MODEL",
+          "link": 11
+        },
+        {
+          "name": "clip",
+          "type": "CLIP",
+          "link": 12
+        }
+      ],
+      "outputs": [
+        {
+          "name": "model",
+          "type": "MODEL",
+          "links": [
+            13
+          ]
+        },
+        {
+          "name": "clip",
+          "type": "CLIP",
+          "links": [
+            18
+          ]
+        }
+      ],
+      "title": "LoRA Loader Stack (turbo)",
+      "properties": {
+        "htc_speed": "lora",
+        "Node name for S&R": "LTX_lora_loader"
+      },
+      "widgets_values": [
+        "minimax",
+        "[{\"on\":true,\"lora\":\"minimax_h3_ref2v_turbo_4step_v0.1_comfyui_bf16.safetensors\",\"str\":1,\"v\":1,\"a\":1,\"t\":1}]",
+        ""
+      ]
+    },
+    {
+      "id": 31,
+      "type": "H3AdaLNLoRAFix",
+      "pos": [
+        520,
+        240
+      ],
+      "size": [
+        340,
+        150
+      ],
+      "flags": {},
+      "order": 0,
+      "mode": 0,
+      "inputs": [
+        {
+          "name": "model",
+          "type": "MODEL",
+          "link": 13
+        }
+      ],
+      "outputs": [
+        {
+          "name": "MODEL",
+          "type": "MODEL",
+          "links": [
+            14
+          ]
+        }
+      ],
+      "title": "H3 AdaLN LoRA Fix",
+      "properties": {
+        "htc_speed": "adaln",
+        "Node name for S&R": "H3AdaLNLoRAFix"
+      },
+      "widgets_values": [
+        "port"
+      ]
+    },
+    {
+      "id": 32,
+      "type": "MiniMaxLowVRAMAttention",
+      "pos": [
+        520,
+        430
+      ],
+      "size": [
+        330,
+        58
+      ],
+      "flags": {},
+      "order": 0,
+      "mode": 0,
+      "inputs": [
+        {
+          "name": "model",
+          "type": "MODEL",
+          "link": 14
+        }
+      ],
+      "outputs": [
+        {
+          "name": "model",
+          "type": "MODEL",
+          "links": [
+            15
+          ]
+        }
+      ],
+      "title": "MiniMax H3 Low VRAM Attention",
+      "properties": {
+        "htc_speed": "lowvram",
+        "Node name for S&R": "MiniMaxLowVRAMAttention"
+      },
+      "widgets_values": [
+        4
+      ]
+    },
+    {
+      "id": 33,
+      "type": "H3SLAAttention",
+      "pos": [
+        520,
+        530
+      ],
+      "size": [
+        340,
+        322
+      ],
+      "flags": {},
+      "order": 0,
+      "mode": 0,
+      "inputs": [
+        {
+          "name": "model",
+          "type": "MODEL",
+          "link": 15
+        }
+      ],
+      "outputs": [
+        {
+          "name": "MODEL",
+          "type": "MODEL",
+          "links": [
+            16
+          ]
+        }
+      ],
+      "title": "H3 SLA Attention",
+      "properties": {
+        "htc_speed": "sla",
+        "Node name for S&R": "H3SLAAttention"
+      },
+      "widgets_values": [
+        0.9,
+        "64",
+        8192,
+        0,
+        true,
+        true,
+        "0",
+        "comfy_kitchen",
+        true,
+        true,
+        "Light"
+      ]
+    },
+    {
+      "id": 34,
+      "type": "ModelPreviewOverrideKJ",
+      "pos": [
+        520,
+        900
+      ],
+      "size": [
+        360,
+        480
+      ],
+      "flags": {},
+      "order": 0,
+      "mode": 0,
+      "inputs": [
+        {
+          "name": "model",
+          "type": "MODEL",
+          "link": 16
+        },
+        {
+          "name": "vae",
+          "type": "VAE",
+          "link": null
+        }
+      ],
+      "outputs": [
+        {
+          "name": "MODEL",
+          "type": "MODEL",
+          "links": [
+            17
+          ]
+        }
+      ],
+      "title": "Model Preview Override",
+      "properties": {
+        "htc_speed": "preview",
+        "Node name for S&R": "ModelPreviewOverrideKJ"
+      },
+      "widgets_values": [
+        512,
+        80,
+        true,
+        100,
+        8,
+        "taeh3.safetensors",
+        ""
+      ]
+    }
+  ],
+  "links": [
+    [
+      3,
+      4,
+      0,
+      7,
+      2,
+      "VAE"
+    ],
+    [
+      4,
+      5,
+      0,
+      7,
+      3,
+      "VAE"
+    ],
+    [
+      5,
+      7,
+      0,
+      16,
+      0,
+      "IMAGE"
+    ],
+    [
+      6,
+      7,
+      1,
+      16,
+      1,
+      "AUDIO"
+    ],
+    [
+      7,
+      7,
+      2,
+      16,
+      2,
+      "STRING"
+    ],
+    [
+      8,
+      16,
+      0,
+      8,
+      0,
+      "IMAGE"
+    ],
+    [
+      9,
+      16,
+      1,
+      8,
+      1,
+      "AUDIO"
+    ],
+    [
+      10,
+      8,
+      0,
+      9,
+      0,
+      "VIDEO"
+    ],
+    [
+      11,
+      2,
+      0,
+      30,
+      0,
+      "MODEL"
+    ],
+    [
+      12,
+      3,
+      0,
+      30,
+      1,
+      "CLIP"
+    ],
+    [
+      13,
+      30,
+      0,
+      31,
+      0,
+      "MODEL"
+    ],
+    [
+      14,
+      31,
+      0,
+      32,
+      0,
+      "MODEL"
+    ],
+    [
+      15,
+      32,
+      0,
+      33,
+      0,
+      "MODEL"
+    ],
+    [
+      16,
+      33,
+      0,
+      34,
+      0,
+      "MODEL"
+    ],
+    [
+      17,
+      34,
+      0,
+      7,
+      0,
+      "MODEL"
+    ],
+    [
+      18,
+      30,
+      1,
+      7,
+      1,
+      "CLIP"
+    ]
+  ],
+  "groups": [],
+  "config": {},
+  "extra": {
+    "ds": {
+      "scale": 0.8264462809917354,
+      "offset": [
+        76.11091610712583,
+        -281.1386834420914
+      ]
+    }
+  },
+  "version": 0.4
+}

workflows/HandTieClips_Starter.json

@@ -0,0 +1,1358 @@
+{
+  "id": "h3-ref2va-chain",
+  "revision": 1,
+  "last_node_id": 34,
+  "last_link_id": 18,
+  "nodes": [
+    {
+      "id": 2,
+      "type": "UNETLoader",
+      "pos": [
+        0,
+        340
+      ],
+      "size": [
+        420,
+        82
+      ],
+      "flags": {},
+      "order": 0,
+      "mode": 0,
+      "inputs": [
+        {
+          "localized_name": "unet_name",
+          "name": "unet_name",
+          "type": "COMBO",
+          "widget": {
+            "name": "unet_name"
+          },
+          "link": null
+        },
+        {
+          "localized_name": "weight_dtype",
+          "name": "weight_dtype",
+          "type": "COMBO",
+          "widget": {
+            "name": "weight_dtype"
+          },
+          "link": null
+        }
+      ],
+      "outputs": [
+        {
+          "localized_name": "MODEL",
+          "name": "MODEL",
+          "type": "MODEL",
+          "slot_index": 0,
+          "links": [
+            11
+          ]
+        }
+      ],
+      "title": "DiT (ref2va)",
+      "properties": {
+        "cnr_id": "comfy-core",
+        "ver": "0.34.0",
+        "Node name for S&R": "UNETLoader"
+      },
+      "widgets_values": [
+        "minimax_h3_hybrid_fl2va_ref2va_b30-49-int8.safetensors",
+        "default"
+      ]
+    },
+    {
+      "id": 3,
+      "type": "CLIPLoader",
+      "pos": [
+        0,
+        460
+      ],
+      "size": [
+        420,
+        106
+      ],
+      "flags": {},
+      "order": 1,
+      "mode": 0,
+      "inputs": [
+        {
+          "localized_name": "clip_name",
+          "name": "clip_name",
+          "type": "COMBO",
+          "widget": {
+            "name": "clip_name"
+          },
+          "link": null
+        },
+        {
+          "localized_name": "type",
+          "name": "type",
+          "type": "COMBO",
+          "widget": {
+            "name": "type"
+          },
+          "link": null
+        },
+        {
+          "localized_name": "device",
+          "name": "device",
+          "shape": 7,
+          "type": "COMBO",
+          "widget": {
+            "name": "device"
+          },
+          "link": null
+        }
+      ],
+      "outputs": [
+        {
+          "localized_name": "CLIP",
+          "name": "CLIP",
+          "type": "CLIP",
+          "slot_index": 0,
+          "links": [
+            12
+          ]
+        }
+      ],
+      "title": "Text encoder",
+      "properties": {
+        "cnr_id": "comfy-core",
+        "ver": "0.34.0",
+        "Node name for S&R": "CLIPLoader"
+      },
+      "widgets_values": [
+        "qwen3vl_32b_minimax_h3_int8_convrot.safetensors",
+        "minimax",
+        "default"
+      ]
+    },
+    {
+      "id": 4,
+      "type": "VAELoader",
+      "pos": [
+        0,
+        600
+      ],
+      "size": [
+        420,
+        82
+      ],
+      "flags": {},
+      "order": 2,
+      "mode": 0,
+      "inputs": [
+        {
+          "localized_name": "vae_name",
+          "name": "vae_name",
+          "type": "COMBO",
+          "widget": {
+            "name": "vae_name"
+          },
+          "link": null
+        }
+      ],
+      "outputs": [
+        {
+          "localized_name": "VAE",
+          "name": "VAE",
+          "type": "VAE",
+          "slot_index": 0,
+          "links": [
+            3
+          ]
+        }
+      ],
+      "title": "Video VAE",
+      "properties": {
+        "cnr_id": "comfy-core",
+        "ver": "0.34.0",
+        "Node name for S&R": "VAELoader"
+      },
+      "widgets_values": [
+        "minimax_h3_video_vae_int8_convrot.safetensors"
+      ]
+    },
+    {
+      "id": 5,
+      "type": "VAELoader",
+      "pos": [
+        0,
+        720
+      ],
+      "size": [
+        420,
+        82
+      ],
+      "flags": {},
+      "order": 3,
+      "mode": 0,
+      "inputs": [
+        {
+          "localized_name": "vae_name",
+          "name": "vae_name",
+          "type": "COMBO",
+          "widget": {
+            "name": "vae_name"
+          },
+          "link": null
+        }
+      ],
+      "outputs": [
+        {
+          "localized_name": "VAE",
+          "name": "VAE",
+          "type": "VAE",
+          "slot_index": 0,
+          "links": [
+            4
+          ]
+        }
+      ],
+      "title": "Audio VAE",
+      "properties": {
+        "cnr_id": "comfy-core",
+        "ver": "0.34.0",
+        "Node name for S&R": "VAELoader"
+      },
+      "widgets_values": [
+        "minimax_h3_audio_vae_fp32.safetensors"
+      ]
+    },
+    {
+      "id": 7,
+      "type": "HandTieClips",
+      "pos": [
+        994,
+        427
+      ],
+      "size": [
+        968.3162169696975,
+        1426.2006199999998
+      ],
+      "flags": {},
+      "order": 4,
+      "mode": 0,
+      "inputs": [
+        {
+          "localized_name": "model",
+          "name": "model",
+          "type": "MODEL",
+          "link": 17
+        },
+        {
+          "localized_name": "clip",
+          "name": "clip",
+          "type": "CLIP",
+          "link": 18
+        },
+        {
+          "localized_name": "vae",
+          "name": "vae",
+          "type": "VAE",
+          "link": 3
+        },
+        {
+          "localized_name": "audio_vae",
+          "name": "audio_vae",
+          "type": "VAE",
+          "link": 4
+        },
+        {
+          "localized_name": "continuity_state",
+          "name": "continuity_state",
+          "shape": 7,
+          "type": "STRING",
+          "link": null
+        },
+        {
+          "localized_name": "prompt",
+          "name": "prompt",
+          "type": "STRING",
+          "widget": {
+            "name": "prompt"
+          },
+          "link": null
+        },
+        {
+          "localized_name": "chains",
+          "name": "chains",
+          "type": "COMBO",
+          "widget": {
+            "name": "chains"
+          },
+          "link": null
+        },
+        {
+          "localized_name": "resolution",
+          "name": "resolution",
+          "type": "COMBO",
+          "widget": {
+            "name": "resolution"
+          },
+          "link": null
+        },
+        {
+          "localized_name": "aspect",
+          "name": "aspect",
+          "type": "COMBO",
+          "widget": {
+            "name": "aspect"
+          },
+          "link": null
+        },
+        {
+          "localized_name": "duration",
+          "name": "duration",
+          "type": "COMBO",
+          "widget": {
+            "name": "duration"
+          },
+          "link": null
+        },
+        {
+          "localized_name": "overlap",
+          "name": "overlap",
+          "type": "COMBO",
+          "widget": {
+            "name": "overlap"
+          },
+          "link": null
+        },
+        {
+          "localized_name": "seed",
+          "name": "seed",
+          "type": "INT",
+          "widget": {
+            "name": "seed"
+          },
+          "link": null
+        },
+        {
+          "localized_name": "seed_per_shot",
+          "name": "seed_per_shot",
+          "type": "BOOLEAN",
+          "widget": {
+            "name": "seed_per_shot"
+          },
+          "link": null
+        },
+        {
+          "localized_name": "steps",
+          "name": "steps",
+          "type": "INT",
+          "widget": {
+            "name": "steps"
+          },
+          "link": null
+        },
+        {
+          "localized_name": "sampler_name",
+          "name": "sampler_name",
+          "type": "COMBO",
+          "widget": {
+            "name": "sampler_name"
+          },
+          "link": null
+        },
+        {
+          "localized_name": "scheduler",
+          "name": "scheduler",
+          "type": "COMBO",
+          "widget": {
+            "name": "scheduler"
+          },
+          "link": null
+        },
+        {
+          "localized_name": "shift_video",
+          "name": "shift_video",
+          "type": "FLOAT",
+          "widget": {
+            "name": "shift_video"
+          },
+          "link": null
+        },
+        {
+          "localized_name": "shift_audio",
+          "name": "shift_audio",
+          "type": "FLOAT",
+          "widget": {
+            "name": "shift_audio"
+          },
+          "link": null
+        },
+        {
+          "localized_name": "ref_image_size",
+          "name": "ref_image_size",
+          "type": "COMBO",
+          "widget": {
+            "name": "ref_image_size"
+          },
+          "link": null
+        },
+        {
+          "localized_name": "hop_script",
+          "name": "hop_script",
+          "shape": 7,
+          "type": "COMBO",
+          "widget": {
+            "name": "hop_script"
+          },
+          "link": null
+        },
+        {
+          "localized_name": "pin_to_qwen",
+          "name": "pin_to_qwen",
+          "shape": 7,
+          "type": "COMBO",
+          "widget": {
+            "name": "pin_to_qwen"
+          },
+          "link": null
+        },
+        {
+          "localized_name": "shot_plan",
+          "name": "shot_plan",
+          "shape": 7,
+          "type": "STRING",
+          "widget": {
+            "name": "shot_plan"
+          },
+          "link": null
+        },
+        {
+          "localized_name": "ref_plan",
+          "name": "ref_plan",
+          "shape": 7,
+          "type": "STRING",
+          "widget": {
+            "name": "ref_plan"
+          },
+          "link": null
+        },
+        {
+          "localized_name": "cache_hops",
+          "name": "cache_hops",
+          "shape": 7,
+          "type": "COMBO",
+          "widget": {
+            "name": "cache_hops"
+          },
+          "link": null
+        },
+        {
+          "localized_name": "cache_budget_gb",
+          "name": "cache_budget_gb",
+          "shape": 7,
+          "type": "FLOAT",
+          "widget": {
+            "name": "cache_budget_gb"
+          },
+          "link": null
+        },
+        {
+          "localized_name": "audio_pin_frames",
+          "name": "audio_pin_frames",
+          "shape": 7,
+          "type": "INT",
+          "widget": {
+            "name": "audio_pin_frames"
+          },
+          "link": null
+        },
+        {
+          "localized_name": "pin_renorm",
+          "name": "pin_renorm",
+          "shape": 7,
+          "type": "COMBO",
+          "widget": {
+            "name": "pin_renorm"
+          },
+          "link": null
+        },
+        {
+          "localized_name": "pin_noise",
+          "name": "pin_noise",
+          "shape": 7,
+          "type": "FLOAT",
+          "widget": {
+            "name": "pin_noise"
+          },
+          "link": null
+        },
+        {
+          "localized_name": "tone_compensate",
+          "name": "tone_compensate",
+          "shape": 7,
+          "type": "COMBO",
+          "widget": {
+            "name": "tone_compensate"
+          },
+          "link": null
+        },
+        {
+          "localized_name": "start_image_file",
+          "name": "start_image_file",
+          "shape": 7,
+          "type": "STRING",
+          "widget": {
+            "name": "start_image_file"
+          },
+          "link": null
+        },
+        {
+          "localized_name": "reference_video_file",
+          "name": "reference_video_file",
+          "shape": 7,
+          "type": "STRING",
+          "widget": {
+            "name": "reference_video_file"
+          },
+          "link": null
+        },
+        {
+          "localized_name": "voice_file",
+          "name": "voice_file",
+          "shape": 7,
+          "type": "STRING",
+          "widget": {
+            "name": "voice_file"
+          },
+          "link": null
+        }
+      ],
+      "outputs": [
+        {
+          "localized_name": "images",
+          "name": "images",
+          "type": "IMAGE",
+          "slot_index": 0,
+          "links": [
+            5
+          ]
+        },
+        {
+          "localized_name": "audio",
+          "name": "audio",
+          "type": "AUDIO",
+          "slot_index": 1,
+          "links": [
+            6
+          ]
+        },
+        {
+          "localized_name": "info",
+          "name": "info",
+          "type": "STRING",
+          "slot_index": 2,
+          "links": [
+            7
+          ]
+        }
+      ],
+      "properties": {
+        "Node name for S&R": "H3RefChain",
+        "h3_plan_backup": "{\n  \"shots\": [\n    {\n      \"id\": \"s1\",\n      \"beat\": \"Live-action, natural indoor light. The cook stands at the counter in @kitchen, looks up from the chopping board, and speaks one short line to someone off-frame.\",\n      \"directives\": {\n        \"camera\": \"hold\",\n        \"framing\": \"medium\",\n        \"pace\": \"steady\",\n        \"tail\": \"ongoing\"\n      }\n    },\n    {\n      \"id\": \"s2\",\n      \"beat\": \"The cook sets the knife down, turns toward the window, and finishes her last word as she looks out.\",\n      \"directives\": {\n        \"join\": \"continuous\",\n        \"camera\": \"push_in\",\n        \"framing\": \"close\",\n        \"pace\": \"steady\",\n        \"tail\": \"ongoing\"\n      }\n    },\n    {\n      \"id\": \"s3\",\n      \"beat\": \"The cook leans back against the counter with her lips closed, and lets her eyes move slowly across the room. The room is still, with only the low hum of the refrigerator.\",\n      \"directives\": {\n        \"join\": \"continuous\",\n        \"camera\": \"pull_back\",\n        \"framing\": \"medium\",\n        \"pace\": \"slow\",\n        \"tail\": \"settle\"\n      }\n    }\n  ]\n}",
+        "h3_editor_mode": "shots"
+      },
+      "widgets_values": [
+        "Live-action, natural indoor light. The person looks exactly as in the reference photographs.\n\nA cook in an apron stands at a kitchen counter, slicing. They look up, speak one short line, then turn back to the board.",
+        "2",
+        "0.3 MP",
+        "16:9 landscape",
+        "5 s",
+        "0.9 s",
+        427058607873049,
+        "fixed",
+        true,
+        7,
+        "res_multistep",
+        "simple",
+        12,
+        3,
+        "match",
+        "next",
+        "last frame",
+        "{\n  \"shots\": [\n    {\n      \"id\": \"s1\",\n      \"beat\": \"A cook in an apron stands at a kitchen counter, looks up from the chopping board and says, 'You are earlier than I expected.' She turns back to the board and goes on slicing, the knife tapping steadily against the wood.\",\n      \"directives\": {\n        \"camera\": \"hold\",\n        \"framing\": \"medium\",\n        \"pace\": \"steady\",\n        \"tail\": \"ongoing\"\n      }\n    },\n    {\n      \"id\": \"s2\",\n      \"beat\": \"She sets the knife down, turns toward the window and looks out at the street, her weight settling onto one hip. The kitchen is quiet apart from the low hum of the refrigerator.\",\n      \"directives\": {\n        \"join\": \"continuous\",\n        \"camera\": \"pan_follow\",\n        \"framing\": \"medium\",\n        \"pace\": \"steady\",\n        \"tail\": \"settle\"\n      }\n    }\n  ]\n}",
+        "{\n  \"refs\": [],\n  \"subjects\": {}\n}",
+        "on",
+        19,
+        24,
+        "off",
+        0,
+        "frame_shift",
+        "",
+        "",
+        "",
+        "Live-action, natural light, one continuous take."
+      ],
+      "title": "H3 Ref2VA Chain - starter"
+    },
+    {
+      "id": 16,
+      "type": "HTCChainPreview",
+      "pos": [
+        2258.827272727274,
+        -90.16060606060621
+      ],
+      "size": [
+        400,
+        460
+      ],
+      "flags": {},
+      "order": 5,
+      "mode": 0,
+      "inputs": [
+        {
+          "localized_name": "images",
+          "name": "images",
+          "type": "IMAGE",
+          "link": 5
+        },
+        {
+          "localized_name": "audio",
+          "name": "audio",
+          "shape": 7,
+          "type": "AUDIO",
+          "link": 6
+        },
+        {
+          "localized_name": "info",
+          "name": "info",
+          "shape": 7,
+          "type": "STRING",
+          "link": 7
+        }
+      ],
+      "outputs": [
+        {
+          "localized_name": "images",
+          "name": "images",
+          "type": "IMAGE",
+          "slot_index": 0,
+          "links": [
+            8
+          ]
+        },
+        {
+          "localized_name": "audio",
+          "name": "audio",
+          "type": "AUDIO",
+          "slot_index": 1,
+          "links": [
+            9
+          ]
+        }
+      ],
+      "properties": {
+        "Node name for S&R": "H3ChainPreview",
+        "h3rcPanelH": 40
+      },
+      "widgets_values": [
+        ""
+      ]
+    },
+    {
+      "id": 8,
+      "type": "CreateVideo",
+      "pos": [
+        2991.7272727272743,
+        37.33939393939383
+      ],
+      "size": [
+        300,
+        130
+      ],
+      "flags": {},
+      "order": 6,
+      "mode": 0,
+      "inputs": [
+        {
+          "localized_name": "images",
+          "name": "images",
+          "type": "IMAGE",
+          "link": 8
+        },
+        {
+          "localized_name": "audio",
+          "name": "audio",
+          "shape": 7,
+          "type": "AUDIO",
+          "link": 9
+        },
+        {
+          "localized_name": "fps",
+          "name": "fps",
+          "type": "FLOAT",
+          "widget": {
+            "name": "fps"
+          },
+          "link": null
+        },
+        {
+          "localized_name": "bit_depth",
+          "name": "bit_depth",
+          "shape": 7,
+          "type": "COMBO",
+          "widget": {
+            "name": "bit_depth"
+          },
+          "link": null
+        },
+        {
+          "localized_name": "color_space",
+          "name": "color_space",
+          "shape": 7,
+          "type": "COMBO",
+          "widget": {
+            "name": "color_space"
+          },
+          "link": null
+        }
+      ],
+      "outputs": [
+        {
+          "localized_name": "VIDEO",
+          "name": "VIDEO",
+          "type": "VIDEO",
+          "slot_index": 0,
+          "links": [
+            10
+          ]
+        }
+      ],
+      "properties": {
+        "cnr_id": "comfy-core",
+        "ver": "0.34.0",
+        "Node name for S&R": "CreateVideo"
+      },
+      "widgets_values": [
+        24,
+        "auto",
+        "sRGB"
+      ]
+    },
+    {
+      "id": 9,
+      "type": "SaveVideo",
+      "pos": [
+        3032.515151515151,
+        714.542424242424
+      ],
+      "size": [
+        340,
+        106
+      ],
+      "flags": {},
+      "order": 7,
+      "mode": 0,
+      "inputs": [
+        {
+          "localized_name": "video",
+          "name": "video",
+          "type": "VIDEO",
+          "link": 10
+        },
+        {
+          "localized_name": "filename_prefix",
+          "name": "filename_prefix",
+          "type": "STRING",
+          "widget": {
+            "name": "filename_prefix"
+          },
+          "link": null
+        },
+        {
+          "localized_name": "format",
+          "name": "format",
+          "type": "COMFY_DYNAMICCOMBO_V3",
+          "widget": {
+            "name": "format"
+          },
+          "link": null
+        },
+        {
+          "localized_name": "format.codec",
+          "name": "format.codec",
+          "type": "COMFY_DYNAMICCOMBO_V3",
+          "widget": {
+            "name": "format.codec"
+          },
+          "link": null
+        },
+        {
+          "localized_name": "codec",
+          "name": "codec",
+          "shape": 7,
+          "type": "COMFY_DYNAMICCOMBO_V3",
+          "widget": {
+            "name": "codec"
+          },
+          "link": null
+        }
+      ],
+      "outputs": [
+        {
+          "localized_name": "video",
+          "name": "video",
+          "type": "VIDEO",
+          "links": []
+        }
+      ],
+      "title": "SAVE",
+      "properties": {
+        "cnr_id": "comfy-core",
+        "ver": "0.34.0",
+        "Node name for S&R": "SaveVideo"
+      },
+      "widgets_values": [
+        "video/HANDTIECLIPS/chain",
+        "auto",
+        "auto",
+        "auto"
+      ]
+    },
+    {
+      "id": 30,
+      "type": "LTX_lora_loader",
+      "pos": [
+        520,
+        -40
+      ],
+      "size": [
+        420,
+        240
+      ],
+      "flags": {},
+      "order": 0,
+      "mode": 0,
+      "inputs": [
+        {
+          "name": "model",
+          "type": "MODEL",
+          "link": 11
+        },
+        {
+          "name": "clip",
+          "type": "CLIP",
+          "link": 12
+        }
+      ],
+      "outputs": [
+        {
+          "name": "model",
+          "type": "MODEL",
+          "links": [
+            13
+          ]
+        },
+        {
+          "name": "clip",
+          "type": "CLIP",
+          "links": [
+            18
+          ]
+        }
+      ],
+      "title": "LoRA Loader Stack (turbo)",
+      "properties": {
+        "htc_speed": "lora",
+        "Node name for S&R": "LTX_lora_loader"
+      },
+      "widgets_values": [
+        "minimax",
+        "[{\"on\":true,\"lora\":\"minimax_h3_ref2v_turbo_4step_v0.1_comfyui_bf16.safetensors\",\"str\":1,\"v\":1,\"a\":1,\"t\":1}]",
+        ""
+      ]
+    },
+    {
+      "id": 31,
+      "type": "H3AdaLNLoRAFix",
+      "pos": [
+        520,
+        240
+      ],
+      "size": [
+        340,
+        150
+      ],
+      "flags": {},
+      "order": 0,
+      "mode": 0,
+      "inputs": [
+        {
+          "name": "model",
+          "type": "MODEL",
+          "link": 13
+        }
+      ],
+      "outputs": [
+        {
+          "name": "MODEL",
+          "type": "MODEL",
+          "links": [
+            14
+          ]
+        }
+      ],
+      "title": "H3 AdaLN LoRA Fix",
+      "properties": {
+        "htc_speed": "adaln",
+        "Node name for S&R": "H3AdaLNLoRAFix"
+      },
+      "widgets_values": [
+        "port"
+      ]
+    },
+    {
+      "id": 32,
+      "type": "MiniMaxLowVRAMAttention",
+      "pos": [
+        520,
+        430
+      ],
+      "size": [
+        330,
+        58
+      ],
+      "flags": {},
+      "order": 0,
+      "mode": 0,
+      "inputs": [
+        {
+          "name": "model",
+          "type": "MODEL",
+          "link": 14
+        }
+      ],
+      "outputs": [
+        {
+          "name": "model",
+          "type": "MODEL",
+          "links": [
+            15
+          ]
+        }
+      ],
+      "title": "MiniMax H3 Low VRAM Attention",
+      "properties": {
+        "htc_speed": "lowvram",
+        "Node name for S&R": "MiniMaxLowVRAMAttention"
+      },
+      "widgets_values": [
+        4
+      ]
+    },
+    {
+      "id": 33,
+      "type": "H3SLAAttention",
+      "pos": [
+        520,
+        530
+      ],
+      "size": [
+        340,
+        322
+      ],
+      "flags": {},
+      "order": 0,
+      "mode": 0,
+      "inputs": [
+        {
+          "name": "model",
+          "type": "MODEL",
+          "link": 15
+        }
+      ],
+      "outputs": [
+        {
+          "name": "MODEL",
+          "type": "MODEL",
+          "links": [
+            16
+          ]
+        }
+      ],
+      "title": "H3 SLA Attention",
+      "properties": {
+        "htc_speed": "sla",
+        "Node name for S&R": "H3SLAAttention"
+      },
+      "widgets_values": [
+        0.9,
+        "64",
+        8192,
+        0,
+        true,
+        true,
+        "0",
+        "comfy_kitchen",
+        true,
+        true,
+        "Light"
+      ]
+    },
+    {
+      "id": 34,
+      "type": "ModelPreviewOverrideKJ",
+      "pos": [
+        520,
+        900
+      ],
+      "size": [
+        360,
+        480
+      ],
+      "flags": {},
+      "order": 0,
+      "mode": 0,
+      "inputs": [
+        {
+          "name": "model",
+          "type": "MODEL",
+          "link": 16
+        },
+        {
+          "name": "vae",
+          "type": "VAE",
+          "link": null
+        }
+      ],
+      "outputs": [
+        {
+          "name": "MODEL",
+          "type": "MODEL",
+          "links": [
+            17
+          ]
+        }
+      ],
+      "title": "Model Preview Override",
+      "properties": {
+        "htc_speed": "preview",
+        "Node name for S&R": "ModelPreviewOverrideKJ"
+      },
+      "widgets_values": [
+        512,
+        80,
+        true,
+        100,
+        8,
+        "taeh3.safetensors",
+        ""
+      ]
+    },
+    {
+      "id": 20,
+      "type": "MarkdownNote",
+      "pos": [
+        -960,
+        -400
+      ],
+      "size": [
+        440,
+        940
+      ],
+      "flags": {},
+      "order": 8,
+      "mode": 0,
+      "inputs": [],
+      "outputs": [],
+      "title": "START HERE",
+      "properties": {
+        "htc_card": "start"
+      },
+      "widgets_values": [
+        "## Start here\n\nTwo hops of 5 s, joined into one 10 s clip.\n\n### Requires\n\nThe MODEL wire is a turbo stack, not a bare loader:\n\n```\nUNETLoader\n  -> LoRA Loader Stack          (turbo LoRA)\n  -> H3 AdaLN LoRA Fix\n  -> MiniMax H3 Low VRAM Attention\n  -> H3 SLA Attention\n  -> Model Preview Override\n  -> this node\n```\n\n| pack | nodes |\n|---|---|\n| **ComfyUI-PlagueKind-Nodes** | LoRA Loader Stack, AdaLN Fix, SLA Attention |\n| **ComfyUI-KJNodes** | Low VRAM Attention (experimental), Model Preview Override |\n\nAlso on disk: the **turbo LoRA** named in the loader, and `taeh3.safetensors`\nfor the live preview (or set `tiny_vae` to `none`).\n\n**CLIP goes to this node from the LoRA loader, not from the encoder.** That is\nwhat makes the text half of every LoRA land. Do not rewire it back.\n\n`steps` is **7**, which only works with the turbo LoRA. Missing a pack? Its\nnodes load as red boxes -- delete them, wire the loader straight into `model`\nand the encoder into `clip`, and raise `steps` to 20 or so.\n\n1. Point the four **loaders** at your H3 files.\n2. Queue.\n3. Read the **SHOTS** cards on the node.\n\n**Shot 1 is the whole opening. Every later shot is only the new beat.** The node\nwrites the identity lock, the live-frame citation and the join itself -- so\nre-describing the face, the clothes or the room after shot 1 competes with the\nframe pin instead of reinforcing it.\n\nThis plan ships with **no references on purpose**, so it runs before you have\nsupplied any pictures.\n\n### Adding pictures\n\n- Open **REFERENCES**, add a row, drop a photo on its thumbnail. Files land in\n  `ComfyUI/input/h3_refs`. There is no Load Image node to wire.\n- Give the row a `@tag`, and group photos of the same person under one subject.\n- Write the tag into the beat: `@hero_face stands at the counter in @kitchen`.\n\nThe long-form guide is `PROMPTING.md` in the pack folder."
+      ],
+      "color": "#232",
+      "bgcolor": "#353"
+    },
+    {
+      "id": 21,
+      "type": "MarkdownNote",
+      "pos": [
+        -960,
+        600
+      ],
+      "size": [
+        440,
+        760
+      ],
+      "flags": {},
+      "order": 9,
+      "mode": 0,
+      "inputs": [],
+      "outputs": [],
+      "title": "The rules",
+      "properties": {
+        "htc_card": "rules"
+      },
+      "widgets_values": [
+        "## The rules that decide whether it works\n\nNot style preferences. This is how this model fails.\n\n### 1. The prompt is additive\n\nSampling runs at **cfg 1.0 with no negative branch**. Every concept you name is\nadded, and nothing can be removed by mentioning it -- `no cut` puts the word\n*cut* in front of the encoder. **Never write a negation.**\n\n### 2. Never name the thing you want to end\n\n\"The cook stops talking\" keeps her talking. Write the state you want as **a pose\nplus a sound**:\n\n> leans back against the counter with her lips closed, and lets her eyes move\n> slowly across the room. The kitchen is quiet apart from the low hum of the\n> refrigerator.\n\nAudio is always generated. Silence written as an absence comes back as speech,\nso **silence has to be written as a sound** -- room tone, a fridge, a single\nclick. Keep it narrowband: \"faint street noise\" renders as a five-second hiss.\n\n**The ban is on the idea, not on a word list.** *Fades, passes, wanes, subsides,\ndies down, eases off* all name an ending as surely as *stops* does, and all of\nthem add the thing they describe. Ask of each sentence: is this happening, or\nhas it finished happening?\n\n### 3. A state change belongs at the END of the previous shot\n\nEvery hop opens holding the frames it was handed, and the audio pin carries the\nprevious hop's tail across the join. Nothing you write in shot 3 can make shot 3\nstart quiet. **Arrive there before the previous shot ends.**\n\n### 4. A hop that ends on dialogue keeps talking\n\nSpeech at the end of hop N opens hop N+1 and propagates down the whole chain.\nLand each line **mid-hop** and leave a non-verbal action running into the seam --\nslicing, walking, a hand on a doorframe. Give every hop with no dialogue a sound\nbed of its own.\n\n### 5. A walk between two rooms is `match_cut`\n\n`join: continuous` across a real location change makes the model morph one room\ninto the other mid-movement.\n\n### 6. Set `tail` on your last shot\n\nLeft at `ongoing`, the model is told action is still underway at the final frame\nand will invent something to satisfy it. Use `settle` or `hold`."
+      ],
+      "color": "#432",
+      "bgcolor": "#653"
+    },
+    {
+      "id": 22,
+      "type": "MarkdownNote",
+      "pos": [
+        -960,
+        1420
+      ],
+      "size": [
+        440,
+        640
+      ],
+      "flags": {},
+      "order": 10,
+      "mode": 0,
+      "inputs": [],
+      "outputs": [],
+      "title": "References and @tags",
+      "properties": {
+        "htc_card": "refs"
+      },
+      "widgets_values": [
+        "## References and @tags\n\nA picture in the register does not make the model use it. **The beat is what\ndrives the frame** -- write the tag into the action line.\n\nPhrase a place as a place that is *depicted*, not as a container to be placed\ninside: \"at the counter in `@kitchen`\", not \"steps into `@kitchen`\".\n\n### Fields\n\n| field | what it does |\n|---|---|\n| `tag` | what you write in beats as `@tag` |\n| `file` | a bare filename in `input/h3_refs` |\n| `subject` | groups pictures **of the same person** |\n| `retention` | `fully_preserved` / `partially_copy` / `reference` |\n| `shots` | the 1-based hops this picture rides |\n\n**One subject number per person.** Two different people under one number makes\nthe model render the average of their faces.\n\n### `shots` is the part that decides continuity\n\n**A reference with no `shots` list rides hop 1 only.** Right for a **place**\nplate: a room still riding a hop set somewhere else beats the frame pin, and the\nmodel follows the still. **List every hop a picture belongs on.**\n\n**A face plate is the opposite \u2014 put it on every hop.** A hop scheduled with no\nface reference came back a different person, and no later hop recovered.\nIdentity drift does not self-correct.\n\n- Every **face** ref gets every hop: `\"shots\": [1, 2, 3, 4, 5, 6]`.\n- Keep a **place** ref on the hops set in that place, and off the rest.\n\n### `locked` and `context`\n\nPer-subject prose that rides **every hop**, with no picture citation, so it\ncarries identity across a hop where the photograph is absent. Give every subject\na `locked`, and a `name` -- from hop 2 on, `@tag` for a person resolves to that\nname.\n\n**Name a colour or it drifts.** A noun with no adjective is unanchored: each hop\nis an independent encode, so \"the bowl\" on hop 4 came back stainless steel. Put\nproperties in `context` -- \"the bowl is white porcelain\" -- never locations, and\nrepeat the adjective in every beat."
+      ],
+      "color": "#432",
+      "bgcolor": "#653"
+    },
+    {
+      "id": 23,
+      "type": "MarkdownNote",
+      "pos": [
+        -480,
+        -400
+      ],
+      "size": [
+        440,
+        640
+      ],
+      "flags": {},
+      "order": 11,
+      "mode": 0,
+      "inputs": [],
+      "outputs": [],
+      "title": "Directives",
+      "properties": {
+        "htc_card": "directives"
+      },
+      "widgets_values": [
+        "## Directives\n\nFive axes, all optional, set per shot. An unset axis emits nothing at all and\ncosts no tokens.\n\n| axis | values |\n|---|---|\n| `join` | `continuous`, `match_cut`, `hard_cut` -- **omit on shot 1** |\n| `camera` | `hold`, `pan_follow`, `push_in`, `pull_back`, `orbit`, `handheld` |\n| `framing` | `keep`, `wide`, `medium`, `close` |\n| `pace` | `slow`, `steady`, `brisk` |\n| `tail` | `ongoing` (default), `settle`, `hold` |\n\nThey compile in that order -- `join` first, because it describes how this hop\nmeets the previous one.\n\n### Two combinations the node warns about\n\n**`join: continuous` + a framing change + `camera: hold`.** A framing change asks\nthe audience to be somewhere new; with the camera still, the only way there is a\ncut. Earn it on the move (`push_in`, `pull_back`, `pan_follow`) or use\n`framing: keep`.\n\n**`push_in` + `wide`, or `pull_back` + `close`.** The move points the opposite way\nfrom the destination.\n\nBoth are warnings, not errors. They are legitimate things to want -- they just\nrarely read the way you meant.\n\n### Duration\n\nPer-shot `duration` overrides the chain, using exactly these labels:\n`\"5 s\"`, `\"7 s\"`, `\"8 s\"`, `\"10 s\"`, `\"15 s\"`."
+      ],
+      "color": "#432",
+      "bgcolor": "#653"
+    },
+    {
+      "id": 24,
+      "type": "MarkdownNote",
+      "pos": [
+        -480,
+        280
+      ],
+      "size": [
+        440,
+        760
+      ],
+      "flags": {},
+      "order": 12,
+      "mode": 0,
+      "inputs": [],
+      "outputs": [],
+      "title": "When it goes wrong",
+      "properties": {
+        "htc_card": "trouble"
+      },
+      "widgets_values": [
+        "## When it goes wrong\n\n| symptom | cause | fix |\n|---|---|---|\n| The clip cuts to the reference photo in its last seconds | The beat finished before the frames did | Set `tail`, give the beat enough to do |\n| A stray gesture or line in the closing second | `tail: ongoing` on the final shot | `settle` or `hold` |\n| She keeps talking after you asked for quiet | You named the ending | Pose plus a sound |\n| Dialogue continues into hops that have none written | The hop before ended on speech | Land the line early; non-verbal action into the seam; a sound bed on every quiet hop |\n| A character walks between two rooms and one morphs into the other | `continuous` across a location change | `match_cut` |\n| Silence renders as speech | Silence written as an absence | Name room tone, a fridge, a distant car |\n| Ambience is a five-second hiss | Broadband wording | Narrowband, or one discrete event |\n| Two characters' faces merge | Both declared as the same `subject` | One subject number per person |\n| The face becomes a different person partway through | A hop scheduled with no face plate. `locked` holds a face that is still right; only a plate rebuilds one that is gone, and the drift never self-corrects | Put the face ref on **every** hop |\n| A stylised plan renders photoreal | The node's hop-1 establishing line asserts live action | Name the medium in shot 1's first sentence, or clear the `establish` widget |\n| The film gets darker every hop | Luminance drifts one way and nothing pushes back | Restate the light as a positive property in every beat |\n| A location introduced mid-plan drifts | It has no place plate of its own | Plate it, on the hop it arrives and every hop after |\n| A prop or garment changes colour or material | Named with no adjective, so each hop's encode is free to invent one | Repeat the adjective in every beat, and state it as a property in `context` |\n| A hard cut ~1.5 s into a hop, mid-scene | The previous hop over-delivered, so this beat instructs what its own live frame already did | One movement per hop; write the next beat so it is true from either ending |\n| A continuous join reads as a cut | Framing change with `camera: hold` | Earn it on the move, or `framing: keep` |\n| The run stops, naming a reference | That row's picture is not in `h3_refs` | Drop the file on the row, or clear its picture to run without it |\n| A reference has no effect on some hop | Its `shots` list leaves that hop out | List every hop the picture should ride |\n| A pasted plan is rejected as invalid JSON | Escaped double quotes mangled in transit | Single quotes around dialogue |\n\nEvery error message names the shot or the reference it came from. Nothing\nguesses."
+      ],
+      "color": "#432",
+      "bgcolor": "#653"
+    },
+    {
+      "id": 25,
+      "type": "MarkdownNote",
+      "pos": [
+        -480,
+        1080
+      ],
+      "size": [
+        440,
+        620
+      ],
+      "flags": {},
+      "order": 13,
+      "mode": 0,
+      "inputs": [],
+      "outputs": [],
+      "title": "Let a model write it",
+      "properties": {
+        "htc_card": "author"
+      },
+      "widgets_values": [
+        "## Let a model write your plan\n\n`prompt_pack/` in the pack folder turns any chat model into a plan writer. In\nLM Studio, or anything with a system-prompt box:\n\n1. Load a model with **context 8192 or more**. The prompt is ~2,600 tokens and\n   the reply another 1,000-2,000; a 4k window truncates the rules and you get\n   invented directive names.\n2. Paste **`prompt_pack/SYSTEM_PROMPT.md`** into the **System Prompt** box.\n   Nothing else goes in that box.\n3. **Temperature 0.3-0.5.** Higher and the JSON grows trailing commas and smart\n   quotes.\n4. Describe the scene, and say how many hops and what pictures you have:\n\n   > Six hops. A cook in a kitchen; she says one line, walks out into a hallway,\n   > waits by a window, then comes back. I have a face photo, a photo of her\n   > apron, and a photo of the kitchen.\n\n5. Each panel section has its own **JSON** disclosure at the bottom. The first\n   ```json``` block goes in the one under **SCRIPT** (`shot_plan`), the second\n   in the one under **REFERENCES** (`ref_plan`). Bad JSON keeps the last good\n   version on screen and says so, rather than discarding your paste.\n6. **If the node rejects it, paste the error straight back into the chat.** One\n   round trip usually fixes it.\n\nWant it to match a shape? Paste `prompt_pack/EXAMPLE_6_HOP.md` first.\n\nSmall models (7B-8B) hold the JSON schema but drift on the prose rules -- they\nwrite negations. Skim the beats before queueing."
+      ],
+      "color": "#432",
+      "bgcolor": "#653"
+    }
+  ],
+  "links": [
+    [
+      3,
+      4,
+      0,
+      7,
+      2,
+      "VAE"
+    ],
+    [
+      4,
+      5,
+      0,
+      7,
+      3,
+      "VAE"
+    ],
+    [
+      5,
+      7,
+      0,
+      16,
+      0,
+      "IMAGE"
+    ],
+    [
+      6,
+      7,
+      1,
+      16,
+      1,
+      "AUDIO"
+    ],
+    [
+      7,
+      7,
+      2,
+      16,
+      2,
+      "STRING"
+    ],
+    [
+      8,
+      16,
+      0,
+      8,
+      0,
+      "IMAGE"
+    ],
+    [
+      9,
+      16,
+      1,
+      8,
+      1,
+      "AUDIO"
+    ],
+    [
+      10,
+      8,
+      0,
+      9,
+      0,
+      "VIDEO"
+    ],
+    [
+      11,
+      2,
+      0,
+      30,
+      0,
+      "MODEL"
+    ],
+    [
+      12,
+      3,
+      0,
+      30,
+      1,
+      "CLIP"
+    ],
+    [
+      13,
+      30,
+      0,
+      31,
+      0,
+      "MODEL"
+    ],
+    [
+      14,
+      31,
+      0,
+      32,
+      0,
+      "MODEL"
+    ],
+    [
+      15,
+      32,
+      0,
+      33,
+      0,
+      "MODEL"
+    ],
+    [
+      16,
+      33,
+      0,
+      34,
+      0,
+      "MODEL"
+    ],
+    [
+      17,
+      34,
+      0,
+      7,
+      0,
+      "MODEL"
+    ],
+    [
+      18,
+      30,
+      1,
+      7,
+      1,
+      "CLIP"
+    ]
+  ],
+  "groups": [
+    {
+      "id": 1,
+      "title": "READ ME -- writing for this node",
+      "bounding": [
+        -990,
+        -465,
+        980,
+        2560
+      ],
+      "color": "#3f789e",
+      "font_size": 24
+    }
+  ],
+  "config": {},
+  "extra": {
+    "ds": {
+      "scale": 0.8264462809917354,
+      "offset": [
+        500,
+        -281.1386834420914
+      ]
+    }
+  },
+  "version": 0.4
+}