dexterm-cli 0.0.0-stage → 0.1.1

package/dist/packages/data/src/images/png.js

@@ -0,0 +1,310 @@
+// @dexterm/data — PNG decoder + encoder (task-1326, coin images). Pure TypeScript on node:zlib, no native
+// code and no third-party decoder: an untrusted coin logo is parsed by bounds-checked JS and can never run
+// anything. Decodes every PNG colour type (grey, RGB, palette, grey+alpha, RGBA) at bit depths 1/2/4/8/16,
+// with tRNS transparency and Adam7 interlace, into straight-alpha RGBA8. Dimension and pixel caps are
+// enforced BEFORE any pixel buffer is allocated. Ancillary chunks (APNG, iCCP, gAMA, …) are ignored.
+import { inflateSync, deflateSync } from 'node:zlib';
+import { DEFAULT_LIMITS, ImageDecodeError, checkDims } from "./types.js";
+const SIG = [0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a];
+export function isPng(b) {
+    if (b.length < 8)
+        return false;
+    for (let i = 0; i < 8; i++)
+        if (b[i] !== SIG[i])
+            return false;
+    return true;
+}
+function channelsOf(colorType) {
+    switch (colorType) {
+        case 0: return 1; // grey
+        case 2: return 3; // rgb
+        case 3: return 1; // palette index
+        case 4: return 2; // grey + alpha
+        case 6: return 4; // rgba
+        default: throw new ImageDecodeError(`png: unknown colour type ${colorType}`);
+    }
+}
+function paeth(a, b, c) {
+    const p = a + b - c;
+    const pa = Math.abs(p - a), pb = Math.abs(p - b), pc = Math.abs(p - c);
+    return pa <= pb && pa <= pc ? a : pb <= pc ? b : c;
+}
+/** Undo the per-scanline filter in place over `rows` scanlines of `stride` bytes (plus a filter byte each). */
+function unfilter(data, off, rows, stride, bpp) {
+    const out = new Uint8Array(rows * stride);
+    let prevRow = null;
+    for (let y = 0; y < rows; y++) {
+        const ft = data[off];
+        off += 1;
+        const row = out.subarray(y * stride, (y + 1) * stride);
+        row.set(data.subarray(off, off + stride));
+        off += stride;
+        switch (ft) {
+            case 0: break;
+            case 1:
+                for (let i = bpp; i < stride; i++)
+                    row[i] = (row[i] + row[i - bpp]) & 0xff;
+                break;
+            case 2:
+                if (prevRow)
+                    for (let i = 0; i < stride; i++)
+                        row[i] = (row[i] + prevRow[i]) & 0xff;
+                break;
+            case 3:
+                for (let i = 0; i < stride; i++) {
+                    const left = i >= bpp ? row[i - bpp] : 0;
+                    const up = prevRow ? prevRow[i] : 0;
+                    row[i] = (row[i] + ((left + up) >> 1)) & 0xff;
+                }
+                break;
+            case 4:
+                for (let i = 0; i < stride; i++) {
+                    const left = i >= bpp ? row[i - bpp] : 0;
+                    const up = prevRow ? prevRow[i] : 0;
+                    const ul = prevRow && i >= bpp ? prevRow[i - bpp] : 0;
+                    row[i] = (row[i] + paeth(left, up, ul)) & 0xff;
+                }
+                break;
+            default: throw new ImageDecodeError(`png: bad filter type ${ft}`);
+        }
+        prevRow = row;
+    }
+    return out;
+}
+/** Read sample `i` (0-based, across the row) of `depth` bits from a packed scanline, scaled to 0..255. */
+function sampleAt(row, i, depth) {
+    if (depth === 8)
+        return row[i];
+    if (depth === 16)
+        return row[i * 2]; // high byte: 16-bit → 8-bit
+    const perByte = 8 / depth;
+    const byte = row[Math.floor(i / perByte)];
+    const shift = 8 - depth * ((i % perByte) + 1);
+    const v = (byte >> shift) & ((1 << depth) - 1);
+    return depth === 1 ? v * 255 : depth === 2 ? v * 85 : v * 17;
+}
+/** Raw sample value (unscaled) for palette indices. */
+function indexAt(row, i, depth) {
+    if (depth === 8)
+        return row[i];
+    const perByte = 8 / depth;
+    const byte = row[Math.floor(i / perByte)];
+    const shift = 8 - depth * ((i % perByte) + 1);
+    return (byte >> shift) & ((1 << depth) - 1);
+}
+// Adam7: x start, y start, x step, y step
+const ADAM7 = [[0, 0, 8, 8], [4, 0, 8, 8], [0, 4, 4, 8], [2, 0, 4, 4], [0, 2, 2, 4], [1, 0, 2, 2], [0, 1, 1, 2]];
+export function decodePng(bytes, limits = DEFAULT_LIMITS) {
+    if (!isPng(bytes))
+        throw new ImageDecodeError('png: bad signature');
+    const dv = new DataView(bytes.buffer, bytes.byteOffset, bytes.byteLength);
+    let pos = 8;
+    let hdr = null;
+    let palette = null;
+    let trns = null;
+    const idat = [];
+    let idatLen = 0;
+    while (pos + 8 <= bytes.length) {
+        const len = dv.getUint32(pos);
+        const type = String.fromCharCode(bytes[pos + 4], bytes[pos + 5], bytes[pos + 6], bytes[pos + 7]);
+        const dataOff = pos + 8;
+        if (len > bytes.length - dataOff)
+            throw new ImageDecodeError(`png: chunk ${type} overruns the file`);
+        if (type === 'IHDR') {
+            if (len < 13)
+                throw new ImageDecodeError('png: short IHDR');
+            hdr = { w: dv.getUint32(dataOff), h: dv.getUint32(dataOff + 4), depth: bytes[dataOff + 8], colorType: bytes[dataOff + 9], interlace: bytes[dataOff + 12] };
+            if (bytes[dataOff + 10] !== 0 || bytes[dataOff + 11] !== 0)
+                throw new ImageDecodeError('png: unsupported compression/filter method');
+            if (![1, 2, 4, 8, 16].includes(hdr.depth))
+                throw new ImageDecodeError(`png: bad bit depth ${hdr.depth}`);
+            if (hdr.interlace !== 0 && hdr.interlace !== 1)
+                throw new ImageDecodeError('png: bad interlace method');
+            checkDims(hdr.w, hdr.h, limits, 'png');
+        }
+        else if (type === 'PLTE') {
+            palette = bytes.subarray(dataOff, dataOff + len);
+        }
+        else if (type === 'tRNS') {
+            trns = bytes.subarray(dataOff, dataOff + len);
+        }
+        else if (type === 'IDAT') {
+            idat.push(bytes.subarray(dataOff, dataOff + len));
+            idatLen += len;
+            if (idatLen > limits.maxBytes)
+                throw new ImageDecodeError('png: compressed data over the byte cap');
+        }
+        else if (type === 'IEND') {
+            break;
+        }
+        pos = dataOff + len + 4; // skip CRC (not verified: a corrupt chunk fails decoding anyway)
+    }
+    if (!hdr)
+        throw new ImageDecodeError('png: no IHDR');
+    if (!idat.length)
+        throw new ImageDecodeError('png: no IDAT');
+    const { w, h, depth, colorType, interlace } = hdr;
+    const ch = channelsOf(colorType);
+    if (colorType === 3 && !palette)
+        throw new ImageDecodeError('png: palette image without PLTE');
+    if ((colorType === 2 || colorType === 4 || colorType === 6) && depth < 8)
+        throw new ImageDecodeError('png: bad depth for colour type');
+    const bitsPerPx = ch * depth;
+    const bpp = Math.max(1, Math.ceil(bitsPerPx / 8));
+    const strideFor = (cols) => Math.ceil((cols * bitsPerPx) / 8);
+    // Expected raw size (bounded by the dimension caps checked above).
+    let expect = 0;
+    if (interlace) {
+        for (const [sx, sy, dx, dy] of ADAM7) {
+            const pw = Math.ceil((w - sx) / dx), ph = Math.ceil((h - sy) / dy);
+            if (pw > 0 && ph > 0)
+                expect += ph * (strideFor(pw) + 1);
+        }
+    }
+    else
+        expect = h * (strideFor(w) + 1);
+    const raw = inflateSync(Buffer.concat(idat.map((c) => Buffer.from(c)), idatLen), { maxOutputLength: expect });
+    if (raw.length < expect)
+        throw new ImageDecodeError('png: truncated image data');
+    const out = new Uint8Array(w * h * 4);
+    const writePixel = (x, y, row, i) => {
+        const o = (y * w + x) * 4;
+        switch (colorType) {
+            case 0: {
+                const g = sampleAt(row, i, depth);
+                out[o] = g;
+                out[o + 1] = g;
+                out[o + 2] = g;
+                let a = 255;
+                if (trns && trns.length >= 2) {
+                    const key = (trns[0] << 8) | trns[1];
+                    const rawV = depth === 16 ? ((row[i * 2] << 8) | row[i * 2 + 1]) : indexAt(row, i, depth);
+                    if (rawV === key)
+                        a = 0;
+                }
+                out[o + 3] = a;
+                break;
+            }
+            case 2: {
+                const s = depth === 16 ? 2 : 1;
+                const r = row[i * 3 * s], g = row[(i * 3 + 1) * s], b = row[(i * 3 + 2) * s];
+                out[o] = r;
+                out[o + 1] = g;
+                out[o + 2] = b;
+                let a = 255;
+                if (trns && trns.length >= 6) {
+                    const kr = (trns[0] << 8) | trns[1], kg = (trns[2] << 8) | trns[3], kb = (trns[4] << 8) | trns[5];
+                    const rr = depth === 16 ? ((row[i * 6] << 8) | row[i * 6 + 1]) : r;
+                    const gg = depth === 16 ? ((row[i * 6 + 2] << 8) | row[i * 6 + 3]) : g;
+                    const bb = depth === 16 ? ((row[i * 6 + 4] << 8) | row[i * 6 + 5]) : b;
+                    if (rr === kr && gg === kg && bb === kb)
+                        a = 0;
+                }
+                out[o + 3] = a;
+                break;
+            }
+            case 3: {
+                const idx = indexAt(row, i, depth);
+                const p = palette;
+                if (idx * 3 + 2 >= p.length)
+                    throw new ImageDecodeError('png: palette index out of range');
+                out[o] = p[idx * 3];
+                out[o + 1] = p[idx * 3 + 1];
+                out[o + 2] = p[idx * 3 + 2];
+                out[o + 3] = trns && idx < trns.length ? trns[idx] : 255;
+                break;
+            }
+            case 4: {
+                const s = depth === 16 ? 2 : 1;
+                const g = row[i * 2 * s], a = row[(i * 2 + 1) * s];
+                out[o] = g;
+                out[o + 1] = g;
+                out[o + 2] = g;
+                out[o + 3] = a;
+                break;
+            }
+            case 6: {
+                const s = depth === 16 ? 2 : 1;
+                out[o] = row[i * 4 * s];
+                out[o + 1] = row[(i * 4 + 1) * s];
+                out[o + 2] = row[(i * 4 + 2) * s];
+                out[o + 3] = row[(i * 4 + 3) * s];
+                break;
+            }
+        }
+    };
+    if (!interlace) {
+        const stride = strideFor(w);
+        const px = unfilter(raw, 0, h, stride, bpp);
+        for (let y = 0; y < h; y++) {
+            const row = px.subarray(y * stride, (y + 1) * stride);
+            for (let x = 0; x < w; x++)
+                writePixel(x, y, row, x);
+        }
+    }
+    else {
+        let off = 0;
+        for (const [sx, sy, dx, dy] of ADAM7) {
+            const pw = Math.ceil((w - sx) / dx), ph = Math.ceil((h - sy) / dy);
+            if (pw <= 0 || ph <= 0)
+                continue;
+            const stride = strideFor(pw);
+            const px = unfilter(raw, off, ph, stride, bpp);
+            off += ph * (stride + 1);
+            for (let py = 0; py < ph; py++) {
+                const row = px.subarray(py * stride, (py + 1) * stride);
+                for (let pxi = 0; pxi < pw; pxi++)
+                    writePixel(sx + pxi * dx, sy + py * dy, row, pxi);
+            }
+        }
+    }
+    return { w, h, rgba: out };
+}
+// ---------------------------------------------------------------------------------------------- encoder
+const CRC_TABLE = (() => {
+    const t = new Uint32Array(256);
+    for (let n = 0; n < 256; n++) {
+        let c = n;
+        for (let k = 0; k < 8; k++)
+            c = c & 1 ? 0xedb88320 ^ (c >>> 1) : c >>> 1;
+        t[n] = c >>> 0;
+    }
+    return t;
+})();
+function crc32(buf) {
+    let c = 0xffffffff;
+    for (let i = 0; i < buf.length; i++)
+        c = CRC_TABLE[(c ^ buf[i]) & 0xff] ^ (c >>> 8);
+    return (c ^ 0xffffffff) >>> 0;
+}
+function chunk(type, data) {
+    const out = Buffer.alloc(12 + data.length);
+    out.writeUInt32BE(data.length, 0);
+    out.write(type, 4, 'latin1');
+    out.set(data, 8);
+    const crc = crc32(out.subarray(4, 8 + data.length));
+    out.writeUInt32BE(crc, 8 + data.length);
+    return out;
+}
+/** Encode straight-alpha RGBA8 as a PNG (colour type 6, filter 0 on every scanline, deflate level 6). */
+export function encodePng(img) {
+    const { w, h, rgba } = img;
+    if (rgba.length !== w * h * 4)
+        throw new ImageDecodeError('png encode: buffer size mismatch');
+    const ihdr = Buffer.alloc(13);
+    ihdr.writeUInt32BE(w, 0);
+    ihdr.writeUInt32BE(h, 4);
+    ihdr[8] = 8;
+    ihdr[9] = 6;
+    ihdr[10] = 0;
+    ihdr[11] = 0;
+    ihdr[12] = 0;
+    const stride = w * 4;
+    const raw = Buffer.alloc(h * (stride + 1));
+    for (let y = 0; y < h; y++) {
+        raw[y * (stride + 1)] = 0;
+        raw.set(rgba.subarray(y * stride, (y + 1) * stride), y * (stride + 1) + 1);
+    }
+    const idat = deflateSync(raw, { level: 6 });
+    return Buffer.concat([Buffer.from(SIG), chunk('IHDR', ihdr), chunk('IDAT', idat), chunk('IEND', new Uint8Array(0))]);
+}

