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

package/dist/decode/levels.js

@@ -0,0 +1,68 @@
+/**
+ * The resolutions a source may be decoded at.
+ *
+ * Levels sit half an octave apart, so a decode is never more than √2 larger than
+ * what a draw asked for, and a slow zoom re-decodes a dozen times across the
+ * whole range rather than once per frame.
+ */
+/**
+ * Longest edge any level is decoded at. The conventional maximum GPU texture
+ * edge, so pixels past it could not be sampled in one draw anyway; a 4096²
+ * RGBA level is 67 MB resident.
+ */
+export const MAX_IMAGE_DECODE_EDGE = 4096;
+export const MIN_LEVEL_EDGE = 64;
+/** `64·2^(k/2)` up to {@link MAX_IMAGE_DECODE_EDGE}. */
+export const LEVEL_LADDER = (() => {
+    const out = [];
+    for (let k = 0;; k++) {
+        const edge = Math.round(MIN_LEVEL_EDGE * 2 ** (k / 2));
+        if (edge > MAX_IMAGE_DECODE_EDGE)
+            break;
+        out.push(edge);
+    }
+    return out;
+})();
+/**
+ * The largest level worth holding: the source's own long edge for a raster
+ * (there is no more detail to reveal), the ceiling for a vector.
+ */
+export function levelCap(intrinsic, vector) {
+    if (vector)
+        return MAX_IMAGE_DECODE_EDGE;
+    const long = Math.max(1, Math.round(Math.max(intrinsic.width, intrinsic.height)));
+    return Math.min(long, MAX_IMAGE_DECODE_EDGE);
+}
+/**
+ * The level for a draw that needs `demand` device px along the source's long
+ * edge: the smallest rung at or above it, snapped to `cap` once a rung is
+ * within half an octave of it — a level at 0.8× the source costs almost what
+ * the source does and looks worse.
+ */
+export function levelFor(demand, cap) {
+    const need = Number.isFinite(demand) ? Math.max(0, demand) : cap;
+    if (need >= cap)
+        return cap;
+    const snap = cap / Math.SQRT2;
+    for (const edge of LEVEL_LADDER) {
+        if (edge >= snap)
+            return cap;
+        if (edge >= need)
+            return edge;
+    }
+    return cap;
+}
+/** The smallest level a source can be held at. */
+export function floorLevel(cap) {
+    return levelFor(0, cap);
+}
+/** Pixel dimensions of `edge`, keeping the intrinsic aspect. */
+export function levelSize(edge, intrinsic) {
+    const long = Math.max(intrinsic.width, intrinsic.height, 1);
+    const scale = edge / long;
+    return {
+        width: Math.max(1, Math.round(intrinsic.width * scale)),
+        height: Math.max(1, Math.round(intrinsic.height * scale)),
+    };
+}
+//# sourceMappingURL=levels.js.map

package/dist/decode/levels.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"levels.js","sourceRoot":"","sources":["../../src/decode/levels.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH;;;;GAIG;AACH,MAAM,CAAC,MAAM,qBAAqB,GAAG,IAAI,CAAC;AAE1C,MAAM,CAAC,MAAM,cAAc,GAAG,EAAE,CAAC;AAEjC,wDAAwD;AACxD,MAAM,CAAC,MAAM,YAAY,GAAsB,CAAC,GAAG,EAAE;IACjD,MAAM,GAAG,GAAa,EAAE,CAAC;IACzB,KAAK,IAAI,CAAC,GAAG,CAAC,GAAI,CAAC,EAAE,EAAE,CAAC;QACpB,MAAM,IAAI,GAAG,IAAI,CAAC,KAAK,CAAC,cAAc,GAAG,CAAC,IAAI,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC;QACvD,IAAI,IAAI,GAAG,qBAAqB;YAAE,MAAM;QACxC,GAAG,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IACnB,CAAC;IACD,OAAO,GAAG,CAAC;AACf,CAAC,CAAC,EAAE,CAAC;AAOL;;;GAGG;AACH,MAAM,UAAU,QAAQ,CAAC,SAAoB,EAAE,MAAe;IAC1D,IAAI,MAAM;QAAE,OAAO,qBAAqB,CAAC;IACzC,MAAM,IAAI,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,GAAG,CAAC,SAAS,CAAC,KAAK,EAAE,SAAS,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC;IAClF,OAAO,IAAI,CAAC,GAAG,CAAC,IAAI,EAAE,qBAAqB,CAAC,CAAC;AACjD,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,QAAQ,CAAC,MAAc,EAAE,GAAW;IAChD,MAAM,IAAI,GAAG,MAAM,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,MAAM,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC;IACjE,IAAI,IAAI,IAAI,GAAG;QAAE,OAAO,GAAG,CAAC;IAC5B,MAAM,IAAI,GAAG,GAAG,GAAG,IAAI,CAAC,KAAK,CAAC;IAC9B,KAAK,MAAM,IAAI,IAAI,YAAY,EAAE,CAAC;QAC9B,IAAI,IAAI,IAAI,IAAI;YAAE,OAAO,GAAG,CAAC;QAC7B,IAAI,IAAI,IAAI,IAAI;YAAE,OAAO,IAAI,CAAC;IAClC,CAAC;IACD,OAAO,GAAG,CAAC;AACf,CAAC;AAED,kDAAkD;AAClD,MAAM,UAAU,UAAU,CAAC,GAAW;IAClC,OAAO,QAAQ,CAAC,CAAC,EAAE,GAAG,CAAC,CAAC;AAC5B,CAAC;AAED,gEAAgE;AAChE,MAAM,UAAU,SAAS,CAAC,IAAY,EAAE,SAAoB;IACxD,MAAM,IAAI,GAAG,IAAI,CAAC,GAAG,CAAC,SAAS,CAAC,KAAK,EAAE,SAAS,CAAC,MAAM,EAAE,CAAC,CAAC,CAAC;IAC5D,MAAM,KAAK,GAAG,IAAI,GAAG,IAAI,CAAC;IAC1B,OAAO;QACH,KAAK,EAAE,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,IAAI,CAAC,KAAK,CAAC,SAAS,CAAC,KAAK,GAAG,KAAK,CAAC,CAAC;QACvD,MAAM,EAAE,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,IAAI,CAAC,KAAK,CAAC,SAAS,CAAC,MAAM,GAAG,KAAK,CAAC,CAAC;KAC5D,CAAC;AACN,CAAC","sourcesContent":["/**\n * The resolutions a source may be decoded at.\n *\n * Levels sit half an octave apart, so a decode is never more than √2 larger than\n * what a draw asked for, and a slow zoom re-decodes a dozen times across the\n * whole range rather than once per frame.\n */\n\n/**\n * Longest edge any level is decoded at. The conventional maximum GPU texture\n * edge, so pixels past it could not be sampled in one draw anyway; a 4096²\n * RGBA level is 67 MB resident.\n */\nexport const MAX_IMAGE_DECODE_EDGE = 4096;\n\nexport const MIN_LEVEL_EDGE = 64;\n\n/** `64·2^(k/2)` up to {@link MAX_IMAGE_DECODE_EDGE}. */\nexport const LEVEL_LADDER: readonly number[] = (() => {\n    const out: number[] = [];\n    for (let k = 0; ; k++) {\n        const edge = Math.round(MIN_LEVEL_EDGE * 2 ** (k / 2));\n        if (edge > MAX_IMAGE_DECODE_EDGE) break;\n        out.push(edge);\n    }\n    return out;\n})();\n\nexport interface PixelSize {\n    width: number;\n    height: number;\n}\n\n/**\n * The largest level worth holding: the source's own long edge for a raster\n * (there is no more detail to reveal), the ceiling for a vector.\n */\nexport function levelCap(intrinsic: PixelSize, vector: boolean): number {\n    if (vector) return MAX_IMAGE_DECODE_EDGE;\n    const long = Math.max(1, Math.round(Math.max(intrinsic.width, intrinsic.height)));\n    return Math.min(long, MAX_IMAGE_DECODE_EDGE);\n}\n\n/**\n * The level for a draw that needs `demand` device px along the source's long\n * edge: the smallest rung at or above it, snapped to `cap` once a rung is\n * within half an octave of it — a level at 0.8× the source costs almost what\n * the source does and looks worse.\n */\nexport function levelFor(demand: number, cap: number): number {\n    const need = Number.isFinite(demand) ? Math.max(0, demand) : cap;\n    if (need >= cap) return cap;\n    const snap = cap / Math.SQRT2;\n    for (const edge of LEVEL_LADDER) {\n        if (edge >= snap) return cap;\n        if (edge >= need) return edge;\n    }\n    return cap;\n}\n\n/** The smallest level a source can be held at. */\nexport function floorLevel(cap: number): number {\n    return levelFor(0, cap);\n}\n\n/** Pixel dimensions of `edge`, keeping the intrinsic aspect. */\nexport function levelSize(edge: number, intrinsic: PixelSize): PixelSize {\n    const long = Math.max(intrinsic.width, intrinsic.height, 1);\n    const scale = edge / long;\n    return {\n        width: Math.max(1, Math.round(intrinsic.width * scale)),\n        height: Math.max(1, Math.round(intrinsic.height * scale)),\n    };\n}\n"]}

