@melite/models-h3 0.2.2-alpha → 0.3.0-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.
@@ -1,10 +1,27 @@
1
1
  import { deriveFamilyLane } from '@melite/contracts/familyLane';
2
+ /** The frames of generated context a carried seam contributes — the
3
+ * generation head a non-cut join rides (a carried window's authored
4
+ * span excludes it; its render includes it). */
2
5
  export const SEAM_OVERLAP_FRAMES = 22;
6
+ /** The window grid's floor and first rung: every legal length is BASE + STEP·k. */
3
7
  export const GRID_BASE_FRAMES = 22;
8
+ /** The window grid's rung spacing: legal lengths advance 17 frames per step. */
4
9
  export const GRID_STEP_FRAMES = 17;
10
+ /** The window grid's ceiling: no window renders more than 362 frames. */
5
11
  export const GRID_MAX_FRAMES = 362;
12
+ /** The generated-length residue: a carried window renders 17k + 22 ≡ 5
13
+ * (mod 17) frames — the "% 17 == 5" the engine's own refusals name. */
6
14
  export const GRID_REMAINDER = 5;
15
+ /** The conditioning image bus's slot count (bundle inputs 3–9). */
7
16
  export const IMAGE_BUS_SLOTS = 9;
17
+ /** The family's LAST-FRAME PICK spelling (one home, both readers —
18
+ * extend.ts's anchor and the seam's keyframe carry): a positive
19
+ * out-of-band batch index the engine clamps onto the clip's FINAL
20
+ * row (min(shape−1, index)) under every build; the negative
21
+ * spelling slices empty on the live estate and is banned
22
+ * family-wide. */
23
+ export const LAST_FRAME_BATCH_INDEX = 16384;
24
+ /** Per-media reference caps — the max stack each declared ref lane admits. */
8
25
  export const REF_CAPS = {
9
26
  images: 8,
10
27
  videos: 3,
@@ -14,6 +31,71 @@ export const REF_CAPS = {
14
31
  // the loader row the compose fills.
15
32
  refmods: 8,
16
33
  };
34
+ /** THE AV-CONTINUITY LAW, one TS home (defect board row 4, the
35
+ * "derive the carry value" rider). The engine's own vocabulary is
36
+ * AV_TRANSITION_CONTEXT_LENGTHS = (39, 90, 141, 192, 243)
37
+ * (vendor/comfyui_extensions/ComfyUI-MiniMaxH3-Context-Loop/
38
+ * contracts_v05.py:55); on a generated-audio carry join (the edit
39
+ * chain's own mode — context > 0) any other positive boundary
40
+ * refuses AT THE NODE, eight graphs deep
41
+ * (run-1f91718b7cde: "H3 AV generated-audio continuity requires an
42
+ * exact shared video/audio boundary: 39, 90, 141, 192, or 243
43
+ * context frames"). The compose door judges THIS vocabulary at zero
44
+ * GPU so no agent ever discovers it by a burned run; 0 (the cut
45
+ * join, carry: false — the engine's own "cut / independent" preset,
46
+ * contracts_v05.py:158-162) is the one legal value outside it. */
47
+ export const AV_CONTINUITY_OVERLAPS = [39, 90, 141, 192, 243];
48
+ /** The derived carry join (defect board row 4: "join with the same
49
+ * overlap" — the smallest legal boundary, the least context spent;
50
+ * the engine's own reference value and the chain's historical
51
+ * default, now DERIVED instead of typed). */
52
+ export const CARRY_JOIN_OVERLAP = 39;
53
+ /** The carry statement's admission (defect board row 4: "expose
54
+ * exactly one new concept — carry: true"). ABSENT = carry, THE
55
+ * DEFAULT — the gen seam's own law (docModel.ts: "'extend'
56
+ * (ABSENT = carry, THE DEFAULT)"): the film splits on its own
57
+ * timeline and every segment continues from the last frame of the
58
+ * previous. Stated false = the cut join (each segment stands
59
+ * alone; the engine's cut preset, context 0).
60
+ * @param entry the edit-bag entry carrying the carry seat
61
+ * @returns true when segments join with context carry */
62
+ export function entryCarries(entry) {
63
+ const raw = entry['carry'];
64
+ if (raw === undefined)
65
+ return true;
66
+ if (typeof raw === 'boolean')
67
+ return raw;
68
+ throw new Error(`h3-timeline edit: carry must be a boolean (true = continue each segment from the last frame of the previous; false = cut the joins) — saw ${JSON.stringify(raw)}`);
69
+ }
70
+ /** THE CARRY-OVERLAP RESOLVER (defect board row 4 — the door the
71
+ * operator asked for five times): the join boundary is DERIVED from
72
+ * the engine's AV-continuity vocabulary, never hand-typed. Unstated
73
+ * → the derived 39 (carry on) or 0 (carry: false); an explicitly
74
+ * stated overlap_frames — the expert override, served on AUTHORED
75
+ * seams' context_length (the plan head itself carries only the
76
+ * AV-legal 39; see chainEdit's planOverlapFeed) — must be 0 or one
77
+ * of the five legal boundaries and REFUSES HERE, at the compose
78
+ * door, quoting the engine's law and naming the stated value, so
79
+ * the run-1f91718b7cde class (a boundary typed legal-looking,
80
+ * refused eight nodes deep) is dead at zero GPU.
81
+ * @param entry the edit-bag entry (overlap_frames / carry seats)
82
+ * @returns the join boundary in frames: 0, 39, 90, 141, 192 or 243 */
83
+ export function resolveCarryOverlap(entry) {
84
+ const stated = entry['overlap_frames'];
85
+ if (stated === undefined || stated === '')
86
+ return entryCarries(entry)
87
+ ? CARRY_JOIN_OVERLAP
88
+ : 0;
89
+ const n = typeof stated === 'number' ? stated : Number(stated);
90
+ if (!Number.isFinite(n) || Math.round(n) !== n) {
91
+ throw new Error(`h3-timeline edit: overlap_frames must be a whole number of frames — saw ${JSON.stringify(stated)}`);
92
+ }
93
+ if (n === 0 || AV_CONTINUITY_OVERLAPS.includes(n))
94
+ return n;
95
+ throw new Error(`h3-timeline edit: overlap_frames ${n} is not a boundary the engine accepts — H3 AV generated-audio continuity requires an exact shared video/audio boundary: 39, 90, 141, 192, or 243 frames on an AUTHORED seam (0 = the cut join, carry: false — authored windows only); run-1f91718b7cde refused this eight nodes deep. Leave overlap_frames unstated and carry: true (the default) derives the join — never type a boundary`);
96
+ }
97
+
98
+
17
99
 
18
100
 
19
101
 
@@ -25,6 +107,11 @@ export const REF_CAPS = {
25
107
  export function isMediaRef(v) {
26
108
  return v.startsWith('$') || v.startsWith('data:') || v.includes('/') || /\.[A-Za-z0-9]+$/.test(v);
27
109
  }
110
+ /** The context frames a seam carries: 0 for the cut join, the
111
+ * SEAM_OVERLAP_FRAMES generation head for any other transition
112
+ * (unstated included — carry is the default).
113
+ * @param transition the seam a call states (undefined = carry)
114
+ * @returns the join's context overlap in frames */
28
115
  export function transitionOverlap(transition) {
29
116
  return transition === 'cut' ? 0 : SEAM_OVERLAP_FRAMES;
30
117
  }
@@ -47,6 +134,14 @@ export function transitionOverlap(transition) {
47
134
 
48
135
 
49
136
  export const DOC_FPS_DEFAULT = 24;
137
+ /** The doc's LENGTH row default — the schema row's own (56f, the
138
+ * engine grid's design window 22+17·2), the same seed the walk
139
+ * fills for span-less calls. One owner, the same law as
140
+ * DOC_FPS_DEFAULT: the studio's axis fallback reads THIS, never a
141
+ * second literal (the D-19 cure retired the `: 1` collapse — an
142
+ * empty-calls axis books the doc's own plan floor, never a
143
+ * 1-frame sliver strip). */
144
+ export const DOC_LENGTH_DEFAULT = 56;
50
145
 
51
146
 
52
147
 
@@ -154,13 +249,27 @@ export function deriveWindowFamily(raw) {
154
249
  // (the run-899a8448 disease).
155
250
  return deriveFamilyLane(FAMILY_LAW, raw);
156
251
  }
252
+ /** A span's join overlap — transitionOverlap over the span's own seam.
253
+ * @param span the authored window
254
+ * @returns the window's context overlap in frames */
157
255
  export function spanOverlap(span) {
158
256
  return transitionOverlap(span.transition);
159
257
  }
258
+ /** The window's render length on the engine grid: the span plus its
259
+ * carry, snapped to 22+17k inside [22,362]. Off-grid spans snap;
260
+ * doors that must refuse use assertSpanGrid instead.
261
+ * @param span the authored window
262
+ * @param carry the seam overlap the window rides (0 for first/cut)
263
+ * @returns the grid-legal generated length in frames */
160
264
  export function spanStanzaFrames(span, carry = 0) {
161
265
  const k = Math.round((span.end - span.start + carry - GRID_BASE_FRAMES) / GRID_STEP_FRAMES);
162
266
  return Math.min(GRID_MAX_FRAMES, Math.max(GRID_BASE_FRAMES, GRID_BASE_FRAMES + GRID_STEP_FRAMES * k));
163
267
  }
268
+ /** Compute a carried window's grid geometry without judging it: the
269
+ * generated start, the snapped length, and the neighboring legal ends.
270
+ * @param span the authored carried window
271
+ * @param carry the seam overlap (the SEAM_OVERLAP_FRAMES default)
272
+ * @returns the CarriedSpanGrid for the window */
164
273
  export function carriedSpanGrid(span, carry = SEAM_OVERLAP_FRAMES) {
165
274
  const generatedStart = span.start - carry;
166
275
  const requestedLength = span.end - span.start + carry;
@@ -178,6 +287,14 @@ export function carriedSpanGrid(span, carry = SEAM_OVERLAP_FRAMES) {
178
287
  upperEnd: endAt(upperIndex),
179
288
  };
180
289
  }
290
+ /** The carried window's admission gate: the snapped grid length must
291
+ * equal the requested span+carry exactly; anything else refuses loud
292
+ * naming the authored range, the snapped range, and the legal
293
+ * neighboring end frames.
294
+ * @param span the authored carried window
295
+ * @param where the refusal's voice (the calling door's name)
296
+ * @param carry the seam overlap (the SEAM_OVERLAP_FRAMES default)
297
+ * @returns the grid-legal generated length in frames */
181
298
  export function assertCarriedSpanGrid(span, where, carry = SEAM_OVERLAP_FRAMES) {
182
299
  const grid = carriedSpanGrid(span, carry);
183
300
  const requestedLength = span.end - span.start + carry;
@@ -197,10 +314,17 @@ export function assertCarriedSpanGrid(span, where, carry = SEAM_OVERLAP_FRAMES)
197
314
  * quotient to milliseconds before it rides the wire, so every
198
315
  * consumer that needs the value the graph will actually carry (the
199
316
  * schema's own rail bounds, the mix ledger) books through here —
200
- * never a second copy of the rounding. */
317
+ * never a second copy of the rounding.
318
+ * @param lengthFrames the window's generated length
319
+ * @param fps the doc's playback clock
320
+ * @returns the length in seconds, rounded to milliseconds */
201
321
  export function bookSeconds(lengthFrames, fps) {
202
322
  return Math.round((lengthFrames / fps) * 1000) / 1000;
203
323
  }
324
+ /** The nearest legal 22+17k length (round to the rung, clamp into
325
+ * [22,362]) — the "nearest legal" value refusal voices quote.
326
+ * @param length the requested length in frames
327
+ * @returns the nearest grid-legal length */
204
328
  export function gridSnap(length) {
205
329
  const k = Math.round((length - GRID_BASE_FRAMES) / GRID_STEP_FRAMES);
206
330
  return Math.min(GRID_MAX_FRAMES, Math.max(GRID_BASE_FRAMES, GRID_BASE_FRAMES + GRID_STEP_FRAMES * k));
@@ -208,13 +332,20 @@ export function gridSnap(length) {
208
332
  /** THE GRID PREDICATE, one owner: a length the engine can render is
209
333
  * 22+17k inside [22,362]. Every refusal door asks this question, so
210
334
  * knob pins, single windows, cut windows, and carried windows cannot
211
- * drift into different laws. */
335
+ * drift into different laws.
336
+ * @param length the candidate length in frames
337
+ * @returns true when length is 22+17k inside [22,362] */
212
338
  export function isGridLength(length) {
213
339
  return Number.isInteger(length) &&
214
340
  length >= GRID_BASE_FRAMES &&
215
341
  length <= GRID_MAX_FRAMES &&
216
342
  (length - GRID_BASE_FRAMES) % GRID_STEP_FRAMES === 0;
217
343
  }
344
+ /** The grid admission gate: a non-number or off-grid length refuses
345
+ * naming the nearest legal value; a legal length passes verbatim.
346
+ * @param length the value under admission (a number is required)
347
+ * @param where the refusal's voice (the calling door's name)
348
+ * @returns the length, verbatim */
218
349
  export function assertGridLength(length, where) {
219
350
  if (typeof length !== 'number' || !isGridLength(length)) {
220
351
  const nearest = typeof length === 'number' && Number.isFinite(length)
@@ -230,6 +361,180 @@ export function assertGridLength(length, where) {
230
361
  * seam after the first carries (the swap's clip law, shared with the
231
362
  * extend's window composition). */
232
363
  export const CONTEXT_OVERLAP_FRAMES = 39;
364
+
365
+
366
+
367
+
368
+
369
+
370
+
371
+
372
+
373
+
374
+
375
+
376
+
377
+
378
+
379
+
380
+
381
+ /** Is this window's seam a carried join? Index-aware — index 0 is
382
+ * always a first window (no carry), and a 'cut' seam never
383
+ * carries.
384
+ * @param index the window's position in the calls array (0-based)
385
+ * @param call the window's own row (its transition seat)
386
+ * @returns true when the seam rides the carry join */
387
+ export function isCarriedShape(index, call) {
388
+ return index > 0 && transitionOverlap(call.transition) > 0;
389
+ }
390
+ /** Is this authored LENGTH legal for the window's shape? A carried
391
+ * window rides the 17k step (content + 22f carry head ≤ 362); a
392
+ * first/cut window rides the 22+17k grid.
393
+ * @param length the authored length in frames
394
+ * @param carried true when the window is a carried join
395
+ * @returns true when the shape's own grid admits the length */
396
+ export function isLegalCallLength(length, carried) {
397
+ if (carried) {
398
+ return Number.isInteger(length) && length >= GRID_STEP_FRAMES &&
399
+ length + SEAM_OVERLAP_FRAMES <= GRID_MAX_FRAMES && length % GRID_STEP_FRAMES === 0;
400
+ }
401
+ return isGridLength(length);
402
+ }
403
+ /** The splice frame for a split where BOTH halves must be legal —
404
+ * the gesture's frame when it already qualifies, else the nearest
405
+ * one that does. NULL when no interior frame qualifies (the §0.5
406
+ * fence): a window at its shape's floor has no legal split at all
407
+ * — the caller refuses loud, never repairs.
408
+ * @param start the containing window's first frame
409
+ * @param end the containing window's end frame
410
+ * @param leftCarried whether the left half keeps the carried shape
411
+ * @param rightCarried whether the right half takes the carried shape
412
+ * @param gesture the frame the split was asked at
413
+ * @returns the legal frame nearest the gesture, or null */
414
+ export function snapSplitFrame(start, end, leftCarried, rightCarried, gesture) {
415
+ let best = null;
416
+ let bestDistance = Number.POSITIVE_INFINITY;
417
+ for (let frame = start + 1; frame < end; frame++) {
418
+ if (!isLegalCallLength(frame - start, leftCarried))
419
+ continue;
420
+ if (!isLegalCallLength(end - frame, rightCarried))
421
+ continue;
422
+ const distance = Math.abs(frame - gesture);
423
+ if (distance < bestDistance) {
424
+ bestDistance = distance;
425
+ best = frame;
426
+ }
427
+ }
428
+ return best;
429
+ }
430
+ /** The seam toggle's re-frame: the 22-frame carry moves from the
431
+ * generation head to (or from) the authored span. A first window
432
+ * has no carry either way, so its toggle never moves frames.
433
+ * @param call the window row the toggle re-frames
434
+ * @param index the window's position in the calls array (0-based)
435
+ * @param next the seam state after the toggle
436
+ * @returns the window's re-framed end frame */
437
+ export function reflowSeamSpan(call, index, next) {
438
+ const wasCarried = isCarriedShape(index, call);
439
+ const willCarried = isCarriedShape(index, { transition: next });
440
+ if (wasCarried === willCarried)
441
+ return call.end_frame;
442
+ const length = call.end_frame - call.start_frame;
443
+ return call.start_frame + (willCarried ? length - SEAM_OVERLAP_FRAMES : length + SEAM_OVERLAP_FRAMES);
444
+ }
445
+ /** Split the doc's calls at a gesture frame with a selected carry —
446
+ * §0.5's split, verbatim: the gesture frame snaps to the authoring
447
+ * lattice, one window becomes its own two halves (the row carries
448
+ * whole into both; the seam the split births states CUT), everything
449
+ * downstream rebases, and a selected carry mode re-frames the NEW
450
+ * seam. A gesture with no legal split frame REFUSES (null): the doc
451
+ * keeps its identity. Generic over the row: the rest of the call
452
+ * (text, refs, knobs, anchors) carries whole by construction.
453
+ * @param calls the doc's own windows (the calls rows)
454
+ * @param gestureFrame the frame the split is asked at (doc space)
455
+ * @param carry the seam state the NEW split births after the stock
456
+ * cut ("cut" keeps the split's own default seam)
457
+ * @returns the next calls array, or null when no legal split exists. */
458
+ export function splitCallsAt(calls, gestureFrame, carry) {
459
+ if (calls.length === 0)
460
+ return null;
461
+ const i = calls.findIndex((c) => gestureFrame > c.start_frame && gestureFrame < c.end_frame);
462
+ if (i < 0) {
463
+ // a boundary or past-the-end gesture resolves the TARGET
464
+ // window's midpoint — the press always cuts, never appends
465
+ const target = calls.find((c) => gestureFrame === c.start_frame) ?? calls[calls.length - 1];
466
+ return splitCallsAt(calls, Math.round((target.start_frame + target.end_frame) / 2), carry);
467
+ }
468
+ const cur = calls[i];
469
+ // rightCarried is TRUE by construction: the right half is a carried
470
+ // window (17k content) — it seats 'cut' transiently for the reframe
471
+ // math, then the carry block below re-frames it to the caller's
472
+
473
+ const split = snapSplitFrame(cur.start_frame, cur.end_frame, isCarriedShape(i, cur), true, gestureFrame);
474
+ if (split === null)
475
+ return null;
476
+ // the right half seats transition cut — the reframe computes its end
477
+ const rightEnd = reflowSeamSpan({ ...cur, start_frame: split, transition: 'extend' }, i + 1, 'cut');
478
+ const next = [...calls];
479
+ next[i] = { ...cur, end_frame: split };
480
+ next.splice(i + 1, 0, { ...cur, start_frame: split, end_frame: rightEnd, transition: 'cut' });
481
+ const delta = rightEnd - cur.end_frame;
482
+ for (let j = i + 2; j < next.length; j++) {
483
+ next[j] = { ...next[j], start_frame: next[j].start_frame + delta, end_frame: next[j].end_frame + delta };
484
+ }
485
+ if (carry !== 'cut') {
486
+ // the seam re-frames onto its carry lattice (17k content), and
487
+ // EVERY downstream window follows on BOTH coordinates — its span
488
+ // is its own lattice seat and never changes, only its position.
489
+
490
+ // window's start landed it at 141f — off the 17k carried lattice,
491
+ // a doc the walk itself would refuse, authored by the split that
492
+ // was supposed to be legal. It slept because every caller passed
493
+ // 'cut' until the carry default landed.)
494
+ const seam = { ...next[i + 1] };
495
+ const end = reflowSeamSpan(seam, i + 1, carry);
496
+ next[i + 1] = { ...seam, transition: carry, end_frame: end };
497
+ const rebase = end - rightEnd;
498
+ for (let j = i + 2; j < next.length; j++) {
499
+ next[j] = { ...next[j], start_frame: next[j].start_frame + rebase, end_frame: next[j].end_frame + rebase };
500
+ }
501
+ }
502
+ return next;
503
+ }
504
+ /** THE CUTS VERB (the agent's door into the one storage): seconds,
505
+ * never frame math (the run-e79f3b304e4b law — hand-typed frames
506
+ * repaired 90 of 243 frames once). "2.5, 5" splits the containing
507
+ * windows at those seconds — each fold rides splitCallsAt, so the
508
+ * verb IS the split law, not a second arithmetic. The seconds
509
+ * spelling never persists: every write door expands it into the
510
+ * calls rows and drops it (ONE storage; a lingering cuts key on a
511
+ * doc is a bug, refused by the walk).
512
+ * @param calls the doc's own windows the verb splits
513
+ * @param cuts the comma-separated seconds ("2.5, 5")
514
+ * @param carry the seam state every new seam births
515
+ * @returns the next calls array, or the refusal naming the cure. */
516
+ export function expandCuts(calls, cuts, carry = 'extend') {
517
+ const parts = cuts.split(',').map((s) => s.trim());
518
+ if (parts.some((p) => p === '')) {
519
+ return { ok: false, refusal: `cuts '${cuts}' states an empty split point — write the split points as seconds, e.g. "2.5, 5" (the door snaps each to the authoring lattice; frames are never typed)` };
520
+ }
521
+ const seconds = parts.map((p) => Number(p));
522
+ if (seconds.some((n) => !Number.isFinite(n))) {
523
+ return { ok: false, refusal: `cuts '${cuts}' states no seconds — write the split points as seconds, e.g. "2.5, 5" (the door snaps each to the authoring lattice; frames are never typed)` };
524
+ }
525
+ let acc = calls;
526
+ for (const s of seconds.sort((a, b) => a - b)) {
527
+ const next = splitCallsAt(acc, Math.round(s * DOC_FPS_DEFAULT), carry);
528
+ if (next === null) {
529
+ return {
530
+ ok: false,
531
+ refusal: `cuts: ${s}s has no legal split — the containing window's shortest legal halves don't fit (a window at its shape's floor cannot halve); lengthen it first, or the seconds fall on a boundary every fold resolves the same way`,
532
+ };
533
+ }
534
+ acc = next;
535
+ }
536
+ return { ok: true, calls: acc };
537
+ }
233
538
  /** The plan's scene cap (chain_nodes: a 32-scene cap refuses
234
539
  * mis-authored loops) — the composition solver's window ceiling. */
235
540
  export const MAX_COMPOSED_WINDOWS = 32;
@@ -295,6 +600,10 @@ export function solveWindowComposition(totalFrames, where, overlap = CONTEXT_OVE
295
600
 
296
601
 
297
602
 
603
+
604
+
605
+
606
+
298
607
  export function assertSpanGrid(span, where, carry = 0) {
299
608
  if (carry > 0)
300
609
  return assertCarriedSpanGrid(span, where, carry);
@@ -306,15 +615,30 @@ export function assertSpanGrid(span, where, carry = 0) {
306
615
  }
307
616
  return length;
308
617
  }
618
+ /** The frames a window contributes to the delivered film: a first or
619
+ * cut window contributes its span verbatim; a carried window nets
620
+ * out the SEAM_OVERLAP_FRAMES it shares with the previous window.
621
+ * @param call the window row
622
+ * @param index the window's position in the calls array (0-based)
623
+ * @returns the delivered frame count (never negative) */
309
624
  export function deliveredFrames(call, index) {
310
625
  const span = call.end_frame - call.start_frame;
311
626
  if (index === 0 || call.transition === 'cut')
312
627
  return span;
313
628
  return Math.max(0, span - SEAM_OVERLAP_FRAMES);
314
629
  }
630
+ /** The image-bus seats available to loose references: a last-frame
631
+ * pin spends one of the REF_CAPS.images seats when it is set.
632
+ * @param hasLastFrame whether a last-frame pin occupies the bus
633
+ * @returns the maximum reference-image stack */
315
634
  export function imageReferenceCap(hasLastFrame) {
316
635
  return hasLastFrame ? REF_CAPS.images - 1 : REF_CAPS.images;
317
636
  }
637
+ /** Split a comma-separated reference string into entries, trimming
638
+ * separators and surrounding spaces; a data: URI's mime comma does
639
+ * not split its entry.
640
+ * @param value the wire spelling (undefined = no refs)
641
+ * @returns the entries, in order, without empties */
318
642
  export function splitRefList(value) {
319
643
  if (!value)
320
644
  return [];
@@ -346,6 +670,11 @@ export function splitRefList(value) {
346
670
  }
347
671
  return out;
348
672
  }
673
+ /** A declared ref seat's entries, either wire spelling: an array
674
+ * passes its non-empty strings; a comma string rides splitRefList;
675
+ * any other value is zero refs.
676
+ * @param value the ref seat's raw value
677
+ * @returns the reference entries, in order */
349
678
  export function normalizeDeclaredRefs(value) {
350
679
  if (Array.isArray(value)) {
351
680
  return value.filter((entry) => typeof entry === 'string' && entry.trim() !== '');
@@ -354,6 +683,10 @@ export function normalizeDeclaredRefs(value) {
354
683
  return splitRefList(value);
355
684
  return [];
356
685
  }
686
+ /** The inverse wire spelling: entries join into one ", "-separated
687
+ * string; empty input yields undefined (no seat, never an empty string).
688
+ * @param value an array of entries, a string, or absent
689
+ * @returns the joined string, or undefined when nothing is stated */
357
690
  export function joinRefList(value) {
358
691
  if (Array.isArray(value)) {
359
692
  const entries = value.map(String).map((entry) => entry.trim()).filter(Boolean);
@@ -363,6 +696,12 @@ export function joinRefList(value) {
363
696
  return value.trim();
364
697
  return undefined;
365
698
  }
699
+ /** A reference's media genre: the engine's video_w* naming first (its
700
+ * _last_frame/_prev faces are images), else the extension of the name
701
+ * or the URL's path (?path= decoded wins), else 'other'.
702
+ * @param name the entry's file name
703
+ * @param url the entry's URL, when one rides
704
+ * @returns 'image' | 'video' | 'audio' | 'other' */
366
705
  export function refGenreOf(name, url) {
367
706
  const lowerName = name.toLowerCase();
368
707
  if (/^video_w\d+_/.test(lowerName)) {
@@ -375,6 +714,7 @@ export function refGenreOf(name, url) {
375
714
  if (pathMatch !== null) {
376
715
  try {
377
716
  urlFace = decodeURIComponent(pathMatch[1]);
717
+ // a malformed percent-escape throws URIError — the raw encoded text is kept, and the genre sniff reads its extension instead of crashing
378
718
  }
379
719
  catch {
380
720
  urlFace = pathMatch[1];
@@ -390,6 +730,9 @@ export function refGenreOf(name, url) {
390
730
  return 'audio';
391
731
  return 'other';
392
732
  }
733
+ /** The per-call knob vocabulary in serve order — the studio renders a
734
+ * call's knob rows in this order; KnobKey and CALL_KNOB_KEYS derive
735
+ * from it. */
393
736
  export const KNOB_ORDER = [
394
737
  'steps', 'denoise', 'sampler_name', 'sched_name',
395
738
  'shift_video', 'shift_audio',
@@ -403,6 +746,7 @@ export const KNOB_ORDER = [
403
746
  'interpolate_enabled', 'interp_model', 'interp_multiplier',
404
747
  'length',
405
748
  ];
749
+ /** The admitted per-call knob keys — KNOB_ORDER as a membership set. */
406
750
  export const CALL_KNOB_KEYS = new Set(KNOB_ORDER);
407
751
 
408
752
 
@@ -429,6 +773,21 @@ export const CALL_KEYS = new Set([
429
773
  'ref_image', 'image_name', 'ref_images', 'ref_videos', 'ref_audios',
430
774
  'beats', 'last_frame', 'first_frame_prev_sec', 'seam_carry',
431
775
  ]);
776
+
777
+
778
+
779
+
780
+
781
+
782
+
783
+
784
+
785
+
786
+
787
+
788
+ export const CALL_TRANSITIONS = ['cut', 'extend', 'carry+keyframe'];
789
+ /** Legacy knob spellings → their current knob keys (a stored row
790
+ * carrying the left column reads under the right). */
432
791
  export const LEGACY_KNOB_KEY = {
433
792
  sampling_steps: 'steps',
434
793
  sampler: 'sampler_name',
@@ -446,6 +805,10 @@ export const LEGACY_KNOB_KEY = {
446
805
  interpolate_model: 'interp_model',
447
806
  interpolate_multiplier: 'interp_multiplier',
448
807
  };
808
+ /** Map a legacy knob spelling to its current knob key; an unknown key
809
+ * passes through verbatim.
810
+ * @param key the stored or stated knob key
811
+ * @returns the current knob key */
449
812
  export function migrateCallKnobKey(key) {
450
813
  return LEGACY_KNOB_KEY[key] ?? key;
451
814
  }
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@melite/models-h3",
3
- "version": "0.2.2-alpha",
3
+ "version": "0.3.0-alpha",
4
4
  "license": "AGPL-3.0-or-later",
5
5
  "type": "module",
6
6
  "exports": {
@@ -17,6 +17,10 @@
17
17
  "types": "./lib/timelineContract.d.ts",
18
18
  "default": "./lib/timelineContract.js"
19
19
  },
20
+ "./secondPass": {
21
+ "types": "./lib/secondPass.d.ts",
22
+ "default": "./lib/secondPass.js"
23
+ },
20
24
  "./filmMix": {
21
25
  "types": "./lib/filmMix.d.ts",
22
26
  "default": "./lib/filmMix.js"
@@ -31,9 +35,9 @@
31
35
  }
32
36
  },
33
37
  "dependencies": {
34
- "@deepseek-ai/schemastery": "^3.18.5",
35
- "@melite/comfyui-card-kit": "0.2.2-alpha",
36
- "@melite/contracts": "0.2.2-alpha"
38
+ "@deepseek-ai/schemastery": "^3.19.0",
39
+ "@melite/comfyui-card-kit": "0.3.0-alpha",
40
+ "@melite/contracts": "0.3.0-alpha"
37
41
  },
38
42
  "files": [
39
43
  "lib/index.js",
@@ -41,7 +45,7 @@
41
45
  "lib/**/*.d.ts"
42
46
  ],
43
47
  "peerDependencies": {
44
- "@deepseek-ai/cordis": "^4.0.5",
48
+ "@deepseek-ai/cordis": "^4.1.0",
45
49
  "@deepseek-ai/cosmokit": "~1.8.5"
46
50
  },
47
51
  "description": "MiniMax H3 family, joint video and audio generation across timeline, single-shot, and keyframe lanes.",