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

package/dist/browser/manifest.json

@@ -0,0 +1,15 @@
+{
+  "name": "@motionscript/browser",
+  "version": "0.1.0-alpha.0",
+  "exports": {
+    ".": "dist/browser/index.js",
+    "./audio": "dist/browser/audio.js"
+  },
+  "peers": [
+    "@motionscript/canvaskit",
+    "@motionscript/core"
+  ],
+  "assets": {
+    "esbuild.wasm": "dist/browser/esbuild.wasm"
+  }
+}

package/dist/concat.d.ts

@@ -0,0 +1,95 @@
+/**
+ * Join encoded MP4 segments end to end, without re-encoding.
+ *
+ * The point of this is what it *doesn't* do: no decode, no encode, no pixels.
+ * Each segment is demuxed to its encoded packets, the packets are re-stamped onto
+ * one continuous timeline, and a single muxer writes them into one container. The
+ * bytes of every frame survive untouched, so the result is bit-identical to the
+ * segments and the whole thing runs at I/O speed rather than encode speed.
+ *
+ * It exists so an export can be **split across workers**. Rendering a timeline is
+ * embarrassingly parallel per scene — each scene's generator is independent — but
+ * the output has to be one file, and re-encoding the parts to join them would give
+ * back everything the parallelism won (and lose a generation of quality). Joining
+ * at the packet level is what makes splitting worth doing.
+ *
+ * ## What the caller has to guarantee
+ *
+ * **Every segment must be encoded with an identical configuration** — same codec,
+ * same resolution, same bitrate settings. A container carries exactly one decoder
+ * configuration for a track, so a segment whose parameter sets differ from the
+ * first would be described by a configuration that isn't its own, and decode as
+ * garbage from that point on. That is not a theoretical concern: hardware encoders
+ * are free to pick different parameter sets for the same nominal settings. This is
+ * checked rather than assumed — see {@link ConcatMismatchError} — because the
+ * failure is silent corruption rather than an exception.
+ *
+ * **Every segment must begin with a key frame.** Otherwise its first packets refer
+ * back to frames that lived in the previous segment's GOP and no longer precede
+ * them. Encoders start with a key frame by default; a caller choosing an explicit
+ * `keyFrameInterval` needs it to divide the segment length.
+ *
+ * Audio is *muxed* here but never *joined*: the segments' own audio is ignored
+ * entirely, and a single already-mixed buffer is encoded once across the whole
+ * result (see {@link ConcatOptions.audio}). Concatenating separately-encoded AAC
+ * would put 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 timeline's
+ * audio is mixed in one pass by whoever owns the timeline, and arrives here as
+ * one buffer.
+ */
+/** Thrown when segments can't be joined losslessly. Carries which segment disagreed. */
+export declare class ConcatMismatchError extends Error {
+    /** Index of the offending segment in the input array. */
+    readonly segment: number;
+    constructor(
+    /** Index of the offending segment in the input array. */
+    segment: number, message: string);
+}
+export interface ConcatOptions {
+    /**
+     * One continuous audio track for the whole joined timeline.
+     *
+     * Mixed once by the caller (see `mixTimelineAudio`) rather than per segment,
+     * and that is not a convenience: separately-encoded AAC carries an encoder
+     * priming delay at the head of each piece, so joining them puts a click at
+     * every scene boundary and drifts the track further out of sync with each
+     * one. One buffer in, one encode, no seams.
+     */
+    audio?: AudioBuffer | null;
+    /** AAC bitrate for that track. Defaults to 192 kbps. */
+    audioBitrate?: number;
+    /**
+     * Write the result out as it is muxed instead of returning it.
+     *
+     * With this the joined file never exists in memory as one buffer, which is
+     * the difference between an export the process can hold and one it can't:
+     * a 4× 60fps render is hundreds of megabytes, and the default path costs
+     * roughly twice that at the tail once the `Blob` copy is counted.
+     *
+     * **Chunks carry a byte `position` and do not arrive in file order** — a
+     * muxer seeks back to patch atom sizes. A sink that appends will produce a
+     * file of exactly the right length whose size fields belong to a different
+     * one: unplayable, and indistinguishable from success until it is opened.
+     * Honour `position`.
+     *
+     * `concatVideoSegments` resolves to an empty array when this is used; the
+     * bytes went to the sink.
+     */
+    stream?: WritableStream<{
+        type: "write";
+        data: Uint8Array;
+        position: number;
+    }>;
+}
+/**
+ * Concatenate `segments` (each a complete MP4) into one MP4.
+ *
+ * Segments are joined in array order. Returns the muxed bytes.
+ *
+ * @throws {ConcatMismatchError} if a segment carries no video track, or one whose
+ *         decoder configuration differs from the first segment's. Callers that can
+ *         fall back to a single-threaded export should catch this and do so — the
+ *         alternative is shipping a file that decodes into garbage halfway through.
+ */
+export declare function concatVideoSegments(segments: Uint8Array[], options?: ConcatOptions): Promise<Uint8Array>;
+//# sourceMappingURL=concat.d.ts.map

