picopilot 0.0.0 → 0.1.0

package/dist/engine/gfx/label.js

@@ -0,0 +1,190 @@
+/**
+ * The `__label__` builder: turn a 128x128 image into the hex a `.p8` cart's
+ * label section holds, so `picopilot export --label <png>` can give a labelless
+ * cart a loading splash WITHOUT an interactive PICO-8 (F7) capture.
+ *
+ * A PICO-8 label is a 128x128 grid of palette indices (0..15), serialised as 128
+ * rows of 128 hex nibbles. This module decodes a PNG to RGB (via Node's stdlib
+ * `zlib` inflate, no npm dependency), maps each pixel to the NEAREST PICO-8
+ * palette colour, and emits that hex. It is the inverse direction of the
+ * palette-accurate PNG RENDER in `render.ts`/`png.ts` (which goes indices -> RGB).
+ *
+ * It intentionally supports only the PNG subset a caller realistically produces
+ * for a 128x128 label: 8-bit, non-interlaced, colour types 2 (RGB) and 6 (RGBA),
+ * and (via the palette map) 0/3 are rejected with a clear error rather than
+ * guessed at. Anything else fails loud with a structured {@link LabelError}.
+ */
+import { inflateSync } from 'node:zlib';
+import { PICO8_PALETTE } from './palette.js';
+/** The fixed PICO-8 label dimensions: a 128x128 image. */
+export const LABEL_SIZE = 128;
+/** A structured label-build failure (bad PNG, wrong size, unsupported format). */
+export class LabelError extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.code = code;
+        this.name = 'LabelError';
+    }
+}
+const PNG_SIGNATURE = [0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a];
+/**
+ * Decodes an 8-bit, non-interlaced PNG (colour type 2 RGB or 6 RGBA) to RGBA.
+ * Uses `node:zlib` inflate for the IDAT stream and applies the five PNG scanline
+ * filters. Throws {@link LabelError} for anything outside this subset.
+ */
+function decodePng(bytes) {
+    for (let i = 0; i < PNG_SIGNATURE.length; i++) {
+        if (bytes[i] !== PNG_SIGNATURE[i]) {
+            throw new LabelError('not-a-png', 'not a PNG file (bad signature)');
+        }
+    }
+    let off = 8;
+    let width = 0;
+    let height = 0;
+    let bitDepth = 0;
+    let colourType = 0;
+    let interlace = 0;
+    const idat = [];
+    const readU32 = (p) => ((bytes[p] << 24) |
+        (bytes[p + 1] << 16) |
+        (bytes[p + 2] << 8) |
+        bytes[p + 3]) >>>
+        0;
+    while (off + 8 <= bytes.length) {
+        const len = readU32(off);
+        const type = String.fromCharCode(bytes[off + 4], bytes[off + 5], bytes[off + 6], bytes[off + 7]);
+        const dataStart = off + 8;
+        const dataEnd = dataStart + len;
+        if (dataEnd + 4 > bytes.length) {
+            throw new LabelError('truncated-png', 'PNG chunk runs past end of file');
+        }
+        if (type === 'IHDR') {
+            width = readU32(dataStart);
+            height = readU32(dataStart + 4);
+            bitDepth = bytes[dataStart + 8];
+            colourType = bytes[dataStart + 9];
+            interlace = bytes[dataStart + 12];
+        }
+        else if (type === 'IDAT') {
+            idat.push(bytes.subarray(dataStart, dataEnd));
+        }
+        else if (type === 'IEND') {
+            break;
+        }
+        off = dataEnd + 4; // skip the 4-byte CRC
+    }
+    if (bitDepth !== 8 ||
+        interlace !== 0 ||
+        (colourType !== 2 && colourType !== 6)) {
+        throw new LabelError('unsupported-png', `unsupported PNG: need 8-bit non-interlaced RGB or RGBA (got bitDepth=${bitDepth}, colourType=${colourType}, interlace=${interlace})`);
+    }
+    const channels = colourType === 6 ? 4 : 3;
+    const compressed = Buffer.concat(idat.map((c) => Buffer.from(c)));
+    let raw;
+    try {
+        raw = inflateSync(compressed);
+    }
+    catch (e) {
+        throw new LabelError('truncated-png', `could not inflate PNG image data: ${e.message}`);
+    }
+    const stride = width * channels;
+    const rgba = new Uint8Array(width * height * 4);
+    const prev = new Uint8Array(stride);
+    let src = 0;
+    for (let y = 0; y < height; y++) {
+        const filter = raw[src++];
+        const line = new Uint8Array(stride);
+        for (let x = 0; x < stride; x++) {
+            const rawByte = raw[src++];
+            const a = x >= channels ? line[x - channels] : 0; // left
+            const b = prev[x]; // up
+            const c = x >= channels ? prev[x - channels] : 0; // up-left
+            let val = rawByte;
+            switch (filter) {
+                case 0:
+                    break; // None
+                case 1:
+                    val = (rawByte + a) & 0xff;
+                    break; // Sub
+                case 2:
+                    val = (rawByte + b) & 0xff;
+                    break; // Up
+                case 3:
+                    val = (rawByte + ((a + b) >> 1)) & 0xff;
+                    break; // Average
+                case 4:
+                    val = (rawByte + paeth(a, b, c)) & 0xff;
+                    break; // Paeth
+                default:
+                    throw new LabelError('unsupported-png', `unsupported PNG scanline filter ${filter}`);
+            }
+            line[x] = val;
+        }
+        // Expand this decoded scanline into RGBA.
+        for (let x = 0; x < width; x++) {
+            const s = x * channels;
+            const d = (y * width + x) * 4;
+            rgba[d] = line[s];
+            rgba[d + 1] = line[s + 1];
+            rgba[d + 2] = line[s + 2];
+            rgba[d + 3] = channels === 4 ? line[s + 3] : 255;
+        }
+        prev.set(line);
+    }
+    return { width, height, rgba };
+}
+/** The PNG Paeth predictor. */
+function paeth(a, b, c) {
+    const p = a + b - c;
+    const pa = Math.abs(p - a);
+    const pb = Math.abs(p - b);
+    const pc = Math.abs(p - c);
+    if (pa <= pb && pa <= pc)
+        return a;
+    if (pb <= pc)
+        return b;
+    return c;
+}
+/** The nearest PICO-8 palette index (by squared RGB distance) for an RGB triple. */
+export function nearestPaletteIndex(r, g, b) {
+    let best = 0;
+    let bestDist = Infinity;
+    for (let i = 0; i < PICO8_PALETTE.length; i++) {
+        const c = PICO8_PALETTE[i];
+        const dr = r - c.r;
+        const dg = g - c.g;
+        const db = b - c.b;
+        const dist = dr * dr + dg * dg + db * db;
+        if (dist < bestDist) {
+            bestDist = dist;
+            best = i;
+        }
+    }
+    return best;
+}
+const HEX = '0123456789abcdef';
+/**
+ * Builds the `__label__` hex body (128 rows of 128 nibbles, newline-joined, with
+ * a trailing newline) from a 128x128 PNG. Each pixel is mapped to its nearest
+ * PICO-8 palette colour. The PNG MUST be exactly 128x128 ({@link LABEL_SIZE});
+ * anything else is a {@link LabelError} (`wrong-size`) so a mis-sized image fails
+ * loud instead of being silently cropped or stretched.
+ */
+export function labelHexFromPng(pngBytes) {
+    const { width, height, rgba } = decodePng(pngBytes);
+    if (width !== LABEL_SIZE || height !== LABEL_SIZE) {
+        throw new LabelError('wrong-size', `label image must be ${LABEL_SIZE}x${LABEL_SIZE}, got ${width}x${height}`);
+    }
+    const rows = [];
+    for (let y = 0; y < LABEL_SIZE; y++) {
+        let row = '';
+        for (let x = 0; x < LABEL_SIZE; x++) {
+            const d = (y * LABEL_SIZE + x) * 4;
+            row += HEX[nearestPaletteIndex(rgba[d], rgba[d + 1], rgba[d + 2])];
+        }
+        rows.push(row);
+    }
+    return `${rows.join('\n')}\n`;
+}
+//# sourceMappingURL=label.js.map

