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

package/dist/index.js

@@ -0,0 +1,72 @@
+// @motionscript/browser — CanvasKit/Skia-based renderer for @motionscript/core,
+// running in the browser (canvas mount, video export, audio playback/clock).
+export { WebRenderContext } from "./render-context";
+export { WebStorageAdapter } from "./storage-adapter";
+// The seam letting a host answer for an asset's bytes before the adapter goes
+// to the network — see `asset-bytes.ts` for why it is module-level.
+export { setAssetByteSource } from "./asset-bytes";
+export { getCanvasKit } from "./getter";
+// Re-exported from @motionscript/skia-render, whose canonical home these are —
+// kept on this barrel so the specifier consumers already use keeps resolving.
+export { EffectRegistry } from "@motionscript/skia-render";
+export { exportVideo, } from "./exporter";
+// mediabunny's resolution-aware quality levels, re-exported so a host can pick
+// one for `ExportParams.video.bitrate` without taking a direct dependency on the
+// encoder library this package happens to use.
+export { QUALITY_VERY_LOW, QUALITY_LOW, QUALITY_MEDIUM, QUALITY_HIGH, QUALITY_VERY_HIGH, } from "mediabunny";
+export { exportScreenshot } from "./screenshot";
+// Joins separately-encoded MP4s end to end without re-encoding. What makes it
+// worth rendering an export in parallel at all: the parts still have to become
+// one file, and re-encoding to join them gives back everything the parallelism
+// won. See `concat.ts` for the two things a caller has to guarantee.
+export { concatVideoSegments, ConcatMismatchError } from "./concat";
+// Mixes a timeline's audio without rendering a frame — the other half of a split
+// export, whose video arrives in separately-encoded pieces that AAC cannot be
+// concatenated across. See `mix-timeline-audio.ts`.
+export { mixTimelineAudio } from "./mix-timeline-audio";
+// Single frames as a first-class capability: one long-lived renderer that repaints
+// into a canvas the host owns, for thumbnails and still previews. `exportScreenshot`
+// above is the one-shot wrapper over it.
+export { StillRenderer, createStillRenderer } from "./still";
+export { WebAudioSink as WebAudioPlayer } from "./audio/player";
+// Mixdown. Also on the `@motionscript/browser/audio` subpath, which is the
+// import to prefer — it reaches it without loading CanvasKit, since none of it
+// draws.
+export { mixAudio, encodeWav } from "./audio/mixer";
+export { WebMeasureContext } from "./measure-context";
+export { WebTicker } from "./ticker";
+// Exported from the barrel, never from a subpath of its own: the 3D
+// registrations at the bottom of this file are what make `Canvas3D` draw
+// anything, and a consumer reaching `createBrowserEngine` without evaluating
+// this module would get an engine whose 3D silently renders empty.
+export { createBrowserEngine } from "./engine";
+// ─── 3D ──────────────────────────────────────────────────────────────────────
+// The reconciler, handlers and lazy `three` boundary all live in
+// @motionscript/skia-render now; this package supplies only the WebGL renderer
+// that rasterizes what they build. Re-exported here so the specifiers consumers
+// already use keep resolving.
+export { Canvas3DBackend, canvas3DBackend, loadCanvas3D, disposeCanvas3DBackend } from "@motionscript/skia-render";
+import { registerCanvas3DBackend, registerCanvas3DRendererHost } from "@motionscript/skia-render";
+import { webCanvas3DRendererHost } from "./three/renderer";
+// Hand core the three-loading hook so the loader `Canvas3D.declareAssets()` declares
+// can preload the runtime before any frame draws. Done at module scope rather
+// than lazily because core has no way to reach into this package on its own — the
+// registration is the seam.
+//
+// Note this package declares `sideEffects: false`, which is still accurate: the
+// call has no observable effect for a 2D-only project (it just stores a function
+// reference), and because it lives in the barrel every consumer imports, a
+// bundler can't drop it while keeping anything else here.
+registerCanvas3DBackend();
+// Hand skia-render the WebGL renderer, for the same reason and with the same
+// constraint: it MUST be registered from this barrel.
+//
+// `./three/renderer` is no longer statically imported by anything else in this
+// package — the reconciler that used to import it moved out. Combined with
+// `sideEffects: false`, a module-scope registration inside that file could be
+// tree-shaken away, and the failure is silent: `canvas3DBackend()` returns null
+// forever, the warm-and-retry loop exhausts its three passes, and every frame
+// ships its 2D parts with no 3D and no error. Registering here keeps the module
+// reachable and the behaviour explicit.
+registerCanvas3DRendererHost(webCanvas3DRendererHost);
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,gFAAgF;AAChF,6EAA6E;AAE7E,OAAO,EAAE,gBAAgB,EAAE,MAAM,kBAAkB,CAAC;AACpD,OAAO,EAAE,iBAAiB,EAAE,MAAM,mBAAmB,CAAC;AACtD,8EAA8E;AAC9E,oEAAoE;AACpE,OAAO,EAAE,kBAAkB,EAAwB,MAAM,eAAe,CAAC;AACzE,OAAO,EAAE,YAAY,EAAE,MAAM,UAAU,CAAC;AACxC,+EAA+E;AAC/E,8EAA8E;AAC9E,OAAO,EAAE,cAAc,EAAE,MAAM,2BAA2B,CAAC;AAE3D,OAAO,EACH,WAAW,GAKd,MAAM,YAAY,CAAC;AACpB,+EAA+E;AAC/E,iFAAiF;AACjF,+CAA+C;AAC/C,OAAO,EACH,gBAAgB,EAChB,WAAW,EACX,cAAc,EACd,YAAY,EACZ,iBAAiB,GAEpB,MAAM,YAAY,CAAC;AACpB,OAAO,EAAE,gBAAgB,EAAuF,MAAM,cAAc,CAAC;AACrI,8EAA8E;AAC9E,+EAA+E;AAC/E,+EAA+E;AAC/E,qEAAqE;AACrE,OAAO,EAAE,mBAAmB,EAAE,mBAAmB,EAAsB,MAAM,UAAU,CAAC;AACxF,iFAAiF;AACjF,8EAA8E;AAC9E,oDAAoD;AACpD,OAAO,EAAE,gBAAgB,EAA+B,MAAM,sBAAsB,CAAC;AACrF,mFAAmF;AACnF,qFAAqF;AACrF,yCAAyC;AACzC,OAAO,EAAE,aAAa,EAAE,mBAAmB,EAAE,MAAM,SAAS,CAAC;AAQ7D,OAAO,EAAE,YAAY,IAAI,cAAc,EAAE,MAAM,gBAAgB,CAAC;AAChE,2EAA2E;AAC3E,+EAA+E;AAC/E,SAAS;AACT,OAAO,EAAE,QAAQ,EAAE,SAAS,EAAwB,MAAM,eAAe,CAAC;AAC1E,OAAO,EAAE,iBAAiB,EAAE,MAAM,mBAAmB,CAAC;AACtD,OAAO,EAAE,SAAS,EAAE,MAAM,UAAU,CAAC;AAErC,oEAAoE;AACpE,yEAAyE;AACzE,6EAA6E;AAC7E,mEAAmE;AACnE,OAAO,EAAE,mBAAmB,EAAE,MAAM,UAAU,CAAC;AAG/C,gFAAgF;AAEhF,iEAAiE;AACjE,+EAA+E;AAC/E,gFAAgF;AAChF,8BAA8B;AAC9B,OAAO,EAAE,eAAe,EAAE,eAAe,EAAE,YAAY,EAAE,sBAAsB,EAAE,MAAM,2BAA2B,CAAC;AAGnH,OAAO,EAAE,uBAAuB,EAAE,4BAA4B,EAAE,MAAM,2BAA2B,CAAC;AAClG,OAAO,EAAE,uBAAuB,EAAE,MAAM,kBAAkB,CAAC;AAE3D,qFAAqF;AACrF,8EAA8E;AAC9E,kFAAkF;AAClF,4BAA4B;AAC5B,EAAE;AACF,gFAAgF;AAChF,iFAAiF;AACjF,2EAA2E;AAC3E,0DAA0D;AAC1D,uBAAuB,EAAE,CAAC;AAE1B,6EAA6E;AAC7E,sDAAsD;AACtD,EAAE;AACF,+EAA+E;AAC/E,2EAA2E;AAC3E,8EAA8E;AAC9E,gFAAgF;AAChF,8EAA8E;AAC9E,gFAAgF;AAChF,wCAAwC;AACxC,4BAA4B,CAAC,uBAAuB,CAAC,CAAC","sourcesContent":["// @motionscript/browser — CanvasKit/Skia-based renderer for @motionscript/core,\n// running in the browser (canvas mount, video export, audio playback/clock).\n\nexport { WebRenderContext } from \"./render-context\";\nexport { WebStorageAdapter } from \"./storage-adapter\";\n// The seam letting a host answer for an asset's bytes before the adapter goes\n// to the network — see `asset-bytes.ts` for why it is module-level.\nexport { setAssetByteSource, type AssetByteSource } from \"./asset-bytes\";\nexport { getCanvasKit } from \"./getter\";\n// Re-exported from @motionscript/skia-render, whose canonical home these are —\n// kept on this barrel so the specifier consumers already use keeps resolving.\nexport { EffectRegistry } from \"@motionscript/skia-render\";\nexport type { EffectHandler, EffectGeometry, EffectResources, EffectTarget, RenderEffect } from \"@motionscript/skia-render\";\nexport {\n    exportVideo,\n    type ExportParams,\n    type ExportProgressCallback,\n    type VideoEncoderOptions,\n    type AudioEncoderOptions,\n} from \"./exporter\";\n// mediabunny's resolution-aware quality levels, re-exported so a host can pick\n// one for `ExportParams.video.bitrate` without taking a direct dependency on the\n// encoder library this package happens to use.\nexport {\n    QUALITY_VERY_LOW,\n    QUALITY_LOW,\n    QUALITY_MEDIUM,\n    QUALITY_HIGH,\n    QUALITY_VERY_HIGH,\n    type Quality,\n} from \"mediabunny\";\nexport { exportScreenshot, type ScreenshotParams, type ScreenshotResult, type ScreenshotFormat, type FrameSpec } from \"./screenshot\";\n// Joins separately-encoded MP4s end to end without re-encoding. What makes it\n// worth rendering an export in parallel at all: the parts still have to become\n// one file, and re-encoding to join them gives back everything the parallelism\n// won. See `concat.ts` for the two things a caller has to guarantee.\nexport { concatVideoSegments, ConcatMismatchError, type ConcatOptions } from \"./concat\";\n// Mixes a timeline's audio without rendering a frame — the other half of a split\n// export, whose video arrives in separately-encoded pieces that AAC cannot be\n// concatenated across. See `mix-timeline-audio.ts`.\nexport { mixTimelineAudio, type MixTimelineAudioParams } from \"./mix-timeline-audio\";\n// Single frames as a first-class capability: one long-lived renderer that repaints\n// into a canvas the host owns, for thumbnails and still previews. `exportScreenshot`\n// above is the one-shot wrapper over it.\nexport { StillRenderer, createStillRenderer } from \"./still\";\nexport type {\n    StillRendererOptions,\n    RenderStillOptions,\n    EncodeStillOptions,\n    StillSource,\n    FrameRef,\n} from \"./still\";\nexport { WebAudioSink as WebAudioPlayer } from \"./audio/player\";\n// Mixdown. Also on the `@motionscript/browser/audio` subpath, which is the\n// import to prefer — it reaches it without loading CanvasKit, since none of it\n// draws.\nexport { mixAudio, encodeWav, type MixAudioOptions } from \"./audio/mixer\";\nexport { WebMeasureContext } from \"./measure-context\";\nexport { WebTicker } from \"./ticker\";\n\n// Exported from the barrel, never from a subpath of its own: the 3D\n// registrations at the bottom of this file are what make `Canvas3D` draw\n// anything, and a consumer reaching `createBrowserEngine` without evaluating\n// this module would get an engine whose 3D silently renders empty.\nexport { createBrowserEngine } from \"./engine\";\nexport type { BrowserEngineOptions, BrowserEncodeOptions } from \"./engine\";\n\n// ─── 3D ──────────────────────────────────────────────────────────────────────\n\n// The reconciler, handlers and lazy `three` boundary all live in\n// @motionscript/skia-render now; this package supplies only the WebGL renderer\n// that rasterizes what they build. Re-exported here so the specifiers consumers\n// already use keep resolving.\nexport { Canvas3DBackend, canvas3DBackend, loadCanvas3D, disposeCanvas3DBackend } from \"@motionscript/skia-render\";\nexport type { Canvas3DAssets, RenderedCanvas3D } from \"@motionscript/skia-render\";\n\nimport { registerCanvas3DBackend, registerCanvas3DRendererHost } from \"@motionscript/skia-render\";\nimport { webCanvas3DRendererHost } from \"./three/renderer\";\n\n// Hand core the three-loading hook so the loader `Canvas3D.declareAssets()` declares\n// can preload the runtime before any frame draws. Done at module scope rather\n// than lazily because core has no way to reach into this package on its own — the\n// registration is the seam.\n//\n// Note this package declares `sideEffects: false`, which is still accurate: the\n// call has no observable effect for a 2D-only project (it just stores a function\n// reference), and because it lives in the barrel every consumer imports, a\n// bundler can't drop it while keeping anything else here.\nregisterCanvas3DBackend();\n\n// Hand skia-render the WebGL renderer, for the same reason and with the same\n// constraint: it MUST be registered from this barrel.\n//\n// `./three/renderer` is no longer statically imported by anything else in this\n// package — the reconciler that used to import it moved out. Combined with\n// `sideEffects: false`, a module-scope registration inside that file could be\n// tree-shaken away, and the failure is silent: `canvas3DBackend()` returns null\n// forever, the warm-and-retry loop exhausts its three passes, and every frame\n// ships its 2D parts with no 3D and no error. Registering here keeps the module\n// reachable and the behaviour explicit.\nregisterCanvas3DRendererHost(webCanvas3DRendererHost);\n"]}

