picopilot 0.2.1 → 0.3.0

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

@@ -0,0 +1,137 @@
+/**
+ * `engine/audio`: the score to `__sfx__` + `__music__` planner (ADR-0020).
+ *
+ * A SCORE is one or more SONGS (sections of `__music__`, e.g. a title song and
+ * an in-game song), each up to 4 channels of picopilot-MML of ANY length. The
+ * planner does the bookkeeping an author used to do by hand (the conquest
+ * dogfood needed a 250-line script for it):
+ *
+ * 1. parse every channel into its tracker-row stream ({@link mmlToRows});
+ * 2. cut all channels of a song at the SAME row boundaries into patterns of
+ *    `patternRows` rows (default 32), so channels stay aligned;
+ * 3. a channel that is silent for a whole pattern becomes `null` (channel OFF),
+ *    not a silent SFX; a pattern silent on EVERY channel keeps one silent SFX on
+ *    channel 0 so it still lasts its length;
+ * 4. de-duplicate identical SFX rows across the whole score;
+ * 5. allocate slots: free (note-less) slots only, from 63 downwards, unless the
+ *    caller names an explicit slot RANGE, which the score then OWNS (it may
+ *    overwrite any slot in it and clears the slots in it it does not use);
+ * 6. lay songs out back to back in `__music__`, with loop / stop flags.
+ *
+ * Pure: cart-free inputs in, a plan out. The `music from-score` command applies
+ * the plan through the cart model (only owned `__sfx__` slots + `__music__`
+ * change).
+ */
+/** One score channel: MML text, or `{mml, filters}` where `filters` are `!` directives. */
+export type ScoreChannel = string | {
+    mml: string;
+    filters?: string;
+} | null;
+/** One song (a contiguous section of `__music__`). */
+export interface ScoreSong {
+    /** A label for the report (default `song<N>`). */
+    name?: string;
+    /** SFX speed (ticks/row) for every channel. Default: the channels' shared `s<N>`, else 16. */
+    speed?: number;
+    /** Rows per pattern, 1..32 (default 32). Under 32, each SFX carries the LEN header. */
+    patternRows?: number;
+    /** Loop the song (default true). false = the last pattern stops the music. */
+    loop?: boolean;
+    /** The pattern (0-based, within the song) the loop returns to (default 0). */
+    loopFrom?: number;
+    /** Up to 4 channels (ch0..ch3); `null` or a missing entry = no channel. */
+    channels: ScoreChannel[];
+}
+/** A whole score: the songs, laid out in this order. */
+export interface Score {
+    songs: ScoreSong[];
+}
+/** Machine-readable reason a score could not be planned. */
+export type ScoreErrorCode = 'audio-score-parse-error' | 'audio-score-empty' | 'audio-score-bad-channel-count' | 'audio-score-bad-speed' | 'audio-score-speed-mismatch' | 'audio-score-bad-pattern-rows' | 'audio-score-bad-loop-from' | 'audio-score-loop-marker' | 'audio-score-too-many-patterns' | 'audio-score-no-free-slots' | 'audio-score-bad-slot-range';
+/** A structured score refusal (mirrors {@link AudioMmlError}). */
+export declare class ScoreError extends Error {
+    readonly code: ScoreErrorCode;
+    constructor(code: ScoreErrorCode, message: string);
+}
+/** What the planner needs to know about the cart it plans for. */
+export interface ScoreCartState {
+    /** The current `__sfx__` rows, indexed by slot (missing = empty). */
+    sfxRows: readonly (string | undefined)[];
+    /** The SFX slots the cart's CURRENT `__music__` references (the song being replaced). */
+    musicRefs: ReadonlySet<number>;
+}
+/** Planner options. */
+export interface ScorePlanOptions {
+    /** An explicit inclusive slot range the score OWNS (overwrite + clear unused). */
+    slots?: {
+        from: number;
+        to: number;
+    };
+}
+/** One song as laid out in `__music__`. */
+export interface PlannedSong {
+    name: string;
+    /** The first pattern index: play it with `music(startPattern)`. */
+    startPattern: number;
+    /** The last pattern index of the song. */
+    endPattern: number;
+    patterns: number;
+    speed: number;
+    patternRows: number;
+    loop: boolean;
+    /** The absolute pattern index the loop returns to (when `loop`). */
+    loopStartPattern: number | undefined;
+    /** Play length of one pass through the song, in seconds. */
+    seconds: number;
+}
+/** One SFX slot the plan writes. */
+export interface PlannedSlot {
+    slot: number;
+    row: string;
+    /** Where the SFX is used, e.g. `title p0 ch1` (pattern index is within the song). */
+    uses: string[];
+    /** Whether the slot held DIFFERENT, non-empty content before (an overwrite). */
+    overwrote: boolean;
+}
+/** The plan: what to write into the cart, and the report. */
+export interface ScorePlan {
+    songs: PlannedSong[];
+    slots: PlannedSlot[];
+    /** Owned slots the score does not use, cleared to empty (only with a range). */
+    cleared: number[];
+    /** The `__music__` section body. */
+    musicSection: string;
+    /** Total patterns written. */
+    patterns: number;
+    /** Advisory warnings. */
+    warnings: string[];
+}
+/** An all-zero `__sfx__` row: the canonical empty slot. */
+export declare const EMPTY_SFX_ROW: string;
+/** Whether an `__sfx__` row has no notes (its 32 note slots are all zero). */
+export declare function isFreeSfxRow(row: string | undefined): boolean;
+/**
+ * Parses + validates a score from JSON-ish input. Accepts `{songs:[...]}` or a
+ * single song object (`{channels:[...]}`) as shorthand.
+ *
+ * @throws {ScoreError} `audio-score-parse-error` for a shape it cannot read.
+ */
+export declare function readScore(raw: unknown): Score;
+/**
+ * Plans a score against a cart's current audio (ADR-0020). Pure.
+ *
+ * @throws {ScoreError} a malformed score, a speed/loop conflict, more than 64
+ *   patterns, or not enough slots.
+ * @throws {AudioMmlError} a channel's MML is invalid (message names song+channel).
+ */
+export declare function planScore(score: Score, cart: ScoreCartState, options?: ScorePlanOptions): ScorePlan;
+/** Formats slot numbers compactly: `16-20,25`. */
+export declare function formatSlots(slots: readonly number[]): string;
+/**
+ * Parses a slot list like `5`, `16-63` or `3,5,16-20` into sorted unique slots.
+ * Returns `undefined` when the text is not a valid list within 0..63.
+ */
+export declare function parseSlotList(text: string): number[] | undefined;
+/** The SFX slots a `__music__` body references (on channels that are not off). */
+export declare function musicSfxRefs(body: string | undefined): Set<number>;
+//# sourceMappingURL=score.d.ts.map

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

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