package/dist/concat.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"concat.d.ts","sourceRoot":"","sources":["../src/concat.ts"],"names":[],"mappings":"AAeA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsCG;AAEH,wFAAwF;AACxF,qBAAa,mBAAoB,SAAQ,KAAK;IAEtC,yDAAyD;IACzD,QAAQ,CAAC,OAAO,EAAE,MAAM;;IADxB,yDAAyD;IAChD,OAAO,EAAE,MAAM,EACxB,OAAO,EAAE,MAAM;CAKtB;AA0CD,MAAM,WAAW,aAAa;IAC1B;;;;;;;;OAQG;IACH,KAAK,CAAC,EAAE,WAAW,GAAG,IAAI,CAAC;IAC3B,wDAAwD;IACxD,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB;;;;;;;;;;;;;;;;OAgBG;IACH,MAAM,CAAC,EAAE,cAAc,CAAC;QAAE,IAAI,EAAE,OAAO,CAAC;QAAC,IAAI,EAAE,UAAU,CAAC;QAAC,QAAQ,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;CAClF;AAID;;;;;;;;;GASG;AACH,wBAAsB,mBAAmB,CACrC,QAAQ,EAAE,UAAU,EAAE,EACtB,OAAO,GAAE,aAAkB,GAC5B,OAAO,CAAC,UAAU,CAAC,CA8ErB"}

package/dist/concat.js