package/dist/measure-context.d.ts

@@ -0,0 +1,12 @@
+import { SkiaMeasureContext } from "@motionscript/skia-render/measure-context";
+/**
+ * Browser alias for {@link SkiaMeasureContext}.
+ *
+ * A real subclass rather than a re-export, so `instanceof WebMeasureContext` and the
+ * name in a stack trace both still mean something, and so a future
+ * browser-specific measurement path has an obvious home. Text measurement itself
+ * is pure Skia paragraph layout and needs no platform code at all.
+ */
+export declare class WebMeasureContext extends SkiaMeasureContext {
+}
+//# sourceMappingURL=measure-context.d.ts.map

package/dist/measure-context.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"measure-context.d.ts","sourceRoot":"","sources":["../src/measure-context.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,kBAAkB,EAAE,MAAM,2CAA2C,CAAC;AAE/E;;;;;;;GAOG;AACH,qBAAa,iBAAkB,SAAQ,kBAAkB;CAAI"}

package/dist/measure-context.js

@@ -0,0 +1,12 @@
+import { SkiaMeasureContext } from "@motionscript/skia-render/measure-context";
+/**
+ * Browser alias for {@link SkiaMeasureContext}.
+ *
+ * A real subclass rather than a re-export, so `instanceof WebMeasureContext` and the
+ * name in a stack trace both still mean something, and so a future
+ * browser-specific measurement path has an obvious home. Text measurement itself
+ * is pure Skia paragraph layout and needs no platform code at all.
+ */
+export class WebMeasureContext extends SkiaMeasureContext {
+}
+//# sourceMappingURL=measure-context.js.map

