@yam8d/m8-sdk 0.3.3 → 0.5.0

package/types/types.d.ts

@@ -26,6 +26,11 @@ export interface M8State {
     highlightColor: RGB | null;
     titleColor: RGB | null;
     backgroundColor: RGB | null;
+    /**
+     * Colour of the cursor rectangle as last drawn. The M8 animates the cursor, so it is not
+     * the theme's CURSOR colour (read that with parseThemeScreen). Absent before SDK 0.5.
+     */
+    cursorColor?: RGB | null;
     textUnderCursor: string | null;
     currentLine: string | null;
     deviceModel: string | null;
@@ -35,7 +40,38 @@ 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[];
+}
+/**
+ * The screen with the colour of every character cell, for apps that want to look like
+ * the device (or learn which theme colour the M8 uses for what).
+ */
+export interface M8ScreenCells extends M8Screen {
+    /** fg[row][col]: foreground colour as '#rrggbb'; null where no character was drawn. Each row has `width` entries. */
+    fg: (string | null)[][];
+    /** bg[row][col]: background colour behind the character, same layout as `fg`. */
+    bg: (string | null)[][];
+}
 export type M8KeyName = 'left' | 'right' | 'up' | 'down' | 'shift' | 'play' | 'opt' | 'edit';
+/**
+ * MIDI clock / transport from the M8 (SYNC OUT in its MIDI Settings, stored per song).
+ * `at` is epoch milliseconds (performance.timeOrigin + timestamp), comparable across frames.
+ * `clock` comes once per sixteenth (6 ticks at 24 PPQ); `ticks` counts clock ticks since the
+ * host started listening (monotonic: the M8 can send clock while stopped and without Start);
+ * `msPerTick` is the measured tick length, null until known.
+ */
+export interface M8TransportEvent {
+    kind: 'start' | 'stop' | 'continue' | 'clock' | 'position';
+    ticks: number;
+    at: number;
+    msPerTick: number | null;
+    /** Song Position Pointer (sixteenths), on 'position' events. */
+    spp?: number;
+}
 export interface M8HostMethods {
     navigateToView(viewName: string): Promise<boolean>;
     navigateTo(x: number, y: number): Promise<void>;
@@ -49,6 +85,12 @@ export interface M8HostMethods {
     sendKeyDown(keys: M8KeyName[]): Promise<void>;
     sendKeyUp(): Promise<void>;
     getState(): Promise<M8State>;
+    getScreen(): Promise<M8Screen>;
+    getScreenCells(): Promise<M8ScreenCells>;
+    enableMidiTransport(): Promise<{
+        ok: boolean;
+        error?: string;
+    }>;
 }
 export interface M8ClientMethods {
     ping(): Promise<string>;
@@ -71,6 +113,7 @@ export interface M8HostEvents {
     keyPressed: {
         keys: number;
     };
+    transport: M8TransportEvent;
 }
 export interface M8ClientEvents {
     ready: undefined;
@@ -78,6 +121,94 @@ export interface M8ClientEvents {
         message: string;
     };
 }
+/** 'host': yam8d owns the M8 and the app talks to it from an iframe. 'standalone': the app connects to the M8 itself. */
+export type M8ClientMode = 'host' | 'standalone';
+/** The browser API a standalone client uses to reach the M8. */
+export type M8DeviceTransport = 'serial' | 'usb' | 'midi';
 export interface M8SdkConfig {
     debug?: boolean;
+    /**
+     * 'auto' (default): use the yam8d host when the page runs in a yam8d External Apps iframe,
+     * otherwise connect to the M8 from this page. 'host' and 'standalone' force one mode.
+     */
+    mode?: 'auto' | M8ClientMode;
+    /**
+     * Auto mode in an iframe that yam8d did not mark: how long to wait for a host handshake
+     * before going standalone. Default 3000 ms.
+     */
+    handshakeTimeoutMs?: number;
+    /**
+     * Standalone: at connect, reopen a device this page was granted before, without a prompt.
+     * Default true. A first connection always needs connectDevice() from a user gesture.
+     */
+    autoConnect?: boolean;
+}
+export interface M8DeviceConnectOptions {
+    /** 'auto' (default) picks Web Serial, then WebUSB, then Web MIDI SysEx, by browser support. */
+    transport?: 'auto' | M8DeviceTransport;
+    /** Also play the M8's USB audio through the page (see M8Client.connectAudio). Default false. */
+    audio?: boolean;
+}
+/** Which device APIs this browser offers for standalone mode. */
+export interface M8DeviceSupport {
+    serial: boolean;
+    usb: boolean;
+    midi: boolean;
+}
+/**
+ * Low-level access to the M8 a standalone client is connected to: the raw draw / key /
+ * system events and the device commands. For apps that render the screen themselves or
+ * play notes; everything else is simpler through the client methods.
+ */
+export interface M8DeviceBus {
+    readonly transport: M8DeviceTransport;
+    readonly events: {
+        on<K extends keyof M8DeviceEvents>(event: K, callback: (data: M8DeviceEvents[K]) => void): void;
+        off<K extends keyof M8DeviceEvents>(event: K, callback: (data: M8DeviceEvents[K]) => void): void;
+    };
+    readonly commands: {
+        /** Raw key mask (see M8KeyMask); 0 releases every key. */
+        sendKeys(keys: number): void;
+        /** Asks the M8 to redraw the whole screen. */
+        resetScreen(): void;
+        sendNoteOn(note: number, velocity: number): void;
+        sendNoteOff(): void;
+        sendProgramChange(program: number, channel?: number): void;
+    };
+}
+/** Payloads of the M8 display protocol, in M8 pixel coordinates. */
+export interface M8DeviceEvents {
+    text: {
+        character: string;
+        pos: {
+            x: number;
+            y: number;
+        };
+        foreground: RGB;
+        background: RGB;
+    };
+    rect: {
+        type: number;
+        pos: {
+            x: number;
+            y: number;
+        };
+        size: {
+            width: number;
+            height: number;
+        };
+        color?: RGB;
+    };
+    wave: {
+        color: RGB;
+        wave: number[];
+    };
+    key: {
+        keys: number;
+    };
+    system: {
+        model: string;
+        version: string;
+        fontMode: 0 | 1 | 2;
+    };
 }

package/types/viewContext.d.ts

@@ -4,11 +4,51 @@
  * Derives semantic meaning from raw M8State by mapping cursor position and
  * currentLine content to typed, labelled fields using the m8-view-context.json schema.
  *
- * The five grid views (song, chain, phrase, table, groove) are fully supported.
- * Parameter views (inst, mixer, project, …) return a minimal context with viewName only.
+ * Every view listed in viewlist.json is mapped: the grid views (song, chain, phrase,
+ * table, groove, scale, instrument pool) through their columns, the parameter views
+ * (instrument, modulation, mixer, project, effects, EQ, scope, system settings, file
+ * browsers) through the label/value layouts in m8-parameter-views.json.
  */
-import type { M8State } from './types';
-export type M8FieldType = 'chainRef' | 'phraseRef' | 'note' | 'velocity' | 'instrumentRef' | 'fxCommand' | 'fxValue' | 'transpose' | 'ticks' | 'volume' | 'ppq' | 'instrumentName' | 'eqSlot' | 'rowIndex' | 'noteInterval' | 'onOff' | 'semitoneOffset' | 'swing';
+import type { M8Screen, M8State } from './types';
+import { type ValueFormat } from './parameterViews';
+import { type M8FxLaneTrace, type M8RelativeFxState } from './fxInsight';
+import { type M8ScaleInfo, type M8ScaleNote } from './scaleInsight';
+export type { M8FxLaneTrace, M8RelativeFxState } from './fxInsight';
+export { getInstrumentFxCommands, lookupFxCommand, RELATIVE_FX_RULE } from './fxCommands';
+export type { M8FxCommandInfo, M8InstrumentFxList } from './fxCommands';
+export type { M8ScaleInfo, M8ScaleNote } from './scaleInsight';
+export type M8FieldType = 'chainRef' | 'phraseRef' | 'note' | 'velocity' | 'instrumentRef' | 'fxCommand' | 'fxValue' | 'transpose' | 'ticks' | 'volume' | 'ppq' | 'instrumentName' | 'eqSlot' | 'rowIndex' | 'noteInterval' | 'onOff' | 'semitoneOffset' | 'swing'
+/** Instrument engine of the TYPE field (WAVSYNTH, SAMPLER, …). */
+ | 'instrumentType'
+/** Free-text name field (instrument, song, directory). */
+ | 'name'
+/** Named, editable value (CUTOFF, TEMPO, GAIN, …). */
+ | 'parameter'
+/** Choice from a list, e.g. '00CHORUS', 'BELL'. */
+ | 'option'
+/** Button-like caption (LOAD, SAVE, RENDER, SETTINGS, …). */
+ | 'action'
+/** Row of a file browser ('/folder', '/..', 'Bass.m8i'). */
+ | 'fileEntry';
+/** What a file browser entry is: '/..', '/folder', 'Bass.m8i', 'kick.wav', 'song.m8s', anything else. */
+export type M8FileKind = 'parent' | 'directory' | 'instrumentPreset' | 'sample' | 'm8file' | 'file';
+export interface ColumnDef {
+    x: number;
+    width: number;
+    key: string;
+    type: M8FieldType;
+    label: string;
+    description?: string;
+    meta?: Record<string, unknown>;
+    /** How to read the text (parameter views); grid views use the type's built-in reading. */
+    format?: ValueFormat;
+    /** Unit appended when showing the value (' BPM', ' dB', ' ms'). */
+    unit?: string;
+    /** Names of the numbers of an 'XX:YY' pair (['delay', 'repeat']). */
+    parts?: string[];
+    /** Explanations of the options a choice cell can show, keyed by option name. */
+    options?: Record<string, string>;
+}
 /**
  * A single parsed field value extracted from the currentLine.
  */
@@ -30,6 +70,25 @@ export interface M8ParsedField {
     isEmpty: boolean;
     /** Extra view-specific metadata (e.g. { trackIndex: 2 } for song view track columns). */
     meta?: Record<string, unknown>;
+    /** What this field is, from the schema (parameter views). */
+    description?: string;
+    /**
+     * Parameter views: the non-numeric part of the value - option name ('CHORUS'),
+     * button caption ('LOAD'), instrument type ('WAVSYNTH'), name text. null otherwise.
+     */
+    text?: string | null;
+    /** Parameter views: the value as a number in its natural base (hex, decimal or fractional). */
+    numericValue?: number | null;
+    /** Parameter views: both numbers of an 'XX:YY' pair (e.g. delay time left/right). */
+    values?: number[] | null;
+    /** Names of the numbers in `values`, e.g. ['left time', 'right time']. */
+    parts?: string[];
+    /** Unit of the value, e.g. ' BPM'. */
+    unit?: string;
+    /** What the currently selected option does (choice cells that list their options). */
+    valueDescription?: string;
+    /** File browser rows: what the entry is. */
+    fileKind?: M8FileKind;
 }
 /**
  * All fields parsed from the current row (line at cursorPos.y).
@@ -39,6 +98,8 @@ export interface M8ParsedRow {
     rowIndex: number | null;
     /** Schema key for the row index field (e.g. 'songRow', 'step', 'chainPos'). */
     rowKey: string;
+    /** Parameter views: id of the schema row that matched this line ('tempo', 'gain', …); null for grid views. */
+    rowId: string | null;
     /** Map of column key → parsed field for every column in this view. */
     fields: Record<string, M8ParsedField>;
 }
@@ -71,21 +132,145 @@ export interface M8SemanticContext {
     isUnsaved: boolean;
     /** Whether this view is a structured grid (song/chain/phrase/table/groove). */
     isGridView: boolean;
+    /** Whether this is a label/value parameter view (instrument, mixer, project, effects, EQ, …). */
+    isParameterView: boolean;
+    /** Effect Settings View: the block the cursor is in ('MODFX', 'DELAY', 'REVERB'). */
+    section: string | null;
+    /**
+     * Instrument View: the engine on the TYPE row as displayed ('WAVSYNTH'), and its
+     * normalised key ('wavsynth', 'macrosynth', 'sampler', 'fmsynth', 'hypersynth',
+     * 'external', 'midiout'). Needs the screen; null otherwise.
+     */
+    instrumentType: {
+        text: string;
+        key: string | null;
+    } | null;
     /** All fields on the line at cursorPos.y (null for non-grid views or missing line). */
     row: M8ParsedRow | null;
     /** The specific field under the cursor (null when cursor is out of any column range). */
     activeField: M8ActiveField | null;
+    /** Text of the cursor row with the playback marker removed (null when there is none). */
+    lineText: string | null;
+    /**
+     * Every step of the current phrase (index = step 0-F), so an FX cell can be read
+     * against the cells above it. Only filled for the phrase view, and only when a
+     * screen matching the cursor row was passed to getSemanticContext().
+     */
+    steps: M8ParsedRow[] | null;
+    /**
+     * FX lane (1-3) that shows the '^^' marker: a REP from a previous phrase is still
+     * running there. null when no marker is on screen or there is no screen.
+     */
+    carriedRepLane: number | null;
+    /** What the active FX cell means in the light of its lane (phrase view with `steps`). */
+    fxLane: M8FxLaneTrace | null;
+    /**
+     * Relative instrument commands (VOL, CUT…) in force after the active step, with their
+     * net change since the last note trigger (an instrument number in the I column or a RET).
+     * Phrase view with `steps` only; null otherwise.
+     */
+    relativeFx: Record<string, M8RelativeFxState> | null;
+    /**
+     * When the cursor step triggers the instrument again (an instrument number in the I
+     * column, or a RET), the relative commands in force just before it: the trigger puts
+     * their parameters back. Entries can have a net change of 0. Phrase view with `steps`,
+     * from step 1 on; null otherwise.
+     */
+    resetsRelative: Record<string, M8RelativeFxState> | null;
+    /** Scale View: the interval row under the cursor. Null on the other rows and views. */
+    scaleNote: M8ScaleNote | null;
+    /** Scale View only, when the whole screen was passed: the 12 intervals interpreted together. */
+    scale: M8ScaleInfo | null;
+}
+/** What a part of the description says, so a consumer can keep, drop, reorder or style it. */
+export type M8DescriptionPartKind = 
+/** Label and value of the field under the cursor: "FX1 Command: KIL", "Tempo (TEMPO): 120.00 BPM". */
+'field'
+/** What the FX command does in general: "(Kill: stops the playing instrument after XX ticks)". */
+ | 'fxInfo'
+/** On an FX value, the command it belongs to: "for KIL (…)". */
+ | 'fxTarget'
+/** What the value does here: "value 03: stops the note after 3 ticks", "E is detuned by −0.50 st". */
+ | 'meaning'
+/** The FX lane read down the phrase: a running REP, its RTO limit, REP00… */
+ | 'fxLane'
+/** Relative commands: their net change since the last trigger, or what a trigger resets. */
+ | 'relative'
+/** What the selected option does. */
+ | 'optionInfo'
+/** What the field is. */
+ | 'fieldInfo'
+/** File browser: what the entry is and what [EDIT] does. */
+ | 'fileInfo'
+/** Instrument View: the engine ("Wavsynth instrument"). */
+ | 'instrument'
+/** Effect Settings block or modulator slot ("Delay", "MOD2"). */
+ | 'section'
+/** Scale View: the scale the 12 intervals spell. */
+ | 'scale'
+/** Song View: the track of the cell. */
+ | 'track'
+/** Where the cursor is: view, item number, row ("Phrase View row 07", "Mixer View"). */
+ | 'location'
+/** Text of the cursor row, when no field on it is recognised. */
+ | 'line';
+/** One piece of describeContext(); a kind can appear more than once. */
+export interface M8DescriptionPart {
+    kind: M8DescriptionPartKind;
+    text: string;
+}
+/** The item number of a screen title and the marker after it ('PHRASE 1F*', 'PHRASE 27^'). */
+export declare function parseViewTitle(rawTitle: string | null): {
+    viewId: string | null;
+    isUnsaved: boolean;
+    marker: '*' | '^' | null;
+};
+/**
+ * Every screen row has a one-column left margin (the playback marker '<' / '>' is drawn
+ * in it), so the schema's x positions are counted from column 1, and `cursorPos.x` is
+ * one more than the schema x of the cell it covers. `currentLine` is trimmed and so
+ * already starts at the schema's column 0.
+ */
+export declare const SCREEN_MARGIN = 1;
+/** A grid row read off the whole screen, with the screen row it was found on. */
+export interface M8ScreenGridRow extends M8ParsedRow {
+    screenRow: number;
+}
+/**
+ * Every content row of a grid view (song, chain, phrase, table, groove, instrument pool)
+ * read off the whole screen, top to bottom. Rows whose index column does not parse are
+ * skipped, so check `rowIndex` continuity when you need a full page.
+ *
+ * @example
+ * ```ts
+ * const rows = parseGridScreen('phrase', await m8.getScreen())
+ * rows[0].fields.note.rawValue // 'C-4'
+ * ```
+ */
+export declare function parseGridScreen(viewName: string, screen: M8Screen): M8ScreenGridRow[];
+/** Where the song is playing, as far as the screen shows it. */
+export interface M8PlayPositions {
+    /** Song view: the song row each track's play marker is on (null when its marker is not on screen). */
+    tracks: (number | null)[] | null;
+    /** Chain, phrase, table, groove views: the row with the play marker after its index. */
+    row: number | null;
 }
 /**
- * Look up the description of a 3-character FX command name.
- * Returns undefined if the command is unknown.
+ * Reads the play markers off a grid view. On the Song view the M8 draws a marker in the
+ * blank just left of each playing chain (`00>00>01>02`); on the other grid views in the
+ * blank after the row index of the playing row (`F>--- -- --`), both seen on a Model:02,
+ * firmware 6.5. The '<' drawn in the margin marks the cursor row, not playback. Returns
+ * null for views without a grid; all nulls when nothing is playing.
  */
-export declare function lookupFxCommand(cmd: string): {
-    description: string;
-} | undefined;
+export declare function readPlayPositions(viewName: string, screen: M8Screen): M8PlayPositions | null;
 /**
  * Derives a full semantic context from the current M8State.
  *
+ * Pass the whole `screen` (see M8Client.getScreen) to let the context look beyond the
+ * cursor row: the other steps of a phrase (so an FX cell can be read against the
+ * commands above it) and the other rows of the Scale View. Without a screen, or with
+ * one that no longer matches the cursor row, only the cursor row is interpreted.
+ *
  * @example
  * ```ts
  * const ctx = getSemanticContext(state)
@@ -96,17 +281,33 @@ export declare function lookupFxCommand(cmd: string): {
  * }
  * ```
  */
-export declare function getSemanticContext(state: M8State): M8SemanticContext | null;
+export declare function getSemanticContext(state: M8State, screen?: M8Screen | null): M8SemanticContext | null;
+/**
+ * What the cursor is on, as ordered, tagged parts. Every part is built from
+ * `ctx` alone, so a consumer can keep, drop, reorder or restyle them, or ignore them
+ * and write its own text from the context.
+ *
+ * @example
+ * ```ts
+ * describeContextParts(ctx)
+ * // [{ kind: 'field', text: 'FX2 Command: KIL' },
+ * //  { kind: 'fxInfo', text: '(Kill: stops the playing instrument after XX ticks)' },
+ * //  { kind: 'meaning', text: 'value 03: stops the note after 3 ticks' },
+ * //  { kind: 'location', text: 'Phrase View row 01' }]
+ * ```
+ */
+export declare function describeContextParts(ctx: M8SemanticContext): M8DescriptionPart[];
 /**
- * Returns a short human-readable description of what the cursor is currently on.
+ * Returns a short human-readable description of what the cursor is currently on:
+ * the text of describeContextParts(), joined with ' — '.
  *
  * @example
- * "Track 3 — Chain 0A — Song Row 02"
- * "Note A#4 — Step 7 (Phrase)"
- * "FX1 Command: KIL (Kill Note) — Step 0"
+ * "Track 3: 0A — Track 3 — Song View row 01"
+ * "Note (N): Note C-4 — Phrase View row 00"
+ * "FX2 Command: KIL — (Kill: stops the playing instrument after XX ticks) — value 03: stops the note after 3 ticks — Phrase View row 01"
  */
 export declare function describeContext(ctx: M8SemanticContext): string;
 /**
  * Formats a parsed field value as a human-readable string.
  */
-export declare function formatFieldValue(field: M8ParsedField): string;
+export declare function formatFieldValue(input: M8ParsedField): string;