fractal-midi 0.1.0-alpha.0

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+export declare const VERSION = "0.1.0-alpha.0";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAYA,eAAO,MAAM,OAAO,kBAAkB,CAAC"}

package/dist/index.js

@@ -0,0 +1,12 @@
+// fractal-midi public entry point.
+//
+// The shape exposed here is intentionally narrow at the root; consumers
+// import from the subpath that matches their device or layer:
+//
+//   import { packValue, fractalChecksum } from 'fractal-midi/shared';
+//   import { ... } from 'fractal-midi/am4';
+//   import { ... } from 'fractal-midi/axe-fx-ii';
+//
+// The root `VERSION` constant is convenience-only — useful for log
+// lines and version pinning sanity checks.
+export const VERSION = '0.1.0-alpha.0';

package/dist/shared/checksum.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Fractal SysEx XOR checksum.
+ * Confirmed across all observed AM4 messages — see docs/SYSEX-MAP.md.
+ *
+ *   cs = (XOR of every byte from F0 through the last data byte) & 0x7F
+ *
+ * The result is appended just before the F7 terminator.
+ */
+export declare function fractalChecksum(bytes: readonly number[]): number;
+//# sourceMappingURL=checksum.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"checksum.d.ts","sourceRoot":"","sources":["../../src/shared/checksum.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AACH,wBAAgB,eAAe,CAAC,KAAK,EAAE,SAAS,MAAM,EAAE,GAAG,MAAM,CAIhE"}

package/dist/shared/checksum.js

@@ -0,0 +1,14 @@
+/**
+ * Fractal SysEx XOR checksum.
+ * Confirmed across all observed AM4 messages — see docs/SYSEX-MAP.md.
+ *
+ *   cs = (XOR of every byte from F0 through the last data byte) & 0x7F
+ *
+ * The result is appended just before the F7 terminator.
+ */
+export function fractalChecksum(bytes) {
+    let acc = 0;
+    for (const b of bytes)
+        acc ^= b;
+    return acc & 0x7f;
+}

package/dist/shared/device.d.ts