package/dist/measure-context.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"measure-context.js","sourceRoot":"","sources":["../src/measure-context.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,kBAAkB,EAAE,MAAM,2CAA2C,CAAC;AAE/E;;;;;;;GAOG;AACH,MAAM,OAAO,iBAAkB,SAAQ,kBAAkB;CAAI","sourcesContent":["import { SkiaMeasureContext } from \"@motionscript/skia-render/measure-context\";\n\n/**\n * Browser alias for {@link SkiaMeasureContext}.\n *\n * A real subclass rather than a re-export, so `instanceof WebMeasureContext` and the\n * name in a stack trace both still mean something, and so a future\n * browser-specific measurement path has an obvious home. Text measurement itself\n * is pure Skia paragraph layout and needs no platform code at all.\n */\nexport class WebMeasureContext extends SkiaMeasureContext { }\n"]}

package/dist/mix-timeline-audio.d.ts

@@ -0,0 +1,42 @@
+import { Registry, type AssetManifest, type ProjectDocument, type SceneDocument, type Size2D } from "@motionscript/core";
+export interface MixTimelineAudioParams {
+    /** A project, or a lone still or composition as the one track of one. */
+    document: ProjectDocument | SceneDocument;
+    /** 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;
+    manifest?: AssetManifest;
+    /** Mixdown rate. Defaults to the mixer's own (44100). */
+    sampleRate?: number;
+    wasmUrl?: string;
+}
+/**
+ * Mix a timeline's audio without rendering a single frame.
+ *
+ * `exportVideo` normally does this as part of the render, and for a
+ * single-threaded export that is exactly right. A **split** export cannot: its
+ * video is rendered in pieces by separate workers, and concatenating
+ * separately-encoded AAC puts the encoder's priming delay at every join — a click
+ * at each boundary and a track that drifts further out of sync with every one. So
+ * the coordinator mixes the whole timeline once, here, and the joined file gets a
+ * single continuous audio track.
+ *
+ * Returns `null` when the timeline schedules no audio at all, which is the common
+ * case and not a failure — the caller should then mux video only rather than
+ * declare an empty track.
+ *
+ * ## Why this discovers
+ *
+ * Audio requests are an *output of discovery*: each node declares its clips as it
+ * enters the tree, and the pass that finds what a clip's frames draw is the one
+ * that puts its nodes in the tree, so there is no way to know what plays when
+ * without it.
+ *
+ * Nothing is drawn, so this takes a {@link WebMeasureContext} rather than a render
+ * context: discovery lays each clip out, which needs text measured, not
+ * rasterized. No canvas, no surface, no GPU.
+ */
+export declare function mixTimelineAudio(params: MixTimelineAudioParams): Promise<AudioBuffer | null>;
+//# sourceMappingURL=mix-timeline-audio.d.ts.map

