@scenerok/sdk 0.2.0

package/README.md

@@ -0,0 +1,114 @@
+# @scenerok/sdk
+
+TypeScript-first authoring SDK for SceneRok. Agents use this for **complex, data-driven scenes**. Humans keep **VidScript** for short declarative scripts. Both emit the same `IRTimeline` for preview and render.
+
+## Install
+
+```bash
+npm install @scenerok/sdk
+```
+
+## Quick start
+
+```ts
+import { timeline, video, loadVideo, text, audio, s, fadeIn } from '@scenerok/sdk'
+
+export default async function main() {
+  const t = timeline({ width: 1080, height: 1920, fps: 30 })
+  const scene1 = await loadVideo('./hero.mp4')
+
+  t[0][scene1.duration] = scene1.animate(fadeIn(s(0.4)))
+  t['0s']['3s'] = text('Hello', { size: 72 })
+  t[scene1.duration][scene1.duration + s(2)] = text('Next')
+  t.push(audio('./bed.mp3', { duration: 7, volume: 0.4 }))
+
+  return t.toIR()
+}
+```
+
+Use `loadVideo(path)` / `loadAudio(path)` when the asset exists and the SceneRok host can probe it. They call the media stdlib to fill `duration` when omitted, then return normal `video(...)` / `audio(...)` values:
+
+```ts
+const clip = await loadVideo('./hero.mp4')
+t[0][clip.duration] = clip
+```
+
+The sync `video(path, { duration })` and `audio(path, { duration })` factories remain available when you already know the timing.
+
+## Schedule syntax
+
+JavaScript has no `t[0, end]` dual key (comma operator). Use:
+
+| Form | Meaning |
+|------|---------|
+| `t[start][end] = value` | Dual-index Proxy (preferred) |
+| `t.range(start, end, value)` | Explicit call |
+| `t['-'] = value` / `t.push(value)` | Auto-append at playhead |
+
+`start` / `end` accept numbers (seconds), `s(3)` / `ms(300)`, or strings (`'3s'`, `'1:30'`). Full JS arithmetic works: `clip.duration + 0.5`.
+
+No `video` / `text` keywords after `=` — the RHS type is inferred from factories.
+
+## When to use SDK vs VidScript
+
+| Use | Language |
+|-----|----------|
+| Short promos, human edits, templates | VidScript (`.vid`) |
+| Loops, branches, computed timing, agents | TypeScript + `@scenerok/sdk` |
+
+## AI plugins
+
+```ts
+import { timeline, text, s } from '@scenerok/sdk'
+import xai from '@scenerok/xai'
+import eleven from '@elevenlabs/music'
+
+export default async function main() {
+  const t = timeline({ width: 1080, height: 1920, fps: 30 })
+  t.grid({
+    rows: '16% 1fr 18% 10%',
+    areas: ['title', 'stage', 'lower-third', 'caption'],
+  })
+  const clip = await xai.genVideo('Cinematic drone shot', { duration: 5, resolution: '720p' })
+  const bed = await eleven.music('Warm ambient bed', { duration: 10 })
+  t[0][clip.duration] = clip
+  t[0][s(3)] = text('Launch', { size: 72, area: 'title' })
+  t.push(bed)
+  return t.toIR()
+}
+```
+
+Also available: `@scenerok/cloudflare` (`cf.image`, `cf.video`, …). Host secrets and billing match VidScript.
+
+## Grid areas
+
+```ts
+t.grid({
+  rows: '20% 1fr 30%',
+  cols: '1fr 1fr',
+  areas: ['title title', 'left right', 'caption caption'],
+})
+t[0]['3s'] = text('Left', { area: 'left' })
+```
+
+Without `t.grid(...)`, `area: 'title' | 'stage' | 'lower-third' | 'caption'` uses the built-in preset.
+
+## Transitions
+
+```ts
+import { timeline, video } from '@scenerok/sdk'
+import tr from '@scenerok/transitions'
+
+t[0][5] = video('./a.mp4', { duration: 5 })
+t[5][5.6] = tr.dissolve()
+t[5.6][10] = video('./b.mp4', { duration: 4.4 })
+```
+
+Same 29 shaders as VidScript. `toIR()` binds neighboring clips automatically.
+
+## Validate / render
+
+```bash
+scenerok validate scene.ts
+scenerok render scene.ts --watch
+```