package/dist/decode/video-levels.d.ts

@@ -0,0 +1,37 @@
+import type { DecodePolicy } from "./image-levels";
+import { type PixelSize } from "./levels";
+/**
+ * Decoded frames one clip's window may hold, in bytes. Frames are counted at
+ * their decoded level, so a clip drawn small keeps a long window and one drawn
+ * full-screen a short one, rather than a fixed count sized for neither.
+ */
+export declare const VIDEO_WINDOW_BUDGET_BYTES: number;
+/** Forward and back window lengths for frames of `size`, split 3:1 like the fixed window was. */
+export declare function videoWindowFrames(size: PixelSize | null): {
+    forward: number;
+    back: number;
+};
+/**
+ * The level one clip's frames are snapshotted at, and how it follows demand.
+ *
+ * A clip has one level at a time, not one per draw: the decoder is sequential,
+ * and a frame is resized as it is snapshotted, so changing the level changes
+ * what the next snapshot produces without restarting the stream.
+ */
+export declare class VideoLevel {
+    level: number;
+    private _cap;
+    private _passNeed;
+    private _passDraws;
+    private _passAllOver;
+    private _overSince;
+    constructor(intrinsic: PixelSize, policy: DecodePolicy, lastDemand: number | undefined, surfaceEdge: number);
+    get cap(): number;
+    /** Record one draw's footprint; absent means the clip's own resolution. */
+    note(footprint: number | undefined): void;
+    /** Whether a frame snapshotted at `frameLevel` is good enough to count as the frame. */
+    accepts(frameLevel: number | undefined, policy: DecodePolicy): boolean;
+    /** The pass's demand is complete: move the level, and report whether it moved. */
+    endPass(policy: DecodePolicy, playing: boolean, now: number): boolean;
+}
+//# sourceMappingURL=video-levels.d.ts.map

package/dist/decode/video-levels.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"video-levels.d.ts","sourceRoot":"","sources":["../../src/decode/video-levels.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAC;AAEnD,OAAO,EAAkC,KAAK,SAAS,EAAE,MAAM,UAAU,CAAC;AAE1E;;;;GAIG;AACH,eAAO,MAAM,yBAAyB,QAAoB,CAAC;AAK3D,iGAAiG;AACjG,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,SAAS,GAAG,IAAI,GAAG;IAAE,OAAO,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,CAS3F;AAED;;;;;;GAMG;AACH,qBAAa,UAAU;IACnB,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,CAAC,IAAI,CAAS;IACrB,OAAO,CAAC,SAAS,CAAK;IACtB,OAAO,CAAC,UAAU,CAAK;IACvB,OAAO,CAAC,YAAY,CAAQ;IAC5B,OAAO,CAAC,UAAU,CAAuB;gBAE7B,SAAS,EAAE,SAAS,EAAE,MAAM,EAAE,YAAY,EAAE,UAAU,EAAE,MAAM,GAAG,SAAS,EAAE,WAAW,EAAE,MAAM;IAO3G,IAAI,GAAG,IAAI,MAAM,CAEhB;IAED,2EAA2E;IAC3E,IAAI,CAAC,SAAS,EAAE,MAAM,GAAG,SAAS,GAAG,IAAI;IASzC,wFAAwF;IACxF,OAAO,CAAC,UAAU,EAAE,MAAM,GAAG,SAAS,EAAE,MAAM,EAAE,YAAY,GAAG,OAAO;IAKtE,kFAAkF;IAClF,OAAO,CAAC,MAAM,EAAE,YAAY,EAAE,OAAO,EAAE,OAAO,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO;CA6BxE"}

package/dist/decode/video-levels.js

