fractal-midi 0.1.0-alpha.0

package/dist/shared/lineage/wah-lineage.json

@@ -0,0 +1,117 @@
+{
+  "_source": "Fractal Audio wiki — Wah_block.md",
+  "_extractedAt": "2026-04-26T02:14:32.329Z",
+  "_catalogSize": 9,
+  "_recordCount": 9,
+  "records": [
+    {
+      "am4Name": "FAS Wah",
+      "wikiName": "FAS Wah",
+      "description": "Fractal Audio's custom model.",
+      "descriptionSource": "fractal-wiki",
+      "fractalQuotes": [],
+      "flags": []
+    },
+    {
+      "am4Name": "Clyde",
+      "wikiName": "Clyde",
+      "description": "Based on original Vox Clyde McCoy wah pedal.",
+      "descriptionSource": "fractal-wiki",
+      "fractalQuotes": [],
+      "flags": [],
+      "basedOn": {
+        "primary": "Vox Clyde McCoy",
+        "manufacturer": "Vox",
+        "productName": "Clyde McCoy",
+        "source": "fractal-wiki"
+      }
+    },
+    {
+      "am4Name": "Cry Babe",
+      "wikiName": "Cry Babe",
+      "description": "Based on Dunlop Cry Baby.",
+      "descriptionSource": "fractal-wiki",
+      "fractalQuotes": [],
+      "flags": [],
+      "basedOn": {
+        "primary": "Dunlop Cry Baby",
+        "manufacturer": "Dunlop",
+        "productName": "Cry Baby",
+        "source": "fractal-wiki"
+      }
+    },
+    {
+      "am4Name": "VX846",
+      "wikiName": "VX846",
+      "description": "Based on Vox V846-HW handwired wah pedal (Stevie Ray Vaughan).",
+      "descriptionSource": "fractal-wiki",
+      "fractalQuotes": [],
+      "flags": [],
+      "basedOn": {
+        "primary": "Vox V846 -HW",
+        "manufacturer": "Vox",
+        "model": "V846",
+        "productName": "-HW",
+        "source": "fractal-wiki"
+      }
+    },
+    {
+      "am4Name": "Color-Tone",
+      "wikiName": "Color-Tone",
+      "description": "Based on Sola Colorsound wah pedal.",
+      "descriptionSource": "fractal-wiki",
+      "fractalQuotes": [],
+      "flags": [],
+      "basedOn": {
+        "primary": "Colorsound Sola",
+        "manufacturer": "Colorsound",
+        "productName": "Sola",
+        "source": "fractal-wiki"
+      }
+    },
+    {
+      "am4Name": "Funk Wah",
+      "wikiName": "Funk Wah",
+      "description": "Wah sound from the “Shaft” movie.",
+      "descriptionSource": "fractal-wiki",
+      "fractalQuotes": [],
+      "flags": []
+    },
+    {
+      "am4Name": "Mortal",
+      "wikiName": "Mortal",
+      "description": "Based on Morley wah/volume pedal.",
+      "descriptionSource": "fractal-wiki",
+      "fractalQuotes": [],
+      "flags": [],
+      "basedOn": {
+        "primary": "Morley wah/volume",
+        "manufacturer": "Morley",
+        "productName": "wah/volume",
+        "source": "fractal-wiki"
+      }
+    },
+    {
+      "am4Name": "VX845",
+      "fractalQuotes": [],
+      "flags": [
+        "VERIFY: no wiki entry found",
+        "VERIFY: no description or lineage identified"
+      ]
+    },
+    {
+      "am4Name": "Paragon",
+      "wikiName": "Paragon",
+      "description": "Based on Tycobrahe Parapedal.",
+      "descriptionSource": "fractal-wiki",
+      "fractalQuotes": [],
+      "flags": [],
+      "basedOn": {
+        "primary": "Tycobrahe Parapedal",
+        "manufacturer": "Tycobrahe",
+        "productName": "Parapedal",
+        "source": "fractal-wiki"
+      }
+    }
+  ]
+}