package/dist/duration.d.ts

@@ -0,0 +1,29 @@
+/** Duration helpers — seconds as the canonical unit (matches IR). */
+declare const DURATION_BRAND: unique symbol;
+export type TimeInput = number | Duration | string;
+export declare class Duration {
+    readonly [DURATION_BRAND]: true;
+    /** Length in seconds. */
+    readonly seconds: number;
+    constructor(seconds: number);
+    valueOf(): number;
+    toString(): string;
+    add(other: TimeInput): Duration;
+    sub(other: TimeInput): Duration;
+    mul(factor: number): Duration;
+    static isDuration(value: unknown): value is Duration;
+}
+/** Seconds helper: `s(3)` → 3s. */
+export declare function s(seconds: number): Duration;
+/** Milliseconds helper: `ms(300)` → 0.3s. */
+export declare function ms(milliseconds: number): Duration;
+/** Frame count at a given fps (default 30). */
+export declare function frames(count: number, fps?: number): Duration;
+/**
+ * Parse a time value to seconds.
+ * Accepts numbers (already seconds), Duration, or strings like `3s`, `300ms`, `1:30`, `0:01:30`.
+ */
+export declare function toSeconds(value: TimeInput): number;
+export declare function isAutoPlayheadKey(key: PropertyKey): boolean;
+export {};
+//# sourceMappingURL=duration.d.ts.map

package/dist/duration.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"duration.d.ts","sourceRoot":"","sources":["../src/duration.ts"],"names":[],"mappings":"AAAA,qEAAqE;AAErE,QAAA,MAAM,cAAc,eAAkC,CAAC;AAEvD,MAAM,MAAM,SAAS,GAAG,MAAM,GAAG,QAAQ,GAAG,MAAM,CAAC;AAEnD,qBAAa,QAAQ;IACnB,QAAQ,CAAC,CAAC,cAAc,CAAC,EAAG,IAAI,CAAU;IAC1C,yBAAyB;IACzB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;gBAEb,OAAO,EAAE,MAAM;IAO3B,OAAO,IAAI,MAAM;IAIjB,QAAQ,IAAI,MAAM;IAIlB,GAAG,CAAC,KAAK,EAAE,SAAS,GAAG,QAAQ;IAI/B,GAAG,CAAC,KAAK,EAAE,SAAS,GAAG,QAAQ;IAI/B,GAAG,CAAC,MAAM,EAAE,MAAM,GAAG,QAAQ;IAI7B,MAAM,CAAC,UAAU,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,QAAQ;CAOrD;AAED,mCAAmC;AACnC,wBAAgB,CAAC,CAAC,OAAO,EAAE,MAAM,GAAG,QAAQ,CAE3C;AAED,6CAA6C;AAC7C,wBAAgB,EAAE,CAAC,YAAY,EAAE,MAAM,GAAG,QAAQ,CAEjD;AAED,+CAA+C;AAC/C,wBAAgB,MAAM,CAAC,KAAK,EAAE,MAAM,EAAE,GAAG,SAAK,GAAG,QAAQ,CAGxD;AAKD;;;GAGG;AACH,wBAAgB,SAAS,CAAC,KAAK,EAAE,SAAS,GAAG,MAAM,CA4BlD;AAED,wBAAgB,iBAAiB,CAAC,GAAG,EAAE,WAAW,GAAG,OAAO,CAE3D"}

package/dist/duration.js