package/dist/mix-timeline-audio.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"mix-timeline-audio.d.ts","sourceRoot":"","sources":["../src/mix-timeline-audio.ts"],"names":[],"mappings":"AAAA,OAAO,EAGH,QAAQ,EAER,KAAK,aAAa,EAClB,KAAK,eAAe,EACpB,KAAK,aAAa,EAClB,KAAK,MAAM,EACd,MAAM,oBAAoB,CAAC;AAS5B,MAAM,WAAW,sBAAsB;IACnC,yEAAyE;IACzE,QAAQ,EAAE,eAAe,GAAG,aAAa,CAAC;IAC1C,oFAAoF;IACpF,QAAQ,CAAC,EAAE,QAAQ,CAAC;IACpB,0EAA0E;IAC1E,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,QAAQ,CAAC,EAAE,aAAa,CAAC;IACzB,yDAAyD;IACzD,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,OAAO,CAAC,EAAE,MAAM,CAAC;CACpB;AAID;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,wBAAsB,gBAAgB,CAClC,MAAM,EAAE,sBAAsB,GAC/B,OAAO,CAAC,WAAW,GAAG,IAAI,CAAC,CA4B7B"}

package/dist/mix-timeline-audio.js

@@ -0,0 +1,63 @@
+import { ManifestAssetCatalog, AssetTimeline, Registry, resolveProjectDocument, } from "@motionscript/core";
+import { collectAudio } from "@motionscript/skia-render/export";
+import { mixAudio } from "./audio/mixer";
+import { getCanvasKit } from "./getter";
+import { WebMeasureContext } from "./measure-context";
+import { DEFAULT_OUTPUT } from "./output";
+import { WebStorageAdapter } from "./storage-adapter";
+const EMPTY_MANIFEST = { image: {}, video: {}, audio: {}, font: {} };
+/**
+ * Mix a timeline's audio without rendering a single frame.
+ *
+ * `exportVideo` normally does this as part of the render, and for a
+ * single-threaded export that is exactly right. A **split** export cannot: its
+ * video is rendered in pieces by separate workers, and concatenating
+ * separately-encoded AAC puts the encoder's priming delay at every join — a click
+ * at each boundary and a track that drifts further out of sync with every one. So
+ * the coordinator mixes the whole timeline once, here, and the joined file gets a
+ * single continuous audio track.
+ *
+ * Returns `null` when the timeline schedules no audio at all, which is the common
+ * case and not a failure — the caller should then mux video only rather than
+ * declare an empty track.
+ *
+ * ## Why this discovers
+ *
+ * Audio requests are an *output of discovery*: each node declares its clips as it
+ * enters the tree, and the pass that finds what a clip's frames draw is the one
+ * that puts its nodes in the tree, so there is no way to know what plays when
+ * without it.
+ *
+ * Nothing is drawn, so this takes a {@link WebMeasureContext} rather than a render
+ * context: discovery lays each clip out, which needs text measured, not
+ * rasterized. No canvas, no surface, no GPU.
+ */
+export async function mixTimelineAudio(params) {
+    const { registry = new Registry(), manifest = EMPTY_MANIFEST, sampleRate, wasmUrl } = params;
+    const project = resolveProjectDocument(params.document, params, DEFAULT_OUTPUT);
+    if (project.tracks.length === 0)
+        return null;
+    const viewport = project.viewport;
+    const fps = project.fps;
+    // CanvasKit only for its font manager — `WebMeasureContext` shapes text through it.
+    const canvasKit = await getCanvasKit(wasmUrl);
+    const catalog = new ManifestAssetCatalog(manifest);
+    const storage = new WebStorageAdapter(canvasKit, catalog, viewport, fps);
+    const measurer = new WebMeasureContext(storage);
+    // Audio is declared from each node's arrival state, so no asset windows are refined.
+    const precomper = new AssetTimeline(project, { registry, viewport, fps, assets: catalog, measurer }, { assets: false });
+    try {
+        const precomp = precomper.run();
+        const scheduled = collectAudio(precomp);
+        if (scheduled.length === 0)
+            return null;
+        return await mixAudio(scheduled, precomp.totalDuration, { sampleRate, catalog });
+    }
+    finally {
+        precomper.dispose();
+        // The adapter holds decode sessions and cached images; without this a mix
+        // leaks them for the life of the page.
+        storage.dispose();
+    }
+}
+//# sourceMappingURL=mix-timeline-audio.js.map

