fractal-midi 0.1.0-alpha.3 → 0.3.0

package/NOTICE

@@ -26,3 +26,20 @@ descriptively (nominative fair use) to identify the hardware family
 this library targets. The library does not embed Fractal Audio
 firmware, factory presets, branding assets, or any other Fractal-
 copyrighted material.
+
+---
+
+THIRD-PARTY SOFTWARE
+
+This library includes gen-3 (Axe-Fx III / FM3 / FM9) protocol data
+derived from:
+
+  - fractal-syx-codec  (Apache License, Version 2.0)
+    Copyright 2026 Andrew Mercurio ("BoodieTraps")
+    https://github.com/drewmerc302/fractal-syx-codec
+    The gen-3 preset-file format spec (FORMAT.md) and the read-ordinal
+    effect-type roster tables (shipped as the gen-3 read rosters /
+    body-decode tables). The Huffman/CRC codec is a clean-room
+    reimplementation from that spec; the roster name tables are derived
+    from its data, independently cross-validated against our own
+    hardware captures.

package/README.md

@@ -4,14 +4,11 @@ Pure-TypeScript codec and parameter dictionaries for Fractal Audio
 guitar processors. Build and parse the SysEx wire bytes a Fractal
 device speaks, without pulling in a MIDI transport library.
 
-> **Status — pre-release.** The first published version (`0.1.0`)
-> covers AM4 and Axe-Fx II at hardware-verified parity, plus the
-> Axe-Fx III at codec + calibration ✅ via public-capture
-> verification and JUCE-BinaryData mining (hardware-verification
-> stays community-driven — see the III notes in the coverage table).
-> FM3 / FM9 ship next via mechanical ports of the III pipeline.
-> Don't depend on this package from production code yet — APIs may
-> shift before `0.1.0`.
+> Covers AM4 and Axe-Fx II at hardware-verified parity, the modern Fractal
+> family (Axe-Fx III / FM3 / FM9) at codec and calibration via public-capture
+> verification and editor-binary mining, and the Axe-Fx Standard/Ultra (gen-1)
+> as a SET-only descriptor. The gen-3 family stays community-driven for
+> hardware verification; see the per-device notes in the coverage table.
 
 > **Unaffiliated community library.** "Fractal Audio", "AM4",
 > "Axe-Fx", "Axe-Fx II", "Axe-Fx III", "FM3", and "FM9" are
@@ -24,16 +21,16 @@ device speaks, without pulling in a MIDI transport library.
 
 ## What this is
 
-- **JSON-shaped parameter dictionaries** — every block-and-param the
+- **JSON-shaped parameter dictionaries.** Every block-and-param the
   device understands, with display unit, value range, and the
   paramId that goes on the wire. Reverse-engineered against real
   hardware and Fractal's own published 3rd-party MIDI specs.
