picopilot 0.0.0 → 0.1.1

package/src/engine/gfx/png.ts

@@ -0,0 +1,196 @@
+/**
+ * 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;
+}
+
+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: RgbImage): Uint8Array {
+	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: number, height: number): Uint8Array {
+	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: string, data: Uint8Array): Uint8Array {
+	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: Uint8Array): Uint8Array {
+	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: Uint8Array, offset: number, value: number): void {
+	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(): Uint32Array {
+	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: Uint8Array): number {
+	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: Uint8Array): number {
+	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;
+}

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

@@ -0,0 +1,180 @@
+import {inflateSync} from 'node:zlib';
+import {describe, expect, it} from 'vitest';
+
+import {GfxSheet} from '../cart/index.js';
+import {PICO8_PALETTE} from './palette.js';
+import type {RgbImage} from './png.js';
+import {
+	renderSheetPng,
+	renderSpritePng,
+	SHEET_RENDER_SCALE,
+	SPRITE_RENDER_SCALE,
+	upscale,
+} from './render.js';
+
+/** Decodes a PNG (via node's independent inflate) into a raw RGB image. */
+function decodePng(bytes: Uint8Array): RgbImage {
+	let off = 8;
+	let width = 0;
+	let height = 0;
+	const idatParts: Buffer[] = [];
+	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);
+		} else if (type === 'IDAT') {
+			idatParts.push(Buffer.from(data));
+		}
+		off += 12 + len;
+		if (type === 'IEND') break;
+	}
+	const raw = new Uint8Array(inflateSync(Buffer.concat(idatParts)));
+	const stride = width * 3;
+	const rgb = new Uint8Array(width * height * 3);
+	for (let y = 0; y < height; y++) {
+		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]!];
+}
+
+function rgbOf(index: number): [number, number, number] {
+	const c = PICO8_PALETTE[index]!;
+	return [c.r, c.g, c.b];
+}
+
+/** An 8x8 nibble grid from a generator. */
+function makeGrid(fn: (r: number, c: number) => number): number[][] {
+	return Array.from({length: 8}, (_, r) =>
+		Array.from({length: 8}, (_, c) => fn(r, c)),
+	);
+}
+
+describe('upscale (nearest-neighbour, palette-accurate)', () => {
+	it('paints each source pixel as a scale x scale block of its palette RGB', () => {
+		// 2x1 source: index 8 (red) then index 12 (blue), scale 4.
+		const img = upscale(2, 1, (x) => (x === 0 ? 8 : 12), 4);
+		expect(img.width).toBe(8);
+		expect(img.height).toBe(4);
+		// The whole left 4x4 block is red; the whole right 4x4 block is blue.
+		for (let y = 0; y < 4; y++) {
+			for (let x = 0; x < 4; x++) expect(pixelAt(img, x, y)).toEqual(rgbOf(8));
+			for (let x = 4; x < 8; x++) expect(pixelAt(img, x, y)).toEqual(rgbOf(12));
+		}
+	});
+});
+
+describe('renderSpritePng: deterministic palette-accurate pixel bytes', () => {
+	it('upscales an 8x8 sprite to 256x256 with the exact palette RGB per index', () => {
+		// Paint sprite 0 so pixel (c, r) has colour index (r*8 + c) % 16 — every
+		// index appears, at a known position.
+		const painted = makeGrid((r, c) => (r * 8 + c) % 16);
+		const sheet = GfxSheet.fromBody(undefined);
+		sheet.setSprite(0, painted);
+
+		const png = renderSpritePng(sheet, 0);
+		const img = decodePng(png);
+		expect(img.width).toBe(8 * SPRITE_RENDER_SCALE);
+		expect(img.height).toBe(8 * SPRITE_RENDER_SCALE);
+		expect(img.width).toBe(256);
+
+		// Assert the PIXEL BYTES: the centre of each source-pixel block is exactly
+		// that index's palette RGB.
+		const s = SPRITE_RENDER_SCALE;
+		for (let r = 0; r < 8; r++) {
+			for (let c = 0; c < 8; c++) {
+				const index = (r * 8 + c) % 16;
+				const cx = c * s + (s >> 1);
+				const cy = r * s + (s >> 1);
+				expect(pixelAt(img, cx, cy)).toEqual(rgbOf(index));
+			}
+		}
+	});
+
+	it('renders a non-zero sprite (e.g. 5) from its own origin, not sprite 0', () => {
+		const sheet = GfxSheet.fromBody(undefined);
+		sheet.setSprite(
+			0,
+			makeGrid(() => 8),
+		); // sprite 0 is all red — must NOT leak in
+		sheet.setSprite(
+			5,
+			makeGrid(() => 11),
+		); // sprite 5 is all green
+
+		const img = decodePng(renderSpritePng(sheet, 5));
+		// Every pixel is green (index 11), proving sprite 5's origin was used.
+		for (let y = 0; y < img.height; y += 37) {
+			for (let x = 0; x < img.width; x += 37) {
+				expect(pixelAt(img, x, y)).toEqual(rgbOf(11));
+			}
+		}
+	});
+
+	it('is byte-deterministic for the same sprite', () => {
+		const sheet = GfxSheet.fromBody(undefined);
+		sheet.setSprite(
+			0,
+			makeGrid((r, c) => (r + c) % 16),
+		);
+		const a = renderSpritePng(sheet, 0);
+		const b = renderSpritePng(sheet, 0);
+		expect(Array.from(a)).toEqual(Array.from(b));
+	});
+});
+
+describe('renderSheetPng: the whole 128x128 spritesheet', () => {
+	it('upscales the 128x128 sheet to 256x256 with palette-accurate pixels', () => {
+		const sheet = GfxSheet.fromBody(undefined);
+		// Distinct colours in distinct sprites, so positions are checkable.
+		sheet.setSprite(
+			0,
+			makeGrid(() => 8),
+		); // top-left 8x8 (upscaled) = red
+		sheet.setSprite(
+			15,
+			makeGrid(() => 12),
+		); // top-right sprite = blue
+		sheet.setSprite(
+			255,
+			makeGrid(() => 10),
+		); // bottom-right sprite = yellow
+
+		const img = decodePng(renderSheetPng(sheet));
+		expect(img.width).toBe(128 * SHEET_RENDER_SCALE);
+		expect(img.height).toBe(128 * SHEET_RENDER_SCALE);
+		expect(img.width).toBe(256);
+
+		const s = SHEET_RENDER_SCALE;
+		// sprite 0 occupies source pixels [0,8)x[0,8) → dest [0,16)x[0,16).
+		expect(pixelAt(img, 0, 0)).toEqual(rgbOf(8));
+		expect(pixelAt(img, 8 * s - 1, 8 * s - 1)).toEqual(rgbOf(8));
+		// sprite 15 is source cols [120,128) row [0,8) → dest x [240,256).
+		expect(pixelAt(img, 120 * s, 0)).toEqual(rgbOf(12));
+		// sprite 255 is the bottom-right 8x8 → dest bottom-right corner.
+		expect(pixelAt(img, img.width - 1, img.height - 1)).toEqual(rgbOf(10));
+		// An untouched pixel (sprite 1 region) is index 0 = black.
+		expect(pixelAt(img, 8 * s, 0)).toEqual(rgbOf(0));
+	});
+});

