picopilot 0.0.0 → 0.1.0

package/src/engine/gfx/label.ts

@@ -0,0 +1,229 @@
+/**
+ * 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 {
+	constructor(
+		readonly code:
+			'not-a-png' | 'unsupported-png' | 'wrong-size' | 'truncated-png',
+		message: string,
+	) {
+		super(message);
+		this.name = 'LabelError';
+	}
+}
+
+const PNG_SIGNATURE = [0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a];
+
+interface DecodedPng {
+	readonly width: number;
+	readonly height: number;
+	/** Row-major RGBA, 4 bytes per pixel. */
+	readonly rgba: Uint8Array;
+}
+
+/**
+ * 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: Uint8Array): DecodedPng {
+	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: Uint8Array[] = [];
+
+	const readU32 = (p: number): number =>
+		((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: Buffer;
+	try {
+		raw = inflateSync(compressed);
+	} catch (e) {
+		throw new LabelError(
+			'truncated-png',
+			`could not inflate PNG image data: ${(e as Error).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: number, b: number, c: number): number {
+	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: number, g: number, b: number): number {
+	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: Uint8Array): string {
+	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: string[] = [];
+	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`;
+}

package/src/engine/gfx/overlap.test.ts

@@ -0,0 +1,71 @@
+import {describe, expect, it} from 'vitest';
+
+import {GfxSheet} from '../cart/index.js';
+import {decideOverlap, spriteHasData} from './overlap.js';
+
+/** A GfxSheet whose sprite `n` is painted non-zero (data at risk in the shared bank). */
+function sheetWithSpriteData(n: number): GfxSheet {
+	const sheet = GfxSheet.fromBody(undefined);
+	// A single non-zero pixel is enough to mean "the shared region holds data".
+	sheet.setPixel(...spritePixel(n), 8);
+	return sheet;
+}
+
+/** A pixel coordinate inside sprite `n` (its top-left corner). */
+function spritePixel(n: number): [number, number] {
+	const x0 = (n % 16) * 8;
+	const y0 = Math.floor(n / 16) * 8;
+	return [x0, y0];
+}
+
+describe('gfx overlap: spriteHasData reads the target sprite own __gfx__ pixels', () => {
+	it('is false for an all-zero sprite', () => {
+		const sheet = GfxSheet.fromBody(undefined);
+		expect(spriteHasData(sheet, 200)).toBe(false);
+	});
+	it('is true once any pixel is non-zero', () => {
+		const sheet = sheetWithSpriteData(200);
+		expect(spriteHasData(sheet, 200)).toBe(true);
+	});
+});
+
+describe('gfx overlap: decideOverlap branches (ADR-0004 smart-refuse)', () => {
+	it('a base-bank sprite (0..127) is always allowed (no overlap possible)', () => {
+		const sheet = sheetWithSpriteData(10);
+		// Even with data present, a base-bank sprite aliases nothing.
+		expect(decideOverlap(sheet, 10, false)).toEqual({kind: 'allowed'});
+	});
+
+	it('a shared-bank sprite with all-zero pixels is allowed-shared (empty)', () => {
+		const sheet = GfxSheet.fromBody(undefined);
+		expect(decideOverlap(sheet, 130, false)).toEqual({
+			kind: 'allowed-shared',
+			reason: 'empty',
+		});
+	});
+
+	it('a shared-bank sprite with data + authorised is allowed-shared (authorised)', () => {
+		const sheet = sheetWithSpriteData(130);
+		expect(decideOverlap(sheet, 130, true)).toEqual({
+			kind: 'allowed-shared',
+			reason: 'authorised',
+		});
+	});
+
+	it('a shared-bank sprite with data + NOT authorised is refused (the data-loss corner)', () => {
+		const sheet = sheetWithSpriteData(130);
+		const decision = decideOverlap(sheet, 130, false);
+		expect(decision.kind).toBe('refused');
+		if (decision.kind === 'refused') expect(decision.nonZeroPixels).toBe(1);
+	});
+
+	it('sprite 128 (first shared) and 255 (last) both alias the shared bank', () => {
+		for (const n of [128, 255]) {
+			const sheet = sheetWithSpriteData(n);
+			expect(decideOverlap(sheet, n, false).kind).toBe('refused');
+		}
+		// 127 (last base) does NOT.
+		const base = sheetWithSpriteData(127);
+		expect(decideOverlap(base, 127, false).kind).toBe('allowed');
+	});
+});

