@melite/models-h3 0.2.2-alpha → 0.2.3-rc.4

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 CHANGED
@@ -1,11 +1,12 @@
1
1
  import { fireControlNets } from '@melite/comfyui-card-kit/guard';
2
2
  import { saveAudio } from '@melite/comfyui-card-kit';
3
- import { mediaKindOf } from '@melite/contracts/mediaKinds';
4
- import { assertKeyframeRowShape, FAMILIES, paramSchema, wireList, H3_RECOMMENDED_SAMPLERS, REFINE_DENOISE_DEFAULT } from './schema.js';
3
+ import { assertKeyframeRowShape, FAMILIES, paramSchema, wireList, H3_RECOMMENDED_SAMPLERS, REFINE_DENOISE_DEFAULT, outputNameTailOf } from './schema.js';
5
4
  import { H3_LORA_ROWS } from '@melite/models-h3/mods/loras';
6
5
  import { SAMPLER_OPTIONS, SCHEDULER_OPTIONS } from '@melite/comfyui-card-kit/vocab';
7
- import { computeFilmMix, parseFilmMixClips, spanOverlap, stanzaSecs } from './filmMix.js';
8
- import { DOC_FPS_DEFAULT, GRID_REMAINDER, GRID_STEP_FRAMES, IMAGE_BUS_SLOTS, REF_CAPS, assertGridLength, assertSpanGrid, bookSeconds, imageReferenceCap, isGridLength, isMediaRef, spanStanzaFrames, transitionOverlap } from './timelineContract.js';
6
+ import { chooseLaneClips, computeFilmMix, parseFilmMixClips, spanOverlap, stanzaSecs } from './filmMix.js';
7
+ import { SECOND_PASS_WINDOW } from './secondPass.js';
8
+ import { mountRefModBake } from './refmodBake.js';
9
+ import { DOC_FPS_DEFAULT, GRID_REMAINDER, GRID_STEP_FRAMES, IMAGE_BUS_SLOTS, LAST_FRAME_BATCH_INDEX, REF_CAPS, assertGridLength, assertSpanGrid, bookSeconds, imageReferenceCap, isGridLength, isMediaRef, spanStanzaFrames, transitionOverlap } from './timelineContract.js';
9
10
  import { applyH3ReshootCond, applyH3ReshootModel, buildH3Reshoot, reshootArmed, reshootPrompt, } from './reshoot.js';
10
11
 
11
12
 
