@motionscript/browser 0.0.0-stage → 0.1.0-alpha.10

package/dist/renderer.js

@@ -0,0 +1,23 @@
+import { createWgpuRenderer, isWgpuSupported } from "@motionscript/renderer";
+import { loadAssetBytes } from "./asset-bytes";
+/**
+ * This browser cannot run the WebGPU renderer: no `navigator.gpu`, or no
+ * adapter behind it. Every entry that draws (an engine, a still, an export,
+ * a timeline's audio mix) rejects with it before drawing anything.
+ */
+export class WebGpuUnavailableError extends Error {
+    constructor() {
+        super("Motion Script draws with WebGPU, and this browser has no WebGPU adapter.");
+        this.name = "WebGpuUnavailableError";
+    }
+}
+/**
+ * The renderer every entry draws with, or {@link WebGpuUnavailableError}.
+ * `gpu: false` is for an entry that only measures text, which needs no device.
+ */
+export async function loadRenderer(options = {}, { gpu = true } = {}) {
+    if (gpu && !(await isWgpuSupported()))
+        throw new WebGpuUnavailableError();
+    return createWgpuRenderer({ wasmUrl: options.rendererWasmUrl, loadBytes: loadAssetBytes });
+}
+//# sourceMappingURL=renderer.js.map

package/dist/renderer.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"renderer.js","sourceRoot":"","sources":["../src/renderer.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,kBAAkB,EAAE,eAAe,EAAqB,MAAM,wBAAwB,CAAC;AAChG,OAAO,EAAE,cAAc,EAAE,MAAM,eAAe,CAAC;AAQ/C;;;;GAIG;AACH,MAAM,OAAO,sBAAuB,SAAQ,KAAK;IAC7C;QACI,KAAK,CAAC,0EAA0E,CAAC,CAAC;QAClF,IAAI,CAAC,IAAI,GAAG,wBAAwB,CAAC;IACzC,CAAC;CACJ;AAED;;;GAGG;AACH,MAAM,CAAC,KAAK,UAAU,YAAY,CAAC,UAA8B,EAAE,EAAE,EAAE,GAAG,GAAG,IAAI,EAAE,GAAG,EAAE;IACpF,IAAI,GAAG,IAAI,CAAC,CAAC,MAAM,eAAe,EAAE,CAAC;QAAE,MAAM,IAAI,sBAAsB,EAAE,CAAC;IAC1E,OAAO,kBAAkB,CAAC,EAAE,OAAO,EAAE,OAAO,CAAC,eAAe,EAAE,SAAS,EAAE,cAAc,EAAE,CAAC,CAAC;AAC/F,CAAC","sourcesContent":["import { createWgpuRenderer, isWgpuSupported, type WgpuRenderer } from \"@motionscript/renderer\";\nimport { loadAssetBytes } from \"./asset-bytes\";\n\n/** Where the renderer's WebAssembly is served, for every entry that draws. */\nexport interface RendererWasmOption {\n    /** URL of `ms_renderer_bg.wasm`; defaults to beside `@motionscript/renderer`'s module, which a bundler resolves. */\n    rendererWasmUrl?: string | URL;\n}\n\n/**\n * This browser cannot run the WebGPU renderer: no `navigator.gpu`, or no\n * adapter behind it. Every entry that draws (an engine, a still, an export,\n * a timeline's audio mix) rejects with it before drawing anything.\n */\nexport class WebGpuUnavailableError extends Error {\n    constructor() {\n        super(\"Motion Script draws with WebGPU, and this browser has no WebGPU adapter.\");\n        this.name = \"WebGpuUnavailableError\";\n    }\n}\n\n/**\n * The renderer every entry draws with, or {@link WebGpuUnavailableError}.\n * `gpu: false` is for an entry that only measures text, which needs no device.\n */\nexport async function loadRenderer(options: RendererWasmOption = {}, { gpu = true } = {}): Promise<WgpuRenderer> {\n    if (gpu && !(await isWgpuSupported())) throw new WebGpuUnavailableError();\n    return createWgpuRenderer({ wasmUrl: options.rendererWasmUrl, loadBytes: loadAssetBytes });\n}\n"]}

package/dist/screenshot.d.ts

@@ -0,0 +1,45 @@
+import { type AssetManifest, type FrameSpec, type ProjectDocument, type Registry, type VisualDocument, type Size2D, type Theme } from "@motionscript/core";
+import type { ScreenshotFormat } from "./frame-loop";
+import type { RendererWasmOption } from "./renderer";
+import { type FrameRef } from "./still";
+export type { ScreenshotFormat, FrameSpec };
+export type ScreenshotParams = RendererWasmOption & {
+    /** A project, or a lone still or composition as the one track of one. */
+    document: ProjectDocument | VisualDocument;
+    /** The vocabulary its clips compile against. Defaults to what the library ships. */
+    registry?: Registry;
+    /** Win over the document's own; 1920×1080 at 60 fps when neither says. */
+    viewport?: Size2D;
+    fps?: number;
+    scale?: number;
+    manifest?: AssetManifest;
+    /** Theme for a document that carries none of its own. */
+    theme?: Theme;
+    /** Which frame to capture. Defaults to the timeline's first. */
+    frame?: FrameRef;
+    /** Encoding format (default "png"). */
+    format?: ScreenshotFormat;
+    /** JPEG quality in [0,1] (ignored for png; default 0.92). */
+    quality?: number;
+};
+export type ScreenshotResult = {
+    /** The project frame that was captured, after clamping. */
+    frame: number;
+    totalFrames: number;
+    /** Encoded image bytes. */
+    bytes: Uint8Array;
+};
+/**
+ * Renders a single frame of a document to an image.
+ *
+ * A one-shot wrapper over {@link StillRenderer}: create, render, encode, dispose.
+ * It therefore takes the same path as a live preview, and as the video export at
+ * that frame — there is one renderer, not three.
+ *
+ * For anything that captures **repeatedly** — a thumbnail builder, a preview that
+ * repaints as the user edits — hold a {@link StillRenderer} instead. This function
+ * builds and tears down a WebGPU surface per call, which is the right trade for one
+ * capture and the wrong one for a hundred.
+ */
+export declare function exportScreenshot(params: ScreenshotParams): Promise<ScreenshotResult>;
+//# sourceMappingURL=screenshot.d.ts.map

package/dist/screenshot.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"screenshot.d.ts","sourceRoot":"","sources":["../src/screenshot.ts"],"names":[],"mappings":"AAAA,OAAO,EAEH,KAAK,aAAa,EAAE,KAAK,SAAS,EAAE,KAAK,eAAe,EAAE,KAAK,QAAQ,EAAE,KAAK,cAAc,EAAE,KAAK,MAAM,EAAE,KAAK,KAAK,EACxH,MAAM,oBAAoB,CAAC;AAC5B,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,cAAc,CAAC;AACrD,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,YAAY,CAAC;AACrD,OAAO,EAAuB,KAAK,QAAQ,EAAE,MAAM,SAAS,CAAC;AAE7D,YAAY,EAAE,gBAAgB,EAAE,SAAS,EAAE,CAAC;AAE5C,MAAM,MAAM,gBAAgB,GAAG,kBAAkB,GAAG;IAChD,yEAAyE;IACzE,QAAQ,EAAE,eAAe,GAAG,cAAc,CAAC;IAC3C,oFAAoF;IACpF,QAAQ,CAAC,EAAE,QAAQ,CAAC;IACpB,0EAA0E;IAC1E,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,QAAQ,CAAC,EAAE,aAAa,CAAC;IACzB,yDAAyD;IACzD,KAAK,CAAC,EAAE,KAAK,CAAC;IACd,gEAAgE;IAChE,KAAK,CAAC,EAAE,QAAQ,CAAC;IACjB,uCAAuC;IACvC,MAAM,CAAC,EAAE,gBAAgB,CAAC;IAC1B,6DAA6D;IAC7D,OAAO,CAAC,EAAE,MAAM,CAAC;CACpB,CAAC;AAEF,MAAM,MAAM,gBAAgB,GAAG;IAC3B,2DAA2D;IAC3D,KAAK,EAAE,MAAM,CAAC;IACd,WAAW,EAAE,MAAM,CAAC;IACpB,2BAA2B;IAC3B,KAAK,EAAE,UAAU,CAAC;CACrB,CAAC;AAEF;;;;;;;;;;;GAWG;AACH,wBAAsB,gBAAgB,CAAC,MAAM,EAAE,gBAAgB,GAAG,OAAO,CAAC,gBAAgB,CAAC,CAmB1F"}