@@ -0,0 +1,95 @@
+import { DOWNGRADE_AFTER_MS } from "./image-levels";
+import { floorLevel, levelCap, levelFor } from "./levels";
+/**
+ * Decoded frames one clip's window may hold, in bytes. Frames are counted at
+ * their decoded level, so a clip drawn small keeps a long window and one drawn
+ * full-screen a short one, rather than a fixed count sized for neither.
+ */
+export const VIDEO_WINDOW_BUDGET_BYTES = 512 * 1024 * 1024;
+const MAX_FORWARD_FRAMES = 96;
+const MAX_BACK_FRAMES = 32;
+/** Forward and back window lengths for frames of `size`, split 3:1 like the fixed window was. */
+export function videoWindowFrames(size) {
+    if (!size || !(size.width > 0) || !(size.height > 0)) {
+        return { forward: MAX_FORWARD_FRAMES, back: MAX_BACK_FRAMES };
+    }
+    const frames = VIDEO_WINDOW_BUDGET_BYTES / (size.width * size.height * 4);
+    return {
+        forward: Math.max(4, Math.min(MAX_FORWARD_FRAMES, Math.floor(frames * 0.75))),
+        back: Math.max(1, Math.min(MAX_BACK_FRAMES, Math.floor(frames * 0.25))),
+    };
+}
+/**
+ * The level one clip's frames are snapshotted at, and how it follows demand.
+ *
+ * A clip has one level at a time, not one per draw: the decoder is sequential,
+ * and a frame is resized as it is snapshotted, so changing the level changes
+ * what the next snapshot produces without restarting the stream.
+ */
+export class VideoLevel {
+    level;
+    _cap;
+    _passNeed = 0;
+    _passDraws = 0;
+    _passAllOver = true;
+    _overSince = null;
+    constructor(intrinsic, policy, lastDemand, surfaceEdge) {
+        this._cap = levelCap(intrinsic, false);
+        this.level = policy === "exact"
+            ? floorLevel(this._cap)
+            : levelFor(lastDemand ?? Math.min(Math.max(intrinsic.width, intrinsic.height), surfaceEdge), this._cap);
+    }
+    get cap() {
+        return this._cap;
+    }
+    /** Record one draw's footprint; absent means the clip's own resolution. */
+    note(footprint) {
+        const need = footprint !== undefined && Number.isFinite(footprint) && footprint > 0
+            ? Math.min(footprint, this._cap)
+            : this._cap;
+        this._passNeed = Math.max(this._passNeed, need);
+        this._passDraws++;
+        if (this.level < 2 * need)
+            this._passAllOver = false;
+    }
+    /** Whether a frame snapshotted at `frameLevel` is good enough to count as the frame. */
+    accepts(frameLevel, policy) {
+        if (frameLevel === undefined)
+            return true;
+        return policy === "exact" ? frameLevel === this.level : frameLevel >= this.level;
+    }
+    /** The pass's demand is complete: move the level, and report whether it moved. */
+    endPass(policy, playing, now) {
+        const draws = this._passDraws;
+        const need = this._passNeed;
+        const allOver = this._passAllOver;
+        this._passDraws = 0;
+        this._passNeed = 0;
+        this._passAllOver = true;
+        if (draws === 0)
+            return false;
+        const target = levelFor(need, this._cap);
+        const before = this.level;
+        if (policy === "exact") {
+            this.level = target;
+        }
+        else if (this.level < need) {
+            this.level = target;
+            this._overSince = null;
+        }
+        else if (allOver && !playing) {
+            // Only while paused: a playing clip dropping resolution is visible
+            // as a pop, and its window would re-decode behind the playhead.
+            this._overSince ??= now;
+            if (now - this._overSince >= DOWNGRADE_AFTER_MS) {
+                this.level = target;
+                this._overSince = null;
+            }
+        }
+        else {
+            this._overSince = null;
+        }
+        return this.level !== before;
+    }
+}
+//# sourceMappingURL=video-levels.js.map

package/dist/decode/video-levels.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"video-levels.js","sourceRoot":"","sources":["../../src/decode/video-levels.ts"],"names":[],"mappings":"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","sourcesContent":["import type { DecodePolicy } from \"./image-levels\";\nimport { DOWNGRADE_AFTER_MS } from \"./image-levels\";\nimport { floorLevel, levelCap, levelFor, type PixelSize } from \"./levels\";\n\n/**\n * Decoded frames one clip's window may hold, in bytes. Frames are counted at\n * their decoded level, so a clip drawn small keeps a long window and one drawn\n * full-screen a short one, rather than a fixed count sized for neither.\n */\nexport const VIDEO_WINDOW_BUDGET_BYTES = 512 * 1024 * 1024;\n\nconst MAX_FORWARD_FRAMES = 96;\nconst MAX_BACK_FRAMES = 32;\n\n/** Forward and back window lengths for frames of `size`, split 3:1 like the fixed window was. */\nexport function videoWindowFrames(size: PixelSize | null): { forward: number; back: number } {\n    if (!size || !(size.width > 0) || !(size.height > 0)) {\n        return { forward: MAX_FORWARD_FRAMES, back: MAX_BACK_FRAMES };\n    }\n    const frames = VIDEO_WINDOW_BUDGET_BYTES / (size.width * size.height * 4);\n    return {\n        forward: Math.max(4, Math.min(MAX_FORWARD_FRAMES, Math.floor(frames * 0.75))),\n        back: Math.max(1, Math.min(MAX_BACK_FRAMES, Math.floor(frames * 0.25))),\n    };\n}\n\n/**\n * The level one clip's frames are snapshotted at, and how it follows demand.\n *\n * A clip has one level at a time, not one per draw: the decoder is sequential,\n * and a frame is resized as it is snapshotted, so changing the level changes\n * what the next snapshot produces without restarting the stream.\n */\nexport class VideoLevel {\n    level: number;\n    private _cap: number;\n    private _passNeed = 0;\n    private _passDraws = 0;\n    private _passAllOver = true;\n    private _overSince: number | null = null;\n\n    constructor(intrinsic: PixelSize, policy: DecodePolicy, lastDemand: number | undefined, surfaceEdge: number) {\n        this._cap = levelCap(intrinsic, false);\n        this.level = policy === \"exact\"\n            ? floorLevel(this._cap)\n            : levelFor(lastDemand ?? Math.min(Math.max(intrinsic.width, intrinsic.height), surfaceEdge), this._cap);\n    }\n\n    get cap(): number {\n        return this._cap;\n    }\n\n    /** Record one draw's footprint; absent means the clip's own resolution. */\n    note(footprint: number | undefined): void {\n        const need = footprint !== undefined && Number.isFinite(footprint) && footprint > 0\n            ? Math.min(footprint, this._cap)\n            : this._cap;\n        this._passNeed = Math.max(this._passNeed, need);\n        this._passDraws++;\n        if (this.level < 2 * need) this._passAllOver = false;\n    }\n\n    /** Whether a frame snapshotted at `frameLevel` is good enough to count as the frame. */\n    accepts(frameLevel: number | undefined, policy: DecodePolicy): boolean {\n        if (frameLevel === undefined) return true;\n        return policy === \"exact\" ? frameLevel === this.level : frameLevel >= this.level;\n    }\n\n    /** The pass's demand is complete: move the level, and report whether it moved. */\n    endPass(policy: DecodePolicy, playing: boolean, now: number): boolean {\n        const draws = this._passDraws;\n        const need = this._passNeed;\n        const allOver = this._passAllOver;\n        this._passDraws = 0;\n        this._passNeed = 0;\n        this._passAllOver = true;\n        if (draws === 0) return false;\n\n        const target = levelFor(need, this._cap);\n        const before = this.level;\n        if (policy === \"exact\") {\n            this.level = target;\n        } else if (this.level < need) {\n            this.level = target;\n            this._overSince = null;\n        } else if (allOver && !playing) {\n            // Only while paused: a playing clip dropping resolution is visible\n            // as a pop, and its window would re-decode behind the playhead.\n            this._overSince ??= now;\n            if (now - this._overSince >= DOWNGRADE_AFTER_MS) {\n                this.level = target;\n                this._overSince = null;\n            }\n        } else {\n            this._overSince = null;\n        }\n        return this.level !== before;\n    }\n}\n"]}