package/dist/engine/gfx/label.js.map

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

package/dist/engine/gfx/overlap.d.ts

@@ -0,0 +1,42 @@
+import { type GfxSheet } from '../cart/index.js';
+/**
+ * The gfx/map overlap smart-refuse decision (ADR-0004), computed purely from a
+ * cart's CURRENT `__gfx__` pixels plus the authorisation flag.
+ *
+ * Why `__gfx__`, not `__map__` (the corrected seam): sprites 128..255 alias the
+ * shared map region, but those shared bytes live in the `__gfx__` `0x1000` upper
+ * bank, NOT in the text-format `.p8` `__map__` section (which stores only map
+ * rows 0..31). So "the data at risk" when overwriting a shared-bank sprite IS
+ * the sprite's OWN current `__gfx__` pixels. This module inspects those pixels
+ * directly (via {@link GfxSheet}); it deliberately does NOT consult `__map__`.
+ *
+ * The single invariant: picopilot never SILENTLY overwrites existing
+ * shared-region data that nothing authorised.
+ */
+/** Whether ANY pixel of sprite `n` is non-zero, i.e. the sprite already holds data. */
+export declare function spriteHasData(sheet: GfxSheet, n: number): boolean;
+/** The verdict of {@link decideOverlap}. */
+export type OverlapDecision = {
+    kind: 'allowed';
+} | {
+    kind: 'allowed-shared';
+    reason: 'authorised' | 'empty';
+} | {
+    kind: 'refused';
+    nonZeroPixels: number;
+};
+/**
+ * Decides whether a `gfx set` write to sprite `n` may proceed, given the cart's
+ * current `__gfx__` and whether overlap is authorised.
+ *
+ * - sprite 0..127 (base bank, aliases nothing) → `allowed` (no overlap possible).
+ * - sprite 128..255 whose current pixels are ALL-ZERO → `allowed-shared` (empty):
+ *   the write proceeds; the caller notes the aliasing in its result.
+ * - sprite 128..255 with non-zero pixels AND `authorised` → `allowed-shared`
+ *   (authorised): the write proceeds and overwrites the shared data on purpose.
+ * - sprite 128..255 with non-zero pixels AND NOT authorised → `refused`: the
+ *   genuine data-loss corner. The caller REFUSES (structured + nonzero exit +
+ *   bytes untouched).
+ */
+export declare function decideOverlap(sheet: GfxSheet, n: number, authorised: boolean): OverlapDecision;
+//# sourceMappingURL=overlap.d.ts.map