package/dist/packages/data/src/images/service.js

@@ -0,0 +1,334 @@
+// @dexterm/data — ImageService (task-1326): the one object the UI asks for coin images. `get(url)` is
+// SYNCHRONOUS and never blocks: it answers from memory and, for an unknown URL, enqueues the work and
+// answers `pending`. A small worker pool then (1) checks the on-disk cache, (2) fetches through the SSRF-
+// safe binary fetch, (3) decodes + thumbnails in a worker thread, (4) stores our re-encoded PNG, and
+// (5) calls `onChange` so the UI loop redraws. Priorities: the screen re-requests what is visible every
+// frame, so the queue is served highest-priority-then-most-recent (the rows you are looking at win over
+// a pool scrolled past). Offline / replay runs answer from disk only and never touch the network.
+import { Worker } from 'node:worker_threads';
+import { readFile } from 'node:fs/promises';
+import { decodePng } from "./png.js";
+import { fetchBytes, thumbnailUrl } from "./fetch.js";
+import { ImageDiskCache, imageCacheKey } from "./cache.js";
+import { runDecodeJob } from "./decode-worker.js";
+/** Backoff before a transient failure is retried: 2 min, then 10 min, then never (this session). */
+export const RETRY_BACKOFF_MS = [120_000, 600_000];
+export class ImageService {
+    mem = new Map();
+    queue = [];
+    inflightUrls = new Set();
+    perHostInflight = new Map();
+    disk;
+    opts;
+    seq = 0;
+    closed = false;
+    worker = null;
+    workerBroken = false;
+    jobId = 0;
+    jobs = new Map();
+    abort = new AbortController();
+    /** Called after any image settles (ready or missing); the UI loop redraws. Settable after construction. */
+    onChange = null;
+    idleWaiters = [];
+    stats = { known: 0, ready: 0, missing: 0, pending: 0, inflight: 0, queued: 0, fetched: 0, fetchFailed: 0, diskHits: 0, decodeFailed: 0, decodeMsTotal: 0, decodes: 0, workerFallbacks: 0, bytesFetched: 0 };
+    constructor(opts) {
+        this.opts = { offline: false, concurrency: 3, perHost: 2, thumbMax: 96, maxMemory: 400, ...opts };
+        this.disk = new ImageDiskCache({ dir: opts.dir, maxBytes: opts.maxDiskBytes, now: opts.now });
+        this.onChange = opts.onChange ?? null;
+    }
+    /** True when nothing is queued or in flight. */
+    get idle() { return this.queue.length === 0 && this.inflightUrls.size === 0; }
+    /** Resolves once the queue drains (every requested image settled) or after `timeoutMs`. One-shot renders use it. */
+    whenIdle(timeoutMs = 4000) {
+        if (this.idle)
+            return Promise.resolve(true);
+        return new Promise((resolve) => {
+            const timer = setTimeout(() => { this.idleWaiters = this.idleWaiters.filter((w) => w !== done); resolve(false); }, timeoutMs);
+            timer.unref?.();
+            const done = () => { clearTimeout(timer); resolve(true); };
+            this.idleWaiters.push(done);
+        });
+    }
+    get dir() { return this.disk.dir; }
+    get offline() { return this.opts.offline; }
+    /** Stable cache key for a source URL (the popup route and the disk file name use it). */
+    keyFor(url) { return imageCacheKey(url); }
+    /**
+     * The image for a URL, right now. Never blocks: unknown URLs are queued (bumping their priority /
+     * recency on every ask) and answered `pending` until the worker lands them.
+     */
+    get(url, priority = 0) {
+        if (!url || typeof url !== 'string')
+            return { state: 'none' };
+        const e = this.mem.get(url);
+        if (e) {
+            if (e.state.state === 'pending' && !this.inflightUrls.has(url)) {
+                e.priority = Math.max(e.priority, priority);
+                e.seq = ++this.seq;
+            }
+            else if (e.state.state === 'ready') {
+                this.mem.delete(url);
+                this.mem.set(url, e);
+            } // LRU refresh
+            else if (e.state.state === 'missing' && e.state.retryAt !== undefined && this.now() >= e.state.retryAt && !this.inflightUrls.has(url)) {
+                // a transient failure, past its backoff: ask again (bounded by RETRY_BACKOFF_MS.length attempts)
+                e.state = { state: 'pending', key: e.key };
+                e.priority = priority;
+                e.seq = ++this.seq;
+                this.queue.push(e);
+                this.pump();
+            }
+            return e.state;
+        }
+        const key = this.keyFor(url);
+        const entry = { state: { state: 'pending', key }, url, key, priority, seq: ++this.seq, at: this.now(), attempts: 0 };
+        this.mem.set(url, entry);
+        this.queue.push(entry);
+        this.stats.known = this.mem.size;
+        this.pump();
+        return entry.state;
+    }
+    /** Warm a set of URLs (visible rows, the open token) at a priority; no answer needed. */
+    prefetch(urls, priority = 0) {
+        for (const u of urls)
+            if (u)
+                this.get(u, priority);
+    }
+    /** Our stored PNG for a key (memory, then disk) — what the popup server serves. Sync, small. */
+    pngFor(key) {
+        if (!/^[0-9a-f]{32}$/.test(key))
+            return null;
+        for (const e of this.mem.values())
+            if (e.key === key && e.state.state === 'ready')
+                return e.state.png;
+        const b = this.disk.get(key);
+        return b ? new Uint8Array(b.buffer, b.byteOffset, b.byteLength) : null;
+    }
+    snapshot() {
+        let ready = 0, missing = 0, pending = 0;
+        for (const e of this.mem.values()) {
+            if (e.state.state === 'ready')
+                ready++;
+            else if (e.state.state === 'missing')
+                missing++;
+            else
+                pending++;
+        }
+        return { ...this.stats, known: this.mem.size, ready, missing, pending, inflight: this.inflightUrls.size, queued: this.queue.length };
+    }
+    close() {
+        if (this.closed)
+            return;
+        this.closed = true;
+        this.abort.abort(new Error('closing'));
+        this.queue.length = 0;
+        for (const j of this.jobs.values()) {
+            clearTimeout(j.timer);
+            j.resolve({ id: 0, ok: false, error: 'closing' });
+        }
+        this.jobs.clear();
+        if (this.worker) {
+            void this.worker.terminate().catch(() => { });
+            this.worker = null;
+        }
+    }
+    now() { return this.opts.now ? this.opts.now() : Date.now(); }
+    hostOf(url) { try {
+        return new URL(url).hostname;
+    }
+    catch {
+        return '?';
+    } }
+    pump() {
+        if (this.closed)
+            return;
+        while (this.inflightUrls.size < this.opts.concurrency && this.queue.length) {
+            // highest priority, then most recently asked for
+            let best = -1;
+            for (let i = 0; i < this.queue.length; i++) {
+                const e = this.queue[i];
+                const host = this.hostOf(e.url);
+                if ((this.perHostInflight.get(host) ?? 0) >= this.opts.perHost)
+                    continue;
+                if (best < 0 || e.priority > this.queue[best].priority || (e.priority === this.queue[best].priority && e.seq > this.queue[best].seq))
+                    best = i;
+            }
+            if (best < 0)
+                return;
+            const [e] = this.queue.splice(best, 1);
+            void this.run(e);
+        }
+    }
+    settle(e, state) {
+        e.state = state;
+        e.at = this.now();
+        if (state.state === 'ready') {
+            this.mem.delete(e.url);
+            this.mem.set(e.url, e);
+            // memory LRU: drop the oldest READY entries past the cap (pending/missing are tiny)
+            let readyCount = 0;
+            for (const x of this.mem.values())
+                if (x.state.state === 'ready')
+                    readyCount++;
+            if (readyCount > this.opts.maxMemory) {
+                for (const [k, x] of this.mem) {
+                    if (x.state.state !== 'ready')
+                        continue;
+                    this.mem.delete(k);
+                    readyCount--;
+                    if (readyCount <= this.opts.maxMemory)
+                        break;
+                }
+            }
+        }
+        if (!this.closed)
+            this.onChange?.();
+    }
+    async run(e) {
+        const host = this.hostOf(e.url);
+        this.inflightUrls.add(e.url);
+        this.perHostInflight.set(host, (this.perHostInflight.get(host) ?? 0) + 1);
+        const t0 = this.now();
+        try {
+            // 1. disk cache (our own PNG) — fresh or not, it is the thumbnail we last made for this URL
+            const cached = this.disk.get(e.key);
+            if (cached) {
+                try {
+                    const img = decodePng(cached);
+                    this.stats.diskHits += 1;
+                    this.opts.onRequest?.({ url: e.url, ok: true, bytes: cached.length, ms: this.now() - t0, reason: null, source: 'disk' });
+                    this.settle(e, { state: 'ready', img, png: new Uint8Array(cached.buffer, cached.byteOffset, cached.byteLength), key: e.key });
+                    return;
+                }
+                catch { /* corrupt file: fall through and refetch */ }
+            }
+            if (this.disk.failed(e.key)) {
+                this.settle(e, { state: 'missing', reason: 'failed recently', key: e.key });
+                return;
+            }
+            if (this.opts.offline) {
+                this.opts.onRequest?.({ url: e.url, ok: false, bytes: 0, ms: 0, reason: 'offline', source: 'offline' });
+                this.settle(e, { state: 'missing', reason: 'offline', key: e.key });
+                return;
+            }
+            // 2. network
+            const target = (this.opts.rewrite ?? thumbnailUrl)(e.url);
+            const res = this.opts.fetch ? await this.opts.fetch(target, this.abort.signal) : await fetchBytes(target, { signal: this.abort.signal });
+            if (this.closed)
+                return;
+            if (!res.ok) {
+                this.stats.fetchFailed += 1;
+                this.opts.onRequest?.({ url: target, ok: false, bytes: 0, ms: res.elapsedMs, reason: res.reason, source: 'network' });
+                // a 4xx (not 429) or a policy refusal is durable (marked on disk); a 429 / timeout / 5xx is transient and
+                // retried after a backoff within this session (public IPFS gateways rate-limit in bursts)
+                const policy = res.status === 0 && !/timed out|fetch failed/.test(res.reason ?? '');
+                const durable = policy || (res.status >= 400 && res.status < 500 && res.status !== 429);
+                if (durable)
+                    this.disk.markFailed(e.key, res.reason ?? 'http');
+                e.attempts += 1;
+                const wait = durable ? undefined : RETRY_BACKOFF_MS[e.attempts - 1];
+                this.settle(e, { state: 'missing', reason: res.reason ?? 'fetch failed', key: e.key, ...(wait !== undefined ? { retryAt: this.now() + wait } : {}) });
+                return;
+            }
+            this.stats.fetched += 1;
+            this.stats.bytesFetched += res.bytes.length;
+            // 3. decode (worker thread), 4. store, 5. notify
+            const td = this.now();
+            const d = await this.decode(res.bytes);
+            this.stats.decodes += 1;
+            this.stats.decodeMsTotal += this.now() - td;
+            if (this.closed)
+                return;
+            if (!d.ok) {
+                this.stats.decodeFailed += 1;
+                this.opts.onRequest?.({ url: target, ok: false, bytes: res.bytes.length, ms: this.now() - t0, reason: d.error, source: 'network' });
+                this.disk.markFailed(e.key, d.error);
+                this.settle(e, { state: 'missing', reason: d.error, key: e.key });
+                return;
+            }
+            this.disk.put(e.key, d.png);
+            this.opts.onRequest?.({ url: target, ok: true, bytes: res.bytes.length, ms: this.now() - t0, reason: null, source: 'network' });
+            this.settle(e, { state: 'ready', img: { w: d.w, h: d.h, rgba: d.rgba }, png: d.png, key: e.key });
+        }
+        catch (err) {
+            if (!this.closed)
+                this.settle(e, { state: 'missing', reason: err.message ?? 'error', key: e.key });
+        }
+        finally {
+            this.inflightUrls.delete(e.url);
+            this.perHostInflight.set(host, Math.max(0, (this.perHostInflight.get(host) ?? 1) - 1));
+            this.pump();
+            if (this.idle && this.idleWaiters.length) {
+                const ws = this.idleWaiters;
+                this.idleWaiters = [];
+                for (const w of ws)
+                    w();
+            }
+        }
+    }
+    decode(bytes) {
+        if (this.opts.decode)
+            return this.opts.decode(bytes, this.opts.thumbMax);
+        const w = this.ensureWorker();
+        const id = ++this.jobId;
+        const job = { id, bytes: new Uint8Array(bytes), thumbMax: this.opts.thumbMax };
+        if (!w) {
+            this.stats.workerFallbacks += 1;
+            return Promise.resolve(runDecodeJob(job));
+        }
+        return new Promise((resolve) => {
+            // A decode that takes more than 10 s is pathological input: kill the worker, fail the job, rebuild lazily.
+            const timer = setTimeout(() => { this.jobs.delete(id); this.breakWorker(); resolve({ id, ok: false, error: 'decode timed out' }); }, 10_000);
+            timer.unref?.();
+            this.jobs.set(id, { resolve, timer });
+            try {
+                w.postMessage(job, [job.bytes.buffer]);
+            }
+            catch (e) {
+                clearTimeout(timer);
+                this.jobs.delete(id);
+                resolve({ id, ok: false, error: e.message });
+            }
+        });
+    }
+    ensureWorker() {
+        if (this.worker)
+            return this.worker;
+        if (this.workerBroken || this.closed)
+            return null;
+        try {
+            const w = new Worker(new URL('./decode-worker.js', import.meta.url));
+            w.unref(); // a worker alone never keeps the process alive (quit stays instant)
+            w.on('message', (r) => {
+                const j = this.jobs.get(r.id);
+                if (!j)
+                    return;
+                clearTimeout(j.timer);
+                this.jobs.delete(r.id);
+                j.resolve(r);
+            });
+            w.on('error', (e) => { this.failJobs(`worker error: ${e.message}`); this.breakWorker(); });
+            w.on('exit', () => { if (this.worker === w)
+                this.worker = null; this.failJobs('worker exited'); });
+            this.worker = w;
+            return w;
+        }
+        catch {
+            this.workerBroken = true; // main-thread fallback from now on
+            return null;
+        }
+    }
+    failJobs(reason) {
+        for (const [id, j] of this.jobs) {
+            clearTimeout(j.timer);
+            j.resolve({ id, ok: false, error: reason });
+        }
+        this.jobs.clear();
+    }
+    breakWorker() {
+        const w = this.worker;
+        this.worker = null;
+        if (w)
+            void w.terminate().catch(() => { });
+    }
+}

