picopilot 0.0.0 → 0.1.1

package/src/engine/cart/cart.test.ts

@@ -0,0 +1,304 @@
+import {readFileSync} from 'node:fs';
+import {fileURLToPath} from 'node:url';
+import {describe, expect, it} from 'vitest';
+import {
+	Cart,
+	CART_SECTION_NAMES,
+	CartParseError,
+	CartRangeError,
+	GFX_HEIGHT,
+	GfxSheet,
+	MapData,
+	mapRowsForSprite,
+	spriteAliasesMap,
+	spriteOrigin,
+} from './index.js';
+
+/** Reads a fixture `.p8` as a raw string (no newline normalisation). */
+function fixture(name: string): string {
+	return readFileSync(
+		fileURLToPath(new URL(`./fixtures/${name}`, import.meta.url)),
+		'utf8',
+	);
+}
+
+const ALL_FIXTURES = [
+	'minimal.p8',
+	'full.p8',
+	'crlf.p8',
+	'no-trailing-newline.p8',
+	'header-only.p8',
+];
+
+describe('Cart round-trip identity', () => {
+	for (const name of ALL_FIXTURES) {
+		it(`parse -> serialize is byte-identical for ${name}`, () => {
+			const text = fixture(name);
+			expect(Cart.parse(text).serialize()).toBe(text);
+		});
+	}
+
+	it('round-trips CRLF newlines without normalising them', () => {
+		const text = fixture('crlf.p8');
+		expect(text).toContain('\r\n');
+		const out = Cart.parse(text).serialize();
+		expect(out).toBe(text);
+		expect(out).toContain('\r\n');
+	});
+
+	it('round-trips a cart with no trailing newline', () => {
+		const text = fixture('no-trailing-newline.p8');
+		expect(text.endsWith('\n')).toBe(false);
+		expect(Cart.parse(text).serialize()).toBe(text);
+	});
+
+	it('does not mistake a `__x__` token inside Lua for a section marker', () => {
+		const text = [
+			'pico-8 cartridge // http://www.pico-8.com',
+			'version 42',
+			'__lua__',
+			'x = "__gfx__ inside a string, indented"',
+			'   __map__ = 1 -- indented, not a marker',
+			'__gfx__',
+			'00000000',
+			'',
+		].join('\n');
+		const cart = Cart.parse(text);
+		// Only the two real, line-anchored markers are sections.
+		expect(cart.sectionNames()).toEqual(['lua', 'gfx']);
+		expect(cart.getSection('lua')).toContain('__gfx__ inside a string');
+		expect(cart.serialize()).toBe(text);
+	});
+});
+
+describe('Cart section-level read/write', () => {
+	it('reads individual section bodies', () => {
+		const cart = Cart.parse(fixture('minimal.p8'));
+		expect(cart.sectionNames()).toEqual(['lua', 'gfx']);
+		expect(cart.getSection('lua')).toContain('function _init()');
+		expect(cart.getSection('gfx')).toContain('00000000');
+		expect(cart.getSection('sfx')).toBeUndefined();
+		expect(cart.hasSection('map')).toBe(false);
+	});
+
+	it('replaces __gfx__ without disturbing __lua__ or the header', () => {
+		const text = fixture('minimal.p8');
+		const cart = Cart.parse(text);
+		const luaBefore = cart.getSection('lua');
+		cart.setSection('gfx', 'ffffffff\n');
+		expect(cart.getSection('gfx')).toBe('ffffffff\n');
+		// Other section + header untouched.
+		expect(cart.getSection('lua')).toBe(luaBefore);
+		expect(cart.header).toBe(Cart.parse(text).header);
+		// The only diff from the original is inside __gfx__.
+		const out = cart.serialize();
+		expect(out).toContain('__lua__\n-- minimal cart');
+		expect(out).toContain('__gfx__\nffffffff\n');
+		expect(out).not.toContain('00000000');
+	});
+
+	it('appends a new section in the file newline style, leaving others intact', () => {
+		const text = fixture('minimal.p8');
+		const cart = Cart.parse(text);
+		cart.setSection('sfx', '000100000\n');
+		expect(cart.sectionNames()).toEqual(['lua', 'gfx', 'sfx']);
+		// Original text is a strict prefix; the new section is appended verbatim.
+		expect(cart.serialize()).toBe(`${text}__sfx__\n000100000\n`);
+	});
+
+	it('setSection is idempotent for an unchanged body (still round-trips)', () => {
+		const text = fixture('full.p8');
+		const cart = Cart.parse(text);
+		const gfx = cart.getSection('gfx');
+		if (gfx === undefined) throw new Error('fixture missing __gfx__');
+		cart.setSection('gfx', gfx);
+		expect(cart.serialize()).toBe(text);
+	});
+});
+
+describe('Cart structured errors (no crash on malformed input)', () => {
+	it('throws missing-header when the header line is absent', () => {
+		try {
+			Cart.parse(fixture('malformed-no-header.p8'));
+			throw new Error('expected CartParseError');
+		} catch (e) {
+			expect(e).toBeInstanceOf(CartParseError);
+			expect((e as CartParseError).code).toBe('missing-header');
+		}
+	});
+
+	it('throws missing-version when the version line is absent', () => {
+		const text = 'pico-8 cartridge // http://www.pico-8.com\n__lua__\nx=1\n';
+		expect(() => Cart.parse(text)).toThrow(CartParseError);
+		try {
+			Cart.parse(text);
+		} catch (e) {
+			expect((e as CartParseError).code).toBe('missing-version');
+		}
+	});
+
+	it('throws unknown-section for an unmodelled marker', () => {
+		const text =
+			'pico-8 cartridge // http://www.pico-8.com\nversion 42\n__bogus__\nx\n';
+		try {
+			Cart.parse(text);
+			throw new Error('expected CartParseError');
+		} catch (e) {
+			expect(e).toBeInstanceOf(CartParseError);
+			expect((e as CartParseError).code).toBe('unknown-section');
+		}
+	});
+
+	it('throws duplicate-section when a marker repeats', () => {
+		const text =
+			'pico-8 cartridge // http://www.pico-8.com\nversion 42\n__lua__\nx\n__lua__\ny\n';
+		try {
+			Cart.parse(text);
+			throw new Error('expected CartParseError');
+		} catch (e) {
+			expect((e as CartParseError).code).toBe('duplicate-section');
+		}
+	});
+
+	it('parses a header-only cart (no sections) and round-trips it', () => {
+		const text = fixture('header-only.p8');
+		const cart = Cart.parse(text);
+		expect(cart.sectionNames()).toEqual([]);
+		expect(cart.serialize()).toBe(text);
+	});
+
+	it('recognises every modelled section name', () => {
+		expect([...CART_SECTION_NAMES].sort()).toEqual(
+			['gff', 'gfx', 'label', 'lua', 'map', 'music', 'sfx'].sort(),
+		);
+	});
+});
+
+describe('GfxSheet addressable region', () => {
+	it('reads a sprite from the parsed sheet as an 8x8 colour grid', () => {
+		const cart = Cart.parse(fixture('full.p8'));
+		const sheet = GfxSheet.fromBody(cart.getSection('gfx'));
+		const sprite1 = sheet.getSprite(1);
+		expect(sprite1.length).toBe(8);
+		expect(sprite1[0]?.length).toBe(8);
+		// Fixture painted sprite 1 with e (14) / 8 (8) in a checker.
+		expect(sprite1[0]?.[0]).toBe(14);
+		expect(sprite1[0]?.[1]).toBe(8);
+	});
+
+	it('gfx grid round-trips to the same __gfx__ body (identity)', () => {
+		const cart = Cart.parse(fixture('full.p8'));
+		const body = cart.getSection('gfx');
+		if (body === undefined) throw new Error('fixture missing __gfx__');
+		expect(GfxSheet.fromBody(body).toBody()).toBe(body);
+	});
+
+	it('editing one sprite and committing changes only __gfx__', () => {
+		const text = fixture('full.p8');
+		const cart = Cart.parse(text);
+		const luaBefore = cart.getSection('lua');
+		const mapBefore = cart.getSection('map');
+		const sheet = GfxSheet.fromBody(cart.getSection('gfx'));
+		const solid = Array.from({length: 8}, () =>
+			Array.from({length: 8}, () => 9),
+		);
+		sheet.setSprite(0, solid);
+		sheet.commit(cart);
+		expect(GfxSheet.fromBody(cart.getSection('gfx')).getSprite(0)).toEqual(
+			solid,
+		);
+		// Sprite 1 (unrelated) and other sections untouched.
+		expect(GfxSheet.fromBody(cart.getSection('gfx')).getSprite(1)[0]?.[0]).toBe(
+			14,
+		);
+		expect(cart.getSection('lua')).toBe(luaBefore);
+		expect(cart.getSection('map')).toBe(mapBefore);
+	});
+
+	it('setPixel round-trips through hex', () => {
+		const sheet = GfxSheet.fromBody(undefined);
+		expect(sheet.getPixel(0, 0)).toBe(0);
+		sheet.setPixel(3, 5, 12);
+		expect(sheet.getPixel(3, 5)).toBe(12);
+		const reparsed = GfxSheet.fromBody(sheet.toBody());
+		expect(reparsed.getPixel(3, 5)).toBe(12);
+	});
+
+	it('rejects out-of-range pixels, sprites, and colours', () => {
+		const sheet = GfxSheet.fromBody(undefined);
+		expect(() => sheet.getPixel(-1, 0)).toThrow(CartRangeError);
+		expect(() => sheet.getPixel(0, GFX_HEIGHT)).toThrow(CartRangeError);
+		expect(() => sheet.setPixel(0, 0, 16)).toThrow(CartRangeError);
+		expect(() => sheet.getSprite(256)).toThrow(CartRangeError);
+	});
+});
+
+describe('sprite <-> pixel <-> map addressing (0x1000 overlap)', () => {
+	it('maps sprite index to its pixel origin', () => {
+		expect(spriteOrigin(0)).toEqual({x0: 0, y0: 0});
+		expect(spriteOrigin(1)).toEqual({x0: 8, y0: 0});
+		expect(spriteOrigin(16)).toEqual({x0: 0, y0: 8});
+		expect(spriteOrigin(128)).toEqual({x0: 0, y0: 64});
+		expect(spriteOrigin(255)).toEqual({x0: 120, y0: 120});
+	});
+
+	it('flags the shared upper bank (128..255) as map-aliasing', () => {
+		expect(spriteAliasesMap(0)).toBe(false);
+		expect(spriteAliasesMap(127)).toBe(false);
+		expect(spriteAliasesMap(128)).toBe(true);
+		expect(spriteAliasesMap(255)).toBe(true);
+	});
+
+	it('base-bank sprites alias no map rows; shared-bank sprites alias 4 rows', () => {
+		expect(mapRowsForSprite(0)).toBeUndefined();
+		expect(mapRowsForSprite(127)).toBeUndefined();
+		// sprite 128 sits at gfx row 64 -> map rows 32..35.
+		expect(mapRowsForSprite(128)).toEqual({start: 32, end: 36});
+		// sprite 255 sits at gfx row 120 -> map rows 60..63.
+		expect(mapRowsForSprite(255)).toEqual({start: 60, end: 64});
+	});
+});
+
+describe('MapData addressable region + overlap inspection', () => {
+	it('reads a tile from the parsed map', () => {
+		const cart = Cart.parse(fixture('full.p8'));
+		const map = MapData.fromBody(cart.getSection('map'));
+		expect(map.getTile(0, 0)).toBe(5); // fixture set tile (0,0) = 05
+		expect(map.getTile(1, 0)).toBe(0);
+	});
+
+	it('map grid round-trips to the same __map__ body (identity)', () => {
+		const cart = Cart.parse(fixture('full.p8'));
+		const body = cart.getSection('map');
+		if (body === undefined) throw new Error('fixture missing __map__');
+		expect(MapData.fromBody(body).toBody()).toBe(body);
+	});
+
+	it('counts non-zero tiles across a row range (overlap primitive)', () => {
+		const cart = Cart.parse(fixture('full.p8'));
+		const map = MapData.fromBody(cart.getSection('map'));
+		// Only tile (0,0) is non-zero, in row 0.
+		expect(map.nonZeroTilesInRows(0, 1)).toBe(1);
+		expect(map.nonZeroTilesInRows(1, 32)).toBe(0);
+		// Shared-bank rows (>= 32) are not stored in text __map__, so zero.
+		expect(map.nonZeroTilesInRows(32, 64)).toBe(0);
+	});
+
+	it('editing a tile and committing changes only __map__', () => {
+		const text = fixture('full.p8');
+		const cart = Cart.parse(text);
+		const gfxBefore = cart.getSection('gfx');
+		const map = MapData.fromBody(cart.getSection('map'));
+		map.setTile(5, 5, 42);
+		map.commit(cart);
+		expect(MapData.fromBody(cart.getSection('map')).getTile(5, 5)).toBe(42);
+		expect(cart.getSection('gfx')).toBe(gfxBefore);
+	});
+
+	it('rejects out-of-range map cells and tile values', () => {
+		const map = MapData.fromBody(undefined);
+		expect(() => map.getTile(-1, 0)).toThrow(CartRangeError);
+		expect(() => map.setTile(0, 0, 256)).toThrow(CartRangeError);
+		expect(() => map.getRow(32)).toThrow(CartRangeError);
+	});
+});

