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

package/dist/still.d.ts.map

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

package/dist/still.js

@@ -0,0 +1,222 @@
+import { ManifestAssetCatalog, Registry, resolveProjectDocument, setTheme, } from "@motionscript/core";
+import { drawFrameAt, } from "@motionscript/skia-render/export";
+import { WebRenderContext } from "./render-context";
+import { WebStorageAdapter } from "./storage-adapter";
+import { getCanvasKit } from "./getter";
+import { DEFAULT_OUTPUT } from "./output";
+const EMPTY_MANIFEST = { image: {}, video: {}, audio: {}, font: {} };
+/** Normalize the many ways a caller can name a frame into the engine's own form. */
+export function toFrameSpec(options, fps) {
+    if (options?.time !== undefined) {
+        return { kind: "frame", frame: Math.round(options.time * fps) };
+    }
+    const frame = options?.frame;
+    if (frame === undefined || frame === "first")
+        return { kind: "first" };
+    if (frame === "last")
+        return { kind: "last" };
+    if (typeof frame === "number")
+        return { kind: "frame", frame };
+    return frame;
+}
+function mimeOf(format) {
+    return format === "jpeg" ? "image/jpeg" : "image/png";
+}
+/**
+ * A long-lived single-frame renderer.
+ *
+ * Where `exportScreenshot` is one frame from a standing start, this keeps the
+ * expensive things — the 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 class StillRenderer {
+    canvas;
+    renderContext;
+    storageAdapter;
+    catalog;
+    canvasKit;
+    /** True when we made the canvas and must clean it up. */
+    ownsCanvas;
+    viewportValue;
+    fpsValue;
+    scaleValue;
+    manifest;
+    theme;
+    registry;
+    disposed = false;
+    /** @internal Use {@link createStillRenderer}, which loads CanvasKit first. */
+    constructor(canvasKit, options) {
+        this.canvasKit = canvasKit;
+        this.viewportValue = options.viewport ?? DEFAULT_OUTPUT.viewport;
+        this.fpsValue = options.fps ?? DEFAULT_OUTPUT.fps;
+        this.scaleValue = options.scale ?? 1;
+        this.manifest = options.manifest ?? EMPTY_MANIFEST;
+        this.theme = options.theme;
+        this.registry = options.registry ?? new Registry();
+        this.ownsCanvas = options.canvas === undefined;
+        this.canvas = options.canvas ?? document.createElement("canvas");
+        if (this.ownsCanvas) {
+            this.canvas.style.display = "none";
+            document.body.appendChild(this.canvas);
+        }
+        this.sizeCanvas();
+        this.catalog = new ManifestAssetCatalog(this.manifest);
+        this.storageAdapter = new WebStorageAdapter(canvasKit, this.catalog, this.viewportValue, this.fpsValue);
+        this.renderContext = new WebRenderContext(canvasKit, this.storageAdapter);
+        this.renderContext.mount(this.canvas);
+    }
+    get viewport() { return this.viewportValue; }
+    get fps() { return this.fpsValue; }
+    get scale() { return this.scaleValue; }
+    /**
+     * Draw one frame of `source`, at this renderer's viewport — the surface is
+     * the output, so it wins over any size the document asks for.
+     */
+    async render(source, options) {
+        this.assertLive();
+        const scale = options?.scale ?? this.scaleValue;
+        if (scale !== this.scaleValue) {
+            this.scaleValue = scale;
+            this.remount();
+        }
+        const project = resolveProjectDocument(source, { viewport: this.viewportValue }, { viewport: this.viewportValue, fps: this.fpsValue });
+        // Re-applied per render, not once at construction: it is a global
+        // registry, so a second renderer (or the player) may have replaced it
+        // since. Cheap — a map swap.
+        setTheme(project.theme ?? this.theme);
+        return drawFrameAt({
+            project,
+            registry: this.registry,
+            scale,
+            renderContext: this.renderContext,
+            storageAdapter: this.storageAdapter,
+            assetCatalog: this.catalog,
+            frame: toFrameSpec(options, project.fps),
+        });
+    }
+    /** Theme for a document that carries none of its own. */
+    setTheme(theme) { this.theme = theme; }
+    /** Swap the asset manifest, keeping every decode already cached. */
+    setManifest(manifest) {
+        this.assertLive();
+        this.manifest = manifest;
+        this.catalog = new ManifestAssetCatalog(manifest);
+        this.storageAdapter.setCatalog(this.catalog);
+    }
+    /**
+     * Change the output resolution.
+     *
+     * A full reset, unlike {@link setManifest}: the viewport clamps the resolution
+     * images are decoded *at*, so cached decodes made for the old one would be
+     * soft at the new one, and the render context's handlers captured the adapter
+     * when they were built — so both are rebuilt. Call this when the output format
+     * changes, not per edit.
+     */
+    setViewport(viewport) {
+        this.assertLive();
+        if (viewport.width === this.viewportValue.width && viewport.height === this.viewportValue.height) {
+            return;
+        }
+        this.viewportValue = viewport;
+        // Disposing the context disposes the adapter it holds, so this releases
+        // the old surface, its handlers and every decode in one call.
+        this.renderContext.dispose();
+        this.storageAdapter = new WebStorageAdapter(this.canvasKit, this.catalog, viewport, this.fpsValue);
+        this.renderContext = new WebRenderContext(this.canvasKit, this.storageAdapter);
+        this.remount();
+    }
+    /** Encode the frame currently on the surface. */
+    async toBytes(options) {
+        const blob = await this.toBlob(options);
+        return new Uint8Array(await blob.arrayBuffer());
+    }
+    /** Encode the frame currently on the surface. */
+    toBlob(options) {
+        const canvas = this.snapshotToCanvas();
+        const { format = "png", quality = 0.92 } = options ?? {};
+        return new Promise((resolve, reject) => {
+            canvas.toBlob((blob) => blob
+                ? resolve(blob)
+                : reject(new Error("Still encode produced no data.")), mimeOf(format), quality);
+        });
+    }
+    /** Encode the frame currently on the surface. */
+    toDataURL(options) {
+        const { format = "png", quality = 0.92 } = options ?? {};
+        return this.snapshotToCanvas().toDataURL(mimeOf(format), quality);
+    }
+    dispose() {
+        if (this.disposed)
+            return;
+        this.disposed = true;
+        this.renderContext.dispose();
+        if (this.ownsCanvas)
+            this.canvas.remove();
+    }
+    /**
+     * Read the surface back into a 2D canvas, which is what actually encodes: this
+     * CanvasKit build ships no wasm image encoders, so the browser's own codecs are
+     * the only ones available.
+     */
+    snapshotToCanvas() {
+        this.assertLive();
+        const snapshot = this.renderContext.snapshotPixels();
+        if (!snapshot)
+            throw new Error("Nothing has been rendered yet.");
+        const canvas = document.createElement("canvas");
+        canvas.width = snapshot.width;
+        canvas.height = snapshot.height;
+        const ctx = canvas.getContext("2d");
+        if (!ctx)
+            throw new Error("Still encode: could not get a 2d context.");
+        // `pixels` is unpremultiplied RGBA8888, which is exactly ImageData's layout.
+        ctx.putImageData(new ImageData(new Uint8ClampedArray(snapshot.pixels), snapshot.width, snapshot.height), 0, 0);
+        return canvas;
+    }
+    sizeCanvas() {
+        this.canvas.width = this.viewportValue.width * this.scaleValue;
+        this.canvas.height = this.viewportValue.height * this.scaleValue;
+    }
+    /** Resize the backing store and build a fresh Skia surface over it. */
+    remount() {
+        this.sizeCanvas();
+        this.renderContext.mount(this.canvas);
+    }
+    assertLive() {
+        if (this.disposed)
+            throw new Error("This StillRenderer has been disposed.");
+    }
+}
+/**
+ * Create a {@link StillRenderer}, loading CanvasKit if it isn't already.
+ *
+ * `getCanvasKit` memoizes, so a second renderer in the same page is cheap.
+ */
+export async function createStillRenderer(options = {}) {
+    const canvasKit = await getCanvasKit(options.wasmUrl);
+    return new StillRenderer(canvasKit, options);
+}
+//# sourceMappingURL=still.js.map