package/src/engine/gfx/overlap.ts

@@ -0,0 +1,66 @@
+import {type GfxSheet, 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: GfxSheet, n: number): boolean {
+	const grid = sheet.getSprite(n);
+	for (const row of grid) {
+		for (const px of row) if (px !== 0) return true;
+	}
+	return false;
+}
+
+/** 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 function decideOverlap(
+	sheet: GfxSheet,
+	n: number,
+	authorised: boolean,
+): OverlapDecision {
+	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: GfxSheet, n: number): number {
+	let count = 0;
+	for (const row of sheet.getSprite(n)) {
+		for (const px of row) if (px !== 0) count++;
+	}
+	return count;
+}

package/src/engine/gfx/palette.test.ts

@@ -0,0 +1,35 @@
+import {describe, expect, it} from 'vitest';
+
+import {PICO8_PALETTE, paletteColor} from './palette.js';
+
+describe('PICO-8 palette (single source of truth)', () => {
+	it('has exactly 16 entries', () => {
+		expect(PICO8_PALETTE).toHaveLength(16);
+	});
+
+	it('matches the fixed PICO-8 constants from the findings table', () => {
+		// A representative spot-check against work/notes/findings/pico8-api-reference.md:
+		// do NOT re-invent these; they are the load-bearing render source of truth.
+		expect(paletteColor(0)).toEqual({r: 0, g: 0, b: 0}); // black
+		expect(paletteColor(7)).toEqual({r: 255, g: 241, b: 232}); // white
+		expect(paletteColor(8)).toEqual({r: 255, g: 0, b: 77}); // red
+		expect(paletteColor(11)).toEqual({r: 0, g: 228, b: 54}); // green
+		expect(paletteColor(12)).toEqual({r: 41, g: 173, b: 255}); // blue
+		expect(paletteColor(15)).toEqual({r: 255, g: 204, b: 170}); // peach
+	});
+
+	it('every entry is a valid 0..255 RGB triple', () => {
+		for (const c of PICO8_PALETTE) {
+			for (const v of [c.r, c.g, c.b]) {
+				expect(Number.isInteger(v)).toBe(true);
+				expect(v).toBeGreaterThanOrEqual(0);
+				expect(v).toBeLessThanOrEqual(255);
+			}
+		}
+	});
+
+	it('throws for an out-of-range index', () => {
+		expect(() => paletteColor(-1)).toThrow();
+		expect(() => paletteColor(16)).toThrow();
+	});
+});

package/src/engine/gfx/palette.ts

@@ -0,0 +1,54 @@
+/**
+ * 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 const PICO8_PALETTE: readonly PaletteColor[] = 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
+] as const);
+
+/** The RGB triple for colour index 0..15. Throws for an out-of-range index. */
+export function paletteColor(index: number): PaletteColor {
+	const c = PICO8_PALETTE[index];
+	if (c === undefined) {
+		throw new RangeError(`palette index ${index} out of range 0..15`);
+	}
+	return c;
+}

package/src/engine/gfx/png.test.ts