@@ -0,0 +1,174 @@
+import { AudioBufferSource, BufferSource, BufferTarget, EncodedPacketSink, EncodedVideoPacketSource, Input, MP4, Mp4OutputFormat, Output, StreamTarget, } from "mediabunny";
+/**
+ * Join encoded MP4 segments end to end, without re-encoding.
+ *
+ * The point of this is what it *doesn't* do: no decode, no encode, no pixels.
+ * Each segment is demuxed to its encoded packets, the packets are re-stamped onto
+ * one continuous timeline, and a single muxer writes them into one container. The
+ * bytes of every frame survive untouched, so the result is bit-identical to the
+ * segments and the whole thing runs at I/O speed rather than encode speed.
+ *
+ * It exists so an export can be **split across workers**. Rendering a timeline is
+ * embarrassingly parallel per scene — each scene's generator is independent — but
+ * the output has to be one file, and re-encoding the parts to join them would give
+ * back everything the parallelism won (and lose a generation of quality). Joining
+ * at the packet level is what makes splitting worth doing.
+ *
+ * ## What the caller has to guarantee
+ *
+ * **Every segment must be encoded with an identical configuration** — same codec,
+ * same resolution, same bitrate settings. A container carries exactly one decoder
+ * configuration for a track, so a segment whose parameter sets differ from the
+ * first would be described by a configuration that isn't its own, and decode as
+ * garbage from that point on. That is not a theoretical concern: hardware encoders
+ * are free to pick different parameter sets for the same nominal settings. This is
+ * checked rather than assumed — see {@link ConcatMismatchError} — because the
+ * failure is silent corruption rather than an exception.
+ *
+ * **Every segment must begin with a key frame.** Otherwise its first packets refer
+ * back to frames that lived in the previous segment's GOP and no longer precede
+ * them. Encoders start with a key frame by default; a caller choosing an explicit
+ * `keyFrameInterval` needs it to divide the segment length.
+ *
+ * Audio is *muxed* here but never *joined*: the segments' own audio is ignored
+ * entirely, and a single already-mixed buffer is encoded once across the whole
+ * result (see {@link ConcatOptions.audio}). Concatenating separately-encoded AAC
+ * would put 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 timeline's
+ * audio is mixed in one pass by whoever owns the timeline, and arrives here as
+ * one buffer.
+ */
+/** Thrown when segments can't be joined losslessly. Carries which segment disagreed. */
+export class ConcatMismatchError extends Error {
+    segment;
+    constructor(
+    /** Index of the offending segment in the input array. */
+    segment, message) {
+        super(message);
+        this.segment = segment;
+        this.name = "ConcatMismatchError";
+    }
+}
+/**
+ * Two decoder configurations describe the same bitstream.
+ *
+ * `description` holds the codec's parameter sets (the `avcC` box for H.264) and is
+ * the field that actually decides decodability — a differing one is exactly the
+ * silent-corruption case. Compared bytewise; the rest are compared by value.
+ */
+function sameDecoderConfig(a, b) {
+    if (a.codec !== b.codec)
+        return false;
+    if (a.codedWidth !== b.codedWidth)
+        return false;
+    if (a.codedHeight !== b.codedHeight)
+        return false;
+    const da = toBytes(a.description);
+    const db = toBytes(b.description);
+    if (da === null || db === null)
+        return da === db;
+    if (da.length !== db.length)
+        return false;
+    for (let i = 0; i < da.length; i++) {
+        if (da[i] !== db[i])
+            return false;
+    }
+    return true;
+}
+function toBytes(description) {
+    if (!description)
+        return null;
+    // `description` is a BufferSource: an ArrayBuffer, a SharedArrayBuffer, or any
+    // view over one. Views carry an offset into a larger buffer, so they must be
+    // narrowed rather than wrapped whole.
+    if (ArrayBuffer.isView(description)) {
+        return new Uint8Array(description.buffer, description.byteOffset, description.byteLength);
+    }
+    return new Uint8Array(description);
+}
+const DEFAULT_AUDIO_BITRATE = 192_000;
+/**
+ * Concatenate `segments` (each a complete MP4) into one MP4.
+ *
+ * Segments are joined in array order. Returns the muxed bytes.
+ *
+ * @throws {ConcatMismatchError} if a segment carries no video track, or one whose
+ *         decoder configuration differs from the first segment's. Callers that can
+ *         fall back to a single-threaded export should catch this and do so — the
+ *         alternative is shipping a file that decodes into garbage halfway through.
+ */
+export async function concatVideoSegments(segments, options = {}) {
+    if (segments.length === 0)
+        throw new Error("concatVideoSegments: no segments");
+    // A lone segment is already the finished file — unless a track has to be added
+    // to it, or it has to go to a sink, either of which means muxing after all.
+    if (segments.length === 1 && !options.audio && !options.stream)
+        return segments[0];
+    const opened = [];
+    for (let i = 0; i < segments.length; i++) {
+        const input = new Input({ source: new BufferSource(segments[i]), formats: [MP4] });
+        const track = await input.getPrimaryVideoTrack();
+        if (!track)
+            throw new ConcatMismatchError(i, `Segment ${i} has no video track.`);
+        const config = await track.getDecoderConfig();
+        if (!config)
+            throw new ConcatMismatchError(i, `Segment ${i} has no decoder configuration.`);
+        if (opened.length > 0 && !sameDecoderConfig(opened[0].config, config)) {
+            throw new ConcatMismatchError(i, `Segment ${i} was encoded differently from segment 0 (${opened[0].config.codec} `
+                + `${opened[0].config.codedWidth}x${opened[0].config.codedHeight} vs ${config.codec} `
+                + `${config.codedWidth}x${config.codedHeight}); joining them would decode as garbage.`);
+        }
+        opened.push({ track, config, duration: await track.computeDuration() });
+    }
+    const target = options.stream
+        ? new StreamTarget(options.stream)
+        : new BufferTarget();
+    const output = new Output({ format: new Mp4OutputFormat(), target });
+    // `codec` comes off the track rather than the decoder config: the latter's
+    // `codec` is the full codec *string* (`avc1.64001f`), while the source wants
+    // the family.
+    const source = new EncodedVideoPacketSource(opened[0].track.codec);
+    output.addVideoTrack(source);
+    // Declared before `start()` — a muxer fixes its track list up front, so an
+    // audio track added later would have nowhere to go.
+    const audioSource = options.audio
+        ? new AudioBufferSource({
+            codec: "aac",
+            bitrate: options.audioBitrate ?? DEFAULT_AUDIO_BITRATE,
+        })
+        : null;
+    if (audioSource)
+        output.addAudioTrack(audioSource);
+    await output.start();
+    let offset = 0;
+    for (const segment of opened) {
+        // The decoder config is handed over with the first packet of each segment.
+        // Only the first one can take effect — a container holds one per track —
+        // but they have all been checked equal above, so restating it is harmless
+        // and keeps the muxer from having to infer anything.
+        let first = true;
+        for await (const packet of new EncodedPacketSink(segment.track).packets()) {
+            await source.add(packet.clone({ timestamp: packet.timestamp + offset }), first ? { decoderConfig: segment.config } : undefined);
+            first = false;
+        }
+        // Advance by the segment's own duration rather than by the last packet's
+        // end: a packet's `duration` is what the container recorded, and summing
+        // those would accumulate rounding into a drift across many segments.
+        offset += segment.duration;
+    }
+    // After the video packets, so the encode overlaps nothing it has to wait on.
+    if (audioSource && options.audio)
+        await audioSource.add(options.audio);
+    source.close();
+    audioSource?.close();
+    await output.finalize();
+    // A streamed result has already gone to the sink; there is nothing to hand
+    // back, and materialising it here would undo the point of streaming.
+    if (options.stream)
+        return new Uint8Array(0);
+    const buffer = target.buffer;
+    if (!buffer)
+        throw new Error("concatVideoSegments produced no data");
+    return new Uint8Array(buffer);
+}
+//# sourceMappingURL=concat.js.map