package/dist/mix-timeline-audio.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"mix-timeline-audio.js","sourceRoot":"","sources":["../src/mix-timeline-audio.ts"],"names":[],"mappings":"AAAA,OAAO,EACH,oBAAoB,EACpB,aAAa,EACb,QAAQ,EACR,sBAAsB,GAKzB,MAAM,oBAAoB,CAAC;AAC5B,OAAO,EAAE,YAAY,EAAE,MAAM,kCAAkC,CAAC;AAEhE,OAAO,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAC;AACzC,OAAO,EAAE,YAAY,EAAE,MAAM,UAAU,CAAC;AACxC,OAAO,EAAE,iBAAiB,EAAE,MAAM,mBAAmB,CAAC;AACtD,OAAO,EAAE,cAAc,EAAE,MAAM,UAAU,CAAC;AAC1C,OAAO,EAAE,iBAAiB,EAAE,MAAM,mBAAmB,CAAC;AAgBtD,MAAM,cAAc,GAAkB,EAAE,KAAK,EAAE,EAAE,EAAE,KAAK,EAAE,EAAE,EAAE,KAAK,EAAE,EAAE,EAAE,IAAI,EAAE,EAAE,EAAE,CAAC;AAEpF;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,MAAM,CAAC,KAAK,UAAU,gBAAgB,CAClC,MAA8B;IAE9B,MAAM,EAAE,QAAQ,GAAG,IAAI,QAAQ,EAAE,EAAE,QAAQ,GAAG,cAAc,EAAE,UAAU,EAAE,OAAO,EAAE,GAAG,MAAM,CAAC;IAC7F,MAAM,OAAO,GAAG,sBAAsB,CAAC,MAAM,CAAC,QAAQ,EAAE,MAAM,EAAE,cAAc,CAAC,CAAC;IAChF,IAAI,OAAO,CAAC,MAAM,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,IAAI,CAAC;IAC7C,MAAM,QAAQ,GAAG,OAAO,CAAC,QAAS,CAAC;IACnC,MAAM,GAAG,GAAG,OAAO,CAAC,GAAI,CAAC;IAEzB,oFAAoF;IACpF,MAAM,SAAS,GAAG,MAAM,YAAY,CAAC,OAAO,CAAC,CAAC;IAC9C,MAAM,OAAO,GAAG,IAAI,oBAAoB,CAAC,QAAQ,CAAC,CAAC;IACnD,MAAM,OAAO,GAAG,IAAI,iBAAiB,CAAC,SAAS,EAAE,OAAO,EAAE,QAAQ,EAAE,GAAG,CAAC,CAAC;IACzE,MAAM,QAAQ,GAAG,IAAI,iBAAiB,CAAC,OAAO,CAAC,CAAC;IAEhD,qFAAqF;IACrF,MAAM,SAAS,GAAG,IAAI,aAAa,CAAC,OAAO,EAAE,EAAE,QAAQ,EAAE,QAAQ,EAAE,GAAG,EAAE,MAAM,EAAE,OAAO,EAAE,QAAQ,EAAE,EAAE,EAAE,MAAM,EAAE,KAAK,EAAE,CAAC,CAAC;IACxH,IAAI,CAAC;QACD,MAAM,OAAO,GAAG,SAAS,CAAC,GAAG,EAAE,CAAC;QAEhC,MAAM,SAAS,GAAG,YAAY,CAAC,OAAO,CAAC,CAAC;QACxC,IAAI,SAAS,CAAC,MAAM,KAAK,CAAC;YAAE,OAAO,IAAI,CAAC;QAExC,OAAO,MAAM,QAAQ,CAAC,SAAS,EAAE,OAAO,CAAC,aAAa,EAAE,EAAE,UAAU,EAAE,OAAO,EAAE,CAAC,CAAC;IACrF,CAAC;YAAS,CAAC;QACP,SAAS,CAAC,OAAO,EAAE,CAAC;QACpB,0EAA0E;QAC1E,uCAAuC;QACvC,OAAO,CAAC,OAAO,EAAE,CAAC;IACtB,CAAC;AACL,CAAC","sourcesContent":["import {\n    ManifestAssetCatalog,\n    AssetTimeline,\n    Registry,\n    resolveProjectDocument,\n    type AssetManifest,\n    type ProjectDocument,\n    type SceneDocument,\n    type Size2D,\n} from \"@motionscript/core\";\nimport { collectAudio } from \"@motionscript/skia-render/export\";\n\nimport { mixAudio } from \"./audio/mixer\";\nimport { getCanvasKit } from \"./getter\";\nimport { WebMeasureContext } from \"./measure-context\";\nimport { DEFAULT_OUTPUT } from \"./output\";\nimport { WebStorageAdapter } from \"./storage-adapter\";\n\nexport interface MixTimelineAudioParams {\n    /** A project, or a lone still or composition as the one track of one. */\n    document: ProjectDocument | SceneDocument;\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    manifest?: AssetManifest;\n    /** Mixdown rate. Defaults to the mixer's own (44100). */\n    sampleRate?: number;\n    wasmUrl?: string;\n}\n\nconst EMPTY_MANIFEST: AssetManifest = { image: {}, video: {}, audio: {}, font: {} };\n\n/**\n * Mix a timeline's audio without rendering a single frame.\n *\n * `exportVideo` normally does this as part of the render, and for a\n * single-threaded export that is exactly right. A **split** export cannot: its\n * video is rendered in pieces by separate workers, and concatenating\n * separately-encoded AAC puts the encoder's priming delay at every join — a click\n * at each boundary and a track that drifts further out of sync with every one. So\n * the coordinator mixes the whole timeline once, here, and the joined file gets a\n * single continuous audio track.\n *\n * Returns `null` when the timeline schedules no audio at all, which is the common\n * case and not a failure — the caller should then mux video only rather than\n * declare an empty track.\n *\n * ## Why this discovers\n *\n * Audio requests are an *output of discovery*: each node declares its clips as it\n * enters the tree, and the pass that finds what a clip's frames draw is the one\n * that puts its nodes in the tree, so there is no way to know what plays when\n * without it.\n *\n * Nothing is drawn, so this takes a {@link WebMeasureContext} rather than a render\n * context: discovery lays each clip out, which needs text measured, not\n * rasterized. No canvas, no surface, no GPU.\n */\nexport async function mixTimelineAudio(\n    params: MixTimelineAudioParams,\n): Promise<AudioBuffer | null> {\n    const { registry = new Registry(), manifest = EMPTY_MANIFEST, sampleRate, wasmUrl } = params;\n    const project = resolveProjectDocument(params.document, params, DEFAULT_OUTPUT);\n    if (project.tracks.length === 0) return null;\n    const viewport = project.viewport!;\n    const fps = project.fps!;\n\n    // CanvasKit only for its font manager — `WebMeasureContext` shapes text through it.\n    const canvasKit = await getCanvasKit(wasmUrl);\n    const catalog = new ManifestAssetCatalog(manifest);\n    const storage = new WebStorageAdapter(canvasKit, catalog, viewport, fps);\n    const measurer = new WebMeasureContext(storage);\n\n    // Audio is declared from each node's arrival state, so no asset windows are refined.\n    const precomper = new AssetTimeline(project, { registry, viewport, fps, assets: catalog, measurer }, { assets: false });\n    try {\n        const precomp = precomper.run();\n\n        const scheduled = collectAudio(precomp);\n        if (scheduled.length === 0) return null;\n\n        return await mixAudio(scheduled, precomp.totalDuration, { sampleRate, catalog });\n    } finally {\n        precomper.dispose();\n        // The adapter holds decode sessions and cached images; without this a mix\n        // leaks them for the life of the page.\n        storage.dispose();\n    }\n}\n"]}