package/dist/dynamic-nodes.d.ts

@@ -0,0 +1,9 @@
+import type { DynamicNodeConfig } from "@motionscript/core";
+/**
+ * Resolves a full `DynamicNodeConfig`, filling in whatever the caller left
+ * unset with `browser`'s own default. Synchronous — the WASM import happens
+ * on `compile`'s first actual call, not here, so attaching this to every
+ * engine costs nothing until a source string is genuinely registered.
+ */
+export declare function resolveDynamicNodes(partial: Partial<DynamicNodeConfig> | undefined, compilerWasmUrl?: string): DynamicNodeConfig;
+//# sourceMappingURL=dynamic-nodes.d.ts.map

package/dist/dynamic-nodes.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"dynamic-nodes.d.ts","sourceRoot":"","sources":["../src/dynamic-nodes.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,oBAAoB,CAAC;AA+C5D;;;;;GAKG;AACH,wBAAgB,mBAAmB,CAC/B,OAAO,EAAE,OAAO,CAAC,iBAAiB,CAAC,GAAG,SAAS,EAC/C,eAAe,CAAC,EAAE,MAAM,GACzB,iBAAiB,CAOnB"}

package/dist/dynamic-nodes.js

@@ -0,0 +1,56 @@
+import * as sdk from "@motionscript/core/sdk";
+import * as jsxRuntime from "@motionscript/core/jsx/jsx-runtime";
+import * as esbuild from "esbuild-wasm";
+/**
+ * `browser`'s real, working default for `Registry.addNodeFromSource` — the
+ * `sdk`/`jsxRuntime` halves are cheap (re-exported classes, no WASM) and
+ * imported eagerly; the compiler is the expensive half, and stays behind a
+ * lazy `import()` so an app that never registers a source-string node never
+ * pays for it, however long the engine has been running.
+ *
+ * `core` has no compiler dependency of its own and cannot import the published
+ * `motion-script` sdk barrel (that package depends on `core`, so the reverse
+ * would be circular) — `browser` is where this concern actually belongs: the
+ * package whose entire job is "what running in an actual browser tab looks
+ * like" already owns `getCanvasKit`/`WebAudioSink`/`WebTicker` on exactly that
+ * basis.
+ */
+// Default to the wasm shipped by esbuild-wasm, resolved lazily — `import.meta.url`
+// is empty in a non-ESM output (an IIFE bundle, which is what the headless page
+// loads), and `new URL("…", "")` throws on import, before a caller has had the
+// chance to pass an explicit URL that would have made the default irrelevant.
+// Mirrors `getCanvasKit`'s own `defaultWasmUrl` in `getter.ts`.
+function defaultCompilerWasmUrl() {
+    return new URL("esbuild-wasm/esbuild.wasm", import.meta.url).href;
+}
+let compilerPromise;
+/** Loaded once, memoized process-wide — mirrors how `getCanvasKit` is shared. */
+function defaultCompiler(wasmUrl) {
+    return (compilerPromise ??= (async () => {
+        await esbuild.initialize({ wasmURL: wasmUrl ?? defaultCompilerWasmUrl() });
+        return async (source) => {
+            const { code } = await esbuild.transform(source, {
+                loader: "tsx",
+                format: "cjs",
+                target: "es2020",
+                tsconfigRaw: { compilerOptions: { experimentalDecorators: true } },
+            });
+            return code;
+        };
+    })());
+}
+/**
+ * Resolves a full `DynamicNodeConfig`, filling in whatever the caller left
+ * unset with `browser`'s own default. Synchronous — the WASM import happens
+ * on `compile`'s first actual call, not here, so attaching this to every
+ * engine costs nothing until a source string is genuinely registered.
+ */
+export function resolveDynamicNodes(partial, compilerWasmUrl) {
+    return {
+        sdk: partial?.sdk ?? sdk,
+        jsxRuntime: partial?.jsxRuntime ?? jsxRuntime,
+        modules: partial?.modules,
+        compile: partial?.compile ?? (async (source) => (await defaultCompiler(compilerWasmUrl))(source)),
+    };
+}
+//# sourceMappingURL=dynamic-nodes.js.map

