fractal-midi 0.1.0-alpha.3 → 0.3.1

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';
@@ -84,15 +78,27 @@ import { buildSetParam } from 'fractal-midi/axe-fx-ii/codec';
 import { params } from 'fractal-midi/axe-fx-iii';
 ```
 
+### Not using TypeScript? Use the JSON catalog
+
+`catalog/` ships a generated, language-agnostic export of every device's
+parameter dictionary, block tables, enum rosters, and ranges — one JSON file
+per device. Read it straight from the installed package
+(`node_modules/fractal-midi/catalog/<device>.json`) or from a pinned git tag.
+Pin a version rather than copying the files: calibration fixes and enum-roster
+fills land here first. Shape contract:
+[docs/CATALOG-SCHEMA.md](docs/CATALOG-SCHEMA.md). The JSON is regenerated from
+the TypeScript source on every change and CI-gated against drift.
+
 ## Per-device coverage
 
 | Device | Catalog | Codec | Calibration | Hardware-verified |
 |---|---|---|---|---|
 | 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 +106,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 +119,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 +143,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