@audiofab-io/fv1-core 0.4.0 → 0.5.0

package/dist/spnbank/index.d.ts

@@ -0,0 +1,55 @@
+/**
+ * `.spnbank` — Easy Spin Program Bank file format.
+ *
+ * A `.spnbank` file is a small JSON manifest describing the eight program
+ * slots of an Easy Spin pedal. Each slot points at a workspace-relative
+ * `.spn` (FV-1 assembly) or `.spndiagram` (block diagram) file. The manifest
+ * is the unit of "program the whole pedal" — tooling resolves each slot to a
+ * compiled binary at programming time.
+ *
+ *   Slot indices in the manifest are 1-based (slot 1..8) for human readability.
+ *   The runtime API uses 0-based indices via `bankSlotIndex0()`.
+ *
+ * Round-trip:
+ *   parseSpnBankJson(serializeSpnBankJson(b)) === b   // structurally equal
+ */
+/** A single entry in a `.spnbank` file. */
+export interface SpnBankSlot {
+    /** 1-based slot number (1..8). */
+    slot: number;
+    /** Workspace-relative path to a `.spn` or `.spndiagram` file. Empty
+     *  string indicates an unassigned slot. */
+    path: string;
+}
+/** Parsed `.spnbank` file. */
+export interface SpnBankFile {
+    /** Display name. Defaults to the filename's basename when not set. */
+    name?: string;
+    /** Always exactly `PROGRAM_SLOT_COUNT` (8) entries, in slot-number order. */
+    slots: SpnBankSlot[];
+}
+/** True if a slot has no assigned program. */
+export declare function isSlotEmpty(slot: SpnBankSlot): boolean;
+/** Build an empty bank. All slots unassigned. */
+export declare function createEmptyBank(name?: string): SpnBankFile;
+/**
+ * Parse the JSON text of a `.spnbank` file. Always returns a structurally
+ * complete bank (8 slots in order); malformed JSON or missing fields fall
+ * back to defaults so tooling can render a usable editor over a corrupt or
+ * empty file.
+ *
+ * @param text         Raw file contents.
+ * @param fallbackName Display name to use when the file's `name` field is
+ *                     missing — typically the file basename without `.spnbank`.
+ */
+export declare function parseSpnBankJson(text: string, fallbackName?: string): SpnBankFile;
+/**
+ * Serialise a `.spnbank` file to JSON text. Output is pretty-printed with
+ * 2-space indentation and a trailing newline.
+ */
+export declare function serializeSpnBankJson(bank: SpnBankFile): string;
+/** Convenience: 0-based index for a slot. */
+export declare function bankSlotIndex0(slot: SpnBankSlot): number;
+/** Re-exported for convenience so callers don't have to also import from `/pedal`. */
+export { PROGRAM_SLOT_COUNT } from '../pedal/constants.js';
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/spnbank/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAIH,2CAA2C;AAC3C,MAAM,WAAW,WAAW;IAC1B,kCAAkC;IAClC,IAAI,EAAE,MAAM,CAAA;IACZ;+CAC2C;IAC3C,IAAI,EAAE,MAAM,CAAA;CACb;AAED,8BAA8B;AAC9B,MAAM,WAAW,WAAW;IAC1B,sEAAsE;IACtE,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,6EAA6E;IAC7E,KAAK,EAAE,WAAW,EAAE,CAAA;CACrB;AAED,8CAA8C;AAC9C,wBAAgB,WAAW,CAAC,IAAI,EAAE,WAAW,GAAG,OAAO,CAEtD;AAED,iDAAiD;AACjD,wBAAgB,eAAe,CAAC,IAAI,CAAC,EAAE,MAAM,GAAG,WAAW,CAQ1D;AA6BD;;;;;;;;;GASG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,MAAM,EAAE,YAAY,CAAC,EAAE,MAAM,GAAG,WAAW,CAoBjF;AAED;;;GAGG;AACH,wBAAgB,oBAAoB,CAAC,IAAI,EAAE,WAAW,GAAG,MAAM,CAM9D;AAED,6CAA6C;AAC7C,wBAAgB,cAAc,CAAC,IAAI,EAAE,WAAW,GAAG,MAAM,CAExD;AAED,sFAAsF;AACtF,OAAO,EAAE,kBAAkB,EAAE,MAAM,uBAAuB,CAAA"}

package/dist/spnbank/index.js