package/dist/screenshot.js

@@ -0,0 +1,31 @@
+import { DEFAULT_OUTPUT, resolveProjectDocument, } from "@motionscript/core";
+import { createStillRenderer } from "./still";
+/**
+ * Renders a single frame of a document to an image.
+ *
+ * A one-shot wrapper over {@link StillRenderer}: create, render, encode, dispose.
+ * It therefore takes the same path as a live preview, and as the video export at
+ * that frame — there is one renderer, not three.
+ *
+ * For anything that captures **repeatedly** — a thumbnail builder, a preview that
+ * repaints as the user edits — hold a {@link StillRenderer} instead. This function
+ * builds and tears down a WebGPU surface per call, which is the right trade for one
+ * capture and the wrong one for a hundred.
+ */
+export async function exportScreenshot(params) {
+    const { registry, scale, manifest, theme, rendererWasmUrl, frame, format = "png", quality = 0.92, } = params;
+    const project = resolveProjectDocument(params.document, params, DEFAULT_OUTPUT);
+    if (project.tracks.length === 0)
+        throw new Error("The project has no tracks to screenshot.");
+    const renderer = await createStillRenderer({
+        viewport: project.viewport, fps: project.fps, scale, manifest, theme, rendererWasmUrl, registry,
+    });
+    try {
+        const drawn = await renderer.render(project, { frame });
+        return { ...drawn, bytes: await renderer.toBytes({ format, quality }) };
+    }
+    finally {
+        renderer.dispose();
+    }
+}
+//# sourceMappingURL=screenshot.js.map

package/dist/screenshot.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"screenshot.js","sourceRoot":"","sources":["../src/screenshot.ts"],"names":[],"mappings":"AAAA,OAAO,EACH,cAAc,EAAE,sBAAsB,GAEzC,MAAM,oBAAoB,CAAC;AAG5B,OAAO,EAAE,mBAAmB,EAAiB,MAAM,SAAS,CAAC;AAgC7D;;;;;;;;;;;GAWG;AACH,MAAM,CAAC,KAAK,UAAU,gBAAgB,CAAC,MAAwB;IAC3D,MAAM,EACF,QAAQ,EAAE,KAAK,EAAE,QAAQ,EAAE,KAAK,EAAE,eAAe,EACjD,KAAK,EAAE,MAAM,GAAG,KAAK,EAAE,OAAO,GAAG,IAAI,GACxC,GAAG,MAAM,CAAC;IAEX,MAAM,OAAO,GAAG,sBAAsB,CAAC,MAAM,CAAC,QAAQ,EAAE,MAAM,EAAE,cAAc,CAAC,CAAC;IAChF,IAAI,OAAO,CAAC,MAAM,CAAC,MAAM,KAAK,CAAC;QAAE,MAAM,IAAI,KAAK,CAAC,0CAA0C,CAAC,CAAC;IAE7F,MAAM,QAAQ,GAAG,MAAM,mBAAmB,CAAC;QACvC,QAAQ,EAAE,OAAO,CAAC,QAAQ,EAAE,GAAG,EAAE,OAAO,CAAC,GAAG,EAAE,KAAK,EAAE,QAAQ,EAAE,KAAK,EAAE,eAAe,EAAE,QAAQ;KAClG,CAAC,CAAC;IAEH,IAAI,CAAC;QACD,MAAM,KAAK,GAAG,MAAM,QAAQ,CAAC,MAAM,CAAC,OAAO,EAAE,EAAE,KAAK,EAAE,CAAC,CAAC;QACxD,OAAO,EAAE,GAAG,KAAK,EAAE,KAAK,EAAE,MAAM,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,EAAE,OAAO,EAAE,CAAC,EAAE,CAAC;IAC5E,CAAC;YAAS,CAAC;QACP,QAAQ,CAAC,OAAO,EAAE,CAAC;IACvB,CAAC;AACL,CAAC","sourcesContent":["import {\n    DEFAULT_OUTPUT, resolveProjectDocument,\n    type AssetManifest, type FrameSpec, type ProjectDocument, type Registry, type VisualDocument, type Size2D, type Theme,\n} from \"@motionscript/core\";\nimport type { ScreenshotFormat } from \"./frame-loop\";\nimport type { RendererWasmOption } from \"./renderer\";\nimport { createStillRenderer, type FrameRef } from \"./still\";\n\nexport type { ScreenshotFormat, FrameSpec };\n\nexport type ScreenshotParams = RendererWasmOption & {\n    /** A project, or a lone still or composition as the one track of one. */\n    document: ProjectDocument | VisualDocument;\n    /** The vocabulary its clips compile against. Defaults to what the library ships. */\n    registry?: Registry;\n    /** Win over the document's own; 1920×1080 at 60 fps when neither says. */\n    viewport?: Size2D;\n    fps?: number;\n    scale?: number;\n    manifest?: AssetManifest;\n    /** Theme for a document that carries none of its own. */\n    theme?: Theme;\n    /** Which frame to capture. Defaults to the timeline's first. */\n    frame?: FrameRef;\n    /** Encoding format (default \"png\"). */\n    format?: ScreenshotFormat;\n    /** JPEG quality in [0,1] (ignored for png; default 0.92). */\n    quality?: number;\n};\n\nexport type ScreenshotResult = {\n    /** The project frame that was captured, after clamping. */\n    frame: number;\n    totalFrames: number;\n    /** Encoded image bytes. */\n    bytes: Uint8Array;\n};\n\n/**\n * Renders a single frame of a document to an image.\n *\n * A one-shot wrapper over {@link StillRenderer}: create, render, encode, dispose.\n * It therefore takes the same path as a live preview, and as the video export at\n * that frame — there is one renderer, not three.\n *\n * For anything that captures **repeatedly** — a thumbnail builder, a preview that\n * repaints as the user edits — hold a {@link StillRenderer} instead. This function\n * builds and tears down a WebGPU surface per call, which is the right trade for one\n * capture and the wrong one for a hundred.\n */\nexport async function exportScreenshot(params: ScreenshotParams): Promise<ScreenshotResult> {\n    const {\n        registry, scale, manifest, theme, rendererWasmUrl,\n        frame, format = \"png\", quality = 0.92,\n    } = params;\n\n    const project = resolveProjectDocument(params.document, params, DEFAULT_OUTPUT);\n    if (project.tracks.length === 0) throw new Error(\"The project has no tracks to screenshot.\");\n\n    const renderer = await createStillRenderer({\n        viewport: project.viewport, fps: project.fps, scale, manifest, theme, rendererWasmUrl, registry,\n    });\n\n    try {\n        const drawn = await renderer.render(project, { frame });\n        return { ...drawn, bytes: await renderer.toBytes({ format, quality }) };\n    } finally {\n        renderer.dispose();\n    }\n}\n"]}

package/dist/still.d.ts

