picopilot 0.0.0 → 0.1.0

package/src/engine/config/config.ts

@@ -0,0 +1,115 @@
+import {z} from 'incur';
+
+/**
+ * The per-cart `picopilot.json` config, US #10.
+ *
+ * picopilot's config is incur's built-in `config: { files: ['picopilot.json'] }`
+ * mechanism (declared in `createCli`): a JSON file whose values become option
+ * DEFAULTS for the matching command, with precedence `argv > config > zod
+ * defaults`. incur keys config by command path, a command's options live under
+ * `commands.<group>.commands.<name>.options.<key>`, so a policy an agent sets
+ * once (like `allowMapOverlap`) is stored where the command that reads it looks.
+ *
+ * This module is the single source of truth for the config SHAPE: `init`
+ * scaffolds a file from {@link defaultConfigFile}, and the later `gfx set`
+ * command reads `allowMapOverlap` through incur's config layer (its own
+ * `--allow-map-overlap` option default). Keeping the shape here, rather than
+ * inlining a blob in `init`, means the scaffolded file and the reader cannot
+ * drift.
+ */
+
+/**
+ * The `gfx set` options that `picopilot.json` may set as defaults.
+ *
+ * `allowMapOverlap` authorises `gfx set` to write sprites 128-255 even when the
+ * overlapping `__map__` rows hold real tiles (see ADR-0004). It is a rarely /
+ * once-set PROJECT setting: OFF by default (the smart-refuse is the safety), so
+ * a fresh cart never silently loses map data. The matching invocation flag is
+ * `--allow-map-overlap`; `argv > config > default` means the flag always wins.
+ */
+export const GfxSetOptions = z.object({
+	allowMapOverlap: z
+		.boolean()
+		.default(false)
+		.describe(
+			'Authorise `gfx set` to overwrite __map__ tiles that alias sprites 128-255 (ADR-0004). Off by default; the smart-refuse is the safety.',
+		),
+});
+
+/**
+ * The full `picopilot.json` document shape, mirroring incur's config tree
+ * (`commands.<path>.options`). Only the keys picopilot actually reads are
+ * modelled; the schema is `.strict()`-free on purpose so a human/agent may add
+ * config for commands this version does not yet know about without a parse
+ * failure.
+ */
+export const PicopilotConfig = z.object({
+	$schema: z.string().optional().describe('JSON Schema reference (optional).'),
+	commands: z
+		.object({
+			gfx: z
+				.object({
+					commands: z
+						.object({
+							set: z
+								.object({
+									options: GfxSetOptions.partial().optional(),
+								})
+								.optional(),
+						})
+						.optional(),
+				})
+				.optional(),
+		})
+		.optional()
+		.describe(
+			'Per-command option defaults, keyed by command path (incur config layout).',
+		),
+});
+
+export type PicopilotConfig = z.infer<typeof PicopilotConfig>;
+
+/**
+ * The default `picopilot.json` written by `init`: valid, minimal, and
+ * self-documenting via `$schema`. It sets `allowMapOverlap: false` explicitly
+ * so the one policy knob an agent is likely to flip is visible in the file (an
+ * agent is FREE to read/write this to match a higher-level instruction, US #10)
+ * rather than hidden behind a zod default.
+ */
+export const defaultConfig: PicopilotConfig = {
+	$schema: './picopilot.schema.json',
+	commands: {
+		gfx: {
+			commands: {
+				set: {
+					options: {
+						allowMapOverlap: false,
+					},
+				},
+			},
+		},
+	},
+};
+
+/** The default `picopilot.json` serialized as it is written to disk (trailing newline). */
+export function defaultConfigFile(): string {
+	return `${JSON.stringify(defaultConfig, null, 2)}\n`;
+}
+
+/**
+ * Reads `allowMapOverlap` out of a parsed `picopilot.json` tree, tolerating a
+ * partially-shaped or absent config. Returns `false` when the key is missing or
+ * the file is malformed enough that the value cannot be found, the SAFE default
+ * (the smart-refuse still guards the genuine data-loss corner).
+ *
+ * `gfx set` normally gets this value through incur's config → option-default
+ * layer; this helper exists for callers that hold a raw config object (and to
+ * keep the "where allowMapOverlap lives" knowledge in one place).
+ */
+export function readAllowMapOverlap(config: unknown): boolean {
+	const parsed = PicopilotConfig.safeParse(config);
+	if (!parsed.success) return false;
+	return (
+		parsed.data.commands?.gfx?.commands?.set?.options?.allowMapOverlap ?? false
+	);
+}

