@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.
@@ -1,20 +1,83 @@
1
+ /** The frames of generated context a carried seam contributes — the
2
+ * generation head a non-cut join rides (a carried window's authored
3
+ * span excludes it; its render includes it). */
1
4
  export declare const SEAM_OVERLAP_FRAMES = 22;
5
+ /** The window grid's floor and first rung: every legal length is BASE + STEP·k. */
2
6
  export declare const GRID_BASE_FRAMES = 22;
7
+ /** The window grid's rung spacing: legal lengths advance 17 frames per step. */
3
8
  export declare const GRID_STEP_FRAMES = 17;
9
+ /** The window grid's ceiling: no window renders more than 362 frames. */
4
10
  export declare const GRID_MAX_FRAMES = 362;
11
+ /** The generated-length residue: a carried window renders 17k + 22 ≡ 5
12
+ * (mod 17) frames — the "% 17 == 5" the engine's own refusals name. */
5
13
  export declare const GRID_REMAINDER = 5;
14
+ /** The conditioning image bus's slot count (bundle inputs 3–9). */
6
15
  export declare const IMAGE_BUS_SLOTS = 9;
16
+ /** The family's LAST-FRAME PICK spelling (one home, both readers —
17
+ * extend.ts's anchor and the seam's keyframe carry): a positive
18
+ * out-of-band batch index the engine clamps onto the clip's FINAL
19
+ * row (min(shape−1, index)) under every build; the negative
20
+ * spelling slices empty on the live estate and is banned
21
+ * family-wide. */
22
+ export declare const LAST_FRAME_BATCH_INDEX = 16384;
23
+ /** Per-media reference caps — the max stack each declared ref lane admits. */
7
24
  export declare const REF_CAPS: {
8
25
  readonly images: 8;
9
26
  readonly videos: 3;
10
27
  readonly audios: 3;
11
28
  readonly refmods: 8;
12
29
  };
30
+ /** THE AV-CONTINUITY LAW, one TS home (defect board row 4, the
31
+ * "derive the carry value" rider). The engine's own vocabulary is
32
+ * AV_TRANSITION_CONTEXT_LENGTHS = (39, 90, 141, 192, 243)
33
+ * (vendor/comfyui_extensions/ComfyUI-MiniMaxH3-Context-Loop/
34
+ * contracts_v05.py:55); on a generated-audio carry join (the edit
35
+ * chain's own mode — context > 0) any other positive boundary
36
+ * refuses AT THE NODE, eight graphs deep
37
+ * (run-1f91718b7cde: "H3 AV generated-audio continuity requires an
38
+ * exact shared video/audio boundary: 39, 90, 141, 192, or 243
39
+ * context frames"). The compose door judges THIS vocabulary at zero
40
+ * GPU so no agent ever discovers it by a burned run; 0 (the cut
41
+ * join, carry: false — the engine's own "cut / independent" preset,
42
+ * contracts_v05.py:158-162) is the one legal value outside it. */
43
+ export declare const AV_CONTINUITY_OVERLAPS: readonly [39, 90, 141, 192, 243];
44
+ /** The derived carry join (defect board row 4: "join with the same
45
+ * overlap" — the smallest legal boundary, the least context spent;
46
+ * the engine's own reference value and the chain's historical
47
+ * default, now DERIVED instead of typed). */
48
+ export declare const CARRY_JOIN_OVERLAP = 39;
49
+ /** The carry statement's admission (defect board row 4: "expose
50
+ * exactly one new concept — carry: true"). ABSENT = carry, THE
51
+ * DEFAULT — the gen seam's own law (docModel.ts: "'extend'
52
+ * (ABSENT = carry, THE DEFAULT)"): the film splits on its own
53
+ * timeline and every segment continues from the last frame of the
54
+ * previous. Stated false = the cut join (each segment stands
55
+ * alone; the engine's cut preset, context 0).
56
+ * @param entry the edit-bag entry carrying the carry seat
57
+ * @returns true when segments join with context carry */
58
+ export declare function entryCarries(entry: Record<string, unknown>): boolean;
59
+ /** THE CARRY-OVERLAP RESOLVER (defect board row 4 — the door the
60
+ * operator asked for five times): the join boundary is DERIVED from
61
+ * the engine's AV-continuity vocabulary, never hand-typed. Unstated
62
+ * → the derived 39 (carry on) or 0 (carry: false); an explicitly
63
+ * stated overlap_frames — the expert override, served on AUTHORED
64
+ * seams' context_length (the plan head itself carries only the
65
+ * AV-legal 39; see chainEdit's planOverlapFeed) — must be 0 or one
66
+ * of the five legal boundaries and REFUSES HERE, at the compose
67
+ * door, quoting the engine's law and naming the stated value, so
68
+ * the run-1f91718b7cde class (a boundary typed legal-looking,
69
+ * refused eight nodes deep) is dead at zero GPU.
70
+ * @param entry the edit-bag entry (overlap_frames / carry seats)
71
+ * @returns the join boundary in frames: 0, 39, 90, 141, 192 or 243 */
72
+ export declare function resolveCarryOverlap(entry: Record<string, unknown>): number;
73
+ /** One authored window in film frames: half-open [start, end), with
74
+ * the seam its join carries (undefined = the carry default). */
13
75
  export interface TimelineSpan {
14
76
  readonly start: number;
15
77
  readonly end: number;
16
78
  readonly transition?: string;
17
79
  }