@@ -0,0 +1,159 @@
+import { Registry, type AssetManifest, type FrameSpec, type RenderIssue, type ProjectDocument, type VisualDocument, type Size2D, type Theme } from "@motionscript/core";
+import { type DrawnFrame, type ScreenshotFormat } from "./frame-loop";
+import type { BrowserRenderer } from "./engine";
+import { type RendererWasmOption } from "./renderer";
+/** Anything a still can be rendered from: a project, or a lone still or composition as the one track of one. */
+export type StillSource = ProjectDocument | VisualDocument;
+/**
+ * Which frame to draw, in whatever form is most convenient — a global frame
+ * index, the timeline's first or last frame, or a `FrameSpec`.
+ */
+export type FrameRef = FrameSpec | number | "first" | "last";
+export interface StillRendererOptions extends RendererWasmOption {
+    /**
+     * The canvas to draw into. Omit and the renderer creates its own hidden one
+     * and removes it on {@link StillRenderer.dispose} — which is what a one-shot
+     * capture wants, while a live preview passes the canvas it already shows.
+     */
+    canvas?: HTMLCanvasElement;
+    /** Output resolution in pixels, whatever the document asks for. Defaults to 1920×1080. */
+    viewport?: Size2D;
+    /** Frame rate for a document that sets none. Defaults to 60. */
+    fps?: number;
+    /** Device pixel ratio the surface is sized at. Defaults to 1. */
+    scale?: number;
+    manifest?: AssetManifest;
+    /** Theme for a document that carries none of its own. */
+    theme?: Theme;
+    /**
+     * The vocabulary a document is compiled against.
+     *
+     * Defaults to a fresh one carrying only what the library ships — a renderer
+     * owns its registry the way an engine does, so a host with custom node types
+     * passes the same one it gave its engine rather than relying on whatever a
+     * module happened to register.
+     */
+    registry?: Registry;
+}
+export interface RenderStillOptions {
+    /** Which frame to draw. Defaults to the timeline's first. */
+    frame?: FrameRef;
+    /** Seconds into the timeline, converted with the document's fps. Wins over `frame`. */
+    time?: number;
+    /**
+     * Draw this call at this pixel ratio instead of the renderer's. **Resizes the
+     * canvas and rebuilds the surface**, and the next call without it rebuilds
+     * them back, so keep it off the per-edit path — render the preview at its
+     * normal scale and pass this only when capturing at a higher one.
+     */
+    scale?: number;
+    /** What the renderer drew but not as the document says; a lost GPU device throws `RenderBackendError` instead. */
+    onIssue?: (issue: RenderIssue) => void;
+}
+export interface EncodeStillOptions {
+    /** Defaults to `"png"`. */
+    format?: ScreenshotFormat;
+    /** JPEG quality in [0,1]; ignored for png. Defaults to 0.92. */
+    quality?: number;
+}
+/** Normalize the many ways a caller can name a frame into the engine's own form. */
+export declare function stillFrameSpec(options: RenderStillOptions | undefined, fps: number): FrameSpec;
+/**
+ * A long-lived single-frame renderer.
+ *
+ * Where `exportScreenshot` is one frame from a standing start, this keeps the
+ * expensive things — the renderer module, its GPU surface, and the
+ * storage adapter's decoded-asset cache — alive across calls, so re-rendering
+ * after an edit costs discovering one frame and a draw rather than a new GL
+ * context. That is
+ * the difference between a one-off capture and a builder that repaints while the
+ * user types.
+ *
+ * It is also the *same* draw: {@link render} goes through `drawFrameAt`, which is
+ * the pass the video exporter runs per frame. A preview and its exported image
+ * cannot drift apart, because there is only one path.
+ *
+ * ```ts
+ * const renderer = await createStillRenderer({ canvas, viewport, manifest, theme });
+ * await renderer.render({ kind: "still", nodes: [
+ *     { id: "bg", type: "rect", parentId: null, layerOrder: 0, props: { width: 1920, height: 1080, fill: "bg" } },
+ * ] });
+ * const blob = await renderer.toBlob({ format: "png" });
+ * renderer.dispose();
+ * ```
+ *
+ * **The theme is process-global in core.** {@link render} re-applies the
+ * document's (or this renderer's) before every draw, so two renderers with
+ * different themes still each draw correctly; but anything else that calls
+ * `setTheme` between a render and a read of the surface will have been
+ * overwritten by the next render.
+ *
+ * **One surface, one caller at a time.** A render and the encode of its result
+ * are two calls, and the next render draws over the surface between them, so
+ * callers that share a renderer without knowing of each other must be queued —
+ * as `session.image()` queues its calls.
+ */
+export declare class StillRenderer {
+    readonly canvas: HTMLCanvasElement;
+    private renderContext;
+    private storageAdapter;
+    private catalog;
+    private readonly backend;
+    /** True when we made the canvas and must clean it up. */
+    private readonly ownsCanvas;
+    private viewportValue;
+    private readonly fpsValue;
+    private readonly scaleValue;
+    /** What the canvas is sized at now, which a call's own `scale` changes. */
+    private surfaceScale;
+    private manifest;
+    private theme?;
+    private readonly registry;
+    private disposed;
+    /** False until a frame has been drawn onto the current surface; a remount clears it. */
+    private drawn;
+    /** @internal Use {@link createStillRenderer}, which loads the renderer first. */
+    constructor(backend: BrowserRenderer, options: StillRendererOptions);
+    get viewport(): Size2D;
+    get fps(): number;
+    get scale(): number;
+    /**
+     * Draw one frame of `source`, at this renderer's viewport — the surface is
+     * the output, so it wins over any size the document asks for.
+     */
+    render(source: StillSource, options?: RenderStillOptions): Promise<DrawnFrame>;
+    /** Theme for a document that carries none of its own. */
+    setTheme(theme?: Theme): void;
+    /** Swap the asset manifest, keeping every decode already cached. */
+    setManifest(manifest: AssetManifest): void;
+    /**
+     * Change the output resolution.
+     *
+     * A full reset, unlike {@link setManifest}: the viewport clamps the resolution
+     * images are decoded *at*, so cached decodes made for the old one would be
+     * soft at the new one, and the render context's handlers captured the adapter
+     * when they were built — so both are rebuilt. Call this when the output format
+     * changes, not per edit.
+     */
+    setViewport(viewport: Size2D): void;
+    /** Encode the frame currently on the surface. */
+    toBytes(options?: EncodeStillOptions): Promise<Uint8Array>;
+    /** Encode the frame currently on the surface. */
+    toBlob(options?: EncodeStillOptions): Promise<Blob>;
+    /** Encode the frame currently on the surface. */
+    toDataURL(options?: EncodeStillOptions): string;
+    dispose(): void;
+    /**
+     * Read the surface back into a 2D canvas, which is what actually encodes: the
+     * renderers ship no image encoders, so the browser's own codecs are the only
+     * ones available.
+     */
+    private snapshotToCanvas;
+    private sizeCanvas;
+    /** Resize the backing store and mount a fresh surface over it. */
+    private remount;
+    private assertLive;
+}
+/** Create a {@link StillRenderer}; rejects with `WebGpuUnavailableError` without WebGPU. */
+export declare function createStillRenderer(options?: StillRendererOptions): Promise<StillRenderer>;
+//# sourceMappingURL=still.d.ts.map

package/dist/still.d.ts.map

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

package/dist/still.js

