picopilot 0.0.0 → 0.1.1

package/dist/engine/audio/section.js

@@ -0,0 +1,67 @@
+import { SFX_ROW_LENGTH } from './sfx.js';
+/**
+ * The number of SFX slots a cart holds (finding: 64 SFX, indices 0..63).
+ */
+export const SFX_SLOT_COUNT = 64;
+/** An all-zero `__sfx__` row (168 chars): the canonical "empty slot". */
+const EMPTY_ROW = '0'.repeat(SFX_ROW_LENGTH);
+/**
+ * Merges one transpiled `__sfx__` row into slot `slot` (0..63) of a cart's
+ * `__sfx__` section, leaving every other slot BYTE-IDENTICAL, and commits it
+ * back through the cart model (so all other sections stay untouched).
+ *
+ * PICO-8 trims trailing all-zero SFX rows on save, so a cart's `__sfx__` body
+ * may have FEWER than 64 lines (or be absent). This pads with empty rows up to
+ * the target slot as needed, replaces the target, and drops trailing empty rows
+ * again so the result matches what PICO-8 would write (a stable round-trip).
+ *
+ * The `__sfx__` body's newline style + trailing-newline are preserved from the
+ * existing section (defaulting to `\n` with a terminating newline, matching what
+ * PICO-8 writes).
+ */
+export function mergeSfxRow(cart, slot, row) {
+    if (!Number.isInteger(slot) || slot < 0 || slot >= SFX_SLOT_COUNT) {
+        throw new RangeError(`SFX slot ${slot} out of range 0..${SFX_SLOT_COUNT - 1}`);
+    }
+    if (row.length !== SFX_ROW_LENGTH) {
+        throw new RangeError(`SFX row must be ${SFX_ROW_LENGTH} hex chars, got ${row.length}`);
+    }
+    const body = cart.getSection('sfx');
+    const newline = body !== undefined && /\r\n/.test(body) ? '\r\n' : '\n';
+    // Parse existing rows (ignoring blank/trailing lines the split produces).
+    const existing = body === undefined
+        ? []
+        : body.split(/\r?\n/).filter((line) => line.length > 0);
+    // Grow to include the target slot, padding intermediate slots with empties.
+    const rows = existing.slice();
+    while (rows.length <= slot)
+        rows.push(EMPTY_ROW);
+    rows[slot] = row;
+    // Trim trailing all-zero rows (what PICO-8 does on save) so the body is the
+    // canonical minimal form; a cart with only slot 0 authored stays one line.
+    while (rows.length > 0 && rows[rows.length - 1] === EMPTY_ROW)
+        rows.pop();
+    const newBody = rows.length === 0 ? '' : rows.join(newline) + newline;
+    cart.setSection('sfx', newBody);
+}
+/**
+ * Replaces a cart's `__music__` section with a transpiled body, leaving every
+ * OTHER section (including `__sfx__`) BYTE-IDENTICAL, and commits it back through
+ * the cart model.
+ *
+ * Unlike `__sfx__` (where {@link mergeSfxRow} writes ONE slot), a `music
+ * from-patterns` call authors the WHOLE song at once (an ordered pattern list is
+ * the whole `__music__`), so this REPLACES the section wholesale rather than
+ * merging a single row. The body is the codec's output (one `FF CCCCCCCC` row per
+ * pattern); this only normalises its newline style to match the cart's existing
+ * `__music__`/dominant newline so the round-trip stays stable.
+ */
+export function setMusicSection(cart, body) {
+    const existing = cart.getSection('music');
+    // Preserve the file's newline style: CRLF if the existing music section (or,
+    // absent, the codec body would already be \n) uses it. The codec emits \n.
+    const crlf = existing !== undefined && /\r\n/.test(existing);
+    const normalised = crlf ? body.replace(/\n/g, '\r\n') : body;
+    cart.setSection('music', normalised);
+}
+//# sourceMappingURL=section.js.map