@@ -0,0 +1,195 @@
+/**
+ * Fractal device abstraction.
+ *
+ * Each Fractal device family member (AM4, Axe-Fx II XL+, Axe-Fx III,
+ * FM3, FM9, VP4) implements `FractalDevice` to expose its protocol
+ * details (model byte, parameter registry, message builders) and its
+ * capability flags (scene count, slot count, channels per block).
+ *
+ * The MCP server holds a single `activeDevice: FractalDevice`
+ * reference and dispatches tool calls through it. Adding a new device
+ * means adding a new implementation under `src/fractal/<device-name>/`,
+ * not touching the server tools.
+ *
+ * Designed 2026-05-04 (Session 47, Path C of multi-device roadmap).
+ * v0.1.0 ships AM4 only; Axe-Fx II is the first follow-up.
+ */
+import type { ParamId } from './types.js';
+/**
+ * Minimal shape every device's parameter entry shares. Each device's
+ * own param type extends this with device-specific fields (AM4's `unit`,
+ * `scaling`, `pidLow`/`pidHigh`; Axe-Fx II's `paramId`, `groupCode`,
+ * `controlType`, etc.). The shared interface is intentionally narrow so
+ * tool-surface code that walks any device's registry only depends on
+ * these universal fields.
+ */
+export interface BaseParam {
+    readonly block: string;
+    readonly name: string;
+    readonly displayMin?: number;
+    readonly displayMax?: number;
+    readonly enumValues?: Readonly<Record<number, string>>;
+}
+/**
+ * Identifies a parsed inbound SysEx message's role. Used by the
+ * predicate functions on `FractalDevice` so the server can wait for
+ * the right kind of response without knowing the protocol details.
+ */
+export interface ReadResponse {
+    pidLow: number;
+    pidHigh: number;
+    /** The 32-bit unsigned int packed into the response payload. */
+    asUInt32LE(): number;
+    /** The Q15-normalized [0,1] internal float for use with `decode`. */
+    asInternalFloat(): number;
+}
+/**
+ * Per-device capability flags. The server uses these for tool input
+ * validation (`scene` ≤ `sceneCount`, etc.) and for capability-aware
+ * tool descriptions. Adding a new capability here requires updating
+ * every device's implementation — by design, so the surface stays
+ * honest.
+ */
+export interface DeviceCapabilities {
+    /**
+     * Number of scenes per preset.
+     *   - AM4 = 4 (the outlier — smallest device in the family)
+     *   - Axe-Fx II XL+ = 8 (per the official Scenes Mini-Manual,
+     *     Fractal Audio: `Axe-Fx-II-Scenes-Mini-Manual-1.02.pdf`)
+     *   - Axe-Fx III, FM3, FM9, VP4 = 8 (per their respective manuals)
+     */
+    readonly sceneCount: number;
+    /**
+     * Number of effect slots in the signal chain. AM4 = 4 (linear).
+     * Axe-Fx II XL+ = 12. Axe-Fx III/FM9 = grid (effectively up to 16+
+     * slots arranged in rows × columns).
+     */
+    readonly slotCount: number;
+    /**
+     * Channels available per block. AM4 = 4 (A/B/C/D). Axe-Fx III also
+     * 4. Some devices may not have channels at all (`'none'`).
+     */
+    readonly channelsPerBlock: 'A-D' | 'A-H' | 'none';
+    /**
+     * Routing topology. Linear = the AM4's "blocks in series" model.
+     * Grid = Axe-Fx III/FM9 row × column matrix routing. v0.1.0 supports
+     * 'linear' only; grid devices land at v0.2 with a routing schema
+     * extension to apply_preset.
+     */
+    readonly routing: 'linear' | 'grid';
+    /**
+     * Total preset locations. AM4 = 104 (banks A-Z × 4). Axe-Fx II = 384.
+     * Axe-Fx III = 512. Used for write-safety bounds checks and for
+     * `formatLocationCode`.
+     */
+    readonly presetLocationCount: number;
+}
+/**
+ * Information returned by a device's `identify()` call. Populated
+ * from the wire response to GET_FIRMWARE_VERSION (function 0x08) at
+ * server startup.
+ */
+export interface DeviceIdentity {
+    readonly modelByte: number;
+    readonly firmwareVersion: string;
+    readonly buildDate?: string;
+}
+/**
+ * Block-type registry: enum values like `{ amp: 0x003a, drive: 0x0076,
+ * ... }` mapping block-type names to their wire-level pidLow.
+ */
+export type BlockTypeRegistry = Readonly<Record<string, number>>;
+/**
+ * Parameter registry: every addressable parameter on the device,
+ * keyed by `<block>.<name>`. Each device exposes its own param shape
+ * (which extends `BaseParam`); generic-tool code only walks the shared
+ * fields. AM4's `KNOWN_PARAMS` and Axe-Fx II's `AXE_FX_II_PARAMS` both
+ * satisfy this.
+ */
+export type ParamRegistry = Readonly<Record<string, BaseParam>>;
+/**
+ * The contract every Fractal device implementation satisfies.
+ *
+ * Implementations live under `src/fractal/<device-name>/device.ts`
+ * and export a single instance: `export const AM4_DEVICE: FractalDevice`,
+ * `export const AXE_FX_II_DEVICE: FractalDevice`, etc.
+ *
+ * Methods that build wire bytes return `number[]` to match the
+ * existing `node-midi` send signature; methods that read return
+ * structured types so the server doesn't need protocol-level knowledge.
+ */
+export interface FractalDevice {
+    /** Wire-level model byte (e.g. 0x15 for AM4, 0x03 for Axe-Fx II XL+). */
+    readonly modelByte: number;
+    /** Display name shown in tool descriptions and logs. */
+    readonly displayName: string;
+    /** Short slug used in URLs / file paths (e.g. "am4", "axe-fx-ii"). */
+    readonly slug: string;
+    /** Capability flags consulted by tools for validation + UX. */
+    readonly capabilities: DeviceCapabilities;
+    /**
+     * Optional substring used to filter MIDI ports during discovery.
+     * Hardware-specific; e.g. AM4's port name contains "AM4". Used by
+     * `connect()` when no port is explicitly requested.
+     */
+    readonly midiPortPattern?: RegExp;
+    readonly knownParams: ParamRegistry;
+    readonly blockTypes: BlockTypeRegistry;
+    /**
+     * Display-name aliases for parameters (e.g. `mix_level` → `mix`).
+     * Empty for devices without aliases.
+     */
+    readonly paramAliases: Readonly<Record<string, string>>;
+    /** Convert a 0-based location index to a human display ("A01" / "U4" / etc.). */
+    formatLocationCode(locationIndex: number): string;
+    /** Same but in Fractal's preferred display style ("U4" not "U04"). */
+    formatLocationDisplay(locationIndex: number): string;
+    /** Parse "A01" / "U4" / "Z04" → 0-based location index. Throws on invalid. */
+    parseLocationCode(code: string): number;
+    /** Resolve a block-type display name or wire value to its wire value. */
+    resolveBlockType(input: string | number): number | undefined;
+    /** Reverse-lookup: wire value → display name. */
+    blockNameForValue(value: number): string | undefined;
+    buildSetParam(key: string, displayValue: number): number[];
+    buildReadParam(param: ParamId, readType?: number): number[];
+    buildSetBlockType(slot: 1 | 2 | 3 | 4, blockTypeValue: number): number[];
+    buildSetBlockBypass(blockPidLow: number, bypassed: boolean): number[];
+    buildSwitchScene(sceneIndex: number): number[];
+    buildSwitchPreset(locationIndex: number): number[];
+    buildSetPresetName(locationIndex: number, name: string): number[];
+    buildSetSceneName(sceneIndex: number, name: string): number[];
+    buildSaveToLocation(locationIndex: number): number[];
+    isWriteEcho(write: number[], response: number[]): boolean;
+    isCommandAck(write: number[], response: number[]): boolean;
+    isReadResponse(read: number[], response: number[]): boolean;
+    parseReadResponse(bytes: number[]): ReadResponse;
+    /**
+     * Send a firmware-identify request and return parsed device info.
+     * Used at server startup to confirm which device is connected.
+     * Returns undefined if the device doesn't respond within the
+     * implementation's chosen timeout.
+     */
+    identify?(send: (bytes: number[]) => void, recv: () => Promise<number[]>): Promise<DeviceIdentity | undefined>;
+}
+/**
+ * Registry of all supported Fractal devices. Server walks this at
+ * startup, asking each registered device's `identify()` (if defined)
+ * to find a match against the connected hardware.
+ *
+ * Order matters for fallback: when no device responds to identify,
+ * the first entry is used as the default. AM4 is the v0.1.0 default
+ * since it's the only fully-implemented device.
+ */
+export declare const FRACTAL_DEVICE_REGISTRY: FractalDevice[];
+export declare function registerDevice(device: FractalDevice): void;
+/**
+ * Pick a device by its model byte. Returns undefined if no registered
+ * device matches — caller decides whether to fall back to the default.
+ */
+export declare function deviceByModelByte(modelByte: number): FractalDevice | undefined;
+/**
+ * Pick a device by slug (used for explicit selection via env var or
+ * config flag).
+ */
+export declare function deviceBySlug(slug: string): FractalDevice | undefined;
+//# sourceMappingURL=device.d.ts.map

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

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