@@ -0,0 +1,222 @@
+import { DEFAULT_OUTPUT, ManifestAssetCatalog, frameSpecAtTime, Registry, resolveProjectDocument, } from "@motionscript/core";
+import { drawFrameAt, } from "./frame-loop";
+import { loadRenderer } from "./renderer";
+const EMPTY_MANIFEST = { image: {}, video: {}, audio: {}, font: {} };
+/** Normalize the many ways a caller can name a frame into the engine's own form. */
+export function stillFrameSpec(options, fps) {
+    if (options?.time !== undefined)
+        return frameSpecAtTime(options.time, fps);
+    const frame = options?.frame;
+    if (frame === undefined || frame === "first")
+        return { kind: "first" };
+    if (frame === "last")
+        return { kind: "last" };
+    if (typeof frame === "number")
+        return { kind: "frame", frame };
+    return frame;
+}
+function mimeOf(format) {
+    return format === "jpeg" ? "image/jpeg" : "image/png";
+}
+/**
+ * A long-lived single-frame renderer.
+ *
+ * Where `exportScreenshot` is one frame from a standing start, this keeps the
+ * expensive things — the renderer module, its GPU surface, and the
+ * storage adapter's decoded-asset cache — alive across calls, so re-rendering
+ * after an edit costs discovering one frame and a draw rather than a new GL
+ * context. That is
+ * the difference between a one-off capture and a builder that repaints while the
+ * user types.
+ *
+ * It is also the *same* draw: {@link render} goes through `drawFrameAt`, which is
+ * the pass the video exporter runs per frame. A preview and its exported image
+ * cannot drift apart, because there is only one path.
+ *
+ * ```ts
+ * const renderer = await createStillRenderer({ canvas, viewport, manifest, theme });
+ * await renderer.render({ kind: "still", nodes: [
+ *     { id: "bg", type: "rect", parentId: null, layerOrder: 0, props: { width: 1920, height: 1080, fill: "bg" } },
+ * ] });
+ * const blob = await renderer.toBlob({ format: "png" });
+ * renderer.dispose();
+ * ```
+ *
+ * **The theme is process-global in core.** {@link render} re-applies the
+ * document's (or this renderer's) before every draw, so two renderers with
+ * different themes still each draw correctly; but anything else that calls
+ * `setTheme` between a render and a read of the surface will have been
+ * overwritten by the next render.
+ *
+ * **One surface, one caller at a time.** A render and the encode of its result
+ * are two calls, and the next render draws over the surface between them, so
+ * callers that share a renderer without knowing of each other must be queued —
+ * as `session.image()` queues its calls.
+ */
+export class StillRenderer {
+    canvas;
+    renderContext;
+    storageAdapter;
+    catalog;
+    backend;
+    /** True when we made the canvas and must clean it up. */
+    ownsCanvas;
+    viewportValue;
+    fpsValue;
+    scaleValue;
+    /** What the canvas is sized at now, which a call's own `scale` changes. */
+    surfaceScale;
+    manifest;
+    theme;
+    registry;
+    disposed = false;
+    /** False until a frame has been drawn onto the current surface; a remount clears it. */
+    drawn = false;
+    /** @internal Use {@link createStillRenderer}, which loads the renderer first. */
+    constructor(backend, options) {
+        this.backend = backend;
+        this.viewportValue = options.viewport ?? DEFAULT_OUTPUT.viewport;
+        this.fpsValue = options.fps ?? DEFAULT_OUTPUT.fps;
+        this.scaleValue = options.scale ?? 1;
+        this.surfaceScale = this.scaleValue;
+        this.manifest = options.manifest ?? EMPTY_MANIFEST;
+        this.theme = options.theme;
+        this.registry = options.registry ?? new Registry();
+        this.ownsCanvas = options.canvas === undefined;
+        this.canvas = options.canvas ?? document.createElement("canvas");
+        if (this.ownsCanvas) {
+            this.canvas.style.display = "none";
+            document.body.appendChild(this.canvas);
+        }
+        this.sizeCanvas();
+        this.catalog = new ManifestAssetCatalog(this.manifest);
+        this.storageAdapter = this.backend.createStorageAdapter({
+            catalog: this.catalog, viewport: this.viewportValue, fps: this.fpsValue,
+        });
+        this.renderContext = this.backend.createRenderContext(this.storageAdapter);
+        this.renderContext.mount(this.canvas);
+    }
+    get viewport() { return this.viewportValue; }
+    get fps() { return this.fpsValue; }
+    get scale() { return this.scaleValue; }
+    /**
+     * Draw one frame of `source`, at this renderer's viewport — the surface is
+     * the output, so it wins over any size the document asks for.
+     */
+    async render(source, options) {
+        this.assertLive();
+        const scale = options?.scale ?? this.scaleValue;
+        if (scale !== this.surfaceScale)
+            this.remount(scale);
+        await this.renderContext.whenMounted?.();
+        const project = resolveProjectDocument(source, { viewport: this.viewportValue }, { viewport: this.viewportValue, fps: this.fpsValue });
+        const frame = await drawFrameAt({
+            project,
+            registry: this.registry,
+            theme: this.theme,
+            scale,
+            renderContext: this.renderContext,
+            storageAdapter: this.storageAdapter,
+            assetCatalog: this.catalog,
+            frame: stillFrameSpec(options, project.fps),
+            onIssue: options?.onIssue,
+        });
+        this.drawn = true;
+        return frame;
+    }
+    /** Theme for a document that carries none of its own. */
+    setTheme(theme) { this.theme = theme; }
+    /** Swap the asset manifest, keeping every decode already cached. */
+    setManifest(manifest) {
+        this.assertLive();
+        this.manifest = manifest;
+        this.catalog = new ManifestAssetCatalog(manifest);
+        this.storageAdapter.setCatalog(this.catalog);
+    }
+    /**
+     * Change the output resolution.
+     *
+     * A full reset, unlike {@link setManifest}: the viewport clamps the resolution
+     * images are decoded *at*, so cached decodes made for the old one would be
+     * soft at the new one, and the render context's handlers captured the adapter
+     * when they were built — so both are rebuilt. Call this when the output format
+     * changes, not per edit.
+     */
+    setViewport(viewport) {
+        this.assertLive();
+        if (viewport.width === this.viewportValue.width && viewport.height === this.viewportValue.height) {
+            return;
+        }
+        this.viewportValue = viewport;
+        // Disposing the context disposes the adapter it holds, so this releases
+        // the old surface, its handlers and every decode in one call.
+        this.renderContext.dispose();
+        this.storageAdapter = this.backend.createStorageAdapter({
+            catalog: this.catalog, viewport, fps: this.fpsValue,
+        });
+        this.renderContext = this.backend.createRenderContext(this.storageAdapter);
+        this.remount(this.scaleValue);
+    }
+    /** Encode the frame currently on the surface. */
+    async toBytes(options) {
+        const blob = await this.toBlob(options);
+        return new Uint8Array(await blob.arrayBuffer());
+    }
+    /** Encode the frame currently on the surface. */
+    toBlob(options) {
+        const canvas = this.snapshotToCanvas();
+        const { format = "png", quality = 0.92 } = options ?? {};
+        return new Promise((resolve, reject) => {
+            canvas.toBlob((blob) => blob
+                ? resolve(blob)
+                : reject(new Error("Still encode produced no data.")), mimeOf(format), quality);
+        });
+    }
+    /** Encode the frame currently on the surface. */
+    toDataURL(options) {
+        const { format = "png", quality = 0.92 } = options ?? {};
+        return this.snapshotToCanvas().toDataURL(mimeOf(format), quality);
+    }
+    dispose() {
+        if (this.disposed)
+            return;
+        this.disposed = true;
+        this.renderContext.dispose();
+        if (this.ownsCanvas)
+            this.canvas.remove();
+    }
+    /**
+     * Read the surface back into a 2D canvas, which is what actually encodes: the
+     * renderers ship no image encoders, so the browser's own codecs are the only
+     * ones available.
+     */
+    snapshotToCanvas() {
+        this.assertLive();
+        if (!this.drawn)
+            throw new Error("Nothing has been rendered yet.");
+        const canvas = this.renderContext.snapshotCanvas?.();
+        if (!canvas)
+            throw new Error("Still encode: could not read the surface into a 2d canvas.");
+        return canvas;
+    }
+    sizeCanvas() {
+        this.canvas.width = this.viewportValue.width * this.surfaceScale;
+        this.canvas.height = this.viewportValue.height * this.surfaceScale;
+    }
+    /** Resize the backing store and mount a fresh surface over it. */
+    remount(scale) {
+        this.surfaceScale = scale;
+        this.drawn = false;
+        this.sizeCanvas();
+        this.renderContext.mount(this.canvas);
+    }
+    assertLive() {
+        if (this.disposed)
+            throw new Error("This StillRenderer has been disposed.");
+    }
+}
+/** Create a {@link StillRenderer}; rejects with `WebGpuUnavailableError` without WebGPU. */
+export async function createStillRenderer(options = {}) {
+    return new StillRenderer(await loadRenderer(options), options);
+}
+//# sourceMappingURL=still.js.map

