@scenerok/sdk 0.9.0 → 0.10.0

package/dist/ir-builder.d.ts

@@ -1,28 +1,81 @@
 /**
- * Shared IR builder — appends SDK nodes onto an IRTimeline.
- * Used by @scenerok/sdk Timeline and (later) optionally by the VidScript compiler.
+ * IR lowering for SDK nodes — the TypeScript twin of the VidScript compiler's
+ * placement rules (`placeVidValue` in the platform's `src/parser/compiler-v2.ts`),
+ * so an SDK scene and the VidScript that says the same thing emit the same IR.
+ *
+ * A timeline records placements and lowers them in `toIR()`. Lowering late lets
+ * a nested timeline take its parent's canvas and share its id counter.
  */
 import { type IRTimeline } from './ir.js';
 import { type TimeInput } from './duration.js';
+import { type TimeBase } from './frame-rate.js';
 import { type GridAreaRect, type GridSpec } from './grid.js';
-import type { Schedulable, TimelineOptions } from './types.js';
-export declare function resetIrBuilderIds(seed?: number): void;
+import type { Schedulable, TimelineLike, TimelineOptions } from './types.js';
+/** Canvas a timeline lowers onto when its options do not say. */
+export interface Canvas {
+    width: number;
+    height: number;
+    fps: number;
+}
+/**
+ * The canvas `timeline()` uses when it gives no size: the host's (a VidScript
+ * import sets `globalThis.__scenerokCanvas` to the importing script's output),
+ * else 1080×1920 at 30 fps.
+ */
+export declare function hostCanvas(): Canvas;
+/** @deprecated Ids are numbered per `toIR()` call now; kept for compatibility. */
+export declare function resetIrBuilderIds(_seed?: number): void;
 export interface IrBuilderState {
     ir: IRTimeline;
+    /** Visual playhead (seconds) after the last placed picture. */
     visualCursor: number;
     audioCursor: number;
     /** Named area rects (percent) from `timeline.grid(...)`; null until declared. */
     gridAreas: Map<string, GridAreaRect> | null;
+    /** Block boundaries snap to this frame grid, as VidScript's do. */
+    timeBase: TimeBase;
+    /** Shared across nested lowerings so ids are unique in the whole IR. */
+    ids: {
+        next: number;
+    };
 }
-export declare function createIrBuilder(options?: TimelineOptions): IrBuilderState;
-/** Declare or replace the timeline grid used by `area:` text placement. */
+export declare function createIrBuilder(options?: TimelineOptions, canvas?: Canvas, ids?: {
+    next: number;
+}): IrBuilderState;
+/** Declare or replace the timeline grid used by `area:` placement. */
 export declare function setGrid(state: IrBuilderState, spec: GridSpec): Map<string, GridAreaRect>;
+export declare function normalizeBlendMode(raw: string): string;
 /**
  * Post-pass: resolve fromId/toId for transition surfaces from neighboring clips.
  * Mirrors VidScript `bindTransitions` in compiler-v2.
  */
 export declare function bindTransitions(ir: IRTimeline, warnings?: string[]): void;
-export declare function scheduleAt(state: IrBuilderState, start: number, end: number, value: Schedulable): void;
-export declare function inferAutoDuration(value: Schedulable, explicit?: TimeInput): number;
+/** A timeline's recorded placements, lowered by `lowerTimeline`. */
+export interface TimelineRecord {
+    options: TimelineOptions;
+    grid: GridSpec | null;
+    entries: Array<{
+        start: number;
+        end: number;
+        value: Schedulable;
+    }>;
+}
+declare const RECORD: unique symbol;
+export declare function timelineRecordOf(value: TimelineLike): TimelineRecord;
+export { RECORD as TIMELINE_RECORD };
+/** Lower a recorded timeline into a fresh builder on `canvas`. Transitions are not bound. */
+export declare function lowerTimeline(record: TimelineRecord, canvas: Canvas, ids?: {
+    next: number;
+}): IrBuilderState;
+export interface ScheduleOptions {
+    /** Snap the window to the frame grid (default true; mattes reuse their host's window). */
+    snap?: boolean;
+    /** Advance the playheads (default true). */
+    advance?: boolean;
+}
+/** Lower one placement into `state.ir`. Returns where it ended. */
+export declare function scheduleAt(state: IrBuilderState, rawStart: number, rawEnd: number, value: Schedulable, options?: ScheduleOptions): number;
+/** The span `push` gives a value with no explicit duration. */
+export declare function inferAutoDuration(value: Schedulable, explicit?: TimeInput, fps?: number): number;
 export declare function assertSchedulable(value: unknown): asserts value is Schedulable;
 //# sourceMappingURL=ir-builder.d.ts.map

package/dist/ir-builder.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"ir-builder.d.ts","sourceRoot":"","sources":["../src/ir-builder.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAWL,KAAK,UAAU,EAEhB,MAAM,SAAS,CAAC;AACjB,OAAO,EAAa,KAAK,SAAS,EAAE,MAAM,eAAe,CAAC;AAC1D,OAAO,EAIL,KAAK,YAAY,EACjB,KAAK,QAAQ,EACd,MAAM,WAAW,CAAC;AACnB,OAAO,KAAK,EAIV,WAAW,EAIX,eAAe,EAGhB,MAAM,YAAY,CAAC;AAKpB,wBAAgB,iBAAiB,CAAC,IAAI,SAAI,GAAG,IAAI,CAEhD;AA0GD,MAAM,WAAW,cAAc;IAC7B,EAAE,EAAE,UAAU,CAAC;IACf,YAAY,EAAE,MAAM,CAAC;IACrB,WAAW,EAAE,MAAM,CAAC;IACpB,iFAAiF;IACjF,SAAS,EAAE,GAAG,CAAC,MAAM,EAAE,YAAY,CAAC,GAAG,IAAI,CAAC;CAC7C;AAED,wBAAgB,eAAe,CAAC,OAAO,GAAE,eAAoB,GAAG,cAAc,CAqB7E;AAED,2EAA2E;AAC3E,wBAAgB,OAAO,CAAC,KAAK,EAAE,cAAc,EAAE,IAAI,EAAE,QAAQ,GAAG,GAAG,CAAC,MAAM,EAAE,YAAY,CAAC,CAIxF;AA2LD;;;GAGG;AACH,wBAAgB,eAAe,CAAC,EAAE,EAAE,UAAU,EAAE,QAAQ,GAAE,MAAM,EAAO,GAAG,IAAI,CAiD7E;AAmED,wBAAgB,UAAU,CACxB,KAAK,EAAE,cAAc,EACrB,KAAK,EAAE,MAAM,EACb,GAAG,EAAE,MAAM,EACX,KAAK,EAAE,WAAW,GACjB,IAAI,CA6BN;AAED,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,WAAW,EAAE,QAAQ,CAAC,EAAE,SAAS,GAAG,MAAM,CAkBlF;AAED,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,CAAC,KAAK,IAAI,WAAW,CAM9E"}
+{"version":3,"file":"ir-builder.d.ts","sourceRoot":"","sources":["../src/ir-builder.ts"],"names":[],"mappings":"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"}