package/dist/shared/device.js

@@ -0,0 +1,27 @@
+/**
+ * Registry of all supported Fractal devices. Server walks this at
+ * startup, asking each registered device's `identify()` (if defined)
+ * to find a match against the connected hardware.
+ *
+ * Order matters for fallback: when no device responds to identify,
+ * the first entry is used as the default. AM4 is the v0.1.0 default
+ * since it's the only fully-implemented device.
+ */
+export const FRACTAL_DEVICE_REGISTRY = [];
+export function registerDevice(device) {
+    FRACTAL_DEVICE_REGISTRY.push(device);
+}
+/**
+ * Pick a device by its model byte. Returns undefined if no registered
+ * device matches — caller decides whether to fall back to the default.
+ */
+export function deviceByModelByte(modelByte) {
+    return FRACTAL_DEVICE_REGISTRY.find((d) => d.modelByte === modelByte);
+}
+/**
+ * Pick a device by slug (used for explicit selection via env var or
+ * config flag).
+ */
+export function deviceBySlug(slug) {
+    return FRACTAL_DEVICE_REGISTRY.find((d) => d.slug === slug);
+}

package/dist/shared/index.d.ts

@@ -0,0 +1,8 @@
+export { fractalChecksum } from './checksum.js';
+export { packValue, unpackValue, packFloat32LE, unpackFloat32LE, packValueChunked, unpackValueChunked, } from './packValue.js';
+export type { ParamId } from './types.js';
+export type { BaseParam, ReadResponse, DeviceCapabilities, DeviceIdentity, BlockTypeRegistry, ParamRegistry, FractalDevice, } from './device.js';
+export { FRACTAL_DEVICE_REGISTRY, registerDevice, deviceByModelByte, deviceBySlug, } from './device.js';
+export { LINEAGE_BLOCKS, loadLineage, scoreRecord, matchesStructured, formatLineageRecord, runLineageLookup, } from './lineageLookup.js';
+export type { LineageBlock, LineageRecord, LineageLookupAsk, LineageLookupHit, LineageLookupResult, } from './lineageLookup.js';
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/shared/index.ts"],"names":[],"mappings":"AAQA,OAAO,EAAE,eAAe,EAAE,MAAM,eAAe,CAAC;AAChD,OAAO,EACL,SAAS,EACT,WAAW,EACX,aAAa,EACb,eAAe,EACf,gBAAgB,EAChB,kBAAkB,GACnB,MAAM,gBAAgB,CAAC;AACxB,YAAY,EAAE,OAAO,EAAE,MAAM,YAAY,CAAC;AAC1C,YAAY,EACV,SAAS,EACT,YAAY,EACZ,kBAAkB,EAClB,cAAc,EACd,iBAAiB,EACjB,aAAa,EACb,aAAa,GACd,MAAM,aAAa,CAAC;AACrB,OAAO,EACL,uBAAuB,EACvB,cAAc,EACd,iBAAiB,EACjB,YAAY,GACb,MAAM,aAAa,CAAC;AACrB,OAAO,EACL,cAAc,EACd,WAAW,EACX,WAAW,EACX,iBAAiB,EACjB,mBAAmB,EACnB,gBAAgB,GACjB,MAAM,oBAAoB,CAAC;AAC5B,YAAY,EACV,YAAY,EACZ,aAAa,EACb,gBAAgB,EAChB,gBAAgB,EAChB,mBAAmB,GACpB,MAAM,oBAAoB,CAAC"}

package/dist/shared/index.js

@@ -0,0 +1,11 @@
+// Barrel for fractal-midi/shared.
+//
+// Vendor-shared protocol primitives that every Fractal device family
+// member builds on: SysEx checksum, septet pack/unpack, packed-float
+// codec, and the shared `ParamId` / `FractalDevice` type shapes.
+//
+// Pure code — no MIDI transport dependency. Bring your own.
+export { fractalChecksum } from './checksum.js';
+export { packValue, unpackValue, packFloat32LE, unpackFloat32LE, packValueChunked, unpackValueChunked, } from './packValue.js';
+export { FRACTAL_DEVICE_REGISTRY, registerDevice, deviceByModelByte, deviceBySlug, } from './device.js';
+export { LINEAGE_BLOCKS, loadLineage, scoreRecord, matchesStructured, formatLineageRecord, runLineageLookup, } from './lineageLookup.js';