@scenerok/sdk 0.2.0

package/dist/plugins/xai.js

@@ -0,0 +1,60 @@
+/**
+ * Client stubs for `@scenerok/xai` — same surface as VidScript `import xai from "@scenerok/xai"`.
+ * Host executes the real plugin via CompilerAPI during `scenerok validate/render`.
+ */
+import { invokeAudioPlugin, invokeDataPlugin, invokeVideoPlugin } from './invoke.js';
+const PKG = '@scenerok/xai';
+/** Text → video (Grok Imagine Video). */
+export function imagine(prompt, options) {
+    return invokeVideoPlugin(PKG, 'imagine', prompt, options ?? {});
+}
+/** Text → still image clip. */
+export function image(prompt, options) {
+    return invokeVideoPlugin(PKG, 'image', prompt, options ?? {});
+}
+export function generateImage(prompt, options) {
+    return invokeVideoPlugin(PKG, 'generateImage', prompt, options ?? {});
+}
+/** Text → video. */
+export function genVideo(prompt, options) {
+    return invokeVideoPlugin(PKG, 'genVideo', prompt, options ?? {});
+}
+/** Animate one image into video. */
+export function imageToVideo(imageSrc, prompt, options) {
+    if (prompt === undefined) {
+        return invokeVideoPlugin(PKG, 'imageToVideo', imageSrc, options ?? {});
+    }
+    return invokeVideoPlugin(PKG, 'imageToVideo', imageSrc, prompt, options ?? {});
+}
+/** Guide a scene with 1–7 reference images. */
+export function referenceToVideo(images, prompt, options) {
+    return invokeVideoPlugin(PKG, 'referenceToVideo', images, prompt, options ?? {});
+}
+/** Extend an existing video clip. */
+export function extendVideo(videoSrc, prompt, options) {
+    return invokeVideoPlugin(PKG, 'extendVideo', videoSrc, prompt, options ?? {});
+}
+/** Text → speech. */
+export function tts(text, options) {
+    return invokeAudioPlugin(PKG, 'tts', text, options ?? {});
+}
+export function textToSpeech(text, options) {
+    return invokeAudioPlugin(PKG, 'textToSpeech', text, options ?? {});
+}
+/** List available TTS voices. */
+export function listVoices() {
+    return invokeDataPlugin(PKG, 'listVoices');
+}
+const xai = {
+    imagine,
+    image,
+    generateImage,
+    genVideo,
+    imageToVideo,
+    referenceToVideo,
+    extendVideo,
+    tts,
+    textToSpeech,
+    listVoices,
+};
+export default xai;

package/dist/stdlib.d.ts