package/dist/still.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"still.js","sourceRoot":"","sources":["../src/still.ts"],"names":[],"mappings":"AAAA,OAAO,EACW,cAAc,EAAE,oBAAoB,EAClD,eAAe,EACf,QAAQ,EACR,sBAAsB,GASzB,MAAM,oBAAoB,CAAC;AAC5B,OAAO,EACH,WAAW,GAGd,MAAM,cAAc,CAAC;AAEtB,OAAO,EAAE,YAAY,EAA2B,MAAM,YAAY,CAAC;AAEnE,MAAM,cAAc,GAAkB,EAAE,KAAK,EAAE,EAAE,EAAE,KAAK,EAAE,EAAE,EAAE,KAAK,EAAE,EAAE,EAAE,IAAI,EAAE,EAAE,EAAE,CAAC;AA6DpF,oFAAoF;AACpF,MAAM,UAAU,cAAc,CAAC,OAAuC,EAAE,GAAW;IAC/E,IAAI,OAAO,EAAE,IAAI,KAAK,SAAS;QAAE,OAAO,eAAe,CAAC,OAAO,CAAC,IAAI,EAAE,GAAG,CAAC,CAAC;IAC3E,MAAM,KAAK,GAAG,OAAO,EAAE,KAAK,CAAC;IAC7B,IAAI,KAAK,KAAK,SAAS,IAAI,KAAK,KAAK,OAAO;QAAE,OAAO,EAAE,IAAI,EAAE,OAAO,EAAE,CAAC;IACvE,IAAI,KAAK,KAAK,MAAM;QAAE,OAAO,EAAE,IAAI,EAAE,MAAM,EAAE,CAAC;IAC9C,IAAI,OAAO,KAAK,KAAK,QAAQ;QAAE,OAAO,EAAE,IAAI,EAAE,OAAO,EAAE,KAAK,EAAE,CAAC;IAC/D,OAAO,KAAK,CAAC;AACjB,CAAC;AAED,SAAS,MAAM,CAAC,MAAwB;IACpC,OAAO,MAAM,KAAK,MAAM,CAAC,CAAC,CAAC,YAAY,CAAC,CAAC,CAAC,WAAW,CAAC;AAC1D,CAAC;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AACH,MAAM,OAAO,aAAa;IACb,MAAM,CAAoB;IAE3B,aAAa,CAAuB;IACpC,cAAc,CAAiB;IAC/B,OAAO,CAAe;IAEb,OAAO,CAAkB;IAC1C,yDAAyD;IACxC,UAAU,CAAU;IAE7B,aAAa,CAAS;IACb,QAAQ,CAAS;IACjB,UAAU,CAAS;IACpC,2EAA2E;IACnE,YAAY,CAAS;IACrB,QAAQ,CAAgB;IACxB,KAAK,CAAS;IACL,QAAQ,CAAW;IAC5B,QAAQ,GAAG,KAAK,CAAC;IACzB,wFAAwF;IAChF,KAAK,GAAG,KAAK,CAAC;IAEtB,iFAAiF;IACjF,YACI,OAAwB,EACxB,OAA6B;QAE7B,IAAI,CAAC,OAAO,GAAG,OAAO,CAAC;QACvB,IAAI,CAAC,aAAa,GAAG,OAAO,CAAC,QAAQ,IAAI,cAAc,CAAC,QAAQ,CAAC;QACjE,IAAI,CAAC,QAAQ,GAAG,OAAO,CAAC,GAAG,IAAI,cAAc,CAAC,GAAG,CAAC;QAClD,IAAI,CAAC,UAAU,GAAG,OAAO,CAAC,KAAK,IAAI,CAAC,CAAC;QACrC,IAAI,CAAC,YAAY,GAAG,IAAI,CAAC,UAAU,CAAC;QACpC,IAAI,CAAC,QAAQ,GAAG,OAAO,CAAC,QAAQ,IAAI,cAAc,CAAC;QACnD,IAAI,CAAC,KAAK,GAAG,OAAO,CAAC,KAAK,CAAC;QAC3B,IAAI,CAAC,QAAQ,GAAG,OAAO,CAAC,QAAQ,IAAI,IAAI,QAAQ,EAAE,CAAC;QAEnD,IAAI,CAAC,UAAU,GAAG,OAAO,CAAC,MAAM,KAAK,SAAS,CAAC;QAC/C,IAAI,CAAC,MAAM,GAAG,OAAO,CAAC,MAAM,IAAI,QAAQ,CAAC,aAAa,CAAC,QAAQ,CAAC,CAAC;QACjE,IAAI,IAAI,CAAC,UAAU,EAAE,CAAC;YAClB,IAAI,CAAC,MAAM,CAAC,KAAK,CAAC,OAAO,GAAG,MAAM,CAAC;YACnC,QAAQ,CAAC,IAAI,CAAC,WAAW,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;QAC3C,CAAC;QACD,IAAI,CAAC,UAAU,EAAE,CAAC;QAElB,IAAI,CAAC,OAAO,GAAG,IAAI,oBAAoB,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC;QACvD,IAAI,CAAC,cAAc,GAAG,IAAI,CAAC,OAAO,CAAC,oBAAoB,CAAC;YACpD,OAAO,EAAE,IAAI,CAAC,OAAO,EAAE,QAAQ,EAAE,IAAI,CAAC,aAAa,EAAE,GAAG,EAAE,IAAI,CAAC,QAAQ;SAC1E,CAAC,CAAC;QACH,IAAI,CAAC,aAAa,GAAG,IAAI,CAAC,OAAO,CAAC,mBAAmB,CAAC,IAAI,CAAC,cAAc,CAAC,CAAC;QAC3E,IAAI,CAAC,aAAa,CAAC,KAAK,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;IAC1C,CAAC;IAED,IAAI,QAAQ,KAAa,OAAO,IAAI,CAAC,aAAa,CAAC,CAAC,CAAC;IACrD,IAAI,GAAG,KAAa,OAAO,IAAI,CAAC,QAAQ,CAAC,CAAC,CAAC;IAC3C,IAAI,KAAK,KAAa,OAAO,IAAI,CAAC,UAAU,CAAC,CAAC,CAAC;IAE/C;;;OAGG;IACH,KAAK,CAAC,MAAM,CAAC,MAAmB,EAAE,OAA4B;QAC1D,IAAI,CAAC,UAAU,EAAE,CAAC;QAClB,MAAM,KAAK,GAAG,OAAO,EAAE,KAAK,IAAI,IAAI,CAAC,UAAU,CAAC;QAChD,IAAI,KAAK,KAAK,IAAI,CAAC,YAAY;YAAE,IAAI,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC;QACrD,MAAM,IAAI,CAAC,aAAa,CAAC,WAAW,EAAE,EAAE,CAAC;QAEzC,MAAM,OAAO,GAAG,sBAAsB,CAClC,MAAM,EAAE,EAAE,QAAQ,EAAE,IAAI,CAAC,aAAa,EAAE,EAAE,EAAE,QAAQ,EAAE,IAAI,CAAC,aAAa,EAAE,GAAG,EAAE,IAAI,CAAC,QAAQ,EAAE,CACjG,CAAC;QAEF,MAAM,KAAK,GAAG,MAAM,WAAW,CAAC;YAC5B,OAAO;YACP,QAAQ,EAAE,IAAI,CAAC,QAAQ;YACvB,KAAK,EAAE,IAAI,CAAC,KAAK;YACjB,KAAK;YACL,aAAa,EAAE,IAAI,CAAC,aAAa;YACjC,cAAc,EAAE,IAAI,CAAC,cAAc;YACnC,YAAY,EAAE,IAAI,CAAC,OAAO;YAC1B,KAAK,EAAE,cAAc,CAAC,OAAO,EAAE,OAAO,CAAC,GAAI,CAAC;YAC5C,OAAO,EAAE,OAAO,EAAE,OAAO;SAC5B,CAAC,CAAC;QACH,IAAI,CAAC,KAAK,GAAG,IAAI,CAAC;QAClB,OAAO,KAAK,CAAC;IACjB,CAAC;IAED,yDAAyD;IACzD,QAAQ,CAAC,KAAa,IAAU,IAAI,CAAC,KAAK,GAAG,KAAK,CAAC,CAAC,CAAC;IAErD,oEAAoE;IACpE,WAAW,CAAC,QAAuB;QAC/B,IAAI,CAAC,UAAU,EAAE,CAAC;QAClB,IAAI,CAAC,QAAQ,GAAG,QAAQ,CAAC;QACzB,IAAI,CAAC,OAAO,GAAG,IAAI,oBAAoB,CAAC,QAAQ,CAAC,CAAC;QAClD,IAAI,CAAC,cAAc,CAAC,UAAU,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;IACjD,CAAC;IAED;;;;;;;;OAQG;IACH,WAAW,CAAC,QAAgB;QACxB,IAAI,CAAC,UAAU,EAAE,CAAC;QAClB,IAAI,QAAQ,CAAC,KAAK,KAAK,IAAI,CAAC,aAAa,CAAC,KAAK,IAAI,QAAQ,CAAC,MAAM,KAAK,IAAI,CAAC,aAAa,CAAC,MAAM,EAAE,CAAC;YAC/F,OAAO;QACX,CAAC;QACD,IAAI,CAAC,aAAa,GAAG,QAAQ,CAAC;QAC9B,wEAAwE;QACxE,8DAA8D;QAC9D,IAAI,CAAC,aAAa,CAAC,OAAO,EAAE,CAAC;QAC7B,IAAI,CAAC,cAAc,GAAG,IAAI,CAAC,OAAO,CAAC,oBAAoB,CAAC;YACpD,OAAO,EAAE,IAAI,CAAC,OAAO,EAAE,QAAQ,EAAE,GAAG,EAAE,IAAI,CAAC,QAAQ;SACtD,CAAC,CAAC;QACH,IAAI,CAAC,aAAa,GAAG,IAAI,CAAC,OAAO,CAAC,mBAAmB,CAAC,IAAI,CAAC,cAAc,CAAC,CAAC;QAC3E,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,UAAU,CAAC,CAAC;IAClC,CAAC;IAED,iDAAiD;IACjD,KAAK,CAAC,OAAO,CAAC,OAA4B;QACtC,MAAM,IAAI,GAAG,MAAM,IAAI,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC;QACxC,OAAO,IAAI,UAAU,CAAC,MAAM,IAAI,CAAC,WAAW,EAAE,CAAC,CAAC;IACpD,CAAC;IAED,iDAAiD;IACjD,MAAM,CAAC,OAA4B;QAC/B,MAAM,MAAM,GAAG,IAAI,CAAC,gBAAgB,EAAE,CAAC;QACvC,MAAM,EAAE,MAAM,GAAG,KAAK,EAAE,OAAO,GAAG,IAAI,EAAE,GAAG,OAAO,IAAI,EAAE,CAAC;QACzD,OAAO,IAAI,OAAO,CAAC,CAAC,OAAO,EAAE,MAAM,EAAE,EAAE;YACnC,MAAM,CAAC,MAAM,CACT,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI;gBACV,CAAC,CAAC,OAAO,CAAC,IAAI,CAAC;gBACf,CAAC,CAAC,MAAM,CAAC,IAAI,KAAK,CAAC,gCAAgC,CAAC,CAAC,EACzD,MAAM,CAAC,MAAM,CAAC,EACd,OAAO,CACV,CAAC;QACN,CAAC,CAAC,CAAC;IACP,CAAC;IAED,iDAAiD;IACjD,SAAS,CAAC,OAA4B;QAClC,MAAM,EAAE,MAAM,GAAG,KAAK,EAAE,OAAO,GAAG,IAAI,EAAE,GAAG,OAAO,IAAI,EAAE,CAAC;QACzD,OAAO,IAAI,CAAC,gBAAgB,EAAE,CAAC,SAAS,CAAC,MAAM,CAAC,MAAM,CAAC,EAAE,OAAO,CAAC,CAAC;IACtE,CAAC;IAED,OAAO;QACH,IAAI,IAAI,CAAC,QAAQ;YAAE,OAAO;QAC1B,IAAI,CAAC,QAAQ,GAAG,IAAI,CAAC;QACrB,IAAI,CAAC,aAAa,CAAC,OAAO,EAAE,CAAC;QAC7B,IAAI,IAAI,CAAC,UAAU;YAAE,IAAI,CAAC,MAAM,CAAC,MAAM,EAAE,CAAC;IAC9C,CAAC;IAED;;;;OAIG;IACK,gBAAgB;QACpB,IAAI,CAAC,UAAU,EAAE,CAAC;QAClB,IAAI,CAAC,IAAI,CAAC,KAAK;YAAE,MAAM,IAAI,KAAK,CAAC,gCAAgC,CAAC,CAAC;QACnE,MAAM,MAAM,GAAG,IAAI,CAAC,aAAa,CAAC,cAAc,EAAE,EAAE,CAAC;QACrD,IAAI,CAAC,MAAM;YAAE,MAAM,IAAI,KAAK,CAAC,4DAA4D,CAAC,CAAC;QAC3F,OAAO,MAAM,CAAC;IAClB,CAAC;IAEO,UAAU;QACd,IAAI,CAAC,MAAM,CAAC,KAAK,GAAG,IAAI,CAAC,aAAa,CAAC,KAAK,GAAG,IAAI,CAAC,YAAY,CAAC;QACjE,IAAI,CAAC,MAAM,CAAC,MAAM,GAAG,IAAI,CAAC,aAAa,CAAC,MAAM,GAAG,IAAI,CAAC,YAAY,CAAC;IACvE,CAAC;IAED,kEAAkE;IAC1D,OAAO,CAAC,KAAa;QACzB,IAAI,CAAC,YAAY,GAAG,KAAK,CAAC;QAC1B,IAAI,CAAC,KAAK,GAAG,KAAK,CAAC;QACnB,IAAI,CAAC,UAAU,EAAE,CAAC;QAClB,IAAI,CAAC,aAAa,CAAC,KAAK,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;IAC1C,CAAC;IAEO,UAAU;QACd,IAAI,IAAI,CAAC,QAAQ;YAAE,MAAM,IAAI,KAAK,CAAC,uCAAuC,CAAC,CAAC;IAChF,CAAC;CACJ;AAED,4FAA4F;AAC5F,MAAM,CAAC,KAAK,UAAU,mBAAmB,CACrC,UAAgC,EAAE;IAElC,OAAO,IAAI,aAAa,CAAC,MAAM,YAAY,CAAC,OAAO,CAAC,EAAE,OAAO,CAAC,CAAC;AACnE,CAAC","sourcesContent":["import {\n    AssetCatalog, DEFAULT_OUTPUT, ManifestAssetCatalog,\n    frameSpecAtTime,\n    Registry,\n    resolveProjectDocument,\n    type AssetManifest,\n    type FrameSpec,\n    type RenderIssue,\n    type ProjectDocument,\n    type VisualDocument,\n    type Size2D,\n    type StorageAdapter,\n    type Theme,\n} from \"@motionscript/core\";\nimport {\n    drawFrameAt,\n    type DrawnFrame,\n    type ScreenshotFormat,\n} from \"./frame-loop\";\nimport type { BrowserRenderContext, BrowserRenderer } from \"./engine\";\nimport { loadRenderer, type RendererWasmOption } from \"./renderer\";\n\nconst EMPTY_MANIFEST: AssetManifest = { image: {}, video: {}, audio: {}, font: {} };\n\n/** Anything a still can be rendered from: a project, or a lone still or composition as the one track of one. */\nexport type StillSource = ProjectDocument | VisualDocument;\n\n/**\n * Which frame to draw, in whatever form is most convenient — a global frame\n * index, the timeline's first or last frame, or a `FrameSpec`.\n */\nexport type FrameRef = FrameSpec | number | \"first\" | \"last\";\n\nexport interface StillRendererOptions extends RendererWasmOption {\n    /**\n     * The canvas to draw into. Omit and the renderer creates its own hidden one\n     * and removes it on {@link StillRenderer.dispose} — which is what a one-shot\n     * capture wants, while a live preview passes the canvas it already shows.\n     */\n    canvas?: HTMLCanvasElement;\n    /** Output resolution in pixels, whatever the document asks for. Defaults to 1920×1080. */\n    viewport?: Size2D;\n    /** Frame rate for a document that sets none. Defaults to 60. */\n    fps?: number;\n    /** Device pixel ratio the surface is sized at. Defaults to 1. */\n    scale?: number;\n    manifest?: AssetManifest;\n    /** Theme for a document that carries none of its own. */\n    theme?: Theme;\n    /**\n     * The vocabulary a document is compiled against.\n     *\n     * Defaults to a fresh one carrying only what the library ships — a renderer\n     * owns its registry the way an engine does, so a host with custom node types\n     * passes the same one it gave its engine rather than relying on whatever a\n     * module happened to register.\n     */\n    registry?: Registry;\n}\n\nexport interface RenderStillOptions {\n    /** Which frame to draw. Defaults to the timeline's first. */\n    frame?: FrameRef;\n    /** Seconds into the timeline, converted with the document's fps. Wins over `frame`. */\n    time?: number;\n    /**\n     * Draw this call at this pixel ratio instead of the renderer's. **Resizes the\n     * canvas and rebuilds the surface**, and the next call without it rebuilds\n     * them back, so keep it off the per-edit path — render the preview at its\n     * normal scale and pass this only when capturing at a higher one.\n     */\n    scale?: number;\n    /** What the renderer drew but not as the document says; a lost GPU device throws `RenderBackendError` instead. */\n    onIssue?: (issue: RenderIssue) => void;\n}\n\nexport interface EncodeStillOptions {\n    /** Defaults to `\"png\"`. */\n    format?: ScreenshotFormat;\n    /** JPEG quality in [0,1]; ignored for png. Defaults to 0.92. */\n    quality?: number;\n}\n\n/** Normalize the many ways a caller can name a frame into the engine's own form. */\nexport function stillFrameSpec(options: RenderStillOptions | undefined, fps: number): FrameSpec {\n    if (options?.time !== undefined) return frameSpecAtTime(options.time, fps);\n    const frame = options?.frame;\n    if (frame === undefined || frame === \"first\") return { kind: \"first\" };\n    if (frame === \"last\") return { kind: \"last\" };\n    if (typeof frame === \"number\") return { kind: \"frame\", frame };\n    return frame;\n}\n\nfunction mimeOf(format: ScreenshotFormat): string {\n    return format === \"jpeg\" ? \"image/jpeg\" : \"image/png\";\n}\n\n/**\n * A long-lived single-frame renderer.\n *\n * Where `exportScreenshot` is one frame from a standing start, this keeps the\n * expensive things — the renderer module, its GPU surface, and the\n * storage adapter's decoded-asset cache — alive across calls, so re-rendering\n * after an edit costs discovering one frame and a draw rather than a new GL\n * context. That is\n * the difference between a one-off capture and a builder that repaints while the\n * user types.\n *\n * It is also the *same* draw: {@link render} goes through `drawFrameAt`, which is\n * the pass the video exporter runs per frame. A preview and its exported image\n * cannot drift apart, because there is only one path.\n *\n * ```ts\n * const renderer = await createStillRenderer({ canvas, viewport, manifest, theme });\n * await renderer.render({ kind: \"still\", nodes: [\n *     { id: \"bg\", type: \"rect\", parentId: null, layerOrder: 0, props: { width: 1920, height: 1080, fill: \"bg\" } },\n * ] });\n * const blob = await renderer.toBlob({ format: \"png\" });\n * renderer.dispose();\n * ```\n *\n * **The theme is process-global in core.** {@link render} re-applies the\n * document's (or this renderer's) before every draw, so two renderers with\n * different themes still each draw correctly; but anything else that calls\n * `setTheme` between a render and a read of the surface will have been\n * overwritten by the next render.\n *\n * **One surface, one caller at a time.** A render and the encode of its result\n * are two calls, and the next render draws over the surface between them, so\n * callers that share a renderer without knowing of each other must be queued —\n * as `session.image()` queues its calls.\n */\nexport class StillRenderer {\n    readonly canvas: HTMLCanvasElement;\n\n    private renderContext: BrowserRenderContext;\n    private storageAdapter: StorageAdapter;\n    private catalog: AssetCatalog;\n\n    private readonly backend: BrowserRenderer;\n    /** True when we made the canvas and must clean it up. */\n    private readonly ownsCanvas: boolean;\n\n    private viewportValue: Size2D;\n    private readonly fpsValue: number;\n    private readonly scaleValue: number;\n    /** What the canvas is sized at now, which a call's own `scale` changes. */\n    private surfaceScale: number;\n    private manifest: AssetManifest;\n    private theme?: Theme;\n    private readonly registry: Registry;\n    private disposed = false;\n    /** False until a frame has been drawn onto the current surface; a remount clears it. */\n    private drawn = false;\n\n    /** @internal Use {@link createStillRenderer}, which loads the renderer first. */\n    constructor(\n        backend: BrowserRenderer,\n        options: StillRendererOptions,\n    ) {\n        this.backend = backend;\n        this.viewportValue = options.viewport ?? DEFAULT_OUTPUT.viewport;\n        this.fpsValue = options.fps ?? DEFAULT_OUTPUT.fps;\n        this.scaleValue = options.scale ?? 1;\n        this.surfaceScale = this.scaleValue;\n        this.manifest = options.manifest ?? EMPTY_MANIFEST;\n        this.theme = options.theme;\n        this.registry = options.registry ?? new Registry();\n\n        this.ownsCanvas = options.canvas === undefined;\n        this.canvas = options.canvas ?? document.createElement(\"canvas\");\n        if (this.ownsCanvas) {\n            this.canvas.style.display = \"none\";\n            document.body.appendChild(this.canvas);\n        }\n        this.sizeCanvas();\n\n        this.catalog = new ManifestAssetCatalog(this.manifest);\n        this.storageAdapter = this.backend.createStorageAdapter({\n            catalog: this.catalog, viewport: this.viewportValue, fps: this.fpsValue,\n        });\n        this.renderContext = this.backend.createRenderContext(this.storageAdapter);\n        this.renderContext.mount(this.canvas);\n    }\n\n    get viewport(): Size2D { return this.viewportValue; }\n    get fps(): number { return this.fpsValue; }\n    get scale(): number { return this.scaleValue; }\n\n    /**\n     * Draw one frame of `source`, at this renderer's viewport — the surface is\n     * the output, so it wins over any size the document asks for.\n     */\n    async render(source: StillSource, options?: RenderStillOptions): Promise<DrawnFrame> {\n        this.assertLive();\n        const scale = options?.scale ?? this.scaleValue;\n        if (scale !== this.surfaceScale) this.remount(scale);\n        await this.renderContext.whenMounted?.();\n\n        const project = resolveProjectDocument(\n            source, { viewport: this.viewportValue }, { viewport: this.viewportValue, fps: this.fpsValue },\n        );\n\n        const frame = await drawFrameAt({\n            project,\n            registry: this.registry,\n            theme: this.theme,\n            scale,\n            renderContext: this.renderContext,\n            storageAdapter: this.storageAdapter,\n            assetCatalog: this.catalog,\n            frame: stillFrameSpec(options, project.fps!),\n            onIssue: options?.onIssue,\n        });\n        this.drawn = true;\n        return frame;\n    }\n\n    /** Theme for a document that carries none of its own. */\n    setTheme(theme?: Theme): void { this.theme = theme; }\n\n    /** Swap the asset manifest, keeping every decode already cached. */\n    setManifest(manifest: AssetManifest): void {\n        this.assertLive();\n        this.manifest = manifest;\n        this.catalog = new ManifestAssetCatalog(manifest);\n        this.storageAdapter.setCatalog(this.catalog);\n    }\n\n    /**\n     * Change the output resolution.\n     *\n     * A full reset, unlike {@link setManifest}: the viewport clamps the resolution\n     * images are decoded *at*, so cached decodes made for the old one would be\n     * soft at the new one, and the render context's handlers captured the adapter\n     * when they were built — so both are rebuilt. Call this when the output format\n     * changes, not per edit.\n     */\n    setViewport(viewport: Size2D): void {\n        this.assertLive();\n        if (viewport.width === this.viewportValue.width && viewport.height === this.viewportValue.height) {\n            return;\n        }\n        this.viewportValue = viewport;\n        // Disposing the context disposes the adapter it holds, so this releases\n        // the old surface, its handlers and every decode in one call.\n        this.renderContext.dispose();\n        this.storageAdapter = this.backend.createStorageAdapter({\n            catalog: this.catalog, viewport, fps: this.fpsValue,\n        });\n        this.renderContext = this.backend.createRenderContext(this.storageAdapter);\n        this.remount(this.scaleValue);\n    }\n\n    /** Encode the frame currently on the surface. */\n    async toBytes(options?: EncodeStillOptions): Promise<Uint8Array> {\n        const blob = await this.toBlob(options);\n        return new Uint8Array(await blob.arrayBuffer());\n    }\n\n    /** Encode the frame currently on the surface. */\n    toBlob(options?: EncodeStillOptions): Promise<Blob> {\n        const canvas = this.snapshotToCanvas();\n        const { format = \"png\", quality = 0.92 } = options ?? {};\n        return new Promise((resolve, reject) => {\n            canvas.toBlob(\n                (blob) => blob\n                    ? resolve(blob)\n                    : reject(new Error(\"Still encode produced no data.\")),\n                mimeOf(format),\n                quality,\n            );\n        });\n    }\n\n    /** Encode the frame currently on the surface. */\n    toDataURL(options?: EncodeStillOptions): string {\n        const { format = \"png\", quality = 0.92 } = options ?? {};\n        return this.snapshotToCanvas().toDataURL(mimeOf(format), quality);\n    }\n\n    dispose(): void {\n        if (this.disposed) return;\n        this.disposed = true;\n        this.renderContext.dispose();\n        if (this.ownsCanvas) this.canvas.remove();\n    }\n\n    /**\n     * Read the surface back into a 2D canvas, which is what actually encodes: the\n     * renderers ship no image encoders, so the browser's own codecs are the only\n     * ones available.\n     */\n    private snapshotToCanvas(): HTMLCanvasElement {\n        this.assertLive();\n        if (!this.drawn) throw new Error(\"Nothing has been rendered yet.\");\n        const canvas = this.renderContext.snapshotCanvas?.();\n        if (!canvas) throw new Error(\"Still encode: could not read the surface into a 2d canvas.\");\n        return canvas;\n    }\n\n    private sizeCanvas(): void {\n        this.canvas.width = this.viewportValue.width * this.surfaceScale;\n        this.canvas.height = this.viewportValue.height * this.surfaceScale;\n    }\n\n    /** Resize the backing store and mount a fresh surface over it. */\n    private remount(scale: number): void {\n        this.surfaceScale = scale;\n        this.drawn = false;\n        this.sizeCanvas();\n        this.renderContext.mount(this.canvas);\n    }\n\n    private assertLive(): void {\n        if (this.disposed) throw new Error(\"This StillRenderer has been disposed.\");\n    }\n}\n\n/** Create a {@link StillRenderer}; rejects with `WebGpuUnavailableError` without WebGPU. */\nexport async function createStillRenderer(\n    options: StillRendererOptions = {},\n): Promise<StillRenderer> {\n    return new StillRenderer(await loadRenderer(options), options);\n}\n"]}