@@ -0,0 +1,87 @@
+/** Duration helpers — seconds as the canonical unit (matches IR). */
+const DURATION_BRAND = Symbol.for('scenerok.Duration');
+export class Duration {
+    [DURATION_BRAND] = true;
+    /** Length in seconds. */
+    seconds;
+    constructor(seconds) {
+        if (!Number.isFinite(seconds)) {
+            throw new TypeError(`Duration requires a finite number of seconds, got ${seconds}`);
+        }
+        this.seconds = seconds;
+    }
+    valueOf() {
+        return this.seconds;
+    }
+    toString() {
+        return `${this.seconds}s`;
+    }
+    add(other) {
+        return new Duration(this.seconds + toSeconds(other));
+    }
+    sub(other) {
+        return new Duration(this.seconds - toSeconds(other));
+    }
+    mul(factor) {
+        return new Duration(this.seconds * factor);
+    }
+    static isDuration(value) {
+        return (typeof value === 'object'
+            && value !== null
+            && value[DURATION_BRAND] === true);
+    }
+}
+/** Seconds helper: `s(3)` → 3s. */
+export function s(seconds) {
+    return new Duration(seconds);
+}
+/** Milliseconds helper: `ms(300)` → 0.3s. */
+export function ms(milliseconds) {
+    return new Duration(milliseconds / 1000);
+}
+/** Frame count at a given fps (default 30). */
+export function frames(count, fps = 30) {
+    if (fps <= 0)
+        throw new TypeError('fps must be positive');
+    return new Duration(count / fps);
+}
+const TIME_STRING_RE = /^(?:(?<h>\d+):(?<m>\d{2}):(?<s>\d{2}(?:\.\d+)?))$|^(?:(?<mm>\d+):(?<ss>\d{2}(?:\.\d+)?))$|^(?<num>\d+(?:\.\d+)?)\s*(?<unit>s|sec|secs|seconds|ms|milliseconds)?$/i;
+/**
+ * Parse a time value to seconds.
+ * Accepts numbers (already seconds), Duration, or strings like `3s`, `300ms`, `1:30`, `0:01:30`.
+ */
+export function toSeconds(value) {
+    if (typeof value === 'number') {
+        if (!Number.isFinite(value))
+            throw new TypeError(`Invalid time number: ${value}`);
+        return value;
+    }
+    if (Duration.isDuration(value))
+        return value.seconds;
+    if (typeof value === 'string') {
+        const trimmed = value.trim();
+        if (trimmed === '-' || trimmed === '') {
+            throw new TypeError(`Cannot convert auto-playhead marker '${value}' via toSeconds; use timeline.push / t['-']`);
+        }
+        const match = TIME_STRING_RE.exec(trimmed);
+        if (!match || !match.groups) {
+            throw new TypeError(`Unrecognized time string: ${JSON.stringify(value)}`);
+        }
+        const g = match.groups;
+        if (g.h !== undefined) {
+            return Number(g.h) * 3600 + Number(g.m) * 60 + Number(g.s);
+        }
+        if (g.mm !== undefined) {
+            return Number(g.mm) * 60 + Number(g.ss);
+        }
+        const num = Number(g.num);
+        const unit = (g.unit || 's').toLowerCase();
+        if (unit === 'ms' || unit === 'milliseconds')
+            return num / 1000;
+        return num;
+    }
+    throw new TypeError(`Unsupported time input: ${String(value)}`);
+}
+export function isAutoPlayheadKey(key) {
+    return key === '-' || key === '-';
+}

package/dist/grid.d.ts

@@ -0,0 +1,61 @@
+/**
+ * CSS-Grid-style named regions for SceneRok authoring.
+ *
+ * Declare a grid once (or rely on the built-in preset) and place text with
+ * `area: "title"` instead of guessing coordinates:
+ *
+ * ```ts
+ * t.grid({
+ *   rows: '16% 1fr 18% 10%',
+ *   areas: ['title', 'stage', 'lower-third', 'caption'],
+ * })
+ * t[0]['3s'] = text('BIG SALE', { area: 'title' })
+ * ```
+ *
+ * Semantics follow CSS Grid: `rows`/`cols` are track lists (`%` and `fr` units),
+ * `areas` is grid-template-areas — one string per row, space-separated cell
+ * names, `.` for an empty cell, and a name spanning adjacent cells forms a
+ * rectangle. Everything resolves to percentages of the canvas so the result is
+ * resolution-independent.
+ */
+export interface GridSpec {
+    rows?: string;
+    cols?: string;
+    /** grid-template-areas: one string per row, e.g. ["title title", "left right"] */
+    areas: string[];
+}
+/** Cell rectangle in percent units (0–100) of the canvas. */
+export interface GridAreaRect {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+}
+/** Placement params derived from a named grid area (percent strings). */
+export interface GridAreaPlacement {
+    x: string;
+    y: string;
+    maxWidth: string;
+    maxHeight: string;
+}
+/**
+ * Built-in preset so `area:` works with no grid declaration. Areas match the
+ * common social-video anatomy; proportions differ per orientation.
+ */
+export declare function defaultGridSpec(width: number, height: number): GridSpec;
+/**
+ * Resolve a grid spec into named area rectangles (percent units).
+ * Throws on malformed specs — callers surface the message as a compile error.
+ */
+export declare function resolveGridAreas(spec: GridSpec): Map<string, GridAreaRect>;
+/** Convert a grid area rect into centered text placement params (percent strings). */
+export declare function placementFromGridArea(rect: GridAreaRect): GridAreaPlacement;
+/**
+ * Look up a named area and return placement params.
+ * Uses the built-in social-video preset when `areas` is omitted.
+ */
+export declare function placeInArea(name: string, areasOrSpec?: Map<string, GridAreaRect> | GridSpec, canvas?: {
+    width?: number;
+    height?: number;
+}): GridAreaPlacement;
+//# sourceMappingURL=grid.d.ts.map