@@ -0,0 +1,96 @@
+/**
+ * Client-side stubs for `@scenerok/stdlib`.
+ * At compile time the SDK runtime injects `globalThis.__scenerokStdlib` with real host implementations.
+ */
+/** Path, URL, data URI, or any value the host can resolve to a media file. */
+export type MediaSource = string;
+export type StdlibMediaKind = 'video' | 'audio' | 'image' | 'unknown';
+export interface MediaInfo {
+    source: string;
+    kind: StdlibMediaKind;
+    duration: number | null;
+    width: number | null;
+    height: number | null;
+    fps: number | null;
+    hasAudio: boolean;
+    codec: string | null;
+    audioCodec: string | null;
+}
+export interface Dimensions {
+    width: number;
+    height: number;
+}
+export interface LoudnessInfo {
+    integratedLufs: number | null;
+    truePeakDb: number | null;
+    loudnessRange: number | null;
+    duration: number | null;
+}
+export interface FitBox {
+    width: number;
+    height: number;
+    x: number;
+    y: number;
+}
+export interface GrabFrameOptions {
+    /** Output width in pixels (height scales). Default 720. */
+    width?: number;
+    /** JPEG quality 2–31 (ffmpeg -q:v). Default 5. */
+    quality?: number;
+    /** Prefer data URL instead of uploading. Default true for SDK/local. */
+    asDataUrl?: boolean;
+}
+export interface MeasureTextStyle {
+    font?: string;
+    size?: number;
+    bold?: boolean;
+    italic?: boolean;
+    letterSpacing?: number;
+    lineHeight?: number;
+    maxWidth?: number;
+}
+export interface TextMetrics {
+    width: number;
+    height: number;
+    lines?: number;
+}
+/** Full host API injected as `globalThis.__scenerokStdlib`. */
+export interface StdlibHostApi {
+    getVideoLength(src: MediaSource): Promise<number>;
+    getAudioLength(src: MediaSource): Promise<number>;
+    getMediaInfo(src: MediaSource): Promise<MediaInfo>;
+    getDimensions(src: MediaSource): Promise<Dimensions>;
+    getFps(src: MediaSource): Promise<number | null>;
+    getLoudness(src: MediaSource): Promise<LoudnessInfo>;
+    hasAudio(src: MediaSource): Promise<boolean>;
+    mediaKind(src: MediaSource): Promise<StdlibMediaKind>;
+    grabFrame(src: MediaSource, time: number, options?: GrabFrameOptions): Promise<string>;
+    grabFrames(src: MediaSource, times: readonly number[], options?: GrabFrameOptions): Promise<string[]>;
+    grabFrameAtFraction(src: MediaSource, fraction: number, options?: GrabFrameOptions): Promise<string>;
+    measureText(content: string, style?: MeasureTextStyle): Promise<TextMetrics>;
+    fitContain(srcW: number, srcH: number, boxW: number, boxH: number): FitBox;
+    fitCover(srcW: number, srcH: number, boxW: number, boxH: number): FitBox;
+    clampTime(t: number, duration: number): number;
+    parseTime(value: number | string): number;
+    timecode(seconds: number): string;
+    beats(bpm: number, count: number): number;
+}
+export declare function getVideoLength(src: MediaSource): Promise<number>;
+export declare function getAudioLength(src: MediaSource): Promise<number>;
+export declare function getMediaInfo(src: MediaSource): Promise<MediaInfo>;
+export declare function getDimensions(src: MediaSource): Promise<Dimensions>;
+export declare function getFps(src: MediaSource): Promise<number | null>;
+export declare function getLoudness(src: MediaSource): Promise<LoudnessInfo>;
+export declare function hasAudio(src: MediaSource): Promise<boolean>;
+export declare function mediaKind(src: MediaSource): Promise<StdlibMediaKind>;
+export declare function grabFrame(src: MediaSource, time: number, options?: GrabFrameOptions): Promise<string>;
+export declare function grabFrames(src: MediaSource, times: readonly number[], options?: GrabFrameOptions): Promise<string[]>;
+export declare function grabFrameAtFraction(src: MediaSource, fraction: number, options?: GrabFrameOptions): Promise<string>;
+export declare function measureText(content: string, style?: MeasureTextStyle): Promise<TextMetrics>;
+export declare function fitContain(srcW: number, srcH: number, boxW: number, boxH: number): FitBox;
+export declare function fitCover(srcW: number, srcH: number, boxW: number, boxH: number): FitBox;
+export declare function clampTime(t: number, duration: number): number;
+export declare function parseTime(value: number | string): number;
+export declare function timecode(seconds: number): string;
+export declare function beats(bpm: number, count: number): number;
+//# sourceMappingURL=stdlib.d.ts.map

package/dist/stdlib.d.ts.map

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

package/dist/stdlib.js