@@ -186,8 +187,10 @@ function resolveRefineSeat(p) {
186
187
  // borrowed verbatim by the arm.
187
188
  function resolveStage2Denoise(p) {
188
189
  const denoise = p.refine_denoise ?? REFINE_DENOISE_DEFAULT;
189
- if (!(denoise >= 0.05 && denoise <= 1)) {
190
- throw new Error(`h3 action: refine_denoise ${String(p.refine_denoise)} falls outside the refinement window [0.05, 1] — 1 is the full-denoise taomate mechanic, 0.30–0.35 the SOTA refinement window; a dead or over-terminal second pass never composes`);
190
+ // THE SHARED WINDOW (secondPass.ts): the bounds are the seat's
191
+ // own — this door keeps its taomate voice.
192
+ if (!(denoise >= SECOND_PASS_WINDOW[0] && denoise <= SECOND_PASS_WINDOW[1])) {
193
+ throw new Error(`h3 action: refine_denoise ${String(p.refine_denoise)} falls outside the refinement window [${SECOND_PASS_WINDOW.join(', ')}] — 1 is the full-denoise taomate mechanic, 0.30–0.35 the SOTA refinement window; a dead or over-terminal second pass never composes`);
191
194
  }
192
195
  return denoise;
193
196
  }
@@ -601,16 +604,24 @@ function renderH3Film(p, g, facts, model, runId) {
601
604
  if (sf !== null && ef !== null && Number.isFinite(sf) && Number.isFinite(ef) && ef > sf) {
602
605
  const carry = i > 0 ? overlap : 0;
603
606
  const genStart = sf - carry;
604
- for (let ci = 0; ci < clips.length; ci++) {
605
- const clip = clips[ci];
606
- if (clip.dur <= 0)
607
+
608
+ // a clip that STARTS inside this window owns its class's
609
+ // lane; a seam-crossing clip owns only a window no same-class
610
+ // clip starts inside (the line continues, never restarts, but
611
+ // it yields to the window's own speech); two same-class
612
+ // starters inside one window refuse loud. Row order
613
+
614
+ // window 2's dialogue lane from the row that started there,
615
+ // and window 2 re-performed line 1 while the real row
616
+ // conditioned nothing.
617
+ const lanes = chooseLaneClips(clips, sf, ef, genStart);
618
+ for (const cls of ['dialogue', 'sfx', 'music']) {
619
+ const ci = lanes[cls];
620
+ if (ci === undefined)
607
621
  continue;
608
- if (stamps[clip.cls] !== undefined)
609
- continue; // one lane per class per window
622
+ const clip = clips[ci];
610
623
  const lo = Math.max(clip.start, genStart);
611
624
  const hi = Math.min(clip.start + clip.dur, ef);
612
- if (hi - lo < 2.4)
613
- continue; // below the slice node's 0.1s floor
614
625
  // ONE CLOCK (journey audit AUDIO-2): the stamps' seconds
615
626
  // speak the DOC CLOCK — p.fps when stated, the schema row's
616
627
  // default otherwise. The /24 literal stretched a 16fps
@@ -618,9 +629,13 @@ function renderH3Film(p, g, facts, model, runId) {
618
629
  // the audit's worst burn).
619
630
  const stampFps = typeof p.fps === 'number' && p.fps > 0 ? p.fps : DOC_FPS_DEFAULT;
620
631
  const ms = (frames) => Math.round((frames / stampFps) * 1000) / 1000;
621
- stamps[clip.cls] = {
632
+ stamps[cls] = {
622
633
  src: clip.src,
623
- slice_start_seconds: ms(Math.max(0, genStart - clip.start)),
634
+ // the SOURCE in-point rides BOTH halves (the clipping
635
+ // lane): the conditioning slice starts in_frames into the
636
+ // source, exactly where the pristine overlay starts — the
637
+ // model hears the segment the film plays.
638
+ slice_start_seconds: ms(clip.srcIn + Math.max(0, genStart - clip.start)),
624
639
  slice_duration_seconds: ms(hi - lo),
625
640
  delay_seconds: ms(Math.max(0, clip.start - genStart)),
626
641
  text: clip.text,
@@ -722,7 +737,10 @@ function renderH3Film(p, g, facts, model, runId) {
722
737
  // in renderH3Window's family line, never a window that claims
723
738
  // t4_open while its chain rides the reference arm).
724
739
  const winPins = (p.__keyframe_pins ?? {})[String(k)] ?? [];
725
- stanza.variant = (guide !== '' || hasRefs || hasDirectRefs || anyStamp || winPins.length > 0) ? 't4r' : chainLike ? 't4_chain' : 't4_open';
740
+ // the seam keyframe pin is the same class (an image guide at
741
+ // frame 0) — the window derives the reference lane with it
742
+ const seamKeyframe = stanza.__seam_keyframe === true;
743
+ stanza.variant = (guide !== '' || hasRefs || hasDirectRefs || anyStamp || winPins.length > 0 || seamKeyframe) ? 't4r' : chainLike ? 't4_chain' : 't4_open';
726
744
  // the distill's steps apply unless this call's knobs pinned steps
727
745
  // — or the DOC did (the __steps_pinned stamp, the walk's own
728
746
  // explicit-keys fact; the single-window marriage always consulted
@@ -815,6 +833,14 @@ function renderH3Film(p, g, facts, model, runId) {
815
833
  if (i > 0) {
816
834
  stanza.__iteration = k - 1;
817
835
  stanza.__overlap = overlap;
836
+ // THE THIRD CARRY MODE (the context-carry modes): a
837
+ // 'carry+keyframe' seam chains like extend (the overlap
838
+ // derives the same 22f — transitionOverlap reads only 'cut')
839
+ // AND stamps the keyframe pin — the renderer's seam block
840
+ // mounts the previous window's decoded final frame as this
841
+ // window's first-frame guide (one derivation, no new chain).
842
+ if (call.transition === 'carry+keyframe')
843
+ stanza.__seam_keyframe = true;
818
844
  }
819
845
  if (prev !== undefined)
820
846
  stanza.__prev = prev;
@@ -973,8 +999,14 @@ function renderH3Film(p, g, facts, model, runId) {
973
999
  let nextSeat = 0;
974
1000
  const mixRows = manifest.placements.map((pl) => {
975
1001
  const clip = clips[pl.clip];
1002
+ // THE OVERLAY'S IN-POINT (the clipping lane): in_sec rides only
1003
+ // when the clip starts past the source head — a 0 in-point omits
1004
+ // the key, byte-identical to every manifest row composed before
1005
+ // the lane existed (the wired-row arm freezes that shape).
1006
+ const inSec = Math.round((clip.srcIn / (typeof p.fps === 'number' && p.fps > 0 ? p.fps : DOC_FPS_DEFAULT)) * 1000) / 1000;
1007
+ const inField = inSec > 0 ? { in_sec: inSec } : {};
976
1008
  if (!isSpell(clip.src)) {
977
- return { src: clip.src, start_sec: pl.filmSec, dur_sec: pl.durSec, class: pl.cls };
1009
+ return { src: clip.src, start_sec: pl.filmSec, dur_sec: pl.durSec, class: pl.cls, ...inField };
978
1010
  }
979
1011
  nextSeat += 1;
980
1012
  if (nextSeat > WIRED_CLIP_SEATS) {
@@ -984,7 +1016,7 @@ function renderH3Film(p, g, facts, model, runId) {
984
1016
  audio: clip.src,
985
1017
  sample_rate: FILM_AUDIO_RATE,
986
1018
  }).out(0);
987
- return { wired: nextSeat, start_sec: pl.filmSec, dur_sec: pl.durSec, class: pl.cls };
1019
+ return { wired: nextSeat, start_sec: pl.filmSec, dur_sec: pl.durSec, class: pl.cls, ...inField };
988
1020
  });
989
1021
  const mix = g.node('MeliteFilmAudioMix', {
990
1022
  videos: windowPrefixes.join(','),
@@ -1014,11 +1046,18 @@ function renderH3Film(p, g, facts, model, runId) {
1014
1046
  // clips-free arm rides — container mux only (CreateVideo +
1015
1047
  // SaveVideo h264/mp4 on the decoded window files), never the
1016
1048
  // mix. The mix rides it: audio carries the node's output.
1017
- return concatSavedFilms(g, windowPrefixes, after, `${runId}/h3_t4_film`, {
1049
+
1050
+ // press): a spelled output_name rides the DELIVERED film's
1051
+ // prefix leaf (`h3_t4_film_<slug>`) so the artifact is BORN
1052
+ // named — absent, the machinery prefix is byte-frozen. Both
1053
+ // film arms carry it; the windows and the audio stem stay
1054
+ // machinery (chain intermediates, and the film-lead finders
1055
+ // key on the film stem alone).
1056
+ return concatSavedFilms(g, windowPrefixes, after, `${runId}/h3_t4_film${outputNameTailOf(p)}`, {
1018
1057
  audio: meter.out(0),
1019
1058
  });
1020
1059
  }
1021
- return concatSavedFilms(g, windowPrefixes, after, `${runId}/h3_t4_film`);
1060
+ return concatSavedFilms(g, windowPrefixes, after, `${runId}/h3_t4_film${outputNameTailOf(p)}`);
1022
1061
  }
1023
1062
  /** THE FUN-CONTROLNET CHAIN (002 H2/H4 + 007 L7): family-owned,
1024
1063
  * the LTX_lora_loader precedent — the node pair is the family's
@@ -1173,7 +1212,17 @@ function renderH3Window(p, g, facts, model, runId) {
1173
1212
  min_seq_len: p.sla_min_seq_len,
1174
1213
  dense_last_steps: p.sla_dense_last_steps,
1175
1214
  protect_audio: p.sla_protect_audio,
1176
- enabled: true,
1215
+ // THE NODE-SEAT BYPASS (the velocity arena's slaoff arm, caught
1216
+
1217
+ // pass the model straight through, for a like-for-like speed
1218
+ // baseline without rewiring" — is the DESIGNED bypass, and this
1219
+ // seat hardcoded true while sla_enabled:false only flipped the
1220
+ // DOWNSTREAM ComfySwitchNode. Both switch arms ride the SLA-
1221
+ // patched model (the dense arm wraps it), so the flag never
1222
+ // actually bypassed sparsity. The doc's flag now rides the
1223
+ // node's own input: false passes the model through UNPATCHED on
1224
+ // every arm; true (the declared default) is unchanged.
1225
+ enabled: p.sla_enabled,
1177
1226
  dense_steps: p.sla_dense_steps,
1178
1227
  dense_backend: p.sla_dense_backend,
1179
1228
  disable_fp16_accum: p.sla_disable_fp16_accum,
@@ -1791,156 +1840,11 @@ function renderH3Window(p, g, facts, model, runId) {
1791
1840
  // resolve through wireList; the cap check below guards the UNION.
1792
1841
  // (The refs-lane REPLACE canon governs the image/video/audio BUS
1793
1842
  // lanes only — REFMOD IS NOT REFERENCE.)
1794
- const bagMods = wireList(rb0.mods);
1795
- const declaredMods = wireList(p.ref_mods);
1796
- const seenMods = new Set(declaredMods.map((m) => m.trim()));
1797
- const refModsAll = [...declaredMods, ...bagMods.filter((m) => !seenMods.has(m.trim()))];
1798
- if (refModsAll.length > 0) {
1799
- if (refModsAll.length > REF_CAPS.refmods) {
1800
- throw new Error(`[h3-timeline] ref_mods exceeds the loader's ${String(REF_CAPS.refmods)} slots (saw ${String(refModsAll.length)})`);
1801
- }
1802
- const modStems = [];
1803
- const modImages = [];
1804
- const modVideos = [];
1805
- const modAudios = [];
1806
- for (const src of refModsAll) {
1807
- // Trim, then query-strip (the estate precedent:
1808
- // timelineContract's _kindOfFile splits '?' first), then split
1809
- // on BOTH separators — a backslash-prefixed or padded entry
1810
- // would otherwise pass the suffix check with junk baked into
1811
- // the stem and die server-side as a combo miss. The two `as`
1812
- // casts are total (split always yields a non-empty array), so
1813
- // this adds no defensive branches to the coverage face.
1814
- // A data: URL rides VERBATIM past the split (the studio's
1815
- // upload chips commit data URLs; the run's staging walk
1816
- // uploads them into the engine's input tree and rewrites the
1817
- // load nodes' slots — the family reads off the MIME here).
1818
- const raw = src.trim();
1819
- const query = raw.split('?')[0];
1820
- const base = query.split(/[\\/]/).pop();
1821
- if (raw.startsWith('data:')) {
1822
- const mime = /^data:([^;,]+)[;,]/.exec(raw)?.[1] ?? '';
1823
- if (mime.startsWith('image/'))
1824
- modImages.push(raw);
1825
- else if (mime.startsWith('video/'))
1826
- modVideos.push(raw);
1827
- else if (mime.startsWith('audio/'))
1828
- modAudios.push(raw);
1829
- else {
1830
- throw new Error(`[h3-timeline] ref_mods entries are ANY media (image/video/audio — the system bakes the pack) or pre-baked .safetensors stems under models/refmods/ (saw '${src.slice(0, 60)}')`);
1831
- }
1832
- continue;
1833
- }
1834
- if (base.endsWith('.safetensors')) {
1835
- modStems.push(base.slice(0, -'.safetensors'.length));
1836
- continue;
1837
- }
1838
- // ANY media kind boards (mediaKindOf — the contracts SSOT):
1839
- // image → the creator's refs_image.ref_image_N, video →
1840
- // refs_video.ref_video_N via the component split, audio → the
1841
- // audio extractor. Anything
1842
- // the estate does not recognize as media refuses HERE, loud,
1843
- // instead of dying server-side (the I2V census-alignment law).
1844
- const kind = mediaKindOf(base);
1845
- if (kind === 'image')
1846
- modImages.push(query);
1847
- else if (kind === 'video')
1848
- modVideos.push(query);
1849
- else if (kind === 'audio')
1850
- modAudios.push(query);
1851
- else {
1852
- throw new Error(`[h3-timeline] ref_mods entries are ANY media (image/video/audio — the system bakes the pack) or pre-baked .safetensors stems under models/refmods/ (saw '${src}')`);
1853
- }
1854
- }
1855
- // The chain's law: each mods source appends through its own
1856
- // Apply (Apply passes conditioning through, one mods input), in
1857
- // fixed order — pre-baked stems, the baked visual pack, then
1858
- // each baked audio pack.
1859
- const applyMods = (mods) => {
1860
- cond = g.node('MiniMaxH3RefModApply', {
1861
- conditioning: cond, mods, override: false, retention: 1,
1862
- curve_direction: 'constant', scramble_seed: -1,
1863
- curve_shape: 'linear', curve_value: 1,
1864
- }).out(0);
1865
- };
1866
- if (modStems.length > 0) {
1867
- const loaderInputs = { show_info: false };
1868
- for (let i = 0; i < REF_CAPS.refmods; i++) {
1869
- const stem = modStems[i];
1870
- loaderInputs[`mod_${i + 1}`] = stem === undefined ? '(none)' : stem;
1871
- loaderInputs[`strength_${i + 1}`] = 1;
1872
- loaderInputs[`copies_${i + 1}`] = 1;
1873
- }
1874
- applyMods(g.node('MiniMaxH3RefModsLoader', loaderInputs).out(0));
1875
- }
1876
- if (modImages.length > 0 || modVideos.length > 0) {
1877
- // One creator node stacks every visual ref of the seat into a
1878
- // single video-kind mod (the node's own grammar: stills into
1879
- // the refs_image autogrow container's grown slots, frame
1880
- // batches into refs_video's — DOTTED container.slot addressing,
1881
- // the r2v ref_images.ref_image_0 receipt; a BARE ref_image_1
1882
- // key is an undeclared input and phase 1 refuses it, the
1883
-
1884
- // ref's basename, sanitized node-side — a data: upload chip
1885
- // has no basename, so a data-only seat names the generic
1886
- // 'mod'. save rides the node default (true) so the baked pack
1887
- // lands in the loader's dropdown for later reuse.
1888
- const firstVisual = (modImages[0] ?? modVideos[0]);
1889
- const nameBase = firstVisual.startsWith('data:') ? 'mod' : firstVisual.split(/[\\/]/).pop()?.replace(/\.[^.]+$/, '') ?? 'mod';
1890
- // THE STATED BAKE (study §5/§7.2; value-arms ARMs 13/14): the
1891
- // fidelity dials are DECLARED params (schema.ts, the refmod
1892
- // group) and ride the node verbatim. Before this, pool and
1893
- // identity were SILENT engine defaults (nothing named them)
1894
- // and mode/save were pinned constants — the dials did not
1895
- // exist on this lane. The fallbacks are the declared defaults
1896
- // verbatim — one owner, the schema.
1897
- const bakeMode = typeof p.refmod_mode === 'string' ? p.refmod_mode : 'Compressed Reference';
1898
- const bakePool = typeof p.refmod_pool === 'number' && Number.isFinite(p.refmod_pool) ? p.refmod_pool : 16;
1899
- const bakeIdentity = typeof p.refmod_identity === 'number' && Number.isFinite(p.refmod_identity) ? p.refmod_identity : 500;
1900
- const extractInputs = {
1901
- name: nameBase,
1902
- mode: bakeMode, concept_type: 'generic',
1903
- save: p.refmod_save !== false,
1904
- pool_h: bakePool, pool_w: bakePool, identity: bakeIdentity,
1905
-
1906
- // (MiniMax-H3 VAE loader) or a standard VAE' — the engine
1907
- // refuses the extract at run time without one; both inputs
1908
- // are schema-optional, so no phase-1 judge can catch it).
1909
- // The family's own optimized H3 VAE rides (the int8-convrot
1910
- // video VAE, the same handle the film lane loads); no
1911
- // MINIMAX_H3_AV_ENCODER loader node exists in this engine's
1912
- // /object_info, so the standard-VAE input is THE wire.
1913
- vae: vaeVideo,
1914
- };
1915
- modImages.forEach((img, i) => {
1916
- extractInputs[`refs_image.ref_image_${i}`] = g.node('LoadImage', { image: img, upload: 'image' }).out(0);
1917
- });
1918
- modVideos.forEach((vid, i) => {
1919
- extractInputs[`refs_video.ref_video_${i}`] = g.node('GetVideoComponents', {
1920
- video: g.node('LoadVideo', { file: vid }).out(),
1921
- }).out(0);
1922
- });
1923
- applyMods(g.node('MiniMaxH3RefModExtract', extractInputs).out(0));
1924
- }
1925
- for (const src of modAudios) {
1926
- // Audio mods are their own extractor (AUDIO in, one mod out);
1927
- // one node per entry, voice-grade defaults, saved for reuse
1928
- // (a data: upload chip names the generic 'audio_mod').
1929
- // budget_policy + concept_type are REQUIRED bare combos in the
1930
- // engine's /object_info — no declared default, so no primed
1931
- // builder autofills them (the B7 wall refuses at compose) — the
1932
- // graph states the pack's own signature defaults
1933
- // (vendor/ComfyUI-MiniMaxH3Mod/nodes.py:2143: budget_policy
1934
- // 'error', concept_type 'voice').
1935
- applyMods(g.node('MiniMaxH3RefModAudioExtract', {
1936
- audio: g.node('LoadAudio', { audio: src }).out(),
1937
- audio_vae: vaeAudio,
1938
- name: src.startsWith('data:') ? 'audio_mod' : src.split(/[\\/]/).pop()?.replace(/\.[^.]+$/, '') ?? 'audio_mod',
1939
- budget_policy: 'error', concept_type: 'voice',
1940
- save: true,
1941
- }).out(0));
1942
- }
1943
- }
1843
+ // THE REFMOD BAKE now lives in refmodBake.ts (queue 13 P0-1:
1844
+ // one law, one home, two doors — the film path and the masked
1845
+ // edit chain mount the identical bake; see that module for the
1846
+ // merge law and the any-media law this seat obeys).
1847
+ cond = mountRefModBake(g, { p, bagMods: wireList(rb0.mods), cond, vaeVideo, vaeAudio });
1944
1848
  // ── sampler stack ──────────────────────────────────────────────────
1945
1849
  // card knob first (seed), renderer alias second.
1946
1850
  const noise = g.node('RandomNoise', { noise_seed: (p.noise_seed ?? p.seed) }).out();
@@ -1953,7 +1857,12 @@ function renderH3Window(p, g, facts, model, runId) {
1953
1857
  const ersde = g.node('SamplerER_SDE', {
1954
1858
  solver_type: 'ODE', max_stage: 3, eta: 0.0, s_noise: 1.0,
1955
1859
  }).out();
1956
- // template carries switch=false as a LITERAL, not a bool node
1860
+ // The ER_SDE wrap is THIS ESTATE's spelling — no official h3
1861
+ // workflow template composes SamplerER_SDE (verified across
1862
+
1863
+ // to a PrimitiveBoolean node, never a literal. The literal
1864
+ // false pins the pick to KSamplerSelect — the false side of
1865
+ // the templates' own sampler switch (their default posture).
1957
1866
  sampler = g.node('ComfySwitchNode', { switch: false, on_true: ersde, on_false: samplerSel }).out();
1958
1867
  }
1959
1868
  // THE FUN-CONTROLNET SEAT (007 L7): one insertion past the sigma
@@ -1966,12 +1875,14 @@ function renderH3Window(p, g, facts, model, runId) {
1966
1875
  // and every row fact (schedule capability, strength ceiling, the
1967
1876
  // clip/mask channels) arrived stamped by the service resolution.
1968
1877
 
1969
- // just ahead of it: the CrossView LoRA on the post-shift model —
1970
- // the official order (distill lora → shift → attention → the
1971
- // CrossView LoRA LAST) so the camera-trained adapters win, with
1972
- // any file-based picks refining on top. The hoisted reshootChain
1973
- // (the window head) is the one build — the film loop's stamped
1974
- // handles or the single-window's own.
1878
+ // comfy-reshoot reference app — reshoot.ts's pinned revision, NOT
1879
+ // a workflow template; no template carries a CrossView leg)
1880
+ // mounts just ahead of it: the CrossView LoRA on the post-shift
1881
+ // model — that app's order (distill lora → shift → attention →
1882
+ // the CrossView LoRA LAST) so the camera-trained adapters win,
1883
+ // with any file-based picks refining on top. The hoisted
1884
+ // reshootChain (the window head) is the one build — the film
1885
+ // loop's stamped handles or the single-window's own.
1975
1886
  if (reshootChain !== undefined)
1976
1887
  sigmaModel = applyH3ReshootModel(g, sigmaModel, p);
1977
1888
  sigmaModel = applyH3FunControlNets(g, sigmaModel, vaeVideo, fireControlNets(model, p));
@@ -2013,6 +1924,25 @@ function renderH3Window(p, g, facts, model, runId) {
2013
1924
  /* 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) */
2014
1925
  const overlap = p.__overlap ?? 0;
2015
1926
  if (prev !== undefined && overlap > 0) {
1927
+ // THE KEYFRAME CARRY (the third carry mode): the continuation
1928
+ // below chains the latent AND the prior window's decoded
1929
+ // FINAL FRAME is pinned as this window's first-frame guide —
1930
+ // extend.ts's own last-frame idiom (ImageFromBatch at the
1931
+ // clamp index, length 1), mounted through the image-pin
1932
+ // grammar (AddGuide at frame_idx 0, the keyframe lane's own
1933
+ // node) BEFORE the continuation wraps the conditioning: the
1934
+ // hard image anchor rides inside the drift-controlled seam.
1935
+ // The window derived t4r for the pin (the loop's variant
1936
+ // line), so the guide chain exists on this arm.
1937
+ if (p.__seam_keyframe === true) {
1938
+ const priorLast = g.node('ImageFromBatch', {
1939
+ image: prev.vdec, batch_index: LAST_FRAME_BATCH_INDEX, length: 1,
1940
+ }).out(0);
1941
+ cond = g.node('MiniMaxH3AddGuide', {
1942
+ positive: cond, latent: targetLatent,
1943
+ frame_idx: 0, vae: vaeVideo, image: priorLast,
1944
+ }).out(0);
1945
+ }
2016
1946
  const cont = g.node('MiniMaxH3FiniteLatentContinuation', {
2017
1947
  positive: cond, target_latent: targetLatent,
2018
1948
  iteration, overlap_frames: overlap,
@@ -2607,6 +2537,14 @@ export const film = {
2607
2537
  { name: "refmod_identity", type: "number", bounds: [0, 2000] },
2608
2538
  { name: "refmod_save", type: "boolean" },
2609
2539
  { name: "image_name", type: "string" },
2540
+
2541
+ // the deliverable slug the compose threads into every save
2542
+ // prefix (outputNameTailOf at the film stems). Plain string HERE
2543
+ // — the CARD schema row owns the slug law (charset + length,
2544
+ // refused loud at the walk); this row is the ADVERTISED face, so
2545
+ // the agent's film action names its own output. Absent = the
2546
+ // machinery prefix verbatim.
2547
+ { name: "output_name", type: "string" },
2610
2548
  ],
2611
2549
  facts: parseH3Facts,
2612
2550
  build({ p: docIn, facts, g, model, runId }) {
@@ -13,6 +13,38 @@ import type { H3Facts } from './actions.js';
13
13
 
14
14
 
15
15
  export declare const loadVideo: (g: GraphBuilder, path: string, frameLoadCap?: number, skipFirstFrames?: number) => OutputHandle[];
16
+
17
+
18
+
19
+
20
+
21
+
22
+
23
+
24
+
25
+
26
+
27
+
28
+
29
+
30
+
31
+
32
+
33
+
34
+
35
+
36
+
37
+
38
+
39
+ export declare const contexMaskedTarget: (g: GraphBuilder, plane: {
40
+ vaeVideo: OutputHandle;
41
+ vaeAudio: OutputHandle;
42
+ }, source: {
43
+ frames: OutputHandle;
44
+ audio: OutputHandle;
45
+ mask: OutputHandle;
46
+ keepAudio: boolean;
47
+ }) => OutputHandle;
16
48
  export declare const RESOLUTION_SHORT_EDGE: Readonly<Record<string, number>>;
17
49
  /** The engine's plan_clips shape math, ported (ext lines 270-273):
18
50
  * scale the source by shortEdge/min(w,h), snap both edges to 32
@@ -22,6 +54,26 @@ export declare const planTierShape: (width: number, height: number, shortEdge: n
22
54
  width: number;
23
55
  height: number;
24
56
  };
57
+
58
+
59
+
60
+
61
+
62
+
63
+
64
+
65
+
66
+
67
+
68
+ export declare const planTierPinOf: (filmWidth: number, filmHeight: number) => string;
69
+ /** P0-3 — the entry's stated tier VERBATIM, else the film's own
70
+ * pin: 'auto' (the form's derived default) and absence both derive.
71
+ * The agent never states a tier unless they mean to override the
72
+ * film's own geometry.
73
+ * @param entry the cell's bound entry (resolution seat)
74
+ * @param p the walked doc params (the film regime's width/height)
75
+ * @returns the tier label the plan node takes */
76
+ export declare const resolvePlanTier: (entry: Record<string, unknown>, p: Record<string, unknown>) => string;
25
77
  /** THE CROSS-REGIME JOIN ADMISSION: given the film regime's shape
26
78
  * (the doc's width/height — the shape this estate's film arm
27
79
  * renders and the join appends onto) and the mod bag's tier, answer
@@ -80,7 +132,21 @@ export interface ChainBodyHandles {
80
132
  readonly srcFrames: OutputHandle;
81
133
  /** the window's source audio, muted (the slice's audio seat). */
82
134
  readonly sliceAudio: OutputHandle;
135
+
136
+
137
+
138
+
139
+
140
+ readonly refImages: readonly OutputHandle[];
83
141
  }
142
+ /** Wire the sheet handles into an r2v creator's image slots at the
143
+ * cell's first free index (each cell owns its anchor count; the
144
+ * spine owns the load + the cap). A symmetric input slot to the
145
+ * agent, machinery to the graph.
146
+ * @param refImages the declared sheet handles (possibly empty).
147
+ * @param base the cell's first free ref_images index.
148
+ * @returns dotted-slot inputs for the creator node. */
149
+ export declare function sheetRefSlots(refImages: readonly OutputHandle[], base: number): Record<string, OutputHandle>;
84
150
  /** The seat's masked-edit body: the nodes between ChainCurrent and
85
151
  * ChainContext — the r2v anchors, the source slice, the edit latent,
86
152
  * the masked target. Returns the two wires ChainContext consumes. */
@@ -140,6 +206,18 @@ export interface MaskedChainSeat {
140
206
  /** the scheduler denoise: 1 fresh (swap/extend), partial refine
141
207
  * (repair — its own law refuses >= 1 at the seat's door). */
142
208
  readonly denoise: number;
209
+ /** THE UPSCALE DIAL (the fourth dial — the collapse's refine
210
+ * switch, FRICTION_3's DESIGN PROPOSAL): present = the chain's
211
+ * sampler tail becomes the learned RefineHandoff (the 3D-conv
212
+ * latent upscale + the low-sigma refine pass in one node) over
213
+ * the chain's OWN latents — the same-run second pass, never the
214
+ * saved-clip re-encode; absent = the plain SamplerCustomAdvanced
215
+ * tail, byte-identical to the pre-dial emission. */
216
+ readonly upscale?: {
217
+ readonly mode: string;
218
+ readonly scale: number;
219
+ readonly modelName: string;
220
+ };
143
221
  /** the seat's masked-edit body. */
144
222
  readonly body: ChainBody;
145
223
  /** the ChainAssemble terminal, or null (file-join posture). */
@@ -184,6 +262,22 @@ export declare const PLAN_CLIP_BAND: {
184
262
  readonly min: 2.5;
185
263
  readonly max: 15;
186
264
  };
265
+
266
+
267
+
268
+
269
+
270
+
271
+
272
+
273
+
274
+
275
+
276
+
277
+
278
+
279
+
280
+ export declare const PLAN_OVERLAP_CHOICES: readonly [22, 39, 56];
187
281
  /** Emit the shared masked-edit chain for one seat. The node
188
282
  * parameters are the three seats' historical spellings, verbatim;
189
283
  * the seat's deltas arrive through the seat interface. The emission