@tongue-core/engine 0.0.0-stage → 0.1.0-rc.10

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Backpine
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,63 @@
-# Temporary Holding Version
+# @tongue-core/engine
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Frame → pixels. Given a planned film (`planFilm` from `@tongue-core/film`) and its loaded assets, it
+composes the tracks at a frame, evaluates each clip's scene at its local time, lays it out, paints
+a display list and rasterizes it with the embedded WebAssembly raster. Plain TypeScript with no
+dependencies besides `@tongue-core/film`, and deterministic: the same frame is byte-identical in Bun,
+browsers and Cloudflare Workers.
+
+```ts
+import { planFilm } from "@tongue-core/film";
+import { FilmRenderer, loadAssets } from "@tongue-core/engine";
+
+const plan = planFilm(film, { media });
+const assets = await loadAssets(plan.assets, (path) => fetchBytes(`/assets/${path}`), { audio: false });
+const renderer = await FilmRenderer.create(plan, assets);       // the wasm raster, or pass a RasterBackend
+renderer.render(120, { scale: 0.5 });
+const rgba = renderer.rgba8();                                  // or yuv420(), png()
+```
+
+**In a Cloudflare Worker**, which may not compile WebAssembly from bytes, import the raster as a
+module (`@tongue-core/engine/raster.wasm`, the same bytes as the embedded copy) and pass it in:
+
+```ts
+import { FilmRenderer, Raster } from "@tongue-core/engine";
+import raster from "@tongue-core/engine/raster.wasm";              // a WebAssembly.Module in a Worker
+
+const renderer = await FilmRenderer.create(plan, assets, await Raster.create(raster));
+```
+
+With little memory (a Worker), hold only what each frame draws: `displayList` throws `ImageNotLoaded`
+naming the image a frame needs, and `renderer.keepOnly(list)` frees the rest from the raster before
+`renderer.draw(list)`. `apps/frames-worker/src/runner.ts` does this.
+
+TypeScript needs `declare module "*.wasm" { const module: WebAssembly.Module; export default module; }`
+somewhere in the Worker's sources.
+
+- **Frames are independent.** Nothing carries over between frames except caches, so frames
+  render in any order, on any number of machines.
+- **Video frames come from the host** (`FrameOptions.video`, a `VideoFrameSource`): ffmpeg on a
+  server, WebCodecs in a browser. Without one, a clip shows its poster. `videoFramesAt(frame)` lists
+  what a frame needs so a host can decode ahead.
+- **Other rasters plug in** through `RasterBackend` (`src/raster/backend.ts`): the SDK's native
+  and GPU rasters draw the same display lists. The format is in `docs/display-list.md`.
+- **Sound** is mixed here too: `audioClips(plan, assets)` and `collectSounds(plan)` (typing and
+  clicks scenes make) into `mix(…)`, with time-stretch that keeps pitch.
+- **Assets** are what the SDK imports: TrueType fonts, QOI images, WAV audio, video facts and
+  posters (`loadAssets` with a fetcher). The codecs (PNG, JPEG, QOI, WAV, WOFF2) are ours.
+
+## Layout
+
+```
+src/
+  render/      FilmRenderer: tracks → one frame (compose.ts), and the sounds a film makes
+  evaluate/    a scene at a frame → a tree of boxes (camera, pointer, typing, morph partners)
+  layout/      block, flex, grid and stack layout for the style subset
+  text/        fonts (TTF, WOFF2, variable), shaping, paragraphs
+  style/       style parsing and resolution
+  paint/       tree → display list (and morphs between two trees)
+  raster/      the embedded wasm raster and the RasterBackend contract
+  audio/       the mixer
+  assets/      loading imported assets, and the codecs
+  media/       video frame lookup
+```

package/dist/assets/codecs/jpeg.d.ts

@@ -0,0 +1,2 @@
+import type { RgbaImage } from "./types.js";
+export declare function decodeJpeg(bytes: Uint8Array): RgbaImage;

package/dist/assets/codecs/jpeg.js