@@ -0,0 +1,66 @@
+/**
+ * Client-side stubs for `@scenerok/stdlib`.
+ * At compile time the SDK runtime injects `globalThis.__scenerokStdlib` with real host implementations.
+ */
+function host() {
+    const h = globalThis.__scenerokStdlib;
+    if (!h) {
+        throw new Error('@scenerok/stdlib is only available when compiling via SceneRok (scenerok validate/render). '
+            + 'Host bindings were not injected.');
+    }
+    return h;
+}
+export function getVideoLength(src) {
+    return host().getVideoLength(src);
+}
+export function getAudioLength(src) {
+    return host().getAudioLength(src);
+}
+export function getMediaInfo(src) {
+    return host().getMediaInfo(src);
+}
+export function getDimensions(src) {
+    return host().getDimensions(src);
+}
+export function getFps(src) {
+    return host().getFps(src);
+}
+export function getLoudness(src) {
+    return host().getLoudness(src);
+}
+export function hasAudio(src) {
+    return host().hasAudio(src);
+}
+export function mediaKind(src) {
+    return host().mediaKind(src);
+}
+export function grabFrame(src, time, options) {
+    return host().grabFrame(src, time, options);
+}
+export function grabFrames(src, times, options) {
+    return host().grabFrames(src, times, options);
+}
+export function grabFrameAtFraction(src, fraction, options) {
+    return host().grabFrameAtFraction(src, fraction, options);
+}
+export function measureText(content, style) {
+    return host().measureText(content, style);
+}
+export function fitContain(srcW, srcH, boxW, boxH) {
+    return host().fitContain(srcW, srcH, boxW, boxH);
+}
+export function fitCover(srcW, srcH, boxW, boxH) {
+    return host().fitCover(srcW, srcH, boxW, boxH);
+}
+export function clampTime(t, duration) {
+    return host().clampTime(t, duration);
+}
+export function parseTime(value) {
+    return host().parseTime(value);
+}
+export function timecode(seconds) {
+    return host().timecode(seconds);
+}
+export function beats(bpm, count) {
+    return host().beats(bpm, count);
+}

package/dist/timeline.d.ts

@@ -0,0 +1,27 @@
+import { type TimeInput } from './duration.js';
+import type { GridSpec } from './grid.js';
+import type { IRTimeline } from './ir.js';
+import type { RangeBinder, Schedulable, TimelineLike, TimelineOptions } from './types.js';
+export interface Timeline extends TimelineLike {
+    /** Dual-index schedule: `t[start][end] = value` */
+    [start: string | number | symbol]: RangeBinder | Schedulable | unknown;
+    grid(spec: GridSpec): this;
+    range(start: TimeInput, end: TimeInput, value: Schedulable): this;
+    push(value: Schedulable, duration?: TimeInput): this;
+    toIR(): IRTimeline;
+}
+/**
+ * Create a timeline. Schedule with dual-index assignment:
+ *
+ * ```ts
+ * const t = timeline({ width: 1080, height: 1920, fps: 30 })
+ * t.grid({ rows: '20% 1fr 30%', areas: ['title', 'stage', 'caption'] })
+ * t[0][scene.duration] = scene
+ * t['0s']['3s'] = text('Hello', { area: 'title' })
+ * t.push(text('Tail'))
+ * return t.toIR()
+ * ```
+ */
+export declare function timeline(options?: TimelineOptions): Timeline;
+export declare function isTimeline(value: unknown): value is Timeline;
+//# sourceMappingURL=timeline.d.ts.map

package/dist/timeline.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"timeline.d.ts","sourceRoot":"","sources":["../src/timeline.ts"],"names":[],"mappings":"AAAA,OAAO,EAAgC,KAAK,SAAS,EAAE,MAAM,eAAe,CAAC;AAU7E,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,WAAW,CAAC;AAC1C,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,SAAS,CAAC;AAC1C,OAAO,KAAK,EACV,WAAW,EACX,WAAW,EACX,YAAY,EACZ,eAAe,EAEhB,MAAM,YAAY,CAAC;AAkCpB,MAAM,WAAW,QAAS,SAAQ,YAAY;IAC5C,mDAAmD;IACnD,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,GAAG,MAAM,GAAG,WAAW,GAAG,WAAW,GAAG,OAAO,CAAC;IACvE,IAAI,CAAC,IAAI,EAAE,QAAQ,GAAG,IAAI,CAAC;IAC3B,KAAK,CAAC,KAAK,EAAE,SAAS,EAAE,GAAG,EAAE,SAAS,EAAE,KAAK,EAAE,WAAW,GAAG,IAAI,CAAC;IAClE,IAAI,CAAC,KAAK,EAAE,WAAW,EAAE,QAAQ,CAAC,EAAE,SAAS,GAAG,IAAI,CAAC;IACrD,IAAI,IAAI,UAAU,CAAC;CACpB;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,QAAQ,CAAC,OAAO,GAAE,eAAoB,GAAG,QAAQ,CA2EhE;AAED,wBAAgB,UAAU,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,QAAQ,CAO5D"}

package/dist/timeline.js