package/dist/concat.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"concat.js","sourceRoot":"","sources":["../src/concat.ts"],"names":[],"mappings":"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","sourcesContent":["import {\n    AudioBufferSource,\n    BufferSource,\n    BufferTarget,\n    EncodedPacketSink,\n    EncodedVideoPacketSource,\n    Input,\n    MP4,\n    Mp4OutputFormat,\n    Output,\n    StreamTarget,\n    type InputVideoTrack,\n    type VideoCodec,\n} from \"mediabunny\";\n\n/**\n * Join encoded MP4 segments end to end, without re-encoding.\n *\n * The point of this is what it *doesn't* do: no decode, no encode, no pixels.\n * Each segment is demuxed to its encoded packets, the packets are re-stamped onto\n * one continuous timeline, and a single muxer writes them into one container. The\n * bytes of every frame survive untouched, so the result is bit-identical to the\n * segments and the whole thing runs at I/O speed rather than encode speed.\n *\n * It exists so an export can be **split across workers**. Rendering a timeline is\n * embarrassingly parallel per scene — each scene's generator is independent — but\n * the output has to be one file, and re-encoding the parts to join them would give\n * back everything the parallelism won (and lose a generation of quality). Joining\n * at the packet level is what makes splitting worth doing.\n *\n * ## What the caller has to guarantee\n *\n * **Every segment must be encoded with an identical configuration** — same codec,\n * same resolution, same bitrate settings. A container carries exactly one decoder\n * configuration for a track, so a segment whose parameter sets differ from the\n * first would be described by a configuration that isn't its own, and decode as\n * garbage from that point on. That is not a theoretical concern: hardware encoders\n * are free to pick different parameter sets for the same nominal settings. This is\n * checked rather than assumed — see {@link ConcatMismatchError} — because the\n * failure is silent corruption rather than an exception.\n *\n * **Every segment must begin with a key frame.** Otherwise its first packets refer\n * back to frames that lived in the previous segment's GOP and no longer precede\n * them. Encoders start with a key frame by default; a caller choosing an explicit\n * `keyFrameInterval` needs it to divide the segment length.\n *\n * Audio is *muxed* here but never *joined*: the segments' own audio is ignored\n * entirely, and a single already-mixed buffer is encoded once across the whole\n * result (see {@link ConcatOptions.audio}). Concatenating separately-encoded AAC\n * would put the encoder's priming delay at every join — a click at each boundary\n * and a track that drifts further out of sync with every one — so the timeline's\n * audio is mixed in one pass by whoever owns the timeline, and arrives here as\n * one buffer.\n */\n\n/** Thrown when segments can't be joined losslessly. Carries which segment disagreed. */\nexport class ConcatMismatchError extends Error {\n    constructor(\n        /** Index of the offending segment in the input array. */\n        readonly segment: number,\n        message: string,\n    ) {\n        super(message);\n        this.name = \"ConcatMismatchError\";\n    }\n}\n\n/** One segment's demuxed video track, plus the config that describes it. */\ninterface Segment {\n    track: InputVideoTrack;\n    config: VideoDecoderConfig;\n    duration: number;\n}\n\n/**\n * Two decoder configurations describe the same bitstream.\n *\n * `description` holds the codec's parameter sets (the `avcC` box for H.264) and is\n * the field that actually decides decodability — a differing one is exactly the\n * silent-corruption case. Compared bytewise; the rest are compared by value.\n */\nfunction sameDecoderConfig(a: VideoDecoderConfig, b: VideoDecoderConfig): boolean {\n    if (a.codec !== b.codec) return false;\n    if (a.codedWidth !== b.codedWidth) return false;\n    if (a.codedHeight !== b.codedHeight) return false;\n\n    const da = toBytes(a.description);\n    const db = toBytes(b.description);\n    if (da === null || db === null) return da === db;\n    if (da.length !== db.length) return false;\n    for (let i = 0; i < da.length; i++) {\n        if (da[i] !== db[i]) return false;\n    }\n    return true;\n}\n\nfunction toBytes(description: VideoDecoderConfig[\"description\"]): Uint8Array | null {\n    if (!description) return null;\n    // `description` is a BufferSource: an ArrayBuffer, a SharedArrayBuffer, or any\n    // view over one. Views carry an offset into a larger buffer, so they must be\n    // narrowed rather than wrapped whole.\n    if (ArrayBuffer.isView(description)) {\n        return new Uint8Array(description.buffer, description.byteOffset, description.byteLength);\n    }\n    return new Uint8Array(description);\n}\n\nexport interface ConcatOptions {\n    /**\n     * One continuous audio track for the whole joined timeline.\n     *\n     * Mixed once by the caller (see `mixTimelineAudio`) rather than per segment,\n     * and that is not a convenience: separately-encoded AAC carries an encoder\n     * priming delay at the head of each piece, so joining them puts a click at\n     * every scene boundary and drifts the track further out of sync with each\n     * one. One buffer in, one encode, no seams.\n     */\n    audio?: AudioBuffer | null;\n    /** AAC bitrate for that track. Defaults to 192 kbps. */\n    audioBitrate?: number;\n    /**\n     * Write the result out as it is muxed instead of returning it.\n     *\n     * With this the joined file never exists in memory as one buffer, which is\n     * the difference between an export the process can hold and one it can't:\n     * a 4× 60fps render is hundreds of megabytes, and the default path costs\n     * roughly twice that at the tail once the `Blob` copy is counted.\n     *\n     * **Chunks carry a byte `position` and do not arrive in file order** — a\n     * muxer seeks back to patch atom sizes. A sink that appends will produce a\n     * file of exactly the right length whose size fields belong to a different\n     * one: unplayable, and indistinguishable from success until it is opened.\n     * Honour `position`.\n     *\n     * `concatVideoSegments` resolves to an empty array when this is used; the\n     * bytes went to the sink.\n     */\n    stream?: WritableStream<{ type: \"write\"; data: Uint8Array; position: number }>;\n}\n\nconst DEFAULT_AUDIO_BITRATE = 192_000;\n\n/**\n * Concatenate `segments` (each a complete MP4) into one MP4.\n *\n * Segments are joined in array order. Returns the muxed bytes.\n *\n * @throws {ConcatMismatchError} if a segment carries no video track, or one whose\n *         decoder configuration differs from the first segment's. Callers that can\n *         fall back to a single-threaded export should catch this and do so — the\n *         alternative is shipping a file that decodes into garbage halfway through.\n */\nexport async function concatVideoSegments(\n    segments: Uint8Array[],\n    options: ConcatOptions = {},\n): Promise<Uint8Array> {\n    if (segments.length === 0) throw new Error(\"concatVideoSegments: no segments\");\n    // A lone segment is already the finished file — unless a track has to be added\n    // to it, or it has to go to a sink, either of which means muxing after all.\n    if (segments.length === 1 && !options.audio && !options.stream) return segments[0];\n\n    const opened: Segment[] = [];\n    for (let i = 0; i < segments.length; i++) {\n        const input = new Input({ source: new BufferSource(segments[i]), formats: [MP4] });\n        const track = await input.getPrimaryVideoTrack();\n        if (!track) throw new ConcatMismatchError(i, `Segment ${i} has no video track.`);\n        const config = await track.getDecoderConfig();\n        if (!config) throw new ConcatMismatchError(i, `Segment ${i} has no decoder configuration.`);\n        if (opened.length > 0 && !sameDecoderConfig(opened[0].config, config)) {\n            throw new ConcatMismatchError(\n                i,\n                `Segment ${i} was encoded differently from segment 0 (${opened[0].config.codec} `\n                + `${opened[0].config.codedWidth}x${opened[0].config.codedHeight} vs ${config.codec} `\n                + `${config.codedWidth}x${config.codedHeight}); joining them would decode as garbage.`,\n            );\n        }\n        opened.push({ track, config, duration: await track.computeDuration() });\n    }\n\n    const target = options.stream\n        ? new StreamTarget(options.stream as ConstructorParameters<typeof StreamTarget>[0])\n        : new BufferTarget();\n    const output = new Output({ format: new Mp4OutputFormat(), target });\n    // `codec` comes off the track rather than the decoder config: the latter's\n    // `codec` is the full codec *string* (`avc1.64001f`), while the source wants\n    // the family.\n    const source = new EncodedVideoPacketSource(opened[0].track.codec as VideoCodec);\n    output.addVideoTrack(source);\n    // Declared before `start()` — a muxer fixes its track list up front, so an\n    // audio track added later would have nowhere to go.\n    const audioSource = options.audio\n        ? new AudioBufferSource({\n            codec: \"aac\",\n            bitrate: options.audioBitrate ?? DEFAULT_AUDIO_BITRATE,\n        })\n        : null;\n    if (audioSource) output.addAudioTrack(audioSource);\n    await output.start();\n\n    let offset = 0;\n    for (const segment of opened) {\n        // The decoder config is handed over with the first packet of each segment.\n        // Only the first one can take effect — a container holds one per track —\n        // but they have all been checked equal above, so restating it is harmless\n        // and keeps the muxer from having to infer anything.\n        let first = true;\n        for await (const packet of new EncodedPacketSink(segment.track).packets()) {\n            await source.add(\n                packet.clone({ timestamp: packet.timestamp + offset }),\n                first ? { decoderConfig: segment.config } : undefined,\n            );\n            first = false;\n        }\n        // Advance by the segment's own duration rather than by the last packet's\n        // end: a packet's `duration` is what the container recorded, and summing\n        // those would accumulate rounding into a drift across many segments.\n        offset += segment.duration;\n    }\n\n    // After the video packets, so the encode overlaps nothing it has to wait on.\n    if (audioSource && options.audio) await audioSource.add(options.audio);\n\n    source.close();\n    audioSource?.close();\n    await output.finalize();\n\n    // A streamed result has already gone to the sink; there is nothing to hand\n    // back, and materialising it here would undo the point of streaming.\n    if (options.stream) return new Uint8Array(0);\n\n    const buffer = (target as BufferTarget).buffer;\n    if (!buffer) throw new Error(\"concatVideoSegments produced no data\");\n    return new Uint8Array(buffer);\n}\n"]}

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