package/dist/shared/lineageLookup.d.ts

@@ -0,0 +1,69 @@
+export declare const LINEAGE_BLOCKS: readonly ["amp", "drive", "reverb", "delay", "compressor", "phaser", "chorus", "flanger", "wah"];
+export type LineageBlock = typeof LINEAGE_BLOCKS[number];
+export interface LineageRecord {
+    am4Name: string;
+    wikiName?: string;
+    basedOn?: {
+        primary: string;
+        manufacturer?: string;
+        model?: string;
+        productName?: string;
+        source: string;
+    };
+    description?: string;
+    descriptionSource?: string;
+    fractalQuotes?: Array<{
+        text: string;
+        url?: string;
+        attribution?: string;
+    }>;
+    flags?: string[];
+    family?: string;
+    powerTubes?: string;
+    matchingDynaCab?: string;
+    originalCab?: string;
+    categories?: string[];
+    clipTypes?: string[];
+    familyType?: string;
+}
+export declare function loadLineage(block: LineageBlock): LineageRecord[];
+export declare function scoreRecord(rec: LineageRecord, query: string): number;
+export declare function matchesStructured(rec: LineageRecord, filter: {
+    manufacturer?: string;
+    model?: string;
+}): boolean;
+export declare function formatLineageRecord(rec: LineageRecord, includeQuotes: boolean, maxQuotes?: number): string;
+export type LineageLookupAsk = {
+    block_type: LineageBlock;
+    name?: string;
+    real_gear?: string;
+    manufacturer?: string;
+    model?: string;
+};
+export type LineageLookupHit = {
+    am4Name: string;
+    record: LineageRecord;
+    score?: number;
+};
+export type LineageLookupResult = {
+    ask: LineageLookupAsk;
+    found: true;
+    shape: 'forward' | 'reverse' | 'structured';
+    hits: LineageLookupHit[];
+    totalScanned: number;
+} | {
+    ask: LineageLookupAsk;
+    found: false;
+    shape: 'forward' | 'reverse' | 'structured' | 'invalid';
+    reason: string;
+    totalScanned: number;
+};
+/**
+ * Run a single lineage lookup, returning a structured result. Throws
+ * `Error` only for shape-validation failures the single-ask tool already
+ * surfaces as a thrown error (exactly-one-call-shape, real_gear too
+ * short). Lineage misses return `{ found: false, reason }` so the batch
+ * caller can carry on processing the rest of the asks.
+ */
+export declare function runLineageLookup(ask: LineageLookupAsk): LineageLookupResult;
+//# sourceMappingURL=lineageLookup.d.ts.map

