@melite/models-h3 0.0.0-stage → 0.1.5-pre-alpha

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/lib/actions.js ADDED
@@ -0,0 +1,1626 @@
1
+ import { fireControlNets } from '@melite/comfyui-card-kit/guard';
2
+ import { saveAudio } from '@melite/comfyui-card-kit';
3
+ import { FAMILIES, paramSchema, wireList, H3_RECOMMENDED_SAMPLERS } from "./schema.js";
4
+ import { H3_LORA_ROWS } from '@melite/models-h3/mods/loras';
5
+ import { SAMPLER_OPTIONS, SCHEDULER_OPTIONS } from '@melite/comfyui-card-kit/vocab';
6
+ import { computeFilmMix, parseFilmMixClips, stanzaSecs } from "./filmMix.js";
7
+ import { GRID_REMAINDER, GRID_STEP_FRAMES, IMAGE_BUS_SLOTS, REF_CAPS, assertGridLength, assertSpanGrid, imageReferenceCap, spanStanzaFrames, transitionOverlap, } from "./timelineContract.js";
8
+
9
+ // the ByteDance DMAD row — operator: "the one from bytedance" is the
10
+ // default): the DMAD 4-step row, built from the family lora
11
+ // CATALOG (mods/loras.ts — the one owner of every lora filename and
12
+ // default strength; the value was restated as a literal here, which
13
+ // is how a catalog edit would have silently missed the default).
14
+ // The wire shape matches a resolved bag row: on, lora (filename),
15
+ // str (default_strength), plus the four fixed mode flags. A missing
16
+ // catalog row refuses at load — the default would have no source.
17
+ const loraStackDefault = () => {
18
+ const row = H3_LORA_ROWS.find((r) => r.id === 'h3_dmad_4step');
19
+ if (row === undefined) {
20
+ throw new Error("h3 action: the lora catalog has no 'h3_dmad_4step' row — the absent-bag default has no source; fix the catalog row id");
21
+ }
22
+ return JSON.stringify([{ on: true, lora: row.filename, str: row.default_strength, v: 1, a: 1, t: 1 }]);
23
+ };
24
+ // His 17k+5 grid, in-graph (ComfyMathExpression): snap latent steps to 2 mod 5
25
+ // (the card's own principles row: "Length snaps to the 17k+5 frame grid
26
+ // at 24fps" — the principles).
27
+ const MATH_STEPS_GOLD = `max(${GRID_REMAINDER}, round(a * 24)) + (${GRID_REMAINDER} - (max(${GRID_REMAINDER}, round(a * 24)) % ${GRID_STEP_FRAMES})) % ${GRID_STEP_FRAMES}`;
28
+
29
+ // finding #4): MiniMaxH3ImageToVideo exists in the serialized graph
30
+ // ONLY as the t4r family marker (finalizeH3 keys on it to skip the
31
+ // t4 autofill strip). It is FULLY ORPHANED — no switch consumes it,
32
+ // so no switch can ever select it. The old dead branch carried a
33
+ // 700-char sprinting-city gold prompt through every request sidecar:
34
+ // an off-topic injection-shaped blob and a live hazard the day a
35
+ // switch flipped. Orphan + stub prompt = the marker law kept, the
36
+ // hazard structurally dead.
37
+ const I2V_MARKER_PROMPT = 'i2v marker branch — orphaned, never executed (r2v is the only lane)';
38
+ // ImageSharpenKJ's grouped-widget defaults (the rcas block the python
39
+ // builds when no sharpen leaf is injected; the card exposes only the
40
+ // strength leaf — sharpen_strength).
41
+ const SHARPEN_DEFAULTS = { method: 'rcas', strength: 0.3, radius: 1.0, threshold: 0.05, iterations: 10 };
42
+
43
+
44
+
45
+
46
+
47
+
48
+
49
+
50
+
51
+
52
+
53
+
54
+ const LANE_FILES = {
55
+ clip: 'qwen3vl_32b_minimax_h3_int8_convrot.safetensors',
56
+ vae_video: 'minimax_h3_video_vae_int8_convrot.safetensors',
57
+ vae_audio: 'minimax_h3_audio_vae_fp32.safetensors',
58
+ sr_vae: 'ema_vae_fp16.safetensors',
59
+ };
60
+
61
+
62
+
63
+
64
+
65
+
66
+ const FILM_BIT_DEPTH = 8;
67
+ export function parseH3Facts(raw) {
68
+ const lane = (raw ?? {});
69
+ const unet = lane.unet;
70
+ // CARVE (F4 verification D5): stricter than requireText on purpose —
71
+ // this lane refuses whitespace-only unets (trim), the kit helper
72
+ // refuses only ''. Consolidating onto the helper would silently
73
+ // relax this law.
74
+ if (typeof unet !== 'string' || unet.trim() === '') {
75
+ throw new Error(`h3 film: lane_inputs.unet = ${JSON.stringify(unet)} — a non-empty string is required`);
76
+ }
77
+ return { unet, clip: LANE_FILES.clip, vae_video: LANE_FILES.vae_video, vae_audio: LANE_FILES.vae_audio };
78
+ }
79
+ /** The overlay re-check the film loop voices per stanza (the same
80
+ * carrier the card's compose gate walks — ONE schema, imported).
81
+ * Exported so the card's single-call lift judges through the same
82
+ * re-check (the h3-b duplicate is gone: one owner). */
83
+ export const assertOverlayGated = (doc, where) => {
84
+ try {
85
+ paramSchema(doc);
86
+ }
87
+ catch (e) {
88
+ throw new Error(`${where}: ${String(e)}`);
89
+ }
90
+ };
91
+ /** THE MERGED FILM: ONE prompt, N windows under `window${k}_`
92
+ * scopes (GraphBuilder.scoped), with real seam edges between scopes
93
+ * (the executor orders windows off the graph) and per-window
94
+ * stanzas in the renderer vocabulary (k, ctx_save_clip_index, the
95
+ * per-call knobs REPLACE, the span rider per window). The seam is
96
+ * the studio's document law (docModel): transition 'extend' (absent
97
+ * = extend) chains the previous LATENT; 'cut' is a fresh window, and
98
+ * 'cut' + first_frame_prev_sec opens from the previous VIDEO tail
99
+ * (the node's context_frames arm). prev_sec scales the carry:
100
+ * picture snapped to the node's legal context lengths (5/22/39/56
101
+ * frames — only whole latent steps), audio at 24 frames/second. */
102
+ function renderH3Film(p, g, facts, model) {
103
+ // (the compose dispatch guarantees calls is a non-empty array here)
104
+ const calls = p.calls;
105
+ const str = (v) => (typeof v === 'string' ? v : '');
106
+ const num = (v) => (typeof v === 'number' && Number.isFinite(v) ? v : null);
107
+ let prev;
108
+ // every window's SaveVideo passthrough, in film order — the film
109
+
110
+ // last-save-only boundary left cut windows' saves unordered)
111
+ const windowSaves = [];
112
+
113
+ // composition — the ENGINE'S job, never a harness-side ffmpeg).
114
+
115
+ // MotionContext seam exists): ONE mechanic, automatic — the
116
+ // TimelineDirector drift-control continuation. Every window k≥2
117
+ // carries the previous window's sampled latent through
118
+ // MiniMaxH3FiniteLatentContinuation (schedule-matched prefix noise
119
+ // + Soft AV audio release); a 'cut' call is their overlap-0 arm
120
+ // (independent windows, no guidance). No seam vocabulary, no
121
+ // modes — the film accumulates through their finalize chain
122
+ // (video: the previous window owns the overlap; audio: the
123
+ // incoming soft-released head owns the join). §20, THREE ACTS
124
+
125
+ // window's tensors until the final CreateVideo — the OOM signature
126
+ // that killed positioned-clips films 3× (a 43h engine); (2) the
127
+ // one-day disk-side valve (estate ffmpeg) died of the operator's
128
+ // provenance law — every artifact traces to a composition of
129
+ // cards, never a harness side-effect; (3) the FILE FORM now below:
130
+ // each window saves its own clip, an unload boundary orders +
131
+ // flushes, and a file-decoding tail assembles the film IN-GRAPH —
132
+ // no tensor ever spans the boundary. The mix math lives in
133
+ // filmMix.ts — one owner, stamps and overlay both.
134
+ // THE CONDITIONING stamps below stay in-graph per-window (what
135
+ // each window HEARS at generation — lip sync lives here). The
136
+ // overlay half (positions, duck spans, the music bus) rides the
137
+ // post-generation MeliteFilmAudioMix for clips-carrying films
138
+ // (the valve's second arm) and the clips-free file tail otherwise
139
+ // — both driven by the same filmMix.ts manifest.
140
+
141
+ // per-window CONDITIONING stamps (the model hears the dialogue:
142
+ // lip sync) read THIS list — parseFilmMixClips (filmMix.ts) is
143
+ // the one law for what a clip IS, shared with the post-generation
144
+ // mix node (its clips_json rows carry the parsed seats verbatim).
145
+
146
+ // clip rides one CLASS — dialogue | sfx | music — one H3 audio
147
+ // input each. Every class runs the SAME machinery (stamp → pin →
148
+ // prompt field → overlay); only the prompt field and the duck
149
+ // relationships differ. Default: a text-carrying row is dialogue
150
+ // (the words law), a textless row is music (the historical
151
+ // Music-row behavior, byte-identical for existing docs).
152
+ const clips = parseFilmMixClips(Array.isArray(p.audio_clips) ? p.audio_clips : []);
153
+ // THE FILM DOC'S SPANS — the clock's own rows, one per call, doc
154
+ // frames with the seam word (filmMix.ts owns the law). The stanza
155
+ // snap rides these (spanStanzaFrames): the render loop below and
156
+ // the film manifest at the tail read the SAME snap from the SAME
157
+ // rows — the two-clocks law, one owner.
158
+ const spans = calls.map((c) => ({
159
+ // the shot-law loop above pins every row's int spans (loud
160
+ // refusals upstream) — no defensive fallback arms to keep alive
161
+ start: c.start_frame,
162
+ end: c.end_frame,
163
+ // the seam word rides RAW — filmMix's spanOverlap owns the one
164
+ // meaningful comparison ('cut' = overlap 0; every other spelling
165
+ // including absent IS extend); no card-side re-encoding
166
+ transition: str(c.transition),
167
+ }));
168
+ // (the clip text law lives where the text is consumed: THE
169
+ // TRANSCRIPT — dialogue words ride the <d> prompt tag, sfx text
170
+ // the soundscape field, music text non_diegetic_music. In every
171
+ // class the text tells the model WHAT the audio is.)
172
+
173
+ // adapter is married to its step count — one lora for four steps,
174
+ // another for eight — so the resolved bag rows carry `steps` and
175
+ // the windows honor it. LAYERING: a call's own knobs > the lora
176
+ // entry's steps > this steps row (the row is the no-distill
177
+ // default; a user-stacked pair runs at the HIGHER count — 8 steps
178
+ // on a 4-step distill is fine, 4 on an 8-step is undercooked).
179
+ const loraRows = Array.isArray(p.loras) ? p.loras : [];
180
+ const loraStepsList = loraRows
181
+ .map((r) => r.steps)
182
+ .filter((v) => typeof v === 'number' && Number.isFinite(v));
183
+ const loraStepsApplied = loraStepsList.length > 0 ? Math.max(...loraStepsList) : null;
184
+ calls.forEach((call, i) => {
185
+ const k = i + 1;
186
+ const guide = str(call.image ?? call.ref_image ?? call.image_name);
187
+ // A CALL OWNS ITS TEXT (the operator's no-fallbacks law, enforced
188
+
189
+ // a source substitution, the exact crime class the law bans). The
190
+ // directing skill's own contract says it: "A call needs text (or
191
+ // beats — prompt segments WITHIN the call)". The film-level prompt
192
+ // is the single-window shape's text face (lifted there by the
193
+ // single-call mapping) — NEVER a per-call substitute.
194
+ let text = typeof call.text === 'string' ? call.text.trim() : '';
195
+ if (text === '') {
196
+ throw new Error(`calls[${i}]: a call needs its own text — the film-level prompt is not a fallback (write the shot's text on the call)`);
197
+ }
198
+
199
+ // call is the director's overlap-0 arm (independent windows — no
200
+ // continuation, no guidance, nothing carried); every other seam
201
+ // rides the drift-control continuation at their proven default
202
+ // (22 frames ≈ 0.92s). first_frame_prev_sec retired with the
203
+ // MotionContext seam — cross-run continuity is the FL2VA anchor
204
+ // (set the first-frame square to the previous film's last frame).
205
+ const overlap = transitionOverlap(typeof call.transition === 'string' ? call.transition : undefined);
206
+ const knobs = (call.knobs ?? {});
207
+ // refs are a LAYER B (per-call) property — the reference bundle
208
+ // rides the stanza; a refs-carrying call is t4r EVEN without a
209
+ // guide still (the bundle IS the r2v input). The DECLARED input
210
+ // surface (ref_images/ref_videos/ref_audios — Layer A, the
211
+ // card's own params) implies t4r by the same law.
212
+ const rb = (call.refs ?? {});
213
+ const declaredRefCount = wireList(p.ref_images).length + wireList(p.ref_videos).length + wireList(p.ref_audios).length;
214
+ const hasRefs = declaredRefCount + wireList(rb.images).length + wireList(rb.videos).length + wireList(rb.audios).length > 0;
215
+ const chainLike = i > 0 && overlap > 0;
216
+ const sf = num(call.start_frame);
217
+ const ef = num(call.end_frame);
218
+ const stamps = {};
219
+ if (sf !== null && ef !== null && Number.isFinite(sf) && Number.isFinite(ef) && ef > sf) {
220
+ const carry = i > 0 ? overlap : 0;
221
+ const genStart = sf - carry;
222
+ for (let ci = 0; ci < clips.length; ci++) {
223
+ const clip = clips[ci];
224
+ if (clip.dur <= 0)
225
+ continue;
226
+ if (stamps[clip.cls] !== undefined)
227
+ continue; // one lane per class per window
228
+ const lo = Math.max(clip.start, genStart);
229
+ const hi = Math.min(clip.start + clip.dur, ef);
230
+ if (hi - lo < 2.4)
231
+ continue; // below the slice node's 0.1s floor
232
+ const ms = (frames) => Math.round((frames / 24) * 1000) / 1000;
233
+ stamps[clip.cls] = {
234
+ src: clip.src,
235
+ slice_start_seconds: ms(Math.max(0, genStart - clip.start)),
236
+ slice_duration_seconds: ms(hi - lo),
237
+ delay_seconds: ms(Math.max(0, clip.start - genStart)),
238
+ text: clip.text,
239
+ };
240
+ // (§20: the conditioned set moved to filmMix.ts — the
241
+ // post-generation mix node derives it from the same stamp
242
+ // law. The stamps themselves stay: THIS window hears them.)
243
+ }
244
+ }
245
+ // THE PROMPT FIELDS (the guide's law, one per lane): dialogue
246
+ // rides <d> tags — the exact words at the stamp's LOCAL time
247
+ // (MM:SS.mmm, the window's own clock), never translated or
248
+ // rewritten; this is the half the audio-only conditioning
249
+ // lacked: the audio pins the voice, the tag moves the mouth.
250
+ // SFX rides the soundscape field at its onset time (the model
251
+ // HEARS the blast and times the visual to it); music rides
252
+ // non_diegetic_music. Same delay number, same clock.
253
+ const stampClock = (t) => {
254
+ const mm = String(Math.floor(t / 60)).padStart(2, '0');
255
+ const ss = String(Math.floor(t % 60)).padStart(2, '0');
256
+ const mmm = String(Math.round((t % 1) * 1000)).padStart(3, '0');
257
+ return `${mm}:${ss}.${mmm}`;
258
+ };
259
+ // ONE overall_soundscape FIELD per window (finding 11,
260
+
261
+ // stamp and an sfx stamp once composed TWO fields with separate
262
+ // `At MM:SS.mmm` clocks in one prompt — the format admits one
263
+ // field, and no authoring move avoided it short of dropping a
264
+ // lane. The sentences collect in lane order (dialogue first,
265
+ // then sfx — the historical append order) and ride a single
266
+ // field; each sentence keeps its own lane clock (the one-clock
267
+ // law trims a doubled clock off ONE text, never across lanes).
268
+ const soundscapeSentences = [];
269
+ if (stamps.dialogue !== undefined && stamps.dialogue.text !== '') {
270
+ const t = stampClock(stamps.dialogue.delay_seconds);
271
+ // SPEAKER-NEUTRAL (attempt-019 maker finding): the stamp once
272
+ // hard-coded "She says" — a plainly male harbourmaster got a
273
+ // female pronoun in his own mouth. The speaker is whoever the
274
+ // window shows; the stamp never genders them.
275
+ soundscapeSentences.push(`At ${t}, the on-screen speaker says the line below, mouth visible and articulating the words; room tone continues underneath.\nThe line: <d>[English] ${stamps.dialogue.text}</d>`);
276
+ }
277
+ if (stamps.sfx !== undefined && stamps.sfx.text !== '') {
278
+
279
+ // opens with its own "At MM:SS.mmm," clock must not carry two clocks —
280
+ // the stamp's clock is canonical, the authored one is trimmed.
281
+ const sfxText = stamps.sfx.text
282
+ .replace(/^\s*at\s+\d{1,2}:\d{2}(?:\.\d{1,3})?\s*[,-]\s*/i, '');
283
+ soundscapeSentences.push(`At ${stampClock(stamps.sfx.delay_seconds)}, ${sfxText}`);
284
+ }
285
+ if (soundscapeSentences.length > 0) {
286
+ text = text.replace(/\s+$/, '') + '\n\noverall_soundscape:\n' + soundscapeSentences.join('\n');
287
+ }
288
+ if (stamps.music !== undefined && stamps.music.text !== '') {
289
+ text = text.replace(/\s+$/, '') +
290
+ `\n\nnon_diegetic_music:\n${stamps.music.text}`;
291
+ }
292
+
293
+ // law, paid for on the BRIEF9 films): unless the model is told
294
+ // 'no speech' OR given speech-carrying audio, it INVENTS random
295
+ // gibberish dialogue. A window with no dialogue stamp and no
296
+ // live ref audios is exactly that window — an sfx/music bed does
297
+ // NOT count (the first BRIEF9 window carried the bed on the sfx
298
+ // lane and still gibberished; only the dialogue-conditioned
299
+ // window came out clean). The card stamps the indicator itself:
300
+ // model memory is not a seat. Ref audios count as audio input
301
+ // only when the door guard leaves them live (an unstamped
302
+ // window); an authored indication of any spelling ('no speech',
303
+ // 'no dialogue', 'no voice') is honored, never doubled.
304
+ const voicePinnedHere = stamps.dialogue !== undefined || stamps.sfx !== undefined;
305
+ const hearsRefAudio = !voicePinnedHere
306
+ && (wireList(p.ref_audios).length > 0 || wireList(rb.audios).length > 0);
307
+ if (stamps.dialogue === undefined && !hearsRefAudio && !/\bno[\s_-]*(speech|dialogue|voice)/i.test(text)) {
308
+ text = text.replace(/\s+$/, '') +
309
+ '\n\noverall_soundscape:\nNo speech or dialogue in this shot — ambient and effects only; nobody speaks on screen and there is no voice-over.';
310
+ }
311
+ const stanza = { ...p, ...knobs, prompt: text, k };
312
+
313
+ // its media lanes DIRECTLY — last_frame / ref_images /
314
+ // ref_videos / ref_audios on the call row — and the schema
315
+ // admits them (the media gate walks them), so the compose MUST
316
+ // read them or they die schema-green and engine-blind. A stated
317
+ // lane REPLACES the declared (film) lane, an absent one
318
+ // inherits — the same per-seat canon the refs bag rides.
319
+ if (typeof call.last_frame === 'string' && call.last_frame.trim() !== '')
320
+ stanza.last_frame = call.last_frame;
321
+ if (wireList(call.ref_images).length > 0)
322
+ stanza.ref_images = call.ref_images;
323
+ if (wireList(call.ref_videos).length > 0)
324
+ stanza.ref_videos = call.ref_videos;
325
+ if (wireList(call.ref_audios).length > 0)
326
+ stanza.ref_audios = call.ref_audios;
327
+ const hasDirectRefs = wireList(call.ref_images).length + wireList(call.ref_videos).length + wireList(call.ref_audios).length > 0
328
+ || (typeof call.last_frame === 'string' && call.last_frame.trim() !== '');
329
+ const anyStamp = stamps.dialogue !== undefined || stamps.sfx !== undefined || stamps.music !== undefined;
330
+ stanza.variant = (guide !== '' || hasRefs || hasDirectRefs || anyStamp) ? 't4r' : chainLike ? 't4_chain' : 't4_open';
331
+ // the distill's steps apply unless this call's knobs pinned steps
332
+ if (knobs.steps === undefined && loraStepsApplied !== null)
333
+ stanza.steps = loraStepsApplied;
334
+ // THE DOOR GUARD, voice arm: a dialogue/sfx-pinned window mutes
335
+ // the user ref audios (film-level and per-call) — the pins own
336
+ // that window's audio conditioning; the ref doors reopen on
337
+ // unstamped windows.
338
+ const voicePinned = stamps.dialogue !== undefined || stamps.sfx !== undefined;
339
+ if (voicePinned)
340
+ delete stanza.ref_audios;
341
+
342
+ // ANY lane rides it — refs (bundle bus) OR mods (conditioning
343
+ // tokens). The operator caught the hole live: a mods-only call
344
+ // lost its whole bag (hasRefs counted only the bus lanes, so the
345
+ // reference packs silently died). Mods never flip the arm (the
346
+ // refmod seam's own law below), so the gate widened here is the
347
+ // one behavior change — a mods-only call stays FL2VA.
348
+ const callMods = wireList(rb.mods);
349
+ if (hasRefs || callMods.length > 0)
350
+ stanza.refs = voicePinned && Array.isArray(call.refs?.audios)
351
+ ? { ...call.refs, audios: undefined }
352
+ : call.refs;
353
+ if (guide !== '')
354
+ stanza.image = guide;
355
+ else
356
+ delete stanza.image;
357
+ if (sf !== null && ef !== null && ef > sf) {
358
+ // THE UNIFORM SPAN GATE, second door: a stale or hand-built
359
+ // document re-rides the same law the walk admitted under, so
360
+ // the compose carrier refuses an off-grid span before any node
361
+ // is built (zero GPU) instead of trusting the render snap.
362
+ assertSpanGrid(spans[i], `h3-timeline window ${k}`, chainLike ? overlap : 0);
363
+ }
364
+ // per-window length: the span rider law, unless the call's knobs pin one
365
+ if (sf !== null && ef !== null && ef > sf && knobs.length === undefined) {
366
+
367
+ // covers carry + span — the finalize trims the carried head
368
+ // off the SAVED clip, so the span's tail must exist inside
369
+ // the generation. chainLike is the render's own carry law
370
+ // (i>0 and a non-cut seam) — the same number filmMix's
371
+ // stanzaSecs states (the two-clocks law, still one owner).
372
+ stanza.length = spanStanzaFrames(spans[i], chainLike ? overlap : 0);
373
+
374
+ // film): the window's VIDEO length derives from fps_seconds
375
+ // (the builder's ComfyMathExpression reads it; the length
376
+ // param alone only feeds the film clock's accounting). A doc
377
+ // whose spans disagree with the stale fps_seconds renders
378
+ // uniform 10s windows while the clock books doc spans — the
379
+ // film clock and the render MUST state the same window.
380
+ // (The snap itself is filmMix's spanStanzaFrames — the ONE
381
+ // law the render loop and the film manifest share; the old
382
+ // inline 22+17k twin died here.)
383
+ if (knobs.fps_seconds === undefined) {
384
+ stanza.fps_seconds = Math.round((stanza.length / 24) * 1000) / 1000;
385
+ }
386
+ }
387
+ // THE GRID GATE (§26): a knob-pinned length bypassed the snap
388
+ // above — validate, never trust. Refuses at compose (zero GPU)
389
+ // with the span, the nearest legal length, and the proven
390
+ // geometry in the message.
391
+ assertGridLength(stanza.length, `h3-timeline window ${k} (span ${sf}→${ef})`);
392
+ if (i > 0) {
393
+ stanza.__iteration = k - 1;
394
+ stanza.__overlap = overlap;
395
+ }
396
+ if (prev !== undefined)
397
+ stanza.__prev = prev;
398
+
399
+ // bed arm retired with the bed the same day): a pinned window
400
+ // owns its audio conditioning — the normal inputs stand down for
401
+ // THAT window so nothing double-feeds the same generation. The
402
+ // dialogue/sfx arm strips the user's ref_audios on stamped
403
+ // windows (the pins own those lanes); the music arm has nothing
404
+ // left to guard since the bed left. Per-window, never film-wide.
405
+ assertOverlayGated(stanza, `h3-timeline window ${k} knobs`);
406
+
407
+ // nodes, nothing holds a prior window's tensors — each window
408
+ // frees after its own SaveVideo. The film tail below assembles
409
+ // from the SAVED FILES (decode after every save), never from
410
+ // window tensors.
411
+ // the conditioning stamps ride the stanza (what THIS window
412
+ // hears at generation — the Slice → pin chain reads them).
413
+ if (stamps.dialogue !== undefined)
414
+ stanza.dialogue_slice = stamps.dialogue;
415
+ if (stamps.sfx !== undefined)
416
+ stanza.sfx_slice = stamps.sfx;
417
+ if (stamps.music !== undefined)
418
+ stanza.music_slice = stamps.music;
419
+ const h = g.scoped(`window${k}_`, (w) => renderH3Window(stanza, w, facts, model));
420
+ prev = h;
421
+ /* v8 ignore next 1 -- both family arms assign the passthrough (every path saves); a future arm that forgets is refused loud at the film tail */
422
+ if (h.savePassthrough !== undefined)
423
+ windowSaves.push(h.savePassthrough);
424
+ });
425
+
426
+ // operator's provenance law: every artifact traces to a
427
+ // composition of cards, never a harness side-effect) ──────────────
428
+ //
429
+ // The ORIGINAL tail consumed every window's tensors as graph data
430
+ // (the scheduler kept the whole film's backlog alive while later
431
+ // windows sampled — the 43h-OOM signature). The disk-side valve
432
+ // that replaced it died the same day (out-of-band ffmpeg). THIS
433
+ // tail inverts the memory law while staying in-graph, in TWO arms:
434
+ //
435
+ // CLIPS-FREE films (the 27-film precedent — never OOM'd):
436
+ // 1. every window SAVES its own clip (h3_t4_w<k>) — its tensors
437
+ // die at that SaveVideo (nothing downstream consumes them);
438
+ // 2. ONE MeliteUnload boundary PER window save, token-chained
439
+
440
+ // single boundary on the last save assumed "windows chain, so
441
+ // the last save is downstream of them all" — FALSE for cut
442
+ // films, which chain nothing; window 2's save was an unordered
443
+ // island and the loader could beat it) — every boundary flushes
444
+ // the allocator WITHOUT dropping model weights (the next run
445
+ // pays no reload), and the chain's final token provably waits
446
+ // for EVERY save;
447
+ // 3. MeliteConcatVideos decodes the saved FILES back in
448
+ // (IMAGE+AUDIO+fps) — CPU-side, strictly after every save;
449
+ // 4. CreateVideo → SaveVideo h3_t4_film. The film is a graph
450
+ // output; the estate's engineFilmName presents it first.
451
+ //
452
+
453
+ // VRAM-leak fix, operator law: WE USE COMFYUI, NEVER FFMPEG for
454
+ // the mix; GAP 1 CLOSED same night — the arm delivers the film
455
+ // mp4): the retired in-graph film stitch (film-time Delay/Mix/
456
+ // Duck over live window tensors) held every window resident
457
+ // until the final save — the accumulation that OOM'd a
458
+ // two-window BRIEF9 film at 20.57 GiB. These films take the valve
459
+ // path (windows save per-window and free behind the same chained
460
+ // boundaries — steps 1–2 above) PLUS one post-generation
461
+ // MeliteFilmAudioMix (Layer C, torch, the estate's own node):
462
+ // window audio files + the manifest's clips/duck law in,
463
+ // SaveAudio h3_t4_film_audio stem out — AND the same file-tail
464
+ // video join (MeliteConcatVideos → CreateVideo → SaveVideo
465
+ // h3_t4_film) with the MIXED audio wired in. No film-time
466
+ // Delay/Mix/Duck/LoadAudio — the graph holds windows only
467
+ // during generation.
468
+ //
469
+ // (Single-window docs never reach this tail — the compose
470
+ // dispatch keeps the frozen single-window shape byte-identical;
471
+ // the film is a MULTI-call property, and the single-call mapping
472
+ // refuses clips loudly downstream of the dispatch.)
473
+ /* v8 ignore next 1 -- both family arms assign the passthrough (every path saves); a future arm that forgets refuses here, loudly */
474
+ if (windowSaves.length === 0) {
475
+ throw new Error('[h3-timeline] a family arm saved no clip to pass the film boundary — the film tail cannot order its loads');
476
+ }
477
+ const manifest = computeFilmMix({
478
+ spans,
479
+ clips,
480
+ windowSecs: stanzaSecs(spans),
481
+ // the knob's declared default (−14) walks through the schema
482
+ // door; computeFilmMix owns the fallback for the absent key
483
+ duckDb: p.duck_depth_db,
484
+ });
485
+
486
+ // cut-film ordering fix — receipts run-1057a53c4252 (stale-file
487
+ // stitch: 960×576 leftovers globbed as windows) and
488
+ // run-18ea8c810104 (loud no-match refusal on h3_t4_w2): cut
489
+ // windows chain NOTHING and even chained windows' SAVE nodes are
490
+ // not downstream of one another, so the old single boundary on
491
+ // the LAST save rode a scheduler tie-break — window 2's save was
492
+ // an unordered island the loader could beat). Every window's
493
+ // SaveVideo passthrough feeds its OWN boundary; each boundary's
494
+ // optional 'after' wires the prior boundary's token, so the final
495
+ // token (the concat's 'after') transitively depends on EVERY
496
+ // save — and each window's passthrough tensor still dies at its
497
+ // own boundary (the §20 law; the flush is idempotent, weights
498
+ // stay resident).
499
+ let boundaryAfter;
500
+ for (const save of windowSaves) {
501
+ boundaryAfter = g.node('MeliteUnload', {
502
+ video: save, unload_models: false,
503
+ ...(boundaryAfter !== undefined ? { after: boundaryAfter } : {}),
504
+ }).out(0);
505
+ }
506
+ const after = boundaryAfter;
507
+ if (clips.length > 0) {
508
+
509
+
510
+ // delivers the film mp4 too): ONE MeliteFilmAudioMix composes
511
+ // the film's audio post-generation from the saved window files
512
+ // + the manifest's clips/duck law (the SAME Delay/Mix/Duck
513
+ // methods the retired tail called, in the SAME order — now
514
+ // torch-side inside the estate's own node, never ffmpeg).
515
+ // SaveAudio emits the stem; the VIDEO join is the clips-free
516
+ // arm's own machinery (MeliteConcatVideos decodes the saved
517
+ // files CPU-side strictly after every save — windows' tensors
518
+ // died at their SaveVideos, so no accumulation returns) with
519
+ // the MIXED audio wired into CreateVideo — the film mp4 carries
520
+ // the mix, not the raw concat audio. Early return: the
521
+ // clips-free arm below stays byte-frozen.
522
+ const mix = g.node('MeliteFilmAudioMix', {
523
+ videos: calls.map((_c, i) => `h3_t4_w${i + 1}`).join(','),
524
+ after,
525
+ // the manifest rendered verbatim: every placement's source,
526
+ // film seat, duration, and class — doc order kept (the node's
527
+ // two loops read the same order the retired tail did)
528
+ clips_json: JSON.stringify(manifest.placements.map((pl) => {
529
+ const clip = clips[pl.clip];
530
+ return { src: clip.src, start_sec: pl.filmSec, dur_sec: pl.durSec, class: pl.cls };
531
+ })),
532
+ duck_spans: manifest.duckSpanString,
533
+ music_duck_spans: manifest.musicDuckSpanString,
534
+ duck_db: manifest.duckDb,
535
+ film_seconds: manifest.filmSec,
536
+ });
537
+
538
+ // passthrough tap between the mix and its consumers — the film's
539
+ // integrated loudness (BS.1770-4, K-weighted + gated) rides the
540
+ // history UI dict as loudness_lufs, so every surface REPORTS the
541
+ // number instead of re-deriving it from the encoded file. The
542
+ // AUDIO dict rides out unchanged (meter taps, never transforms);
543
+ // calibrated against ffmpeg's ebur128 to within 0.1 LU on tones,
544
+ // noise, gating, and mono.
545
+ const meter = g.node('MeliteLoudness', { audio: mix.out(0) });
546
+ saveAudio(g, meter.out(0), 'h3_t4_film_audio');
547
+ // THE FILM MP4 (GAP 1): the same file-tail video join the
548
+ // clips-free arm rides — container mux only (CreateVideo +
549
+ // SaveVideo h264/mp4 on the decoded window files), never the
550
+ // mix. The mix rides it: audio carries the node's output.
551
+ const join = g.node('MeliteConcatVideos', {
552
+ videos: calls.map((_c, i) => `h3_t4_w${i + 1}`).join(','),
553
+ after,
554
+ });
555
+ const filmCreated = g.node('CreateVideo', {
556
+ images: join.out(0), audio: meter.out(0), fps: join.out(2), bit_depth: FILM_BIT_DEPTH,
557
+ });
558
+ return g.node('SaveVideo', {
559
+ video: filmCreated.out(), filename_prefix: 'h3_t4_film',
560
+ format: 'mp4', codec: 'h264',
561
+ }).out();
562
+ }
563
+ const concat = g.node('MeliteConcatVideos', {
564
+ videos: calls.map((_c, i) => `h3_t4_w${i + 1}`).join(','),
565
+ after,
566
+ });
567
+ const filmCreated = g.node('CreateVideo', {
568
+ images: concat.out(0), audio: concat.out(1), fps: concat.out(2), bit_depth: FILM_BIT_DEPTH,
569
+ });
570
+ return g.node('SaveVideo', {
571
+ video: filmCreated.out(), filename_prefix: 'h3_t4_film',
572
+ format: 'mp4', codec: 'h264',
573
+ }).out();
574
+ }
575
+ /** THE FUN-CONTROLNET CHAIN (002 H2/H4 + 007 L7): family-owned,
576
+ * the LTX_lora_loader precedent — the node pair is the family's
577
+ * own (ModelPatchLoader + MiniMaxH3FunControlNetApply, the
578
+ * engine's model-patch spelling), spelled HERE, never swapped
579
+ * into the kit's still-image stackControlNets (whose node pair
580
+ * stays z-image's). One link per fired pick, array order = apply
581
+ * order, empty picks → the bare model (byte-stable). The control
582
+ * source rides the pick's clip channel (a staged video artifact —
583
+ * LoadVideo → GetVideoComponents' image stream) or its still
584
+ * image; the mask channel rides LoadImageMask (alpha; the node
585
+ * reads it with source_video unset — no presumption about the
586
+ * video behind the mask). The schedule window stamps verbatim:
587
+ * the row declares 'ranged' and the node carries the dials (the
588
+ * kit's schedule law already refused what the row forbids). */
589
+ function applyH3FunControlNets(g, model, vae, picks) {
590
+ let cur = model;
591
+ for (const pick of picks) {
592
+ const hasClip = pick.clip !== undefined && pick.clip !== '';
593
+ const control = hasClip
594
+ ? g.node('GetVideoComponents', { video: g.node('LoadVideo', { file: pick.clip }).out() }).out(0)
595
+ : pick.image !== ''
596
+ ? g.node('LoadImage', { image: pick.image, upload: 'image' }).out(0)
597
+ : undefined;
598
+ const hasMask = pick.mask !== undefined && pick.mask !== '';
599
+ const patch = g.node('ModelPatchLoader', { name: pick.model }).out();
600
+ cur = g.node('MiniMaxH3FunControlNetApply', {
601
+ model: cur, model_patch: patch, vae,
602
+ strength: pick.strength,
603
+ start_percent: pick.start_percent ?? 0,
604
+ end_percent: pick.end_percent ?? 1,
605
+ ...(control === undefined ? {} : { control_video: control }),
606
+ ...(hasMask ? { mask: g.node('LoadImageMask', { image: pick.mask, channel: 'alpha' }).out(0) } : {}),
607
+ }).out();
608
+ }
609
+ return cur;
610
+ }
611
+ function renderH3Window(p, g, facts, model) {
612
+ // REFS IMPLY THE R2V LANE (the bundle IS the r2v input): a
613
+ // refs-carrying window is t4r even without a guide still — the
614
+ // same law the film renderer applies per call. The DECLARED input
615
+ // surface (ref_images/ref_videos/ref_audios — the typed fields)
616
+ // implies t4r by the same law.
617
+ const rb0 = (p.refs ?? {});
618
+ const declaredCount = wireList(p.ref_images).length + wireList(p.ref_videos).length + wireList(p.ref_audios).length;
619
+ const hasRefs = declaredCount + wireList(rb0.images).length + wireList(rb0.videos).length + wireList(rb0.audios).length > 0;
620
+
621
+ // variant:'timeline' break): the window family is DERIVED from
622
+ // the window's own seats — a guide still or a reference bus makes
623
+ // the reference lane; everything else is text. SEATS BEAT STATED:
624
+ // refs coerce the lane even over a stated lawful family (the old
625
+ // refs-imply-r2v coercion — a refs-carrying window is t4r even
626
+ // without a guide still). A stated LAWFUL family rides only when
627
+ // the seats are silent (the film loop derives per stanza before
628
+ // calling here; the schema walk derives from the same seats); an
629
+ // axis-seeded string ('timeline' — the model axis the add door
630
+ // stamps onto every fresh stage) is not a family and never was:
631
+ // the seats own the lane, model metadata never picks one.
632
+ const statedFamily = typeof p.variant === 'string' && FAMILIES.includes(p.variant)
633
+ ? p.variant : undefined;
634
+ const guide0 = [p.image, p.image_name, p.ref_image].some((v) => typeof v === 'string' && v.trim() !== '');
635
+ const family = (hasRefs || guide0) ? 't4r' : (statedFamily ?? 't4_open');
636
+ const k = (p.k ?? 1);
637
+ // THE GRID GATE (§26, defense in depth): no window renders
638
+ // off-grid — the film loop's pin check voices the call span, this
639
+ // one catches the single-call path and any direct caller.
640
+ assertGridLength(p.length, `h3-timeline window ${k}`);
641
+ const isT4r = family === 't4r';
642
+ const isChain = family === 't4_chain';
643
+
644
+ // is the fresh-card admission, not a fallback crime. The window
645
+ // shape's text face is p.prompt (declared required=True, "optional
646
+
647
+ // card.spec.ts "a fresh press composes") admits an absent/blank
648
+ // prompt as empty conditioning — the fresh-card one-shot document
649
+ // renders. The film path refuses textless calls instead (the
650
+ // no-fallbacks law at the calls walk); the single-call LIFT may
651
+ // lawfully write p.prompt from call text because in the one-window
652
+ // shape p.prompt IS the text owner — never a substitute.)
653
+ const prompt = (p.prompt ?? '');
654
+ // card knob first (image), renderer alias second.
655
+ const guideImage = (p.image ?? p.image_name ?? '');
656
+ // ── the model chain (family-conditional defaults;
657
+ // absent = absent on wire) ──
658
+ const stabilize = p.sla_stabilize_motion ?? (isT4r ? false : true);
659
+ const unet = g.node('UNETLoader', { unet_name: facts.unet, weight_dtype: 'default' }).out();
660
+ const sla = g.node('H3SLAAttention', {
661
+ model: unet,
662
+ sparsity_ratio: p.sla_sparsity,
663
+ block_size: p.sla_block_size,
664
+ min_seq_len: p.sla_min_seq_len,
665
+ dense_last_steps: p.sla_dense_last_steps,
666
+ protect_audio: p.sla_protect_audio,
667
+ enabled: true,
668
+ dense_steps: p.sla_dense_steps,
669
+ dense_backend: p.sla_dense_backend,
670
+ disable_fp16_accum: p.sla_disable_fp16_accum,
671
+ stabilize_motion: stabilize,
672
+ reference_protection: p.sla_reference_protection,
673
+ }).out();
674
+ const chunked = g.node('MiniMaxChunkFeedForward', {
675
+ model: g.node('MiniMaxLowVRAMAttention', { model: sla, head_chunks: 4 }).out(),
676
+ chunks: 2, seq_threshold: 4096,
677
+ }).out();
678
+
679
+
680
+ // `lora_stack` string field is DEAD): the studio/agent surface
681
+ // writes the mod bag `loras` — [{id, strength}] rows the service
682
+ // resolves to {name, strength} filenames against the family's
683
+ // flavor catalog. Those rows build the upstream stack verbatim
684
+ // ({on, lora, str, v:1, a:1, t:1}); an empty bag rides the
685
+ // family catalog's turbo row (the mod plane's own default, built
686
+ // from the catalog so the value has one owner). ONE surface, one
687
+ // owner.
688
+ const loraStack = Array.isArray(p.loras) && p.loras.length > 0
689
+ ? JSON.stringify(p.loras.map((r) => ({
690
+ // the service resolves every row against the family catalog
691
+ // (unknown ids refuse LOUD upstream) — {name, strength} is
692
+ // the guaranteed wire shape, read directly
693
+ on: true,
694
+ lora: r.name,
695
+ str: r.strength,
696
+ v: 1, a: 1, t: 1,
697
+ })))
698
+ : loraStackDefault();
699
+ // t4r templates carry shift_video 8.0; the t4 family carries the INT
700
+ // NO SILENT RESOLUTION LAW: the walked shift_video IS the value
701
+ // (declared default 8; the family literals retired with the
702
+ // nulling that fed them — 8.0 and 8 serialize identically anyway)
703
+ const shiftVideo = p.shift_video;
704
+ const clip = g.node('CLIPLoader', {
705
+ clip_name: facts.clip, type: 'minimax',
706
+ ...(isT4r ? { device: 'default' } : {}), // t4 templates OMIT it
707
+ }).out();
708
+ const vaeVideo = g.node('VAELoader', { vae_name: facts.vae_video }).out();
709
+ const vaeAudio = g.node('VAELoader', { vae_name: facts.vae_audio }).out();
710
+ let cond;
711
+ let latent;
712
+ let sigmaModel;
713
+ let fpsInput;
714
+ if (isT4r) {
715
+ // opener: switch(SLABool) picks SLA-direct vs chunked; lora rides
716
+ // the switch; preview override wired to the in-graph step count.
717
+ // Inject semantics: an injected SCALAR replaces the bool NODE
718
+ // (template link severed, node orphaned) — mirrored by passing the
719
+ // scalar straight when sla_switch is set. sla_enabled=false
720
+ // forces the chunked (SLA-off) path; otherwise the legacy
721
+ // sla_switch spelling rides untouched.
722
+ const fpsNode = g.node('PrimitiveFloat', { value: 24.0 }).out(); // id .0 — CreateVideo.fps walks first
723
+ let slaSel = p.sla_enabled === false
724
+ ? true
725
+ : (p.sla_switch ?? null);
726
+ if (slaSel === null)
727
+ slaSel = g.node('PrimitiveBoolean', { value: false }).out();
728
+ const picked = g.node('ComfySwitchNode', { switch: slaSel, on_true: chunked, on_false: sla }).out();
729
+ const loraModel = g.node('LTX_lora_loader', {
730
+ model: picked, mode: 'minimax', stack_data: loraStack, lora_ui: '',
731
+ }).out();
732
+ const seconds = g.node('PrimitiveFloat', { value: p.fps_seconds }).out(); // id .1
733
+ const lengthNode = g.node('ComfyMathExpression', {
734
+ expression: MATH_STEPS_GOLD, 'values.a': seconds,
735
+ }).out(1);
736
+ const previewed = g.node('ModelPreviewOverrideKJ', {
737
+ max_resolution: 512, jpeg_quality: 80,
738
+ suppress_default_preview: true, preview_frames: lengthNode,
739
+ preview_fps: 8, tiny_vae: 'none', model: loraModel,
740
+ }).out();
741
+ const adaln = g.node('H3AdaLNLoRAFix', { model: previewed, mode: 'port' }).out();
742
+ sigmaModel = g.node('MiniMaxH3SigmaShift', {
743
+ model: adaln, shift_video: shiftVideo, shift_audio: p.shift_audio,
744
+ }).out();
745
+ // THE ANCHOR + THE REFERENCE BUNDLE (the operator's distinction,
746
+
747
+ // the frozen served shape — ref_image_0 on the r2v node, the
748
+ // strongest identity pull; the window's literal first frame
749
+ // GENERATES under its guidance, it is never pinned — the i2v
750
+ // first-frame input is the orphaned marker below); `refs` is the
751
+ // call's REFERENCE bundle
752
+ // — the upstream "Extra References" subgraph's own vocabulary
753
+ // (LoadImage → the ref resizer; LoadVideo → GetVideoComponents →
754
+ // the image+audio component pair; LoadAudio). Bundle layout (the
755
+ // slot map): inputs 1-9 images (anchor first), 10/12/14
756
+ // video image streams, 11/13/15 video audio streams, 16-18
757
+ // audios. RESIZER ORDER IS PINNED: the serialized walk reaches
758
+ // the reference resizer (bundle → r2v refs) before the geometry
759
+ // resizer (i2v) — creation mirrors the walk.
760
+ const refBag = (p.refs ?? {});
761
+
762
+ // is the card's DEFAULTS; a call (Layer B) REPLACES a refs lane
763
+ // it states — per lane, never per bag — and inherits the
764
+ // declared lane when it states none. The pre-canon merge
765
+ // (declared PRIMARY + bag appended, deduped) made a call unable
766
+ // to override the run's references: the exact harm the operator
767
+ // named. LoRAs own the opposite pole — CALL_KEYS admits no
768
+ // loras key, so a call cannot even state one (film-level model
769
+ // configuration is Layer A's alone). One canon, per seat:
770
+ // replace (refs lanes), per-key replace (CALL_KNOB_KEYS), or
771
+ // none (loras, geometry, the bed).
772
+ const declaredImages = wireList(p.ref_images);
773
+ const declaredVideos = wireList(p.ref_videos);
774
+ const declaredAudios = wireList(p.ref_audios);
775
+ // THE 9-SLOT IMAGE BUS (the bundle's own topology — the compose
776
+ // and the UI agree or they lie): inputs 1-9 are IMAGE slots —
777
+ // the anchor at 1, the FL2VA pair's END anchor at 2 when
778
+ // last_frame is set, references at 3..9 (7 with an end anchor,
779
+ // 8 riding input_2..9 without one); input_10 begins the video
780
+ // lanes. A 9th ref would land ON input_10 — the first video's
781
+ // image stream — and be silently clobbered; the law refuses
782
+ // LOUD instead.
783
+ const lastFrame = (p.last_frame ?? '');
784
+ // THE CANON'S REPLACE ARM (per lane): a stated call lane rides
785
+ // INSTEAD of the declared lane; an absent call lane inherits it.
786
+ const bagImages = wireList(refBag.images);
787
+ const refImagesAll = bagImages.length > 0 ? bagImages : declaredImages;
788
+ const imageCap = imageReferenceCap(lastFrame !== '');
789
+ if (lastFrame !== '' && refImagesAll.length > imageCap) {
790
+ throw new Error(`[h3-timeline] the image bus is full: a last frame (input 2) + ${String(refImagesAll.length)} references exceeds the ${IMAGE_BUS_SLOTS}-slot bus — keep references ≤ ${imageCap} with an end anchor (≤ ${REF_CAPS.images} without)`);
791
+ }
792
+ const refImages = refImagesAll.slice(0, imageCap);
793
+ const bagVideos = wireList(refBag.videos);
794
+ const refVideos = (bagVideos.length > 0 ? bagVideos : declaredVideos).slice(0, REF_CAPS.videos);
795
+ // THE TRIM SEAT'S READER (audit 003/V4): index-paired with
796
+ // ref_videos — schema resolve fills each entry's start_time/
797
+ // duration defaults, so a wire `{item:…}` or partial entry
798
+ // normalizes before it reaches the slice. A non-object entry
799
+ // refuses LOUD (the probe-proven law), never rides silent.
800
+ const rawTrims = Array.isArray(p.ref_video_trims) ? p.ref_video_trims : [];
801
+ if (rawTrims.length > REF_CAPS.videos) {
802
+ throw new Error(`ref_video_trims: expected at most ${REF_CAPS.videos} entries (the video lane's cap) — got ${rawTrims.length}`);
803
+ }
804
+ const videoTrims = rawTrims.map((e, i) => {
805
+ if (typeof e !== 'object' || e === null || Array.isArray(e)) {
806
+ throw new Error(`ref_video_trims: entry ${i} must be an object { start_time, duration } — got ${JSON.stringify(e).slice(0, 40)}`);
807
+ }
808
+ const row = e;
809
+ const start = row.start_time;
810
+ const dur = row.duration;
811
+ if (start !== undefined && typeof start !== 'number')
812
+ throw new Error(`ref_video_trims: entry ${i} start_time must be a number — got ${JSON.stringify(start).slice(0, 40)}`);
813
+ if (dur !== undefined && typeof dur !== 'number')
814
+ throw new Error(`ref_video_trims: entry ${i} duration must be a number — got ${JSON.stringify(dur).slice(0, 40)}`);
815
+ return { start_time: start ?? 0, duration: dur ?? 0 };
816
+ });
817
+ const bagAudios = wireList(refBag.audios);
818
+ const refAudios = (bagAudios.length > 0 ? bagAudios : declaredAudios).slice(0, REF_CAPS.audios);
819
+ const bundleInputs = {};
820
+
821
+ // it all"): a '$name' value names a WIRED STAGE INPUT, never a
822
+ // file on disk — the merge (rewriteSpells) lands the upstream
823
+ // producer's tensor link wherever the spell rides, and ROW-4
824
+ // refuses producer links in Load* file slots. So a spelled
825
+ // anchor/last-frame/reference rides its TENSOR slot verbatim
826
+ // and NEVER builds a loader; files/URLs/estate paths keep the
827
+ // Load* disk handoff (the per-stage path owns those). Before
828
+ // this arm the ports validated green at the lattice and died
829
+ // at the merge — the validate-said-nothing disease.
830
+ const isSpell = (s) => s.startsWith('$');
831
+ const imageRef = (src) => isSpell(src) ? src : g.node('LoadImage', { image: src }).out();
832
+ let anchorRaw;
833
+ if (guideImage !== '') {
834
+ anchorRaw = imageRef(guideImage);
835
+ bundleInputs.input_1 = g.node('UnifiedResizeImageMask', {
836
+ image: anchorRaw, scale_mode: 'Shorter Side',
837
+ aspect_ratio: 'Auto (Input Image)', long_side_target: 1024.0,
838
+ short_side_target: 2048.0, width: 1024.0, height: 1024.0,
839
+ multiplier: 1.0, megapixels: 1.0, upscale_method: 'lanczos',
840
+ crop: 'center', divisible_by: 32.0, maintain_aspect: false,
841
+ }).out();
842
+ }
843
+ // THE FL2VA END ANCHOR: input_2 is the pair's second seat — the
844
+ // i2v branch reads out(0)/out(1) as first/last frame verbatim.
845
+ // Without an end anchor, refs ride from input_2 (legacy shelf).
846
+ const resizeRef = (src) => g.node('UnifiedResizeImageMask', {
847
+ image: imageRef(src), scale_mode: 'Shorter Side',
848
+ aspect_ratio: 'Auto (Input Image)', long_side_target: 1024.0,
849
+ short_side_target: 2048.0, width: 1024.0, height: 1024.0,
850
+ multiplier: 1.0, megapixels: 1.0, upscale_method: 'lanczos',
851
+ crop: 'center', divisible_by: 32.0, maintain_aspect: false,
852
+ }).out();
853
+ if (lastFrame !== '')
854
+ bundleInputs.input_2 = resizeRef(lastFrame);
855
+ const firstFreeSlot = lastFrame !== '' ? 3 : 2;
856
+ refImages.forEach((src, i) => {
857
+ const img = imageRef(src);
858
+ if (anchorRaw === undefined && i === 0)
859
+ anchorRaw = img;
860
+ bundleInputs[`input_${firstFreeSlot + i}`] = g.node('UnifiedResizeImageMask', {
861
+ image: img, scale_mode: 'Shorter Side',
862
+ aspect_ratio: 'Auto (Input Image)', long_side_target: 1024.0,
863
+ short_side_target: 2048.0, width: 1024.0, height: 1024.0,
864
+ multiplier: 1.0, megapixels: 1.0, upscale_method: 'lanczos',
865
+ crop: 'center', divisible_by: 32.0, maintain_aspect: false,
866
+ }).out();
867
+ });
868
+ refVideos.forEach((src, i) => {
869
+ // the spelled motion guide rides GetVideoComponents' tensor
870
+ // input directly (the producer's pre-save video tensor); a
871
+ // path keeps the LoadVideo disk handoff.
872
+ let vid = isSpell(src) ? src : g.node('LoadVideo', { file: src }).out();
873
+ // THE TRIM THREAD (audit 003/V4): entry i slices guide i
874
+ // through the engine's own Video Slice BEFORE conditioning —
875
+ // both arms (spelled tensor and disk path) trim the same,
876
+ // because the slice rides the VIDEO tensor either way. A
877
+ // zero/zero or absent entry builds no node: the whole clip
878
+ // stays the guide, byte-stable with the pre-trim graph.
879
+ const trim = videoTrims[i];
880
+ if (trim !== undefined && (trim.start_time > 0 || trim.duration > 0)) {
881
+ vid = g.node('Video Slice', {
882
+ video: vid, start_time: trim.start_time,
883
+ duration: trim.duration, strict_duration: false,
884
+ }).out();
885
+ }
886
+ const comp = g.node('GetVideoComponents', { video: vid });
887
+ bundleInputs[`input_${10 + 2 * i}`] = comp.out(0);
888
+ bundleInputs[`input_${11 + 2 * i}`] = comp.out(1);
889
+ });
890
+ refAudios.forEach((src, i) => {
891
+ // the spelled sound reference rides the bundle's audio seat
892
+ // directly (the producer's audio tensor); a path keeps
893
+ // LoadAudio.
894
+ bundleInputs[`input_${16 + i}`] = isSpell(src)
895
+ ? src
896
+ : g.node('LoadAudio', { audio: src }).out();
897
+ });
898
+ // the geometry resizer (i2v's dead branch): fed by the anchor, or
899
+ // the first ref image, or — anchorless and imageless — pinned to
900
+ // the literals the geo node's own defaults produce (the branch is
901
+ // never selected; r2vBool pins true below).
902
+ const geoSrc = anchorRaw ?? bundleInputs.input_2;
903
+ let geoW = 768.0;
904
+ let geoH = 1344.0;
905
+ if (geoSrc !== undefined) {
906
+ const geo = g.node('UnifiedResizeImageMask', {
907
+ image: geoSrc, scale_mode: 'Total Pixels (MP)',
908
+ aspect_ratio: '3:4 (Portrait Standard)', long_side_target: 1280.0,
909
+ short_side_target: 768.0, width: 768.0, height: 1344.0,
910
+ multiplier: 1.0, megapixels: 0.98, upscale_method: 'lanczos',
911
+ crop: 'center', divisible_by: 32.0, maintain_aspect: false,
912
+ });
913
+ geoW = geo.out(2);
914
+ geoH = geo.out(3);
915
+ }
916
+ const bundle = g.node('PlagueKindBundleIn', bundleInputs).out();
917
+ const bout = g.node('PlagueKindBundleOut', { bundle });
918
+ // declared knobs hoisted: the compose walk fills their defaults
919
+
920
+ const refSize = p.ref_image_size;
921
+ const r2vInputs = {
922
+ prompt, width: p.width, height: p.height,
923
+ length: lengthNode, ref_image_size: refSize,
924
+ clip, vae: vaeVideo, audio_vae: vaeAudio,
925
+ };
926
+ for (let i = 0; i <= 8; i++)
927
+ r2vInputs[`ref_images.ref_image_${i}`] = bout.out(i);
928
+ for (let i = 0; i < 3; i++) {
929
+ r2vInputs[`ref_videos.ref_video_${i}`] = bout.out(9 + 2 * i);
930
+ r2vInputs[`ref_video_audios.ref_video_audio_${i}`] = bout.out(10 + 2 * i);
931
+ r2vInputs[`ref_audios.ref_audio_${i}`] = bout.out(15 + i);
932
+ }
933
+
934
+ // their natural lanes above — no slice, no shift, no fourth
935
+ // anything.)
936
+ let dialogueAudio;
937
+ let dialogueFrameIdx = 0;
938
+ let sfxAudio;
939
+ let sfxFrameIdx = 0;
940
+ let musicAudio;
941
+ let musicFrameIdx = 0;
942
+
943
+ // film loop stamped on THIS window conditions it — the model
944
+ // HEARS the dialogue (the lip-sync mechanism; the generated
945
+ // voice tracks it, the overlay stays the audible authority and
946
+ // the mix DUCKS the generated voice under the real clip at film
947
+ // time). THE BUS LAW, TOLD LOUD: 3 audio lanes total. Bed +
948
+
949
+ // operator caught the dead lane): the bare ref_audios lane is a
950
+ // soft prior this checkpoint ignores — measured zero correlation
951
+ // on two rendered films. The PINNING lane is MiniMaxH3AddGuide
952
+ // with an audio-only keyframe: the clip's true source segment is
953
+ // anchored INTO the model's own timeline at its generation-frame
954
+ // index (the audio latent rides pinned rows; the video around it
955
+ // generates to match — the inpainting-grade prior). Dialogue no
956
+ // longer consumes a ref lane: bed + user audios keep the full
957
+ // 3-lane budget, and the guide is the dialogue's one owner.
958
+ {
959
+ const read = (key) => (p[key] ?? null);
960
+ const stamp = read('dialogue_slice');
961
+ if (stamp !== null) {
962
+ dialogueAudio = g.node('MeliteAudioSlice', {
963
+ audio: stamp.src,
964
+ start_seconds: stamp.slice_start_seconds,
965
+ duration_seconds: stamp.slice_duration_seconds,
966
+ }).out(0);
967
+ dialogueFrameIdx = Math.round(stamp.delay_seconds * 24);
968
+ }
969
+ const sfxStamp = read('sfx_slice');
970
+ if (sfxStamp !== null) {
971
+ sfxAudio = g.node('MeliteAudioSlice', {
972
+ audio: sfxStamp.src,
973
+ start_seconds: sfxStamp.slice_start_seconds,
974
+ duration_seconds: sfxStamp.slice_duration_seconds,
975
+ }).out(0);
976
+ sfxFrameIdx = Math.round(sfxStamp.delay_seconds * 24);
977
+ }
978
+ const musicStamp = read('music_slice');
979
+ if (musicStamp !== null) {
980
+ musicAudio = g.node('MeliteAudioSlice', {
981
+ audio: musicStamp.src,
982
+ start_seconds: musicStamp.slice_start_seconds,
983
+ duration_seconds: musicStamp.slice_duration_seconds,
984
+ }).out(0);
985
+ musicFrameIdx = Math.round(musicStamp.delay_seconds * 24);
986
+ }
987
+ }
988
+ const r2v = g.node('MiniMaxH3ReferenceToVideo', r2vInputs);
989
+
990
+ // serialized graph carries the t4r family key (finalizeH3's
991
+ // marker), wired to the geometry/anchor slots it always read —
992
+ // but consumed by NOTHING. The old shape routed r2v through a
993
+ // hardcoded-true ComfySwitchNode whose on_false arm was this
994
+ // node: never selected, yet a flipped switch would have run the
995
+ // gold prompt. Direct wiring + an orphan = one lane, one truth.
996
+ g.node('MiniMaxH3ImageToVideo', {
997
+
998
+ // node declares clip/first_frame/height/last_frame/length/
999
+ // prompt/vae/width — context_steps and audio_context_steps
1000
+ // are gone from the declaration, and the input wall walks
1001
+ // orphans too, so wiring them refused the whole graph
1002
+ // (BRIEF15: card_compose unknown-input on this node).
1003
+ prompt: I2V_MARKER_PROMPT, width: geoW, height: geoH,
1004
+ length: lengthNode,
1005
+ clip, vae: vaeVideo, first_frame: bout.out(0), last_frame: bout.out(1),
1006
+ });
1007
+ cond = r2v.out(0);
1008
+ latent = r2v.out(1);
1009
+ fpsInput = fpsNode;
1010
+
1011
+ // its slice into the window's own AV latent at its generation-
1012
+ // frame index — the model generates the video (and its own
1013
+ // sound) around the pinned audio instead of merely glancing at
1014
+ // a soft reference. Guides CHAIN (positive flows through): the
1015
+ // dialogue pin lands first (the measured law), then sfx (the
1016
+ // model times the blast to the heard transient), then music.
1017
+ if (dialogueAudio !== undefined) {
1018
+ cond = g.node('MiniMaxH3AddGuide', {
1019
+ positive: cond, latent,
1020
+ frame_idx: dialogueFrameIdx,
1021
+ audio_vae: vaeAudio, audio: dialogueAudio,
1022
+ }).out(0);
1023
+ }
1024
+ if (sfxAudio !== undefined) {
1025
+ cond = g.node('MiniMaxH3AddGuide', {
1026
+ positive: cond, latent,
1027
+ frame_idx: sfxFrameIdx,
1028
+ audio_vae: vaeAudio, audio: sfxAudio,
1029
+ }).out(0);
1030
+ }
1031
+ if (musicAudio !== undefined) {
1032
+ cond = g.node('MiniMaxH3AddGuide', {
1033
+ positive: cond, latent,
1034
+ frame_idx: musicFrameIdx,
1035
+ audio_vae: vaeAudio, audio: musicAudio,
1036
+ }).out(0);
1037
+ }
1038
+ }
1039
+ else {
1040
+ // t4 families: the SLA/attention switch rides ABOVE the LoRA
1041
+ // loader (the t4r mirror — L1: the old order stacked the loader
1042
+ // under the chunked branch only, so sla_enabled=true (the
1043
+ // default) picked the bare SLA model and every bagged LoRA
1044
+ // silently did nothing while the steps marriage still fired).
1045
+ // The switch picks the attention strategy — SLA-direct vs the
1046
+ // backend-pinned chunked chain — and ONE loader applies the bag
1047
+ // over the pick; the fix-up + shift ride the loaded model on
1048
+ // both arms, so no arm bypasses the loader. The backend node
1049
+ // stays on the dense branch (pre-switch): it configures that
1050
+ // branch's attention implementation, and routing the
1051
+ // SLA-patched model through it would risk clobbering the sparse
1052
+ // kernels — the switch selects the strategy, the loader samples
1053
+ // whichever won. The pin autofills the builder adds (lora_ui,
1054
+ // the SeedVR2 tile/offload inputs) are stripped by the finalize
1055
+ // pass — the python's _T4_AUTOFILL_STRIP mirror.
1056
+ const mab = g.node('ModelAttentionBackend', {
1057
+ model: chunked,
1058
+ // schema-defaulted knob (the vocabulary door guarantees the
1059
+ // field — 'comfy kitchen attention' when the caller stays
1060
+ // silent; no compose-side fallback arm to keep alive)
1061
+ attention: p.attention_backend,
1062
+ }).out();
1063
+ const picked = g.node('ComfySwitchNode', {
1064
+
1065
+ // the dense arm; absent = on (every existing doc). The legacy
1066
+
1067
+ // no-silent-resolution law: sla_enabled is DECLARED with
1068
+ // .default(true), so the walk always delivers a boolean and
1069
+ // the fallback arms were unreachable lies.
1070
+ switch: p.sla_enabled, on_true: sla, on_false: mab,
1071
+ }).out();
1072
+ const loraModel = g.node('LTX_lora_loader', {
1073
+ model: picked, mode: 'minimax', stack_data: loraStack,
1074
+ }).out();
1075
+ const adaln = g.node('H3AdaLNLoRAFix', { model: loraModel, mode: 'port' }).out();
1076
+ sigmaModel = g.node('MiniMaxH3SigmaShift', {
1077
+ model: adaln, shift_video: shiftVideo, shift_audio: p.shift_audio,
1078
+ }).out();
1079
+
1080
+ // readout said 7s — the doc's totalFrames, last end_frame @24 —
1081
+ // and the render came back 3, this hardcoded 90 budget). The
1082
+ // window's render length derives from the TIMELINE the calls
1083
+ // author: last end_frame − first start_frame, SNAPPED TO THE
1084
+ // 17k+5 GRID the engine's latent math lawfully renders (22+17k,
1085
+ // clamped [22,362] — the same set the length param's own
1086
+ // min/step admits; the first 168-span probe died inside
1087
+
1088
+ // retired 90/56 budgets remain the fallback ONLY for docs that
1089
+ // (the length source of truth is UPSTREAM of this renderer: the
1090
+ // schema's span rider serializes single-call spans as EXPLICIT
1091
+ // length, and the merged film computes per-window lengths — this
1092
+ // arm only falls back to the family budgets)
1093
+ // NO SILENT RESOLUTION LAW: the walked/stanza length IS the value
1094
+ // (single-call: the span rider's explicit span; multi-call: the
1095
+ // film total; fresh: the walked default; the 90/56 family budgets
1096
+ // retired with the nulling that fed them)
1097
+ const length = p.length;
1098
+ const r2v = g.node('MiniMaxH3ReferenceToVideo', {
1099
+ prompt, width: p.width,
1100
+ height: p.height, length: length,
1101
+ ref_image_size: p.ref_image_size,
1102
+ clip, vae: vaeVideo, audio_vae: vaeAudio,
1103
+ });
1104
+ cond = r2v.out(0);
1105
+ latent = r2v.out(1);
1106
+ fpsInput = 24;
1107
+ }
1108
+
1109
+ // mods — .safetensors packs extracted under the engine's
1110
+ // models/refmods/ — appended to the conditioning's reference
1111
+ // tokens through ALL DiT blocks (the pack rides the model's
1112
+ // native ref2va path; it spends conditioning-side tokens, never a
1113
+ // bundle-bus slot, so the refs-imply-r2v law does not fire on a
1114
+ // mod and BOTH arms share this one seam — Apply accepts the core
1115
+ // CONDITIONING either r2v arm emits and returns the same type).
1116
+ // Paths in, stems out: the loader's combo enumerates
1117
+ // models/refmods/ stems, so a path arrives as its basename minus
1118
+ // .safetensors — anything the engine cannot resolve refuses HERE,
1119
+ // loud, instead of dying server-side as a combo miss (the I2V
1120
+ // census-alignment law).
1121
+
1122
+ // the run-level list — the canon's refs-lane arm (a stated call
1123
+ // lane rides INSTEAD of the declared lane; absent inherits).
1124
+ // Comma strings (the UI wire form) and arrays (the agent form)
1125
+ // both resolve through wireList; the cap check below guards the
1126
+ // EFFECTIVE list.
1127
+ const bagMods = wireList(rb0.mods);
1128
+ const refModsAll = bagMods.length > 0 ? bagMods : wireList(p.ref_mods);
1129
+ if (refModsAll.length > 0) {
1130
+ if (refModsAll.length > REF_CAPS.refmods) {
1131
+ throw new Error(`[h3-timeline] ref_mods exceeds the loader's ${String(REF_CAPS.refmods)} slots (saw ${String(refModsAll.length)})`);
1132
+ }
1133
+ const modStem = (src) => {
1134
+ // Trim, then query-strip (the estate precedent:
1135
+ // timelineContract's _kindOfFile splits '?' first), then split
1136
+ // on BOTH separators — a backslash-prefixed or padded entry
1137
+ // would otherwise pass the suffix check with junk baked into
1138
+ // the stem and die server-side as a combo miss. The two `as`
1139
+ // casts are total (split always yields a non-empty array), so
1140
+ // this adds no defensive branches to the coverage face.
1141
+ const query = src.trim().split('?')[0];
1142
+ const base = query.split(/[\\/]/).pop();
1143
+ if (!base.endsWith('.safetensors')) {
1144
+ throw new Error(`[h3-timeline] ref_mods entries are .safetensors mods under models/refmods/ (saw '${src}')`);
1145
+ }
1146
+ return base.slice(0, -'.safetensors'.length);
1147
+ };
1148
+ const loaderInputs = { show_info: false };
1149
+ for (let i = 0; i < REF_CAPS.refmods; i++) {
1150
+ const src = refModsAll[i];
1151
+ loaderInputs[`mod_${i + 1}`] = src === undefined ? '(none)' : modStem(src);
1152
+ loaderInputs[`strength_${i + 1}`] = 1;
1153
+ loaderInputs[`copies_${i + 1}`] = 1;
1154
+ }
1155
+ const mods = g.node('MiniMaxH3RefModsLoader', loaderInputs).out(0);
1156
+ cond = g.node('MiniMaxH3RefModApply', {
1157
+ conditioning: cond, mods, override: false, retention: 1,
1158
+ curve_direction: 'constant', scramble_seed: -1,
1159
+ curve_shape: 'linear', curve_value: 1,
1160
+ }).out(0);
1161
+ }
1162
+ // ── sampler stack ──────────────────────────────────────────────────
1163
+ // card knob first (seed), renderer alias second.
1164
+ const noise = g.node('RandomNoise', { noise_seed: (p.noise_seed ?? p.seed) }).out();
1165
+ const samplerSel = g.node('KSamplerSelect', { sampler_name: p.sampler_name }).out();
1166
+ let sampler;
1167
+ if (isT4r) {
1168
+ sampler = samplerSel;
1169
+ }
1170
+ else {
1171
+ const ersde = g.node('SamplerER_SDE', {
1172
+ solver_type: 'ODE', max_stage: 3, eta: 0.0, s_noise: 1.0,
1173
+ }).out();
1174
+ // template carries switch=false as a LITERAL, not a bool node
1175
+ sampler = g.node('ComfySwitchNode', { switch: false, on_true: ersde, on_false: samplerSel }).out();
1176
+ }
1177
+ // THE FUN-CONTROLNET SEAT (007 L7): one insertion past the sigma
1178
+ // shift, BOTH t4 arms by construction (each arm assigns sigmaModel
1179
+ // above; every downstream consumer — BasicScheduler, BasicGuider,
1180
+ // the continuation seam, the soft-AV release — rides the chain's
1181
+ // tail). Empty picks → sigmaModel verbatim (byte-stable); entries
1182
+ // fire only when the family boards the controlnet pack (the kit's
1183
+ // boarding gate — the rows are the operator's BENCH row, 002 H1)
1184
+ // and every row fact (schedule capability, strength ceiling, the
1185
+ // clip/mask channels) arrived stamped by the service resolution.
1186
+ sigmaModel = applyH3FunControlNets(g, sigmaModel, vaeVideo, fireControlNets(model, p));
1187
+ const schedName = p.sched_name;
1188
+ const denoiseVal = p.denoise;
1189
+ const sched = g.node('BasicScheduler', {
1190
+ model: sigmaModel, scheduler: schedName,
1191
+ steps: p.steps, denoise: denoiseVal,
1192
+ }).out();
1193
+ let guider = g.node('BasicGuider', { model: sigmaModel, conditioning: cond }).out();
1194
+ let targetLatent = latent;
1195
+
1196
+ // seam is FORGOTTEN — the TimelineDirector drift-control
1197
+ // continuation is the one way, automatic): window k≥2 with a
1198
+ // carried seam rides MiniMaxH3FiniteLatentContinuation — the
1199
+ // previous window's RAW sampled latent becomes this window's
1200
+ // drift-controlled opening (schedule-matched prefix noise: the
1201
+ // carried tail's noise level walks down the sampler's own sigma
1202
+ // schedule, so the model never fights the anchor — the anti-drift
1203
+ // core for unbounded chains), the audio latent rides the Soft AV
1204
+ // half-cosine release (no seam pops), and the MODEL comes back
1205
+ // PATCHED — the guider rebinds to it and the sampler's target is
1206
+ // the MASKED latent. A 'cut' call (overlap 0) and every opener
1207
+ // never mount this block: a true fresh window.
1208
+
1209
+ // t4_chain-only, and the dialogue stamp routes stamped windows to
1210
+ // t4r — a stamped film silently lost the continuation AND the
1211
+ // carried-head trim (two independent windows hard-concatenated:
1212
+ // the broken seam the operator caught on the proof film). The
1213
+ // continuation is latent-level (wraps the sampler's model and
1214
+ // conditioning — family-agnostic); the trim is decode-level.
1215
+ // Every film window k>=2 chains, t4r included. THE WALL: a
1216
+ // stamped window with no Continuation node is a broken seam —
1217
+ // card-gap pins it ("the stamped seam wall").
1218
+ if (isChain || isT4r) {
1219
+ const prev = p.__prev;
1220
+ /* v8 ignore next 1 -- the film loop stamps __iteration on every window k≥2 before the render (the seam block mounts only when it did) */
1221
+ const iteration = p.__iteration ?? 0;
1222
+ /* v8 ignore next 1 -- the film loop stamps __overlap on every window k≥2 before the render (the seam block mounts only when it did) */
1223
+ const overlap = p.__overlap ?? 0;
1224
+ if (prev !== undefined && overlap > 0) {
1225
+ const cont = g.node('MiniMaxH3FiniteLatentContinuation', {
1226
+ positive: cond, target_latent: targetLatent,
1227
+ iteration, overlap_frames: overlap,
1228
+ continue_audio_latent: true,
1229
+ model: sigmaModel, sigmas: sched,
1230
+ previous_latent: prev.latOut,
1231
+ });
1232
+ cond = cont.out(0);
1233
+ targetLatent = cont.out(1);
1234
+ guider = g.node('BasicGuider', { model: cont.out(3), conditioning: cont.out(0) }).out();
1235
+ }
1236
+ }
1237
+ const sampled = g.node('SamplerCustomAdvanced', {
1238
+ noise, guider, sampler, sigmas: sched, latent_image: targetLatent,
1239
+ });
1240
+ let latOut = sampled.out(0);
1241
+ // ── THE T3 REFINE RIDER (roadmap item 2 — the crowd's third
1242
+ // tier, formalized): a short CLOSING pass over the window's
1243
+ // output latent — the refiner lora on its OWN loader (the
1244
+ // primary stack above NEVER changes), full-denoise short
1245
+ // schedule from the same noise seed, riding the doc's own
1246
+ // sampler/scheduler (the rider owns NO solver of its own — one
1247
+ // owner per knob). Mounted ONLY when the service resolved a
1248
+ // refine row; absent = the graph renders exactly as before.
1249
+ // The TaoMate refiner thread's mechanics: pass A full, pass B
1250
+ // closes. The rider sits UPSTREAM of decode AND of the film's
1251
+ // seam handles — the chained texture is the refined one.
1252
+
1253
+ // the only door to the whole post chain — sharpen, interp, VSR,
1254
+ // refine each AND it with their own switch (legacy docs with
1255
+ // leaves set but no master render the plain pass, byte-stable).
1256
+ const secondPassOn = p.second_pass_enabled === true;
1257
+ const refine = secondPassOn ? p.refine : undefined;
1258
+ if (refine !== undefined) {
1259
+ const refineModel = g.node('LTX_lora_loader', {
1260
+ model: sigmaModel, mode: 'minimax',
1261
+ stack_data: JSON.stringify([{ on: true, lora: refine.name, str: refine.strength, v: 1, a: 1, t: 1 }]),
1262
+ lora_ui: '',
1263
+ }).out();
1264
+ const refineSched = g.node('BasicScheduler', {
1265
+ model: refineModel, scheduler: schedName,
1266
+ steps: refine.steps, denoise: 1.0,
1267
+ }).out();
1268
+ const refineGuider = g.node('BasicGuider', { model: refineModel, conditioning: cond }).out();
1269
+ const refined = g.node('SamplerCustomAdvanced', {
1270
+ noise, guider: refineGuider, sampler: samplerSel, sigmas: refineSched, latent_image: latOut,
1271
+ });
1272
+ latOut = refined.out(0);
1273
+ }
1274
+ // ── decode + save ──────────────────────────────────────────────────
1275
+ let vdec = g.node('VAEDecode', { samples: latOut, vae: vaeVideo }).out();
1276
+ let vadec = g.node('VAEDecodeAudio', { samples: latOut, vae: vaeAudio }).out();
1277
+ // the RAW audio head is the soft seam's currency — the film's join
1278
+ // takes the incoming window's UNTRIMMED opening (it owns the seam);
1279
+ // captured BEFORE the clip finalize trims the overlap off
1280
+ let vadecRaw;
1281
+ // `delivered` fills at the save branches (both families save)
1282
+ let delivered = null;
1283
+ const rawHandles = { latOut, vdec, vadec, filmImages: latOut, filmAudio: latOut };
1284
+ if (isChain || isT4r) {
1285
+ const prev = p.__prev;
1286
+ /* v8 ignore next 1 -- the film loop stamps __overlap on every window k≥2 before the render (the block mounts only when it did) */
1287
+ const overlap = p.__overlap ?? 0;
1288
+ if (prev !== undefined && overlap > 0) {
1289
+ vadecRaw = vadec;
1290
+ // the window's OWN clip: the carried overlap leaves picture AND
1291
+ // sound by the same duration (their finalize, hard audio trim —
1292
+ // a clip never replays the seam it grew from)
1293
+ const fin = g.node('MiniMaxH3FiniteSegmentFinalize', {
1294
+ sampled_latent: latOut, images: vdec, audio: vadec,
1295
+ iteration: 1, overlap_frames: overlap, trim_audio_head: true,
1296
+ });
1297
+ vdec = fin.out(1);
1298
+ vadec = fin.out(2);
1299
+ }
1300
+ }
1301
+ if (isT4r) {
1302
+ const created = g.node('CreateVideo', {
1303
+ images: vdec, audio: vadec, fps: fpsInput, bit_depth: FILM_BIT_DEPTH,
1304
+ // color_space: pin autofill "sRGB"
1305
+ });
1306
+
1307
+ // every window saves under h3_t4_w<k> — the t4r arm's legacy
1308
+ // 'video/ComfyUI' prefix died (multi-window anchored films were
1309
+ // unaddressable: every window collided on one prefix, and the
1310
+ // file tail's loader could not name them).
1311
+ const saved = g.node('SaveVideo', {
1312
+ video: created.out(), filename_prefix: `h3_t4_w${k}`,
1313
+ format: 'auto', codec: 'h264',
1314
+ 'codec.encoding': 're-encode', 'codec.encoding.crf': 10.0,
1315
+ });
1316
+ rawHandles.savePassthrough = saved.out(0);
1317
+ delivered = { images: vdec, audio: vadec };
1318
+ }
1319
+ else {
1320
+ // sharpen leaves: only the EXPLICITLY-set ones patch the grouped
1321
+ // dict (absent leaves keep ImageSharpenKJ's own defaults). The old
1322
+ // card knob (sharpen_strength) rides the leaf loop like
1323
+ // the renderer alias does.
1324
+ const method = { ...SHARPEN_DEFAULTS };
1325
+ const sharpenLeaves = [
1326
+ ['sharpen_method', 'method'], ['sharpen_strength', 'strength'],
1327
+ ['sharpen_radius', 'radius'], ['sharpen_threshold', 'threshold'],
1328
+ ['sharpen_iterations', 'iterations'],
1329
+ ];
1330
+ for (const [src, dst] of sharpenLeaves) {
1331
+ const val = p[src];
1332
+ if (val !== null && val !== undefined)
1333
+ method[dst] = val;
1334
+ }
1335
+
1336
+ // upstream moved sharpen LAST: interp → VSR → sharpen → CreateVideo
1337
+ // (V7/ours sharpened FIRST — before the upscaler could soften the
1338
+ // detail away). Sharpen rcas 0.3 after upscale "looks natural"
1339
+ // (his V9 notes). The switches stay ours; the ORDER is his.
1340
+ const film = g.node('FrameInterpolationModelLoader', {
1341
+ model_name: p.interp_model,
1342
+ }).out();
1343
+ const interpMultVal = p.interp_multiplier;
1344
+ const interp = g.node('FrameInterpolate', {
1345
+ interp_model: film, images: vdec, multiplier: interpMultVal,
1346
+ }).out();
1347
+
1348
+ // (declared default false). The legacy interp_switch alias is
1349
+ // retired — post-declaration the walk materializes the primary,
1350
+ // so the alias arm was unreachable dead law.
1351
+ const interpSwOn = secondPassOn && p.interpolate_enabled;
1352
+ const interpSw = g.node('ComfySwitchNode', {
1353
+ switch: interpSwOn, on_true: interp, on_false: vdec,
1354
+ }).out();
1355
+ const srRes = p.sr_resolution;
1356
+ const sr = g.node('SeedVR2VideoUpscaler', {
1357
+ image: interpSw,
1358
+ dit: g.node('SeedVR2LoadDiTModel', {
1359
+ model: p.sr_model, device: 'cuda:0',
1360
+ }).out(),
1361
+ vae: g.node('SeedVR2LoadVAEModel', {
1362
+ model: LANE_FILES.sr_vae, device: 'cuda:0',
1363
+ }).out(),
1364
+ seed: 42, resolution: srRes,
1365
+ max_resolution: 0, batch_size: 5, uniform_batch_size: false,
1366
+ color_correction: 'lab',
1367
+ }).out();
1368
+ const srSwOn = secondPassOn && p.sr_switch;
1369
+ const srSw = g.node('ComfySwitchNode', {
1370
+ switch: srSwOn, on_true: sr, on_false: interpSw,
1371
+ }).out();
1372
+ // sharpen LAST (V9): the upscaler softens; rcas after it restores.
1373
+ // Renderer alias second (sharpen_* leaves above build the method).
1374
+ const sharpened = g.node('ImageSharpenKJ', { image: srSw, method }).out();
1375
+ const sharpSw = g.node('ComfySwitchNode', {
1376
+ switch: secondPassOn && p.sharpen_enabled, on_true: sharpened, on_false: srSw,
1377
+ }).out();
1378
+
1379
+ // CreateVideo.fps = base × interp multiplier (his Enhancements:
1380
+ // PrimitiveFloat 24 → ComfyMathExpression "a * 2" → fps). Without
1381
+ // it every interp-on window plays at HALF speed — the frames
1382
+ // double, the fps doesn't. Byte-stable at defaults (interp off →
1383
+ // the served literal 24).
1384
+ const interpOn = secondPassOn && p.interpolate_enabled;
1385
+ const interpMult = p.interp_multiplier;
1386
+ const created = g.node('CreateVideo', {
1387
+ images: sharpSw, audio: vadec, fps: interpOn ? 24 * interpMult : 24, bit_depth: FILM_BIT_DEPTH,
1388
+ // color_space: pin autofill "sRGB"
1389
+ });
1390
+ const saved = g.node('SaveVideo', {
1391
+ video: created.out(), filename_prefix: `h3_t4_w${k}`,
1392
+ format: 'mp4', codec: 'h264',
1393
+ });
1394
+ rawHandles.savePassthrough = saved.out(0);
1395
+ delivered = { images: sharpSw, audio: vadec };
1396
+ }
1397
+ // (every family path delivers — both arms save the window's clip;
1398
+ // no null arm: the family dispatch is exhaustive over FAMILIES.
1399
+ // The old MotionContextSaveLatent persistence died with the seam —
1400
+ // cross-run continuity is the FL2VA anchor: set the first-frame
1401
+ // square to the previous film's last frame, latent-true.)
1402
+ rawHandles.filmImages = delivered.images;
1403
+ // THE FILM'S AUDIO SEAM CURRENCY: a carried window hands the film
1404
+ // its UNTRIMMED opening (the soft-released head owns the join);
1405
+ // every other window hands its delivered audio
1406
+ rawHandles.filmAudio = vadecRaw !== undefined
1407
+ ? vadecRaw
1408
+ : delivered.audio;
1409
+ return rawHandles;
1410
+ }
1411
+ /** The film action — the h3 family's whole compose segment. The
1412
+ * doc arrives gated + lifted from the card; the build owns the
1413
+ * lane admissions and both renderers (this module is their only
1414
+ * seat). */
1415
+ /** The sampler row the h3 schema itself serves: the ONE engine
1416
+ * vocabulary read through the family's recommended subset (the
1417
+ * schema's own filter law — a retyped list would be a second
1418
+ * SSOT). */
1419
+ const H3_SAMPLER_OPTIONS = SAMPLER_OPTIONS.filter((n) => H3_RECOMMENDED_SAMPLERS.includes(n));
1420
+ export const film = {
1421
+ id: 'film',
1422
+ inputs: [],
1423
+ outputs: [{ name: 'video', kind: 'VIDEO' }],
1424
+ // GATE S (the seed sentinel — the estate's one-mint law): the
1425
+ // schema's default is 42 and explicit seeds ride verbatim; an
1426
+ // explicit -1 (the ComfyUI randomize idiom) mints CLIENT-SIDE
1427
+ // through the one helper instead of leaving the choice to the
1428
+
1429
+ // family port (the card's legacy else still passes -1 through;
1430
+ // the action oracle pins that one deliberate divergence).
1431
+ // THE DECLARED SURFACE (the write plane, phase 2): the h3 card
1432
+ // schema's own types and bounds — the family door judges defaults
1433
+ // and variant presets against this row. The sampler row resolves
1434
+ // from the ONE engine vocabulary read through the family's
1435
+ // recommended subset (the schema's own filter); the scheduler row
1436
+ // reads the whole vocabulary. The timeline's own JSON row params
1437
+ // (calls, audio_clips) ride the timeline contract's validators,
1438
+ // not this surface; the per-window rows (k, noise_seed,
1439
+ // fps_seconds) are internal. ref_image_size is the schema's
1440
+ // const-or-WxH pattern tier — typed as its string spine.
1441
+ params: [
1442
+ { name: "prompt", type: "string" },
1443
+ { name: "image", type: "string" },
1444
+ { name: "last_frame", type: "string" },
1445
+ { name: "ref_images", type: "image_list" },
1446
+ { name: "ref_videos", type: "image_list" },
1447
+ { name: "ref_audios", type: "image_list" },
1448
+ { name: "ref_mods", type: "image_list" },
1449
+ { name: "duck_depth_db", type: "number", bounds: [-48, 0] },
1450
+ { name: "seed", type: "number", rule: "seed-sentinel" },
1451
+ { name: "width", type: "number", bounds: [448, 1344] },
1452
+ { name: "height", type: "number", bounds: [448, 768] },
1453
+ { name: "length", type: "number", bounds: [22, 362] },
1454
+ { name: "steps", type: "number", bounds: [4, 30] },
1455
+ { name: "second_pass_enabled", type: "boolean" },
1456
+ { name: "sharpen_enabled", type: "boolean" },
1457
+ { name: "sharpen_strength", type: "number", bounds: [0, 1] },
1458
+ { name: "sharpen_method", type: "enum", options: ["rcas", "adaptive_usm", "high_pass", "deconvolution"] },
1459
+ { name: "sharpen_radius", type: "number", bounds: [0.5, 5] },
1460
+ { name: "sharpen_threshold", type: "number", bounds: [0, 1] },
1461
+ { name: "sharpen_iterations", type: "number", bounds: [1, 100] },
1462
+ { name: "interpolate_enabled", type: "boolean" },
1463
+ { name: "interp_model", type: "enum", options: ["film_net_fp16.safetensors", "rife47.pth"] },
1464
+ { name: "interp_multiplier", type: "number", bounds: [2, 4] },
1465
+ { name: "denoise", type: "number", bounds: [0, 1] },
1466
+ { name: "sampler_name", type: "enum", options: H3_SAMPLER_OPTIONS },
1467
+ { name: "sched_name", type: "enum", options: SCHEDULER_OPTIONS },
1468
+ { name: "refine_lora", type: "string" },
1469
+ { name: "refine_strength", type: "number", bounds: [0, 2] },
1470
+ { name: "refine_steps", type: "number", bounds: [1, 10] },
1471
+ { name: "attention_backend", type: "enum", options: ["comfy kitchen attention", "pytorch attention"] },
1472
+ { name: "sr_switch", type: "boolean" },
1473
+ { name: "sr_resolution", type: "number", bounds: [720, 2160] },
1474
+ { name: "sr_model", type: "enum", options: ["seedvr2_ema_3b_fp16.safetensors", "seedvr2_ema_3b_fp8_e4m3fn.safetensors"] },
1475
+ { name: "ref_image_size", type: "string" },
1476
+ { name: "shift_video", type: "number", bounds: [1, 20] },
1477
+ { name: "shift_audio", type: "number", bounds: [1, 10] },
1478
+ { name: "sla_enabled", type: "boolean" },
1479
+ { name: "sla_sparsity", type: "number", bounds: [0, 0.95] },
1480
+ { name: "sla_block_size", type: "enum", options: ["32", "64", "128"] },
1481
+ { name: "sla_min_seq_len", type: "number", bounds: [512, Number.MAX_SAFE_INTEGER] },
1482
+ { name: "sla_dense_last_steps", type: "number", bounds: [0, 10] },
1483
+ { name: "sla_dense_steps", type: "string" },
1484
+ { name: "sla_dense_backend", type: "enum", options: ["comfy_kitchen", "pytorch", "auto"] },
1485
+ { name: "sla_reference_protection", type: "enum", options: ["Off", "Light", "Heavy Enforcement"] },
1486
+ { name: "sla_protect_audio", type: "boolean" },
1487
+ { name: "sla_stabilize_motion", type: "boolean" },
1488
+ { name: "sla_disable_fp16_accum", type: "boolean" },
1489
+ { name: "interp_switch", type: "boolean" },
1490
+ { name: "sharpen_switch", type: "boolean" },
1491
+ { name: "sla_switch", type: "boolean" },
1492
+ { name: "image_name", type: "string" },
1493
+ ],
1494
+ facts: parseH3Facts,
1495
+ build({ p: docIn, facts, g, model }) {
1496
+ const p = { ...docIn };
1497
+
1498
+ // single-call doc rides the frozen single-window arm below —
1499
+ // which renders the DOC surface, never the row. Without this
1500
+ // unpack the sole call's Layer B seats (refs bag, anchor image,
1501
+ // text, render knobs) died silently on every single-call doc:
1502
+ // the split-brain twin of the film loop's bag gate. One stanza
1503
+ // law, both arms: the row REPLACES the refs bag / anchor / text
1504
+ // seats it states (per-lane, per-seat); knobs replace per key;
1505
+ // unstated seats inherit the doc.
1506
+ {
1507
+ const row = Array.isArray(p.calls) && p.calls.length === 1
1508
+ ? p.calls[0]
1509
+ : null;
1510
+ if (row !== null) {
1511
+ const rowText = typeof row.text === 'string' ? row.text.trim() : '';
1512
+ if (rowText !== '')
1513
+ p.prompt = row.text;
1514
+ if (row.refs !== undefined && row.refs !== null)
1515
+ p.refs = row.refs;
1516
+ const rowImage = typeof row.image === 'string' ? row.image.trim() : '';
1517
+ if (rowImage !== '')
1518
+ p.image = row.image;
1519
+
1520
+ // law): the row's DIRECT media lanes ride onto p — the same
1521
+ // per-seat replace canon the stanza arm carries; before this
1522
+ // lift a single-window doc's row-level refs died unread.
1523
+ if (typeof row.last_frame === 'string' && row.last_frame.trim() !== '')
1524
+ p.last_frame = row.last_frame;
1525
+ if (wireList(row.ref_images).length > 0)
1526
+ p.ref_images = row.ref_images;
1527
+ if (wireList(row.ref_videos).length > 0)
1528
+ p.ref_videos = row.ref_videos;
1529
+ if (wireList(row.ref_audios).length > 0)
1530
+ p.ref_audios = row.ref_audios;
1531
+ const rowKnobs = (row.knobs ?? null);
1532
+ if (rowKnobs !== null)
1533
+ Object.assign(p, rowKnobs);
1534
+ }
1535
+ }
1536
+ const guideImage = (p.image ?? p.image_name ?? '');
1537
+
1538
+ // LAWFUL stated family in conflict with a guide still refuses
1539
+ // loud — an explicit t4_open/t4_chain pin over an anchored doc
1540
+ // is a contract conflict, named at build. An axis-seeded string
1541
+ // ('timeline' — model metadata, not a family claim) never
1542
+ // reaches this guard: the seats derive the family and the
1543
+ // guide owns the reference lane.
1544
+ const statedFamily = typeof p.variant === 'string' && FAMILIES.includes(p.variant)
1545
+ ? p.variant : undefined;
1546
+ if (guideImage !== '' && statedFamily !== undefined && statedFamily !== 't4r') {
1547
+ const rbRef = (p.refs ?? {});
1548
+ const refsCarry = wireList(rbRef.images).length + wireList(rbRef.videos).length + wireList(rbRef.audios).length
1549
+ + wireList(p.ref_images).length + wireList(p.ref_videos).length + wireList(p.ref_audios).length > 0
1550
+ || (typeof p.last_frame === 'string' && p.last_frame.trim() !== '');
1551
+ if (!refsCarry) {
1552
+ throw new Error(`h3_window: a guide image ("${guideImage.trim()}") rides only the t4r reference lane — ` +
1553
+ `this doc's variant is '${String(p.variant)}'. State no variant (the walk derives t4r from ` +
1554
+ 'the guide) or clear the guide; never a silent text-only render of a reference shot');
1555
+ }
1556
+ }
1557
+
1558
+ // the guard below polices "t4r without a guide" — but the
1559
+ // run-899a8448 rot was the INVERSE hole: a guide present while
1560
+ // variant derived t4_open (the schema derivation missed the
1561
+ // `image` spelling), so renderH3Window took the non-reference
1562
+ // arm, the anchor arm inside `if (isT4r)` never ran, and the
1563
+ // window rendered text-only with the user's reference silently
1564
+ // dead. A guide-bearing window that is not t4r and carries no
1565
+ // reference bus REFUSES here — one law, both directions.
1566
+ if (statedFamily === 't4r' && !guideImage) {
1567
+ // (refs-implied t4r windows carry no anchor — the bundle IS
1568
+ // the r2v input; the guard admits them via the refs law — the
1569
+ // legacy stanza bag AND the declared input surface (the rail's
1570
+ // fields) count; the bed rides the audio lane guideless too)
1571
+ const rbRef = (p.refs ?? {});
1572
+ const refsCarry = wireList(rbRef.images).length + wireList(rbRef.videos).length + wireList(rbRef.audios).length
1573
+ + wireList(p.ref_images).length + wireList(p.ref_videos).length + wireList(p.ref_audios).length > 0
1574
+ || (typeof p.last_frame === 'string' && p.last_frame.trim() !== '');
1575
+ if (!refsCarry) {
1576
+ throw new Error('h3_window(t4r): image-anchored window without a staged guide image — ' +
1577
+ 'compose always injects LoadImage.0.image on this family');
1578
+ }
1579
+ }
1580
+
1581
+ // calls ARE the grammar — more than one call with no per-window
1582
+ // stanza markers (k absent) composes the MERGED film; everything
1583
+ // else is the frozen single-window shape. The variant string
1584
+ // NEVER gates this seat: it is axis metadata ('timeline') or a
1585
+ // schema stamp derived from these same calls — reading it here
1586
+ // demoted multi-window docs to one window and burned the
1587
+ // operator's timing (bench-session-2d6af763, variant:'timeline').
1588
+ const docCalls = Array.isArray(p.calls) ? p.calls : null;
1589
+ const isFilm = docCalls !== null && docCalls.length > 1 && p.k === undefined;
1590
+ if (isFilm)
1591
+ return renderH3Film(p, g, facts, model);
1592
+
1593
+ // FILM-path consumer (it rides the accumulated film audio).
1594
+ // On the frozen single-window shape it would be a silent
1595
+ // skip — the crime class this estate refuses. Loud, with the
1596
+ // fix in the message (the studio's own doc always carries
1597
+ // calls; a second short call unlocks the film path).
1598
+ const clips = (p.audio_clips ?? []);
1599
+ if (clips.some((c) => c !== null && typeof c === 'object'
1600
+ && typeof c.src === 'string' && c.src.trim() !== '')) {
1601
+ throw new Error('h3-timeline: audio clips ride the FILM path — this single-window doc has clips but no film to mix over ' +
1602
+ '(add a second call to author a film, or clear the Music row)');
1603
+ }
1604
+
1605
+ // honors the distill bag's steps — ONE STEPS LAW for both
1606
+ // window paths (007 L3, the film path's verbatim): the marriage
1607
+ // fires only when the caller pinned no steps of their own. The
1608
+ // doc face reads the schema's __steps_pinned stamp (a walked
1609
+ // default is not a pin); the call face reads the single call's
1610
+ // knobs (the film path's own `knobs.steps === undefined` arm).
1611
+ // An explicit count is the user's word — the distill default
1612
+ // never overwrites it.
1613
+ if (Array.isArray(p.loras)) {
1614
+ const rows = p.loras;
1615
+ const applied = rows.map((r) => r.steps).filter((v) => typeof v === 'number' && Number.isFinite(v));
1616
+ const singleKnobs = docCalls !== null && docCalls.length === 1
1617
+ ? (docCalls[0].knobs ?? {})
1618
+ : {};
1619
+ if (applied.length > 0 && p.__steps_pinned !== true && singleKnobs.steps === undefined) {
1620
+ p.steps = Math.max(...applied);
1621
+ }
1622
+ }
1623
+ return renderH3Window(p, g, facts, model).savePassthrough;
1624
+ },
1625
+ };
1626
+ //# sourceMappingURL=actions.js.map