package/dist/engine/audio/section.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"section.js","sourceRoot":"","sources":["../../../src/engine/audio/section.ts"],"names":[],"mappings":"AACA,OAAO,EAAC,cAAc,EAAC,MAAM,UAAU,CAAC;AAExC;;GAEG;AACH,MAAM,CAAC,MAAM,cAAc,GAAG,EAAE,CAAC;AAEjC,yEAAyE;AACzE,MAAM,SAAS,GAAG,GAAG,CAAC,MAAM,CAAC,cAAc,CAAC,CAAC;AAE7C;;;;;;;;;;;;;GAaG;AACH,MAAM,UAAU,WAAW,CAAC,IAAU,EAAE,IAAY,EAAE,GAAW;IAChE,IAAI,CAAC,MAAM,CAAC,SAAS,CAAC,IAAI,CAAC,IAAI,IAAI,GAAG,CAAC,IAAI,IAAI,IAAI,cAAc,EAAE,CAAC;QACnE,MAAM,IAAI,UAAU,CACnB,YAAY,IAAI,oBAAoB,cAAc,GAAG,CAAC,EAAE,CACxD,CAAC;IACH,CAAC;IACD,IAAI,GAAG,CAAC,MAAM,KAAK,cAAc,EAAE,CAAC;QACnC,MAAM,IAAI,UAAU,CACnB,mBAAmB,cAAc,mBAAmB,GAAG,CAAC,MAAM,EAAE,CAChE,CAAC;IACH,CAAC;IAED,MAAM,IAAI,GAAG,IAAI,CAAC,UAAU,CAAC,KAAK,CAAC,CAAC;IACpC,MAAM,OAAO,GAAG,IAAI,KAAK,SAAS,IAAI,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,IAAI,CAAC;IAExE,0EAA0E;IAC1E,MAAM,QAAQ,GACb,IAAI,KAAK,SAAS;QACjB,CAAC,CAAC,EAAE;QACJ,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,MAAM,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC;IAE1D,4EAA4E;IAC5E,MAAM,IAAI,GAAG,QAAQ,CAAC,KAAK,EAAE,CAAC;IAC9B,OAAO,IAAI,CAAC,MAAM,IAAI,IAAI;QAAE,IAAI,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC;IACjD,IAAI,CAAC,IAAI,CAAC,GAAG,GAAG,CAAC;IAEjB,4EAA4E;IAC5E,2EAA2E;IAC3E,OAAO,IAAI,CAAC,MAAM,GAAG,CAAC,IAAI,IAAI,CAAC,IAAI,CAAC,MAAM,GAAG,CAAC,CAAC,KAAK,SAAS;QAAE,IAAI,CAAC,GAAG,EAAE,CAAC;IAE1E,MAAM,OAAO,GAAG,IAAI,CAAC,MAAM,KAAK,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,OAAO,CAAC,GAAG,OAAO,CAAC;IACtE,IAAI,CAAC,UAAU,CAAC,KAAK,EAAE,OAAO,CAAC,CAAC;AACjC,CAAC;AAED;;;;;;;;;;;GAWG;AACH,MAAM,UAAU,eAAe,CAAC,IAAU,EAAE,IAAY;IACvD,MAAM,QAAQ,GAAG,IAAI,CAAC,UAAU,CAAC,OAAO,CAAC,CAAC;IAC1C,6EAA6E;IAC7E,2EAA2E;IAC3E,MAAM,IAAI,GAAG,QAAQ,KAAK,SAAS,IAAI,MAAM,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC;IAC7D,MAAM,UAAU,GAAG,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC,OAAO,CAAC,KAAK,EAAE,MAAM,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC;IAC7D,IAAI,CAAC,UAAU,CAAC,OAAO,EAAE,UAAU,CAAC,CAAC;AACtC,CAAC"}

package/dist/engine/audio/sfx.d.ts