package/dist/shared/lineageLookup.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"lineageLookup.d.ts","sourceRoot":"","sources":["../../src/shared/lineageLookup.ts"],"names":[],"mappings":"AAoBA,eAAO,MAAM,cAAc,kGAGjB,CAAC;AACX,MAAM,MAAM,YAAY,GAAG,OAAO,cAAc,CAAC,MAAM,CAAC,CAAC;AAEzD,MAAM,WAAW,aAAa;IAC5B,OAAO,EAAE,MAAM,CAAC;IAChB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,OAAO,CAAC,EAAE;QACR,OAAO,EAAE,MAAM,CAAC;QAChB,YAAY,CAAC,EAAE,MAAM,CAAC;QACtB,KAAK,CAAC,EAAE,MAAM,CAAC;QACf,WAAW,CAAC,EAAE,MAAM,CAAC;QACrB,MAAM,EAAE,MAAM,CAAC;KAChB,CAAC;IACF,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B,aAAa,CAAC,EAAE,KAAK,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,GAAG,CAAC,EAAE,MAAM,CAAC;QAAC,WAAW,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IAC5E,KAAK,CAAC,EAAE,MAAM,EAAE,CAAC;IAEjB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,WAAW,CAAC,EAAE,MAAM,CAAC;IAErB,UAAU,CAAC,EAAE,MAAM,EAAE,CAAC;IACtB,SAAS,CAAC,EAAE,MAAM,EAAE,CAAC;IAErB,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAID,wBAAgB,WAAW,CAAC,KAAK,EAAE,YAAY,GAAG,aAAa,EAAE,CAahE;AAED,wBAAgB,WAAW,CAAC,GAAG,EAAE,aAAa,EAAE,KAAK,EAAE,MAAM,GAAG,MAAM,CAgBrE;AAED,wBAAgB,iBAAiB,CAC/B,GAAG,EAAE,aAAa,EAClB,MAAM,EAAE;IAAE,YAAY,CAAC,EAAE,MAAM,CAAC;IAAC,KAAK,CAAC,EAAE,MAAM,CAAA;CAAE,GAChD,OAAO,CAQT;AAED,wBAAgB,mBAAmB,CAAC,GAAG,EAAE,aAAa,EAAE,aAAa,EAAE,OAAO,EAAE,SAAS,SAAI,GAAG,MAAM,CA6BrG;AAED,MAAM,MAAM,gBAAgB,GAAG;IAC7B,UAAU,EAAE,YAAY,CAAC;IACzB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB,CAAC;AAEF,MAAM,MAAM,gBAAgB,GAAG;IAC7B,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,aAAa,CAAC;IAGtB,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB,CAAC;AAEF,MAAM,MAAM,mBAAmB,GAC3B;IACE,GAAG,EAAE,gBAAgB,CAAC;IACtB,KAAK,EAAE,IAAI,CAAC;IACZ,KAAK,EAAE,SAAS,GAAG,SAAS,GAAG,YAAY,CAAC;IAG5C,IAAI,EAAE,gBAAgB,EAAE,CAAC;IACzB,YAAY,EAAE,MAAM,CAAC;CACtB,GACD;IACE,GAAG,EAAE,gBAAgB,CAAC;IACtB,KAAK,EAAE,KAAK,CAAC;IACb,KAAK,EAAE,SAAS,GAAG,SAAS,GAAG,YAAY,GAAG,SAAS,CAAC;IACxD,MAAM,EAAE,MAAM,CAAC;IACf,YAAY,EAAE,MAAM,CAAC;CACtB,CAAC;AAEN;;;;;;GAMG;AACH,wBAAgB,gBAAgB,CAAC,GAAG,EAAE,gBAAgB,GAAG,mBAAmB,CAuF3E"}

package/dist/shared/lineageLookup.js