@@ -0,0 +1,117 @@
+import { isAutoPlayheadKey, toSeconds } from './duration.js';
+import { assertSchedulable, bindTransitions, createIrBuilder, inferAutoDuration, scheduleAt, setGrid, } from './ir-builder.js';
+const INTERNAL = Symbol('scenerok.timeline.internal');
+function parseTimeKey(key) {
+    if (isAutoPlayheadKey(key))
+        return 'auto';
+    if (typeof key === 'symbol') {
+        throw new TypeError('Timeline keys must be numbers, Duration, time strings, or "-"');
+    }
+    return toSeconds(key);
+}
+function createRangeBinder(internal, start) {
+    return new Proxy({}, {
+        set(_target, endKey, value) {
+            assertSchedulable(value);
+            const endParsed = parseTimeKey(endKey);
+            if (endParsed === 'auto') {
+                throw new TypeError('End time cannot be auto-playhead "-"');
+            }
+            scheduleAt(internal.state, start, endParsed, value);
+            return true;
+        },
+        get() {
+            return undefined;
+        },
+    });
+}
+/**
+ * Create a timeline. Schedule with dual-index assignment:
+ *
+ * ```ts
+ * const t = timeline({ width: 1080, height: 1920, fps: 30 })
+ * t.grid({ rows: '20% 1fr 30%', areas: ['title', 'stage', 'caption'] })
+ * t[0][scene.duration] = scene
+ * t['0s']['3s'] = text('Hello', { area: 'title' })
+ * t.push(text('Tail'))
+ * return t.toIR()
+ * ```
+ */
+export function timeline(options = {}) {
+    const internal = {
+        state: createIrBuilder(options),
+        options: { ...options },
+    };
+    const api = {
+        __sdk: true,
+        kind: 'timeline',
+        options: internal.options,
+        get duration() {
+            return internal.state.ir.duration;
+        },
+        get length() {
+            return internal.state.ir.duration;
+        },
+        grid(spec) {
+            setGrid(internal.state, spec);
+            return proxy;
+        },
+        range(start, end, value) {
+            assertSchedulable(value);
+            scheduleAt(internal.state, toSeconds(start), toSeconds(end), value);
+            return proxy;
+        },
+        push(value, duration) {
+            assertSchedulable(value);
+            const start = value.kind === 'audio'
+                ? internal.state.audioCursor
+                : internal.state.visualCursor;
+            const span = inferAutoDuration(value, duration);
+            scheduleAt(internal.state, start, start + span, value);
+            return proxy;
+        },
+        toIR() {
+            // Bind transition fromId/toId now that all clips are present (incl. nested remaps).
+            bindTransitions(internal.state.ir);
+            // JSON clone — works in isolated-vm (no structuredClone) and strips non-JSON.
+            return JSON.parse(JSON.stringify(internal.state.ir));
+        },
+    };
+    const proxy = new Proxy(api, {
+        get(target, prop, receiver) {
+            if (prop === INTERNAL)
+                return internal;
+            if (prop in target || typeof prop === 'symbol') {
+                return Reflect.get(target, prop, receiver);
+            }
+            const startParsed = parseTimeKey(prop);
+            if (startParsed === 'auto') {
+                // `t['-'] = value` — auto-append
+                return undefined;
+            }
+            return createRangeBinder(internal, startParsed);
+        },
+        set(target, prop, value, receiver) {
+            if (prop in api && prop !== 'duration' && prop !== 'length') {
+                return Reflect.set(target, prop, value, receiver);
+            }
+            if (isAutoPlayheadKey(prop)) {
+                assertSchedulable(value);
+                api.push(value);
+                return true;
+            }
+            // Single-index set is not supported (would be ambiguous). Guide users to dual-index.
+            throw new TypeError('Use t[start][end] = value, t.range(start, end, value), or t["-"] = value / t.push(value)');
+        },
+        has(target, prop) {
+            return prop in target || prop === INTERNAL;
+        },
+    });
+    return proxy;
+}
+export function isTimeline(value) {
+    return (typeof value === 'object'
+        && value !== null
+        && value.__sdk === true
+        && value.kind === 'timeline');
+}

package/dist/transitions/catalog.d.ts