package/dist/still.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"still.js","sourceRoot":"","sources":["../src/still.ts"],"names":[],"mappings":"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","sourcesContent":["import {\n    AssetCatalog, ManifestAssetCatalog,\n    Registry,\n    resolveProjectDocument,\n    setTheme,\n    type AssetManifest,\n    type ProjectDocument,\n    type SceneDocument,\n    type Size2D,\n    type Theme,\n} from \"@motionscript/core\";\nimport {\n    drawFrameAt,\n    type DrawnFrame,\n    type FrameSpec,\n    type ScreenshotFormat,\n} from \"@motionscript/skia-render/export\";\nimport { WebRenderContext } from \"./render-context\";\nimport { WebStorageAdapter } from \"./storage-adapter\";\nimport { getCanvasKit } from \"./getter\";\nimport { DEFAULT_OUTPUT } from \"./output\";\n\nconst EMPTY_MANIFEST: AssetManifest = { image: {}, video: {}, audio: {}, font: {} };\n\n/** Anything a still can be rendered from: a project, or a lone still or composition as the one track of one. */\nexport type StillSource = ProjectDocument | SceneDocument;\n\n/**\n * Which frame to draw, in whatever form is most convenient — a global frame\n * index, the timeline's first or last frame, or a `FrameSpec`.\n */\nexport type FrameRef = FrameSpec | number | \"first\" | \"last\";\n\nexport interface StillRendererOptions {\n    /**\n     * The canvas to draw into. Omit and the renderer creates its own hidden one\n     * and removes it on {@link StillRenderer.dispose} — which is what a one-shot\n     * capture wants, while a live preview passes the canvas it already shows.\n     */\n    canvas?: HTMLCanvasElement;\n    /** Output resolution in pixels, whatever the document asks for. Defaults to 1920×1080. */\n    viewport?: Size2D;\n    /** Frame rate for a document that sets none. Defaults to 60. */\n    fps?: number;\n    /** Device pixel ratio the surface is sized at. Defaults to 1. */\n    scale?: number;\n    manifest?: AssetManifest;\n    /** Theme for a document that carries none of its own. */\n    theme?: Theme;\n    wasmUrl?: string;\n    /**\n     * The vocabulary a document is compiled against.\n     *\n     * Defaults to a fresh one carrying only what the library ships — a renderer\n     * owns its registry the way an engine does, so a host with custom node types\n     * passes the same one it gave its engine rather than relying on whatever a\n     * module happened to register.\n     */\n    registry?: Registry;\n}\n\nexport interface RenderStillOptions {\n    /** Which frame to draw. Defaults to the timeline's first. */\n    frame?: FrameRef;\n    /** Seconds into the timeline, converted with the document's fps. Wins over `frame`. */\n    time?: number;\n    /**\n     * Draw at this pixel ratio instead of the renderer's. **Resizes the canvas and\n     * rebuilds the Skia surface**, so keep it off the per-edit path — render the\n     * preview at its normal scale and pass this only when capturing at a higher one.\n     */\n    scale?: number;\n}\n\nexport interface EncodeStillOptions {\n    /** Defaults to `\"png\"`. */\n    format?: ScreenshotFormat;\n    /** JPEG quality in [0,1]; ignored for png. Defaults to 0.92. */\n    quality?: number;\n}\n\n/** Normalize the many ways a caller can name a frame into the engine's own form. */\nexport function toFrameSpec(options: RenderStillOptions | undefined, fps: number): FrameSpec {\n    if (options?.time !== undefined) {\n        return { kind: \"frame\", frame: Math.round(options.time * fps) };\n    }\n    const frame = options?.frame;\n    if (frame === undefined || frame === \"first\") return { kind: \"first\" };\n    if (frame === \"last\") return { kind: \"last\" };\n    if (typeof frame === \"number\") return { kind: \"frame\", frame };\n    return frame;\n}\n\nfunction mimeOf(format: ScreenshotFormat): string {\n    return format === \"jpeg\" ? \"image/jpeg\" : \"image/png\";\n}\n\n/**\n * A long-lived single-frame renderer.\n *\n * Where `exportScreenshot` is one frame from a standing start, this keeps the\n * expensive things — the CanvasKit module, the WebGL Skia surface, and the\n * storage adapter's decoded-asset cache — alive across calls, so re-rendering\n * after an edit costs discovering one frame and a draw rather than a new GL\n * context. That is\n * the difference between a one-off capture and a builder that repaints while the\n * user types.\n *\n * It is also the *same* draw: {@link render} goes through `drawFrameAt`, which is\n * the pass the video exporter runs per frame. A preview and its exported image\n * cannot drift apart, because there is only one path.\n *\n * ```ts\n * const renderer = await createStillRenderer({ canvas, viewport, manifest, theme });\n * await renderer.render({ kind: \"still\", nodes: [\n *     { id: \"bg\", type: \"rect\", parentId: null, layerOrder: 0, props: { width: 1920, height: 1080, fill: \"bg\" } },\n * ] });\n * const blob = await renderer.toBlob({ format: \"png\" });\n * renderer.dispose();\n * ```\n *\n * **The theme is process-global in core.** {@link render} re-applies the\n * document's (or this renderer's) before every draw, so two renderers with\n * different themes still each draw correctly; but anything else that calls\n * `setTheme` between a render and a read of the surface will have been\n * overwritten by the next render.\n */\nexport class StillRenderer {\n    readonly canvas: HTMLCanvasElement;\n\n    private renderContext: WebRenderContext;\n    private storageAdapter: WebStorageAdapter;\n    private catalog: AssetCatalog;\n\n    private readonly canvasKit: Awaited<ReturnType<typeof getCanvasKit>>;\n    /** True when we made the canvas and must clean it up. */\n    private readonly ownsCanvas: boolean;\n\n    private viewportValue: Size2D;\n    private readonly fpsValue: number;\n    private scaleValue: number;\n    private manifest: AssetManifest;\n    private theme?: Theme;\n    private readonly registry: Registry;\n    private disposed = false;\n\n    /** @internal Use {@link createStillRenderer}, which loads CanvasKit first. */\n    constructor(\n        canvasKit: Awaited<ReturnType<typeof getCanvasKit>>,\n        options: StillRendererOptions,\n    ) {\n        this.canvasKit = canvasKit;\n        this.viewportValue = options.viewport ?? DEFAULT_OUTPUT.viewport;\n        this.fpsValue = options.fps ?? DEFAULT_OUTPUT.fps;\n        this.scaleValue = options.scale ?? 1;\n        this.manifest = options.manifest ?? EMPTY_MANIFEST;\n        this.theme = options.theme;\n        this.registry = options.registry ?? new Registry();\n\n        this.ownsCanvas = options.canvas === undefined;\n        this.canvas = options.canvas ?? document.createElement(\"canvas\");\n        if (this.ownsCanvas) {\n            this.canvas.style.display = \"none\";\n            document.body.appendChild(this.canvas);\n        }\n        this.sizeCanvas();\n\n        this.catalog = new ManifestAssetCatalog(this.manifest);\n        this.storageAdapter = new WebStorageAdapter(\n            canvasKit, this.catalog, this.viewportValue, this.fpsValue,\n        );\n        this.renderContext = new WebRenderContext(canvasKit, this.storageAdapter);\n        this.renderContext.mount(this.canvas);\n    }\n\n    get viewport(): Size2D { return this.viewportValue; }\n    get fps(): number { return this.fpsValue; }\n    get scale(): number { return this.scaleValue; }\n\n    /**\n     * Draw one frame of `source`, at this renderer's viewport — the surface is\n     * the output, so it wins over any size the document asks for.\n     */\n    async render(source: StillSource, options?: RenderStillOptions): Promise<DrawnFrame> {\n        this.assertLive();\n        const scale = options?.scale ?? this.scaleValue;\n        if (scale !== this.scaleValue) {\n            this.scaleValue = scale;\n            this.remount();\n        }\n\n        const project = resolveProjectDocument(\n            source, { viewport: this.viewportValue }, { viewport: this.viewportValue, fps: this.fpsValue },\n        );\n        // Re-applied per render, not once at construction: it is a global\n        // registry, so a second renderer (or the player) may have replaced it\n        // since. Cheap — a map swap.\n        setTheme(project.theme ?? this.theme);\n\n        return drawFrameAt({\n            project,\n            registry: this.registry,\n            scale,\n            renderContext: this.renderContext,\n            storageAdapter: this.storageAdapter,\n            assetCatalog: this.catalog,\n            frame: toFrameSpec(options, project.fps!),\n        });\n    }\n\n    /** Theme for a document that carries none of its own. */\n    setTheme(theme?: Theme): void { this.theme = theme; }\n\n    /** Swap the asset manifest, keeping every decode already cached. */\n    setManifest(manifest: AssetManifest): void {\n        this.assertLive();\n        this.manifest = manifest;\n        this.catalog = new ManifestAssetCatalog(manifest);\n        this.storageAdapter.setCatalog(this.catalog);\n    }\n\n    /**\n     * Change the output resolution.\n     *\n     * A full reset, unlike {@link setManifest}: the viewport clamps the resolution\n     * images are decoded *at*, so cached decodes made for the old one would be\n     * soft at the new one, and the render context's handlers captured the adapter\n     * when they were built — so both are rebuilt. Call this when the output format\n     * changes, not per edit.\n     */\n    setViewport(viewport: Size2D): void {\n        this.assertLive();\n        if (viewport.width === this.viewportValue.width && viewport.height === this.viewportValue.height) {\n            return;\n        }\n        this.viewportValue = viewport;\n        // Disposing the context disposes the adapter it holds, so this releases\n        // the old surface, its handlers and every decode in one call.\n        this.renderContext.dispose();\n        this.storageAdapter = new WebStorageAdapter(\n            this.canvasKit, this.catalog, viewport, this.fpsValue,\n        );\n        this.renderContext = new WebRenderContext(this.canvasKit, this.storageAdapter);\n        this.remount();\n    }\n\n    /** Encode the frame currently on the surface. */\n    async toBytes(options?: EncodeStillOptions): Promise<Uint8Array> {\n        const blob = await this.toBlob(options);\n        return new Uint8Array(await blob.arrayBuffer());\n    }\n\n    /** Encode the frame currently on the surface. */\n    toBlob(options?: EncodeStillOptions): Promise<Blob> {\n        const canvas = this.snapshotToCanvas();\n        const { format = \"png\", quality = 0.92 } = options ?? {};\n        return new Promise((resolve, reject) => {\n            canvas.toBlob(\n                (blob) => blob\n                    ? resolve(blob)\n                    : reject(new Error(\"Still encode produced no data.\")),\n                mimeOf(format),\n                quality,\n            );\n        });\n    }\n\n    /** Encode the frame currently on the surface. */\n    toDataURL(options?: EncodeStillOptions): string {\n        const { format = \"png\", quality = 0.92 } = options ?? {};\n        return this.snapshotToCanvas().toDataURL(mimeOf(format), quality);\n    }\n\n    dispose(): void {\n        if (this.disposed) return;\n        this.disposed = true;\n        this.renderContext.dispose();\n        if (this.ownsCanvas) this.canvas.remove();\n    }\n\n    /**\n     * Read the surface back into a 2D canvas, which is what actually encodes: this\n     * CanvasKit build ships no wasm image encoders, so the browser's own codecs are\n     * the only ones available.\n     */\n    private snapshotToCanvas(): HTMLCanvasElement {\n        this.assertLive();\n        const snapshot = this.renderContext.snapshotPixels();\n        if (!snapshot) throw new Error(\"Nothing has been rendered yet.\");\n\n        const canvas = document.createElement(\"canvas\");\n        canvas.width = snapshot.width;\n        canvas.height = snapshot.height;\n        const ctx = canvas.getContext(\"2d\");\n        if (!ctx) throw new Error(\"Still encode: could not get a 2d context.\");\n        // `pixels` is unpremultiplied RGBA8888, which is exactly ImageData's layout.\n        ctx.putImageData(\n            new ImageData(new Uint8ClampedArray(snapshot.pixels), snapshot.width, snapshot.height),\n            0, 0,\n        );\n        return canvas;\n    }\n\n    private sizeCanvas(): void {\n        this.canvas.width = this.viewportValue.width * this.scaleValue;\n        this.canvas.height = this.viewportValue.height * this.scaleValue;\n    }\n\n    /** Resize the backing store and build a fresh Skia surface over it. */\n    private remount(): void {\n        this.sizeCanvas();\n        this.renderContext.mount(this.canvas);\n    }\n\n    private assertLive(): void {\n        if (this.disposed) throw new Error(\"This StillRenderer has been disposed.\");\n    }\n}\n\n/**\n * Create a {@link StillRenderer}, loading CanvasKit if it isn't already.\n *\n * `getCanvasKit` memoizes, so a second renderer in the same page is cheap.\n */\nexport async function createStillRenderer(\n    options: StillRendererOptions = {},\n): Promise<StillRenderer> {\n    const canvasKit = await getCanvasKit(options.wasmUrl);\n    return new StillRenderer(canvasKit, options);\n}\n"]}