package/dist/dynamic-nodes.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"dynamic-nodes.js","sourceRoot":"","sources":["../src/dynamic-nodes.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,GAAG,MAAM,wBAAwB,CAAC;AAC9C,OAAO,KAAK,UAAU,MAAM,oCAAoC,CAAC;AACjE,OAAO,KAAK,OAAO,MAAM,cAAc,CAAC;AAExC;;;;;;;;;;;;;GAaG;AAEH,mFAAmF;AACnF,gFAAgF;AAChF,+EAA+E;AAC/E,8EAA8E;AAC9E,gEAAgE;AAChE,SAAS,sBAAsB;IAC3B,OAAO,IAAI,GAAG,CAAC,2BAA2B,EAAE,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,IAAI,CAAC;AACtE,CAAC;AAED,IAAI,eAAyE,CAAC;AAE9E,iFAAiF;AACjF,SAAS,eAAe,CAAC,OAAgB;IACrC,OAAO,CAAC,eAAe,KAAK,CAAC,KAAK,IAAI,EAAE;QACpC,MAAM,OAAO,CAAC,UAAU,CAAC,EAAE,OAAO,EAAE,OAAO,IAAI,sBAAsB,EAAE,EAAE,CAAC,CAAC;QAC3E,OAAO,KAAK,EAAE,MAAc,EAAE,EAAE;YAC5B,MAAM,EAAE,IAAI,EAAE,GAAG,MAAM,OAAO,CAAC,SAAS,CAAC,MAAM,EAAE;gBAC7C,MAAM,EAAE,KAAK;gBACb,MAAM,EAAE,KAAK;gBACb,MAAM,EAAE,QAAQ;gBAChB,WAAW,EAAE,EAAE,eAAe,EAAE,EAAE,sBAAsB,EAAE,IAAI,EAAE,EAAE;aACrE,CAAC,CAAC;YACH,OAAO,IAAI,CAAC;QAChB,CAAC,CAAC;IACN,CAAC,CAAC,EAAE,CAAC,CAAC;AACV,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,mBAAmB,CAC/B,OAA+C,EAC/C,eAAwB;IAExB,OAAO;QACH,GAAG,EAAE,OAAO,EAAE,GAAG,IAAI,GAAG;QACxB,UAAU,EAAE,OAAO,EAAE,UAAU,IAAI,UAAU;QAC7C,OAAO,EAAE,OAAO,EAAE,OAAO;QACzB,OAAO,EAAE,OAAO,EAAE,OAAO,IAAI,CAAC,KAAK,EAAE,MAAM,EAAE,EAAE,CAAC,CAAC,MAAM,eAAe,CAAC,eAAe,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC;KACpG,CAAC;AACN,CAAC","sourcesContent":["import type { DynamicNodeConfig } from \"@motionscript/core\";\nimport * as sdk from \"@motionscript/core/sdk\";\nimport * as jsxRuntime from \"@motionscript/core/jsx/jsx-runtime\";\nimport * as esbuild from \"esbuild-wasm\";\n\n/**\n * `browser`'s real, working default for `Registry.addNodeFromSource` — the\n * `sdk`/`jsxRuntime` halves are cheap (re-exported classes, no WASM) and\n * imported eagerly; the compiler is the expensive half, and stays behind a\n * lazy `import()` so an app that never registers a source-string node never\n * pays for it, however long the engine has been running.\n *\n * `core` has no compiler dependency of its own and cannot import the published\n * `motion-script` sdk barrel (that package depends on `core`, so the reverse\n * would be circular) — `browser` is where this concern actually belongs: the\n * package whose entire job is \"what running in an actual browser tab looks\n * like\" already owns `getCanvasKit`/`WebAudioSink`/`WebTicker` on exactly that\n * basis.\n */\n\n// Default to the wasm shipped by esbuild-wasm, resolved lazily — `import.meta.url`\n// is empty in a non-ESM output (an IIFE bundle, which is what the headless page\n// loads), and `new URL(\"…\", \"\")` throws on import, before a caller has had the\n// chance to pass an explicit URL that would have made the default irrelevant.\n// Mirrors `getCanvasKit`'s own `defaultWasmUrl` in `getter.ts`.\nfunction defaultCompilerWasmUrl(): string {\n    return new URL(\"esbuild-wasm/esbuild.wasm\", import.meta.url).href;\n}\n\nlet compilerPromise: Promise<(source: string) => Promise<string>> | undefined;\n\n/** Loaded once, memoized process-wide — mirrors how `getCanvasKit` is shared. */\nfunction defaultCompiler(wasmUrl?: string): Promise<(source: string) => Promise<string>> {\n    return (compilerPromise ??= (async () => {\n        await esbuild.initialize({ wasmURL: wasmUrl ?? defaultCompilerWasmUrl() });\n        return async (source: string) => {\n            const { code } = await esbuild.transform(source, {\n                loader: \"tsx\",\n                format: \"cjs\",\n                target: \"es2020\",\n                tsconfigRaw: { compilerOptions: { experimentalDecorators: true } },\n            });\n            return code;\n        };\n    })());\n}\n\n/**\n * Resolves a full `DynamicNodeConfig`, filling in whatever the caller left\n * unset with `browser`'s own default. Synchronous — the WASM import happens\n * on `compile`'s first actual call, not here, so attaching this to every\n * engine costs nothing until a source string is genuinely registered.\n */\nexport function resolveDynamicNodes(\n    partial: Partial<DynamicNodeConfig> | undefined,\n    compilerWasmUrl?: string,\n): DynamicNodeConfig {\n    return {\n        sdk: partial?.sdk ?? sdk,\n        jsxRuntime: partial?.jsxRuntime ?? jsxRuntime,\n        modules: partial?.modules,\n        compile: partial?.compile ?? (async (source) => (await defaultCompiler(compilerWasmUrl))(source)),\n    };\n}\n"]}

package/dist/engine.d.ts

@@ -0,0 +1,59 @@
+import { Engine, EngineOptions, type DynamicNodeConfig, type NodeConstructor, type NodeTypeMap } from "@motionscript/core";
+import { WebStorageAdapter } from "./storage-adapter";
+import { type AudioEncoderOptions, type VideoEncoderOptions } from "./exporter";
+export interface BrowserEngineOptions extends Omit<EngineOptions, "nodes" | "dynamicNodes"> {
+    /**
+     * Node types any document opened here may name — decorated classes as an
+     * array or a record naming each key outright, same as `EngineOptions`,
+     * plus a TS/JSX source string in the **array** form only. A string
+     * self-declares its key via `@node(...)` in its own source — the record
+     * form stays class-only, so there is exactly one place a dynamic node's
+     * key comes from, not two that could disagree.
+     */
+    nodes?: readonly (NodeConstructor | string)[] | NodeTypeMap;
+    /**
+     * Enables a source string in `nodes`, and `engine.registerNode(source)`
+     * at any point afterward. Any field left unset falls back to `browser`'s
+     * own default — `@motionscript/core/sdk` for `sdk`, a lazily-loaded
+     * `esbuild-wasm` for `compile` — so this never needs to be passed at all
+     * for the common case. `modules` has no default: only the host knows
+     * which loaded packages a script it compiles may reach.
+     */
+    dynamicNodes?: Partial<DynamicNodeConfig>;
+    /**
+     * Where `esbuild-wasm`'s own `.wasm` binary is served — only read if the
+     * default compiler is actually used. Mirrors `wasmUrl` for CanvasKit.
+     */
+    compilerWasmUrl?: string;
+    /** URL of the CanvasKit `.wasm` binary, forwarded to `getCanvasKit`. */
+    wasmUrl?: string;
+    /** Default video encoder settings for `session.export()`. Overridable per call. */
+    video?: VideoEncoderOptions;
+    /** Default audio encoder settings for `session.export()`. Overridable per call. */
+    audio?: AudioEncoderOptions;
+}
+/** What `session.export({ encode })` accepts in this environment. */
+export interface BrowserEncodeOptions {
+    video?: VideoEncoderOptions;
+    audio?: AudioEncoderOptions;
+    supersample?: number;
+    /** Set false to get the bytes back instead of triggering a browser download. */
+    download?: boolean;
+    filename?: string;
+}
+/**
+ * An engine backed by the browser: WebGL/Skia surfaces, Web Audio, WebCodecs.
+ *
+ * Async because CanvasKit is a wasm module and every seam below needs it. Await
+ * once, at app start, and share the result — the caches underneath (registered
+ * fonts, decoded images, shaped paragraphs) are the point of keeping one engine
+ * rather than one per canvas.
+ *
+ * ```ts
+ * const engine = await createBrowserEngine({ nodes: { pulseRing: PulseRing } });
+ * const session = engine.open({ document, target: canvasEl });
+ * session.playback!.play();
+ * ```
+ */
+export declare function createBrowserEngine(options?: BrowserEngineOptions): Promise<Engine<WebStorageAdapter>>;
+//# sourceMappingURL=engine.d.ts.map