package/dist/engine/gfx/overlap.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"overlap.d.ts","sourceRoot":"","sources":["../../../src/engine/gfx/overlap.ts"],"names":[],"mappings":"AAAA,OAAO,EAAC,KAAK,QAAQ,EAAmB,MAAM,kBAAkB,CAAC;AAEjE;;;;;;;;;;;;;GAaG;AAEH,uFAAuF;AACvF,wBAAgB,aAAa,CAAC,KAAK,EAAE,QAAQ,EAAE,CAAC,EAAE,MAAM,GAAG,OAAO,CAMjE;AAED,4CAA4C;AAC5C,MAAM,MAAM,eAAe,GACxB;IAAC,IAAI,EAAE,SAAS,CAAA;CAAC,GACjB;IAAC,IAAI,EAAE,gBAAgB,CAAC;IAAC,MAAM,EAAE,YAAY,GAAG,OAAO,CAAA;CAAC,GACxD;IAAC,IAAI,EAAE,SAAS,CAAC;IAAC,aAAa,EAAE,MAAM,CAAA;CAAC,CAAC;AAE5C;;;;;;;;;;;;GAYG;AACH,wBAAgB,aAAa,CAC5B,KAAK,EAAE,QAAQ,EACf,CAAC,EAAE,MAAM,EACT,UAAU,EAAE,OAAO,GACjB,eAAe,CAQjB"}

package/dist/engine/gfx/overlap.js

@@ -0,0 +1,57 @@
+import { spriteAliasesMap } from '../cart/index.js';
+/**
+ * The gfx/map overlap smart-refuse decision (ADR-0004), computed purely from a
+ * cart's CURRENT `__gfx__` pixels plus the authorisation flag.
+ *
+ * Why `__gfx__`, not `__map__` (the corrected seam): sprites 128..255 alias the
+ * shared map region, but those shared bytes live in the `__gfx__` `0x1000` upper
+ * bank, NOT in the text-format `.p8` `__map__` section (which stores only map
+ * rows 0..31). So "the data at risk" when overwriting a shared-bank sprite IS
+ * the sprite's OWN current `__gfx__` pixels. This module inspects those pixels
+ * directly (via {@link GfxSheet}); it deliberately does NOT consult `__map__`.
+ *
+ * The single invariant: picopilot never SILENTLY overwrites existing
+ * shared-region data that nothing authorised.
+ */
+/** Whether ANY pixel of sprite `n` is non-zero, i.e. the sprite already holds data. */
+export function spriteHasData(sheet, n) {
+    const grid = sheet.getSprite(n);
+    for (const row of grid) {
+        for (const px of row)
+            if (px !== 0)
+                return true;
+    }
+    return false;
+}
+/**
+ * Decides whether a `gfx set` write to sprite `n` may proceed, given the cart's
+ * current `__gfx__` and whether overlap is authorised.
+ *
+ * - sprite 0..127 (base bank, aliases nothing) → `allowed` (no overlap possible).
+ * - sprite 128..255 whose current pixels are ALL-ZERO → `allowed-shared` (empty):
+ *   the write proceeds; the caller notes the aliasing in its result.
+ * - sprite 128..255 with non-zero pixels AND `authorised` → `allowed-shared`
+ *   (authorised): the write proceeds and overwrites the shared data on purpose.
+ * - sprite 128..255 with non-zero pixels AND NOT authorised → `refused`: the
+ *   genuine data-loss corner. The caller REFUSES (structured + nonzero exit +
+ *   bytes untouched).
+ */
+export function decideOverlap(sheet, n, authorised) {
+    if (!spriteAliasesMap(n))
+        return { kind: 'allowed' };
+    if (!spriteHasData(sheet, n))
+        return { kind: 'allowed-shared', reason: 'empty' };
+    if (authorised)
+        return { kind: 'allowed-shared', reason: 'authorised' };
+    return { kind: 'refused', nonZeroPixels: countNonZeroPixels(sheet, n) };
+}
+function countNonZeroPixels(sheet, n) {
+    let count = 0;
+    for (const row of sheet.getSprite(n)) {
+        for (const px of row)
+            if (px !== 0)
+                count++;
+    }
+    return count;
+}
+//# sourceMappingURL=overlap.js.map