package/dist/output.d.ts

@@ -0,0 +1,7 @@
+import type { Size2D } from "@motionscript/core";
+/** What a document renders at when neither the caller nor the document says. */
+export declare const DEFAULT_OUTPUT: {
+    viewport: Size2D;
+    fps: number;
+};
+//# sourceMappingURL=output.d.ts.map

package/dist/output.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"output.d.ts","sourceRoot":"","sources":["../src/output.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,oBAAoB,CAAC;AAEjD,gFAAgF;AAChF,eAAO,MAAM,cAAc,EAAE;IAAE,QAAQ,EAAE,MAAM,CAAC;IAAC,GAAG,EAAE,MAAM,CAAA;CAG3D,CAAC"}

package/dist/output.js

@@ -0,0 +1,6 @@
+/** What a document renders at when neither the caller nor the document says. */
+export const DEFAULT_OUTPUT = {
+    viewport: { width: 1920, height: 1080 },
+    fps: 60,
+};
+//# sourceMappingURL=output.js.map

package/dist/output.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"output.js","sourceRoot":"","sources":["../src/output.ts"],"names":[],"mappings":"AAEA,gFAAgF;AAChF,MAAM,CAAC,MAAM,cAAc,GAAsC;IAC7D,QAAQ,EAAE,EAAE,KAAK,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE;IACvC,GAAG,EAAE,EAAE;CACV,CAAC","sourcesContent":["import type { Size2D } from \"@motionscript/core\";\n\n/** What a document renders at when neither the caller nor the document says. */\nexport const DEFAULT_OUTPUT: { viewport: Size2D; fps: number } = {\n    viewport: { width: 1920, height: 1080 },\n    fps: 60,\n};\n"]}

package/dist/render-context.d.ts

@@ -0,0 +1,30 @@
+import type { CanvasKit } from "@motionscript/canvaskit";
+import { SkiaRenderContext } from "@motionscript/skia-render/render-context";
+import type { WebStorageAdapter } from "./storage-adapter";
+/**
+ * Browser bindings for {@link SkiaRenderContext}.
+ *
+ * Everything about *how a frame is drawn* — shapes, fills, strokes, text, effects,
+ * clips, masks, the camera, the 3D composite — lives in
+ * `@motionscript/skia-render` and is shared with every other backend. What is
+ * genuinely browser-specific is only the two things below: creating a WebGL-backed
+ * Skia surface over a `<canvas>`, and encoding a snapshot (this CanvasKit build
+ * ships no wasm image encoders, so the encode has to come from the host).
+ */
+export declare class WebRenderContext extends SkiaRenderContext {
+    constructor(canvasKit: CanvasKit, storageAdapter: WebStorageAdapter);
+    /** Attaches a WebGL CanvasKit surface to `canvas`, remounting if already mounted (HMR/StrictMode). */
+    mount(canvas: HTMLCanvasElement): void;
+    /**
+     * Core declares `unmount()`; it is `detach()` on the portable base, since
+     * "unmount" only means anything where there is a DOM element to unmount from.
+     */
+    unmount(): void;
+    /**
+     * Snapshots the current surface and encodes it as an image data URL through a
+     * 2D canvas. Defaults to PNG; pass `mime`/`quality` (e.g. `"image/jpeg", 0.9`)
+     * for other formats.
+     */
+    screenshot(mime?: string, quality?: number): string | undefined;
+}
+//# sourceMappingURL=render-context.d.ts.map

package/dist/render-context.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"render-context.d.ts","sourceRoot":"","sources":["../src/render-context.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,yBAAyB,CAAC;AACzD,OAAO,EAAE,iBAAiB,EAAE,MAAM,0CAA0C,CAAC;AAC7E,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,mBAAmB,CAAC;AAE3D;;;;;;;;;GASG;AACH,qBAAa,gBAAiB,SAAQ,iBAAiB;gBACvC,SAAS,EAAE,SAAS,EAAE,cAAc,EAAE,iBAAiB;IAInE,sGAAsG;IACtG,KAAK,CAAC,MAAM,EAAE,iBAAiB,GAAG,IAAI;IAMtC;;;OAGG;IACM,OAAO,IAAI,IAAI;IAIxB;;;;OAIG;IACM,UAAU,CAAC,IAAI,GAAE,MAAoB,EAAE,OAAO,CAAC,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS;CAkBxF"}

package/dist/render-context.js