package/dist/grid.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"grid.d.ts","sourceRoot":"","sources":["../src/grid.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAEH,MAAM,WAAW,QAAQ;IACvB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,kFAAkF;IAClF,KAAK,EAAE,MAAM,EAAE,CAAC;CACjB;AAED,6DAA6D;AAC7D,MAAM,WAAW,YAAY;IAC3B,CAAC,EAAE,MAAM,CAAC;IACV,CAAC,EAAE,MAAM,CAAC;IACV,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,yEAAyE;AACzE,MAAM,WAAW,iBAAiB;IAChC,CAAC,EAAE,MAAM,CAAC;IACV,CAAC,EAAE,MAAM,CAAC;IACV,QAAQ,EAAE,MAAM,CAAC;IACjB,SAAS,EAAE,MAAM,CAAC;CACnB;AAED;;;GAGG;AACH,wBAAgB,eAAe,CAAC,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,QAAQ,CAavE;AAgDD;;;GAGG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,QAAQ,GAAG,GAAG,CAAC,MAAM,EAAE,YAAY,CAAC,CA6D1E;AAMD,sFAAsF;AACtF,wBAAgB,qBAAqB,CAAC,IAAI,EAAE,YAAY,GAAG,iBAAiB,CAO3E;AAED;;;GAGG;AACH,wBAAgB,WAAW,CACzB,IAAI,EAAE,MAAM,EACZ,WAAW,CAAC,EAAE,GAAG,CAAC,MAAM,EAAE,YAAY,CAAC,GAAG,QAAQ,EAClD,MAAM,GAAE;IAAE,KAAK,CAAC,EAAE,MAAM,CAAC;IAAC,MAAM,CAAC,EAAE,MAAM,CAAA;CAAO,GAC/C,iBAAiB,CAgBnB"}

package/dist/grid.js

