picopilot 0.0.0 → 0.1.1

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

@@ -0,0 +1 @@
+{"version":3,"file":"render.d.ts","sourceRoot":"","sources":["../../../src/engine/gfx/render.ts"],"names":[],"mappings":"AAAA,OAAO,EAGN,KAAK,QAAQ,EAGb,MAAM,kBAAkB,CAAC;AAE1B,OAAO,EAAY,KAAK,QAAQ,EAAC,MAAM,UAAU,CAAC;AAElD;;;;;;;;;;;;;;;GAeG;AAEH,uEAAuE;AACvE,eAAO,MAAM,mBAAmB,KAAK,CAAC;AAEtC,4EAA4E;AAC5E,eAAO,MAAM,kBAAkB,IAAI,CAAC;AAEpC,oEAAoE;AACpE,eAAO,MAAM,gBAAgB,MAAM,CAAC;AAEpC;;;GAGG;AACH,wBAAgB,eAAe,CAAC,KAAK,EAAE,QAAQ,EAAE,CAAC,EAAE,MAAM,GAAG,UAAU,CAUtE;AAED;;;GAGG;AACH,wBAAgB,cAAc,CAAC,KAAK,EAAE,QAAQ,GAAG,UAAU,CAS1D;AAED;;;;;GAKG;AACH,wBAAgB,OAAO,CACtB,QAAQ,EAAE,MAAM,EAChB,SAAS,EAAE,MAAM,EACjB,QAAQ,EAAE,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,KAAK,MAAM,EAC1C,KAAK,EAAE,MAAM,GACX,QAAQ,CA2BV"}

package/dist/engine/gfx/render.js

@@ -0,0 +1,72 @@
+import { GFX_HEIGHT, GFX_WIDTH, SPRITE_SIZE, spriteOrigin, } from '../cart/index.js';
+import { paletteColor } from './palette.js';
+import { encodePng } 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, n) {
+    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) {
+    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, srcHeight, getIndex, scale) {
+    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 };
+}
+//# sourceMappingURL=render.js.map

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

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

package/dist/engine/index.d.ts