package/src/engine/config/index.ts

@@ -0,0 +1,12 @@
+/**
+ * The per-cart `picopilot.json` config model: the schema `init` scaffolds from
+ * and the later `gfx set` reads `allowMapOverlap` through (via incur's config
+ * layer). See `config.ts` for why the shape lives here as one source of truth.
+ */
+export {
+	defaultConfig,
+	defaultConfigFile,
+	GfxSetOptions,
+	PicopilotConfig,
+	readAllowMapOverlap,
+} from './config.js';

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

@@ -0,0 +1,128 @@
+import {describe, expect, it} from 'vitest';
+
+import {GfxSheet} from '../cart/index.js';
+import {
+	GfxGridError,
+	GRID_SIZE,
+	gridToNibbles,
+	nibblesToGrid,
+	TRANSPARENT_CHAR,
+} from './grid.js';
+
+/** An 8x8 nibble grid built from a generator, for exhaustive round-trip tests. */
+function makeGrid(fn: (r: number, c: number) => number): number[][] {
+	const grid: number[][] = [];
+	for (let r = 0; r < GRID_SIZE; r++) {
+		const row: number[] = [];
+		for (let c = 0; c < GRID_SIZE; c++) row.push(fn(r, c));
+		grid.push(row);
+	}
+	return grid;
+}
+
+describe('gfx char-grid codec: encode', () => {
+	it('renders colour 0 as "." (transparent) and 1..15 as lowercase hex', () => {
+		// Row of 0..7 then 8..15 across two rows, rest zero.
+		const grid = makeGrid((r, c) => (r === 0 ? c : r === 1 ? c + 8 : 0));
+		const text = nibblesToGrid(grid);
+		const lines = text.split('\n');
+		expect(lines).toHaveLength(GRID_SIZE);
+		// Row 0: 0..7 → ".123457"? no — index 0 is ".", 1..7 are hex.
+		expect(lines[0]).toBe('.1234567');
+		// Row 1: 8..15 → hex 8,9,a..f.
+		expect(lines[1]).toBe('89abcdef');
+		// Empty rows are all dots.
+		expect(lines[2]).toBe(TRANSPARENT_CHAR.repeat(GRID_SIZE));
+	});
+
+	it('produces 8 lines of 8 chars, no trailing newline', () => {
+		const text = nibblesToGrid(makeGrid(() => 0));
+		expect(text.endsWith('\n')).toBe(false);
+		const lines = text.split('\n');
+		expect(lines).toHaveLength(GRID_SIZE);
+		for (const line of lines) expect(line).toHaveLength(GRID_SIZE);
+	});
+});
+
+describe('gfx char-grid codec: decode', () => {
+	it('decodes "." to 0 and hex digits (any case) to 1..15', () => {
+		const text = ['.1234567', '89ABCDEF', ...Array(6).fill('........')].join(
+			'\n',
+		);
+		const grid = gridToNibbles(text);
+		expect(grid[0]).toEqual([0, 1, 2, 3, 4, 5, 6, 7]);
+		// Upper-case hex decodes the same as lower-case.
+		expect(grid[1]).toEqual([8, 9, 10, 11, 12, 13, 14, 15]);
+		expect(grid[2]).toEqual([0, 0, 0, 0, 0, 0, 0, 0]);
+	});
+
+	it('tolerates a single trailing newline (a pasted grid)', () => {
+		const text = `${Array(GRID_SIZE).fill('........').join('\n')}\n`;
+		expect(() => gridToNibbles(text)).not.toThrow();
+	});
+
+	it('accepts CRLF line endings', () => {
+		const text = Array(GRID_SIZE).fill('........').join('\r\n');
+		const grid = gridToNibbles(text);
+		expect(grid).toHaveLength(GRID_SIZE);
+	});
+
+	it('rejects a grid with the wrong number of rows', () => {
+		const tooFew = Array(GRID_SIZE - 1)
+			.fill('........')
+			.join('\n');
+		expect(() => gridToNibbles(tooFew)).toThrow(GfxGridError);
+	});
+
+	it('rejects a row with the wrong number of cells', () => {
+		const rows = Array(GRID_SIZE).fill('........');
+		rows[3] = '.......'; // 7 cells
+		expect(() => gridToNibbles(rows.join('\n'))).toThrow(GfxGridError);
+	});
+
+	it('rejects an invalid char', () => {
+		const rows = Array(GRID_SIZE).fill('........');
+		rows[0] = '.......X';
+		expect(() => gridToNibbles(rows.join('\n'))).toThrow(GfxGridError);
+	});
+});
+
+describe('gfx char-grid codec: round-trip is an IDENTITY (the acceptance guard)', () => {
+	it('nibbles → grid → nibbles is identity for a ramp covering every colour', () => {
+		// Cover all 16 indices densely across the 8x8 (index = (r*8+c) % 16).
+		const grid = makeGrid((r, c) => (r * GRID_SIZE + c) % 16);
+		const round = gridToNibbles(nibblesToGrid(grid));
+		expect(round).toEqual(grid);
+	});
+
+	it('grid → nibbles → grid is identity for a hand-written grid', () => {
+		const text = [
+			'.8888888',
+			'8.7.7.7.',
+			'88888888',
+			'.a.a.a.a',
+			'ffffffff',
+			'........',
+			'0.1.2.3.', // wait: "0" is a valid nibble too (1..15 use hex, 0 uses ".")
+			'c.d.e.f.',
+		];
+		// Fix row 6: "0" is NOT how zero is written; zero is ".". Use non-zero hex.
+		text[6] = '1.2.3.4.';
+		const grid = gridToNibbles(text.join('\n'));
+		const round = nibblesToGrid(grid);
+		expect(round).toBe(text.join('\n'));
+	});
+
+	it('every colour value survives the round trip via a real GfxSheet sprite', () => {
+		// The codec must compose with the cart model: read a sprite off a GfxSheet,
+		// encode, decode, and the sheet write-back must reproduce the same pixels.
+		const sheet = GfxSheet.fromBody(undefined);
+		// Paint sprite 5 with a full-range pattern.
+		const painted = makeGrid((r, c) => (r * GRID_SIZE + c) % 16);
+		sheet.setSprite(5, painted);
+
+		const text = nibblesToGrid(sheet.getSprite(5));
+		const decoded = gridToNibbles(text);
+		expect(decoded).toEqual(painted);
+	});
+});