package/dist/ticker.d.ts

@@ -0,0 +1,74 @@
+import { Ticker } from "@motionscript/core";
+/**
+ * Ticker backed by a Web Audio AudioContext. Clip time follows
+ * `audioContext.currentTime` (within a few ms, see `startLoop`), so any
+ * AudioBufferSourceNodes scheduled on the same context play in sync.
+ *
+ * When paused we suspend the context (audio stops, currentTime freezes);
+ * when playing we resume and a rAF loop publishes ticks at the target fps.
+ *
+ * A single silent buffer covering the full timeline is started on play(),
+ * which keeps the context active and gives the browser a stable audio
+ * graph to schedule against even on scenes that contain no audio nodes.
+ */
+export declare class WebTicker extends Ticker {
+    private readonly contextOf;
+    private readonly ownsContext;
+    private _context;
+    private fps;
+    private playStartCtxTime;
+    private seekOffset;
+    private speed;
+    private reverse;
+    private rafId;
+    /** Bumped by every `seek`, so the loop can tell that a listener or tick callback moved the playhead under it. */
+    private seekEpoch;
+    private silentSource;
+    /**
+     * `context` may be a getter, called on the first `play`: a session hands
+     * over its audio sink's, which is created on first use, so a session that
+     * never plays never opens the audio device.
+     */
+    constructor(opts: {
+        context?: AudioContext | (() => AudioContext);
+        fps: number;
+    });
+    getContext(): AudioContext;
+    private get context();
+    seek(t: number): void;
+    /**
+     * Anchors elapsed-time tracking to the current `context.currentTime`, starts the silent ticker
+     * + rAF tick loop and asks a suspended context to resume.
+     *
+     * Synchronous, as {@link Ticker.play} is: a `pause` or `seek` in the same turn must find a
+     * running clock to stop. A suspended context's `currentTime` is frozen, so the clock holds at
+     * the anchor until the resume lands — outside a user gesture that is never.
+     */
+    play(speed?: number, reverse?: boolean): void;
+    /** Stops the tick loop and silent ticker, then suspends the context — freezing `currentTime` so elapsed-time math stays correct across the pause. */
+    pause(): void;
+    /** (Re)starts the silent buffer source covering the remaining timeline — keeps the AudioContext active and gives a stable graph for other AudioBufferSourceNodes to schedule against, per the class-level note. */
+    private startSilentTicker;
+    private stopSilentTicker;
+    /** Where the playhead is now, from elapsed `context.currentTime` (so it stays sample-accurate), and whether that is the end of the run. */
+    private position;
+    /**
+     * Drives ticks off `requestAnimationFrame`, firing `tick()` when the playhead reaches another
+     * project frame — and once more at the end of the run, whether or not it landed on a boundary.
+     *
+     * `context.currentTime` moves in whole render quanta handed over in bursts: at 48 kHz on a
+     * 60 Hz display it advances 8, 10.67, 18.67 or 21.33 ms between animation frames, and a
+     * playhead read straight off it skipped up to a third of the frames. So the playhead advances
+     * by each animation frame's own interval, pulled 5% of the way to the audio clock every frame
+     * and snapped to it when they disagree by more than 50 ms (a stall, a seek). It stays within
+     * a few ms of the audio and moves one frame per frame.
+     *
+     * A listener may `seek` (a host looping wraps to 0 when it hears the end), so the end is
+     * re-read after the listeners and the tick callbacks have run: a run that was seeked out of
+     * its end carries on, and one that was not pauses itself.
+     */
+    private startLoop;
+    private stopLoop;
+    dispose(): void;
+}
+//# sourceMappingURL=ticker.d.ts.map