@@ -0,0 +1,22 @@
+/**
+ * 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';
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/engine/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AACH,cAAc,kBAAkB,CAAC;AACjC,cAAc,iBAAiB,CAAC;AAChC,cAAc,kBAAkB,CAAC;AACjC,cAAc,oBAAoB,CAAC"}

package/dist/engine/index.js

@@ -0,0 +1,22 @@
+/**
+ * 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';
+//# sourceMappingURL=index.js.map

package/dist/engine/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/engine/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AACH,cAAc,kBAAkB,CAAC;AACjC,cAAc,iBAAiB,CAAC;AAChC,cAAc,kBAAkB,CAAC;AACjC,cAAc,oBAAoB,CAAC"}

package/dist/engine/pico8/adapter.d.ts

@@ -0,0 +1,267 @@
+/**
+ * The PICO-8 adapter SEAM: the typed interface `picopilot run` talks to, plus
+ * the structured result shapes. Mirrors the `engine/shrinko` seam (ADR-0002):
+ * the command layer never knows HOW PICO-8 is launched; it talks to
+ * {@link Pico8Adapter}, and PICO-8 being ABSENT is a first-class value
+ * (`{ok:false, reason:'pico8-not-found', ...}`), never a throw or a hollow
+ * success. The v1 implementation shells out to the user's native `pico8 -x`
+ * (see `shell.ts` and ADR-0006, native path first); a future web-export /
+ * headless-browser implementation can satisfy the SAME interface.
+ *
+ * PICO-8 is a licensed, paid binary with no pip/npm install path, so absence is
+ * a normal, well-signposted boundary (US #14, #19), mirroring shrinko-not-found.
+ */
+/** The remedy string in a pico8-not-found result: how the user makes `run` work. */
+export declare const PICO8_REMEDY: "set PICO8_PATH or install PICO-8";
+/** What `run` needs: the PICO-8 binary (a paid, licensed download; no package manager). */
+export declare const PICO8_NEEDS: readonly ["pico8"];
+/** The default done-sentinel: the cart prints this via `printh` to signal it is finished. */
+export declare const DONE_SENTINEL: "__PICOPILOT_DONE__";
+/**
+ * The structured "PICO-8 is not installed" failure (US #19, ADR-0006). Shape
+ * mirrors {@link import('../shrinko/adapter.js').ShrinkoNotFound}: `ok:false`, a
+ * machine-readable `reason`, the EXACT `remedy`, and the `needs` list. A command
+ * maps it onto incur's `error({ code: reason, ... })` with a nonzero exit.
+ */
+export interface Pico8NotFound {
+    readonly ok: false;
+    readonly reason: 'pico8-not-found';
+    readonly remedy: typeof PICO8_REMEDY;
+    readonly needs: readonly string[];
+}
+/** Why a run ended: the cart signalled done, the backstop fired, or PICO-8 exited on its own. */
+export type ExitReason = 'sentinel' | 'timeout' | 'exit';
+/**
+ * A completed run's collected results. `screenshots` are the PNG paths PICO-8
+ * wrote into the run-controlled `-desktop` dir (via the cart's `extcmd("screen")`);
+ * `printh` is the captured stdout (the cart's `printh` output plus PICO-8's own
+ * lines); `exitReason` says how it ended.
+ */
+export interface RunReport {
+    readonly screenshots: readonly string[];
+    readonly printh: string;
+    readonly exitReason: ExitReason;
+}
+/** A successful adapter call carrying the run report. */
+export interface Pico8Ok {
+    readonly ok: true;
+    readonly value: RunReport;
+}
+/**
+ * The result {@link Pico8Adapter.run} returns: either a {@link RunReport} or the
+ * structured {@link Pico8NotFound}. Absence is a value, not a throw, so the
+ * two-tier capability contract is total and type-checked at the call site.
+ */
+export type Pico8Result = Pico8Ok | Pico8NotFound;
+/**
+ * A completed audio-RECORDING run's results (ADR-0009). `wavPath` is the WAV the
+ * cart wrote via `extcmd("audio_end", 1)` into the run-controlled folder (the
+ * `audio_end(1)`-to-current-folder quirk, isolated to a temp `wavDir`), or
+ * `undefined` if none was produced (e.g. a headless `-x` capture, which yields a
+ * silent 0-frame file we treat as "no usable WAV", or a run that never recorded).
+ * `printh` + `exitReason` mirror {@link RunReport}, so a recording is a run with a
+ * WAV alongside the same run state.
+ */
+export interface RecordReport {
+    readonly wavPath: string | undefined;
+    readonly printh: string;
+    readonly exitReason: ExitReason;
+}
+/** A successful audio-record call carrying the {@link RecordReport}. */
+export interface Pico8RecordOk {
+    readonly ok: true;
+    readonly value: RecordReport;
+}
+/**
+ * A completed DRIVE run's results (ADR-0011, `playtest`). Same shape family as
+ * {@link RunReport}: `screenshots` are the PNGs the driven cart wrote at the SHOT
+ * points (named `<basename>0.png`, ...), `printh` is the captured stdout (the
+ * cart's ACKs + the done-sentinel + any cart printh), `exitReason` says how it
+ * ended. A driven run is a run whose input + frame loop the harness owned.
+ */
+export interface DriveReport {
+    readonly screenshots: readonly string[];
+    readonly printh: string;
+    readonly exitReason: ExitReason;
+}
+/** A successful drive call carrying the {@link DriveReport}. */
+export interface Pico8DriveOk {
+    readonly ok: true;
+    readonly value: DriveReport;
+}
+/**
+ * The result {@link Pico8Adapter.drive} returns: a {@link DriveReport} or the
+ * structured {@link Pico8NotFound} (PICO-8 absent), mirroring {@link Pico8Result}.
+ */
+export type Pico8DriveResult = Pico8DriveOk | Pico8NotFound;
+/**
+ * Options for a single {@link Pico8Adapter.drive} (ADR-0011). The cart is the
+ * THROWAWAY driven cart the drive-transform produced; `blocks` are the encoded
+ * FIXED-SIZE command blocks piped to its live `-x` stdin (the load-bearing
+ * transport: small unpadded writes coalesce/drop, so the whole block stream is
+ * written up front for the one-shot). Screenshots land in `shotDir` (`-desktop`).
+ */
+export interface DriveOptions {
+    /** Absolute path to the throwaway driven `.p8` cart to run. */
+    readonly cartPath: string;
+    /** The run-controlled dir PICO-8 writes screenshots into (`-desktop <dir>`). */
+    readonly shotDir: string;
+    /** The encoded fixed-size command blocks to pipe to the cart's stdin. */
+    readonly blocks: Uint8Array;
+    /** The stdout line that ends the run when matched (defaults to {@link DONE_SENTINEL}). */
+    readonly sentinel?: string;
+    /** The hard backstop in ms: kill PICO-8 if it neither signals nor exits by then. */
+    readonly backstopMs: number;
+}
+/**
+ * The result {@link Pico8Adapter.record} returns: a {@link RecordReport} or the
+ * structured {@link Pico8NotFound} (PICO-8 absent), mirroring {@link Pico8Result}.
+ */
+export type Pico8RecordResult = Pico8RecordOk | Pico8NotFound;
+/**
+ * Options for a single {@link Pico8Adapter.record} (ADR-0009). The recorded cart
+ * is expected to COOPERATE: at start it does `extcmd("set_filename", <base>)` +
+ * `extcmd("audio_rec")`, and when finished `extcmd("audio_end", 1)` (save to the
+ * current folder) then `printh` the sentinel. For `audio record <cart>` the
+ * caller injects that harness around the user's cart; for `audio render` the
+ * whole harness cart is built by {@link import('./harness.js')}.
+ */
+export interface RecordOptions {
+    /** Absolute path to the `.p8` cart to run and record. */
+    readonly cartPath: string;
+    /**
+     * The run-controlled folder PICO-8 records the WAV into. Because
+     * `extcmd("audio_end", 1)` saves to PICO-8's CURRENT folder (NOT `-desktop`),
+     * the adapter points PICO-8's `root_path` here so the WAV lands in an isolated
+     * temp dir, never `~/Desktop` or the carts root (the shared-write discipline).
+     */
+    readonly wavDir: string;
+    /**
+     * The base filename (no extension) the cart passed to `extcmd("set_filename")`,
+     * so the adapter knows which `<base>.wav` to collect. Defaults to
+     * {@link RECORD_WAV_BASENAME} when omitted.
+     */
+    readonly wavBasename?: string;
+    /** The stdout line that ends the run when matched (defaults to {@link DONE_SENTINEL}). */
+    readonly sentinel?: string;
+    /** The hard backstop in ms: kill PICO-8 if it neither signals nor exits by then. */
+    readonly backstopMs: number;
+}
+/**
+ * A completed EXPORT run's results (the PICO-8 HTML export, `pico8 <cart>
+ * -export <name>.html -x`). PICO-8 writes a pair into the output dir: the shell
+ * page (`<name>.html`, which references its sibling by name) and the
+ * Emscripten runtime + baked-in cart payload (`<name>.js`). `htmlPath` is the
+ * shell page (undefined for a payload-only export that keeps only the runtime);
+ * `jsPath` is the runtime payload; `files` lists every produced file (absolute).
+ * `labelWarning` surfaces PICO-8's "please capture a label first" notice: a
+ * labelless cart exports with an ugly/blank splash (a soft warning, not a
+ * failure).
+ */
+export interface ExportReport {
+    readonly htmlPath: string | undefined;
+    readonly jsPath: string | undefined;
+    readonly files: readonly string[];
+    readonly labelWarning: boolean;
+}
+/** A successful export call carrying the {@link ExportReport}. */
+export interface Pico8ExportOk {
+    readonly ok: true;
+    readonly value: ExportReport;
+}
+/**
+ * The result {@link Pico8Adapter.export} returns: an {@link ExportReport} or the
+ * structured {@link Pico8NotFound} (PICO-8 absent), mirroring {@link Pico8Result}.
+ */
+export type Pico8ExportResult = Pico8ExportOk | Pico8NotFound;
+/**
+ * Options for a single {@link Pico8Adapter.export}. PICO-8 derives the produced
+ * file names from `htmlName` (`game.html` -> `game.html` + `game.js`), so the
+ * command passes `index.html` to get a directly-serveable `index.html` +
+ * `index.js` pair in `outDir`. `payloadOnly` keeps only the `.js` runtime
+ * payload (dropping the shell page) for a website that provides its OWN player
+ * shell (a Svelte component), never the PICO-8 binary's concern: the split is a
+ * post-export file operation the command owns.
+ */
+export interface ExportOptions {
+    /** Absolute path to the `.p8` cart to export. */
+    readonly cartPath: string;
+    /** The run-controlled dir PICO-8 writes the export pair into. */
+    readonly outDir: string;
+    /**
+     * The `.html` name handed to `-export` (e.g. `index.html`); PICO-8 derives the
+     * sibling `.js` from it. Defaults to {@link EXPORT_HTML_NAME}.
+     */
+    readonly htmlName?: string;
+    /** The hard backstop in ms: kill PICO-8 if the export neither completes nor exits. */
+    readonly backstopMs: number;
+}
+/** The default `.html` name `export` hands to `-export`: yields a serveable `index.html` + `index.js`. */
+export declare const EXPORT_HTML_NAME: "index.html";
+/** Options for a single {@link Pico8Adapter.run}. */
+export interface RunOptions {
+    /** Absolute path to the `.p8` cart to run. */
+    readonly cartPath: string;
+    /** The run-controlled dir PICO-8 writes screenshots into (`-desktop <dir>`). */
+    readonly shotDir: string;
+    /** The stdout line that ends the run when matched (defaults to {@link DONE_SENTINEL}). */
+    readonly sentinel?: string;
+    /** The hard backstop in ms: kill PICO-8 if it neither signals nor exits by then. */
+    readonly backstopMs: number;
+    /**
+     * Optional one-shot scripted input passed as `-p <input>`; the cart reads it
+     * via `stat(6)` and replays it (the canned-playtest channel). The cart must
+     * cooperate by decoding `stat(6)` (taught in the `picopilot-debug` skill).
+     * Absent = no input passed.
+     */
+    readonly input?: string;
+}
+/**
+ * The PICO-8 capability seam. One method for now: {@link run}. Later PICO-8-gated
+ * operations (`audio render`, `export`) extend THIS interface rather than forking.
+ */
+export interface Pico8Adapter {
+    /**
+     * Launches PICO-8 on `cartPath`, streams stdout, ends the run on the sentinel
+     * (with the backstop as the safety net), and collects screenshots + printh +
+     * exit reason. Returns {@link Pico8NotFound} when PICO-8 is not installed.
+     */
+    run(options: RunOptions): Promise<Pico8Result>;
+    /**
+     * Launches PICO-8 on `cartPath` in a REAL audio+video session (NOT headless
+     * `-x`, which mixes no audio and yields an empty WAV, ADR-0009), streams
+     * stdout, ends on the sentinel (backstop as the net), and collects the WAV the
+     * cooperating cart wrote via `audio_rec`/`audio_end(1)`. Returns
+     * {@link Pico8NotFound} when PICO-8 is not installed. Live capture is a
+     * manual/opt-in tier; CI drives a fake runner + the absent boundary.
+     */
+    record(options: RecordOptions): Promise<Pico8RecordResult>;
+    /**
+     * Launches PICO-8 on the THROWAWAY driven cart (`-desktop <shotDir> -x`),
+     * pipes the encoded FIXED-SIZE command blocks to its live stdin (the input +
+     * frame-loop transport, ADR-0011), ends on the sentinel (backstop as the net),
+     * and collects the SHOT screenshots + printh + exit reason. Returns
+     * {@link Pico8NotFound} when PICO-8 is absent. Live drive-and-capture is a
+     * manual/opt-in tier; CI drives a fake runner + the absent boundary.
+     */
+    drive(options: DriveOptions): Promise<Pico8DriveResult>;
+    /**
+     * Exports `cartPath` as a PICO-8 HTML bundle (`pico8 <cart> -export
+     * <outDir>/<htmlName> -x`, the HEADLESS `-x` path, no display needed) and
+     * collects the produced `.html` + `.js` pair from `outDir`. Returns
+     * {@link Pico8NotFound} when PICO-8 is absent (the CI-testable boundary). Live
+     * export is a manual/opt-in tier: it hard-requires the paid binary, and a
+     * labelless cart exports with a `labelWarning` set (a soft warning, not a
+     * failure). The command owns any post-export payload-only file split.
+     */
+    export(options: ExportOptions): Promise<Pico8ExportResult>;
+}
+/** The default WAV basename a recorded cart passes to `extcmd("set_filename")`. */
+export declare const RECORD_WAV_BASENAME: "picopilot-audio";
+/** The 60 audio ticks PICO-8 advances per second: the record-duration unit (finding). */
+export declare const PICO8_TICKS_PER_SECOND = 120;
+/** The video frames PICO-8 runs per second (`_update` at 30fps; `t` counts frames). */
+export declare const PICO8_FRAMES_PER_SECOND = 30;
+/** The frozen {@link Pico8NotFound} value, so every call site returns the same shape. */
+export declare function pico8NotFound(): Pico8NotFound;
+//# sourceMappingURL=adapter.d.ts.map