package/src/engine/gfx/grid.ts

@@ -0,0 +1,136 @@
+import {SPRITE_SIZE} from '../cart/index.js';
+
+/**
+ * The shrinko-free char-grid codec: converts a sprite's per-pixel colour
+ * nibbles (as {@link import('../cart/index.js').GfxSheet} reads/writes them)
+ * to and from a readable CHAR GRID, and back, as an IDENTITY.
+ *
+ * The char grid is the "SVG for pixels" (CONTEXT.md `char grid`): the EDIT
+ * surface an agent reads with `gfx show` and writes with `gfx set`. Each pixel
+ * is one character:
+ *
+ * - `.` = transparent = colour index 0 (PICO-8's index-0 doubles as the default
+ *   transparent colour; the grid renders it as `.` so an agent SEES the empty
+ *   pixels rather than a wall of `0`s).
+ * - `0`..`f` (lowercase hex) = colour indices 1..15 (`__gfx__` stores nibbles
+ *   lowercase, so decode is case-insensitive but encode is lowercase to match
+ *   what PICO-8 writes).
+ *
+ * The grid is 8 lines of 8 characters (one 8x8 sprite). The round-trip
+ * `nibbles → grid → nibbles` is an identity for every valid sprite (asserted in
+ * the tests), because `.` maps to 0 and 0 maps to `.` with no other collision.
+ *
+ * This codec is deliberately SEPARABLE from the cart model and the commands: it
+ * only knows nibble grids and strings, so the later `gfx render` task can reuse
+ * it and a test can round-trip it without a cart.
+ */
+
+/** The width/height (in pixels) of one sprite; a char grid is this square. */
+export const GRID_SIZE = SPRITE_SIZE;
+
+/** The character that renders colour index 0 (transparent) in a char grid. */
+export const TRANSPARENT_CHAR = '.';
+
+/**
+ * Encodes an 8x8 grid of colour nibbles (0..15) into a char-grid string: 8
+ * lines of 8 chars, `\n`-joined, no trailing newline. Index 0 → `.`; 1..15 →
+ * the lowercase hex digit.
+ *
+ * @throws {GfxGridError} if the grid is not 8x8 or a cell is out of 0..15.
+ */
+export function nibblesToGrid(grid: number[][]): string {
+	assertNibbleGrid(grid);
+	const lines: string[] = [];
+	for (let r = 0; r < GRID_SIZE; r++) {
+		let line = '';
+		for (let c = 0; c < GRID_SIZE; c++) line += nibbleToChar(grid[r]?.[c] ?? 0);
+		lines.push(line);
+	}
+	return lines.join('\n');
+}
+
+/**
+ * Decodes a char-grid string back into an 8x8 grid of colour nibbles (0..15),
+ * the inverse of {@link nibblesToGrid}. Accepts `.` (→ 0) and hex digits
+ * (case-insensitive). Blank lines / trailing whitespace-only content are
+ * tolerated so an agent may paste a grid with a trailing newline; the parsed
+ * content must still be exactly 8 rows of 8 cells.
+ *
+ * @throws {GfxGridError} if the parsed grid is not 8x8 or a char is invalid.
+ */
+export function gridToNibbles(text: string): number[][] {
+	// Split on either newline style; drop a single trailing empty line (a paste
+	// with a final newline) but keep interior blank lines so a genuine malformed
+	// grid (too few rows) is caught rather than silently accepted.
+	const rawLines = text.split(/\r?\n/);
+	while (rawLines.length > 0 && rawLines[rawLines.length - 1] === '')
+		rawLines.pop();
+
+	if (rawLines.length !== GRID_SIZE) {
+		throw new GfxGridError(
+			`char grid must have ${GRID_SIZE} rows, got ${rawLines.length}`,
+		);
+	}
+
+	const grid: number[][] = [];
+	for (let r = 0; r < GRID_SIZE; r++) {
+		const line = rawLines[r] ?? '';
+		if (line.length !== GRID_SIZE) {
+			throw new GfxGridError(
+				`char grid row ${r} must have ${GRID_SIZE} cells, got ${line.length}`,
+			);
+		}
+		const row: number[] = [];
+		for (let c = 0; c < GRID_SIZE; c++)
+			row.push(charToNibble(line[c] as string, r, c));
+		grid.push(row);
+	}
+	return grid;
+}
+
+/** A malformed char grid or nibble grid (wrong shape or an invalid cell/char). */
+export class GfxGridError extends Error {
+	constructor(message: string) {
+		super(message);
+		this.name = 'GfxGridError';
+	}
+}
+
+function nibbleToChar(n: number): string {
+	return n === 0 ? TRANSPARENT_CHAR : n.toString(16);
+}
+
+function charToNibble(ch: string, r: number, c: number): number {
+	if (ch === TRANSPARENT_CHAR) return 0;
+	const v = Number.parseInt(ch, 16);
+	if (Number.isNaN(v) || v < 0 || v > 15) {
+		throw new GfxGridError(
+			`invalid char "${ch}" at (${c}, ${r}); expected "${TRANSPARENT_CHAR}" or a hex digit 0-f`,
+		);
+	}
+	return v;
+}
+
+function assertNibbleGrid(grid: number[][]): void {
+	if (grid.length !== GRID_SIZE) {
+		throw new GfxGridError(
+			`nibble grid must have ${GRID_SIZE} rows, got ${grid.length}`,
+		);
+	}
+	for (let r = 0; r < GRID_SIZE; r++) {
+		const row = grid[r];
+		if (row === undefined || row.length !== GRID_SIZE) {
+			throw new GfxGridError(
+				`nibble grid row ${r} must have ${GRID_SIZE} cells`,
+			);
+		}
+		for (let c = 0; c < GRID_SIZE; c++) {
+			const v = row[c] ?? 0;
+			if (!Number.isInteger(v) || v < 0 || v > 15) {
+				throw new GfxGridError(
+					`nibble grid cell (${c}, ${r}) = ${v} out of range 0..15`,
+				);
+			}
+		}
+	}
+}