@@ -0,0 +1,55 @@
+import { SkiaRenderContext } from "@motionscript/skia-render/render-context";
+/**
+ * Browser bindings for {@link SkiaRenderContext}.
+ *
+ * Everything about *how a frame is drawn* — shapes, fills, strokes, text, effects,
+ * clips, masks, the camera, the 3D composite — lives in
+ * `@motionscript/skia-render` and is shared with every other backend. What is
+ * genuinely browser-specific is only the two things below: creating a WebGL-backed
+ * Skia surface over a `<canvas>`, and encoding a snapshot (this CanvasKit build
+ * ships no wasm image encoders, so the encode has to come from the host).
+ */
+export class WebRenderContext extends SkiaRenderContext {
+    constructor(canvasKit, storageAdapter) {
+        super(canvasKit, storageAdapter);
+    }
+    /** Attaches a WebGL CanvasKit surface to `canvas`, remounting if already mounted (HMR/StrictMode). */
+    mount(canvas) {
+        const surface = this.canvasKit.MakeWebGLCanvasSurface(canvas);
+        if (!surface)
+            throw new Error("Failed to create CanvasKit surface");
+        this.attach(surface);
+    }
+    /**
+     * Core declares `unmount()`; it is `detach()` on the portable base, since
+     * "unmount" only means anything where there is a DOM element to unmount from.
+     */
+    unmount() {
+        this.detach();
+    }
+    /**
+     * Snapshots the current surface and encodes it as an image data URL through a
+     * 2D canvas. Defaults to PNG; pass `mime`/`quality` (e.g. `"image/jpeg", 0.9`)
+     * for other formats.
+     */
+    screenshot(mime = "image/png", quality) {
+        const snapshot = this.snapshotPixels();
+        if (!snapshot)
+            return undefined;
+        const { pixels, width, height } = snapshot;
+        const canvas = document.createElement("canvas");
+        canvas.width = width;
+        canvas.height = height;
+        const ctx = canvas.getContext("2d");
+        if (!ctx)
+            return undefined;
+        // `pixels` is already unpremultiplied RGBA8888 copied out of the wasm heap,
+        // which is exactly ImageData's layout.
+        ctx.putImageData(new ImageData(new Uint8ClampedArray(pixels), width, height), 0, 0);
+        // A data: URL rather than a blob: URL — both work as an <img> src and a
+        // data URL needs no revoke. `quality` is honored only by lossy formats
+        // (e.g. image/jpeg); the browser ignores it for image/png.
+        return canvas.toDataURL(mime, quality);
+    }
+}
+//# sourceMappingURL=render-context.js.map

package/dist/render-context.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"render-context.js","sourceRoot":"","sources":["../src/render-context.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,iBAAiB,EAAE,MAAM,0CAA0C,CAAC;AAG7E;;;;;;;;;GASG;AACH,MAAM,OAAO,gBAAiB,SAAQ,iBAAiB;IACnD,YAAY,SAAoB,EAAE,cAAiC;QAC/D,KAAK,CAAC,SAAS,EAAE,cAAc,CAAC,CAAC;IACrC,CAAC;IAED,sGAAsG;IACtG,KAAK,CAAC,MAAyB;QAC3B,MAAM,OAAO,GAAG,IAAI,CAAC,SAAS,CAAC,sBAAsB,CAAC,MAAM,CAAC,CAAC;QAC9D,IAAI,CAAC,OAAO;YAAE,MAAM,IAAI,KAAK,CAAC,oCAAoC,CAAC,CAAC;QACpE,IAAI,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC;IACzB,CAAC;IAED;;;OAGG;IACM,OAAO;QACZ,IAAI,CAAC,MAAM,EAAE,CAAC;IAClB,CAAC;IAED;;;;OAIG;IACM,UAAU,CAAC,OAAe,WAAW,EAAE,OAAgB;QAC5D,MAAM,QAAQ,GAAG,IAAI,CAAC,cAAc,EAAE,CAAC;QACvC,IAAI,CAAC,QAAQ;YAAE,OAAO,SAAS,CAAC;QAChC,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,GAAG,QAAQ,CAAC;QAE3C,MAAM,MAAM,GAAG,QAAQ,CAAC,aAAa,CAAC,QAAQ,CAAC,CAAC;QAChD,MAAM,CAAC,KAAK,GAAG,KAAK,CAAC;QACrB,MAAM,CAAC,MAAM,GAAG,MAAM,CAAC;QACvB,MAAM,GAAG,GAAG,MAAM,CAAC,UAAU,CAAC,IAAI,CAAC,CAAC;QACpC,IAAI,CAAC,GAAG;YAAE,OAAO,SAAS,CAAC;QAC3B,4EAA4E;QAC5E,uCAAuC;QACvC,GAAG,CAAC,YAAY,CAAC,IAAI,SAAS,CAAC,IAAI,iBAAiB,CAAC,MAAM,CAAC,EAAE,KAAK,EAAE,MAAM,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,CAAC;QACpF,wEAAwE;QACxE,uEAAuE;QACvE,2DAA2D;QAC3D,OAAO,MAAM,CAAC,SAAS,CAAC,IAAI,EAAE,OAAO,CAAC,CAAC;IAC3C,CAAC;CACJ","sourcesContent":["import type { CanvasKit } from \"@motionscript/canvaskit\";\nimport { SkiaRenderContext } from \"@motionscript/skia-render/render-context\";\nimport type { WebStorageAdapter } from \"./storage-adapter\";\n\n/**\n * Browser bindings for {@link SkiaRenderContext}.\n *\n * Everything about *how a frame is drawn* — shapes, fills, strokes, text, effects,\n * clips, masks, the camera, the 3D composite — lives in\n * `@motionscript/skia-render` and is shared with every other backend. What is\n * genuinely browser-specific is only the two things below: creating a WebGL-backed\n * Skia surface over a `<canvas>`, and encoding a snapshot (this CanvasKit build\n * ships no wasm image encoders, so the encode has to come from the host).\n */\nexport class WebRenderContext extends SkiaRenderContext {\n    constructor(canvasKit: CanvasKit, storageAdapter: WebStorageAdapter) {\n        super(canvasKit, storageAdapter);\n    }\n\n    /** Attaches a WebGL CanvasKit surface to `canvas`, remounting if already mounted (HMR/StrictMode). */\n    mount(canvas: HTMLCanvasElement): void {\n        const surface = this.canvasKit.MakeWebGLCanvasSurface(canvas);\n        if (!surface) throw new Error(\"Failed to create CanvasKit surface\");\n        this.attach(surface);\n    }\n\n    /**\n     * Core declares `unmount()`; it is `detach()` on the portable base, since\n     * \"unmount\" only means anything where there is a DOM element to unmount from.\n     */\n    override unmount(): void {\n        this.detach();\n    }\n\n    /**\n     * Snapshots the current surface and encodes it as an image data URL through a\n     * 2D canvas. Defaults to PNG; pass `mime`/`quality` (e.g. `\"image/jpeg\", 0.9`)\n     * for other formats.\n     */\n    override screenshot(mime: string = \"image/png\", quality?: number): string | undefined {\n        const snapshot = this.snapshotPixels();\n        if (!snapshot) return undefined;\n        const { pixels, width, height } = snapshot;\n\n        const canvas = document.createElement(\"canvas\");\n        canvas.width = width;\n        canvas.height = height;\n        const ctx = canvas.getContext(\"2d\");\n        if (!ctx) return undefined;\n        // `pixels` is already unpremultiplied RGBA8888 copied out of the wasm heap,\n        // which is exactly ImageData's layout.\n        ctx.putImageData(new ImageData(new Uint8ClampedArray(pixels), width, height), 0, 0);\n        // A data: URL rather than a blob: URL — both work as an <img> src and a\n        // data URL needs no revoke. `quality` is honored only by lossy formats\n        // (e.g. image/jpeg); the browser ignores it for image/png.\n        return canvas.toDataURL(mime, quality);\n    }\n}\n"]}