package/dist/engine/gfx/overlap.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"overlap.js","sourceRoot":"","sources":["../../../src/engine/gfx/overlap.ts"],"names":[],"mappings":"AAAA,OAAO,EAAgB,gBAAgB,EAAC,MAAM,kBAAkB,CAAC;AAEjE;;;;;;;;;;;;;GAaG;AAEH,uFAAuF;AACvF,MAAM,UAAU,aAAa,CAAC,KAAe,EAAE,CAAS;IACvD,MAAM,IAAI,GAAG,KAAK,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC;IAChC,KAAK,MAAM,GAAG,IAAI,IAAI,EAAE,CAAC;QACxB,KAAK,MAAM,EAAE,IAAI,GAAG;YAAE,IAAI,EAAE,KAAK,CAAC;gBAAE,OAAO,IAAI,CAAC;IACjD,CAAC;IACD,OAAO,KAAK,CAAC;AACd,CAAC;AAQD;;;;;;;;;;;;GAYG;AACH,MAAM,UAAU,aAAa,CAC5B,KAAe,EACf,CAAS,EACT,UAAmB;IAEnB,IAAI,CAAC,gBAAgB,CAAC,CAAC,CAAC;QAAE,OAAO,EAAC,IAAI,EAAE,SAAS,EAAC,CAAC;IAEnD,IAAI,CAAC,aAAa,CAAC,KAAK,EAAE,CAAC,CAAC;QAC3B,OAAO,EAAC,IAAI,EAAE,gBAAgB,EAAE,MAAM,EAAE,OAAO,EAAC,CAAC;IAClD,IAAI,UAAU;QAAE,OAAO,EAAC,IAAI,EAAE,gBAAgB,EAAE,MAAM,EAAE,YAAY,EAAC,CAAC;IAEtE,OAAO,EAAC,IAAI,EAAE,SAAS,EAAE,aAAa,EAAE,kBAAkB,CAAC,KAAK,EAAE,CAAC,CAAC,EAAC,CAAC;AACvE,CAAC;AAED,SAAS,kBAAkB,CAAC,KAAe,EAAE,CAAS;IACrD,IAAI,KAAK,GAAG,CAAC,CAAC;IACd,KAAK,MAAM,GAAG,IAAI,KAAK,CAAC,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC;QACtC,KAAK,MAAM,EAAE,IAAI,GAAG;YAAE,IAAI,EAAE,KAAK,CAAC;gBAAE,KAAK,EAAE,CAAC;IAC7C,CAAC;IACD,OAAO,KAAK,CAAC;AACd,CAAC"}

package/dist/engine/gfx/palette.d.ts

@@ -0,0 +1,29 @@
+/**
+ * PICO-8's FIXED 16-colour palette (index → RGB), the single source of truth for
+ * the `gfx render` PNG encoder.
+ *
+ * These are the stable, widely-reproduced PICO-8 0..15 palette constants,
+ * transcribed verbatim from `work/notes/findings/pico8-api-reference.md` (the
+ * same table the scaffolded `AGENTS.md` reference cites). Do NOT re-invent these
+ * values: if a future PICO-8 version alters them, revise the finding, the
+ * scaffold reference, and THIS table together.
+ *
+ * Index 0 doubles as PICO-8's default transparent colour; `gfx render` renders it
+ * as its RGB (black) so the PNG shows the actual pixels a `spr()` with no
+ * transparency would draw. (Transparency is a draw-time concern, not a property
+ * of the spritesheet bytes, so the JUDGE surface renders every index opaquely.)
+ */
+/** One palette entry: the colour index and its RGB triple. */
+export interface PaletteColor {
+    readonly r: number;
+    readonly g: number;
+    readonly b: number;
+}
+/**
+ * The 16 PICO-8 palette RGB triples, indexed 0..15. Frozen so no caller can
+ * mutate the shared source of truth.
+ */
+export declare const PICO8_PALETTE: readonly PaletteColor[];
+/** The RGB triple for colour index 0..15. Throws for an out-of-range index. */
+export declare function paletteColor(index: number): PaletteColor;
+//# sourceMappingURL=palette.d.ts.map

package/dist/engine/gfx/palette.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"palette.d.ts","sourceRoot":"","sources":["../../../src/engine/gfx/palette.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,8DAA8D;AAC9D,MAAM,WAAW,YAAY;IAC5B,QAAQ,CAAC,CAAC,EAAE,MAAM,CAAC;IACnB,QAAQ,CAAC,CAAC,EAAE,MAAM,CAAC;IACnB,QAAQ,CAAC,CAAC,EAAE,MAAM,CAAC;CACnB;AAED;;;GAGG;AACH,eAAO,MAAM,aAAa,EAAE,SAAS,YAAY,EAiBtC,CAAC;AAEZ,+EAA+E;AAC/E,wBAAgB,YAAY,CAAC,KAAK,EAAE,MAAM,GAAG,YAAY,CAMxD"}