@@ -0,0 +1,174 @@
+/**
+ * CSS-Grid-style named regions for SceneRok authoring.
+ *
+ * Declare a grid once (or rely on the built-in preset) and place text with
+ * `area: "title"` instead of guessing coordinates:
+ *
+ * ```ts
+ * t.grid({
+ *   rows: '16% 1fr 18% 10%',
+ *   areas: ['title', 'stage', 'lower-third', 'caption'],
+ * })
+ * t[0]['3s'] = text('BIG SALE', { area: 'title' })
+ * ```
+ *
+ * Semantics follow CSS Grid: `rows`/`cols` are track lists (`%` and `fr` units),
+ * `areas` is grid-template-areas — one string per row, space-separated cell
+ * names, `.` for an empty cell, and a name spanning adjacent cells forms a
+ * rectangle. Everything resolves to percentages of the canvas so the result is
+ * resolution-independent.
+ */
+/**
+ * Built-in preset so `area:` works with no grid declaration. Areas match the
+ * common social-video anatomy; proportions differ per orientation.
+ */
+export function defaultGridSpec(width, height) {
+    if (width > height) {
+        // Landscape: wider lower-third band, shallower title.
+        return {
+            rows: '14% 1fr 20% 12%',
+            areas: ['title', 'stage', 'lower-third', 'caption'],
+        };
+    }
+    // Portrait / square: leave headroom for platform UI chrome.
+    return {
+        rows: '16% 1fr 18% 10%',
+        areas: ['title', 'stage', 'lower-third', 'caption'],
+    };
+}
+function parseTrackList(list, count, label) {
+    const source = (list ?? '').trim();
+    if (!source) {
+        return Array.from({ length: count }, () => ({ kind: 'fr', value: 1 }));
+    }
+    const tokens = source.split(/\s+/);
+    const tracks = tokens.map((token) => {
+        if (token.endsWith('%')) {
+            const value = Number(token.slice(0, -1));
+            if (!Number.isFinite(value) || value < 0)
+                throw new Error(`Invalid ${label} track '${token}'`);
+            return { kind: 'percent', value };
+        }
+        if (token.endsWith('fr')) {
+            const value = Number(token.slice(0, -2));
+            if (!Number.isFinite(value) || value <= 0)
+                throw new Error(`Invalid ${label} track '${token}'`);
+            return { kind: 'fr', value };
+        }
+        throw new Error(`Invalid ${label} track '${token}' — use '%' or 'fr' units `
+            + '(px is not supported because grids resolve before the output resolution is known)');
+    });
+    if (tracks.length !== count) {
+        throw new Error(`grid ${label} defines ${tracks.length} track(s) but areas has ${count}`);
+    }
+    return tracks;
+}
+/** Resolve track sizes to percent-of-container (they always total 100). */
+function resolveTracks(tracks) {
+    const fixed = tracks.reduce((sum, t) => sum + (t.kind === 'percent' ? t.value : 0), 0);
+    if (fixed > 100.0001) {
+        throw new Error(`grid percent tracks total ${fixed}% (must be <= 100%)`);
+    }
+    const frTotal = tracks.reduce((sum, t) => sum + (t.kind === 'fr' ? t.value : 0), 0);
+    const remaining = Math.max(0, 100 - fixed);
+    return tracks.map((t) => t.kind === 'percent' ? t.value : frTotal > 0 ? (remaining * t.value) / frTotal : 0);
+}
+/**
+ * Resolve a grid spec into named area rectangles (percent units).
+ * Throws on malformed specs — callers surface the message as a compile error.
+ */
+export function resolveGridAreas(spec) {
+    if (!Array.isArray(spec.areas) || spec.areas.length === 0) {
+        throw new Error('grid requires areas: an array of row strings');
+    }
+    const cellRows = spec.areas.map((row) => String(row).trim().split(/\s+/));
+    const colCount = Math.max(...cellRows.map((row) => row.length));
+    for (const row of cellRows) {
+        if (row.length !== colCount) {
+            throw new Error('grid areas rows must all have the same number of cells');
+        }
+    }
+    const rowSizes = resolveTracks(parseTrackList(spec.rows, cellRows.length, 'rows'));
+    const colSizes = resolveTracks(parseTrackList(spec.cols, colCount, 'cols'));
+    const rowOffsets = [0];
+    for (const size of rowSizes)
+        rowOffsets.push(rowOffsets[rowOffsets.length - 1] + size);
+    const colOffsets = [0];
+    for (const size of colSizes)
+        colOffsets.push(colOffsets[colOffsets.length - 1] + size);
+    const bounds = new Map();
+    for (let r = 0; r < cellRows.length; r++) {
+        for (let c = 0; c < colCount; c++) {
+            const name = cellRows[r][c];
+            if (name === '.')
+                continue;
+            const b = bounds.get(name);
+            if (!b) {
+                bounds.set(name, { r0: r, r1: r, c0: c, c1: c });
+            }
+            else {
+                b.r0 = Math.min(b.r0, r);
+                b.r1 = Math.max(b.r1, r);
+                b.c0 = Math.min(b.c0, c);
+                b.c1 = Math.max(b.c1, c);
+            }
+        }
+    }
+    // CSS requires named areas to be rectangular; enforce it so a typo like
+    // ["title stage", "stage title"] fails loudly instead of producing a
+    // surprising bounding box.
+    for (const [name, b] of bounds) {
+        for (let r = b.r0; r <= b.r1; r++) {
+            for (let c = b.c0; c <= b.c1; c++) {
+                if (cellRows[r][c] !== name) {
+                    throw new Error(`grid area '${name}' is not rectangular`);
+                }
+            }
+        }
+    }
+    const rects = new Map();
+    for (const [name, b] of bounds) {
+        rects.set(name, {
+            x: colOffsets[b.c0],
+            y: rowOffsets[b.r0],
+            width: colOffsets[b.c1 + 1] - colOffsets[b.c0],
+            height: rowOffsets[b.r1 + 1] - rowOffsets[b.r0],
+        });
+    }
+    return rects;
+}
+function roundPercent(value) {
+    return Math.round(value * 100) / 100;
+}
+/** Convert a grid area rect into centered text placement params (percent strings). */
+export function placementFromGridArea(rect) {
+    return {
+        x: `${roundPercent(rect.x + rect.width / 2)}%`,
+        y: `${roundPercent(rect.y + rect.height / 2)}%`,
+        maxWidth: `${roundPercent(rect.width)}%`,
+        maxHeight: `${roundPercent(rect.height)}%`,
+    };
+}
+/**
+ * Look up a named area and return placement params.
+ * Uses the built-in social-video preset when `areas` is omitted.
+ */
+export function placeInArea(name, areasOrSpec, canvas = {}) {
+    const width = canvas.width ?? 1080;
+    const height = canvas.height ?? 1920;
+    let areas;
+    if (!areasOrSpec) {
+        areas = resolveGridAreas(defaultGridSpec(width, height));
+    }
+    else if (areasOrSpec instanceof Map) {
+        areas = areasOrSpec;
+    }
+    else {
+        areas = resolveGridAreas(areasOrSpec);
+    }
+    const rect = areas.get(name);
+    if (!rect) {
+        throw new Error(`Unknown grid area '${name}' (available: ${[...areas.keys()].join(', ')})`);
+    }
+    return placementFromGridArea(rect);
+}