@@ -0,0 +1,33 @@
+/**
+ * @scenerok/transitions catalog — shared by VidScript plugin and TypeScript SDK.
+ *
+ * Each entry maps `tr.<fn>(...)` to a native two-texture GL pass that blends a
+ * "from" clip into a "to" clip using a GLSL shader.
+ */
+export interface CatalogParam {
+    name: string;
+    default: string;
+}
+export interface TransitionCatalogEntry {
+    /** Public function name: tr.<fn>(...) */
+    fn: string;
+    /** Shader library key used by the render engine */
+    shaderName: string;
+    /** Default duration in seconds (used by auto-append / push) */
+    defaultDuration: number;
+    width: number;
+    height: number;
+    /** Positional args (in order) map to these param names. */
+    positional: string[];
+    params: CatalogParam[];
+}
+/** Common params shared by every transition function. */
+export declare const TRANSITION_COMMON_PARAMS: CatalogParam[];
+/**
+ * Every transition: 0.6 s default, 1920×1080, four common named params.
+ * fn names are the public API (WITHOUT the `tr.` prefix).
+ */
+export declare const TRANSITIONS: TransitionCatalogEntry[];
+export type TransitionFnName = (typeof TRANSITIONS)[number]['fn'];
+export declare function getTransitionEntry(fn: string): TransitionCatalogEntry | undefined;
+//# sourceMappingURL=catalog.d.ts.map

package/dist/transitions/catalog.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"catalog.d.ts","sourceRoot":"","sources":["../../src/transitions/catalog.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,MAAM,WAAW,YAAY;IAC3B,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,sBAAsB;IACrC,yCAAyC;IACzC,EAAE,EAAE,MAAM,CAAC;IACX,mDAAmD;IACnD,UAAU,EAAE,MAAM,CAAC;IACnB,+DAA+D;IAC/D,eAAe,EAAE,MAAM,CAAC;IACxB,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,CAAC;IACf,2DAA2D;IAC3D,UAAU,EAAE,MAAM,EAAE,CAAC;IACrB,MAAM,EAAE,YAAY,EAAE,CAAC;CACxB;AAED,yDAAyD;AACzD,eAAO,MAAM,wBAAwB,EAAE,YAAY,EAKlD,CAAC;AAEF;;;GAGG;AACH,eAAO,MAAM,WAAW,EAAE,sBAAsB,EA8B/C,CAAC;AAEF,MAAM,MAAM,gBAAgB,GAAG,CAAC,OAAO,WAAW,CAAC,CAAC,MAAM,CAAC,CAAC,IAAI,CAAC,CAAC;AAElE,wBAAgB,kBAAkB,CAAC,EAAE,EAAE,MAAM,GAAG,sBAAsB,GAAG,SAAS,CAEjF"}

package/dist/transitions/catalog.js