package/dist/engine.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"engine.d.ts","sourceRoot":"","sources":["../src/engine.ts"],"names":[],"mappings":"AACA,OAAO,EAEH,MAAM,EACN,aAAa,EAWb,KAAK,iBAAiB,EACtB,KAAK,eAAe,EACpB,KAAK,WAAW,EACnB,MAAM,oBAAoB,CAAC;AAQ5B,OAAO,EAAE,iBAAiB,EAAE,MAAM,mBAAmB,CAAC;AACtD,OAAO,EAAkC,KAAK,mBAAmB,EAAE,KAAK,mBAAmB,EAAE,MAAM,YAAY,CAAC;AAGhH,MAAM,WAAW,oBAAqB,SAAQ,IAAI,CAAC,aAAa,EAAE,OAAO,GAAG,cAAc,CAAC;IACvF;;;;;;;OAOG;IACH,KAAK,CAAC,EAAE,SAAS,CAAC,eAAe,GAAG,MAAM,CAAC,EAAE,GAAG,WAAW,CAAC;IAC5D;;;;;;;OAOG;IACH,YAAY,CAAC,EAAE,OAAO,CAAC,iBAAiB,CAAC,CAAC;IAC1C;;;OAGG;IACH,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,wEAAwE;IACxE,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,mFAAmF;IACnF,KAAK,CAAC,EAAE,mBAAmB,CAAC;IAC5B,mFAAmF;IACnF,KAAK,CAAC,EAAE,mBAAmB,CAAC;CAC/B;AAED,qEAAqE;AACrE,MAAM,WAAW,oBAAoB;IACjC,KAAK,CAAC,EAAE,mBAAmB,CAAC;IAC5B,KAAK,CAAC,EAAE,mBAAmB,CAAC;IAC5B,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,gFAAgF;IAChF,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,QAAQ,CAAC,EAAE,MAAM,CAAC;CACrB;AA6FD;;;;;;;;;;;;;GAaG;AACH,wBAAsB,mBAAmB,CACrC,OAAO,GAAE,oBAAyB,GACnC,OAAO,CAAC,MAAM,CAAC,iBAAiB,CAAC,CAAC,CAgEpC"}

package/dist/engine.js

@@ -0,0 +1,171 @@
+import { Engine, } from "@motionscript/core";
+import { getCanvasKit } from "./getter";
+import { resolveDynamicNodes } from "./dynamic-nodes";
+import { WebAudioSink } from "./audio/player";
+import { WebTicker } from "./ticker";
+import { WebMeasureContext } from "./measure-context";
+import { WebRenderContext } from "./render-context";
+import { WebStorageAdapter } from "./storage-adapter";
+import { exportVideo as exportVideoFile } from "./exporter";
+import { StillRenderer } from "./still";
+/**
+ * The browser's {@link Exporter}: WebCodecs + mediabunny for video, the
+ * browser's own image codecs for a still.
+ *
+ * **It does not reuse a session's storage adapter, and that is deliberate.** An
+ * adapter's viewport clamps the resolution images decode at — `StorageAdapter`
+ * documents that it has no setter for exactly this reason — so handing an export
+ * the preview's adapter would paint a 2× render from decodes sized for 1×, and
+ * the result would be soft in a way nothing reports. What is safely shared is
+ * CanvasKit itself, which `getCanvasKit` already memoizes process-wide.
+ */
+class WebExporter {
+    canvasKit;
+    defaults;
+    wasmUrl;
+    still = null;
+    stillRegistry = null;
+    constructor(canvasKit, defaults, wasmUrl) {
+        this.canvasKit = canvasKit;
+        this.defaults = defaults;
+        this.wasmUrl = wasmUrl;
+    }
+    async exportVideo(request) {
+        const encode = (request.encode ?? {});
+        return exportVideoFile({
+            document: request.project,
+            registry: request.registry,
+            scale: request.scale,
+            manifest: request.manifest,
+            includeAudio: request.includeAudio,
+            video: encode.video ?? this.defaults.video,
+            audio: encode.audio ?? this.defaults.audio,
+            supersample: encode.supersample,
+            filename: encode.filename,
+            // A `Session` asks for bytes; only an explicit `download: true` takes
+            // the DOM anchor path this function offers a page.
+            returnBytes: encode.download !== true,
+            onProgress: request.onProgress,
+            signal: request.signal,
+            wasmUrl: this.wasmUrl,
+        });
+    }
+    async exportStill(request) {
+        const renderer = this.renderer(request);
+        const drawn = await renderer.render(request.project, {
+            scale: request.scale,
+            ...frameOption(request.frame),
+        });
+        const bytes = await renderer.toBytes({
+            format: request.format,
+            quality: request.quality,
+        });
+        return { bytes, frame: drawn.frame, totalFrames: drawn.totalFrames };
+    }
+    dispose() {
+        this.still?.dispose();
+        this.still = null;
+    }
+    /**
+     * One `StillRenderer`, reused across calls and re-viewported when the ask
+     * changes — `setViewport` is a no-op when the size already matches, and a
+     * full reset when it does not, which is the same trade the class documents.
+     */
+    renderer(request) {
+        const { project, registry } = request;
+        if (project.viewport === undefined || project.fps === undefined) {
+            throw new Error("exportStill takes a project whose fps and viewport are resolved — see Session.");
+        }
+        // A renderer compiles against the registry it was built with.
+        if (this.still && this.stillRegistry !== registry)
+            this.dispose();
+        this.still ??= new StillRenderer(this.canvasKit, {
+            viewport: project.viewport,
+            fps: project.fps,
+            manifest: request.manifest,
+            registry,
+        });
+        this.stillRegistry = registry;
+        this.still.setViewport(project.viewport);
+        if (request.manifest)
+            this.still.setManifest(request.manifest);
+        return this.still;
+    }
+}
+/** `ExportStillRequest.frame` in the shape `StillRenderer.render` accepts. */
+function frameOption(frame) {
+    if (frame.kind === "frame")
+        return { frame: frame.frame };
+    return { frame: frame.kind };
+}
+/**
+ * An engine backed by the browser: WebGL/Skia surfaces, Web Audio, WebCodecs.
+ *
+ * Async because CanvasKit is a wasm module and every seam below needs it. Await
+ * once, at app start, and share the result — the caches underneath (registered
+ * fonts, decoded images, shaped paragraphs) are the point of keeping one engine
+ * rather than one per canvas.
+ *
+ * ```ts
+ * const engine = await createBrowserEngine({ nodes: { pulseRing: PulseRing } });
+ * const session = engine.open({ document, target: canvasEl });
+ * session.playback!.play();
+ * ```
+ */
+export async function createBrowserEngine(options = {}) {
+    const rawNodes = options.nodes;
+    // `Array.isArray` doesn't narrow a `readonly T[] | U` union cleanly against
+    // its `arg is any[]` (mutable) predicate — the `.filter` predicate below
+    // already guarantees no string survives, so the cast is just recovering
+    // what the runtime check already proved.
+    const classNodes = (Array.isArray(rawNodes)
+        ? rawNodes.filter((n) => typeof n !== "string")
+        : rawNodes);
+    const sourceNodes = Array.isArray(rawNodes)
+        ? rawNodes.filter((n) => typeof n === "string")
+        : [];
+    // Cheap — see dynamic-nodes.ts: no WASM import happens here, only on
+    // `compile`'s first actual call. Attached unconditionally so a later
+    // `engine.registerNode(source)` works even when `nodes` carried no
+    // string at boot.
+    const dynamicNodes = resolveDynamicNodes(options.dynamicNodes, options.compilerWasmUrl);
+    const canvasKit = await getCanvasKit(options.wasmUrl);
+    const exporter = new WebExporter(canvasKit, { video: options.video, audio: options.audio }, options.wasmUrl);
+    const platform = {
+        createStorageAdapter({ catalog, viewport, fps }) {
+            return new WebStorageAdapter(canvasKit, catalog, viewport, fps);
+        },
+        createRenderContext(storage) {
+            return new WebRenderContext(canvasKit, storage);
+        },
+        createMeasureContext(storage) {
+            return new WebMeasureContext(storage);
+        },
+        createAudioSink() {
+            return new WebAudioSink();
+        },
+        createTicker(fps, audioDevice) {
+            // Shares the device's own `AudioContext`: two independent timebases
+            // in one session drift against each other, and sound is the one that
+            // cannot be nudged back.
+            return new WebTicker({
+                context: audioDevice.getContext(),
+                fps,
+            });
+        },
+        createExporter() {
+            return exporter;
+        },
+        dispose() {
+            exporter.dispose();
+        },
+    };
+    const engine = new Engine(platform, { ...options, nodes: classNodes, dynamicNodes });
+    for (const source of sourceNodes) {
+        // Sequential — one script's error shouldn't mask another's, and
+        // registration order should match array order for determinism.
+        await engine.registerNode(source);
+    }
+    return engine;
+}
+//# sourceMappingURL=engine.js.map