package/dist/index.d.ts

@@ -0,0 +1,27 @@
+/**
+ * @scenerok/sdk — TypeScript-first authoring for SceneRok.
+ *
+ * Agents use this for complex, data-driven scenes. Humans keep VidScript for
+ * short declarative scripts. Both emit the same IRTimeline for Pass 2.
+ */
+export type { IRTimeline, IRClip, IRLayer, IRTextLayer, IRSurface, IREffect, IRAudioTrack, IROutput, IRAnimation, IRMotionTrack, } from './ir.js';
+export { defaultIRTimeline, defaultIROutput } from './ir.js';
+export { Duration, s, ms, frames, toSeconds, type TimeInput, } from './duration.js';
+export type { VideoClip, VideoOptions, TextLayer, TextOptions, AudioTrack, AudioOptions, FilterEffect, ShaderEffect, TransitionEffect, TransitionOptions, AnimationDescriptor, Schedulable, TimelineOptions, TimelineLike, SdkHost, } from './types.js';
+export { isSdkNode, isSchedulable } from './types.js';
+export { video, loadVideo, text, audio, loadAudio, filter, shader } from './media.js';
+export { fadeIn, fadeOut, slideY, slideX, scale, popIn } from './motion.js';
+export { timeline, isTimeline, type Timeline } from './timeline.js';
+export { createIrBuilder, scheduleAt, resetIrBuilderIds, inferAutoDuration, assertSchedulable, bindTransitions, setGrid, type IrBuilderState, } from './ir-builder.js';
+export { defaultGridSpec, resolveGridAreas, placementFromGridArea, placeInArea, type GridSpec, type GridAreaRect, type GridAreaPlacement, } from './grid.js';
+export { getVideoLength, getAudioLength, getMediaInfo, getDimensions, getFps, getLoudness, hasAudio, mediaKind, grabFrame, grabFrames, grabFrameAtFraction, measureText, fitContain, fitCover, clampTime, parseTime, timecode, beats, type MediaSource, type MediaInfo, type Dimensions, type LoudnessInfo, type FitBox, type GrabFrameOptions, type MeasureTextStyle, type TextMetrics, type StdlibMediaKind, type StdlibHostApi, } from './stdlib.js';
+export { default as xai } from './plugins/xai.js';
+export type { XaiPlugin, XaiVideoOptions, XaiImageOptions, XaiTtsOptions, XaiVoiceInfo, XaiVoiceList, XaiImageRef, XaiVideoResolution, XaiImageResolution, XaiVoiceId, XaiTtsCodec, } from './plugins/xai.js';
+export { default as cloudflare } from './plugins/cloudflare.js';
+export type { CloudflarePlugin, CloudflareVideoOptions, CloudflareImageOptions, CloudflareModelCatalog, CloudflareVideoModelInfo, CloudflareImageModelInfo, CloudflareVideoModel, CloudflareImageModel, } from './plugins/cloudflare.js';
+export { default as elevenlabsMusic } from './plugins/elevenlabs-music.js';
+export type { ElevenLabsMusicPlugin, ElevenLabsMusicOptions, ElevenLabsCompositionPlan, ElevenLabsMusicModel, ElevenLabsOutputFormat, } from './plugins/elevenlabs-music.js';
+export type { AspectRatio, MediaUrlRef, StringEnum, } from './plugins/types.js';
+export { default as transitions, transition } from './transitions/index.js';
+export type { TransitionsPlugin, TransitionCatalogEntry, TransitionFnName, } from './transitions/index.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}