package/dist/engine/audio/score.js

@@ -0,0 +1,420 @@
+/**
+ * `engine/audio`: the score to `__sfx__` + `__music__` planner (ADR-0020).
+ *
+ * A SCORE is one or more SONGS (sections of `__music__`, e.g. a title song and
+ * an in-game song), each up to 4 channels of picopilot-MML of ANY length. The
+ * planner does the bookkeeping an author used to do by hand (the conquest
+ * dogfood needed a 250-line script for it):
+ *
+ * 1. parse every channel into its tracker-row stream ({@link mmlToRows});
+ * 2. cut all channels of a song at the SAME row boundaries into patterns of
+ *    `patternRows` rows (default 32), so channels stay aligned;
+ * 3. a channel that is silent for a whole pattern becomes `null` (channel OFF),
+ *    not a silent SFX; a pattern silent on EVERY channel keeps one silent SFX on
+ *    channel 0 so it still lasts its length;
+ * 4. de-duplicate identical SFX rows across the whole score;
+ * 5. allocate slots: free (note-less) slots only, from 63 downwards, unless the
+ *    caller names an explicit slot RANGE, which the score then OWNS (it may
+ *    overwrite any slot in it and clears the slots in it it does not use);
+ * 6. lay songs out back to back in `__music__`, with loop / stop flags.
+ *
+ * Pure: cart-free inputs in, a plan out. The `music from-score` command applies
+ * the plan through the cart model (only owned `__sfx__` slots + `__music__`
+ * change).
+ */
+import { CHANNEL_OFF_BIT, patternsToMusic, MUSIC_PATTERN_MAX, } from './music.js';
+import { AudioMmlError, DEFAULT_SPEED, emitSfxRow, mmlToRows, SFX_MAX_ROWS, SFX_ROW_LENGTH, } from './sfx.js';
+/** The number of SFX slots (0..63). */
+const SLOT_COUNT = 64;
+/** PICO-8 SFX ticks per second (speed 1 = 1/120 s per row). */
+const TICKS_PER_SECOND = 120;
+/** A structured score refusal (mirrors {@link AudioMmlError}). */
+export class ScoreError extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.name = 'ScoreError';
+        this.code = code;
+    }
+}
+/** An all-zero `__sfx__` row: the canonical empty slot. */
+export const EMPTY_SFX_ROW = '0'.repeat(SFX_ROW_LENGTH);
+/** Whether an `__sfx__` row has no notes (its 32 note slots are all zero). */
+export function isFreeSfxRow(row) {
+    return row === undefined || /^0*$/.test(row.slice(8));
+}
+/**
+ * Parses + validates a score from JSON-ish input. Accepts `{songs:[...]}` or a
+ * single song object (`{channels:[...]}`) as shorthand.
+ *
+ * @throws {ScoreError} `audio-score-parse-error` for a shape it cannot read.
+ */
+export function readScore(raw) {
+    if (raw === null || typeof raw !== 'object' || Array.isArray(raw)) {
+        throw new ScoreError('audio-score-parse-error', 'a score is a JSON object: {"songs":[{"name":"title","speed":16,"channels":["<mml>","<mml>",null,null]}]} (or one song object with "channels").');
+    }
+    const obj = raw;
+    const songs = Array.isArray(obj.songs)
+        ? obj.songs
+        : Array.isArray(obj.channels)
+            ? [obj]
+            : undefined;
+    if (songs === undefined) {
+        throw new ScoreError('audio-score-parse-error', 'a score needs "songs" (an array of songs) or, for one song, "channels".');
+    }
+    if (songs.length === 0) {
+        throw new ScoreError('audio-score-empty', 'the score has no songs.');
+    }
+    return {
+        songs: songs.map((s, i) => {
+            if (s === null ||
+                typeof s !== 'object' ||
+                !Array.isArray(s.channels)) {
+                throw new ScoreError('audio-score-parse-error', `song ${i} must be an object with a "channels" array (up to 4 MML strings, {"mml","filters"} objects, or null).`);
+            }
+            const song = s;
+            if (song.loop !== undefined && typeof song.loop !== 'boolean') {
+                throw new ScoreError('audio-score-parse-error', `song ${i} "loop" must be true or false, got ${JSON.stringify(song.loop)}.`);
+            }
+            for (const [c, ch] of song.channels.entries()) {
+                const ok = ch === null ||
+                    typeof ch === 'string' ||
+                    (typeof ch === 'object' &&
+                        typeof ch.mml === 'string' &&
+                        (ch.filters === undefined ||
+                            typeof ch.filters === 'string'));
+                const filters = ch !== null && typeof ch === 'object'
+                    ? ch.filters
+                    : undefined;
+                if (ok &&
+                    filters !== undefined &&
+                    !/^\s*(![a-z]+\d?\s*)*$/i.test(filters)) {
+                    throw new ScoreError('audio-score-parse-error', `song ${i} channel ${c} "filters" may only hold ! filter directives (e.g. "!dampen !reverb"), got "${filters}". Put notes and modal settings in "mml".`);
+                }
+                if (!ok) {
+                    throw new ScoreError('audio-score-parse-error', `song ${i} channel ${c} must be an MML string, {"mml": "...", "filters": "!dampen"}, or null.`);
+                }
+            }
+            return song;
+        }),
+    };
+}
+/** Whether a run of rows is silent (every row at volume 0). */
+function isSilent(notes) {
+    return notes.every((n) => n.volume === 0);
+}
+/** A silent row (the padding past a channel's end). */
+const SILENT = { pitch: 0, waveform: 0, volume: 0, effect: 0 };
+/**
+ * Plans a score against a cart's current audio (ADR-0020). Pure.
+ *
+ * @throws {ScoreError} a malformed score, a speed/loop conflict, more than 64
+ *   patterns, or not enough slots.
+ * @throws {AudioMmlError} a channel's MML is invalid (message names song+channel).
+ */
+export function planScore(score, cart, options = {}) {
+    const warnings = [];
+    const allPatterns = [];
+    const songs = [];
+    /** Unique SFX rows, in first-use order, with their uses. */
+    const unique = new Map();
+    /** Per pattern+channel, the unique row it plays (resolved to a slot later). */
+    const channelRows = [];
+    let usesCustomInstrument = false;
+    for (const [si, song] of score.songs.entries()) {
+        const name = song.name ?? `song${si}`;
+        if (song.channels.length === 0 || song.channels.length > 4) {
+            throw new ScoreError('audio-score-bad-channel-count', `song '${name}' has ${song.channels.length} channels; PICO-8 music has 1 to 4 (ch0..ch3).`);
+        }
+        const patternRows = song.patternRows ?? SFX_MAX_ROWS;
+        if (!Number.isInteger(patternRows) ||
+            patternRows < 1 ||
+            patternRows > SFX_MAX_ROWS) {
+            throw new ScoreError('audio-score-bad-pattern-rows', `song '${name}' patternRows ${patternRows} is not a whole number in 1..${SFX_MAX_ROWS} (one SFX holds 32 rows).`);
+        }
+        // Parse every channel (no 32-row cap: the planner cuts them).
+        const parsed = [];
+        const speeds = new Set();
+        for (const [c, ch] of song.channels.entries()) {
+            if (ch === null || ch === undefined) {
+                parsed.push(null);
+                continue;
+            }
+            const text = typeof ch === 'string' ? ch : `${ch.filters ?? ''} ${ch.mml}`;
+            let rows;
+            try {
+                rows = mmlToRows(text, { maxRows: Number.POSITIVE_INFINITY });
+            }
+            catch (e) {
+                if (e instanceof AudioMmlError) {
+                    throw new AudioMmlError(e.code, `song '${name}' channel ${c}: ${e.message}`);
+                }
+                throw e;
+            }
+            if (rows.loopStartRow !== undefined || rows.loopEndRow !== undefined) {
+                throw new ScoreError('audio-score-loop-marker', `song '${name}' channel ${c} uses a '{'/'}' loop marker. In a score, looping is per SONG ("loop", "loopFrom"), not per SFX; remove the markers.`);
+            }
+            if (rows.speedSet)
+                speeds.add(rows.speed);
+            if (rows.notes.some((n) => n.waveform >= 8 && n.volume > 0)) {
+                usesCustomInstrument = true;
+            }
+            parsed.push({ notes: rows.notes, filters: rows.filters });
+        }
+        let speed;
+        if (song.speed !== undefined) {
+            if (!Number.isInteger(song.speed) || song.speed < 1 || song.speed > 255) {
+                throw new ScoreError('audio-score-bad-speed', `song '${name}' speed ${song.speed} is not a whole number in 1..255 (ticks per row).`);
+            }
+            speed = song.speed;
+            const other = [...speeds].find((s) => s !== speed);
+            if (other !== undefined) {
+                throw new ScoreError('audio-score-speed-mismatch', `song '${name}' has speed ${speed} but a channel sets s${other}. Every channel of a song shares ONE speed (patterns must stay aligned); drop the s<N> from the channel MML.`);
+            }
+        }
+        else if (speeds.size > 1) {
+            throw new ScoreError('audio-score-speed-mismatch', `song '${name}' channels set different speeds (${[...speeds].map((s) => `s${s}`).join(', ')}). Every channel of a song shares ONE speed; set "speed" on the song instead.`);
+        }
+        else {
+            speed = speeds.size === 1 ? [...speeds][0] : DEFAULT_SPEED;
+        }
+        const totalRows = Math.max(0, ...parsed.map((p) => p?.notes.length ?? 0));
+        if (totalRows === 0) {
+            throw new ScoreError('audio-score-empty', `song '${name}' has no rows on any channel.`);
+        }
+        const count = Math.ceil(totalRows / patternRows);
+        for (const [c, p] of parsed.entries()) {
+            if (p !== null && p.notes.length < totalRows) {
+                warnings.push(`song '${name}' channel ${c} is ${p.notes.length} rows, shorter than the song (${totalRows}); it is padded with silence.`);
+            }
+        }
+        if (totalRows % patternRows !== 0) {
+            warnings.push(`song '${name}' is ${totalRows} rows, not a multiple of ${patternRows}; the last pattern is padded with ${count * patternRows - totalRows} silent rows.`);
+        }
+        const loop = song.loop ?? true;
+        const loopFrom = song.loopFrom ?? 0;
+        if (!Number.isInteger(loopFrom) || loopFrom < 0 || loopFrom >= count) {
+            throw new ScoreError('audio-score-bad-loop-from', `song '${name}' loopFrom ${loopFrom} is not a pattern of the song (0..${count - 1}).`);
+        }
+        const start = allPatterns.length;
+        const lenHeader = patternRows < SFX_MAX_ROWS ? patternRows : 0;
+        for (let p = 0; p < count; p++) {
+            const refs = [];
+            for (let c = 0; c < 4; c++) {
+                const ch = parsed[c];
+                if (ch === null || ch === undefined) {
+                    refs.push(null);
+                    continue;
+                }
+                const chunk = ch.notes.slice(p * patternRows, (p + 1) * patternRows);
+                if (isSilent(chunk)) {
+                    refs.push(null);
+                    continue;
+                }
+                while (chunk.length < patternRows)
+                    chunk.push(SILENT);
+                const row = emitSfxRow({
+                    filters: ch.filters,
+                    speed,
+                    loopStart: lenHeader,
+                    loopEnd: 0,
+                    notes: chunk,
+                });
+                refs.push(row);
+                const uses = unique.get(row) ?? [];
+                uses.push(`${name} p${p} ch${c}`);
+                unique.set(row, uses);
+            }
+            if (!refs.some((r) => r !== null)) {
+                // A pattern silent on every channel still has to LAST its length:
+                // keep one silent SFX on channel 0 (PICO-8 times a pattern by its
+                // left-most playing channel).
+                const rest = emitSfxRow({
+                    speed,
+                    filters: 0,
+                    loopStart: lenHeader,
+                    loopEnd: 0,
+                    notes: [],
+                });
+                refs[0] = rest;
+                const uses = unique.get(rest) ?? [];
+                uses.push(`${name} p${p} ch0 (rest)`);
+                unique.set(rest, uses);
+            }
+            channelRows.push(refs);
+            allPatterns.push({
+                channels: [null, null, null, null],
+                ...(loop && p === loopFrom ? { loopStart: true } : {}),
+                ...(loop && p === count - 1 ? { loopBack: true } : {}),
+                ...(!loop && p === count - 1 ? { stop: true } : {}),
+            });
+        }
+        songs.push({
+            name,
+            startPattern: start,
+            endPattern: start + count - 1,
+            patterns: count,
+            speed,
+            patternRows,
+            loop,
+            loopStartPattern: loop ? start + loopFrom : undefined,
+            seconds: round2((count * patternRows * speed) / TICKS_PER_SECOND),
+        });
+    }
+    if (allPatterns.length > MUSIC_PATTERN_MAX) {
+        throw new ScoreError('audio-score-too-many-patterns', `the score needs ${allPatterns.length} patterns; __music__ holds ${MUSIC_PATTERN_MAX}. Shorten a song, or reuse material (identical patterns still take a pattern each).`);
+    }
+    // --- slot allocation --------------------------------------------------------
+    const range = options.slots;
+    if (range !== undefined) {
+        if (!Number.isInteger(range.from) ||
+            !Number.isInteger(range.to) ||
+            range.from < 0 ||
+            range.to > SLOT_COUNT - 1 ||
+            range.from > range.to) {
+            throw new ScoreError('audio-score-bad-slot-range', `slot range ${range.from}-${range.to} is not within 0-63 (from <= to).`);
+        }
+    }
+    // Stable allocation: an SFX whose exact row already sits in a usable slot
+    // keeps that slot, so re-running an unchanged score is a byte-identical
+    // no-op. With a range, "usable" is the range; without one, it is ANY slot
+    // (reusing an identical row overwrites nothing), so default-mode re-runs do
+    // not leak copies of the previous song into fresh slots.
+    const usable = (s) => range !== undefined
+        ? s >= range.from && s <= range.to
+        : !(usesCustomInstrument && s < 8); // @8-@f read SFX 0..7
+    const slotOf = new Map();
+    const taken = new Set();
+    for (const row of unique.keys()) {
+        for (let s = SLOT_COUNT - 1; s >= 0; s--) {
+            if (!taken.has(s) && usable(s) && cart.sfxRows[s] === row) {
+                slotOf.set(row, s);
+                taken.add(s);
+                break;
+            }
+        }
+    }
+    const candidates = [];
+    if (range !== undefined) {
+        for (let s = range.from; s <= range.to; s++)
+            candidates.push(s);
+    }
+    else {
+        // Free slots only, from the top down: game SFX are usually authored from
+        // slot 0 up, so music fills from 63 down and the two meet in the middle.
+        for (let s = SLOT_COUNT - 1; s >= 0; s--) {
+            if (usable(s) && isFreeSfxRow(cart.sfxRows[s]))
+                candidates.push(s);
+        }
+    }
+    const open = candidates.filter((c) => !taken.has(c));
+    const needed = unique.size - slotOf.size;
+    if (needed > open.length) {
+        throw new ScoreError('audio-score-no-free-slots', range !== undefined
+            ? `the score needs ${unique.size} distinct SFX but the slot range ${range.from}-${range.to} has ${candidates.length}. Widen the range or shorten/simplify the score.`
+            : `the score needs ${needed} more SFX slots but the cart has ${open.length} free. Pass --slots <from-to> to give the music a range it owns (it overwrites that range), clear old slots with \`sfx clear\`, or shorten the score.`);
+    }
+    if (range !== undefined && usesCustomInstrument && range.from < 8) {
+        warnings.push(`the score uses custom instruments (@8-@f = SFX 0-7) and the slot range ${range.from}-${range.to} overlaps slots 0-7: music written there would replace those instruments.`);
+    }
+    for (const row of unique.keys()) {
+        if (slotOf.has(row))
+            continue;
+        const s = open.shift();
+        slotOf.set(row, s);
+        taken.add(s);
+    }
+    const slots = [...unique.entries()]
+        .map(([row, uses]) => {
+        const slot = slotOf.get(row);
+        const before = cart.sfxRows[slot];
+        return {
+            slot,
+            row,
+            uses,
+            overwrote: !isFreeSfxRow(before) && before !== row,
+        };
+    })
+        .sort((a, b) => a.slot - b.slot);
+    const cleared = range === undefined
+        ? []
+        : candidates.filter((s) => !taken.has(s) && !isFreeSfxRow(cart.sfxRows[s]));
+    for (const [p, refs] of channelRows.entries()) {
+        allPatterns[p].channels = refs.map((r) => r === null ? null : slotOf.get(r));
+    }
+    // Slots the previous __music__ used that nothing references any more, and
+    // that we neither rewrote nor cleared: leftovers of the replaced song.
+    const nowUsed = new Set(slots.map((s) => s.slot));
+    const orphans = [...cart.musicRefs]
+        .filter((s) => !nowUsed.has(s) &&
+        !cleared.includes(s) &&
+        !isFreeSfxRow(cart.sfxRows[s]))
+        .sort((a, b) => a - b);
+    if (orphans.length > 0) {
+        warnings.push(`SFX ${formatSlots(orphans)} were used by the previous __music__ and are no longer referenced; they still hold the old song's notes. Clear them with \`sfx clear ${formatSlots(orphans)}\`, or re-run with --slots <from-to> so the score owns (and clears) its range.`);
+    }
+    const music = patternsToMusic(allPatterns);
+    warnings.push(...music.warnings.map((w) => w.message));
+    return {
+        songs,
+        slots,
+        cleared,
+        musicSection: music.section,
+        patterns: allPatterns.length,
+        warnings,
+    };
+}
+/** Rounds to 2 decimals. */
+function round2(n) {
+    return Math.round(n * 100) / 100;
+}
+/** Formats slot numbers compactly: `16-20,25`. */
+export function formatSlots(slots) {
+    const sorted = [...slots].sort((a, b) => a - b);
+    const parts = [];
+    for (let i = 0; i < sorted.length;) {
+        let j = i;
+        while (j + 1 < sorted.length && sorted[j + 1] === sorted[j] + 1)
+            j++;
+        parts.push(i === j ? `${sorted[i]}` : `${sorted[i]}-${sorted[j]}`);
+        i = j + 1;
+    }
+    return parts.join(',');
+}
+/**
+ * Parses a slot list like `5`, `16-63` or `3,5,16-20` into sorted unique slots.
+ * Returns `undefined` when the text is not a valid list within 0..63.
+ */
+export function parseSlotList(text) {
+    const out = new Set();
+    for (const part of text.split(',')) {
+        const m = /^\s*(\d+)\s*(?:-\s*(\d+)\s*)?$/.exec(part);
+        if (m === null)
+            return undefined;
+        const from = Number(m[1]);
+        const to = m[2] === undefined ? from : Number(m[2]);
+        if (from > to || to > SLOT_COUNT - 1)
+            return undefined;
+        for (let s = from; s <= to; s++)
+            out.add(s);
+    }
+    return [...out].sort((a, b) => a - b);
+}
+/** The SFX slots a `__music__` body references (on channels that are not off). */
+export function musicSfxRefs(body) {
+    const refs = new Set();
+    if (body === undefined)
+        return refs;
+    for (const line of body.split(/\r?\n/)) {
+        const m = /^[0-9a-f]{2} ([0-9a-f]{8})$/i.exec(line.trim());
+        if (m === null)
+            continue;
+        for (let c = 0; c < 4; c++) {
+            const b = Number.parseInt(m[1].slice(c * 2, c * 2 + 2), 16);
+            if ((b & CHANNEL_OFF_BIT) === 0)
+                refs.add(b & 0x3f);
+        }
+    }
+    return refs;
+}
+//# sourceMappingURL=score.js.map

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

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

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