package/dist/ticker.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ticker.d.ts","sourceRoot":"","sources":["../src/ticker.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAE,MAAM,oBAAoB,CAAC;AAE5C;;;;;;;;;;;GAWG;AACH,qBAAa,SAAU,SAAQ,MAAM;IACjC,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAqB;IAC/C,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAU;IACtC,OAAO,CAAC,QAAQ,CAA6B;IAC7C,OAAO,CAAC,GAAG,CAAS;IAEpB,OAAO,CAAC,gBAAgB,CAAa;IACrC,OAAO,CAAC,UAAU,CAAa;IAC/B,OAAO,CAAC,KAAK,CAAa;IAC1B,OAAO,CAAC,OAAO,CAAkB;IAEjC,OAAO,CAAC,KAAK,CAAuB;IACpC,iHAAiH;IACjH,OAAO,CAAC,SAAS,CAAa;IAC9B,OAAO,CAAC,YAAY,CAAsC;IAE1D;;;;OAIG;gBACS,IAAI,EAAE;QAAE,OAAO,CAAC,EAAE,YAAY,GAAG,CAAC,MAAM,YAAY,CAAC,CAAC;QAAC,GAAG,EAAE,MAAM,CAAA;KAAE;IAQhF,UAAU,IAAI,YAAY;IAK1B,OAAO,KAAK,OAAO,GAElB;IAED,IAAI,CAAC,CAAC,EAAE,MAAM,GAAG,IAAI;IASrB;;;;;;;OAOG;IACH,IAAI,CAAC,KAAK,GAAE,MAAU,EAAE,OAAO,GAAE,OAAe,GAAG,IAAI;IAwBvD,qJAAqJ;IACrJ,KAAK,IAAI,IAAI;IAUb,mNAAmN;IACnN,OAAO,CAAC,iBAAiB;IAYzB,OAAO,CAAC,gBAAgB;IAaxB,2IAA2I;IAC3I,OAAO,CAAC,QAAQ;IAShB;;;;;;;;;;;;;;OAcG;IACH,OAAO,CAAC,SAAS;IA6DjB,OAAO,CAAC,QAAQ;IAOhB,OAAO,IAAI,IAAI;CAQlB"}