package/src/engine/gfx/index.ts

@@ -0,0 +1,34 @@
+/**
+ * `engine/gfx` — the shrinko-free char-grid codec (`__gfx__` nibbles ↔ char
+ * grid) plus the gfx/map overlap smart-refuse decision.
+ *
+ * This module OWNS the char-grid representation (the "SVG for pixels" EDIT
+ * surface), the overlap safety logic, and the palette-accurate PNG render (the
+ * JUDGE surface). The `gfx show`/`gfx set`/`gfx render` commands are thin wiring
+ * over it. It is separable from the cart model (it only speaks nibble grids,
+ * strings, and RGB buffers) so it round-trips in isolation.
+ */
+export {
+	GRID_SIZE,
+	GfxGridError,
+	gridToNibbles,
+	nibblesToGrid,
+	TRANSPARENT_CHAR,
+} from './grid.js';
+export {
+	LABEL_SIZE,
+	LabelError,
+	labelHexFromPng,
+	nearestPaletteIndex,
+} from './label.js';
+export {decideOverlap, type OverlapDecision, spriteHasData} from './overlap.js';
+export {PICO8_PALETTE, type PaletteColor, paletteColor} from './palette.js';
+export {encodePng, type RgbImage} from './png.js';
+export {
+	RENDER_TARGET_PX,
+	renderSheetPng,
+	renderSpritePng,
+	SHEET_RENDER_SCALE,
+	SPRITE_RENDER_SCALE,
+	upscale,
+} from './render.js';

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