@@ -0,0 +1,137 @@
+import { type PixelSize } from "./levels";
+/**
+ * Which level a draw is served, and when levels are decoded and released.
+ *
+ * Browser-free: decoding, uploading and fetching are the host's, so every
+ * decision here runs under a plain test runner with a fake clock.
+ */
+/** Mirrors core's `DecodePolicy`, which its barrel does not export yet. */
+export type DecodePolicy = "exact" | "interactive";
+export declare const IMAGE_DECODE_BUDGET_BYTES: number;
+/** Unselected levels older than this go, whatever the budget — bar a {@link RETAINED_LEVEL_BYTES} largest level. */
+export declare const LEVEL_AGE_OUT_MS = 2000;
+/** A preview drawing a level at twice what it needs for this long decodes the smaller one. */
+export declare const DOWNGRADE_AFTER_MS = 5000;
+export declare const IDLE_TO_FLOOR_MS = 30000;
+export declare const IDLE_DROP_SOURCE_MS = 60000;
+export declare const MAX_CONCURRENT_DECODES = 3;
+/** An interactive decode covers this multiple of the demand, so a growing draw re-decodes per octave, not per rung. */
+export declare const UPGRADE_HEADROOM = 2;
+/**
+ * A largest level no bigger than this is neither aged out nor downgraded until
+ * the budget needs the room: decoding it again the next time a draw grows costs
+ * more, in main-thread copies and a blurry frame, than holding it.
+ */
+export declare const RETAINED_LEVEL_BYTES: number;
+export interface ImageLevel<G = unknown> {
+    /** The ladder rung this level was decoded for. */
+    readonly edge: number;
+    readonly width: number;
+    readonly height: number;
+    readonly pixels: Uint8Array;
+    /** The host's GPU copy, counted against the budget alongside the pixels. */
+    gpu: G | null;
+    lastSelected: number;
+    /** The pass that last selected it — "unselected" is judged by pass, since several can share a clock tick. */
+    selectedPass: number;
+}
+export interface DecodedImage {
+    pixels: Uint8Array;
+    width: number;
+    height: number;
+    intrinsic: PixelSize;
+    vector: boolean;
+}
+export interface ImageLevelHost<G> {
+    now(): number;
+    /**
+     * Decode `src` at the rung `chooseEdge` picks once the source's intrinsic
+     * size is known — the host may have to fetch or even decode the source to
+     * learn it, which is why the choice is a callback rather than an argument.
+     */
+    decode(src: string, chooseEdge: (intrinsic: PixelSize, vector: boolean) => number): Promise<DecodedImage & {
+        edge: number;
+    }>;
+    /** A level left the cache. Free what was built from it. */
+    released(src: string, level: ImageLevel<G>): void;
+    /** Kept compressed bytes for `src`, so an upgrade needs no refetch; 0 when none. */
+    sourceBytes(src: string): number;
+    dropSource(src: string): void;
+    /** Long edge of the surface in device px, for sizing a first interactive load. */
+    surfaceEdge(): number;
+    onError?(src: string, error: unknown): void;
+}
+export declare class ImageLevelCache<G = unknown> {
+    private readonly _host;
+    private readonly _budget;
+    private _policy;
+    private readonly _entries;
+    private _pass;
+    private _inflight;
+    constructor(_host: ImageLevelHost<G>, _budget?: number);
+    get policy(): DecodePolicy;
+    setPolicy(policy: DecodePolicy): void;
+    has(src: string): boolean;
+    intrinsicSize(src: string): PixelSize | null;
+    /** Make sure `src` has a level to draw with. First loads pick their rung by policy. */
+    load(src: string): Promise<void>;
+    beginPass(): void;
+    /**
+     * The level one draw paints with. `footprint` is the long edge in device px
+     * the draw needs; absent means the source's own resolution.
+     */
+    select(src: string, footprint?: number): ImageLevel<G> | null;
+    /** Decide this pass's level changes, now that every draw has reported. */
+    endPass(): void;
+    /**
+     * What a settling caller must wait for before the frame is right: under
+     * `exact`, every decode queued or running; under `interactive`, only a source
+     * the last pass asked for with nothing resident. An upgrade is {@link hasUpgrades}.
+     */
+    hasPending(): boolean;
+    /** Await what {@link hasPending} reports, and report whether there was any. */
+    warm(): Promise<boolean>;
+    /** Whether, under `interactive`, a source the last pass drew below demand has a better level on its way. */
+    hasUpgrades(): boolean;
+    /** Await the upgrades {@link hasUpgrades} reports; whether one landed. */
+    warmUpgrades(): Promise<boolean>;
+    stats(): {
+        sources: number;
+        levels: number;
+        levelBytes: number;
+        sourceBytes: number;
+        inflight: number;
+    };
+    /** Every level held for `src`, ascending — for tests and stats. */
+    levelsOf(src: string): readonly ImageLevel<G>[];
+    dispose(): void;
+    private _entry;
+    private _blocks;
+    private _upgrading;
+    /** The rung an interactive decode for `demand` asks for: with headroom, capped at the source. */
+    private _interactiveEdge;
+    private _learn;
+    private _add;
+    /**
+     * Queue a decode of `edge`. An interactive request replaces what is queued,
+     * since only the latest demand matters; exact requests accumulate, since a
+     * frame may need several rungs of one source.
+     */
+    private _request;
+    private _pump;
+    /**
+     * The next queued rung worth decoding. Under `interactive` never one below the
+     * latest demand, and no upgrade once what landed meanwhile already covers it.
+     */
+    private _nextEdge;
+    private _ageOut;
+    private _total;
+    /**
+     * Cheapest loss first: levels nothing drew this pass, then levels a preview
+     * holds bigger than it needs, then sources nobody has looked at in a while,
+     * then their compressed bytes. A source's last level is never evicted — a
+     * draw finding nothing would throw rather than degrade.
+     */
+    private _enforceBudget;
+}
+//# sourceMappingURL=image-levels.d.ts.map

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

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