@@ -0,0 +1,51 @@
+/**
+ * @scenerok/transitions catalog — shared by VidScript plugin and TypeScript SDK.
+ *
+ * Each entry maps `tr.<fn>(...)` to a native two-texture GL pass that blends a
+ * "from" clip into a "to" clip using a GLSL shader.
+ */
+/** Common params shared by every transition function. */
+export const TRANSITION_COMMON_PARAMS = [
+    { name: 'direction', default: '' },
+    { name: 'ease', default: 'power2' },
+    { name: 'strength', default: '' },
+    { name: 'mode', default: '' },
+];
+/**
+ * Every transition: 0.6 s default, 1920×1080, four common named params.
+ * fn names are the public API (WITHOUT the `tr.` prefix).
+ */
+export const TRANSITIONS = [
+    { fn: 'dissolve', shaderName: 'dissolve', defaultDuration: 0.6, width: 1920, height: 1080, positional: [], params: TRANSITION_COMMON_PARAMS },
+    { fn: 'push', shaderName: 'push', defaultDuration: 0.6, width: 1920, height: 1080, positional: [], params: TRANSITION_COMMON_PARAMS },
+    { fn: 'cover', shaderName: 'cover', defaultDuration: 0.6, width: 1920, height: 1080, positional: [], params: TRANSITION_COMMON_PARAMS },
+    { fn: 'radial', shaderName: 'radial', defaultDuration: 0.6, width: 1920, height: 1080, positional: [], params: TRANSITION_COMMON_PARAMS },
+    { fn: 'grid', shaderName: 'grid', defaultDuration: 0.6, width: 1920, height: 1080, positional: [], params: TRANSITION_COMMON_PARAMS },
+    { fn: 'scale', shaderName: 'scale', defaultDuration: 0.6, width: 1920, height: 1080, positional: [], params: TRANSITION_COMMON_PARAMS },
+    { fn: 'cube', shaderName: 'cube', defaultDuration: 0.6, width: 1920, height: 1080, positional: [], params: TRANSITION_COMMON_PARAMS },
+    { fn: 'blur', shaderName: 'blur', defaultDuration: 0.6, width: 1920, height: 1080, positional: [], params: TRANSITION_COMMON_PARAMS },
+    { fn: 'distortion', shaderName: 'distortion', defaultDuration: 0.6, width: 1920, height: 1080, positional: [], params: TRANSITION_COMMON_PARAMS },
+    { fn: 'destruction', shaderName: 'destruction', defaultDuration: 0.6, width: 1920, height: 1080, positional: [], params: TRANSITION_COMMON_PARAMS },
+    { fn: 'light', shaderName: 'light', defaultDuration: 0.6, width: 1920, height: 1080, positional: [], params: TRANSITION_COMMON_PARAMS },
+    { fn: 'mechanical', shaderName: 'mechanical', defaultDuration: 0.6, width: 1920, height: 1080, positional: [], params: TRANSITION_COMMON_PARAMS },
+    { fn: 'wipe', shaderName: 'wipe', defaultDuration: 0.6, width: 1920, height: 1080, positional: [], params: TRANSITION_COMMON_PARAMS },
+    { fn: 'cinematic_zoom', shaderName: 'cinematic_zoom', defaultDuration: 0.6, width: 1920, height: 1080, positional: [], params: TRANSITION_COMMON_PARAMS },
+    { fn: 'whip_pan', shaderName: 'whip_pan', defaultDuration: 0.6, width: 1920, height: 1080, positional: [], params: TRANSITION_COMMON_PARAMS },
+    { fn: 'light_leak', shaderName: 'light_leak', defaultDuration: 0.6, width: 1920, height: 1080, positional: [], params: TRANSITION_COMMON_PARAMS },
+    { fn: 'flash', shaderName: 'flash', defaultDuration: 0.6, width: 1920, height: 1080, positional: [], params: TRANSITION_COMMON_PARAMS },
+    { fn: 'warp_morph', shaderName: 'warp_morph', defaultDuration: 0.6, width: 1920, height: 1080, positional: [], params: TRANSITION_COMMON_PARAMS },
+    { fn: 'domain_warp', shaderName: 'domain_warp', defaultDuration: 0.6, width: 1920, height: 1080, positional: [], params: TRANSITION_COMMON_PARAMS },
+    { fn: 'chromatic_split', shaderName: 'chromatic_split', defaultDuration: 0.6, width: 1920, height: 1080, positional: [], params: TRANSITION_COMMON_PARAMS },
+    { fn: 'lens', shaderName: 'lens', defaultDuration: 0.6, width: 1920, height: 1080, positional: [], params: TRANSITION_COMMON_PARAMS },
+    { fn: 'glitch', shaderName: 'glitch', defaultDuration: 0.6, width: 1920, height: 1080, positional: [], params: TRANSITION_COMMON_PARAMS },
+    { fn: 'swirl', shaderName: 'swirl', defaultDuration: 0.6, width: 1920, height: 1080, positional: [], params: TRANSITION_COMMON_PARAMS },
+    { fn: 'thermal', shaderName: 'thermal', defaultDuration: 0.6, width: 1920, height: 1080, positional: [], params: TRANSITION_COMMON_PARAMS },
+    { fn: 'ripple', shaderName: 'ripple', defaultDuration: 0.6, width: 1920, height: 1080, positional: [], params: TRANSITION_COMMON_PARAMS },
+    { fn: 'iris', shaderName: 'iris', defaultDuration: 0.6, width: 1920, height: 1080, positional: [], params: TRANSITION_COMMON_PARAMS },
+    { fn: 'burn', shaderName: 'burn', defaultDuration: 0.6, width: 1920, height: 1080, positional: [], params: TRANSITION_COMMON_PARAMS },
+    { fn: 'shatter', shaderName: 'shatter', defaultDuration: 0.6, width: 1920, height: 1080, positional: [], params: TRANSITION_COMMON_PARAMS },
+    { fn: 'liquid', shaderName: 'liquid', defaultDuration: 0.6, width: 1920, height: 1080, positional: [], params: TRANSITION_COMMON_PARAMS },
+];
+export function getTransitionEntry(fn) {
+    return TRANSITIONS.find((entry) => entry.fn === fn);
+}