package/dist/packages/data/src/images/types.js

@@ -0,0 +1,27 @@
+// @dexterm/data — shared image types + caps (task-1326). Every decoder checks the header against these
+// limits BEFORE allocating a pixel buffer, so a hostile header (4 billion × 4 billion) costs nothing.
+/** 2048², 4 MP, 2 MiB: comfortably above any real coin logo, far below anything that could hurt. */
+export const DEFAULT_LIMITS = { maxDim: 2048, maxPixels: 4 * 1024 * 1024, maxBytes: 2 * 1024 * 1024 };
+export class ImageDecodeError extends Error {
+    constructor(msg) { super(msg); this.name = 'ImageDecodeError'; }
+}
+export function checkDims(w, h, limits, what) {
+    if (!(w > 0 && h > 0))
+        throw new ImageDecodeError(`${what}: empty image`);
+    if (w > limits.maxDim || h > limits.maxDim)
+        throw new ImageDecodeError(`${what}: ${w}×${h} exceeds the ${limits.maxDim} px dimension cap`);
+    if (w * h > limits.maxPixels)
+        throw new ImageDecodeError(`${what}: ${w}×${h} exceeds the pixel cap`);
+}
+/** Sniff the container by magic bytes only (never by the URL or the Content-Type header). */
+export function sniffFormat(b) {
+    if (b.length >= 8 && b[0] === 0x89 && b[1] === 0x50 && b[2] === 0x4e && b[3] === 0x47 && b[4] === 0x0d && b[5] === 0x0a && b[6] === 0x1a && b[7] === 0x0a)
+        return 'png';
+    if (b.length >= 3 && b[0] === 0xff && b[1] === 0xd8 && b[2] === 0xff)
+        return 'jpeg';
+    if (b.length >= 6 && b[0] === 0x47 && b[1] === 0x49 && b[2] === 0x46 && b[3] === 0x38 && (b[4] === 0x37 || b[4] === 0x39) && b[5] === 0x61)
+        return 'gif';
+    if (b.length >= 12 && b[0] === 0x52 && b[1] === 0x49 && b[2] === 0x46 && b[3] === 0x46 && b[8] === 0x57 && b[9] === 0x45 && b[10] === 0x42 && b[11] === 0x50)
+        return 'webp';
+    return null;
+}