package/dist/index.js

@@ -0,0 +1,22 @@
+/**
+ * @scenerok/sdk — TypeScript-first authoring for SceneRok.
+ *
+ * Agents use this for complex, data-driven scenes. Humans keep VidScript for
+ * short declarative scripts. Both emit the same IRTimeline for Pass 2.
+ */
+export { defaultIRTimeline, defaultIROutput } from './ir.js';
+export { Duration, s, ms, frames, toSeconds, } from './duration.js';
+export { isSdkNode, isSchedulable } from './types.js';
+export { video, loadVideo, text, audio, loadAudio, filter, shader } from './media.js';
+export { fadeIn, fadeOut, slideY, slideX, scale, popIn } from './motion.js';
+export { timeline, isTimeline } from './timeline.js';
+export { createIrBuilder, scheduleAt, resetIrBuilderIds, inferAutoDuration, assertSchedulable, bindTransitions, setGrid, } from './ir-builder.js';
+export { defaultGridSpec, resolveGridAreas, placementFromGridArea, placeInArea, } from './grid.js';
+// Media stdlib — host-injected at compile time (`@scenerok/stdlib` alias)
+export { getVideoLength, getAudioLength, getMediaInfo, getDimensions, getFps, getLoudness, hasAudio, mediaKind, grabFrame, grabFrames, grabFrameAtFraction, measureText, fitContain, fitCover, clampTime, parseTime, timecode, beats, } from './stdlib.js';
+// AI plugins — prefer package imports (`@scenerok/xai`, …); also re-exported for convenience
+export { default as xai } from './plugins/xai.js';
+export { default as cloudflare } from './plugins/cloudflare.js';
+export { default as elevenlabsMusic } from './plugins/elevenlabs-music.js';
+// Transitions — prefer `import tr from '@scenerok/transitions'`; also re-exported
+export { default as transitions, transition } from './transitions/index.js';

package/dist/ir-builder.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Shared IR builder — appends SDK nodes onto an IRTimeline.
+ * Used by @scenerok/sdk Timeline and (later) optionally by the VidScript compiler.
+ */
+import { type IRTimeline } from './ir.js';
+import { type TimeInput } from './duration.js';
+import { type GridAreaRect, type GridSpec } from './grid.js';
+import type { Schedulable, TimelineOptions } from './types.js';
+export declare function resetIrBuilderIds(seed?: number): void;
+export interface IrBuilderState {
+    ir: IRTimeline;
+    visualCursor: number;
+    audioCursor: number;
+    /** Named area rects (percent) from `timeline.grid(...)`; null until declared. */
+    gridAreas: Map<string, GridAreaRect> | null;
+}
+export declare function createIrBuilder(options?: TimelineOptions): IrBuilderState;
+/** Declare or replace the timeline grid used by `area:` text placement. */
+export declare function setGrid(state: IrBuilderState, spec: GridSpec): Map<string, GridAreaRect>;
+/**
+ * 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;
+export declare function assertSchedulable(value: unknown): asserts value is Schedulable;
+//# sourceMappingURL=ir-builder.d.ts.map

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

@@ -0,0 +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"}