package/dist/engine/gfx/palette.js

@@ -0,0 +1,46 @@
+/**
+ * PICO-8's FIXED 16-colour palette (index → RGB), the single source of truth for
+ * the `gfx render` PNG encoder.
+ *
+ * These are the stable, widely-reproduced PICO-8 0..15 palette constants,
+ * transcribed verbatim from `work/notes/findings/pico8-api-reference.md` (the
+ * same table the scaffolded `AGENTS.md` reference cites). Do NOT re-invent these
+ * values: if a future PICO-8 version alters them, revise the finding, the
+ * scaffold reference, and THIS table together.
+ *
+ * Index 0 doubles as PICO-8's default transparent colour; `gfx render` renders it
+ * as its RGB (black) so the PNG shows the actual pixels a `spr()` with no
+ * transparency would draw. (Transparency is a draw-time concern, not a property
+ * of the spritesheet bytes, so the JUDGE surface renders every index opaquely.)
+ */
+/**
+ * The 16 PICO-8 palette RGB triples, indexed 0..15. Frozen so no caller can
+ * mutate the shared source of truth.
+ */
+export const PICO8_PALETTE = Object.freeze([
+    { r: 0, g: 0, b: 0 }, // 0  black
+    { r: 29, g: 43, b: 83 }, // 1  dark-blue
+    { r: 126, g: 37, b: 83 }, // 2  dark-purple
+    { r: 0, g: 135, b: 81 }, // 3  dark-green
+    { r: 171, g: 82, b: 54 }, // 4  brown
+    { r: 95, g: 87, b: 79 }, // 5  dark-grey
+    { r: 194, g: 195, b: 199 }, // 6  light-grey
+    { r: 255, g: 241, b: 232 }, // 7  white
+    { r: 255, g: 0, b: 77 }, // 8  red
+    { r: 255, g: 163, b: 0 }, // 9  orange
+    { r: 255, g: 236, b: 39 }, // 10 yellow
+    { r: 0, g: 228, b: 54 }, // 11 green
+    { r: 41, g: 173, b: 255 }, // 12 blue
+    { r: 131, g: 118, b: 156 }, // 13 lavender
+    { r: 255, g: 119, b: 168 }, // 14 pink
+    { r: 255, g: 204, b: 170 }, // 15 peach
+]);
+/** The RGB triple for colour index 0..15. Throws for an out-of-range index. */
+export function paletteColor(index) {
+    const c = PICO8_PALETTE[index];
+    if (c === undefined) {
+        throw new RangeError(`palette index ${index} out of range 0..15`);
+    }
+    return c;
+}
+//# sourceMappingURL=palette.js.map

package/dist/engine/gfx/palette.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"palette.js","sourceRoot":"","sources":["../../../src/engine/gfx/palette.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AASH;;;GAGG;AACH,MAAM,CAAC,MAAM,aAAa,GAA4B,MAAM,CAAC,MAAM,CAAC;IACnE,EAAC,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,EAAC,EAAE,WAAW;IAC/B,EAAC,CAAC,EAAE,EAAE,EAAE,CAAC,EAAE,EAAE,EAAE,CAAC,EAAE,EAAE,EAAC,EAAE,eAAe;IACtC,EAAC,CAAC,EAAE,GAAG,EAAE,CAAC,EAAE,EAAE,EAAE,CAAC,EAAE,EAAE,EAAC,EAAE,iBAAiB;IACzC,EAAC,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,GAAG,EAAE,CAAC,EAAE,EAAE,EAAC,EAAE,gBAAgB;IACvC,EAAC,CAAC,EAAE,GAAG,EAAE,CAAC,EAAE,EAAE,EAAE,CAAC,EAAE,EAAE,EAAC,EAAE,WAAW;IACnC,EAAC,CAAC,EAAE,EAAE,EAAE,CAAC,EAAE,EAAE,EAAE,CAAC,EAAE,EAAE,EAAC,EAAE,eAAe;IACtC,EAAC,CAAC,EAAE,GAAG,EAAE,CAAC,EAAE,GAAG,EAAE,CAAC,EAAE,GAAG,EAAC,EAAE,gBAAgB;IAC1C,EAAC,CAAC,EAAE,GAAG,EAAE,CAAC,EAAE,GAAG,EAAE,CAAC,EAAE,GAAG,EAAC,EAAE,WAAW;IACrC,EAAC,CAAC,EAAE,GAAG,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,EAAE,EAAC,EAAE,SAAS;IAChC,EAAC,CAAC,EAAE,GAAG,EAAE,CAAC,EAAE,GAAG,EAAE,CAAC,EAAE,CAAC,EAAC,EAAE,YAAY;IACpC,EAAC,CAAC,EAAE,GAAG,EAAE,CAAC,EAAE,GAAG,EAAE,CAAC,EAAE,EAAE,EAAC,EAAE,YAAY;IACrC,EAAC,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,GAAG,EAAE,CAAC,EAAE,EAAE,EAAC,EAAE,WAAW;IAClC,EAAC,CAAC,EAAE,EAAE,EAAE,CAAC,EAAE,GAAG,EAAE,CAAC,EAAE,GAAG,EAAC,EAAE,UAAU;IACnC,EAAC,CAAC,EAAE,GAAG,EAAE,CAAC,EAAE,GAAG,EAAE,CAAC,EAAE,GAAG,EAAC,EAAE,cAAc;IACxC,EAAC,CAAC,EAAE,GAAG,EAAE,CAAC,EAAE,GAAG,EAAE,CAAC,EAAE,GAAG,EAAC,EAAE,UAAU;IACpC,EAAC,CAAC,EAAE,GAAG,EAAE,CAAC,EAAE,GAAG,EAAE,CAAC,EAAE,GAAG,EAAC,EAAE,WAAW;CAC5B,CAAC,CAAC;AAEZ,+EAA+E;AAC/E,MAAM,UAAU,YAAY,CAAC,KAAa;IACzC,MAAM,CAAC,GAAG,aAAa,CAAC,KAAK,CAAC,CAAC;IAC/B,IAAI,CAAC,KAAK,SAAS,EAAE,CAAC;QACrB,MAAM,IAAI,UAAU,CAAC,iBAAiB,KAAK,qBAAqB,CAAC,CAAC;IACnE,CAAC;IACD,OAAO,CAAC,CAAC;AACV,CAAC"}