@@ -0,0 +1,141 @@
+/**
+ * `engine/audio` — the shrinko-free picopilot-MML to `__sfx__` codec.
+ *
+ * This module OWNS the picopilot-MML dialect and its transpilation into ONE
+ * `__sfx__` text row (the friendly text surface PICO-8 serializes, NOT the
+ * scattered RAM bit-packing). It is the greenfield/algorithmic seam of the audio
+ * path; the `sfx from-mml` command is thin wiring over {@link mmlToSfxRow}.
+ *
+ * The mapping is the CLOSED spec from the ADR-0005 spike, verified byte-for-byte
+ * against PICO-8 v0.2.7:
+ * `work/notes/findings/pico8-audio-sfx-music-layout-and-mml-subset.md` (Part A =
+ * the `__sfx__` text layout; Part B = the picopilot-MML grammar + mapping).
+ *
+ * The KEY reframe (finding B.4 / B.7 #1): PICO-8 has NO per-note duration or
+ * tempo. Every note occupies exactly one tracker ROW; all rows share ONE
+ * SFX-level `speed`. A picopilot-MML length is therefore a ROW COUNT, not a
+ * musical fraction, and there is no tempo/BPM token. Holding a note for M rows
+ * re-emits the same note in the following (M-1) rows (PICO-8 has no cross-row
+ * sustain bit).
+ *
+ * Out-of-range pitch and >32 rows are STRUCTURED ERRORS ({@link AudioMmlError}),
+ * never silent clamps: a silent clamp produces wrong-sounding music the author
+ * cannot see (finding B.2 / B.4, matching picopilot's smart-refuse philosophy).
+ *
+ * SFX-level FILTER directives (finding A.7): `!noiz !buzz !detune1/!detune2
+ * !reverb[1|2] !dampen[1|2]` set PICO-8's 5 per-SFX filters (the first header
+ * byte), reaching the class of DESIGNED sounds (explosion = DAMPEN body + REVERB
+ * tail, engine hum, pad) that no per-note pitch/waveform/volume MML can
+ * synthesize. `!`-prefixed keywords never collide with the note grammar (unlike
+ * the rejected bare-letter effect mnemonics, ADR-0008). A bad DAMPEN/REVERB level
+ * is a structured refusal, never a clamp.
+ */
+/** A `__sfx__` row is exactly this many hex chars: 8 header + 32 notes x 5. */
+export declare const SFX_ROW_LENGTH = 168;
+/** The number of tracker rows (notes) in one SFX. A hard PICO-8 limit. */
+export declare const SFX_MAX_ROWS = 32;
+/** The lowest representable pitch: C0 = 0 (finding A.2 / B.2). */
+export declare const PITCH_MIN = 0;
+/** The highest representable pitch: D#5 = 63 (finding A.2 / B.2). */
+export declare const PITCH_MAX = 63;
+/** The default octave when none is set (`o2`, pitch 24 = C2; finding B.2). */
+export declare const DEFAULT_OCTAVE = 2;
+/** The default SFX speed (ticks/row) when `s<N>` is omitted (finding B.5). */
+export declare const DEFAULT_SPEED = 16;
+/** The default note length in tracker rows (one row; finding B.4). */
+export declare const DEFAULT_LENGTH = 1;
+/**
+ * The per-SFX FILTER switches (finding A.7). They live in the FIRST header byte
+ * of the `__sfx__` row (the `[0:2]` hex pair, the byte A.1 called "editor mode"):
+ * an 8-bit bitfield whose LOW bit is the cosmetic pitch/tracker mode flag and
+ * whose upper 7 bits are the filters. picopilot emits mode 0 (pitch mode), so the
+ * byte is exactly the OR of the selected filter values below.
+ *
+ * Decoded byte-for-byte on PICO-8 v0.2.7 by poke-and-readback + single-bit audio
+ * diff (finding A.7). NOIZ applies only to instrument 6 (`@6`, manual);
+ * DAMPEN/REVERB have 2 levels each (`!dampen`/`!dampen2`, `!reverb`/`!reverb2`).
+ */
+export declare const FILTER_NOIZ = 2;
+export declare const FILTER_BUZZ = 4;
+export declare const FILTER_DETUNE_1 = 8;
+export declare const FILTER_DETUNE_2 = 16;
+/** REVERB (echo) switch (`0x20`); see the level note below (finding A.7). */
+export declare const FILTER_REVERB = 32;
+/**
+ * DAMPEN (low-pass) level 1 (`0x80`) and level 2 (`0xc0`); 0 = off (finding
+ * A.7). Verified progressive: `0xc0` low-passes strictly more than `0x80`.
+ */
+export declare const FILTER_DAMPEN_LEVEL: readonly [0, 128, 192];
+/** The highest level DAMPEN (`!dampen<N>`) accepts (finding A.7). */
+export declare const FILTER_MAX_LEVEL = 2;
+/** Machine-readable reason a picopilot-MML string could not be transpiled. */
+export type AudioMmlErrorCode = 
+/** A pitch fell outside C0..D#5 (0..63) (finding B.2). */
+'audio-mml-pitch-out-of-range'
+/** The accumulated tracker rows exceeded the 32-row SFX cap (finding B.4). */
+ | 'audio-mml-sfx-overflow'
+/** A `!dampen<N>`/`!reverb<N>` level fell outside 1..2 (finding A.7). */
+ | 'audio-mml-filter-level-out-of-range'
+/** The MML text is syntactically malformed (a token we cannot parse). */
+ | 'audio-mml-parse-error';
+/**
+ * A structured picopilot-MML transpile failure. Carries a machine-readable
+ * `code` (surfaced by the command as incur's `error({code,...})` envelope) plus
+ * a human-readable, actionable `message`. Never thrown for a case the spec
+ * defines a clamp/round for; only the genuine refusals + parse errors.
+ */
+export declare class AudioMmlError extends Error {
+    readonly code: AudioMmlErrorCode;
+    constructor(code: AudioMmlErrorCode, message: string);
+}
+/** A rounding note surfaced to the caller (a dotted length that was not integral). */
+export interface RowRoundingWarning {
+    /** The picopilot-MML token whose row count was rounded, e.g. `c4.`. */
+    token: string;
+    /** The exact (fractional) row count the length + dots computed. */
+    exactRows: number;
+    /** The integer row count actually emitted (nearest, min 1). */
+    roundedRows: number;
+}
+/** The successful result of transpiling picopilot-MML to one `__sfx__` row. */
+export interface SfxTranspileResult {
+    /** The `__sfx__` text row: exactly {@link SFX_ROW_LENGTH} hex chars. */
+    row: string;
+    /** The number of tracker rows the MML produced (0..32). */
+    rows: number;
+    /** The SFX speed (ticks/row) written into the header (1..255). */
+    speed: number;
+    /** The header loop-start value (row index, or a LEN; finding A.1 / B.5). */
+    loopStart: number;
+    /** The header loop-end value (0 when off or in the LEN special case). */
+    loopEnd: number;
+    /**
+     * The per-SFX FILTER byte (the first header byte, finding A.7): the OR of the
+     * selected filter values, with the low mode bit 0. 0 = no filters.
+     */
+    filters: number;
+    /** Any dotted-length rows that had to be rounded to a whole row. */
+    roundingWarnings: RowRoundingWarning[];
+}
+/**
+ * Transpiles a picopilot-MML string into ONE `__sfx__` text row (finding Part
+ * A/B). Emits the friendly text nibbles directly.
+ *
+ * Modal state model (finding B.1): `@<hex>` waveform, `v<0-7>` volume,
+ * `e<0-7>`/mnemonic effect, `o<0-5>` octave, `l<N>` default length, `>`/`<`
+ * octave shift, all sticky. A bare note emits one row using the current state.
+ *
+ * SFX-level directives (finding B.5): `s<N>` speed (default 16), `{`/`}` loop
+ * markers (single `{` = the LEN special case).
+ *
+ * Durations are TRACKER ROWS (finding B.4): a length `N` = N rows, emitted as
+ * the note then `(N-1)` tie rows re-striking it; `.` multiplies by 1.5 (rounded
+ * to the nearest whole row, warned); `r` = silent rows; `^` extends the previous
+ * note.
+ *
+ * @throws {AudioMmlError} `audio-mml-pitch-out-of-range` (a note below C0 / above
+ *   D#5), `audio-mml-sfx-overflow` (>32 rows), or `audio-mml-parse-error` (a
+ *   token that cannot be parsed, incl. a tempo-style input).
+ */
+export declare function mmlToSfxRow(mml: string): SfxTranspileResult;
+//# sourceMappingURL=sfx.d.ts.map