@@ -0,0 +1,196 @@
+/**
+ * Lineage-lookup helpers shared between `am4_lookup_lineage` (single ask)
+ * and `am4_lookup_lineages` (batch). The actual lineage data lives in
+ * `src/fractal/shared/lineage/*-lineage.json` (sourced from the Fractal
+ * wiki + Blocks Guide PDF; only Fractal-authored content is stored).
+ *
+ * The MCP server (`src/server/index.ts`) wraps these helpers — single-ask
+ * formats hits as a hint-rich text block, the batch tool collects per-ask
+ * structured results so the agent can correlate without re-parsing prose.
+ *
+ * Tests cover this layer directly via `scripts/verify-msg.ts`, which is
+ * why the surface is exported instead of inlined in the server.
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const KNOWLEDGE_DIR = path.join(__dirname, 'lineage');
+export const LINEAGE_BLOCKS = [
+    'amp', 'drive', 'reverb', 'delay', 'compressor',
+    'phaser', 'chorus', 'flanger', 'wah',
+];
+const lineageCache = {};
+export function loadLineage(block) {
+    const cached = lineageCache[block];
+    if (cached)
+        return cached;
+    const file = path.join(KNOWLEDGE_DIR, `${block}-lineage.json`);
+    if (!fs.existsSync(file)) {
+        throw new Error(`Lineage data missing at ${file}. Run \`npm run extract-lineage\` to regenerate from the wiki scrape + Blocks Guide PDF.`);
+    }
+    const parsed = JSON.parse(fs.readFileSync(file, 'utf8'));
+    const records = parsed.records ?? [];
+    lineageCache[block] = records;
+    return records;
+}
+export function scoreRecord(rec, query) {
+    const q = query.toLowerCase();
+    let score = 0;
+    // Structured field hits score highest — they're deterministic, unlike
+    // substring matches on prose.
+    if (rec.basedOn?.manufacturer?.toLowerCase() === q)
+        score += 20;
+    if (rec.basedOn?.model?.toLowerCase() === q)
+        score += 20;
+    if (rec.basedOn?.productName?.toLowerCase().includes(q))
+        score += 12;
+    if (rec.am4Name.toLowerCase().includes(q))
+        score += 10;
+    if (rec.basedOn?.primary.toLowerCase().includes(q))
+        score += 8;
+    if (rec.wikiName && rec.wikiName.toLowerCase().includes(q))
+        score += 5;
+    if (rec.description && rec.description.toLowerCase().includes(q))
+        score += 5;
+    for (const qt of rec.fractalQuotes ?? []) {
+        if (qt.text.toLowerCase().includes(q))
+            score += 2;
+    }
+    return score;
+}
+export function matchesStructured(rec, filter) {
+    if (!rec.basedOn)
+        return false;
+    const ci = (a, b) => !b || (a?.toLowerCase() === b.toLowerCase());
+    return (ci(rec.basedOn.manufacturer, filter.manufacturer) &&
+        ci(rec.basedOn.model, filter.model));
+}
+export function formatLineageRecord(rec, includeQuotes, maxQuotes = 5) {
+    const lines = [`am4Name: ${rec.am4Name}`];
+    if (rec.wikiName && rec.wikiName !== rec.am4Name)
+        lines.push(`wikiName: ${rec.wikiName}`);
+    if (rec.family)
+        lines.push(`family: ${rec.family}`);
+    if (rec.familyType)
+        lines.push(`familyType: ${rec.familyType}`);
+    if (rec.categories?.length)
+        lines.push(`categories: ${rec.categories.join(', ')}`);
+    if (rec.clipTypes?.length)
+        lines.push(`clipTypes: ${rec.clipTypes.join(', ')}`);
+    if (rec.powerTubes)
+        lines.push(`powerTubes: ${rec.powerTubes}`);
+    if (rec.originalCab)
+        lines.push(`originalCab: ${rec.originalCab}`);
+    if (rec.matchingDynaCab)
+        lines.push(`matchingDynaCab: ${rec.matchingDynaCab}`);
+    if (rec.basedOn) {
+        const parts = [`basedOn: ${rec.basedOn.primary}`];
+        if (rec.basedOn.manufacturer)
+            parts.push(`manufacturer=${rec.basedOn.manufacturer}`);
+        if (rec.basedOn.model)
+            parts.push(`model=${rec.basedOn.model}`);
+        if (rec.basedOn.productName)
+            parts.push(`productName="${rec.basedOn.productName}"`);
+        parts.push(`source=${rec.basedOn.source}`);
+        lines.push(parts.join(' | '));
+    }
+    if (rec.description)
+        lines.push(`description: ${rec.description}`);
+    if (includeQuotes && rec.fractalQuotes?.length) {
+        const shown = rec.fractalQuotes.slice(0, maxQuotes);
+        lines.push(`fractalQuotes (${shown.length}/${rec.fractalQuotes.length}):`);
+        for (const q of shown) {
+            const url = q.url ? ` [${q.url}]` : '';
+            lines.push(`  - "${q.text}"${url}`);
+        }
+    }
+    if (rec.flags?.length)
+        lines.push(`flags: ${rec.flags.join('; ')}`);
+    return lines.join('\n');
+}
+/**
+ * Run a single lineage lookup, returning a structured result. Throws
+ * `Error` only for shape-validation failures the single-ask tool already
+ * surfaces as a thrown error (exactly-one-call-shape, real_gear too
+ * short). Lineage misses return `{ found: false, reason }` so the batch
+ * caller can carry on processing the rest of the asks.
+ */
+export function runLineageLookup(ask) {
+    const hasStructured = !!(ask.manufacturer || ask.model);
+    const shapeCount = [ask.name !== undefined, ask.real_gear !== undefined, hasStructured].filter(Boolean).length;
+    if (shapeCount !== 1) {
+        throw new Error('lookup_lineage requires exactly one call shape: `name` (forward), `real_gear` (fuzzy reverse), or at least one structured filter (`manufacturer` / `model`).');
+    }
+    const records = loadLineage(ask.block_type);
+    if (hasStructured) {
+        const matches = records.filter((r) => matchesStructured(r, { manufacturer: ask.manufacturer, model: ask.model }));
+        if (matches.length === 0) {
+            const filter = [
+                ask.manufacturer && `manufacturer="${ask.manufacturer}"`,
+                ask.model && `model="${ask.model}"`,
+            ].filter(Boolean).join(', ');
+            return {
+                ask,
+                found: false,
+                shape: 'structured',
+                reason: `No ${ask.block_type} records match ${filter}.`,
+                totalScanned: records.length,
+            };
+        }
+        return {
+            ask,
+            found: true,
+            shape: 'structured',
+            hits: matches.slice(0, 10).map((r) => ({ am4Name: r.am4Name, record: r })),
+            totalScanned: records.length,
+        };
+    }
+    if (ask.name !== undefined) {
+        const q = ask.name.toLowerCase().trim();
+        const exact = records.find((r) => r.am4Name.toLowerCase() === q || r.wikiName?.toLowerCase() === q);
+        const partial = exact ?? records.find((r) => r.am4Name.toLowerCase().includes(q) || r.wikiName?.toLowerCase().includes(q));
+        if (!partial) {
+            return {
+                ask,
+                found: false,
+                shape: 'forward',
+                reason: `No ${ask.block_type} lineage record matches "${ask.name}".`,
+                totalScanned: records.length,
+            };
+        }
+        return {
+            ask,
+            found: true,
+            shape: 'forward',
+            hits: [{ am4Name: partial.am4Name, record: partial }],
+            totalScanned: records.length,
+        };
+    }
+    // Reverse lookup.
+    const query = ask.real_gear.trim();
+    if (query.length < 2) {
+        throw new Error('`real_gear` query must be at least 2 characters.');
+    }
+    const scored = records
+        .map((r) => ({ r, score: scoreRecord(r, query) }))
+        .filter((x) => x.score > 0)
+        .sort((a, b) => b.score - a.score)
+        .slice(0, 10);
+    if (scored.length === 0) {
+        return {
+            ask,
+            found: false,
+            shape: 'reverse',
+            reason: `No ${ask.block_type} records mention "${query}".`,
+            totalScanned: records.length,
+        };
+    }
+    return {
+        ask,
+        found: true,
+        shape: 'reverse',
+        hits: scored.map(({ r, score }) => ({ am4Name: r.am4Name, record: r, score })),
+        totalScanned: records.length,
+    };
+}