package/dist/engine/gfx/png.d.ts

@@ -0,0 +1,31 @@
+/**
+ * A tiny, dependency-FREE, deterministic PNG encoder for the `gfx render` JUDGE
+ * surface. Encodes an RGB pixel buffer into a valid 8-bit truecolour PNG using
+ * hand-rolled CRC32, Adler32, and STORED (uncompressed) zlib deflate blocks.
+ *
+ * Why hand-rolled + stored blocks (recorded as a `gfx render` encoder choice):
+ * the eyes-loop is meant to stay dependency-light (shrinko-free, no npm PNG lib),
+ * and `gfx render` output is tiny (~256x256), so compression buys nothing worth a
+ * dependency. STORED deflate blocks keep the encoder ~a page of code AND make the
+ * output BYTE-DETERMINISTIC (no compressor heuristics), which is exactly what the
+ * pixel-byte tests assert against. A standard PNG decoder reads stored blocks
+ * identically to compressed ones, so the file is a normal, viewable PNG.
+ *
+ * This module knows nothing about PICO-8: it takes raw RGB and dimensions. The
+ * palette mapping + upscale live in `render.ts`.
+ */
+/** A raw RGB image: `width * height * 3` bytes, row-major, no padding. */
+export interface RgbImage {
+    readonly width: number;
+    readonly height: number;
+    /** `rgb[(y * width + x) * 3 + {0,1,2}]` = R, G, B (0..255) for pixel (x, y). */
+    readonly rgb: Uint8Array;
+}
+/**
+ * Encodes an {@link RgbImage} into a complete PNG file (signature + IHDR + IDAT +
+ * IEND) as a `Uint8Array`. 8-bit RGB truecolour (colour type 2), no interlace,
+ * each scanline prefixed with filter byte 0 (None) so the pixel bytes appear
+ * verbatim in the IDAT payload.
+ */
+export declare function encodePng(image: RgbImage): Uint8Array;
+//# sourceMappingURL=png.d.ts.map

package/dist/engine/gfx/png.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"png.d.ts","sourceRoot":"","sources":["../../../src/engine/gfx/png.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,0EAA0E;AAC1E,MAAM,WAAW,QAAQ;IACxB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,gFAAgF;IAChF,QAAQ,CAAC,GAAG,EAAE,UAAU,CAAC;CACzB;AAMD;;;;;GAKG;AACH,wBAAgB,SAAS,CAAC,KAAK,EAAE,QAAQ,GAAG,UAAU,CA+CrD"}

package/dist/engine/gfx/png.js