package/dist/engine.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"engine.js","sourceRoot":"","sources":["../src/engine.ts"],"names":[],"mappings":"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","sourcesContent":["import type { CanvasKit } from \"@motionscript/canvaskit\";\nimport {\n    AudioSink,\n    Engine,\n    EngineOptions,\n    EnginePlatform,\n    EngineRenderContext,\n    Exporter,\n    ExportStillRequest,\n    ExportVideoRequest,\n    ExportedStill,\n    Registry,\n    Ticker,\n    MeasureContext2D,\n    PlatformDeps,\n    type DynamicNodeConfig,\n    type NodeConstructor,\n    type NodeTypeMap,\n} from \"@motionscript/core\";\n\nimport { getCanvasKit } from \"./getter\";\nimport { resolveDynamicNodes } from \"./dynamic-nodes\";\nimport { WebAudioSink } from \"./audio/player\";\nimport { WebTicker } from \"./ticker\";\nimport { WebMeasureContext } from \"./measure-context\";\nimport { WebRenderContext } from \"./render-context\";\nimport { WebStorageAdapter } from \"./storage-adapter\";\nimport { exportVideo as exportVideoFile, type AudioEncoderOptions, type VideoEncoderOptions } from \"./exporter\";\nimport { StillRenderer } from \"./still\";\n\nexport interface BrowserEngineOptions extends Omit<EngineOptions, \"nodes\" | \"dynamicNodes\"> {\n    /**\n     * Node types any document opened here may name — decorated classes as an\n     * array or a record naming each key outright, same as `EngineOptions`,\n     * plus a TS/JSX source string in the **array** form only. A string\n     * self-declares its key via `@node(...)` in its own source — the record\n     * form stays class-only, so there is exactly one place a dynamic node's\n     * key comes from, not two that could disagree.\n     */\n    nodes?: readonly (NodeConstructor | string)[] | NodeTypeMap;\n    /**\n     * Enables a source string in `nodes`, and `engine.registerNode(source)`\n     * at any point afterward. Any field left unset falls back to `browser`'s\n     * own default — `@motionscript/core/sdk` for `sdk`, a lazily-loaded\n     * `esbuild-wasm` for `compile` — so this never needs to be passed at all\n     * for the common case. `modules` has no default: only the host knows\n     * which loaded packages a script it compiles may reach.\n     */\n    dynamicNodes?: Partial<DynamicNodeConfig>;\n    /**\n     * Where `esbuild-wasm`'s own `.wasm` binary is served — only read if the\n     * default compiler is actually used. Mirrors `wasmUrl` for CanvasKit.\n     */\n    compilerWasmUrl?: string;\n    /** URL of the CanvasKit `.wasm` binary, forwarded to `getCanvasKit`. */\n    wasmUrl?: string;\n    /** Default video encoder settings for `session.export()`. Overridable per call. */\n    video?: VideoEncoderOptions;\n    /** Default audio encoder settings for `session.export()`. Overridable per call. */\n    audio?: AudioEncoderOptions;\n}\n\n/** What `session.export({ encode })` accepts in this environment. */\nexport interface BrowserEncodeOptions {\n    video?: VideoEncoderOptions;\n    audio?: AudioEncoderOptions;\n    supersample?: number;\n    /** Set false to get the bytes back instead of triggering a browser download. */\n    download?: boolean;\n    filename?: string;\n}\n\n/**\n * The browser's {@link Exporter}: WebCodecs + mediabunny for video, the\n * browser's own image codecs for a still.\n *\n * **It does not reuse a session's storage adapter, and that is deliberate.** An\n * adapter's viewport clamps the resolution images decode at — `StorageAdapter`\n * documents that it has no setter for exactly this reason — so handing an export\n * the preview's adapter would paint a 2× render from decodes sized for 1×, and\n * the result would be soft in a way nothing reports. What is safely shared is\n * CanvasKit itself, which `getCanvasKit` already memoizes process-wide.\n */\nclass WebExporter implements Exporter {\n    private still: StillRenderer | null = null;\n    private stillRegistry: Registry | null = null;\n\n    constructor(\n        private readonly canvasKit: CanvasKit,\n        private readonly defaults: { video?: VideoEncoderOptions; audio?: AudioEncoderOptions },\n        private readonly wasmUrl?: string,\n    ) { }\n\n    async exportVideo(request: ExportVideoRequest): Promise<Uint8Array | void> {\n        const encode = (request.encode ?? {}) as BrowserEncodeOptions;\n        return exportVideoFile({\n            document: request.project,\n            registry: request.registry,\n            scale: request.scale,\n            manifest: request.manifest,\n            includeAudio: request.includeAudio,\n            video: encode.video ?? this.defaults.video,\n            audio: encode.audio ?? this.defaults.audio,\n            supersample: encode.supersample,\n            filename: encode.filename,\n            // A `Session` asks for bytes; only an explicit `download: true` takes\n            // the DOM anchor path this function offers a page.\n            returnBytes: encode.download !== true,\n            onProgress: request.onProgress,\n            signal: request.signal,\n            wasmUrl: this.wasmUrl,\n        });\n    }\n\n    async exportStill(request: ExportStillRequest): Promise<ExportedStill> {\n        const renderer = this.renderer(request);\n        const drawn = await renderer.render(request.project, {\n            scale: request.scale,\n            ...frameOption(request.frame),\n        });\n        const bytes = await renderer.toBytes({\n            format: request.format,\n            quality: request.quality,\n        });\n        return { bytes, frame: drawn.frame, totalFrames: drawn.totalFrames };\n    }\n\n    dispose(): void {\n        this.still?.dispose();\n        this.still = null;\n    }\n\n    /**\n     * One `StillRenderer`, reused across calls and re-viewported when the ask\n     * changes — `setViewport` is a no-op when the size already matches, and a\n     * full reset when it does not, which is the same trade the class documents.\n     */\n    private renderer(request: ExportStillRequest): StillRenderer {\n        const { project, registry } = request;\n        if (project.viewport === undefined || project.fps === undefined) {\n            throw new Error(\"exportStill takes a project whose fps and viewport are resolved — see Session.\");\n        }\n        // A renderer compiles against the registry it was built with.\n        if (this.still && this.stillRegistry !== registry) this.dispose();\n        this.still ??= new StillRenderer(this.canvasKit, {\n            viewport: project.viewport,\n            fps: project.fps,\n            manifest: request.manifest,\n            registry,\n        });\n        this.stillRegistry = registry;\n        this.still.setViewport(project.viewport);\n        if (request.manifest) this.still.setManifest(request.manifest);\n        return this.still;\n    }\n}\n\n/** `ExportStillRequest.frame` in the shape `StillRenderer.render` accepts. */\nfunction frameOption(frame: ExportStillRequest[\"frame\"]): { frame?: number | \"first\" | \"last\" } {\n    if (frame.kind === \"frame\") return { frame: frame.frame };\n    return { frame: frame.kind };\n}\n\n/**\n * An engine backed by the browser: WebGL/Skia surfaces, Web Audio, WebCodecs.\n *\n * Async because CanvasKit is a wasm module and every seam below needs it. Await\n * once, at app start, and share the result — the caches underneath (registered\n * fonts, decoded images, shaped paragraphs) are the point of keeping one engine\n * rather than one per canvas.\n *\n * ```ts\n * const engine = await createBrowserEngine({ nodes: { pulseRing: PulseRing } });\n * const session = engine.open({ document, target: canvasEl });\n * session.playback!.play();\n * ```\n */\nexport async function createBrowserEngine(\n    options: BrowserEngineOptions = {},\n): Promise<Engine<WebStorageAdapter>> {\n    const rawNodes = options.nodes;\n    // `Array.isArray` doesn't narrow a `readonly T[] | U` union cleanly against\n    // its `arg is any[]` (mutable) predicate — the `.filter` predicate below\n    // already guarantees no string survives, so the cast is just recovering\n    // what the runtime check already proved.\n    const classNodes = (\n        Array.isArray(rawNodes)\n            ? rawNodes.filter((n): n is NodeConstructor => typeof n !== \"string\")\n            : rawNodes\n    ) as NodeTypeMap | readonly NodeConstructor[] | undefined;\n    const sourceNodes = Array.isArray(rawNodes)\n        ? rawNodes.filter((n): n is string => typeof n === \"string\")\n        : [];\n    // Cheap — see dynamic-nodes.ts: no WASM import happens here, only on\n    // `compile`'s first actual call. Attached unconditionally so a later\n    // `engine.registerNode(source)` works even when `nodes` carried no\n    // string at boot.\n    const dynamicNodes = resolveDynamicNodes(options.dynamicNodes, options.compilerWasmUrl);\n\n    const canvasKit = await getCanvasKit(options.wasmUrl);\n    const exporter = new WebExporter(\n        canvasKit,\n        { video: options.video, audio: options.audio },\n        options.wasmUrl,\n    );\n\n    const platform: EnginePlatform<WebStorageAdapter> = {\n        createStorageAdapter({ catalog, viewport, fps }: PlatformDeps): WebStorageAdapter {\n            return new WebStorageAdapter(canvasKit, catalog, viewport, fps);\n        },\n        createRenderContext(storage: WebStorageAdapter): EngineRenderContext {\n            return new WebRenderContext(canvasKit, storage);\n        },\n        createMeasureContext(storage: WebStorageAdapter): MeasureContext2D {\n            return new WebMeasureContext(storage);\n        },\n        createAudioSink(): AudioSink {\n            return new WebAudioSink();\n        },\n        createTicker(fps: number, audioDevice: AudioSink): Ticker {\n            // Shares the device's own `AudioContext`: two independent timebases\n            // in one session drift against each other, and sound is the one that\n            // cannot be nudged back.\n            return new WebTicker({\n                context: (audioDevice as WebAudioSink).getContext(),\n                fps,\n            });\n        },\n        createExporter(): Exporter {\n            return exporter;\n        },\n        dispose(): void {\n            exporter.dispose();\n        },\n    };\n\n    const engine = new Engine<WebStorageAdapter>(platform, { ...options, nodes: classNodes, dynamicNodes });\n    for (const source of sourceNodes) {\n        // Sequential — one script's error shouldn't mask another's, and\n        // registration order should match array order for determinism.\n        await engine.registerNode(source);\n    }\n    return engine;\n}\n"]}