package/dist/storage-adapter.d.ts

@@ -0,0 +1,367 @@
+import type { CanvasKit, Image as CKImage, Surface, TypefaceFontProvider } from "@motionscript/canvaskit";
+import { AssetCatalog, StorageAdapter, type Size2D } from "@motionscript/core";
+import { ParagraphShapeCache } from "@motionscript/skia-render/shapes/paragraph-cache";
+import type { SkiaAssets, SkiaTextureSource } from "@motionscript/skia-render/assets";
+import { ImageLevelCache, type DecodePolicy } from "./decode/image-levels";
+import { type PixelSize } from "./decode/levels";
+/**
+ * Browser implementation of {@link StorageAdapter} — owns all async asset
+ * decoding (images, video, audio, fonts) so the render loop can stay
+ * synchronous.
+ *
+ * Images and video are held at **levels** chosen from the footprints the
+ * renderer's getters report, not from declared layout boxes: a 4K photo drawn
+ * as a thumbnail holds a thumbnail's pixels, and the same photo zoomed to fill
+ * the screen is re-decoded to match. See `decode/image-levels.ts`.
+ */
+export declare class WebStorageAdapter extends StorageAdapter implements SkiaAssets {
+    private canvasKit;
+    private fontMgr;
+    private disposed;
+    /**
+     * GPU surface the render context draws into; needed to upload decoded video
+     * frames straight to texture (Surface.makeImageFromTextureSource /
+     * updateTextureFromSource). Set by the render context on mount.
+     */
+    private surface;
+    /** Open decode session per video src (opened once by loadVideo, deduped). */
+    private videoSessions;
+    /** Decoded frame bitmaps per src, keyed by quantized source timestamp; bounded to the forward/back window. */
+    private videoFrames;
+    /**
+     * Decoded past frames the Echo filter needs, kept in a SEPARATE cache so the
+     * forward/back window eviction (which is centered on the current playhead)
+     * never drops them — echo taps reach intentionally outside that window.
+     * Bounded by trimming to the most-recently requested {@link ECHO_CACHE_LIMIT}
+     * per src.
+     */
+    private videoEchoFrames;
+    /** Last timestamp each src's playhead was asked to show, used to drive sequential decoding forward. */
+    private videoPlayhead;
+    /**
+     * Exact `(src, timestamp)` pairs a render asked for but couldn't satisfy from
+     * the warm window. A blocking caller drains these via
+     * {@link warmPendingDecodes} and re-renders.
+     */
+    private pendingVideoFrames;
+    /** Like {@link pendingVideoFrames}, for the several past frames an echo or a second playhead needs at once. */
+    private pendingEchoFrames;
+    /** In-flight echo/extra-playhead decodes, keyed `src#quantizedTs`, so callers join one seek. */
+    private echoDecodes;
+    /**
+     * Quantized timestamps claimed per src during the current render pass, in claim
+     * order (see {@link claimVideoFrame}): index 0 holds the session's own texture,
+     * index *n* holds {@link videoAltSlots} slot *n−1*. Cleared by
+     * {@link beginRenderPass}.
+     */
+    private videoFrameClaims;
+    /**
+     * Extra textures per src — one per *simultaneously visible* time of that clip
+     * beyond the first. Persistent and updated in place exactly like a session's
+     * own texture, so a second playhead costs a blit per frame, not an allocation.
+     */
+    private videoAltSlots;
+    /** The last footprint each clip was drawn at, for sizing a session opened later. */
+    private videoDemand;
+    /**
+     * Whether playback is live. When false the adapter does no look-ahead
+     * prefetch, so a paused clip never drains a backlog of stale decodes.
+     */
+    private playing;
+    private decodePolicy;
+    private readonly images;
+    private readonly imageSources;
+    private readonly reportedImageErrors;
+    private audioBuffers;
+    private audioCtx;
+    private fps;
+    /** Families already registered with the font provider (registered once, all weights at once). */
+    private registeredFontFamilies;
+    /**
+     * Families the catalog could not describe, so the warning is emitted once
+     * rather than on every `loadAt`. Cleared by {@link setCatalog}: a new
+     * manifest is exactly the event that can turn one of these into a real face.
+     */
+    private unknownFontFamilies;
+    /** Cache of shaped straight-text runs; owns the cached Fonts. See {@link ParagraphShapeCache}. */
+    private paragraphCache;
+    /** Bumped whenever a new font family registers, invalidating runs shaped against a fallback. */
+    private fontEpoch;
+    /** Past frames the Echo cache holds per src; caps the renderer's MAX_ECHOES (32) with slack. */
+    private static readonly ECHO_CACHE_LIMIT;
+    /**
+     * Max extra textures per src (see {@link videoAltSlots}) — how many different
+     * times of one clip can be on screen together. Past it the last slot is reused.
+     */
+    private static readonly ALT_SLOT_LIMIT;
+    constructor(canvasKit: CanvasKit, catalog: AssetCatalog, viewport: Size2D, fps: number);
+    getCanvasKit(): CanvasKit;
+    /**
+     * Adopt a new manifest, and forget which families it previously could not
+     * describe — installing a typeface folds it into the live manifest without
+     * rebuilding this adapter, and that family deserves a fresh attempt.
+     */
+    setCatalog(catalog: AssetCatalog): void;
+    setDecodePolicy(policy: DecodePolicy): void;
+    getDecodePolicy(): DecodePolicy;
+    hasPendingDecodes(): boolean;
+    /**
+     * Settle what the last render could not draw acceptably: video frames, echo
+     * taps, the 3D runtime, and images — every exact level under `"exact"`, only
+     * a source drawn with nothing resident under `"interactive"`, whose upgrades
+     * are {@link warmPendingUpgrades}. Returns whether there was any, so a
+     * blocking caller re-renders only when something changed.
+     */
+    warmPendingDecodes(): Promise<boolean>;
+    hasPendingUpgrades(): boolean;
+    warmPendingUpgrades(): Promise<boolean>;
+    /** @deprecated Use {@link warmPendingDecodes}. */
+    warmPendingVideo(): Promise<boolean>;
+    /** Resident decode memory, for tests and the e2e memory script. */
+    _decodeStats(): {
+        images: ReturnType<ImageLevelCache["stats"]>;
+        video: {
+            sessions: number;
+            windowFrames: number;
+            echoFrames: number;
+            frameBytes: number;
+        };
+    };
+    /**
+     * Make `src` drawable: decode its first level. Which level that is follows the
+     * policy — see `ImageLevelCache.load`. Every later level follows the
+     * footprints the draws report.
+     */
+    loadImage(src: string): Promise<void>;
+    /** GPU-resident image for `src` at the level this draw needs, or null until it has loaded. */
+    getCKImage(src: string, footprint?: number): CKImage | null;
+    /**
+     * Decoded RGBA8888 pixels for `src` at the level this draw needs, or null
+     * until it has loaded. The same object comes back for as long as that level
+     * is resident, which is what the 3D texture cache keys its uploads on.
+     */
+    getImagePixels(src: string, footprint?: number): {
+        pixels: Uint8Array;
+        width: number;
+        height: number;
+    } | null;
+    getImageSize(src: string): PixelSize | null;
+    private catalogImageSize;
+    /**
+     * Decode one level of `src`.
+     *
+     * A raster decodes from its kept compressed bytes, resized by the browser's
+     * own high-quality scaler; with no manifest size it is decoded once at
+     * natural size to learn it. An SVG is rasterized from its kept `<img>` at
+     * any level, since it has no resolution of its own to cap at.
+     */
+    private decodeImage;
+    private rasterSource;
+    /**
+     * Decodes an SVG through an `HTMLImageElement`, which every browser
+     * supports — `createImageBitmap` can't decode SVG reliably (Chrome throws on
+     * an SVG Blob). From a data URL rather than an object URL so a missing xmlns
+     * or external ref can't taint the image and fail the readback.
+     */
+    private svgSource;
+    /** Long edge of the draw surface in device px, or the viewport before one is attached. */
+    private surfaceEdge;
+    /**
+     * The compressed bytes for `src`, from the host's local store if it has
+     * them and from the network otherwise. Every byte-reading path goes through
+     * this, so a source is local for all of images, video, audio and fonts or
+     * for none of them.
+     */
+    private fetchBlob;
+    /**
+     * The address `src` is fetched from.
+     *
+     * A manifest key and the URL its bytes live at are the same string only
+     * while the host keys its manifest by URL; `meta.src` is the address. An
+     * undescribed source falls back to itself. `media` is audio-then-video
+     * because a video's own soundtrack is requested under the video's key.
+     */
+    private assetUrl;
+    /** Persistent CanvasKit texture per 3D slot, so a 60 fps 3D scene doesn't allocate a texture a frame. */
+    private canvas3DTextures;
+    /**
+     * Upload a 3D renderer's canvas into a GPU-resident CanvasKit image, creating
+     * the texture on first use and updating it in place afterwards.
+     *
+     * **The source arrives unpremultiplied, even though the canvas is not.**
+     * Uploading a canvas *as a texture source* goes through the browser's unpack
+     * pipeline, where `UNPACK_PREMULTIPLY_ALPHA_WEBGL` is false by default, so
+     * what reaches Skia is straight colour. Declaring it `Premul` made Skia
+     * composite additively — invisible at full alpha, and read as `opacity`
+     * being ignored on a translucent surface. `packages/e2e` has a probe in a
+     * colour that separates the two.
+     *
+     * The returned image is owned by this adapter (keyed by slot): it must NOT
+     * be deleted after the draw, or the next frame loses its texture.
+     */
+    upload3DFrame(key: string, source: SkiaTextureSource, width: number, height: number): CKImage | null;
+    /** Release a 3D node's texture — called when its node is swept. */
+    release3DTexture(key: string): void;
+    /**
+     * Receive the GPU surface so decoded video frames can upload straight to
+     * texture. A texture-backed image is only valid for the surface that made it,
+     * so swapping surfaces drops every one; they are recreated on the next frame.
+     * Image levels are raster images and survive.
+     */
+    setSurface(surface: Surface | null): void;
+    /**
+     * Toggle live-playback mode. While playing, the adapter prefetches a window
+     * ahead; when paused it decodes only the exact frame the render needs, so
+     * pausing immediately quiesces.
+     */
+    setPlaying(playing: boolean): void;
+    /** Start a render pass: forget which timestamp each clip's texture was claimed for. */
+    beginRenderPass(): void;
+    /**
+     * End a render pass: every draw has reported its footprint, so decide level
+     * changes now rather than chasing each draw.
+     */
+    endRenderPass(): void;
+    /**
+     * Open a streaming decode session for `src` (deduped — runs once per clip)
+     * and warm the first frame around `trimStart` so the first synchronous render
+     * hits cache. The rest streams in as the playhead advances; the level
+     * follows the footprints claims report.
+     */
+    loadVideo(src: string, _startFrame: number, _endFrame: number, trimStart?: number, _trimEnd?: number): Promise<void>;
+    getVideoSize(src: string): PixelSize | null;
+    private catalogVideoSize;
+    private trackDisplaySize;
+    /**
+     * Synchronously return the GPU image for the frame at `timestamp` (source
+     * seconds), uploaded in place into the session's one texture. On a miss it
+     * records the exact frame for a blocking re-render and, while playing, primes
+     * the sequential decoder; it returns the nearest decoded frame so the picture
+     * never goes blank mid-stream.
+     *
+     * A *drawing* caller should go through {@link claimVideoFrame}, which owns
+     * the rule for one frame needing two different times of the same clip.
+     */
+    getVideoFrame(src: string, timestamp: number): CKImage | null;
+    /**
+     * The image to paint `src` at `timestamp` with, for one draw in the current
+     * render pass. **This, not {@link getVideoFrame}, is what a fill should call.**
+     *
+     * A session's texture is updated in place and Skia doesn't resolve a draw
+     * until the surface flushes, so two draws of the same clip at different times
+     * would both sample whatever was uploaded last. Each distinct timestamp a
+     * pass asks for therefore gets its own texture: the first claim takes the
+     * session's, the rest take {@link videoAltSlots} by claim order. Every
+     * returned image is adapter-owned.
+     */
+    claimVideoFrame(src: string, timestamp: number, footprint?: number): CKImage | null;
+    /** Free every alt-slot texture (surface swap, teardown). */
+    private clearVideoAltSlots;
+    /** Upload the frame for a non-primary timestamp into its slot — see {@link claimVideoFrame}. */
+    private uploadAltFrame;
+    /**
+     * Upload `frame` into `slot`'s texture — in place when the size held, fresh
+     * when a level change resized the frames, since a texture is fixed-size.
+     */
+    private uploadInto;
+    /**
+     * The decoded frame to show a non-primary playhead at `timestamp`: the exact
+     * one when it's warm at the clip's level, otherwise the nearest decoded, with
+     * the exact one queued. Null only when nothing at all is decoded yet.
+     */
+    private decodedFrameFor;
+    /**
+     * The decoded length of `src` in seconds, or `0` when its session hasn't
+     * opened yet. The *container's* duration rather than the manifest's, so
+     * looping still works for a source whose manifest probe couldn't read one.
+     */
+    getVideoDuration(src: string): number;
+    /**
+     * An INDEPENDENT, caller-owned image for a past `timestamp` — the Echo
+     * filter needs several frames resident at once, which the shared session
+     * texture can't give. The caller must push it to `transientImages`.
+     *
+     * On a miss it records the timestamp for {@link warmPendingDecodes} and
+     * returns null, so the tap is skipped this pass and a blocking caller lands it.
+     */
+    getVideoFrameImage(src: string, timestamp: number, footprint?: number): CKImage | null;
+    /**
+     * Upload `frame`'s bitmap into the session's persistent texture and return it.
+     * No upload when that bitmap is already resident, so a parked playhead costs
+     * nothing per render.
+     */
+    private uploadFrame;
+    /** Whether `frame` counts as the frame at the clip's current level. */
+    private accepts;
+    /** Decode every exact video frame and echo tap a prior render asked for, plus the 3D runtime. */
+    private warmVideo;
+    /**
+     * Sequentially decode forward from `timestamp` to fill the window ahead, using
+     * mediabunny's monotonic pipeline — far cheaper than a random seek per frame.
+     * At most one pass runs per src; it stops as soon as playback pauses or the
+     * playhead jumps away. Each sample is sized as it is snapshotted, so a level
+     * change mid-pass applies to the next frame without restarting the stream.
+     */
+    private driveSequentialDecode;
+    /**
+     * Decode the single frame containing `timestampSec` (random access) and cache
+     * its bitmap — for cold warms, where streaming isn't appropriate. Idempotent
+     * per quantized ts at the clip's current level.
+     */
+    private decodeAt;
+    /** Put `frame` in the window, closing what it replaces unless the echo cache shares it. */
+    private storeFrame;
+    /**
+     * Decode a single past frame into the dedicated {@link videoEchoFrames} cache.
+     * Like {@link decodeAt} but it does NOT window-evict — echo taps reach outside
+     * that window on purpose. Concurrent calls for the same frame join one decode.
+     */
+    private decodeEchoFrameAt;
+    /** {@link decodeEchoFrameAt}'s body, past the dedup gate. */
+    private decodeEchoFrameNow;
+    private replaceEcho;
+    /** Bound the echo cache to ECHO_CACHE_LIMIT frames per src, dropping oldest-inserted first. */
+    private trimEchoCache;
+    /**
+     * Resize `sample` to the clip's level and snapshot it to an immutable bitmap,
+     * closing the sample. Drawn and snapshotted in one synchronous step, so the
+     * pooled canvas can be shared by concurrent decodes of the same clip.
+     */
+    private snapshot;
+    private windowFrames;
+    /** Drop decoded frames (closing their bitmaps) outside the window around `timestamp` (source seconds). */
+    private evictVideoWindow;
+    /**
+     * Closest decoded frame to `timestamp`, or null if none are decoded yet — at
+     * any distance, so a not-yet-warm playhead paints the closest frame.
+     */
+    private nearestDecoded;
+    /** Quantize a source timestamp to a stable integer ring key. */
+    private quantizeTs;
+    /**
+     * The frame in `store` closest to `timestamp`, but only within one frame step
+     * (so a request matches the sample whose grid-aligned timestamp quantized to
+     * an adjacent key, without returning a clearly wrong frame).
+     */
+    private nearestWithin;
+    /** The first sample's duration and size; ~30fps when the track won't say. */
+    private probeFirstFrame;
+    private makeCKImageFromPixels;
+    /** Fetches and decodes `src` into a Web Audio `AudioBuffer`, cached for {@link getAudioBuffer}. No-op if already cached. */
+    loadAudio(src: string, _startFrame: number, _endFrame: number, _trimStart?: number, _trimEnd?: number): Promise<void>;
+    fetchAudioData(src: string): Promise<ArrayBuffer>;
+    getAudioBuffer(src: string): AudioBuffer | null;
+    /**
+     * Registers every weight/slant file for `fontFamily` under the bare family
+     * name, once per family, so CanvasKit's matcher can pick the closest file for
+     * any requested weight — which is what makes weights tweenable.
+     */
+    loadFont(key: string, fontFamily: string, _fontWeight: number): Promise<boolean>;
+    getFontMgr(): TypefaceFontProvider;
+    /** The shared shaped-text cache (see {@link paragraphCache}). */
+    getParagraphCache(): ParagraphShapeCache;
+    /** Current font-registration epoch, folded into paragraph cache keys. */
+    getFontEpoch(): number;
+    dispose(): void;
+}
+//# sourceMappingURL=storage-adapter.d.ts.map

package/dist/storage-adapter.d.ts.map

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