@@ -0,0 +1,165 @@
+/**
+ * A tiny, dependency-FREE, deterministic PNG encoder for the `gfx render` JUDGE
+ * surface. Encodes an RGB pixel buffer into a valid 8-bit truecolour PNG using
+ * hand-rolled CRC32, Adler32, and STORED (uncompressed) zlib deflate blocks.
+ *
+ * Why hand-rolled + stored blocks (recorded as a `gfx render` encoder choice):
+ * the eyes-loop is meant to stay dependency-light (shrinko-free, no npm PNG lib),
+ * and `gfx render` output is tiny (~256x256), so compression buys nothing worth a
+ * dependency. STORED deflate blocks keep the encoder ~a page of code AND make the
+ * output BYTE-DETERMINISTIC (no compressor heuristics), which is exactly what the
+ * pixel-byte tests assert against. A standard PNG decoder reads stored blocks
+ * identically to compressed ones, so the file is a normal, viewable PNG.
+ *
+ * This module knows nothing about PICO-8: it takes raw RGB and dimensions. The
+ * palette mapping + upscale live in `render.ts`.
+ */
+const PNG_SIGNATURE = Uint8Array.from([
+    0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a,
+]);
+/**
+ * Encodes an {@link RgbImage} into a complete PNG file (signature + IHDR + IDAT +
+ * IEND) as a `Uint8Array`. 8-bit RGB truecolour (colour type 2), no interlace,
+ * each scanline prefixed with filter byte 0 (None) so the pixel bytes appear
+ * verbatim in the IDAT payload.
+ */
+export function encodePng(image) {
+    const { width, height, rgb } = image;
+    if (!Number.isInteger(width) ||
+        !Number.isInteger(height) ||
+        width <= 0 ||
+        height <= 0) {
+        throw new RangeError(`PNG dimensions must be positive integers, got ${width}x${height}`);
+    }
+    if (rgb.length !== width * height * 3) {
+        throw new RangeError(`RGB buffer length ${rgb.length} does not match ${width}x${height}x3 = ${width * height * 3}`);
+    }
+    // Raw scanlines: each row is one filter byte (0 = None) then width*3 RGB bytes.
+    const stride = width * 3;
+    const raw = new Uint8Array(height * (stride + 1));
+    for (let y = 0; y < height; y++) {
+        const dst = y * (stride + 1);
+        raw[dst] = 0; // filter type None
+        raw.set(rgb.subarray(y * stride, y * stride + stride), dst + 1);
+    }
+    const ihdr = buildIhdr(width, height);
+    const idat = zlibStore(raw);
+    const chunks = [
+        chunk('IHDR', ihdr),
+        chunk('IDAT', idat),
+        chunk('IEND', new Uint8Array(0)),
+    ];
+    let total = PNG_SIGNATURE.length;
+    for (const c of chunks)
+        total += c.length;
+    const out = new Uint8Array(total);
+    let off = 0;
+    out.set(PNG_SIGNATURE, off);
+    off += PNG_SIGNATURE.length;
+    for (const c of chunks) {
+        out.set(c, off);
+        off += c.length;
+    }
+    return out;
+}
+/** The 13-byte IHDR data: width, height, bit-depth 8, colour type 2 (RGB), etc. */
+function buildIhdr(width, height) {
+    const d = new Uint8Array(13);
+    writeUint32(d, 0, width);
+    writeUint32(d, 4, height);
+    d[8] = 8; // bit depth
+    d[9] = 2; // colour type: truecolour RGB
+    d[10] = 0; // compression: deflate
+    d[11] = 0; // filter: adaptive (only filter 0 used per scanline)
+    d[12] = 0; // interlace: none
+    return d;
+}
+/** Wraps chunk `data` with its 4-byte length, 4-byte type, and 4-byte CRC32. */
+function chunk(type, data) {
+    const typeBytes = Uint8Array.from([
+        type.charCodeAt(0),
+        type.charCodeAt(1),
+        type.charCodeAt(2),
+        type.charCodeAt(3),
+    ]);
+    const out = new Uint8Array(4 + 4 + data.length + 4);
+    writeUint32(out, 0, data.length);
+    out.set(typeBytes, 4);
+    out.set(data, 8);
+    // CRC covers the type + data (not the length).
+    const crcInput = new Uint8Array(4 + data.length);
+    crcInput.set(typeBytes, 0);
+    crcInput.set(data, 4);
+    writeUint32(out, 8 + data.length, crc32(crcInput));
+    return out;
+}
+/**
+ * Wraps `data` in a zlib stream (RFC 1950) using DEFLATE STORED blocks (RFC 1951,
+ * BTYPE=00): a 2-byte zlib header, one or more stored blocks (each ≤ 65535
+ * bytes), and a 4-byte big-endian Adler32 of the uncompressed data.
+ */
+function zlibStore(data) {
+    const MAX_BLOCK = 0xffff;
+    const blockCount = Math.max(1, Math.ceil(data.length / MAX_BLOCK));
+    // 2 header bytes + per-block (1 BFINAL/BTYPE + 2 LEN + 2 NLEN) + data + 4 adler.
+    const out = new Uint8Array(2 + blockCount * 5 + data.length + 4);
+    let off = 0;
+    // zlib header: CMF=0x78 (deflate, 32K window), FLG=0x01 so (CMF*256+FLG)%31==0.
+    out[off++] = 0x78;
+    out[off++] = 0x01;
+    let pos = 0;
+    for (let b = 0; b < blockCount; b++) {
+        const len = Math.min(MAX_BLOCK, data.length - pos);
+        const isFinal = b === blockCount - 1;
+        out[off++] = isFinal ? 1 : 0; // BFINAL bit, BTYPE=00 (stored)
+        // LEN then NLEN, both little-endian.
+        out[off++] = len & 0xff;
+        out[off++] = (len >> 8) & 0xff;
+        const nlen = ~len & 0xffff;
+        out[off++] = nlen & 0xff;
+        out[off++] = (nlen >> 8) & 0xff;
+        out.set(data.subarray(pos, pos + len), off);
+        off += len;
+        pos += len;
+    }
+    writeUint32(out, off, adler32(data));
+    return out;
+}
+function writeUint32(buf, offset, value) {
+    buf[offset] = (value >>> 24) & 0xff;
+    buf[offset + 1] = (value >>> 16) & 0xff;
+    buf[offset + 2] = (value >>> 8) & 0xff;
+    buf[offset + 3] = value & 0xff;
+}
+// --- CRC32 (PNG polynomial 0xedb88320) ---
+const CRC_TABLE = buildCrcTable();
+function buildCrcTable() {
+    const table = 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;
+        }
+        table[n] = c >>> 0;
+    }
+    return table;
+}
+function crc32(data) {
+    let crc = 0xffffffff;
+    for (let i = 0; i < data.length; i++) {
+        crc = CRC_TABLE[(crc ^ (data[i] ?? 0)) & 0xff] ^ (crc >>> 8);
+    }
+    return (crc ^ 0xffffffff) >>> 0;
+}
+// --- Adler32 (RFC 1950) ---
+function adler32(data) {
+    const MOD = 65521;
+    let a = 1;
+    let b = 0;
+    for (let i = 0; i < data.length; i++) {
+        a = (a + (data[i] ?? 0)) % MOD;
+        b = (b + a) % MOD;
+    }
+    return ((b << 16) | a) >>> 0;
+}
+//# sourceMappingURL=png.js.map