package/dist/transitions/index.d.ts

@@ -0,0 +1,62 @@
+/**
+ * Client factories for `@scenerok/transitions`.
+ *
+ * Same surface as VidScript `import tr from "@scenerok/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 })
+ * ```
+ *
+ * A transition window binds the clip active at start (from) and end (to).
+ * Binding runs in `timeline.toIR()` after all clips are scheduled.
+ */
+import { type TimeInput } from '../duration.js';
+import { type TransitionFnName } from './catalog.js';
+import type { TransitionEffect, TransitionOptions } from '../types.js';
+/** Create a transition by catalog function name. */
+export declare function transition(fn: TransitionFnName | string, options?: TransitionOptions): TransitionEffect;
+type TransitionFactory = (options?: TransitionOptions) => TransitionEffect;
+export interface TransitionsPlugin {
+    dissolve: TransitionFactory;
+    push: TransitionFactory;
+    cover: TransitionFactory;
+    radial: TransitionFactory;
+    grid: TransitionFactory;
+    scale: TransitionFactory;
+    cube: TransitionFactory;
+    blur: TransitionFactory;
+    distortion: TransitionFactory;
+    destruction: TransitionFactory;
+    light: TransitionFactory;
+    mechanical: TransitionFactory;
+    wipe: TransitionFactory;
+    cinematic_zoom: TransitionFactory;
+    whip_pan: TransitionFactory;
+    light_leak: TransitionFactory;
+    flash: TransitionFactory;
+    warp_morph: TransitionFactory;
+    domain_warp: TransitionFactory;
+    chromatic_split: TransitionFactory;
+    lens: TransitionFactory;
+    glitch: TransitionFactory;
+    swirl: TransitionFactory;
+    thermal: TransitionFactory;
+    ripple: TransitionFactory;
+    iris: TransitionFactory;
+    burn: TransitionFactory;
+    shatter: TransitionFactory;
+    liquid: TransitionFactory;
+    /** Lookup by name — same as `transition(fn, options)`. */
+    transition: typeof transition;
+}
+declare const tr: TransitionsPlugin;
+export { TRANSITIONS, TRANSITION_COMMON_PARAMS, getTransitionEntry, type CatalogParam, type TransitionCatalogEntry, type TransitionFnName, } from './catalog.js';
+export type { TransitionEffect, TransitionOptions } from '../types.js';
+export type { TimeInput };
+export default tr;
+//# sourceMappingURL=index.d.ts.map