@@ -0,0 +1,111 @@
+import {inflateSync} from 'node:zlib';
+import {describe, expect, it} from 'vitest';
+
+import {encodePng, type RgbImage} from './png.js';
+
+/**
+ * Decodes the PNG structure enough to recover the raw RGB pixels, so the tests
+ * assert against a REAL PNG round-trip (not the encoder's own internals). Uses
+ * node's `zlib.inflateSync` as an INDEPENDENT decompressor: it must accept the
+ * hand-rolled stored-block zlib stream, proving the file is standards-valid.
+ */
+function decodePng(bytes: Uint8Array): RgbImage {
+	const sig = [0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a];
+	for (let i = 0; i < sig.length; i++) {
+		expect(bytes[i]).toBe(sig[i]);
+	}
+
+	let off = 8;
+	let width = 0;
+	let height = 0;
+	const idatParts: Uint8Array[] = [];
+	const view = new DataView(bytes.buffer, bytes.byteOffset, bytes.byteLength);
+
+	while (off < bytes.length) {
+		const len = view.getUint32(off);
+		const type = String.fromCharCode(
+			bytes[off + 4]!,
+			bytes[off + 5]!,
+			bytes[off + 6]!,
+			bytes[off + 7]!,
+		);
+		const data = bytes.subarray(off + 8, off + 8 + len);
+		if (type === 'IHDR') {
+			const dv = new DataView(data.buffer, data.byteOffset, data.byteLength);
+			width = dv.getUint32(0);
+			height = dv.getUint32(4);
+			expect(data[8]).toBe(8); // bit depth
+			expect(data[9]).toBe(2); // colour type RGB
+		} else if (type === 'IDAT') {
+			idatParts.push(data);
+		}
+		off += 12 + len; // length(4) + type(4) + data + crc(4)
+		if (type === 'IEND') break;
+	}
+
+	const idat = Buffer.concat(idatParts.map((p) => Buffer.from(p)));
+	const raw = new Uint8Array(inflateSync(idat));
+
+	// Strip the per-scanline filter byte (all filter type 0 = None).
+	const stride = width * 3;
+	const rgb = new Uint8Array(width * height * 3);
+	for (let y = 0; y < height; y++) {
+		expect(raw[y * (stride + 1)]).toBe(0); // filter None
+		rgb.set(
+			raw.subarray(y * (stride + 1) + 1, y * (stride + 1) + 1 + stride),
+			y * stride,
+		);
+	}
+	return {width, height, rgb};
+}
+
+function pixelAt(
+	img: RgbImage,
+	x: number,
+	y: number,
+): [number, number, number] {
+	const off = (y * img.width + x) * 3;
+	return [img.rgb[off]!, img.rgb[off + 1]!, img.rgb[off + 2]!];
+}
+
+describe('png encoder', () => {
+	it('encodes a 2x2 RGB image that a standard inflate decoder reads back exactly', () => {
+		const rgb = Uint8Array.from([
+			255, 0, 0, /* red   */ 0, 255, 0 /* green */, 0, 0, 255, /* blue  */ 255,
+			255, 255 /* white */,
+		]);
+		const png = encodePng({width: 2, height: 2, rgb});
+		const decoded = decodePng(png);
+		expect(decoded.width).toBe(2);
+		expect(decoded.height).toBe(2);
+		expect(pixelAt(decoded, 0, 0)).toEqual([255, 0, 0]);
+		expect(pixelAt(decoded, 1, 0)).toEqual([0, 255, 0]);
+		expect(pixelAt(decoded, 0, 1)).toEqual([0, 0, 255]);
+		expect(pixelAt(decoded, 1, 1)).toEqual([255, 255, 255]);
+		expect(Array.from(decoded.rgb)).toEqual(Array.from(rgb));
+	});
+
+	it('is deterministic: the same input yields byte-identical output', () => {
+		const rgb = Uint8Array.from([1, 2, 3, 4, 5, 6]);
+		const a = encodePng({width: 2, height: 1, rgb});
+		const b = encodePng({width: 2, height: 1, rgb});
+		expect(Array.from(a)).toEqual(Array.from(b));
+	});
+
+	it('handles a buffer larger than one stored block (>65535 bytes)', () => {
+		// 200x200 RGB = 120000 bytes of pixels + filter bytes > 65535 → 2+ blocks.
+		const width = 200;
+		const height = 200;
+		const rgb = new Uint8Array(width * height * 3);
+		for (let i = 0; i < rgb.length; i++) rgb[i] = i % 256;
+		const png = encodePng({width, height, rgb});
+		const decoded = decodePng(png);
+		expect(Array.from(decoded.rgb)).toEqual(Array.from(rgb));
+	});
+
+	it('rejects a mismatched buffer length', () => {
+		expect(() =>
+			encodePng({width: 2, height: 2, rgb: new Uint8Array(3)}),
+		).toThrow();
+	});
+});