@yam8d/m8-sdk 0.3.3 → 0.4.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@yam8d/m8-sdk",
-  "version": "0.3.3",
+  "version": "0.4.0",
   "description": "Client SDK for iframe applications that communicate with yam8d M8 host.",
   "type": "module",
   "main": "./dist/index.js",

package/types/client.d.ts

@@ -1,7 +1,21 @@
-import type { M8KeyName, M8SdkConfig, M8State } from './types';
-import type { M8SemanticContext } from './viewContext';
-export type { CursorPos, CursorRect, M8KeyName, M8State, RGB, SystemInfos } from './types';
-export type { M8SemanticContext } from './viewContext';
+import type { M8KeyName, M8Screen, M8SdkConfig, M8State } from './types';
+import type { M8DescriptionPart, M8SemanticContext } from './viewContext';
+export type { CursorPos, CursorRect, M8KeyName, M8Screen, M8State, RGB, SystemInfos } from './types';
+export type { M8DescriptionPart, M8SemanticContext } from './viewContext';
+/**
+ * Everything the SDK knows about the moment: raw state, semantic context, its
+ * human-readable description and the whole screen. Plain JSON, safe to persist.
+ */
+export interface M8Snapshot {
+    capturedAt: number;
+    state: Pick<M8State, 'viewName' | 'viewTitle' | 'cursorPos' | 'selectionMode' | 'textUnderCursor' | 'currentLine' | 'deviceModel'>;
+    semantic: M8SemanticContext | null;
+    /** describeContext() output, e.g. "Note (N): Note C-4 — Phrase View row 00". */
+    description: string | null;
+    /** The same description as tagged parts (describeContextParts()). */
+    descriptionParts: M8DescriptionPart[] | null;
+    screen: M8Screen;
+}
 export interface M8Client {
     readonly state: M8State;
     readonly isConnected: boolean;
@@ -18,6 +32,13 @@ export interface M8Client {
     sendKeyUp(): Promise<void>;
     getState(): M8State;
     fetchState(): Promise<M8State>;
+    /**
+     * Whole screen as text rows, read directly from the M8 character stream.
+     * No cursor movement involved, so it is instant and side-effect free.
+     */
+    getScreen(): Promise<M8Screen>;
+    /** Fresh state + semantic context + description + whole screen in one call. */
+    captureSnapshot(): Promise<M8Snapshot>;
     onStateChange(callback: (state: M8State) => void): () => void;
     onViewChange(callback: (viewName: string | null, viewTitle: string | null) => void): () => void;
     onCursorMove(callback: (pos: M8State['cursorPos'], rect: M8State['cursorRect'], selectionMode: boolean) => void): () => void;
@@ -32,9 +53,21 @@ export interface M8Client {
     getSemanticContext(): M8SemanticContext | null;
     /**
      * Returns a short human-readable description of what the cursor is on,
-     * e.g. "Track 3 — Chain 0A — Song View row 02".
+     * e.g. "Track 3: 0A — Track 3 — Song View row 01".
+     *
+     * It also reads the cursor against its surroundings when that changes the meaning:
+     * an FX cell under a running REP says which command is repeating and where it has
+     * got to, FX values are explained (ARP 37 → "+3 and +7 semitones"), and the Scale
+     * View names the scale the enabled notes spell. The surroundings come from a copy of
+     * the screen the client keeps fresh in the background; call getScreen() (or await
+     * captureSnapshot()) first if you need it guaranteed current.
      */
     describeContext(): string | null;
+    /**
+     * The description as ordered, tagged parts ({ kind: 'field' | 'meaning' | 'location' | …, text }),
+     * for consumers that want to keep, drop, reorder or style some of them.
+     */
+    describeContextParts(): M8DescriptionPart[] | null;
 }
 export declare function createM8Client(config?: M8SdkConfig): Promise<M8Client>;
 export declare function createM8ClientSync(config?: M8SdkConfig): {

package/types/fxCommands.d.ts

@@ -0,0 +1,47 @@
+/**
+ * fxCommands.ts
+ *
+ * Lookup of FX commands (the 3-letter names in the FX columns) with what is known
+ * about them: description, whether they are relative, and which instrument types
+ * offer them. Data lives in m8-view-context.json (`fxCommands`, `instrumentFx`).
+ */
+export type FxCategory = 'sequencer' | 'instrument' | 'mixer' | 'modulation';
+export interface M8FxCommandInfo {
+    description: string;
+    category: FxCategory;
+    /**
+     * Relative instrument commands add to the parameter's current value (01-7F add,
+     * 80-FF subtract) and accumulate until a note is triggered with RET or with an
+     * instrument number in the I column.
+     */
+    relative: boolean;
+    /**
+     * Instrument types that offer the command, when it is not offered by all of them
+     * (`null` = every type, or not an instrument command). Only types whose command
+     * list was read from a device are considered.
+     */
+    instrumentTypes: string[] | null;
+    /** Modulator slot 1-4 for envelope/LFO commands (EA1, LF3…). */
+    slot: number | null;
+}
+/**
+ * Look up a 3-character FX command name. Modulator commands carry their slot
+ * number as the third character (EA1, LF3…). Returns undefined for unknown commands.
+ */
+export declare function lookupFxCommand(cmd: string): M8FxCommandInfo | undefined;
+/**
+ * True for relative instrument commands: values 01-7F add to the parameter, 80-FF
+ * subtract (see "Relative and Absolute FX Commands" in the manual).
+ */
+export declare function isRelativeFx(cmd: string): boolean;
+export interface M8InstrumentFxList {
+    /** Type key as used in the schema: sampler, macrosynth, fmsynth, hypersynth, midiout. */
+    type: string;
+    /** Read from a real device (false = taken from documentation). */
+    verified: boolean;
+    commands: string[];
+}
+/** Instrument command names offered for an instrument type, or null when unknown. */
+export declare function getInstrumentFxCommands(type: string): M8InstrumentFxList | null;
+/** What the manual says about relative commands (for tooltips and descriptions). */
+export declare const RELATIVE_FX_RULE: string;

package/types/fxInsight.d.ts

@@ -0,0 +1,136 @@
+/**
+ * fxInsight.ts
+ *
+ * Explains what an FX value does and follows FX "lanes" (FX1/FX2/FX3 columns)
+ * down a phrase, so a REP command - or an empty cell sitting under one - can be
+ * described in terms of the command it is repeating.
+ *
+ * Purely structural: works on already-parsed cells, no dependency on viewContext.
+ */
+import { isRelativeFx } from './fxCommands';
+export { isRelativeFx };
+/** The subset of a parsed cell this module needs. */
+export interface FxCell {
+    rawValue: string;
+    hexValue: number | null;
+    isEmpty: boolean;
+}
+/** One phrase step, indexed by column key ('note', 'fx1cmd', 'fx1val', …). */
+export interface FxStepRow {
+    fields: Record<string, FxCell | undefined>;
+}
+export type FxLaneEvent = 
+/** Nothing FX-related happens in this lane at this step. */
+'none'
+/** A regular command starts a new base value; any REP ends. */
+ | 'set'
+/** A regular command replaces a REP that was running. */
+ | 'replace'
+/** REP XX (XX>0) starts repeating. */
+ | 'rep'
+/** REP XX while another REP was already running (new increment). */
+ | 'repChange'
+/** REP 00 stops the repeat. */
+ | 'repStop'
+/** REP with no earlier command in this lane and none carried over. */
+ | 'orphan'
+/** RTO sets the limit for the running REP. */
+ | 'rto'
+/** Empty cell while a REP is active: the repeated command fires again. */
+ | 'continue';
+export interface M8FxLaneTrace {
+    /** FX lane, 1-3. */
+    lane: number;
+    /** Phrase step this trace was computed for. */
+    step: number;
+    event: FxLaneEvent;
+    /** Last regular command in the lane at or before `step`. */
+    source: {
+        cmd: string;
+        value: number | null;
+        step: number;
+    } | null;
+    /** True when a REP is running after this step. */
+    active: boolean;
+    /** Per-step increment of the running REP (0x01-0xFF, 0x80+ = negative). */
+    increment: number | null;
+    /** Value set with RTO, if any. */
+    limit: number | null;
+    /** Value the repeated command has at this step (null when unknown). */
+    value: number | null;
+    /** True when `value` was clamped by the RTO limit. */
+    atLimit: boolean;
+    /** Step where the running REP began. */
+    repStartStep: number | null;
+    /** True when a REP from a previous phrase is running here (value unknown). */
+    carried: boolean;
+}
+export declare const hex2: (n: number) => string;
+/** Hex text of a value, with its signed reading when the command is relative and negative. */
+export declare function formatFxValue(cmd: string, value: number): string;
+export interface FxValueContext {
+    /** Note on the same step (used by ARP to spell out the notes). */
+    note?: string | null;
+    /** Table view: HOP and CHA mean something different there. */
+    inTable?: boolean;
+}
+/**
+ * Short explanation of what `value` does for `cmd` (phrase view), or null when
+ * the command has no interpretation worth adding beyond its name.
+ */
+export declare function describeFxValue(cmd: string, value: number, ctx?: FxValueContext): string | null;
+/**
+ * Walks FX lane `lane` (1-3) from step 0 to `step` and reports what is in effect
+ * there. `rows` must hold every step of the phrase, index = step.
+ *
+ * Model (manual: "Repeat"): REP XX repeats the lane's last command with its value
+ * bumped by XX on each step, keeps going through empty cells, and stops on a new
+ * command or REP00. RTO XX in the same lane sets the value REP stops at.
+ * `carriedIn` says a REP from a previous phrase is running (the '^^' marker).
+ */
+export declare function analyzeFxLane(rows: FxStepRow[], lane: number, step: number, carriedIn?: boolean): M8FxLaneTrace;
+/**
+ * One-sentence explanation of a lane trace, or null when the lane has nothing to
+ * say at this step. Meant to be appended to the cell description.
+ */
+export declare function describeFxLane(t: M8FxLaneTrace): string | null;
+/**
+ * What a relative instrument command (VOL, CUT, PIT…) has done to its parameter
+ * since the last note trigger.
+ */
+export interface M8RelativeFxState {
+    cmd: string;
+    /** Net change applied to the parameter (signed; the device clamps to the parameter's range). */
+    total: number;
+    /** Times the command was applied (REP-driven repeats included). */
+    count: number;
+    /** Step of the last trigger that reset it, or null when none happened in this phrase. */
+    resetStep: number | null;
+    /** What reset it: a row with an instrument number in the I column, or a RET command. */
+    resetBy: 'instrument' | 'ret' | null;
+    /** True when some of the applications came from a running REP. */
+    viaRep: boolean;
+}
+/**
+ * What makes step `row` trigger the instrument again, which resets every relative change:
+ * an instrument number in the I column, a RET command, or nothing (null).
+ */
+export declare function relativeResetBy(row: FxStepRow): M8RelativeFxState['resetBy'];
+/**
+ * Follows every relative instrument command through the phrase up to `step` (inclusive).
+ *
+ * Model (manual: "Relative and Absolute FX Commands"): a relative command adds its
+ * value (01-7F) or subtracts it (80-FF) from the instrument's parameter, and the change
+ * stays until a note is triggered with a RET command or with an instrument number in
+ * the I column, which puts every parameter back to the instrument's assigned value.
+ * A row that triggers resets first, then applies its own commands. State from a
+ * previous phrase isn't visible, so totals only cover this phrase.
+ */
+export declare function analyzeRelativeFx(rows: FxStepRow[], step: number, carriedLane?: number | null): Record<string, M8RelativeFxState>;
+/** Sentence about a relative command's accumulated effect, for the cell that applies it. */
+export declare function describeRelativeFx(s: M8RelativeFxState | null | undefined): string;
+/**
+ * For an instrument number typed on a step: which relative changes are still in force
+ * and will be wiped by the note it triggers. Null when nothing relative is active.
+ */
+export declare function describeRelativeReset(active: Record<string, M8RelativeFxState>): string | null;

package/types/index.d.ts

@@ -1,4 +1,4 @@
-export type { CursorPos, CursorRect, M8ClientEvents, M8ClientMethods, M8HostEvents, M8HostMethods, M8KeyName, M8SdkConfig, M8State, RGB, SystemInfos, } from './types';
-export { createM8Client, createM8ClientSync, type M8Client } from './client';
-export { getSemanticContext, describeContext, formatFieldValue, lookupFxCommand, type M8FieldType, type M8ParsedField, type M8ParsedRow, type M8ActiveField, type M8SemanticContext, } from './viewContext';
+export type { CursorPos, CursorRect, M8ClientEvents, M8ClientMethods, M8HostEvents, M8HostMethods, M8KeyName, M8Screen, M8SdkConfig, M8State, RGB, SystemInfos, } from './types';
+export { createM8Client, createM8ClientSync, type M8Client, type M8Snapshot } from './client';
+export { getSemanticContext, describeContext, describeContextParts, formatFieldValue, lookupFxCommand, getInstrumentFxCommands, RELATIVE_FX_RULE, type M8FieldType, type M8ParsedField, type M8ParsedRow, type M8ActiveField, type M8SemanticContext, type M8DescriptionPart, type M8DescriptionPartKind, type M8FileKind, type M8FxCommandInfo, type M8InstrumentFxList, type M8FxLaneTrace, type M8RelativeFxState, type M8ScaleInfo, type M8ScaleNote, } from './viewContext';
 export { default } from './client';

package/types/parameterViews.d.ts

@@ -0,0 +1,104 @@
+/**
+ * parameterViews.ts
+ *
+ * Maps the non-grid ("parameter") views - instrument, modulation, mixer, project,
+ * effects, EQ, scope, system settings, file browsers - onto typed field cells,
+ * using m8-parameter-views.json.
+ *
+ * These views are label/value screens, so a row is recognised from its text (its
+ * label), not from a row number, and the cells of that row come from the schema. Views
+ * whose labels change with the instrument or modulation type are read through two
+ * label/value "zones" and the label is looked up in a vocabulary.
+ *
+ * Pure text in, cell definitions out; viewContext.ts turns them into parsed fields.
+ */
+import type { ColumnDef } from './viewContext';
+export type ValueFormat = 'hex' | 'hexOption' | 'hexPair' | 'decimal' | 'decimalPair' | 'float' | 'text' | 'auto';
+interface MatchDef {
+    x: number;
+    text?: string;
+    regex?: string;
+    width?: number;
+}
+interface RowDef {
+    id: string;
+    section?: string;
+    match: MatchDef[];
+    cells: ColumnDef[];
+}
+interface ZoneDef {
+    id: string;
+    labelX: number;
+    labelWidth: number;
+    x: number;
+    width: number;
+}
+type VocabEntry = Pick<ColumnDef, 'type' | 'format' | 'label' | 'description' | 'parts' | 'options' | 'unit'>;
+interface LayoutDef {
+    extends?: string;
+    /** Pattern of the heading label that names the block a cell belongs to ('MOD\\d'): read upward in the cell's zone. */
+    slotLabel?: string;
+    kind?: 'browser' | 'text';
+    browserFor?: string;
+    fieldLabel?: string;
+    description?: string;
+    sections?: string[];
+    rows?: RowDef[];
+    zones?: ZoneDef[];
+    vocabulary?: Record<string, VocabEntry>;
+    vocabularyFrom?: 'instrumentTypes';
+}
+export type ParameterLayout = Omit<LayoutDef, 'extends'>;
+/** Layout of a parameter view, or null when the view has none. */
+export declare function getParameterLayout(viewName: string): ParameterLayout | null;
+/**
+ * Section heading ('MODFX', 'DELAY', 'REVERB') the cursor line belongs to: the
+ * nearest heading at column 0 on this line or above it. `linesUpward` starts with the
+ * cursor line, then the lines above it.
+ */
+export declare function detectSection(layout: ParameterLayout, linesUpward: string[]): string | null;
+/**
+ * Block heading ('MOD1'…'MOD4') a cell in `zoneId` belongs to: the nearest line at or
+ * above the cursor with a heading label in that zone.
+ */
+export declare function detectSlot(layout: ParameterLayout, zoneId: string, linesUpward: string[]): string | null;
+/** 'WAVSYNTH' → 'wavsynth', 'MIDI OUT' → 'midiout', unknown text → null. */
+export declare function instrumentKeyFromText(text: string): string | null;
+/** Instrument type shown on the TYPE row of the Instrument View, read off the screen lines. */
+export declare function instrumentTypeFromLines(lines: string[]): {
+    text: string;
+    key: string | null;
+} | null;
+/** Display name and description of an instrument type key ('wavsynth' → Wavsynth). */
+export declare function getInstrumentType(key: string): {
+    name: string;
+    description: string;
+} | null;
+export interface ParameterLineOptions {
+    section: string | null;
+    instrumentKey: string | null;
+    /** Text under the cursor; the entry of a file-browser row. */
+    entryText?: string | null;
+}
+/**
+ * The cells present on `line`: the schema row whose label text matches, or else the
+ * label/value zones. Empty when nothing on the line is recognised.
+ */
+export declare function readParameterCells(layout: ParameterLayout, line: string, opts: ParameterLineOptions): {
+    rowId: string | null;
+    cells: ColumnDef[];
+};
+export interface ParsedValue {
+    hexValue: number | null;
+    /** Natural number of the value: the hex value, decimal integer or float. */
+    numericValue: number | null;
+    /** Both numbers of an 'XX:YY' pair. */
+    values: number[] | null;
+    /** The non-numeric part: option name, caption, name text. */
+    text: string | null;
+}
+/** Reads a cell's text according to its format. Empty text gives all-null. */
+export declare function parseValue(raw: string, format: ValueFormat): ParsedValue;
+/** Description of the option currently selected ('CLIP' → "Values above the maximum level are clipped."). */
+export declare function describeOption(options: Record<string, string> | undefined, text: string | null): string | null;
+export {};

package/types/scaleInsight.d.ts

@@ -0,0 +1,47 @@
+/**
+ * scaleInsight.ts
+ *
+ * Interprets the Scale View: which of the 12 note intervals are enabled, what
+ * well-known scale that shape spells, and what a given row means musically.
+ */
+/** Interval row labels in screen order. */
+export declare const SCALE_INTERVALS: readonly ["C", "C#", "D", "D#", "E", "F", "F#", "G", "G#", "A", "A#", "B"];
+export interface M8ScaleNote {
+    /** Row label, e.g. 'D#'. */
+    interval: string;
+    /** Semitones above the first row ('C'), 0-11. */
+    semitone: number;
+    /** true = ON, false = OFF, null = unset ('--'). */
+    enabled: boolean | null;
+    /** Detune in semitones (-24..+24), null when unreadable. */
+    offset: number | null;
+}
+export interface M8ScaleInfo {
+    /** The 12 rows, in screen order. */
+    notes: M8ScaleNote[];
+    /** Labels of the enabled intervals, e.g. ['C', 'D', 'E', …]. */
+    enabled: string[];
+    /** Well-known scales this set of notes spells, most natural reading first. */
+    shapes: string[];
+    /** Intervals carrying a non-zero detune. */
+    detuned: {
+        interval: string;
+        offset: number;
+    }[];
+    /** One-line summary, e.g. "C D E F G A B — Major (Ionian)". */
+    summary: string;
+}
+/** 'C-' → 'C', 'C#' → 'C#'. Returns null when the text is not an interval label. */
+export declare function normalizeInterval(raw: string): string | null;
+/** "a major 3rd (+4 semitones above C)" for a given interval label. */
+export declare function describeInterval(interval: string): string;
+/** Names of well-known scales whose notes equal the enabled set, C-rooted reading first. */
+export declare function matchScaleShapes(enabledSemitones: number[]): string[];
+export declare function analyzeScale(notes: M8ScaleNote[]): M8ScaleInfo;
+/**
+ * The two halves of the summary: the enabled notes ("C D E F G A B"), then the scale
+ * they spell with any detune ("Major (Ionian); detuned: E −0.50 st"), when notes are enabled.
+ */
+export declare function scaleSummaryParts(info: Pick<M8ScaleInfo, 'enabled' | 'shapes' | 'detuned'>): string[];
+/** '+0.50 st' style detune text. */
+export declare function formatOffset(offset: number): string;

package/types/types.d.ts

@@ -35,6 +35,12 @@ export interface M8State {
     macroCurrentStep?: number;
     macroSequenceLength?: number;
 }
+export interface M8Screen {
+    width: number;
+    height: number;
+    /** One string per screen row; columns preserved, trailing spaces trimmed. */
+    lines: string[];
+}
 export type M8KeyName = 'left' | 'right' | 'up' | 'down' | 'shift' | 'play' | 'opt' | 'edit';
 export interface M8HostMethods {
     navigateToView(viewName: string): Promise<boolean>;
@@ -49,6 +55,7 @@ export interface M8HostMethods {
     sendKeyDown(keys: M8KeyName[]): Promise<void>;
     sendKeyUp(): Promise<void>;
     getState(): Promise<M8State>;
+    getScreen(): Promise<M8Screen>;
 }
 export interface M8ClientMethods {
     ping(): Promise<string>;