-- **Pure-TypeScript codec** — display value in (`gain: 7.5`,
+- **Pure-TypeScript codec.** Display value in (`gain: 7.5`,
   `'Plexi 100W High'`), SysEx bytes out (`Uint8Array`). No MIDI
   library required.
-- **Parsers / validators** — given captured bytes, parse back to
+- **Parsers and validators.** Given captured bytes, parse back to
   display values for round-trip equality testing.
-- **Reference data** — Fractal's amp / cab / drive lineage tables
+- **Reference data.** Fractal's amp / cab / drive lineage tables
   (the "the JC-120 model is based on this real-world amp" data),
   factory bank metadata, applicability tables.
 
@@ -41,7 +38,7 @@ device speaks, without pulling in a MIDI transport library.
 
 - **Not a MIDI library.** Routing bytes to and from your hardware
   is your responsibility. Use `node-midi`, `webmidi`,
-  `easymidi`, JUCE, RtMidi, CoreMIDI, ALSA — whatever fits.
+  `easymidi`, JUCE, RtMidi, CoreMIDI, ALSA, whatever fits.
 - **Not a preset editor.** This package gives you the wire-level
   primitives a preset editor would be built on top of.
 - **Not affiliated with Fractal Audio Systems.** See the trademark
@@ -57,9 +54,6 @@ Node >= 18. ESM-only.
 
 ## Usage
 
-> The shape below is the target API. Until `0.1.0` ships, the
-> module surface may differ.
-
 ```ts
 import { buildSetParam, parseSetParam } from 'fractal-midi/am4/codec';
 import { params, blocks } from 'fractal-midi/am4';
@@ -90,9 +84,10 @@ import { params } from 'fractal-midi/axe-fx-iii';
 |---|---|---|---|---|
 | AM4 | ✅ | ✅ | ✅ | ✅ |
 | Axe-Fx II | ✅ | ✅ | ✅ | ✅ |
-| Axe-Fx III | ✅ (2216 params) | ✅ ([see note](#axe-fx-iii-codec-note)) | ✅ ([see note](#axe-fx-iii-calibration-note)) | 🟡 community beta ([see note](#axe-fx-iii-hardware-note)) |
-| FM3 | ❌ | ❌ | ❌ | ❌ |
-| FM9 | ❌ | ❌ | ❌ | ❌ |
+| Axe-Fx III | ✅ (full catalog) | ✅ ([see note](#axe-fx-iii-codec-note)) | ✅ ([see note](#axe-fx-iii-calibration-note)) | 🟡 community beta ([see note](#axe-fx-iii-hardware-note)) |
+| FM3 | ✅ (device-true, mined from FM3-Edit) | ✅ (shared gen-3) | 🟡 (linear; some non-linear pending) | ❌ community beta |
+| FM9 | ✅ (device-true, mined from FM9-Edit) | ✅ (shared gen-3) | 🟡 (linear; some non-linear pending) | ❌ community beta |
+| Axe-Fx Standard/Ultra (gen-1) | ✅ (922 params) | ✅ (nibble-split, SET-only) | 🟡 (linear; 171 non-linear pending) | ❌ community beta (no gen-1 hardware) |
 
 ### Coverage notes
 
@@ -100,9 +95,9 @@ import { params } from 'fractal-midi/axe-fx-iii';
 
 The III's SET_PARAMETER wire envelope (fn=0x01, sub-action `09 00`,
 23-byte frame) is byte-verified against 10 public community captures
-spanning two effect blocks and two sub-action codes — see the
-`axe-fx-iii/setparam` test goldens (302 cases: 36 envelope vectors +
-264 round-trip `build → parse → equality` cases + 2
+spanning two effect blocks and two sub-action codes. See the
+`axe-fx-iii/setparam` test goldens (302 cases: 36 envelope vectors,
+264 round-trip `build` to `parse` to equality cases, and 2
 `parseStateBroadcast` assertions). The GET-response shape is
 hypothesis-only (no public capture exists); the parser handles both
 the `09 00` / `52 00` set-echo shape and the async `04 01`
@@ -113,14 +108,14 @@ STATE_BROADCAST shape via `parseSetGetParameterResponse` /
 
 III calibration = 100% of catalog entries carry a non-`'unverified'`
 unit tag (16 string-typed `_NAME` / `_LABEL` / `_MSG` entries are
-exempted by the calibration gate — they have no `'string'` unit in
+exempted by the calibration gate, since they have no `'string'` unit in
 the `Param` type). Enum vocabularies are resolved at runtime via
 `resolveEnumValues(name)` from `enumOverlay.ts`, which carries a
-`provenance` field on every entry — `'am4-shared'` (AM4-verified,
+`provenance` field on every entry: `'am4-shared'` (AM4-verified,
 shared with III), `'fractal-convention'` (universal Fractal-family
 convention like OFF/ON / channel pickers), or `'iii-spec'` (hand-
 curated for III-only params). Coverage of enum vocabularies and
-numeric display ranges is partial — `resolveEnumValues` returns
+numeric display ranges is partial: `resolveEnumValues` returns
 `undefined` for params not yet mapped, and many XML-derived numeric
 entries carry a unit tag but no `displayMin` / `displayMax`. Treat
 the catalog as the wire-level truth; treat the calibration overlay
@@ -137,9 +132,14 @@ that disagrees with their hardware.
 
 FM3 and FM9 share the III protocol family (model bytes `0x11` /
 `0x12` vs III's `0x10`, identical envelope per Fractal's v1.4 MIDI
-spec). Catalog + codec + calibration for those devices are planned as
-mechanical ports of the III pipeline once the FM3-Edit / FM9-Edit
-JUCE binaries are mined for parameterName + dispatcher tables.
+spec). Both ship device-true param catalogs mined from their own
+FM3-Edit / FM9-Edit JUCE binaries (paramIds are device-specific and are
+never reused from the III) on the shared gen-3 codec. Calibration
+covers the linear params; some non-linear display formulas are still
+pending. Neither has been hardware-verified by the maintainer, so they
+remain community beta: FM9 has real community captures confirming the
+shared read and preset-dump paths, while FM3 confirmation is still
+open.
 
 ## License
 

package/dist/am4/blockLayout.d.ts

@@ -0,0 +1,48 @@
+/**
+ * AM4 working-buffer block-layout snapshot — pure helpers.
+ *
+ * The AM4 holds 4 signal-chain slots. Each slot register reports the
+ * pidLow of the block currently placed there (or `BLOCK_TYPE_VALUES.none`
+ * for empty). Reading the four slot registers produces a `BlockLayoutSnapshot`
+ * — the union of placed block types in the active working buffer.
+ *
+ * Used by  phantom-param pre-flight: a `set_param` write against a
+ * block that isn't placed in any slot wire-acks but silently no-ops on
+ * the device. The dispatcher consults the cached snapshot before each
+ * write and surfaces a `validation_info[]` warning when the target block
+ * is absent.
+ *
+ * The codec layer is wire-bytes agnostic — the consumer reads the four
+ * slots however its transport prefers, then constructs a snapshot from
+ * the (slot-index → block-type) pairs.
+ */
+import type { BlockTypeName } from './blockTypes.js';
+/**
+ * Working-buffer block layout. One entry per slot (1..4); each entry is
+ * the canonical block-type name placed there, or 'none' for an empty
+ * slot. `placedBlocks` is a derived Set of unique placed block names for
+ * fast `isBlockPlaced` lookup.
+ *
+ * AM4 enforces single-instance-per-type (no two slots hold the same
+ * block type), so a Set is sufficient. Grid devices (II/III) need a
+ * different snapshot shape — they ship their own helper.
+ */
+export interface BlockLayoutSnapshot {
+    /** Slot 1..4 block-type name, 'none' for empty. */
+    slots: readonly [BlockTypeName, BlockTypeName, BlockTypeName, BlockTypeName];
+    /** Unique non-'none' block names from `slots`, for O(1) `isBlockPlaced` lookup. */
+    placedBlocks: ReadonlySet<BlockTypeName>;
+}
+/**
+ * Build a snapshot from a 4-element block-type array. Filters 'none'
+ * out of `placedBlocks` so callers don't accidentally match an empty
+ * slot when checking placement.
+ */
+export declare function buildBlockLayoutSnapshot(slots: readonly [BlockTypeName, BlockTypeName, BlockTypeName, BlockTypeName]): BlockLayoutSnapshot;
+/**
+ * True when `block` is placed in any slot of the snapshot. Case-sensitive
+ * (the snapshot uses canonical block names); the dispatcher resolves the
+ * block name to canonical before calling this helper.
+ */
+export declare function isBlockPlaced(snapshot: BlockLayoutSnapshot, block: string): boolean;
+//# sourceMappingURL=blockLayout.d.ts.map

package/dist/am4/blockLayout.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"blockLayout.d.ts","sourceRoot":"","sources":["../../src/am4/blockLayout.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAEH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,iBAAiB,CAAC;AAErD;;;;;;;;;GASG;AACH,MAAM,WAAW,mBAAmB;IAClC,mDAAmD;IACnD,KAAK,EAAE,SAAS,CAAC,aAAa,EAAE,aAAa,EAAE,aAAa,EAAE,aAAa,CAAC,CAAC;IAC7E,mFAAmF;IACnF,YAAY,EAAE,WAAW,CAAC,aAAa,CAAC,CAAC;CAC1C;AAED;;;;GAIG;AACH,wBAAgB,wBAAwB,CACtC,KAAK,EAAE,SAAS,CAAC,aAAa,EAAE,aAAa,EAAE,aAAa,EAAE,aAAa,CAAC,GAC3E,mBAAmB,CAMrB;AAED;;;;GAIG;AACH,wBAAgB,aAAa,CAC3B,QAAQ,EAAE,mBAAmB,EAC7B,KAAK,EAAE,MAAM,GACZ,OAAO,CAET"}

package/dist/am4/blockLayout.js

@@ -0,0 +1,39 @@
+/**
+ * AM4 working-buffer block-layout snapshot — pure helpers.
+ *
+ * The AM4 holds 4 signal-chain slots. Each slot register reports the
+ * pidLow of the block currently placed there (or `BLOCK_TYPE_VALUES.none`
+ * for empty). Reading the four slot registers produces a `BlockLayoutSnapshot`
+ * — the union of placed block types in the active working buffer.
+ *
+ * Used by  phantom-param pre-flight: a `set_param` write against a
+ * block that isn't placed in any slot wire-acks but silently no-ops on
+ * the device. The dispatcher consults the cached snapshot before each
+ * write and surfaces a `validation_info[]` warning when the target block
+ * is absent.
+ *
+ * The codec layer is wire-bytes agnostic — the consumer reads the four
+ * slots however its transport prefers, then constructs a snapshot from
+ * the (slot-index → block-type) pairs.
+ */
+/**
+ * Build a snapshot from a 4-element block-type array. Filters 'none'
+ * out of `placedBlocks` so callers don't accidentally match an empty
+ * slot when checking placement.
+ */
+export function buildBlockLayoutSnapshot(slots) {
+    const placed = new Set();
+    for (const s of slots) {
+        if (s !== 'none')
+            placed.add(s);
+    }
+    return { slots, placedBlocks: placed };
+}
+/**
+ * True when `block` is placed in any slot of the snapshot. Case-sensitive
+ * (the snapshot uses canonical block names); the dispatcher resolves the
+ * block name to canonical before calling this helper.
+ */
+export function isBlockPlaced(snapshot, block) {
+    return snapshot.placedBlocks.has(block);
+}

package/dist/am4/blockTypes.js

@@ -16,12 +16,12 @@ export const BLOCK_TYPE_VALUES = {
     amp: 0x003a,
     compressor: 0x002e,
     geq: 0x0032,
-    peq: 0x0036, // pidLow pinned Session 18; no Type enum known
+    peq: 0x0036, // pidLow pinned ; no Type enum known
     reverb: 0x0042,
     delay: 0x0046,
     chorus: 0x004e,
     flanger: 0x0052,
-    rotary: 0x0056, // pidLow pinned Session 18; no Type enum known
+    rotary: 0x0056, // pidLow pinned ; no Type enum known
     phaser: 0x005a,
     wah: 0x005e,
     volpan: 0x0066,

package/dist/am4/cacheEnums.d.ts

@@ -3,7 +3,7 @@
  *
  * Source: AM4-Edit metadata cache (effectDefinitions_15_2p0.cache),
  * parsed by scripts/parse-cache.ts, verified against wire captures
- * by scripts/map-cache-params.ts (Session 15).
+ * by scripts/map-cache-params.ts.
  *
  * Each array lists the firmware's effect-type dictionary in wire
  * order. The wire value sent in SET_PARAM (at pidHigh=0x000A of the

package/dist/am4/cacheEnums.js

@@ -3,7 +3,7 @@
  *
  * Source: AM4-Edit metadata cache (effectDefinitions_15_2p0.cache),
  * parsed by scripts/parse-cache.ts, verified against wire captures
- * by scripts/map-cache-params.ts (Session 15).
+ * by scripts/map-cache-params.ts.
  *
  * Each array lists the firmware's effect-type dictionary in wire
  * order. The wire value sent in SET_PARAM (at pidHigh=0x000A of the