package/dist/engine/pico8/adapter.d.ts.map

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

package/dist/engine/pico8/adapter.js

@@ -0,0 +1,37 @@
+/**
+ * The PICO-8 adapter SEAM: the typed interface `picopilot run` talks to, plus
+ * the structured result shapes. Mirrors the `engine/shrinko` seam (ADR-0002):
+ * the command layer never knows HOW PICO-8 is launched; it talks to
+ * {@link Pico8Adapter}, and PICO-8 being ABSENT is a first-class value
+ * (`{ok:false, reason:'pico8-not-found', ...}`), never a throw or a hollow
+ * success. The v1 implementation shells out to the user's native `pico8 -x`
+ * (see `shell.ts` and ADR-0006, native path first); a future web-export /
+ * headless-browser implementation can satisfy the SAME interface.
+ *
+ * PICO-8 is a licensed, paid binary with no pip/npm install path, so absence is
+ * a normal, well-signposted boundary (US #14, #19), mirroring shrinko-not-found.
+ */
+/** The remedy string in a pico8-not-found result: how the user makes `run` work. */
+export const PICO8_REMEDY = 'set PICO8_PATH or install PICO-8';
+/** What `run` needs: the PICO-8 binary (a paid, licensed download; no package manager). */
+export const PICO8_NEEDS = ['pico8'];
+/** The default done-sentinel: the cart prints this via `printh` to signal it is finished. */
+export const DONE_SENTINEL = '__PICOPILOT_DONE__';
+/** The default `.html` name `export` hands to `-export`: yields a serveable `index.html` + `index.js`. */
+export const EXPORT_HTML_NAME = 'index.html';
+/** The default WAV basename a recorded cart passes to `extcmd("set_filename")`. */
+export const RECORD_WAV_BASENAME = 'picopilot-audio';
+/** The 60 audio ticks PICO-8 advances per second: the record-duration unit (finding). */
+export const PICO8_TICKS_PER_SECOND = 120;
+/** The video frames PICO-8 runs per second (`_update` at 30fps; `t` counts frames). */
+export const PICO8_FRAMES_PER_SECOND = 30;
+/** The frozen {@link Pico8NotFound} value, so every call site returns the same shape. */
+export function pico8NotFound() {
+    return {
+        ok: false,
+        reason: 'pico8-not-found',
+        remedy: PICO8_REMEDY,
+        needs: [...PICO8_NEEDS],
+    };
+}
+//# sourceMappingURL=adapter.js.map