package/dist/shared/packValue.d.ts

@@ -0,0 +1,40 @@
+/**
+ * AM4 0x01 SET_PARAM value-field encoding.
+ *
+ * Reverse-engineered from `FUN_140156d10` (encoder) and `FUN_140156af0`
+ * (decoder) in AM4-Edit.exe — see docs/_private/SESSIONS.md session 05.
+ *
+ * Algorithm: sliding-window 8-to-7 bit-pack. N raw bytes become N+1 wire
+ * septets. Each iteration k=1..N takes the top (8-k) bits of the input
+ * byte for the current wire position (OR'd with the carry from the
+ * previous iteration), and saves the bottom k bits as carry for the next.
+ * All wire bytes have bit 7 = 0, satisfying the SysEx wire constraint.
+ *
+ * Verified round-trip on all 10 captured (param, value) samples — see
+ * scripts/verify-pack.ts.
+ */
+export declare function packValue(raw: Uint8Array): Uint8Array;
+export declare function unpackValue(wire: Uint8Array, rawLen: number): Uint8Array;
+/** Pack a 32-bit IEEE 754 float (little-endian) into 5 wire septets. */
+export declare function packFloat32LE(value: number): Uint8Array;
+/**
+ * Chunked variant of `packValue` for payloads > 7 raw bytes. The sliding
+ * window in `packValue` restarts every 7 raw bytes — i.e. 7 raw → 8 packed,
+ * repeated. A trailing partial chunk of N<7 bytes produces N+1 packed
+ * bytes the same way a full standalone `packValue` call would.
+ *
+ * For ≤ 7 raw bytes this is identical to `packValue`, so small payloads
+ * (the 4-byte float used by SET_PARAM, the 4-byte slot uint used by
+ * SAVE_TO_SLOT) are unaffected. Needed for 36-byte preset-name payloads
+ * decoded Session 19; confirmed byte-exact against the captured rename.
+ */
+export declare function packValueChunked(raw: Uint8Array): Uint8Array;
+/**
+ * Inverse of `packValueChunked`: decode a chunked-packed wire buffer
+ * back into raw bytes. `rawLen` is the known total raw byte count
+ * (typically carried in hdr4 of the command the wire payload came from).
+ */
+export declare function unpackValueChunked(wire: Uint8Array, rawLen: number): Uint8Array;
+/** Inverse of packFloat32LE — decode 5 wire septets back to a float. */
+export declare function unpackFloat32LE(wire: Uint8Array): number;
+//# sourceMappingURL=packValue.d.ts.map