package/src/engine/cart/cart.ts

@@ -0,0 +1,211 @@
+import {CartParseError} from './errors.js';
+
+/**
+ * The section names picopilot models in a text-format `.p8` cart. These are the
+ * markers PICO-8 writes (`__lua__`, `__gfx__`, ...); `__label__` is the cart
+ * label image, also hex.
+ */
+export const CART_SECTION_NAMES = [
+	'lua',
+	'gfx',
+	'gff',
+	'label',
+	'map',
+	'sfx',
+	'music',
+] as const;
+
+/** A recognised `.p8` section name (without the surrounding `__`). */
+export type CartSectionName = (typeof CART_SECTION_NAMES)[number];
+
+const KNOWN_SECTIONS = new Set<string>(CART_SECTION_NAMES);
+
+/**
+ * One parsed section of a cart, kept as three verbatim pieces so re-joining
+ * them reproduces the original bytes exactly:
+ *
+ * - `marker`: the section-marker line INCLUDING its line terminator, e.g.
+ *   `"__gfx__\n"` or `"__gfx__\r\n"`.
+ * - `body`: everything from after the marker line up to (not including) the
+ *   next marker, verbatim (its own trailing newline(s) live here).
+ *
+ * The public API exposes the section body as a string via {@link Cart.getSection}
+ * / {@link Cart.setSection}; the `marker` is internal book-keeping so callers
+ * never have to reason about newline style to keep the round-trip identical.
+ */
+interface CartSection {
+	readonly name: CartSectionName;
+	marker: string;
+	body: string;
+}
+
+/**
+ * Matches a whole line that is a section marker: `__name__` optionally followed
+ * by a `\r` (CRLF) and the line's `\n`, anchored so a `__x__` appearing mid-line
+ * (e.g. inside Lua) is never mistaken for a marker. The trailing newline is
+ * captured into the match so the marker line, terminator included, is preserved.
+ */
+const SECTION_MARKER = /^__([a-zA-Z0-9]+)__[^\S\r\n]*(\r?\n|$)/gm;
+
+/**
+ * The in-memory model of a text-format `.p8` cart: the load-bearing seam every
+ * cart-touching command (init, gfx, tokens, verify) reads and writes through.
+ *
+ * Design contract:
+ *
+ * - **Round-trip is identity.** `Cart.parse(text).serialize() === text`, byte
+ *   for byte, for any well-formed cart, regardless of newline style or trailing
+ *   newline. Achieved by preserving the header, each marker line, and each
+ *   section body verbatim, and never normalising whitespace on the way through.
+ * - **Sections are independently addressable.** {@link getSection} /
+ *   {@link setSection} read and replace one section without disturbing the
+ *   others (or the header).
+ * - **gfx/map are addressable as regions, not opaque strings.** The `__gfx__`
+ *   and `__map__` hex bodies are exposed as row/pixel grids (see `gfx.ts` /
+ *   `map.ts`) so the gfx codec and the 0x1000 overlap check can target specific
+ *   sprites/map rows.
+ */
+export class Cart {
+	/**
+	 * The raw text before the first section marker (the `pico-8 cartridge ...`
+	 * line, the `version N` line, and any trailing blank lines), preserved
+	 * verbatim so it round-trips exactly.
+	 */
+	readonly header: string;
+
+	private readonly sections: CartSection[];
+
+	private constructor(header: string, sections: CartSection[]) {
+		this.header = header;
+		this.sections = sections;
+	}
+
+	/**
+	 * Parses a `.p8` text blob into a {@link Cart}.
+	 *
+	 * Malformed input throws a {@link CartParseError} with a machine-readable
+	 * `code` (missing header/version, unknown or duplicate section) rather than
+	 * crashing, so the command layer can surface a structured failure.
+	 */
+	static parse(text: string): Cart {
+		if (!/^pico-8 cartridge/.test(text)) {
+			throw new CartParseError(
+				'missing-header',
+				'not a .p8 cart: expected a "pico-8 cartridge ..." header on the first line',
+			);
+		}
+		if (!/^pico-8 cartridge[^\n]*\r?\nversion\s+\d+/.test(text)) {
+			throw new CartParseError(
+				'missing-version',
+				'malformed .p8 cart: expected a "version N" line after the header',
+			);
+		}
+
+		const markers: {
+			name: string;
+			marker: string;
+			start: number;
+			bodyStart: number;
+		}[] = [];
+		SECTION_MARKER.lastIndex = 0;
+		for (
+			let m = SECTION_MARKER.exec(text);
+			m !== null;
+			m = SECTION_MARKER.exec(text)
+		) {
+			markers.push({
+				name: m[1] as string,
+				marker: m[0],
+				start: m.index,
+				bodyStart: m.index + m[0].length,
+			});
+		}
+
+		const header = markers.length > 0 ? text.slice(0, markers[0]?.start) : text;
+
+		const sections: CartSection[] = [];
+		const seen = new Set<string>();
+		for (let i = 0; i < markers.length; i++) {
+			const cur = markers[i];
+			if (cur === undefined) continue;
+			if (!KNOWN_SECTIONS.has(cur.name)) {
+				throw new CartParseError(
+					'unknown-section',
+					`unknown .p8 section "__${cur.name}__" (known: ${CART_SECTION_NAMES.map((n) => `__${n}__`).join(', ')})`,
+				);
+			}
+			if (seen.has(cur.name)) {
+				throw new CartParseError(
+					'duplicate-section',
+					`duplicate .p8 section "__${cur.name}__"`,
+				);
+			}
+			seen.add(cur.name);
+			const bodyEnd = markers[i + 1]?.start ?? text.length;
+			sections.push({
+				name: cur.name as CartSectionName,
+				marker: cur.marker,
+				body: text.slice(cur.bodyStart, bodyEnd),
+			});
+		}
+
+		return new Cart(header, sections);
+	}
+
+	/** The names of the sections present in this cart, in file order. */
+	sectionNames(): CartSectionName[] {
+		return this.sections.map((s) => s.name);
+	}
+
+	/** True if the cart contains the named section. */
+	hasSection(name: CartSectionName): boolean {
+		return this.sections.some((s) => s.name === name);
+	}
+
+	/**
+	 * Returns the raw body text of a section (everything after the marker line,
+	 * verbatim including its own newlines), or `undefined` if the section is not
+	 * present. The gfx/map region helpers build on this.
+	 */
+	getSection(name: CartSectionName): string | undefined {
+		return this.sections.find((s) => s.name === name)?.body;
+	}
+
+	/**
+	 * Replaces one section's body in place, leaving every other section and the
+	 * header untouched. If the section is not yet present it is appended (with a
+	 * `__name__\n` marker in the file's dominant newline style).
+	 *
+	 * The body is written verbatim; callers that want a trailing newline must
+	 * include it. Region-level helpers (gfx/map) go through here.
+	 */
+	setSection(name: CartSectionName, body: string): void {
+		const existing = this.sections.find((s) => s.name === name);
+		if (existing !== undefined) {
+			existing.body = body;
+			return;
+		}
+		this.sections.push({name, marker: `__${name}__${this.newline()}`, body});
+	}
+
+	/**
+	 * Serializes the cart back to a `.p8` text blob. For an unmodified cart this
+	 * is byte-identical to the text it was parsed from.
+	 */
+	serialize(): string {
+		let out = this.header;
+		for (const s of this.sections) {
+			out += s.marker + s.body;
+		}
+		return out;
+	}
+
+	/**
+	 * The dominant newline style of the file, inferred from the header, used only
+	 * when APPENDING a brand-new section marker (existing markers keep their own
+	 * terminator verbatim). Defaults to `\n`.
+	 */
+	private newline(): string {
+		return /\r\n/.test(this.header) ? '\r\n' : '\n';
+	}
+}