@@ -0,0 +1,104 @@
+/**
+ * `.spnbank` — Easy Spin Program Bank file format.
+ *
+ * A `.spnbank` file is a small JSON manifest describing the eight program
+ * slots of an Easy Spin pedal. Each slot points at a workspace-relative
+ * `.spn` (FV-1 assembly) or `.spndiagram` (block diagram) file. The manifest
+ * is the unit of "program the whole pedal" — tooling resolves each slot to a
+ * compiled binary at programming time.
+ *
+ *   Slot indices in the manifest are 1-based (slot 1..8) for human readability.
+ *   The runtime API uses 0-based indices via `bankSlotIndex0()`.
+ *
+ * Round-trip:
+ *   parseSpnBankJson(serializeSpnBankJson(b)) === b   // structurally equal
+ */
+import { PROGRAM_SLOT_COUNT } from '../pedal/constants.js';
+/** True if a slot has no assigned program. */
+export function isSlotEmpty(slot) {
+    return !slot.path;
+}
+/** Build an empty bank. All slots unassigned. */
+export function createEmptyBank(name) {
+    return {
+        name,
+        slots: Array.from({ length: PROGRAM_SLOT_COUNT }, (_, i) => ({
+            slot: i + 1,
+            path: '',
+        })),
+    };
+}
+function normaliseSlots(input) {
+    const empty = () => Array.from({ length: PROGRAM_SLOT_COUNT }, (_, i) => ({ slot: i + 1, path: '' }));
+    if (!Array.isArray(input))
+        return empty();
+    // Build a lookup by slot number, tolerant of duplicate / missing entries
+    // and out-of-range slot numbers in the input.
+    const bySlot = new Map();
+    for (const entry of input) {
+        if (typeof entry !== 'object' || entry === null)
+            continue;
+        const e = entry;
+        const slot = typeof e.slot === 'number' ? e.slot : NaN;
+        const path = typeof e.path === 'string' ? e.path : '';
+        if (!Number.isFinite(slot))
+            continue;
+        if (slot < 1 || slot > PROGRAM_SLOT_COUNT)
+            continue;
+        bySlot.set(slot, path);
+    }
+    const result = empty();
+    for (const slot of result) {
+        const path = bySlot.get(slot.slot);
+        if (path !== undefined)
+            slot.path = path;
+    }
+    return result;
+}
+/**
+ * Parse the JSON text of a `.spnbank` file. Always returns a structurally
+ * complete bank (8 slots in order); malformed JSON or missing fields fall
+ * back to defaults so tooling can render a usable editor over a corrupt or
+ * empty file.
+ *
+ * @param text         Raw file contents.
+ * @param fallbackName Display name to use when the file's `name` field is
+ *                     missing — typically the file basename without `.spnbank`.
+ */
+export function parseSpnBankJson(text, fallbackName) {
+    if (!text || !text.trim()) {
+        return createEmptyBank(fallbackName);
+    }
+    let raw;
+    try {
+        raw = JSON.parse(text);
+    }
+    catch {
+        return createEmptyBank(fallbackName);
+    }
+    if (typeof raw !== 'object' || raw === null) {
+        return createEmptyBank(fallbackName);
+    }
+    const obj = raw;
+    const name = typeof obj.name === 'string' && obj.name ? obj.name : fallbackName;
+    const slots = normaliseSlots(obj.slots);
+    return { name, slots };
+}
+/**
+ * Serialise a `.spnbank` file to JSON text. Output is pretty-printed with
+ * 2-space indentation and a trailing newline.
+ */
+export function serializeSpnBankJson(bank) {
+    const json = {
+        ...(bank.name ? { name: bank.name } : {}),
+        slots: bank.slots,
+    };
+    return JSON.stringify(json, null, 2) + '\n';
+}
+/** Convenience: 0-based index for a slot. */
+export function bankSlotIndex0(slot) {
+    return slot.slot - 1;
+}
+/** Re-exported for convenience so callers don't have to also import from `/pedal`. */
+export { PROGRAM_SLOT_COUNT } from '../pedal/constants.js';
+//# sourceMappingURL=index.js.map

package/dist/spnbank/index.js.map

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@audiofab-io/fv1-core",
-  "version": "0.4.0",
+  "version": "0.5.0",
   "description": "FV-1 DSP toolchain: assembler, simulator, Intel HEX parser, and block-diagram compiler",
   "type": "module",
   "sideEffects": false,
@@ -22,7 +22,12 @@
     "./blockDiagram/node": {
       "import": "./dist/blockDiagram/blocks/BlockDirectoryLoader.js",
       "types": "./dist/blockDiagram/blocks/BlockDirectoryLoader.d.ts"
-    }
+    },
+    "./spnbank": {
+      "import": "./dist/spnbank/index.js",
+      "types": "./dist/spnbank/index.d.ts"
+    },
+    "./package.json": "./package.json"
   },
   "files": [
     "dist",
@@ -32,6 +37,7 @@
     "build:manifest": "node scripts/build-manifest.mjs",
     "build": "npm run build:manifest && tsc",
     "clean": "rm -rf dist src/blockDiagram/builtinBlocks.ts",
+    "test": "node test/spnbank-test.mjs",
     "prepublishOnly": "npm run build"
   },
   "dependencies": {