@@ -0,0 +1,105 @@
+import {describe, expect, it} from 'vitest';
+import {
+	LABEL_SIZE,
+	LabelError,
+	labelHexFromPng,
+	nearestPaletteIndex,
+} from './label.js';
+import {PICO8_PALETTE} from './palette.js';
+import {encodePng, type RgbImage} from './png.js';
+
+/**
+ * The label builder is exercised against PNGs produced by our OWN encoder
+ * (`encodePng`, RGB truecolour, stored-deflate), so the decode + nearest-palette
+ * round-trip is verified end-to-end with no external fixtures. Node's `zlib`
+ * inflate reads our stored blocks fine (a standard zlib stream).
+ */
+
+/** Build a solid-colour 128x128 RGB PNG from a PICO-8 palette index. */
+function solidLabelPng(paletteIndex: number): Uint8Array {
+	const c = PICO8_PALETTE[paletteIndex]!;
+	const rgb = new Uint8Array(LABEL_SIZE * LABEL_SIZE * 3);
+	for (let i = 0; i < LABEL_SIZE * LABEL_SIZE; i++) {
+		rgb[i * 3] = c.r;
+		rgb[i * 3 + 1] = c.g;
+		rgb[i * 3 + 2] = c.b;
+	}
+	return encodePng({width: LABEL_SIZE, height: LABEL_SIZE, rgb});
+}
+
+describe('nearestPaletteIndex', () => {
+	it('maps each exact palette RGB back to its own index', () => {
+		for (let i = 0; i < PICO8_PALETTE.length; i++) {
+			const c = PICO8_PALETTE[i]!;
+			expect(nearestPaletteIndex(c.r, c.g, c.b)).toBe(i);
+		}
+	});
+
+	it('snaps a near colour to the closest palette entry (pure black -> 0)', () => {
+		expect(nearestPaletteIndex(3, 2, 1)).toBe(0);
+		// Near PICO-8 red (255,0,77) -> index 8.
+		expect(nearestPaletteIndex(250, 5, 80)).toBe(8);
+	});
+});
+
+describe('labelHexFromPng', () => {
+	it('produces 128 rows of 128 nibbles with a trailing newline', () => {
+		const hex = labelHexFromPng(solidLabelPng(1));
+		const rows = hex.split('\n');
+		// 128 rows + a trailing empty from the final newline.
+		expect(rows.length).toBe(LABEL_SIZE + 1);
+		expect(rows[LABEL_SIZE]).toBe('');
+		for (let y = 0; y < LABEL_SIZE; y++) {
+			expect(rows[y]!.length).toBe(LABEL_SIZE);
+		}
+	});
+
+	it('maps a solid palette colour to that nibble everywhere (index 1 -> all "1")', () => {
+		const hex = labelHexFromPng(solidLabelPng(1));
+		const firstRow = hex.split('\n')[0]!;
+		expect(firstRow).toBe('1'.repeat(LABEL_SIZE));
+	});
+
+	it('round-trips an arbitrary palette index (e.g. 10 -> "a")', () => {
+		const hex = labelHexFromPng(solidLabelPng(10));
+		expect(hex.split('\n')[0]!).toBe('a'.repeat(LABEL_SIZE));
+	});
+
+	it('preserves per-pixel colours (a two-colour split image)', () => {
+		// Left half index 8 (red -> "8"), right half index 12 (blue -> "c").
+		const left = PICO8_PALETTE[8]!;
+		const right = PICO8_PALETTE[12]!;
+		const rgb = new Uint8Array(LABEL_SIZE * LABEL_SIZE * 3);
+		for (let y = 0; y < LABEL_SIZE; y++) {
+			for (let x = 0; x < LABEL_SIZE; x++) {
+				const c = x < LABEL_SIZE / 2 ? left : right;
+				const d = (y * LABEL_SIZE + x) * 3;
+				rgb[d] = c.r;
+				rgb[d + 1] = c.g;
+				rgb[d + 2] = c.b;
+			}
+		}
+		const png = encodePng({width: LABEL_SIZE, height: LABEL_SIZE, rgb});
+		const row = labelHexFromPng(png).split('\n')[0]!;
+		expect(row.slice(0, LABEL_SIZE / 2)).toBe('8'.repeat(LABEL_SIZE / 2));
+		expect(row.slice(LABEL_SIZE / 2)).toBe('c'.repeat(LABEL_SIZE / 2));
+	});
+
+	it('rejects a non-PNG with a structured LabelError', () => {
+		expect(() => labelHexFromPng(new Uint8Array([1, 2, 3, 4]))).toThrowError(
+			LabelError,
+		);
+	});
+
+	it('rejects a wrong-size image (must be exactly 128x128)', () => {
+		const rgb = new Uint8Array(64 * 64 * 3);
+		const png = encodePng({width: 64, height: 64, rgb} as RgbImage);
+		try {
+			labelHexFromPng(png);
+			expect.unreachable('should have thrown');
+		} catch (e) {
+			expect(e).toBeInstanceOf(LabelError);
+			expect((e as LabelError).code).toBe('wrong-size');
+		}
+	});
+});