picopilot 0.0.0 → 0.1.0

package/dist/engine/cart/cart.js

@@ -0,0 +1,153 @@
+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',
+];
+const KNOWN_SECTIONS = new Set(CART_SECTION_NAMES);
+/**
+ * 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.
+     */
+    header;
+    sections;
+    constructor(header, sections) {
+        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) {
+        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 = [];
+        SECTION_MARKER.lastIndex = 0;
+        for (let m = SECTION_MARKER.exec(text); m !== null; m = SECTION_MARKER.exec(text)) {
+            markers.push({
+                name: m[1],
+                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 = [];
+        const seen = new Set();
+        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,
+                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() {
+        return this.sections.map((s) => s.name);
+    }
+    /** True if the cart contains the named section. */
+    hasSection(name) {
+        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) {
+        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, body) {
+        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() {
+        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`.
+     */
+    newline() {
+        return /\r\n/.test(this.header) ? '\r\n' : '\n';
+    }
+}
+//# sourceMappingURL=cart.js.map

package/dist/engine/cart/cart.js.map

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

package/dist/engine/cart/errors.d.ts

@@ -0,0 +1,29 @@
+/**
+ * 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 declare class CartParseError extends Error {
+    readonly code: CartParseErrorCode;
+    constructor(code: CartParseErrorCode, message: string);
+}
+/** Thrown when a gfx/map region access falls outside the addressable grid. */
+export declare class CartRangeError extends Error {
+    constructor(message: string);
+}
+//# sourceMappingURL=errors.d.ts.map

package/dist/engine/cart/errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../../../src/engine/cart/errors.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,+EAA+E;AAC/E,MAAM,MAAM,kBAAkB;AAC7B,yEAAyE;AACvE,gBAAgB;AAClB,oDAAoD;GAClD,iBAAiB;AACnB,6EAA6E;GAC3E,iBAAiB;AACnB,4DAA4D;GAC1D,mBAAmB,CAAC;AAEvB,0EAA0E;AAC1E,qBAAa,cAAe,SAAQ,KAAK;IACxC,QAAQ,CAAC,IAAI,EAAE,kBAAkB,CAAC;gBAEtB,IAAI,EAAE,kBAAkB,EAAE,OAAO,EAAE,MAAM;CAKrD;AAED,8EAA8E;AAC9E,qBAAa,cAAe,SAAQ,KAAK;gBAC5B,OAAO,EAAE,MAAM;CAI3B"}

package/dist/engine/cart/errors.js

@@ -0,0 +1,26 @@
+/**
+ * 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.
+ */
+/** Thrown when a `.p8` text blob cannot be parsed into a {@link Cart}. */
+export class CartParseError extends Error {
+    code;
+    constructor(code, message) {
+        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) {
+        super(message);
+        this.name = 'CartRangeError';
+    }
+}
+//# sourceMappingURL=errors.js.map

package/dist/engine/cart/errors.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.js","sourceRoot":"","sources":["../../../src/engine/cart/errors.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAaH,0EAA0E;AAC1E,MAAM,OAAO,cAAe,SAAQ,KAAK;IAC/B,IAAI,CAAqB;IAElC,YAAY,IAAwB,EAAE,OAAe;QACpD,KAAK,CAAC,OAAO,CAAC,CAAC;QACf,IAAI,CAAC,IAAI,GAAG,gBAAgB,CAAC;QAC7B,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC;IAClB,CAAC;CACD;AAED,8EAA8E;AAC9E,MAAM,OAAO,cAAe,SAAQ,KAAK;IACxC,YAAY,OAAe;QAC1B,KAAK,CAAC,OAAO,CAAC,CAAC;QACf,IAAI,CAAC,IAAI,GAAG,gBAAgB,CAAC;IAC9B,CAAC;CACD"}

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

@@ -0,0 +1,79 @@
+import type { Cart } from './cart.js';
+/**
+ * Addressable view over a cart's `__gfx__` section: the 128x128 spritesheet as a
+ * grid of per-pixel colour nibbles (0..15), NOT an opaque hex string.
+ *
+ * The spritesheet holds 256 8x8 sprites laid out 16 per row: sprite `n` lives at
+ * pixel column `(n % 16) * 8`, row `(n \ 16) * 8`. Sprites 0..127 are the base
+ * bank; sprites 128..255 (`0x1000` in memory) alias `__map__` rows 32..63 (the
+ * overlap the smart-refuse depends on); see {@link mapRowsForSprite}.
+ *
+ * Reads/writes go through the parsed grid; call {@link commit} to write the grid
+ * back into the cart's `__gfx__` body (preserving its trailing-newline style).
+ * If the section body is shorter than the full sheet (a partial/authored cart),
+ * missing pixels read as 0 and short rows are padded to full width on commit.
+ */
+export declare const GFX_WIDTH = 128;
+export declare const GFX_HEIGHT = 128;
+export declare const SPRITE_SIZE = 8;
+export declare const SPRITES_PER_ROW = 16;
+export declare class GfxSheet {
+    /** `pixels[y][x]` is the colour index 0..15 at pixel (x, y). */
+    private readonly pixels;
+    /** The newline that terminates each row line in the source body (`\n` default). */
+    private readonly newline;
+    private constructor();
+    /**
+     * Builds an addressable sheet from a cart's `__gfx__` body. A missing or empty
+     * section yields an all-zero sheet, so the codec can still address any sprite.
+     */
+    static fromBody(body: string | undefined): GfxSheet;
+    /** Reads the colour index (0..15) at pixel (x, y). */
+    getPixel(x: number, y: number): number;
+    /** Writes the colour index (0..15) at pixel (x, y). */
+    setPixel(x: number, y: number, color: number): void;
+    /**
+     * Reads one 8x8 sprite (0..255) as an 8-row grid of colour indices, `grid[r][c]`.
+     */
+    getSprite(n: number): number[][];
+    /**
+     * Writes one 8x8 sprite (0..255) from an 8-row grid of colour indices. The
+     * grid must be 8x8; each cell 0..15.
+     */
+    setSprite(n: number, grid: number[][]): void;
+    /**
+     * Serializes the grid back to a `__gfx__` body (128 lines of 128 hex nibbles),
+     * using the source body's newline style and terminating the last line, so it
+     * matches what PICO-8 writes.
+     */
+    toBody(): string;
+    /** Writes the grid back into the cart's `__gfx__` section. */
+    commit(cart: Cart): void;
+    private assertPixel;
+}
+/** The top-left pixel origin of sprite `n` (0..255) in the 128x128 sheet. */
+export declare function spriteOrigin(n: number): {
+    x0: number;
+    y0: number;
+};
+/**
+ * Whether sprite `n` lives in the shared upper bank (128..255) that aliases the
+ * bottom half of `__map__`. The gfx/map overlap smart-refuse (next task) keys
+ * off this.
+ */
+export declare function spriteAliasesMap(n: number): boolean;
+/**
+ * The `__map__` rows a shared-bank sprite (128..255) aliases, or `undefined` for
+ * a base-bank sprite (0..127) that aliases nothing.
+ *
+ * Memory layout: sprite `n`'s 8 pixel rows sit at gfx rows `(n \ 16) * 8`; for
+ * the shared bank those are gfx rows 64..127, which occupy the SAME memory as
+ * `__map__` rows 32..63. Each map row is 128 bytes = 2 gfx pixel rows (128 gfx
+ * nibbles map to 128/... ). Concretely: gfx row `g` (64..127) aliases map row
+ * `32 + (g - 64) \ 2`, so a single 8-row sprite covers 4 map rows.
+ */
+export declare function mapRowsForSprite(n: number): {
+    start: number;
+    end: number;
+} | undefined;
+//# sourceMappingURL=gfx.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"gfx.d.ts","sourceRoot":"","sources":["../../../src/engine/cart/gfx.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAC,IAAI,EAAC,MAAM,WAAW,CAAC;AAGpC;;;;;;;;;;;;;GAaG;AACH,eAAO,MAAM,SAAS,MAAM,CAAC;AAC7B,eAAO,MAAM,UAAU,MAAM,CAAC;AAC9B,eAAO,MAAM,WAAW,IAAI,CAAC;AAC7B,eAAO,MAAM,eAAe,KAAK,CAAC;AAElC,qBAAa,QAAQ;IACpB,gEAAgE;IAChE,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAa;IAEpC,mFAAmF;IACnF,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAS;IAEjC,OAAO;IAKP;;;OAGG;IACH,MAAM,CAAC,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,SAAS,GAAG,QAAQ;IAgBnD,sDAAsD;IACtD,QAAQ,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,GAAG,MAAM;IAKtC,uDAAuD;IACvD,QAAQ,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,IAAI;IASnD;;OAEG;IACH,SAAS,CAAC,CAAC,EAAE,MAAM,GAAG,MAAM,EAAE,EAAE;IAYhC;;;OAGG;IACH,SAAS,CAAC,CAAC,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,EAAE,GAAG,IAAI;IAmB5C;;;;OAIG;IACH,MAAM,IAAI,MAAM;IAWhB,8DAA8D;IAC9D,MAAM,CAAC,IAAI,EAAE,IAAI,GAAG,IAAI;IAIxB,OAAO,CAAC,WAAW;CAcnB;AAED,6EAA6E;AAC7E,wBAAgB,YAAY,CAAC,CAAC,EAAE,MAAM,GAAG;IAAC,EAAE,EAAE,MAAM,CAAC;IAAC,EAAE,EAAE,MAAM,CAAA;CAAC,CAQhE;AAED;;;;GAIG;AACH,wBAAgB,gBAAgB,CAAC,CAAC,EAAE,MAAM,GAAG,OAAO,CAKnD;AAED;;;;;;;;;GASG;AACH,wBAAgB,gBAAgB,CAC/B,CAAC,EAAE,MAAM,GACP;IAAC,KAAK,EAAE,MAAM,CAAC;IAAC,GAAG,EAAE,MAAM,CAAA;CAAC,GAAG,SAAS,CAM1C"}

package/dist/engine/cart/gfx.js

@@ -0,0 +1,171 @@
+import { CartRangeError } from './errors.js';
+/**
+ * Addressable view over a cart's `__gfx__` section: the 128x128 spritesheet as a
+ * grid of per-pixel colour nibbles (0..15), NOT an opaque hex string.
+ *
+ * The spritesheet holds 256 8x8 sprites laid out 16 per row: sprite `n` lives at
+ * pixel column `(n % 16) * 8`, row `(n \ 16) * 8`. Sprites 0..127 are the base
+ * bank; sprites 128..255 (`0x1000` in memory) alias `__map__` rows 32..63 (the
+ * overlap the smart-refuse depends on); see {@link mapRowsForSprite}.
+ *
+ * Reads/writes go through the parsed grid; call {@link commit} to write the grid
+ * back into the cart's `__gfx__` body (preserving its trailing-newline style).
+ * If the section body is shorter than the full sheet (a partial/authored cart),
+ * missing pixels read as 0 and short rows are padded to full width on commit.
+ */
+export const GFX_WIDTH = 128;
+export const GFX_HEIGHT = 128;
+export const SPRITE_SIZE = 8;
+export const SPRITES_PER_ROW = 16;
+export class GfxSheet {
+    /** `pixels[y][x]` is the colour index 0..15 at pixel (x, y). */
+    pixels;
+    /** The newline that terminates each row line in the source body (`\n` default). */
+    newline;
+    constructor(pixels, newline) {
+        this.pixels = pixels;
+        this.newline = newline;
+    }
+    /**
+     * Builds an addressable sheet from a cart's `__gfx__` body. A missing or empty
+     * section yields an all-zero sheet, so the codec can still address any sprite.
+     */
+    static fromBody(body) {
+        const newline = body !== undefined && /\r\n/.test(body) ? '\r\n' : '\n';
+        const pixels = [];
+        const lines = body === undefined ? [] : body.split(/\r?\n/);
+        for (let y = 0; y < GFX_HEIGHT; y++) {
+            const line = lines[y] ?? '';
+            const row = [];
+            for (let x = 0; x < GFX_WIDTH; x++) {
+                const ch = line[x];
+                row.push(ch === undefined ? 0 : hexNibble(ch));
+            }
+            pixels.push(row);
+        }
+        return new GfxSheet(pixels, newline);
+    }
+    /** Reads the colour index (0..15) at pixel (x, y). */
+    getPixel(x, y) {
+        this.assertPixel(x, y);
+        return this.pixels[y]?.[x] ?? 0;
+    }
+    /** Writes the colour index (0..15) at pixel (x, y). */
+    setPixel(x, y, color) {
+        this.assertPixel(x, y);
+        if (!Number.isInteger(color) || color < 0 || color > 15) {
+            throw new CartRangeError(`colour ${color} out of range 0..15`);
+        }
+        const row = this.pixels[y];
+        if (row !== undefined)
+            row[x] = color;
+    }
+    /**
+     * Reads one 8x8 sprite (0..255) as an 8-row grid of colour indices, `grid[r][c]`.
+     */
+    getSprite(n) {
+        const { x0, y0 } = spriteOrigin(n);
+        const grid = [];
+        for (let r = 0; r < SPRITE_SIZE; r++) {
+            const row = [];
+            for (let c = 0; c < SPRITE_SIZE; c++)
+                row.push(this.getPixel(x0 + c, y0 + r));
+            grid.push(row);
+        }
+        return grid;
+    }
+    /**
+     * Writes one 8x8 sprite (0..255) from an 8-row grid of colour indices. The
+     * grid must be 8x8; each cell 0..15.
+     */
+    setSprite(n, grid) {
+        if (grid.length !== SPRITE_SIZE) {
+            throw new CartRangeError(`sprite grid must have ${SPRITE_SIZE} rows, got ${grid.length}`);
+        }
+        const { x0, y0 } = spriteOrigin(n);
+        for (let r = 0; r < SPRITE_SIZE; r++) {
+            const gridRow = grid[r];
+            if (gridRow === undefined || gridRow.length !== SPRITE_SIZE) {
+                throw new CartRangeError(`sprite grid row ${r} must have ${SPRITE_SIZE} cells`);
+            }
+            for (let c = 0; c < SPRITE_SIZE; c++)
+                this.setPixel(x0 + c, y0 + r, gridRow[c] ?? 0);
+        }
+    }
+    /**
+     * Serializes the grid back to a `__gfx__` body (128 lines of 128 hex nibbles),
+     * using the source body's newline style and terminating the last line, so it
+     * matches what PICO-8 writes.
+     */
+    toBody() {
+        const lines = [];
+        for (let y = 0; y < GFX_HEIGHT; y++) {
+            let line = '';
+            for (let x = 0; x < GFX_WIDTH; x++)
+                line += (this.pixels[y]?.[x] ?? 0).toString(16);
+            lines.push(line);
+        }
+        return lines.join(this.newline) + this.newline;
+    }
+    /** Writes the grid back into the cart's `__gfx__` section. */
+    commit(cart) {
+        cart.setSection('gfx', this.toBody());
+    }
+    assertPixel(x, y) {
+        if (!Number.isInteger(x) ||
+            !Number.isInteger(y) ||
+            x < 0 ||
+            y < 0 ||
+            x >= GFX_WIDTH ||
+            y >= GFX_HEIGHT) {
+            throw new CartRangeError(`pixel (${x}, ${y}) out of range 0..${GFX_WIDTH - 1}`);
+        }
+    }
+}
+/** The top-left pixel origin of sprite `n` (0..255) in the 128x128 sheet. */
+export function spriteOrigin(n) {
+    if (!Number.isInteger(n) || n < 0 || n > 255) {
+        throw new CartRangeError(`sprite ${n} out of range 0..255`);
+    }
+    return {
+        x0: (n % SPRITES_PER_ROW) * SPRITE_SIZE,
+        y0: Math.floor(n / SPRITES_PER_ROW) * SPRITE_SIZE,
+    };
+}
+/**
+ * Whether sprite `n` lives in the shared upper bank (128..255) that aliases the
+ * bottom half of `__map__`. The gfx/map overlap smart-refuse (next task) keys
+ * off this.
+ */
+export function spriteAliasesMap(n) {
+    if (!Number.isInteger(n) || n < 0 || n > 255) {
+        throw new CartRangeError(`sprite ${n} out of range 0..255`);
+    }
+    return n >= 128;
+}
+/**
+ * The `__map__` rows a shared-bank sprite (128..255) aliases, or `undefined` for
+ * a base-bank sprite (0..127) that aliases nothing.
+ *
+ * Memory layout: sprite `n`'s 8 pixel rows sit at gfx rows `(n \ 16) * 8`; for
+ * the shared bank those are gfx rows 64..127, which occupy the SAME memory as
+ * `__map__` rows 32..63. Each map row is 128 bytes = 2 gfx pixel rows (128 gfx
+ * nibbles map to 128/... ). Concretely: gfx row `g` (64..127) aliases map row
+ * `32 + (g - 64) \ 2`, so a single 8-row sprite covers 4 map rows.
+ */
+export function mapRowsForSprite(n) {
+    if (!spriteAliasesMap(n))
+        return undefined;
+    const { y0 } = spriteOrigin(n);
+    // y0 is 64..120 for the shared bank; each pair of gfx rows aliases one map row.
+    const start = 32 + Math.floor((y0 - 64) / 2);
+    return { start, end: start + SPRITE_SIZE / 2 }; // 8 gfx rows = 4 map rows: [start, end)
+}
+function hexNibble(ch) {
+    const v = Number.parseInt(ch, 16);
+    if (Number.isNaN(v)) {
+        throw new CartRangeError(`invalid hex nibble "${ch}" in __gfx__`);
+    }
+    return v;
+}
+//# sourceMappingURL=gfx.js.map

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

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

package/dist/engine/cart/index.d.ts

@@ -0,0 +1,15 @@
+/**
+ * The picopilot cart model: parse a text-format `.p8` into a typed, section-level
+ * model, read/modify individual sections, address the `__gfx__`/`__map__` hex as
+ * pixel/tile regions, and serialize back byte-identically.
+ *
+ * This is the load-bearing seam every cart-touching command (init, gfx, tokens,
+ * verify) reads and writes through. See `cart.ts` for the round-trip-identity
+ * contract; `gfx.ts` / `map.ts` for the addressable regions (and the 0x1000
+ * overlap the smart-refuse depends on).
+ */
+export { Cart, CART_SECTION_NAMES, type CartSectionName } from './cart.js';
+export { CartParseError, type CartParseErrorCode, CartRangeError, } from './errors.js';
+export { GfxSheet, GFX_HEIGHT, GFX_WIDTH, mapRowsForSprite, SPRITE_SIZE, SPRITES_PER_ROW, spriteAliasesMap, spriteOrigin, } from './gfx.js';
+export { MapData, MAP_ROWS, MAP_WIDTH } from './map.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/engine/cart/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/engine/cart/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AACH,OAAO,EAAC,IAAI,EAAE,kBAAkB,EAAE,KAAK,eAAe,EAAC,MAAM,WAAW,CAAC;AACzE,OAAO,EACN,cAAc,EACd,KAAK,kBAAkB,EACvB,cAAc,GACd,MAAM,aAAa,CAAC;AACrB,OAAO,EACN,QAAQ,EACR,UAAU,EACV,SAAS,EACT,gBAAgB,EAChB,WAAW,EACX,eAAe,EACf,gBAAgB,EAChB,YAAY,GACZ,MAAM,UAAU,CAAC;AAClB,OAAO,EAAC,OAAO,EAAE,QAAQ,EAAE,SAAS,EAAC,MAAM,UAAU,CAAC"}

package/dist/engine/cart/index.js

@@ -0,0 +1,15 @@
+/**
+ * The picopilot cart model: parse a text-format `.p8` into a typed, section-level
+ * model, read/modify individual sections, address the `__gfx__`/`__map__` hex as
+ * pixel/tile regions, and serialize back byte-identically.
+ *
+ * This is the load-bearing seam every cart-touching command (init, gfx, tokens,
+ * verify) reads and writes through. See `cart.ts` for the round-trip-identity
+ * contract; `gfx.ts` / `map.ts` for the addressable regions (and the 0x1000
+ * overlap the smart-refuse depends on).
+ */
+export { Cart, CART_SECTION_NAMES } from './cart.js';
+export { CartParseError, CartRangeError, } from './errors.js';
+export { GfxSheet, GFX_HEIGHT, GFX_WIDTH, mapRowsForSprite, SPRITE_SIZE, SPRITES_PER_ROW, spriteAliasesMap, spriteOrigin, } from './gfx.js';
+export { MapData, MAP_ROWS, MAP_WIDTH } from './map.js';
+//# sourceMappingURL=index.js.map

package/dist/engine/cart/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/engine/cart/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AACH,OAAO,EAAC,IAAI,EAAE,kBAAkB,EAAuB,MAAM,WAAW,CAAC;AACzE,OAAO,EACN,cAAc,EAEd,cAAc,GACd,MAAM,aAAa,CAAC;AACrB,OAAO,EACN,QAAQ,EACR,UAAU,EACV,SAAS,EACT,gBAAgB,EAChB,WAAW,EACX,eAAe,EACf,gBAAgB,EAChB,YAAY,GACZ,MAAM,UAAU,CAAC;AAClB,OAAO,EAAC,OAAO,EAAE,QAAQ,EAAE,SAAS,EAAC,MAAM,UAAU,CAAC"}

package/dist/engine/cart/map.d.ts

@@ -0,0 +1,46 @@
+import type { Cart } from './cart.js';
+/**
+ * Addressable view over a cart's `__map__` section: the tile map as a grid of
+ * 8-bit tile indices, NOT an opaque hex string.
+ *
+ * The text `__map__` stores the base map: up to 32 rows of 128 tiles, each tile
+ * a byte written as two hex chars (`grid[y][x]`). Rows 32..63 (the shared half)
+ * are NOT stored here in the text format (they live in `__gfx__`'s upper bank
+), see `gfx.ts` {@link mapRowsForSprite}; this view models the `__map__` body
+ * as written. The 0x1000 overlap check reads a shared-bank sprite's aliased map
+ * region through {@link nonZeroTilesInRows} to decide whether a write clobbers
+ * real tiles.
+ *
+ * Reads/writes go through the parsed grid; call {@link commit} to write it back
+ * into the cart's `__map__` body. A missing/short section reads as zero tiles.
+ */
+export declare const MAP_WIDTH = 128;
+export declare const MAP_ROWS = 32;
+export declare class MapData {
+    /** `tiles[y][x]` is the 0..255 tile index at map cell (x, y). */
+    private readonly tiles;
+    private readonly newline;
+    private constructor();
+    /** Builds an addressable map from a cart's `__map__` body (all-zero if absent). */
+    static fromBody(body: string | undefined): MapData;
+    /** Reads the tile index (0..255) at map cell (x, y). */
+    getTile(x: number, y: number): number;
+    /** Writes the tile index (0..255) at map cell (x, y). */
+    setTile(x: number, y: number, value: number): void;
+    /** Reads one full map row (128 tile indices) at row `y`. */
+    getRow(y: number): number[];
+    /**
+     * Counts non-zero tiles across a half-open row range `[start, end)`, clamped
+     * to the stored `__map__` rows (0..31). Shared-bank rows (32..63) that the
+     * text `__map__` does not store contribute zero. This is the primitive the
+     * gfx/map overlap smart-refuse uses to decide whether a shared-bank sprite
+     * write would clobber real map data.
+     */
+    nonZeroTilesInRows(start: number, end: number): number;
+    /** Serializes the grid back to a `__map__` body (32 lines of 256 hex chars). */
+    toBody(): string;
+    /** Writes the grid back into the cart's `__map__` section. */
+    commit(cart: Cart): void;
+    private assertCell;
+}
+//# sourceMappingURL=map.d.ts.map

package/dist/engine/cart/map.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"map.d.ts","sourceRoot":"","sources":["../../../src/engine/cart/map.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAC,IAAI,EAAC,MAAM,WAAW,CAAC;AAGpC;;;;;;;;;;;;;;GAcG;AACH,eAAO,MAAM,SAAS,MAAM,CAAC;AAC7B,eAAO,MAAM,QAAQ,KAAK,CAAC;AAE3B,qBAAa,OAAO;IACnB,iEAAiE;IACjE,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAa;IAEnC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAS;IAEjC,OAAO;IAKP,mFAAmF;IACnF,MAAM,CAAC,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,SAAS,GAAG,OAAO;IAiBlD,wDAAwD;IACxD,OAAO,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,GAAG,MAAM;IAKrC,yDAAyD;IACzD,OAAO,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,IAAI;IASlD,4DAA4D;IAC5D,MAAM,CAAC,CAAC,EAAE,MAAM,GAAG,MAAM,EAAE;IAO3B;;;;;;OAMG;IACH,kBAAkB,CAAC,KAAK,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,MAAM;IAStD,gFAAgF;IAChF,MAAM,IAAI,MAAM;IAWhB,8DAA8D;IAC9D,MAAM,CAAC,IAAI,EAAE,IAAI,GAAG,IAAI;IAIxB,OAAO,CAAC,UAAU;CAclB"}