package/dist/shared/packValue.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"packValue.d.ts","sourceRoot":"","sources":["../../src/shared/packValue.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,wBAAgB,SAAS,CAAC,GAAG,EAAE,UAAU,GAAG,UAAU,CAWrD;AAED,wBAAgB,WAAW,CAAC,IAAI,EAAE,UAAU,EAAE,MAAM,EAAE,MAAM,GAAG,UAAU,CAWxE;AAED,wEAAwE;AACxE,wBAAgB,aAAa,CAAC,KAAK,EAAE,MAAM,GAAG,UAAU,CAIvD;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,gBAAgB,CAAC,GAAG,EAAE,UAAU,GAAG,UAAU,CAgB5D;AAED;;;;GAIG;AACH,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,UAAU,EAAE,MAAM,EAAE,MAAM,GAAG,UAAU,CAiB/E;AAED,wEAAwE;AACxE,wBAAgB,eAAe,CAAC,IAAI,EAAE,UAAU,GAAG,MAAM,CAMxD"}

package/dist/shared/packValue.js

@@ -0,0 +1,105 @@
+/**
+ * AM4 0x01 SET_PARAM value-field encoding.
+ *
+ * Reverse-engineered from `FUN_140156d10` (encoder) and `FUN_140156af0`
+ * (decoder) in AM4-Edit.exe — see docs/_private/SESSIONS.md session 05.
+ *
+ * Algorithm: sliding-window 8-to-7 bit-pack. N raw bytes become N+1 wire
+ * septets. Each iteration k=1..N takes the top (8-k) bits of the input
+ * byte for the current wire position (OR'd with the carry from the
+ * previous iteration), and saves the bottom k bits as carry for the next.
+ * All wire bytes have bit 7 = 0, satisfying the SysEx wire constraint.
+ *
+ * Verified round-trip on all 10 captured (param, value) samples — see
+ * scripts/verify-pack.ts.
+ */
+export function packValue(raw) {
+    const out = new Uint8Array(raw.length + 1);
+    let carry = 0;
+    for (let i = 0; i < raw.length; i++) {
+        const k = i + 1;
+        const b = raw[i];
+        out[i] = (((b >> k) & 0x7f) | carry) & 0x7f;
+        carry = ((~(0x7f << k) & b) << (7 - k)) & 0x7f;
+    }
+    out[raw.length] = carry;
+    return out;
+}
+export function unpackValue(wire, rawLen) {
+    const out = new Uint8Array(rawLen);
+    for (let i = 0; i < wire.length; i++) {
+        const k = i + 1;
+        const b = wire[i] & 0x7f;
+        if (i > 0 && i - 1 < rawLen) {
+            out[i - 1] |= ((~(0x7f >> k) & b) >> (8 - k)) & 0xff;
+        }
+        if (i < rawLen)
+            out[i] = (b << k) & 0xff;
+    }
+    return out;
+}
+/** Pack a 32-bit IEEE 754 float (little-endian) into 5 wire septets. */
+export function packFloat32LE(value) {
+    const buf = new ArrayBuffer(4);
+    new DataView(buf).setFloat32(0, value, true);
+    return packValue(new Uint8Array(buf));
+}
+/**
+ * Chunked variant of `packValue` for payloads > 7 raw bytes. The sliding
+ * window in `packValue` restarts every 7 raw bytes — i.e. 7 raw → 8 packed,
+ * repeated. A trailing partial chunk of N<7 bytes produces N+1 packed
+ * bytes the same way a full standalone `packValue` call would.
+ *
+ * For ≤ 7 raw bytes this is identical to `packValue`, so small payloads
+ * (the 4-byte float used by SET_PARAM, the 4-byte slot uint used by
+ * SAVE_TO_SLOT) are unaffected. Needed for 36-byte preset-name payloads
+ * decoded Session 19; confirmed byte-exact against the captured rename.
+ */
+export function packValueChunked(raw) {
+    const CHUNK = 7;
+    // Full 7-byte chunks → 8 packed bytes each; trailing partial chunk of
+    // length R → R+1 packed bytes.
+    const fullChunks = Math.floor(raw.length / CHUNK);
+    const remainder = raw.length % CHUNK;
+    const outLen = fullChunks * 8 + (remainder > 0 ? remainder + 1 : 0);
+    const out = new Uint8Array(outLen);
+    let outPos = 0;
+    for (let offset = 0; offset < raw.length; offset += CHUNK) {
+        const end = Math.min(offset + CHUNK, raw.length);
+        const chunkPacked = packValue(raw.subarray(offset, end));
+        out.set(chunkPacked, outPos);
+        outPos += chunkPacked.length;
+    }
+    return out;
+}
+/**
+ * Inverse of `packValueChunked`: decode a chunked-packed wire buffer
+ * back into raw bytes. `rawLen` is the known total raw byte count
+ * (typically carried in hdr4 of the command the wire payload came from).
+ */
+export function unpackValueChunked(wire, rawLen) {
+    const CHUNK_RAW = 7;
+    const CHUNK_WIRE = 8;
+    const out = new Uint8Array(rawLen);
+    let rawPos = 0;
+    let wirePos = 0;
+    while (rawPos < rawLen) {
+        const remainingRaw = rawLen - rawPos;
+        const thisChunkRaw = Math.min(CHUNK_RAW, remainingRaw);
+        const thisChunkWire = thisChunkRaw === CHUNK_RAW ? CHUNK_WIRE : thisChunkRaw + 1;
+        const chunk = wire.subarray(wirePos, wirePos + thisChunkWire);
+        const unpacked = unpackValue(chunk, thisChunkRaw);
+        out.set(unpacked, rawPos);
+        rawPos += thisChunkRaw;
+        wirePos += thisChunkWire;
+    }
+    return out;
+}
+/** Inverse of packFloat32LE — decode 5 wire septets back to a float. */
+export function unpackFloat32LE(wire) {
+    if (wire.length !== 5) {
+        throw new Error(`unpackFloat32LE: expected 5 wire bytes, got ${wire.length}`);
+    }
+    const raw = unpackValue(wire, 4);
+    return new DataView(raw.buffer, raw.byteOffset, 4).getFloat32(0, true);
+}