package/src/engine/gfx/render.ts

@@ -0,0 +1,106 @@
+import {
+	GFX_HEIGHT,
+	GFX_WIDTH,
+	type GfxSheet,
+	SPRITE_SIZE,
+	spriteOrigin,
+} from '../cart/index.js';
+import {paletteColor} from './palette.js';
+import {encodePng, 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 const SPRITE_RENDER_SCALE = 32;
+
+/** Nearest-neighbour scale for the 128x128 spritesheet: 128 * 2 = 256px. */
+export const SHEET_RENDER_SCALE = 2;
+
+/** The target viewable edge length both scales aim for (~256px). */
+export 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 function renderSpritePng(sheet: GfxSheet, n: number): Uint8Array {
+	const {x0, y0} = spriteOrigin(n);
+	return encodePng(
+		upscale(
+			SPRITE_SIZE,
+			SPRITE_SIZE,
+			(x, y) => sheet.getPixel(x0 + x, y0 + y),
+			SPRITE_RENDER_SCALE,
+		),
+	);
+}
+
+/**
+ * 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 function renderSheetPng(sheet: GfxSheet): Uint8Array {
+	return encodePng(
+		upscale(
+			GFX_WIDTH,
+			GFX_HEIGHT,
+			(x, y) => sheet.getPixel(x, y),
+			SHEET_RENDER_SCALE,
+		),
+	);
+}
+
+/**
+ * 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 function upscale(
+	srcWidth: number,
+	srcHeight: number,
+	getIndex: (x: number, y: number) => number,
+	scale: number,
+): RgbImage {
+	if (!Number.isInteger(scale) || scale < 1) {
+		throw new RangeError(
+			`upscale factor must be a positive integer, got ${scale}`,
+		);
+	}
+	const width = srcWidth * scale;
+	const height = srcHeight * scale;
+	const rgb = new Uint8Array(width * height * 3);
+
+	for (let sy = 0; sy < srcHeight; sy++) {
+		for (let sx = 0; sx < srcWidth; sx++) {
+			const {r, g, b} = paletteColor(getIndex(sx, sy));
+			// Paint the scale x scale destination block for this source pixel.
+			for (let dy = 0; dy < scale; dy++) {
+				const y = sy * scale + dy;
+				for (let dx = 0; dx < scale; dx++) {
+					const x = sx * scale + dx;
+					const off = (y * width + x) * 3;
+					rgb[off] = r;
+					rgb[off + 1] = g;
+					rgb[off + 2] = b;
+				}
+			}
+		}
+	}
+	return {width, height, rgb};
+}

package/src/engine/index.ts

@@ -0,0 +1,21 @@
+/**
+ * The picopilot engine layer: pure codecs and external-tool adapters, kept
+ * separate from the incur command layer (`src/commands/`) so commands stay thin
+ * and the engine stays independently testable.
+ *
+ * Modules (one per seam; more added by later tasks):
+ *
+ * - `engine/cart`:    the `.p8` cart model: parse sections, addressable
+ *                      gfx/map regions, byte-identical serialize (this seam).
+ * - `engine/gfx`:     TS codec: `__gfx__` hex to/from char grid, and hex to PNG.
+ * - `engine/audio`:   TS codec: picopilot-MML to `__sfx__`, patterns to `__music__`.
+ * - `engine/shrinko`: adapter shelling out to the external `shrinko8` tool
+ *                      (token count, lint, minify, p8/lua, spritesheet PNG).
+ * - `engine/pico8`:   headless run + capture + export (needs the PICO-8 binary).
+ *
+ * Later tasks re-export from here without restructuring.
+ */
+export * from './audio/index.js';
+export * from './cart/index.js';
+export * from './pico8/index.js';
+export * from './shrinko/index.js';