package/dist/engine/pico8/adapter.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"adapter.js","sourceRoot":"","sources":["../../../src/engine/pico8/adapter.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,oFAAoF;AACpF,MAAM,CAAC,MAAM,YAAY,GAAG,kCAA2C,CAAC;AAExE,2FAA2F;AAC3F,MAAM,CAAC,MAAM,WAAW,GAAG,CAAC,OAAO,CAAU,CAAC;AAE9C,6FAA6F;AAC7F,MAAM,CAAC,MAAM,aAAa,GAAG,oBAA6B,CAAC;AAsM3D,0GAA0G;AAC1G,MAAM,CAAC,MAAM,gBAAgB,GAAG,YAAqB,CAAC;AAiEtD,mFAAmF;AACnF,MAAM,CAAC,MAAM,mBAAmB,GAAG,iBAA0B,CAAC;AAE9D,yFAAyF;AACzF,MAAM,CAAC,MAAM,sBAAsB,GAAG,GAAG,CAAC;AAE1C,uFAAuF;AACvF,MAAM,CAAC,MAAM,uBAAuB,GAAG,EAAE,CAAC;AAE1C,yFAAyF;AACzF,MAAM,UAAU,aAAa;IAC5B,OAAO;QACN,EAAE,EAAE,KAAK;QACT,MAAM,EAAE,iBAAiB;QACzB,MAAM,EAAE,YAAY;QACpB,KAAK,EAAE,CAAC,GAAG,WAAW,CAAC;KACvB,CAAC;AACH,CAAC"}