package/dist/screenshot.d.ts

@@ -0,0 +1,45 @@
+import { type AssetManifest, type ProjectDocument, type Registry, type SceneDocument, type Size2D, type Theme } from "@motionscript/core";
+import type { FrameSpec, ScreenshotFormat } from "@motionscript/skia-render/export";
+import { type FrameRef } from "./still";
+export type { ScreenshotFormat, FrameSpec };
+export type ScreenshotParams = {
+    /** A project, or a lone still or composition as the one track of one. */
+    document: ProjectDocument | SceneDocument;
+    /** 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;
+    wasmUrl?: string;
+    /** 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 WebGL 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,eAAe,EAAE,KAAK,QAAQ,EAAE,KAAK,aAAa,EAAE,KAAK,MAAM,EAAE,KAAK,KAAK,EACvG,MAAM,oBAAoB,CAAC;AAC5B,OAAO,KAAK,EAAE,SAAS,EAAE,gBAAgB,EAAE,MAAM,kCAAkC,CAAC;AAEpF,OAAO,EAAuB,KAAK,QAAQ,EAAE,MAAM,SAAS,CAAC;AAE7D,YAAY,EAAE,gBAAgB,EAAE,SAAS,EAAE,CAAC;AAE5C,MAAM,MAAM,gBAAgB,GAAG;IAC3B,yEAAyE;IACzE,QAAQ,EAAE,eAAe,GAAG,aAAa,CAAC;IAC1C,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,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,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,32 @@
+import { resolveProjectDocument, } from "@motionscript/core";
+import { DEFAULT_OUTPUT } from "./output";
+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 WebGL 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, wasmUrl, 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, wasmUrl, 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,sBAAsB,GAEzB,MAAM,oBAAoB,CAAC;AAE5B,OAAO,EAAE,cAAc,EAAE,MAAM,UAAU,CAAC;AAC1C,OAAO,EAAE,mBAAmB,EAAiB,MAAM,SAAS,CAAC;AAiC7D;;;;;;;;;;;GAWG;AACH,MAAM,CAAC,KAAK,UAAU,gBAAgB,CAAC,MAAwB;IAC3D,MAAM,EACF,QAAQ,EAAE,KAAK,EAAE,QAAQ,EAAE,KAAK,EAAE,OAAO,EACzC,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,OAAO,EAAE,QAAQ;KAC1F,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    resolveProjectDocument,\n    type AssetManifest, type ProjectDocument, type Registry, type SceneDocument, type Size2D, type Theme,\n} from \"@motionscript/core\";\nimport type { FrameSpec, ScreenshotFormat } from \"@motionscript/skia-render/export\";\nimport { DEFAULT_OUTPUT } from \"./output\";\nimport { createStillRenderer, type FrameRef } from \"./still\";\n\nexport type { ScreenshotFormat, FrameSpec };\n\nexport type ScreenshotParams = {\n    /** A project, or a lone still or composition as the one track of one. */\n    document: ProjectDocument | SceneDocument;\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    wasmUrl?: string;\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 WebGL 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, wasmUrl,\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, wasmUrl, 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,151 @@
+import { Registry, type AssetManifest, type ProjectDocument, type SceneDocument, type Size2D, type Theme } from "@motionscript/core";
+import { type DrawnFrame, type FrameSpec, type ScreenshotFormat } from "@motionscript/skia-render/export";
+import { getCanvasKit } from "./getter";
+/** 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 | SceneDocument;
+/**
+ * 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 {
+    /**
+     * 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;
+    wasmUrl?: string;
+    /**
+     * 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 at this pixel ratio instead of the renderer's. **Resizes the canvas and
+     * rebuilds the Skia surface**, 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;
+}
+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 toFrameSpec(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 CanvasKit module, the WebGL Skia 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.
+ */
+export declare class StillRenderer {
+    readonly canvas: HTMLCanvasElement;
+    private renderContext;
+    private storageAdapter;
+    private catalog;
+    private readonly canvasKit;
+    /** True when we made the canvas and must clean it up. */
+    private readonly ownsCanvas;
+    private viewportValue;
+    private readonly fpsValue;
+    private scaleValue;
+    private manifest;
+    private theme?;
+    private readonly registry;
+    private disposed;
+    /** @internal Use {@link createStillRenderer}, which loads CanvasKit first. */
+    constructor(canvasKit: Awaited<ReturnType<typeof getCanvasKit>>, 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: this
+     * CanvasKit build ships no wasm image encoders, so the browser's own codecs are
+     * the only ones available.
+     */
+    private snapshotToCanvas;
+    private sizeCanvas;
+    /** Resize the backing store and build a fresh Skia surface over it. */
+    private remount;
+    private assertLive;
+}
+/**
+ * Create a {@link StillRenderer}, loading CanvasKit if it isn't already.
+ *
+ * `getCanvasKit` memoizes, so a second renderer in the same page is cheap.
+ */
+export declare function createStillRenderer(options?: StillRendererOptions): Promise<StillRenderer>;
+//# sourceMappingURL=still.d.ts.map