@@ -0,0 +1,591 @@
+// JPEG decoder, from scratch: baseline and extended sequential (SOF0/SOF1) and progressive
+// (SOF2) Huffman JPEGs with any sampling factors and restart intervals. Coefficients for the
+// whole image are kept until the last scan, because progressive scans refine them in passes.
+import { CodecError } from "./png.js";
+const fail = (message) => {
+    throw new CodecError("jpeg", message);
+};
+// Zigzag position k → natural (row-major) index in the 8×8 block. Padded with 63s so a corrupt
+// run that overshoots lands on the last coefficient instead of outside the block.
+const ZIGZAG = new Uint8Array([
+    0, 1, 8, 16, 9, 2, 3, 10, 17, 24, 32, 25, 18, 11, 4, 5, 12, 19, 26, 33, 40, 48, 41, 34, 27, 20, 13, 6, 7, 14, 21, 28,
+    35, 42, 49, 56, 57, 50, 43, 36, 29, 22, 15, 23, 30, 37, 44, 51, 58, 59, 52, 45, 38, 31, 39, 46, 53, 60, 61, 54, 47, 55, 62, 63,
+    63, 63, 63, 63, 63, 63, 63, 63, 63, 63, 63, 63, 63, 63, 63, 63,
+]);
+function huffman(counts, values) {
+    const maxcode = new Int32Array(18).fill(-1);
+    const mincode = new Int32Array(17);
+    const valptr = new Int32Array(17);
+    let code = 0;
+    let k = 0;
+    for (let length = 1; length <= 16; length++) {
+        const count = counts[length - 1] ?? 0;
+        valptr[length] = k;
+        mincode[length] = code;
+        code += count;
+        k += count;
+        if (count > 0)
+            maxcode[length] = code - 1;
+        if (code > 1 << length)
+            fail("Huffman table has too many codes");
+        code <<= 1;
+    }
+    maxcode[17] = 0x7fffffff;
+    return { maxcode, mincode, valptr, values };
+}
+class Component {
+    id;
+    h;
+    v;
+    table;
+    pred = 0;
+    dc;
+    ac;
+    coefficients = new Int16Array(0);
+    blocksPerLine = 0; // visible blocks, used by non-interleaved scans
+    blocksPerColumn = 0;
+    blocksPerLineForMcu = 0; // padded to whole MCUs, the storage stride
+    blocksPerColumnForMcu = 0;
+    constructor(id, h, v, table) {
+        this.id = id;
+        this.h = h;
+        this.v = v;
+        this.table = table;
+    }
+}
+export function decodeJpeg(bytes) {
+    if (bytes[0] !== 0xff || bytes[1] !== 0xd8)
+        fail("not a JPEG file (no SOI marker)");
+    const quantization = [];
+    const dcTables = [];
+    const acTables = [];
+    let frame;
+    let restartInterval = 0;
+    let adobeTransform = -1;
+    const u16 = (at) => ((bytes[at] ?? 0) << 8) | (bytes[at + 1] ?? 0);
+    let at = 2;
+    for (;;) {
+        // Markers may be preceded by any number of 0xFF fill bytes; skip stray data between segments.
+        while (at < bytes.length && bytes[at] !== 0xff)
+            at++;
+        while (at < bytes.length && bytes[at] === 0xff)
+            at++;
+        if (at >= bytes.length)
+            break;
+        const marker = bytes[at++] ?? 0;
+        if (marker === 0xd9)
+            break; // EOI
+        if (marker === 0xd8 || (marker >= 0xd0 && marker <= 0xd7) || marker === 0x01)
+            continue; // no length
+        if (at + 2 > bytes.length)
+            fail("truncated segment");
+        const length = u16(at);
+        const start = at + 2;
+        const end = at + length;
+        if (length < 2 || end > bytes.length)
+            fail(`segment ${marker.toString(16)} runs past the end of the file`);
+        switch (marker) {
+            case 0xdb: { // DQT
+                for (let p = start; p < end;) {
+                    const pq = (bytes[p] ?? 0) >> 4;
+                    const tq = (bytes[p] ?? 0) & 15;
+                    p++;
+                    if (tq > 3)
+                        fail("quantization table id out of range");
+                    const table = new Uint16Array(64);
+                    for (let k = 0; k < 64; k++) {
+                        table[ZIGZAG[k] ?? 0] = pq === 0 ? bytes[p + k] ?? 0 : u16(p + k * 2);
+                    }
+                    p += pq === 0 ? 64 : 128;
+                    quantization[tq] = table;
+                }
+                break;
+            }
+            case 0xc4: { // DHT
+                for (let p = start; p < end;) {
+                    const tc = (bytes[p] ?? 0) >> 4;
+                    const th = (bytes[p] ?? 0) & 15;
+                    if (th > 3 || tc > 1)
+                        fail("Huffman table id out of range");
+                    const counts = bytes.slice(p + 1, p + 17);
+                    const total = counts.reduce((sum, n) => sum + n, 0);
+                    const values = bytes.slice(p + 17, p + 17 + total);
+                    if (values.length !== total)
+                        fail("truncated Huffman table");
+                    (tc === 0 ? dcTables : acTables)[th] = huffman(counts, values);
+                    p += 17 + total;
+                }
+                break;
+            }
+            case 0xdd: // DRI
+                restartInterval = u16(start);
+                break;
+            case 0xee: // APP14 "Adobe": says whether three components are YCbCr or plain RGB
+                if (length >= 14 && String.fromCharCode(...bytes.subarray(start, start + 5)) === "Adobe")
+                    adobeTransform = bytes[start + 11] ?? 0;
+                break;
+            case 0xc0:
+            case 0xc1:
+            case 0xc2: {
+                if (frame !== undefined)
+                    fail("more than one frame");
+                if (bytes[start] !== 8)
+                    fail(`${bytes[start] ?? 0}-bit samples are not supported`);
+                const height = u16(start + 1);
+                const width = u16(start + 3);
+                const count = bytes[start + 5] ?? 0;
+                if (width === 0 || height === 0)
+                    fail("zero-sized image (DNL is not supported)");
+                if (count !== 1 && count !== 3)
+                    fail(`${count}-component JPEGs are not supported`);
+                const components = [];
+                for (let i = 0; i < count; i++) {
+                    const p = start + 6 + i * 3;
+                    const h = (bytes[p + 1] ?? 0) >> 4;
+                    const v = (bytes[p + 1] ?? 0) & 15;
+                    if (h < 1 || h > 4 || v < 1 || v > 4)
+                        fail("bad sampling factors");
+                    components.push(new Component(bytes[p] ?? 0, h, v, bytes[p + 2] ?? 0));
+                }
+                frame = layout(marker === 0xc2, width, height, components);
+                break;
+            }
+            case 0xc3:
+            case 0xc5:
+            case 0xc6:
+            case 0xc7:
+            case 0xc9:
+            case 0xca:
+            case 0xcb:
+            case 0xcd:
+            case 0xce:
+            case 0xcf:
+                return fail("lossless, hierarchical and arithmetic-coded JPEGs are not supported");
+            case 0xda: { // SOS
+                if (frame === undefined)
+                    return fail("scan before frame header");
+                const count = bytes[start] ?? 0;
+                const scan = [];
+                for (let i = 0; i < count; i++) {
+                    const id = bytes[start + 1 + i * 2] ?? 0;
+                    const tables = bytes[start + 2 + i * 2] ?? 0;
+                    const component = frame.components.find((c) => c.id === id) ?? fail(`scan refers to unknown component ${id}`);
+                    component.dc = dcTables[tables >> 4];
+                    component.ac = acTables[tables & 15];
+                    scan.push(component);
+                }
+                const p = start + 1 + count * 2;
+                const ss = bytes[p] ?? 0;
+                const se = bytes[p + 1] ?? 0;
+                const ah = (bytes[p + 2] ?? 0) >> 4;
+                const al = (bytes[p + 2] ?? 0) & 15;
+                at = decodeScan(bytes, end, frame, scan, restartInterval, ss, se, ah, al);
+                continue;
+            }
+            default:
+                break; // APPn, COM and the rest carry nothing we need
+        }
+        at = end;
+    }
+    if (frame === undefined)
+        return fail("no frame header");
+    return toRgba(frame, quantization, adobeTransform);
+}
+function layout(progressive, width, height, components) {
+    const hmax = Math.max(...components.map((c) => c.h));
+    const vmax = Math.max(...components.map((c) => c.v));
+    const mcusPerLine = Math.ceil(width / (8 * hmax));
+    const mcusPerColumn = Math.ceil(height / (8 * vmax));
+    for (const c of components) {
+        c.blocksPerLine = Math.ceil(Math.ceil((width * c.h) / hmax) / 8);
+        c.blocksPerColumn = Math.ceil(Math.ceil((height * c.v) / vmax) / 8);
+        c.blocksPerLineForMcu = mcusPerLine * c.h;
+        c.blocksPerColumnForMcu = mcusPerColumn * c.v;
+        c.coefficients = new Int16Array(c.blocksPerLineForMcu * c.blocksPerColumnForMcu * 64);
+    }
+    return { progressive, width, height, components, hmax, vmax, mcusPerLine, mcusPerColumn };
+}
+// Decodes one scan's entropy-coded data starting at `start`; returns the offset of the marker
+// that ends it.
+function decodeScan(data, start, frame, components, restartInterval, ss, se, ah, al) {
+    let offset = start;
+    let bits = 0;
+    let bitCount = 0;
+    let atMarker = false;
+    // One bit, MSB first, undoing 0xFF00 byte stuffing. On reaching a marker the stream reads as
+    // zeros from then on, the way libjpeg pads a truncated interval.
+    const readBit = () => {
+        if (bitCount === 0) {
+            if (atMarker)
+                return 0;
+            const byte = data[offset] ?? 0;
+            if (byte === 0xff) {
+                const next = data[offset + 1] ?? 0;
+                if (next !== 0) {
+                    atMarker = true;
+                    return 0;
+                }
+                offset += 2;
+            }
+            else {
+                offset++;
+            }
+            if (offset > data.length) {
+                atMarker = true;
+                return 0;
+            }
+            bits = byte;
+            bitCount = 8;
+        }
+        bitCount--;
+        return (bits >> bitCount) & 1;
+    };
+    const receive = (length) => {
+        let n = 0;
+        for (let i = 0; i < length; i++)
+            n = (n << 1) | readBit();
+        return n;
+    };
+    // A magnitude category's bits as a signed value (Annex F.2.2.1, EXTEND).
+    const extend = (length) => {
+        if (length === 0)
+            return 0;
+        const n = receive(length);
+        return n >= 1 << (length - 1) ? n : n - (1 << length) + 1;
+    };
+    const decode = (table) => {
+        if (table === undefined)
+            return fail("scan uses an undefined Huffman table");
+        let code = readBit();
+        let length = 1;
+        while (code > (table.maxcode[length] ?? 0x7fffffff)) {
+            code = (code << 1) | readBit();
+            length++;
+        }
+        if (length > 16)
+            return 0; // corrupt code: treat as zero and let the restart marker resync
+        return table.values[(table.valptr[length] ?? 0) + code - (table.mincode[length] ?? 0)] ?? 0;
+    };
+    let eobrun = 0;
+    let refineState = 0; // successive-approximation AC state machine, Annex G.1.2.3
+    let refineValue = 0;
+    const baseline = (c, o) => {
+        const t = decode(c.dc);
+        c.pred += extend(t);
+        c.coefficients[o] = c.pred;
+        for (let k = 1; k < 64;) {
+            const rs = decode(c.ac);
+            const s = rs & 15;
+            const r = rs >> 4;
+            if (s === 0) {
+                if (r < 15)
+                    break;
+                k += 16;
+                continue;
+            }
+            k += r;
+            if (k > 63)
+                break;
+            c.coefficients[o + (ZIGZAG[k] ?? 63)] = extend(s);
+            k++;
+        }
+    };
+    const dcFirst = (c, o) => {
+        const t = decode(c.dc);
+        c.pred += extend(t) * (1 << al);
+        c.coefficients[o] = c.pred;
+    };
+    const dcRefine = (c, o) => {
+        if (readBit())
+            c.coefficients[o] = (c.coefficients[o] ?? 0) | (1 << al);
+    };
+    const acFirst = (c, o) => {
+        if (eobrun > 0) {
+            eobrun--;
+            return;
+        }
+        for (let k = ss; k <= se;) {
+            const rs = decode(c.ac);
+            const s = rs & 15;
+            const r = rs >> 4;
+            if (s === 0) {
+                if (r < 15) {
+                    eobrun = receive(r) + (1 << r) - 1;
+                    break;
+                }
+                k += 16;
+                continue;
+            }
+            k += r;
+            if (k > 63)
+                break;
+            c.coefficients[o + (ZIGZAG[k] ?? 63)] = extend(s) * (1 << al);
+            k++;
+        }
+    };
+    // Refinement scans add one bit to every coefficient already nonzero and place new ±1 values
+    // into zero positions after skipping `r` zeros. The state carries across blocks for EOB runs.
+    const acRefine = (c, o) => {
+        const coefficients = c.coefficients;
+        let r = 0;
+        for (let k = ss; k <= se;) {
+            const z = o + (ZIGZAG[k] ?? 63);
+            const current = coefficients[z] ?? 0;
+            const sign = current < 0 ? -1 : 1;
+            switch (refineState) {
+                case 0: {
+                    const rs = decode(c.ac);
+                    const s = rs & 15;
+                    r = rs >> 4;
+                    if (s === 0) {
+                        if (r < 15) {
+                            eobrun = receive(r) + (1 << r);
+                            refineState = 4;
+                        }
+                        else {
+                            r = 16;
+                            refineState = 1;
+                        }
+                    }
+                    else {
+                        if (s !== 1)
+                            fail("bad refinement value size");
+                        refineValue = extend(s);
+                        refineState = r > 0 ? 2 : 3;
+                    }
+                    continue; // reconsider the same k in the new state
+                }
+                case 1:
+                case 2:
+                    if (current !== 0) {
+                        coefficients[z] = current + sign * (readBit() << al);
+                    }
+                    else {
+                        r--;
+                        if (r === 0)
+                            refineState = refineState === 2 ? 3 : 0;
+                    }
+                    break;
+                case 3:
+                    if (current !== 0) {
+                        coefficients[z] = current + sign * (readBit() << al);
+                    }
+                    else {
+                        coefficients[z] = refineValue * (1 << al);
+                        refineState = 0;
+                    }
+                    break;
+                default: // 4: inside an EOB run, only correction bits
+                    if (current !== 0)
+                        coefficients[z] = current + sign * (readBit() << al);
+                    break;
+            }
+            k++;
+        }
+        if (refineState === 4) {
+            eobrun--;
+            if (eobrun === 0)
+                refineState = 0;
+        }
+    };
+    let decodeBlock;
+    if (!frame.progressive)
+        decodeBlock = baseline;
+    else if (ss === 0) {
+        if (se !== 0)
+            fail("progressive DC scan with AC coefficients");
+        decodeBlock = ah === 0 ? dcFirst : dcRefine;
+    }
+    else {
+        if (components.length !== 1)
+            fail("progressive AC scan with more than one component");
+        if (se > 63 || ss > se)
+            fail("bad spectral selection");
+        decodeBlock = ah === 0 ? acFirst : acRefine;
+    }
+    const single = components.length === 1 ? components[0] : undefined;
+    const total = single !== undefined ? single.blocksPerLine * single.blocksPerColumn : frame.mcusPerLine * frame.mcusPerColumn;
+    const decodeMcu = (mcu) => {
+        if (single !== undefined) {
+            // Non-interleaved: one block per MCU, covering only the component's visible blocks.
+            const row = Math.floor(mcu / single.blocksPerLine);
+            const col = mcu % single.blocksPerLine;
+            decodeBlock(single, (row * single.blocksPerLineForMcu + col) * 64);
+            return;
+        }
+        const mcuRow = Math.floor(mcu / frame.mcusPerLine);
+        const mcuCol = mcu % frame.mcusPerLine;
+        for (const c of components) {
+            for (let v = 0; v < c.v; v++) {
+                for (let h = 0; h < c.h; h++) {
+                    const row = mcuRow * c.v + v;
+                    const col = mcuCol * c.h + h;
+                    decodeBlock(c, (row * c.blocksPerLineForMcu + col) * 64);
+                }
+            }
+        }
+    };
+    for (let mcu = 0; mcu < total;) {
+        for (const c of components)
+            c.pred = 0;
+        eobrun = 0;
+        refineState = 0;
+        bitCount = 0;
+        const end = restartInterval > 0 ? Math.min(total, mcu + restartInterval) : total;
+        for (; mcu < end; mcu++)
+            decodeMcu(mcu);
+        // Find the next marker: a restart marker continues the scan, anything else ends it.
+        atMarker = false;
+        bitCount = 0;
+        while (offset < data.length && !(data[offset] === 0xff && (data[offset + 1] ?? 0) !== 0 && data[offset + 1] !== 0xff))
+            offset++;
+        const marker = data[offset + 1] ?? 0;
+        if (marker >= 0xd0 && marker <= 0xd7) {
+            offset += 2;
+            continue;
+        }
+        break;
+    }
+    return offset;
+}
+// Dequantize, inverse DCT, upsample chroma and convert to RGB.
+function toRgba(frame, quantization, adobeTransform) {
+    const planes = frame.components.map((c) => {
+        const table = quantization[c.table] ?? fail(`missing quantization table ${c.table}`);
+        const width = c.blocksPerLineForMcu * 8;
+        const plane = new Uint8Array(width * c.blocksPerColumnForMcu * 8);
+        const block = new Float32Array(64);
+        const out = new Uint8Array(64);
+        for (let row = 0; row < c.blocksPerColumnForMcu; row++) {
+            for (let col = 0; col < c.blocksPerLineForMcu; col++) {
+                const offset = (row * c.blocksPerLineForMcu + col) * 64;
+                for (let i = 0; i < 64; i++)
+                    block[i] = (c.coefficients[offset + i] ?? 0) * (table[i] ?? 0);
+                idct(block, out);
+                for (let y = 0; y < 8; y++)
+                    plane.set(out.subarray(y * 8, y * 8 + 8), (row * 8 + y) * width + col * 8);
+            }
+        }
+        return {
+            plane, width,
+            visibleWidth: Math.ceil((frame.width * c.h) / frame.hmax),
+            visibleHeight: Math.ceil((frame.height * c.v) / frame.vmax),
+            sx: c.h / frame.hmax, sy: c.v / frame.vmax,
+        };
+    });
+    const { width, height } = frame;
+    const data = new Uint8Array(width * height * 4);
+    // Each component resampled to full size: bilinear with centered samples, so 2:1 chroma
+    // gets libjpeg's "fancy upsampling" weights (3/4, 1/4).
+    const full = planes.map((p) => {
+        if (p.sx === 1 && p.sy === 1)
+            return { plane: p.plane, stride: p.width };
+        const plane = new Uint8Array(width * height);
+        const xs = new Int32Array(width), xw = new Float32Array(width);
+        for (let x = 0; x < width; x++) {
+            const fx = Math.min(Math.max((x + 0.5) * p.sx - 0.5, 0), p.visibleWidth - 1);
+            xs[x] = Math.floor(fx);
+            xw[x] = fx - Math.floor(fx);
+        }
+        for (let y = 0; y < height; y++) {
+            const fy = Math.min(Math.max((y + 0.5) * p.sy - 0.5, 0), p.visibleHeight - 1);
+            const y0 = Math.floor(fy);
+            const wy = fy - y0;
+            const r0 = y0 * p.width;
+            const r1 = Math.min(y0 + 1, p.visibleHeight - 1) * p.width;
+            for (let x = 0; x < width; x++) {
+                const x0 = xs[x] ?? 0;
+                const x1 = Math.min(x0 + 1, p.visibleWidth - 1);
+                const wx = xw[x] ?? 0;
+                const top = (p.plane[r0 + x0] ?? 0) + ((p.plane[r0 + x1] ?? 0) - (p.plane[r0 + x0] ?? 0)) * wx;
+                const bottom = (p.plane[r1 + x0] ?? 0) + ((p.plane[r1 + x1] ?? 0) - (p.plane[r1 + x0] ?? 0)) * wx;
+                plane[y * width + x] = Math.round(top + (bottom - top) * wy);
+            }
+        }
+        return { plane, stride: width };
+    });
+    const [a, b, c] = full;
+    if (a === undefined)
+        return fail("no components");
+    if (b === undefined || c === undefined) {
+        for (let y = 0; y < height; y++) {
+            for (let x = 0; x < width; x++) {
+                const g = a.plane[y * a.stride + x] ?? 0;
+                const o = (y * width + x) * 4;
+                data[o] = g;
+                data[o + 1] = g;
+                data[o + 2] = g;
+                data[o + 3] = 255;
+            }
+        }
+        return { width, height, data };
+    }
+    // Three components are YCbCr unless an Adobe marker says "no transform" or the component ids
+    // spell R, G, B.
+    const ids = frame.components.map((comp) => comp.id).join(",");
+    const rgb = adobeTransform === 0 || ids === "82,71,66";
+    const clamp = (v) => (v < 0 ? 0 : v > 255 ? 255 : Math.round(v));
+    for (let y = 0; y < height; y++) {
+        for (let x = 0; x < width; x++) {
+            const Y = a.plane[y * a.stride + x] ?? 0;
+            const Cb = b.plane[y * b.stride + x] ?? 0;
+            const Cr = c.plane[y * c.stride + x] ?? 0;
+            const o = (y * width + x) * 4;
+            if (rgb) {
+                data[o] = Y;
+                data[o + 1] = Cb;
+                data[o + 2] = Cr;
+            }
+            else {
+                data[o] = clamp(Y + 1.402 * (Cr - 128));
+                data[o + 1] = clamp(Y - 0.344136 * (Cb - 128) - 0.714136 * (Cr - 128));
+                data[o + 2] = clamp(Y + 1.772 * (Cb - 128));
+            }
+            data[o + 3] = 255;
+        }
+    }
+    return { width, height, data };
+}
+// Separable float IDCT: out(x) = Σ_u C(u)/2 · F(u) · cos((2x+1)uπ/16), rows then columns,
+// skipping rows that are all zero past DC (the common case after quantization).
+const COS = (() => {
+    const table = new Float32Array(64);
+    for (let x = 0; x < 8; x++) {
+        for (let u = 0; u < 8; u++)
+            table[x * 8 + u] = ((u === 0 ? Math.SQRT1_2 : 1) / 2) * Math.cos(((2 * x + 1) * u * Math.PI) / 16);
+    }
+    return table;
+})();
+const scratch = new Float32Array(64);
+function idct(block, out) {
+    for (let y = 0; y < 8; y++) {
+        const r = y * 8;
+        let ac = false;
+        for (let u = 1; u < 8; u++)
+            if ((block[r + u] ?? 0) !== 0) {
+                ac = true;
+                break;
+            }
+        if (!ac) {
+            const dc = (block[r] ?? 0) * (COS[0] ?? 0);
+            for (let x = 0; x < 8; x++)
+                scratch[r + x] = dc;
+            continue;
+        }
+        for (let x = 0; x < 8; x++) {
+            let sum = 0;
+            for (let u = 0; u < 8; u++)
+                sum += (block[r + u] ?? 0) * (COS[x * 8 + u] ?? 0);
+            scratch[r + x] = sum;
+        }
+    }
+    for (let x = 0; x < 8; x++) {
+        for (let y = 0; y < 8; y++) {
+            let sum = 0;
+            for (let v = 0; v < 8; v++)
+                sum += (scratch[v * 8 + x] ?? 0) * (COS[y * 8 + v] ?? 0);
+            const value = Math.round(sum + 128);
+            out[y * 8 + x] = value < 0 ? 0 : value > 255 ? 255 : value;
+        }
+    }
+}

package/dist/assets/codecs/png.d.ts

@@ -0,0 +1,9 @@
+import type { RgbaImage } from "./types.js";
+export type Codec = "png" | "jpeg" | "qoi" | "wav" | "resize";
+/** Malformed or unsupported input to one of the import-time codecs. */
+export declare class CodecError extends Error {
+    readonly codec: Codec;
+    readonly name = "CodecError";
+    constructor(codec: Codec, message: string);
+}
+export declare function decodePng(bytes: Uint8Array, inflate: (zlib: Uint8Array) => Uint8Array): RgbaImage;