package/dist/shared/types.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Shared Fractal-protocol types used by multiple device packages.
+ *
+ * Lifted out of per-device files so device modules don't have to
+ * cross-import each other for fundamental protocol shapes (every
+ * Fractal device since the AM4 has used the same 14-bit pidLow/pidHigh
+ * addressing for parameters).
+ */
+/**
+ * Two-coordinate address of a parameter in a Fractal device's wire
+ * protocol. Both fields are 14-bit unsigned ints, transmitted as
+ * septet pairs in the SysEx payload.
+ *
+ * AM4: `pidLow` selects the block/slot, `pidHigh` is the parameter
+ * register within that block.
+ * Axe-Fx II / III / FM3 / FM9 use the same shape with device-specific
+ * encoding details documented per device.
+ */
+export interface ParamId {
+    pidLow: number;
+    pidHigh: number;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/shared/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/shared/types.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH;;;;;;;;;GASG;AACH,MAAM,WAAW,OAAO;IACtB,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,EAAE,MAAM,CAAC;CACjB"}

package/dist/shared/types.js

@@ -0,0 +1,9 @@
+/**
+ * Shared Fractal-protocol types used by multiple device packages.
+ *
+ * Lifted out of per-device files so device modules don't have to
+ * cross-import each other for fundamental protocol shapes (every
+ * Fractal device since the AM4 has used the same 14-bit pidLow/pidHigh
+ * addressing for parameters).
+ */
+export {};

package/package.json

@@ -0,0 +1,75 @@
+{
+  "name": "fractal-midi",
+  "version": "0.1.0-alpha.0",
+  "description": "Pure-TypeScript codec and parameter dictionaries for Fractal Audio devices (AM4, Axe-Fx II, Axe-Fx III). No MIDI transport dependency — bring your own.",
+  "license": "Apache-2.0",
+  "author": "Stephen Staker <stephenstaker@gmail.com>",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./shared": {
+      "types": "./dist/shared/index.d.ts",
+      "default": "./dist/shared/index.js"
+    },
+    "./am4": {
+      "types": "./dist/am4/index.d.ts",
+      "default": "./dist/am4/index.js"
+    },
+    "./axe-fx-ii": {
+      "types": "./dist/axe-fx-ii/index.d.ts",
+      "default": "./dist/axe-fx-ii/index.js"
+    },
+    "./axe-fx-iii": {
+      "types": "./dist/axe-fx-iii/index.d.ts",
+      "default": "./dist/axe-fx-iii/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE",
+    "NOTICE"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/TheAndrewStaker/fractal-midi.git"
+  },
+  "homepage": "https://github.com/TheAndrewStaker/fractal-midi#readme",
+  "bugs": {
+    "url": "https://github.com/TheAndrewStaker/fractal-midi/issues"
+  },
+  "keywords": [
+    "fractal",
+    "fractal-audio",
+    "axe-fx",
+    "axe-fx-ii",
+    "axe-fx-iii",
+    "am4",
+    "fm3",
+    "fm9",
+    "midi",
+    "sysex",
+    "codec",
+    "guitar",
+    "amp-modeling"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.json && tsx scripts/copy-build-assets.ts",
+    "typecheck": "tsc --noEmit -p tsconfig.json",
+    "test": "tsx test/run-all.ts",
+    "preflight": "npm run typecheck && npm test && npm run build"
+  },
+  "devDependencies": {
+    "@types/node": "^20.0.0",
+    "tsx": "^4.19.0",
+    "typescript": "^5.0.0"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  }
+}