80
+ /** The calls-row spelling of a window: start/end_frame plus the seam. */
18
81
  export interface TimelineCallSpan {
19
82
  readonly start_frame: number;
20
83
  readonly end_frame: number;
@@ -28,7 +91,14 @@ export interface TimelineCallSpan {
28
91
 
29
92
 
30
93
 
94
+
95
+
31
96
  export declare function isMediaRef(v: string): boolean;
97
+ /** The context frames a seam carries: 0 for the cut join, the
98
+ * SEAM_OVERLAP_FRAMES generation head for any other transition
99
+ * (unstated included — carry is the default).
100
+ * @param transition the seam a call states (undefined = carry)
101
+ * @returns the join's context overlap in frames */
32
102
  export declare function transitionOverlap(transition?: string): number;
33
103
 
34
104
 
@@ -49,6 +119,17 @@ export declare function transitionOverlap(transition?: string): number;
49
119
 
50
120
 
51
121
  export declare const DOC_FPS_DEFAULT: 24;
122
+ /** The doc's LENGTH row default — the schema row's own (56f, the
123
+ * engine grid's design window 22+17·2), the same seed the walk
124
+ * fills for span-less calls. One owner, the same law as
125
+ * DOC_FPS_DEFAULT: the studio's axis fallback reads THIS, never a
126
+ * second literal (the D-19 cure retired the `: 1` collapse — an
127
+ * empty-calls axis books the doc's own plan floor, never a
128
+ * 1-frame sliver strip). */
129
+ export declare const DOC_LENGTH_DEFAULT: 56;
130
+
131
+
132
+
52
133
 
53
134
 
54
135
 
@@ -67,7 +148,6 @@ export declare const DOC_FPS_DEFAULT: 24;
67
148
 
68
149
 
69
150
 
70
- export declare const T4_ONLY_KEYS: readonly ["sharpen_switch", "sharpen_method", "sharpen_strength", "sharpen_radius", "sharpen_threshold", "sharpen_iterations", "interp_switch", "interp_multiplier", "interp_model", "sr_switch", "sr_model", "sr_resolution", "second_pass_enabled", "sharpen_enabled", "interpolate_enabled", "attention_backend"];
71
151
 
72
152
 
73
153
 
@@ -102,6 +182,7 @@ export declare const FILM_ONLY_KEYS: readonly ["duck_depth_db"];
102
182
 
103
183
 
104
184
 
185
+
105
186
 
106
187
 
107
188
  export declare const FAMILY_LAW: {
@@ -115,9 +196,7 @@ export declare const FAMILY_LAW: {
115
196
  }, {
116
197
  readonly lane: "t4_open";
117
198
  }];
118
- readonly deadKeys: {
119
- readonly t4r: readonly ["sharpen_switch", "sharpen_method", "sharpen_strength", "sharpen_radius", "sharpen_threshold", "sharpen_iterations", "interp_switch", "interp_multiplier", "interp_model", "sr_switch", "sr_model", "sr_resolution", "second_pass_enabled", "sharpen_enabled", "interpolate_enabled", "attention_backend"];
120
- };
199
+ readonly deadKeys: {};
121
200
  };
122
201
 
123
202
 
@@ -139,8 +218,23 @@ export declare const FAMILY_LAW: {
139
218
 
140
219
 
141
220
  export declare function deriveWindowFamily(raw: Record<string, unknown>): 't4r' | 't4_open' | 't4_chain';
221
+ /** A span's join overlap — transitionOverlap over the span's own seam.
222
+ * @param span the authored window
223
+ * @returns the window's context overlap in frames */
142
224
  export declare function spanOverlap(span: TimelineSpan): number;
225
+ /** The window's render length on the engine grid: the span plus its
226
+ * carry, snapped to 22+17k inside [22,362]. Off-grid spans snap;
227
+ * doors that must refuse use assertSpanGrid instead.
228
+ * @param span the authored window
229
+ * @param carry the seam overlap the window rides (0 for first/cut)
230
+ * @returns the grid-legal generated length in frames */
143
231
  export declare function spanStanzaFrames(span: TimelineSpan, carry?: number): number;
232
+ /** A carried window's grid geometry: the generated start (span.start −
233
+ * carry), the snapped generated length, and the two neighboring legal
234
+ * end frames a refusal names.
235
+ * @param span the authored carried window (span = 17k content frames)
236
+ * @param carry the seam overlap (the SEAM_OVERLAP_FRAMES default)
237
+ * @returns the snapped geometry — never a legality verdict */
144
238
  export interface CarriedSpanGrid {
145
239
  readonly generatedStart: number;
146
240
  readonly generatedEnd: number;
@@ -148,19 +242,143 @@ export interface CarriedSpanGrid {
148
242
  readonly lowerEnd: number;
149
243
  readonly upperEnd: number;
150
244
  }
245
+ /** Compute a carried window's grid geometry without judging it: the
246
+ * generated start, the snapped length, and the neighboring legal ends.
247
+ * @param span the authored carried window
248
+ * @param carry the seam overlap (the SEAM_OVERLAP_FRAMES default)
249
+ * @returns the CarriedSpanGrid for the window */
151
250
  export declare function carriedSpanGrid(span: TimelineSpan, carry?: number): CarriedSpanGrid;
251
+ /** The carried window's admission gate: the snapped grid length must
252
+ * equal the requested span+carry exactly; anything else refuses loud
253
+ * naming the authored range, the snapped range, and the legal
254
+ * neighboring end frames.
255
+ * @param span the authored carried window
256
+ * @param where the refusal's voice (the calling door's name)
257
+ * @param carry the seam overlap (the SEAM_OVERLAP_FRAMES default)
258
+ * @returns the grid-legal generated length in frames */
152
259
  export declare function assertCarriedSpanGrid(span: TimelineSpan, where: string, carry?: number): number;
260
+ /** The booked render clock, one home: the seconds seat rounds its
261
+ * quotient to milliseconds before it rides the wire, so every
262
+ * consumer that needs the value the graph will actually carry (the
263
+ * schema's own rail bounds, the mix ledger) books through here —
264
+ * never a second copy of the rounding.
265
+ * @param lengthFrames the window's generated length
266
+ * @param fps the doc's playback clock
267
+ * @returns the length in seconds, rounded to milliseconds */
268
+ export declare function bookSeconds(lengthFrames: number, fps: number): number;
269
+ /** The nearest legal 22+17k length (round to the rung, clamp into
270
+ * [22,362]) — the "nearest legal" value refusal voices quote.
271
+ * @param length the requested length in frames
272
+ * @returns the nearest grid-legal length */
153
273
  export declare function gridSnap(length: number): number;
154
274
  /** THE GRID PREDICATE, one owner: a length the engine can render is
155
275
  * 22+17k inside [22,362]. Every refusal door asks this question, so
156
276
  * knob pins, single windows, cut windows, and carried windows cannot
157
- * drift into different laws. */
277
+ * drift into different laws.
278
+ * @param length the candidate length in frames
279
+ * @returns true when length is 22+17k inside [22,362] */
158
280
  export declare function isGridLength(length: number): boolean;
281
+ /** The grid admission gate: a non-number or off-grid length refuses
282
+ * naming the nearest legal value; a legal length passes verbatim.
283
+ * @param length the value under admission (a number is required)
284
+ * @param where the refusal's voice (the calling door's name)
285
+ * @returns the length, verbatim */
159
286
  export declare function assertGridLength(length: unknown, where: string): number;
160
287
  /** The chain policy's masked_av context — the overlap every composed
161
288
  * seam after the first carries (the swap's clip law, shared with the
162
289
  * extend's window composition). */
163
290
  export declare const CONTEXT_OVERLAP_FRAMES = 39;
291
+ /** The three carry states a split seat states (§0.9's vocabulary,
292
+ * the same three the call card's seam seat and the strip head's
293
+ * carry menu serve). */
294
+ export type SplitCarry = 'cut' | 'extend' | 'carry+keyframe';
295
+
296
+
297
+
298
+
299
+
300
+
301
+
302
+
303
+
304
+
305
+
306
+
307
+
308
+
309
+
310
+
311
+
312
+ /** Is this window's seam a carried join? Index-aware — index 0 is
313
+ * always a first window (no carry), and a 'cut' seam never
314
+ * carries.
315
+ * @param index the window's position in the calls array (0-based)
316
+ * @param call the window's own row (its transition seat)
317
+ * @returns true when the seam rides the carry join */
318
+ export declare function isCarriedShape(index: number, call: Pick<TimelineCallSpan, 'transition'>): boolean;
319
+ /** Is this authored LENGTH legal for the window's shape? A carried
320
+ * window rides the 17k step (content + 22f carry head ≤ 362); a
321
+ * first/cut window rides the 22+17k grid.
322
+ * @param length the authored length in frames
323
+ * @param carried true when the window is a carried join
324
+ * @returns true when the shape's own grid admits the length */
325
+ export declare function isLegalCallLength(length: number, carried: boolean): boolean;
326
+ /** The splice frame for a split where BOTH halves must be legal —
327
+ * the gesture's frame when it already qualifies, else the nearest
328
+ * one that does. NULL when no interior frame qualifies (the §0.5
329
+ * fence): a window at its shape's floor has no legal split at all
330
+ * — the caller refuses loud, never repairs.
331
+ * @param start the containing window's first frame
332
+ * @param end the containing window's end frame
333
+ * @param leftCarried whether the left half keeps the carried shape
334
+ * @param rightCarried whether the right half takes the carried shape
335
+ * @param gesture the frame the split was asked at
336
+ * @returns the legal frame nearest the gesture, or null */
337
+ export declare function snapSplitFrame(start: number, end: number, leftCarried: boolean, rightCarried: boolean, gesture: number): number | null;
338
+ /** The seam toggle's re-frame: the 22-frame carry moves from the
339
+ * generation head to (or from) the authored span. A first window
340
+ * has no carry either way, so its toggle never moves frames.
341
+ * @param call the window row the toggle re-frames
342
+ * @param index the window's position in the calls array (0-based)
343
+ * @param next the seam state after the toggle
344
+ * @returns the window's re-framed end frame */
345
+ export declare function reflowSeamSpan(call: Pick<TimelineCallSpan, 'start_frame' | 'end_frame' | 'transition'>, index: number, next: 'extend' | 'cut' | 'carry+keyframe'): number;
346
+ /** Split the doc's calls at a gesture frame with a selected carry —
347
+ * §0.5's split, verbatim: the gesture frame snaps to the authoring
348
+ * lattice, one window becomes its own two halves (the row carries
349
+ * whole into both; the seam the split births states CUT), everything
350
+ * downstream rebases, and a selected carry mode re-frames the NEW
351
+ * seam. A gesture with no legal split frame REFUSES (null): the doc
352
+ * keeps its identity. Generic over the row: the rest of the call
353
+ * (text, refs, knobs, anchors) carries whole by construction.
354
+ * @param calls the doc's own windows (the calls rows)
355
+ * @param gestureFrame the frame the split is asked at (doc space)
356
+ * @param carry the seam state the NEW split births after the stock
357
+ * cut ("cut" keeps the split's own default seam)
358
+ * @returns the next calls array, or null when no legal split exists. */
359
+ export declare function splitCallsAt<T extends TimelineCallSpan>(calls: T[], gestureFrame: number, carry: SplitCarry): T[] | null;
360
+ /** THE CUTS VERB'S OUTCOME — the rows, or the loud refusal (never a
361
+ * silent drop, never a repair behind the caller's back). */
362
+ export type CutsResult<T extends TimelineCallSpan> = {
363
+ ok: true;
364
+ calls: T[];
365
+ } | {
366
+ ok: false;
367
+ refusal: string;
368
+ };
369
+ /** THE CUTS VERB (the agent's door into the one storage): seconds,
370
+ * never frame math (the run-e79f3b304e4b law — hand-typed frames
371
+ * repaired 90 of 243 frames once). "2.5, 5" splits the containing
372
+ * windows at those seconds — each fold rides splitCallsAt, so the
373
+ * verb IS the split law, not a second arithmetic. The seconds
374
+ * spelling never persists: every write door expands it into the
375
+ * calls rows and drops it (ONE storage; a lingering cuts key on a
376
+ * doc is a bug, refused by the walk).
377
+ * @param calls the doc's own windows the verb splits
378
+ * @param cuts the comma-separated seconds ("2.5, 5")
379
+ * @param carry the seam state every new seam births
380
+ * @returns the next calls array, or the refusal naming the cure. */
381
+ export declare function expandCuts<T extends TimelineCallSpan>(calls: T[], cuts: string, carry?: SplitCarry): CutsResult<T>;
164
382
  /** The plan's scene cap (chain_nodes: a 32-scene cap refuses
165
383
  * mis-authored loops) — the composition solver's window ceiling. */
166
384
  export declare const MAX_COMPOSED_WINDOWS = 32;
@@ -195,15 +413,54 @@ export declare function solveWindowComposition(totalFrames: number, where: strin
195
413
 
196
414
 
197
415
 
416
+
417
+
418
+
419
+
198
420
  export declare function assertSpanGrid(span: TimelineSpan, where: string, carry?: number): number;
421
+ /** The frames a window contributes to the delivered film: a first or
422
+ * cut window contributes its span verbatim; a carried window nets
423
+ * out the SEAM_OVERLAP_FRAMES it shares with the previous window.
424
+ * @param call the window row
425
+ * @param index the window's position in the calls array (0-based)
426
+ * @returns the delivered frame count (never negative) */
199
427
  export declare function deliveredFrames(call: TimelineCallSpan, index: number): number;
428
+ /** The image-bus seats available to loose references: a last-frame
429
+ * pin spends one of the REF_CAPS.images seats when it is set.
430
+ * @param hasLastFrame whether a last-frame pin occupies the bus
431
+ * @returns the maximum reference-image stack */
200
432
  export declare function imageReferenceCap(hasLastFrame: boolean): number;
433
+ /** Split a comma-separated reference string into entries, trimming
434
+ * separators and surrounding spaces; a data: URI's mime comma does
435
+ * not split its entry.
436
+ * @param value the wire spelling (undefined = no refs)
437
+ * @returns the entries, in order, without empties */
201
438
  export declare function splitRefList(value: string | undefined): string[];
439
+ /** A declared ref seat's entries, either wire spelling: an array
440
+ * passes its non-empty strings; a comma string rides splitRefList;
441
+ * any other value is zero refs.
442
+ * @param value the ref seat's raw value
443
+ * @returns the reference entries, in order */
202
444
  export declare function normalizeDeclaredRefs(value: unknown): string[];
445
+ /** The inverse wire spelling: entries join into one ", "-separated
446
+ * string; empty input yields undefined (no seat, never an empty string).
447
+ * @param value an array of entries, a string, or absent
448
+ * @returns the joined string, or undefined when nothing is stated */
203
449
  export declare function joinRefList(value: unknown): string | undefined;
450
+ /** A reference's media genre: the engine's video_w* naming first (its
451
+ * _last_frame/_prev faces are images), else the extension of the name
452
+ * or the URL's path (?path= decoded wins), else 'other'.
453
+ * @param name the entry's file name
454
+ * @param url the entry's URL, when one rides
455
+ * @returns 'image' | 'video' | 'audio' | 'other' */
204
456
  export declare function refGenreOf(name: string, url?: string): 'image' | 'video' | 'audio' | 'other';
457
+ /** The per-call knob vocabulary in serve order — the studio renders a
458
+ * call's knob rows in this order; KnobKey and CALL_KNOB_KEYS derive
459
+ * from it. */
205
460
  export declare const KNOB_ORDER: readonly ["steps", "denoise", "sampler_name", "sched_name", "shift_video", "shift_audio", "sla_sparsity", "sla_block_size", "sla_min_seq_len", "sla_dense_last_steps", "sla_protect_audio", "sla_stabilize_motion", "sla_reference_protection", "sla_dense_backend", "sla_dense_steps", "sla_disable_fp16_accum", "sharpen_enabled", "sharpen_method", "sharpen_strength", "sharpen_radius", "sharpen_threshold", "sharpen_iterations", "interpolate_enabled", "interp_model", "interp_multiplier", "length"];
461
+ /** One per-call knob key — a member of KNOB_ORDER. */
206
462
  export type KnobKey = (typeof KNOB_ORDER)[number];
463
+ /** The admitted per-call knob keys — KNOB_ORDER as a membership set. */
207
464
  export declare const CALL_KNOB_KEYS: ReadonlySet<string>;
208
465
 
209
466
 
@@ -221,6 +478,21 @@ export declare const SECOND_PASS_KNOBS: ReadonlySet<string>;
221
478
 
222
479
 
223
480
  export declare const CALL_KEYS: ReadonlySet<string>;
481
+
482
+
483
+
484
+
485
+
486
+
487
+
488
+
489
+
490
+
491
+
492
+
493
+ export declare const CALL_TRANSITIONS: readonly ["cut", "extend", "carry+keyframe"];
494
+ /** Legacy knob spellings → their current knob keys (a stored row
495
+ * carrying the left column reads under the right). */
224
496
  export declare const LEGACY_KNOB_KEY: {
225
497
  readonly sampling_steps: "steps";
226
498
  readonly sampler: "sampler_name";
@@ -238,5 +510,9 @@ export declare const LEGACY_KNOB_KEY: {
238
510
  readonly interpolate_model: "interp_model";
239
511
  readonly interpolate_multiplier: "interp_multiplier";
240
512
  };
513
+ /** Map a legacy knob spelling to its current knob key; an unknown key
514
+ * passes through verbatim.
515
+ * @param key the stored or stated knob key
516
+ * @returns the current knob key */
241
517
  export declare function migrateCallKnobKey(key: string): string;
242
518
  //# sourceMappingURL=timelineContract.d.ts.map