package/dist/engine/gfx/png.js.map

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

package/dist/engine/gfx/render.d.ts

@@ -0,0 +1,42 @@
+import { type GfxSheet } from '../cart/index.js';
+import { type RgbImage } from './png.js';
+/**
+ * The `gfx render` JUDGE surface: turn a sprite (or the whole spritesheet) into a
+ * nearest-neighbour-upscaled, palette-accurate PNG a multimodal agent can LOOK at.
+ *
+ * The char grid (`gfx show`/`gfx set`) is the exact EDIT surface, but an LLM reads
+ * serialized hex poorly for gestalt/colour (the SVG parallel: models generate
+ * structured visual source well but read it back poorly). So this renders the
+ * ACTUAL pixels, upscaled enough to be viewable, with each colour index mapped to
+ * its exact PICO-8 palette RGB (single source of truth: {@link paletteColor}).
+ *
+ * Upscale is NEAREST-NEIGHBOUR (each source pixel becomes a `scale`x`scale` block
+ * of identical RGB) so the pixel-art stays crisp and the output bytes are
+ * deterministic. The scale is chosen so the longer edge lands near ~256px:
+ * - a single 8x8 sprite → scale 32 → 256x256 (see {@link SPRITE_RENDER_SCALE}).
+ * - the 128x128 sheet    → scale 2  → 256x256 (see {@link SHEET_RENDER_SCALE}).
+ */
+/** Nearest-neighbour scale for a single 8x8 sprite: 8 * 32 = 256px. */
+export declare const SPRITE_RENDER_SCALE = 32;
+/** Nearest-neighbour scale for the 128x128 spritesheet: 128 * 2 = 256px. */
+export declare const SHEET_RENDER_SCALE = 2;
+/** The target viewable edge length both scales aim for (~256px). */
+export declare const RENDER_TARGET_PX = 256;
+/**
+ * Renders one sprite (0..255) to a PNG buffer: its 8x8 pixels, each mapped to its
+ * palette RGB, nearest-neighbour upscaled by {@link SPRITE_RENDER_SCALE}.
+ */
+export declare function renderSpritePng(sheet: GfxSheet, n: number): Uint8Array;
+/**
+ * Renders the whole 128x128 spritesheet to a PNG buffer: every pixel mapped to
+ * its palette RGB, nearest-neighbour upscaled by {@link SHEET_RENDER_SCALE}.
+ */
+export declare function renderSheetPng(sheet: GfxSheet): Uint8Array;
+/**
+ * Builds an upscaled {@link RgbImage} from a source of colour indices. Each
+ * source pixel (`getIndex(x, y)`) is mapped to its palette RGB and painted as a
+ * `scale`x`scale` block (nearest-neighbour), producing a `(srcW*scale)` x
+ * `(srcH*scale)` RGB buffer.
+ */
+export declare function upscale(srcWidth: number, srcHeight: number, getIndex: (x: number, y: number) => number, scale: number): RgbImage;
+//# sourceMappingURL=render.d.ts.map