package/src/engine/cart/errors.ts

@@ -0,0 +1,39 @@
+/**
+ * Structured errors for the cart model.
+ *
+ * Parsing a malformed cart throws a `CartParseError` (never an unstructured
+ * crash), carrying a machine-readable `code` and a human-readable `message` so
+ * the command layer can turn it into incur's `error({ code, message, ... })`
+ * envelope rather than letting a raw exception escape. Region access out of
+ * bounds throws a `CartRangeError` for the same reason.
+ */
+
+/** Machine-readable reason a `.p8` could not be parsed into the cart model. */
+export type CartParseErrorCode =
+	/** The `pico-8 cartridge ...` header line is missing or unrecognised. */
+	| 'missing-header'
+	/** The `version N` line is missing or malformed. */
+	| 'missing-version'
+	/** A `__section__` marker is present but names a section we do not model. */
+	| 'unknown-section'
+	/** The same `__section__` marker appears more than once. */
+	| 'duplicate-section';
+
+/** Thrown when a `.p8` text blob cannot be parsed into a {@link Cart}. */
+export class CartParseError extends Error {
+	readonly code: CartParseErrorCode;
+
+	constructor(code: CartParseErrorCode, message: string) {
+		super(message);
+		this.name = 'CartParseError';
+		this.code = code;
+	}
+}
+
+/** Thrown when a gfx/map region access falls outside the addressable grid. */
+export class CartRangeError extends Error {
+	constructor(message: string) {
+		super(message);
+		this.name = 'CartRangeError';
+	}
+}

package/src/engine/cart/fixtures/crlf.p8

@@ -0,0 +1,6 @@
+pico-8 cartridge // http://www.pico-8.com
+version 42
+__lua__
+print("crlf")
+__gfx__
+00000000