package/dist/transitions/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/transitions/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAEH,OAAO,EAAa,KAAK,SAAS,EAAE,MAAM,gBAAgB,CAAC;AAC3D,OAAO,EAIL,KAAK,gBAAgB,EACtB,MAAM,cAAc,CAAC;AACtB,OAAO,KAAK,EAAE,gBAAgB,EAAE,iBAAiB,EAAE,MAAM,aAAa,CAAC;AAsBvE,oDAAoD;AACpD,wBAAgB,UAAU,CAAC,EAAE,EAAE,gBAAgB,GAAG,MAAM,EAAE,OAAO,CAAC,EAAE,iBAAiB,GAAG,gBAAgB,CAOvG;AAED,KAAK,iBAAiB,GAAG,CAAC,OAAO,CAAC,EAAE,iBAAiB,KAAK,gBAAgB,CAAC;AAM3E,MAAM,WAAW,iBAAiB;IAChC,QAAQ,EAAE,iBAAiB,CAAC;IAC5B,IAAI,EAAE,iBAAiB,CAAC;IACxB,KAAK,EAAE,iBAAiB,CAAC;IACzB,MAAM,EAAE,iBAAiB,CAAC;IAC1B,IAAI,EAAE,iBAAiB,CAAC;IACxB,KAAK,EAAE,iBAAiB,CAAC;IACzB,IAAI,EAAE,iBAAiB,CAAC;IACxB,IAAI,EAAE,iBAAiB,CAAC;IACxB,UAAU,EAAE,iBAAiB,CAAC;IAC9B,WAAW,EAAE,iBAAiB,CAAC;IAC/B,KAAK,EAAE,iBAAiB,CAAC;IACzB,UAAU,EAAE,iBAAiB,CAAC;IAC9B,IAAI,EAAE,iBAAiB,CAAC;IACxB,cAAc,EAAE,iBAAiB,CAAC;IAClC,QAAQ,EAAE,iBAAiB,CAAC;IAC5B,UAAU,EAAE,iBAAiB,CAAC;IAC9B,KAAK,EAAE,iBAAiB,CAAC;IACzB,UAAU,EAAE,iBAAiB,CAAC;IAC9B,WAAW,EAAE,iBAAiB,CAAC;IAC/B,eAAe,EAAE,iBAAiB,CAAC;IACnC,IAAI,EAAE,iBAAiB,CAAC;IACxB,MAAM,EAAE,iBAAiB,CAAC;IAC1B,KAAK,EAAE,iBAAiB,CAAC;IACzB,OAAO,EAAE,iBAAiB,CAAC;IAC3B,MAAM,EAAE,iBAAiB,CAAC;IAC1B,IAAI,EAAE,iBAAiB,CAAC;IACxB,IAAI,EAAE,iBAAiB,CAAC;IACxB,OAAO,EAAE,iBAAiB,CAAC;IAC3B,MAAM,EAAE,iBAAiB,CAAC;IAC1B,0DAA0D;IAC1D,UAAU,EAAE,OAAO,UAAU,CAAC;CAC/B;AAQD,QAAA,MAAM,EAAE,EAGH,iBAAiB,CAAC;AAEvB,OAAO,EACL,WAAW,EACX,wBAAwB,EACxB,kBAAkB,EAClB,KAAK,YAAY,EACjB,KAAK,sBAAsB,EAC3B,KAAK,gBAAgB,GACtB,MAAM,cAAc,CAAC;AAEtB,YAAY,EAAE,gBAAgB,EAAE,iBAAiB,EAAE,MAAM,aAAa,CAAC;AACvE,YAAY,EAAE,SAAS,EAAE,CAAC;AAE1B,eAAe,EAAE,CAAC"}

package/dist/transitions/index.js

@@ -0,0 +1,57 @@
+/**
+ * Client factories for `@scenerok/transitions`.
+ *
+ * Same surface as VidScript `import tr from "@scenerok/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 })
+ * ```
+ *
+ * A transition window binds the clip active at start (from) and end (to).
+ * Binding runs in `timeline.toIR()` after all clips are scheduled.
+ */
+import { toSeconds } from '../duration.js';
+import { getTransitionEntry, TRANSITIONS, } from './catalog.js';
+function resolveDuration(entry, options) {
+    if (options.duration !== undefined)
+        return toSeconds(options.duration);
+    return entry.defaultDuration;
+}
+function buildTransition(entry, options = {}) {
+    const duration = resolveDuration(entry, options);
+    return {
+        __sdk: true,
+        kind: 'transition',
+        name: entry.fn,
+        shaderName: entry.shaderName,
+        options: { ...options },
+        duration,
+        with(opts) {
+            return buildTransition(entry, { ...options, ...opts });
+        },
+    };
+}
+/** Create a transition by catalog function name. */
+export function transition(fn, options) {
+    const entry = getTransitionEntry(fn);
+    if (!entry) {
+        const known = TRANSITIONS.map((t) => t.fn).join(', ');
+        throw new Error(`Unknown transition '${fn}' (available: ${known})`);
+    }
+    return buildTransition(entry, options ?? {});
+}
+function makeFactory(entry) {
+    return (options) => buildTransition(entry, options ?? {});
+}
+const factories = Object.fromEntries(TRANSITIONS.map((entry) => [entry.fn, makeFactory(entry)]));
+const tr = {
+    ...factories,
+    transition,
+};
+export { TRANSITIONS, TRANSITION_COMMON_PARAMS, getTransitionEntry, } from './catalog.js';
+export default tr;