package/dist/engine/audio/sfx.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sfx.d.ts","sourceRoot":"","sources":["../../../src/engine/audio/sfx.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AAEH,+EAA+E;AAC/E,eAAO,MAAM,cAAc,MAAM,CAAC;AAElC,0EAA0E;AAC1E,eAAO,MAAM,YAAY,KAAK,CAAC;AAE/B,kEAAkE;AAClE,eAAO,MAAM,SAAS,IAAI,CAAC;AAE3B,qEAAqE;AACrE,eAAO,MAAM,SAAS,KAAK,CAAC;AAE5B,8EAA8E;AAC9E,eAAO,MAAM,cAAc,IAAI,CAAC;AAEhC,8EAA8E;AAC9E,eAAO,MAAM,aAAa,KAAK,CAAC;AAEhC,sEAAsE;AACtE,eAAO,MAAM,cAAc,IAAI,CAAC;AAEhC;;;;;;;;;;GAUG;AACH,eAAO,MAAM,WAAW,IAAO,CAAC;AAChC,eAAO,MAAM,WAAW,IAAO,CAAC;AAChC,eAAO,MAAM,eAAe,IAAO,CAAC;AACpC,eAAO,MAAM,eAAe,KAAO,CAAC;AACpC,6EAA6E;AAC7E,eAAO,MAAM,aAAa,KAAO,CAAC;AAClC;;;GAGG;AACH,eAAO,MAAM,mBAAmB,wBAA8B,CAAC;AAE/D,qEAAqE;AACrE,eAAO,MAAM,gBAAgB,IAAI,CAAC;AAyBlC,8EAA8E;AAC9E,MAAM,MAAM,iBAAiB;AAC5B,0DAA0D;AACxD,8BAA8B;AAChC,8EAA8E;GAC5E,wBAAwB;AAC1B,yEAAyE;GACvE,qCAAqC;AACvC,yEAAyE;GACvE,uBAAuB,CAAC;AAE3B;;;;;GAKG;AACH,qBAAa,aAAc,SAAQ,KAAK;IACvC,QAAQ,CAAC,IAAI,EAAE,iBAAiB,CAAC;gBAErB,IAAI,EAAE,iBAAiB,EAAE,OAAO,EAAE,MAAM;CAKpD;AAcD,sFAAsF;AACtF,MAAM,WAAW,kBAAkB;IAClC,uEAAuE;IACvE,KAAK,EAAE,MAAM,CAAC;IACd,mEAAmE;IACnE,SAAS,EAAE,MAAM,CAAC;IAClB,+DAA+D;IAC/D,WAAW,EAAE,MAAM,CAAC;CACpB;AAED,+EAA+E;AAC/E,MAAM,WAAW,kBAAkB;IAClC,wEAAwE;IACxE,GAAG,EAAE,MAAM,CAAC;IACZ,2DAA2D;IAC3D,IAAI,EAAE,MAAM,CAAC;IACb,kEAAkE;IAClE,KAAK,EAAE,MAAM,CAAC;IACd,4EAA4E;IAC5E,SAAS,EAAE,MAAM,CAAC;IAClB,yEAAyE;IACzE,OAAO,EAAE,MAAM,CAAC;IAChB;;;OAGG;IACH,OAAO,EAAE,MAAM,CAAC;IAChB,oEAAoE;IACpE,gBAAgB,EAAE,kBAAkB,EAAE,CAAC;CACvC;AAWD;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,WAAW,CAAC,GAAG,EAAE,MAAM,GAAG,kBAAkB,CAkP3D"}