@melite/models-h3 0.2.0-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.
@@ -0,0 +1,29 @@
1
+ import type { GraphBuilder, OutputHandle } from '@melite/comfyui-card-kit/graph';
2
+
3
+
4
+
5
+
6
+
7
+
8
+
9
+
10
+
11
+
12
+
13
+
14
+
15
+
16
+
17
+
18
+
19
+
20
+
21
+
22
+ export declare function mountRefModBake(g: GraphBuilder, opts: {
23
+ p: Record<string, unknown>;
24
+ bagMods?: readonly string[];
25
+ cond: OutputHandle;
26
+ vaeVideo: OutputHandle;
27
+ vaeAudio: OutputHandle;
28
+ }): OutputHandle;
29
+ //# sourceMappingURL=refmodBake.d.ts.map
@@ -0,0 +1,176 @@
1
+ import { mediaKindOf } from '@melite/contracts/mediaKinds';
2
+ import { wireList } from './schema.js';
3
+ import { REF_CAPS } from './timelineContract.js';
4
+
5
+
6
+
7
+
8
+
9
+
10
+
11
+
12
+
13
+
14
+
15
+
16
+
17
+
18
+
19
+
20
+
21
+
22
+
23
+
24
+ export function mountRefModBake(g, opts) {
25
+ const { p, cond: inCond, vaeVideo, vaeAudio } = opts;
26
+ let cond = inCond;
27
+ const bagMods = opts.bagMods ?? [];
28
+ const declaredMods = wireList(p.ref_mods);
29
+ const seenMods = new Set(declaredMods.map((m) => m.trim()));
30
+ const refModsAll = [...declaredMods, ...bagMods.filter((m) => !seenMods.has(m.trim()))];
31
+ if (refModsAll.length === 0)
32
+ return cond;
33
+ if (refModsAll.length > REF_CAPS.refmods) {
34
+ throw new Error(`[h3-timeline] ref_mods exceeds the loader's ${String(REF_CAPS.refmods)} slots (saw ${String(refModsAll.length)})`);
35
+ }
36
+ const modStems = [];
37
+ const modImages = [];
38
+ const modVideos = [];
39
+ const modAudios = [];
40
+ for (const src of refModsAll) {
41
+ // Trim, then query-strip (the estate precedent:
42
+ // timelineContract's _kindOfFile splits '?' first), then split
43
+ // on BOTH separators — a backslash-prefixed or padded entry
44
+ // would otherwise pass the suffix check with junk baked into
45
+ // the stem and die server-side as a combo miss. The two `as`
46
+ // casts are total (split always yields a non-empty array), so
47
+ // this adds no defensive branches to the coverage face.
48
+ // A data: URL rides VERBATIM past the split (the studio's
49
+ // upload chips commit data URLs; the run's staging walk
50
+ // uploads them into the engine's input tree and rewrites the
51
+ // load nodes' slots — the family reads off the MIME here).
52
+ const raw = src.trim();
53
+ const query = raw.split('?')[0];
54
+ const base = query.split(/[\\/]/).pop();
55
+ if (raw.startsWith('data:')) {
56
+ const mime = /^data:([^;,]+)[;,]/.exec(raw)?.[1] ?? '';
57
+ if (mime.startsWith('image/'))
58
+ modImages.push(raw);
59
+ else if (mime.startsWith('video/'))
60
+ modVideos.push(raw);
61
+ else if (mime.startsWith('audio/'))
62
+ modAudios.push(raw);
63
+ else {
64
+ 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)}')`);
65
+ }
66
+ continue;
67
+ }
68
+ if (base.endsWith('.safetensors')) {
69
+ modStems.push(base.slice(0, -'.safetensors'.length));
70
+ continue;
71
+ }
72
+ // ANY media boards (mediaKindOf — the contracts SSOT): image →
73
+ // the creator's refs_image.ref_image_N, video →
74
+ // refs_video.ref_video_N via the component split, audio → the
75
+ // audio extractor. Anything the estate does not recognize as
76
+ // media refuses HERE, loud, instead of dying server-side (the
77
+ // I2V census-alignment law).
78
+ const kind = mediaKindOf(base);
79
+ if (kind === 'image')
80
+ modImages.push(query);
81
+ else if (kind === 'video')
82
+ modVideos.push(query);
83
+ else if (kind === 'audio')
84
+ modAudios.push(query);
85
+ else {
86
+ 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}')`);
87
+ }
88
+ }
89
+ // The chain's law: each mods source appends through its own
90
+ // Apply (Apply passes conditioning through, one mods input), in
91
+ // fixed order — pre-baked stems, the baked visual pack, then
92
+ // each baked audio pack.
93
+ const applyMods = (mods) => {
94
+ cond = g.node('MiniMaxH3RefModApply', {
95
+ conditioning: cond, mods, override: false, retention: 1,
96
+ curve_direction: 'constant', scramble_seed: -1,
97
+ curve_shape: 'linear', curve_value: 1,
98
+ }).out(0);
99
+ };
100
+ if (modStems.length > 0) {
101
+ const loaderInputs = { show_info: false };
102
+ for (let i = 0; i < REF_CAPS.refmods; i++) {
103
+ const stem = modStems[i];
104
+ loaderInputs[`mod_${i + 1}`] = stem === undefined ? '(none)' : stem;
105
+ loaderInputs[`strength_${i + 1}`] = 1;
106
+ loaderInputs[`copies_${i + 1}`] = 1;
107
+ }
108
+ applyMods(g.node('MiniMaxH3RefModsLoader', loaderInputs).out(0));
109
+ }
110
+ if (modImages.length > 0 || modVideos.length > 0) {
111
+ // One creator node stacks every visual ref of the seat into a
112
+ // single video-kind mod (the node's own grammar: stills into
113
+ // the refs_image autogrow container's grown slots, frame
114
+ // batches into refs_video's — DOTTED container.slot addressing,
115
+ // the r2v ref_images.ref_image_0 receipt; a BARE ref_image_1
116
+ // key is an undeclared input and phase 1 refuses it, the
117
+
118
+ // ref's basename, sanitized node-side — a data: upload chip
119
+ // has no basename, so a data-only seat names the generic
120
+ // 'mod'. save rides the node default (true) so the baked pack
121
+ // lands in the loader's dropdown for later reuse.
122
+ const firstVisual = (modImages[0] ?? modVideos[0]);
123
+ const nameBase = firstVisual.startsWith('data:') ? 'mod' : firstVisual.split(/[\\/]/).pop()?.replace(/\.[^.]+$/, '') ?? 'mod';
124
+ // THE STATED BAKE (study §5/§7.2; value-arms ARMs 13/14): the
125
+ // fidelity dials are DECLARED params (schema.ts, the refmod
126
+ // group) and ride the node verbatim. The fallbacks are the
127
+ // declared defaults verbatim — one owner, the schema.
128
+ const bakeMode = typeof p.refmod_mode === 'string' ? p.refmod_mode : 'Compressed Reference';
129
+ const bakePool = typeof p.refmod_pool === 'number' && Number.isFinite(p.refmod_pool) ? p.refmod_pool : 16;
130
+ const bakeIdentity = typeof p.refmod_identity === 'number' && Number.isFinite(p.refmod_identity) ? p.refmod_identity : 500;
131
+ const extractInputs = {
132
+ name: nameBase,
133
+ mode: bakeMode, concept_type: 'generic',
134
+ save: p.refmod_save !== false,
135
+ pool_h: bakePool, pool_w: bakePool, identity: bakeIdentity,
136
+
137
+ // (MiniMax-H3 VAE loader) or a standard VAE' — the engine
138
+ // refuses the extract at run time without one; both inputs
139
+ // are schema-optional, so no phase-1 judge can catch it).
140
+ // The family's own optimized H3 VAE rides (the int8-convrot
141
+ // video VAE, the same handle the film lane loads); no
142
+ // MINIMAX_H3_AV_ENCODER loader node exists in this engine's
143
+ // /object_info, so the standard-VAE input is THE wire.
144
+ vae: vaeVideo,
145
+ };
146
+ modImages.forEach((img, i) => {
147
+ extractInputs[`refs_image.ref_image_${i}`] = g.node('LoadImage', { image: img, upload: 'image' }).out(0);
148
+ });
149
+ modVideos.forEach((vid, i) => {
150
+ extractInputs[`refs_video.ref_video_${i}`] = g.node('GetVideoComponents', {
151
+ video: g.node('LoadVideo', { file: vid }).out(),
152
+ }).out(0);
153
+ });
154
+ applyMods(g.node('MiniMaxH3RefModExtract', extractInputs).out(0));
155
+ }
156
+ for (const src of modAudios) {
157
+ // Audio mods are their own extractor (AUDIO in, one mod out);
158
+ // one node per entry, voice-grade defaults, saved for reuse
159
+ // (a data: upload chip names the generic 'audio_mod').
160
+ // budget_policy + concept_type are REQUIRED bare combos in the
161
+ // engine's /object_info — no declared default, so no primed
162
+ // builder autofills them (the B7 wall refuses at compose) — the
163
+ // graph states the pack's own signature defaults
164
+ // (vendor/ComfyUI-MiniMaxH3Mod/nodes.py:2143: budget_policy
165
+ // 'error', concept_type 'voice').
166
+ applyMods(g.node('MiniMaxH3RefModAudioExtract', {
167
+ audio: g.node('LoadAudio', { audio: src }).out(),
168
+ audio_vae: vaeAudio,
169
+ name: src.startsWith('data:') ? 'audio_mod' : src.split(/[\\/]/).pop()?.replace(/\.[^.]+$/, '') ?? 'audio_mod',
170
+ budget_policy: 'error', concept_type: 'voice',
171
+ save: true,
172
+ }).out(0));
173
+ }
174
+ return cond;
175
+ }
176
+ //# sourceMappingURL=refmodBake.js.map
package/lib/repair.js CHANGED
@@ -1,21 +1,40 @@
1
- import { loadVideo, renderMaskedEditChain } from './chainEdit.js';
2
- import { assertGridLength } from './timelineContract.js';
3
- /** The SAM3 checkpoint the mask family declares + hash-pins
4
- * (packages/models/mask/src/index.ts — auto-provisioned; the track
5
- * card's own SAM3_CKPT constant is the same file). */
6
- const SAM3_CKPT = 'sam3.1_multiplex_fp16.safetensors';
1
+ import { contexMaskedTarget, loadVideo, renderMaskedEditChain, resolvePlanTier, sheetRefSlots } from './chainEdit.js';
2
+ import { assertGridLength, resolveCarryOverlap } from './timelineContract.js';
7
3
  /** The repair entry's required seats (the reshoot idiom: an armed
8
- * doc with an empty seat refuses loud naming the seat). Two of the
9
- * three are text, not staged media — the loop still speaks the one
10
- * spelling so the refusal names the seat the same way the swap's
11
- * does. */
4
+ * doc with an empty seat refuses loud naming the seat). The third
5
+ * is staged media, not text — P0-2 (defect board row 2, the
6
+ * operator's contract "repair receives a mask and errors without
7
+ * one") killed the inline SAM3 manufacture: the mask is RECEIVED as
8
+ * ONE staged PNG, and the refusal names the seat the same way the
9
+ * swap's does. */
12
10
  const REQUIRED_SEATS = [
13
11
  ['source_clip', 'the clip whose region is repaired — ONE staged leaf: the VHS window loader + the core LoadVideo read it by staged name, and the timeline reads it back off the native VIDEO wire'],
14
12
  ['repair_prompt', 'the repair action text — what the masked region should become (the R2V prompt seat; agent-composed, user-confirmed)'],
15
- ['region_prompt', 'the free-text SAM3 detection target naming the region — "hands", "a person", "a face" are param VALUES, never card kinds (the region-agnostic law)'],
13
+ ['mask', "ONE staged PNG the repair RECEIVES (the operator's contract, defect board row 2: a repair errors without one) — the track run's pixel-max union is the recommended bridge; the chain resizes it to its own geometry in-graph, prose manufactures nothing"],
16
14
  ];
17
- const num = (p, k, d) => typeof p[k] === 'number' ? p[k] : d;
18
- const str = (p, k) => typeof p[k] === 'string' ? p[k] : '';
15
+ /** Reads one required seat NARROWED by its own refusal — the seat
16
+ * is a string or the door never composes (no fallback arm exists:
17
+ * a validated seat re-read through a forgiving helper would be a
18
+ * second, weaker validator below the law — a silent error). */
19
+ const requiredSeat = (entry, seat, what) => {
20
+ const v = entry[seat];
21
+ if (typeof v !== 'string' || v.trim() === '') {
22
+ throw new Error(`h3-timeline repair: '${seat}' names no media — ${what}; a repair needs all three seats bound (source_clip, repair_prompt, mask)`);
23
+ }
24
+ return v;
25
+ };
26
+ /** Reads one optional number seat: absent falls to the documented
27
+ * default; a stated non-number REFUSES — a defaulting fallback would
28
+ * swallow a bypassed door's wrong-typed value as a silent error. */
29
+ const statedNumber = (p, k, d) => {
30
+ const v = p[k];
31
+ if (v === undefined)
32
+ return d;
33
+ if (typeof v !== 'number' || !Number.isFinite(v)) {
34
+ throw new Error(`h3-timeline repair: '${k}' is stated as ${JSON.stringify(v)} — a number seat carries a number (absent falls to ${d}); a wrong-typed value never silently defaults`);
35
+ }
36
+ return v;
37
+ };
19
38
  /** The repair renderer: validates the bound entry, then composes the
20
39
  * masked second-pass chain. Like the swap, the film path never
21
40
  * reaches here (the card branches on a non-empty repair bag, refuses
@@ -28,22 +47,23 @@ const str = (p, k) => typeof p[k] === 'string' ? p[k] : '';
28
47
  * @param g the run's graph builder
29
48
  * @param runId the run tree's id (the assemble filename rides it) */
30
49
  export function renderH3Repair(entry, p, facts, g, runId) {
31
- for (const [seat, what] of REQUIRED_SEATS) {
32
- const v = entry[seat];
33
- if (typeof v !== 'string' || v.trim() === '') {
34
- throw new Error(`h3-timeline repair: '${seat}' names no media — ${what}; a repair needs all three seats bound (source_clip, repair_prompt, region_prompt)`);
35
- }
36
- }
37
- const denoise = num(entry, 'denoise', 0.32);
50
+ // NO FALLBACK READS: every required seat narrows through its own
51
+ // refusal; every optional number refuses a wrong-typed stated
52
+ // value instead of silently defaulting (the schema walk types
53
+ // every lawful doc — a wrong-typed value means a bypassed door).
54
+ const sourceClipSeat = requiredSeat(entry, 'source_clip', REQUIRED_SEATS[0][1]);
55
+ const repairPromptSeat = requiredSeat(entry, 'repair_prompt', REQUIRED_SEATS[1][1]);
56
+ const maskSeat = requiredSeat(entry, 'mask', REQUIRED_SEATS[2][1]);
57
+ const denoise = statedNumber(entry, 'denoise', 0.32);
38
58
  if (denoise >= 1) {
39
59
  throw new Error(`h3-timeline repair: denoise ${denoise} >= 1 — a masked second pass is a refine, never a re-render (the partial-denoise window is 0.05–0.50; denoise 1 would boil the held region into a new take — that is a reshoot, and the reshoot door exists)`);
40
60
  }
41
- const seed = num(entry, 'seed', 0);
42
- const steps = num(entry, 'steps', 6);
43
- const clipSeconds = num(entry, 'clip_seconds', 6);
44
- const resolution = str(entry, 'resolution') || '736p';
45
- const windowStart = num(entry, 'window_start', 0);
46
- const windowLength = num(entry, 'window_length', 0);
61
+ const seed = statedNumber(entry, 'seed', 0);
62
+ const steps = statedNumber(entry, 'steps', 6);
63
+ const clipSeconds = statedNumber(entry, 'clip_seconds', 6);
64
+ const resolution = resolvePlanTier(entry, p);
65
+ const windowStart = statedNumber(entry, 'window_start', 0);
66
+ const windowLength = statedNumber(entry, 'window_length', 0);
47
67
  // No silent clamps (the no-silent-repair law): a negative window
48
68
  // is a caller bug — refuse loud, never round it into a render.
49
69
 
@@ -60,22 +80,7 @@ export function renderH3Repair(entry, p, facts, g, runId) {
60
80
  // ── the staged media: the WINDOW loader (cap + skip on the same
61
81
  // VHS seat, so frames and audio stay in sync) and the inline
62
82
  // per-frame SAM3 mask that replaces the swap's staged PNG ──
63
- const [srcFrames, srcAudio] = loadVideo(g, str(entry, 'source_clip'), Math.round(windowLength), Math.round(windowStart));
64
- const scaled = g.node('ImageScaleToMaxDimension', {
65
- image: srcFrames, upscale_method: 'area', largest_size: 1008,
66
- }).out(0);
67
- const sam = g.node('CheckpointLoaderSimple', { ckpt_name: SAM3_CKPT });
68
- const regionCond = g.node('CLIPTextEncode', {
69
- text: str(entry, 'region_prompt'), clip: sam.out(1),
70
- }).out(0);
71
- const track = g.node('SAM3_VideoTrack', {
72
- images: scaled, model: sam.out(0), conditioning: regionCond,
73
- detection_threshold: num(entry, 'detection_threshold', 0.5),
74
- max_objects: 0, detect_interval: 1,
75
- }).out(0);
76
- const regionMasks = g.node('SAM3_TrackToMask', {
77
- track_data: track, object_indices: '',
78
- }).out(0);
83
+ const [srcFrames, srcAudio] = loadVideo(g, sourceClipSeat, Math.round(windowLength), Math.round(windowStart));
79
84
  // picture_1 for the plan head: the window's own first frame. The
80
85
  // plan node REQUIRES a picture (its describer vocabulary); the
81
86
  // repair's "replacement" is the source's own person, so the
@@ -88,16 +93,16 @@ export function renderH3Repair(entry, p, facts, g, runId) {
88
93
  renderMaskedEditChain(g, {
89
94
  p, facts,
90
95
  clipSeconds,
91
- overlapFrames: num(entry, 'overlap_frames', 39),
96
+ overlapFrames: resolveCarryOverlap(entry),
92
97
  resolution, seed, steps,
93
98
  roles: '',
94
- sourceClip: str(entry, 'source_clip'),
99
+ sourceClip: sourceClipSeat,
95
100
  windowStart,
96
101
  picture1: anchorFrame,
97
102
  srcFrames, srcAudio,
98
103
  // the ignored literal fallback — the plan node's WINDOW-RE-SLICED
99
104
  // shots ride plan_json_input (the repair's geometry law)
100
- planJson: JSON.stringify({ shots: [{ id: 'repair', prompt: str(entry, 'repair_prompt') }] }),
105
+ planJson: JSON.stringify({ shots: [{ id: 'repair', prompt: repairPromptSeat }] }),
101
106
  planFromSource: true,
102
107
  denoise,
103
108
  assemble: {
@@ -107,56 +112,58 @@ export function renderH3Repair(entry, p, facts, g, runId) {
107
112
  audioSource: 'source',
108
113
  filename: `${runId}/repair`,
109
114
  },
110
- body: ({ cur, clip, vaeVideo, vaeAudio, mutedChainAudio, sliceAudio }) => {
115
+ body: ({ cur, clip, vaeVideo, vaeAudio, mutedChainAudio, sliceAudio, refImages }) => {
116
+ // ── P0-2 (defect board row 2): the mask is RECEIVED, never
117
+ // manufactured — the inline SAM3 prose door (and its F7
118
+ // per-scene slice of a TRACKED stack) died with the contract.
119
+ // The static arm verbatim (the edit door's own F3-16 cure):
120
+ // the staged PNG's own shape is the TRACK's shape, not the
121
+ // chain's — resize to the plan geometry in-graph, never trust
122
+ // the file. The recommended bridge (the track run's pixel-max
123
+ // union) arrives already grown; prose manufactures nothing. ──
124
+ const raw = g.node('LoadImage', { image: maskSeat }).out(0);
111
125
 
112
- // parity. The plan head segments the window engine-side (the
113
- // swap's own choreography — planFromSource rides the same
114
- // seat); the loop drives the scenes; ChainAssemble stitches.
115
- // The one wire that never segmented was THE MASK: the tracked
116
- // stack (the whole window's timeline) fed every scene whole,
117
- // so a multi-scene repair saw rows it did not own (the F7
118
- // burn: one oversized shot, the mask leg loop-posture-only).
119
- // MiniMaxH3ContexLoopMaskSlice selects the current scene's
120
- // interval off the loop state — the tracked mask stack sliced
121
- // to each scene's frame range, BEFORE the grow (the
122
- // extension's own posture: slice, then Grow Mask). A
123
- // single-scene window slices its own whole interval — the
124
- // cure is posture-uniform, never a branch. ──
125
- const sceneMask = g.node('MiniMaxH3ContexLoopMaskSlice', {
126
- state: cur.out(0), mask: regionMasks, source_fps: 24,
127
- });
128
- const grown = g.node('GrowMaskWithBlur', {
129
- mask: sceneMask.out(0), expand: Math.round(num(entry, 'mask_grow', 16)),
130
- tapered_corners: true, blur_radius: 0,
126
+ // `ImageResize` — a class NO engine build owns (1817 classes,
127
+ // none so named; the refusal landed at compose time, after the
128
+ // authoring pass). Core `ImageScale` is the exact-fit resize
129
+ // the law always meant: it resizes to width/height with no
130
+ // proportion-keeping arm — the mask fills the chain canvas.
131
+
132
+ // plane and the conversion rides LAST — ImageScale is
133
+ // IMAGE→IMAGE, and a MASK socket fed an IMAGE is the
134
+ // prompt-validation death the engine serves after compose
135
+ // passes. Same two nodes; the ORDER is the law.
136
+ const fitted = g.node('ImageScale', {
137
+ image: raw, width: cur.out(8), height: cur.out(9),
138
+ upscale_method: 'bilinear', crop: 'disabled',
139
+ }).out(0);
140
+ const editMask = g.node('ImageToMask', {
141
+ image: fitted, channel: 'red',
131
142
  }).out(0);
132
143
  // ── the masked second-pass body: NO still, NO mannequin — the
133
144
  // source clip rides its own ref_video seat (the identity
134
145
  // anchor of a repair is the person already in the frame — the
135
146
  // zero-new-pixels law) ──
136
147
  const r2v = g.node('MiniMaxH3ReferenceToVideo', {
137
- prompt: str(entry, 'repair_prompt'),
148
+ prompt: repairPromptSeat,
138
149
  width: cur.out(8), height: cur.out(9), length: cur.out(6),
139
150
  ref_image_size: 'match',
140
151
  clip, vae: vaeVideo, audio_vae: vaeAudio,
141
152
  'ref_videos.ref_video_0': srcFrames,
142
153
  'ref_video_audios.ref_video_audio_0': mutedChainAudio,
154
+ // THE SHEET (P0-1): repair mounts NO image anchor — the
155
+ // declared ref_images ride from slot 0, stated exactly as
156
+ // the gen door states them (an input slot, nothing more).
157
+ ...sheetRefSlots(refImages, 0),
143
158
  });
144
159
  const slice = g.node('H3SourceSlice', {
145
160
  source_fps: 24, crop: 'center',
146
161
  state: cur.out(0), latent: r2v.out(1),
147
162
  audio_vae: vaeAudio, source_frames: srcFrames, source_audio: sliceAudio,
148
163
  });
149
- const edit = g.node('MiniMaxH3FantasticVideoEditLatent', {
150
- grow: 0, keep_audio: true, megapixels: 0,
151
- vae: vaeVideo, images: slice.out(0), mask: grown,
152
- audio_vae: vaeAudio, audio: slice.out(1),
153
- }).out(0);
154
- const target = g.node('MiniMaxH3ContexMaskedTarget', {
155
- mask_meaning: 'white = generate',
156
- audio_mode: 'preserve source audio',
157
- mask_conversion: 'H3 exact (causal/token max)',
158
- target_latent: edit, mask: grown,
159
- }).out(0);
164
+ const target = contexMaskedTarget(g, { vaeVideo, vaeAudio }, {
165
+ frames: slice.out(0), audio: slice.out(1), mask: editMask, keepAudio: true,
166
+ });
160
167
  return { conditioning: r2v.out(0), targetLatent: target };
161
168
  },
162
169
  });
package/lib/reshoot.js CHANGED
@@ -1,3 +1,4 @@
1
+ import { outputNameTailOf } from './schema.js';
1
2
  /** The pack's clip-normalization node (the official chain's first
2
3
  * stage — resamples to 24 fps, snaps the frame count to H3's 17k+5
3
4
  * grid, centre-crops to the requested aspect at the pixel budget).
@@ -87,16 +88,62 @@ export const RESHOOT_DIAL_BOUNDS = {
87
88
  dolly: [0.1, 3],
88
89
  zoom: [20, 120],
89
90
  pan: [-1, 1],
90
- strength: [0.5, 1],
91
+
92
+ // floor — under 0.8 the warp is followed less and the model's prior
93
+ // rebuilds the frame (the F33 anime drift); the old 0.5 floor left the
94
+ // drift reachable from [0.5, 0.8).)
95
+ strength: [0.8, 1],
91
96
  depth_ratio: [1.5, 1000],
92
97
  };
93
- const banded = (e, key, fallback) => {
94
- const v = num(e, key, fallback);
95
- const [lo, hi] = RESHOOT_DIAL_BOUNDS[key];
96
- if (v < lo || v > hi) {
97
- throw new Error(`h3 re-shoot: the bag's ${key} dial is ${v} — outside the camera band [${lo}, ${hi}] (the card's Reshoot rows state the same bounds); refuse ahead of the engine, never a widget 400`);
98
+ /** The dial defaults (the OFFICIAL app's own slider posture — the
99
+ * identity camera is not a re-shoot, so absent dials never fall to
100
+ * zero). */
101
+ const DIAL_DEFAULTS = {
102
+ orbit: RESHOOT_DEFAULT_POSE.orbit,
103
+ tilt: RESHOOT_DEFAULT_POSE.tilt,
104
+ dolly: 1.0,
105
+ zoom: 50,
106
+ pan: 0,
107
+ strength: 0.8,
108
+ depth_ratio: 6,
109
+ };
110
+
111
+
112
+
113
+
114
+
115
+ const DIAL_UNITS = {
116
+ orbit: 'degrees of orbit (negative orbits left, positive right; ±45 tested)',
117
+ tilt: 'degrees of elevation (positive looks down; below −20 is the weak direction)',
118
+ dolly: 'camera distance where 1.0 keeps the source distance (below 1 dollies in)',
119
+ zoom: 'lens field of view in degrees (50 = a normal lens; NOT a multiplier)',
120
+ pan: 'vertical framing shift as a fraction of frame height (the camera does not move)',
121
+ strength: 'CrossView LoRA strength (the official tested band; under 0.8 the prior rebuilds the frame)',
122
+ depth_ratio: 'scene depth as a far/near ratio (2.5–4 close-ups, 4–8 mid, 8–16 wide)',
123
+ };
124
+ /** THE ALL-DIALS REFUSAL (the F13 cure): the compose iterates every
125
+ * dial anyway — the refusal reports them the same way, each with its
126
+ * band AND its unit, so ONE round trip states the whole camera. The
127
+ * old per-dial throw burned five presses on one bag entry (zoom,
128
+ * dolly, pan, strength, depth_ratio — each refusal naming exactly
129
+ * one dial and nothing else).
130
+ * @param e the bag's entry (the dial seat values, loose)
131
+ * @returns every dial's in-band value, keyed by wire name */
132
+ const bandedAll = (e) => {
133
+ const bad = [];
134
+ const dials = {};
135
+ for (const key of Object.keys(RESHOOT_DIAL_BOUNDS)) {
136
+ const v = num(e, key, DIAL_DEFAULTS[key]);
137
+ dials[key] = v;
138
+ const [lo, hi] = RESHOOT_DIAL_BOUNDS[key];
139
+ if (v < lo || v > hi) {
140
+ bad.push(`${key} ${v} is outside the camera band [${lo}, ${hi}] — ${DIAL_UNITS[key]}`);
141
+ }
98
142
  }
99
- return v;
143
+ if (bad.length > 0) {
144
+ throw new Error(`h3 re-shoot: the bag's camera dials are out of band — ${bad.join('; ')} (the card's Reshoot rows state the same bounds; refused ahead of the engine, never a widget 400 — every offender named in one pass)`);
145
+ }
146
+ return dials;
100
147
  };
101
148
  /** The bag's first (and only — max_stack 1) entry, typed loose. */
102
149
  const bagEntry = (p) => {
@@ -123,14 +170,15 @@ const bagEntry = (p) => {
123
170
  * band is 0.5–1, served default 0.8). */
124
171
  export function readReshootKnobs(p) {
125
172
  const e = bagEntry(p) ?? {};
173
+ const dials = bandedAll(e);
126
174
  return {
127
- orbit: banded(e, 'orbit', RESHOOT_DEFAULT_POSE.orbit),
128
- tilt: banded(e, 'tilt', RESHOOT_DEFAULT_POSE.tilt),
129
- dolly: banded(e, 'dolly', 1.0),
130
- zoom: banded(e, 'zoom', 50),
131
- pan: banded(e, 'pan', 0),
132
- strength: banded(e, 'strength', 0.8),
133
- depthRatio: banded(e, 'depth_ratio', 6),
175
+ orbit: dials.orbit,
176
+ tilt: dials.tilt,
177
+ dolly: dials.dolly,
178
+ zoom: dials.zoom,
179
+ pan: dials.pan,
180
+ strength: dials.strength,
181
+ depthRatio: dials.depth_ratio,
134
182
  smoothDepth: e.smooth_depth === true,
135
183
  invertDepth: e.invert_depth === true,
136
184
  };
@@ -287,13 +335,17 @@ export function buildH3Reshoot(p, g, windowFrames, runId) {
287
335
  batch_index: 0,
288
336
  length: 1,
289
337
  }).out(0);
338
+
339
+ // press): the re-shoot's DELIVERED plates are BORN named
340
+ // (`reshoot_warp_<slug>` / `reshoot_orbit_<slug>`) — the same
341
+ // stem on both faces of the one re-shoot.
290
342
  const plateSave = g.node('SaveImage', {
291
343
  images: plate,
292
- filename_prefix: `${runId}/reshoot_warp`,
344
+ filename_prefix: `${runId}/reshoot_warp${outputNameTailOf(p)}`,
293
345
  }).out(0);
294
346
  const orbitSave = g.node('SaveImage', {
295
347
  images: warpNode.out(1),
296
- filename_prefix: `${runId}/reshoot_orbit`,
348
+ filename_prefix: `${runId}/reshoot_orbit${outputNameTailOf(p)}`,
297
349
  }).out(0);
298
350
  return {
299
351
  refFrames: source,
package/lib/schema.d.ts CHANGED
@@ -5,6 +5,22 @@ export type Family = (typeof FAMILIES)[number];
5
5
  export declare const wireList: typeof normalizeDeclaredRefs;
6
6
  export declare const H3_RECOMMENDED_SAMPLERS: readonly ["euler", "euler_cfg_pp", "euler_ancestral", "dpmpp_2m", "dpmpp_2m_sde", "heun", "res_multistep", "res_multistep_cfg_pp", "er_sde", "seeds_2", "seeds_3"];
7
7
  export declare const JSON_ARRAY_PARAMS: readonly ["calls", "audio_clips", "keyframes"];
8
+ /** The fps rail's own bounds, one home: the row declares them and the
9
+ * internal seconds rail derives its own bounds from them (see
10
+ * fps_seconds) — a second rail must never invent a rival bound. */
11
+ export declare const FPS_RAIL_MIN = 1;
12
+ export declare const FPS_RAIL_MAX = 120;
13
+ /** The refinement window's DECLARED default — one home for the seat,
14
+ * the schema walk, and every wall/receipt that judges the unstated
15
+ * rider (the SOTA plan's researched 0.30–0.35 band; 1.0 is the
16
+ * taomate full-denoise mechanic, opt-in). */
17
+ export declare const REFINE_DENOISE_DEFAULT = 0.35;
18
+ /** THE OUTPUT-NAME SLUG LAW (the file-plane seat on the carrier
19
+ * below): a filename segment and nothing else — the stem lands
20
+ * inside a SaveVideo / SaveImage prefix, so no space, slash, dot,
21
+ * or case may ride it. Shared by the carrier (the walk's boundary
22
+ * refusal) and the compose tail helper at the carrier's foot. */
23
+ export declare const OUTPUT_NAME_SLUG_RE: RegExp;
8
24
  export declare const paramSchema: z<Schemastery.ObjectS<NoInfer<{
9
25
  image: z<string, string, "plain">;
10
26
  last_frame: z<string, string, "plain">;
@@ -70,6 +86,7 @@ export declare const paramSchema: z<Schemastery.ObjectS<NoInfer<{
70
86
  k: z<number, number, "plain">;
71
87
  noise_seed: z<number, number, "plain">;
72
88
  fps_seconds: z<number, number, "plain">;
89
+ output_name: z<string, string, "plain">;
73
90
  interp_switch: z<boolean, boolean, "plain">;
74
91
  sharpen_switch: z<boolean, boolean, "plain">;
75
92
  sla_switch: z<boolean, boolean, "plain">;
@@ -139,11 +156,21 @@ export declare const paramSchema: z<Schemastery.ObjectS<NoInfer<{
139
156
  k: z<number, number, "plain">;
140
157
  noise_seed: z<number, number, "plain">;
141
158
  fps_seconds: z<number, number, "plain">;
159
+ output_name: z<string, string, "plain">;
142
160
  interp_switch: z<boolean, boolean, "plain">;
143
161
  sharpen_switch: z<boolean, boolean, "plain">;
144
162
  sla_switch: z<boolean, boolean, "plain">;
145
163
  image_name: z<string, string, "plain">;
146
164
  }>>, "plain">;
165
+ /** The composed prefix tail for a doc's output_name — `_<slug>` when
166
+ * spelled, '' when absent. The DELIVERABLE prefix sites thread this
167
+ * (the film `h3_t4_film`, the extend film `extend_film`, the
168
+ * re-shoot plates `reshoot_warp` / `reshoot_orbit`); a stem that
169
+ * escaped the boundary walk (a legacy draft, a hand-built doc)
170
+ * refuses HERE loud, naming the law — a bad stem must never reach
171
+ * a filename. An empty string is the label seam's silence law:
172
+ * no stem, no tail, no refusal. */
173
+ export declare function outputNameTailOf(p: Record<string, unknown>): string;
147
174
  /** Schemastery objects are lenient (unknown/missing keys ride); the
148
175
  * family-admission laws are the renderer's own validators, ported:
149
176
  * unknown variant + family-conditional key admission on EXPLICIT
@@ -165,6 +192,12 @@ export declare const refinePlaneSchema: z<Schemastery.ObjectS<NoInfer<{
165
192
  }>>, Schemastery.ObjectT<NoInfer<{
166
193
  [k: string]: z;
167
194
  }>>, "plain">;
195
+ /** The wire tolerance for interpolate_enabled: the bench add-door's
196
+ * "false"/"true" string literal folds to a boolean before the walk;
197
+ * any other string refuses loud. Booleans and every other key pass
198
+ * verbatim.
199
+ * @param raw the pre-walk params record
200
+ * @returns the record with interpolate_enabled narrowed to boolean */
168
201
  export declare const coerceWireBoolean: (raw: Record<string, unknown>) => Record<string, unknown>;
169
202
  /** THE PIN ROW SHAPE (one law, two seats): the doc walk and the compose
170
203
  * gate both run this BEFORE any placement math — a row must carry a
@@ -173,6 +206,15 @@ export declare const coerceWireBoolean: (raw: Record<string, unknown>) => Record
173
206
  * gate-and-walk wall pins them); placement and media existence stay
174
207
  * the compose gate's, which owns the doc's calls/windows. */
175
208
  export declare function assertKeyframeRowShape(rows: readonly unknown[]): void;
209
+ /** The compose-admission walk over a raw doc (the card gate's
210
+ * model_validator port): array and boolean wire tolerances restored,
211
+ * keyframe rows shape-judged, shot rows judged (per-call vocabulary,
212
+ * int spans, tiling, seam/grid/guide gates), the window family
213
+ * derived, and the family-conditional key gates run. A refusal names
214
+ * the row and the cure; a passing doc returns the walked params with
215
+ * the __steps_pinned/__shift_pinned stamps added.
216
+ * @param v the raw doc (absent = the fresh-card draft)
217
+ * @returns the walked params record the compose reads */
176
218
  export declare function schema(v: unknown): Record<string, unknown>;
177
219
  export declare const carrier: z<Schemastery.ObjectS<NoInfer<{
178
220
  image: z<string, string, "plain">;
@@ -239,6 +281,7 @@ export declare const carrier: z<Schemastery.ObjectS<NoInfer<{
239
281
  k: z<number, number, "plain">;
240
282
  noise_seed: z<number, number, "plain">;
241
283
  fps_seconds: z<number, number, "plain">;
284
+ output_name: z<string, string, "plain">;
242
285
  interp_switch: z<boolean, boolean, "plain">;
243
286
  sharpen_switch: z<boolean, boolean, "plain">;
244
287
  sla_switch: z<boolean, boolean, "plain">;
@@ -308,6 +351,7 @@ export declare const carrier: z<Schemastery.ObjectS<NoInfer<{
308
351
  k: z<number, number, "plain">;
309
352
  noise_seed: z<number, number, "plain">;
310
353
  fps_seconds: z<number, number, "plain">;
354
+ output_name: z<string, string, "plain">;
311
355
  interp_switch: z<boolean, boolean, "plain">;
312
356
  sharpen_switch: z<boolean, boolean, "plain">;
313
357
  sla_switch: z<boolean, boolean, "plain">;