@@ -31,4 +31,11 @@ export declare function mergeSfxRow(cart: Cart, slot: number, row: string): void
  * `__music__`/dominant newline so the round-trip stays stable.
  */
 export declare function setMusicSection(cart: Cart, body: string): void;
+/**
+ * Reads a cart's `__sfx__` section into one entry per slot (0..63); a slot past
+ * the end of the (trimmed) section is `undefined` (empty).
+ */
+export declare function readSfxRows(cart: Cart): (string | undefined)[];
+/** Clears SFX slot `slot` back to empty (the all-zero row), via {@link mergeSfxRow}. */
+export declare function clearSfxSlot(cart: Cart, slot: number): void;
 //# sourceMappingURL=section.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"section.d.ts","sourceRoot":"","sources":["../../../src/engine/audio/section.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAC,IAAI,EAAC,MAAM,kBAAkB,CAAC;AAG3C;;GAEG;AACH,eAAO,MAAM,cAAc,KAAK,CAAC;AAKjC;;;;;;;;;;;;;GAaG;AACH,wBAAgB,WAAW,CAAC,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,IAAI,CAgCvE;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,eAAe,CAAC,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,MAAM,GAAG,IAAI,CAO9D"}
+{"version":3,"file":"section.d.ts","sourceRoot":"","sources":["../../../src/engine/audio/section.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAC,IAAI,EAAC,MAAM,kBAAkB,CAAC;AAG3C;;GAEG;AACH,eAAO,MAAM,cAAc,KAAK,CAAC;AAKjC;;;;;;;;;;;;;GAaG;AACH,wBAAgB,WAAW,CAAC,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,IAAI,CAgCvE;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,eAAe,CAAC,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,MAAM,GAAG,IAAI,CAO9D;AAED;;;GAGG;AACH,wBAAgB,WAAW,CAAC,IAAI,EAAE,IAAI,GAAG,CAAC,MAAM,GAAG,SAAS,CAAC,EAAE,CAQ9D;AAED,wFAAwF;AACxF,wBAAgB,YAAY,CAAC,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,MAAM,GAAG,IAAI,CAE3D"}

package/dist/engine/audio/section.js

@@ -64,4 +64,21 @@ export function setMusicSection(cart, body) {
     const normalised = crlf ? body.replace(/\n/g, '\r\n') : body;
     cart.setSection('music', normalised);
 }
+/**
+ * Reads a cart's `__sfx__` section into one entry per slot (0..63); a slot past
+ * the end of the (trimmed) section is `undefined` (empty).
+ */
+export function readSfxRows(cart) {
+    const body = cart.getSection('sfx');
+    const rows = body === undefined
+        ? []
+        : body.split(/\r?\n/).filter((line) => line.length > 0);
+    while (rows.length < SFX_SLOT_COUNT)
+        rows.push(undefined);
+    return rows.slice(0, SFX_SLOT_COUNT);
+}
+/** Clears SFX slot `slot` back to empty (the all-zero row), via {@link mergeSfxRow}. */
+export function clearSfxSlot(cart, slot) {
+    mergeSfxRow(cart, slot, EMPTY_ROW);
+}
 //# sourceMappingURL=section.js.map

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

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