@yam8d/m8-sdk 0.4.0 → 0.5.0

package/types/engine/protocol.d.ts

@@ -0,0 +1,138 @@
+export type RectCommand = ReturnType<typeof parseRectCommand>;
+declare const parseRectCommand: (data: DataView, length: number) => {
+    readonly type: 1;
+    readonly pos: {
+        readonly x: number;
+        readonly y: number;
+    };
+    readonly size: {
+        readonly width: 1;
+        readonly height: 1;
+    };
+    readonly color?: undefined;
+} | {
+    readonly type: 2;
+    readonly pos: {
+        readonly x: number;
+        readonly y: number;
+    };
+    readonly size: {
+        readonly width: 1;
+        readonly height: 1;
+    };
+    readonly color: {
+        readonly r: number;
+        readonly g: number;
+        readonly b: number;
+    };
+} | {
+    readonly type: 3;
+    readonly pos: {
+        readonly x: number;
+        readonly y: number;
+    };
+    readonly size: {
+        readonly width: number;
+        readonly height: number;
+    };
+    readonly color?: undefined;
+} | {
+    readonly type: 4;
+    readonly pos: {
+        readonly x: number;
+        readonly y: number;
+    };
+    readonly size: {
+        readonly width: number;
+        readonly height: number;
+    };
+    readonly color: {
+        readonly r: number;
+        readonly g: number;
+        readonly b: number;
+    };
+} | {
+    readonly type: 0;
+    readonly pos: {
+        readonly x: number;
+        readonly y: number;
+    };
+    readonly size: {
+        readonly width: 0;
+        readonly height: 0;
+    };
+    readonly color?: undefined;
+};
+export type CharacterCommand = ReturnType<typeof parseCharacterCommand>;
+declare const parseCharacterCommand: (data: DataView, length: number) => {
+    character: string;
+    pos: {
+        x: number;
+        y: number;
+    };
+    foreground: {
+        r: number;
+        g: number;
+        b: number;
+    };
+    background: {
+        r: number;
+        g: number;
+        b: number;
+    };
+};
+export type WaveCommand = ReturnType<typeof parseWaveCommand>;
+declare const parseWaveCommand: (data: DataView, length: number) => {
+    color: {
+        r: number;
+        g: number;
+        b: number;
+    };
+    wave: number[];
+};
+export type KeyCommand = ReturnType<typeof parseKeyCommand>;
+declare const parseKeyCommand: (data: DataView, length: number) => {
+    keys: number;
+};
+export type SystemCommand = ReturnType<typeof parseSystemCommand>;
+declare const parseSystemCommand: (data: DataView, length: number) => {
+    model: "Headless" | "Beta M8" | "M8 Model:01" | "M8 Model:02";
+    version: string;
+    fontMode: 0 | 1 | 2;
+};
+/** System command plus the layout metrics derived from the model and font mode. */
+export type SystemInfos = {
+    model: SystemCommand['model'];
+    fontMode: SystemCommand['fontMode'];
+    spacingX: number;
+    spacingY: number;
+    offX: number;
+    offY: number;
+    screenWidth: number;
+    screenHeight: number;
+    rectOffset: number;
+};
+export type ProtocolEvents = {
+    rect: (data: RectCommand) => void;
+    text: (data: CharacterCommand) => void;
+    wave: (data: WaveCommand) => void;
+    key: (data: KeyCommand) => void;
+    system: (data: SystemCommand) => void;
+    systemInfo: (data: SystemInfos) => void;
+    any: (data: Uint8Array<ArrayBufferLike>) => void;
+};
+export declare const protocol: () => {
+    eventBus: {
+        emit: <K extends keyof ProtocolEvents>(event: K, ...args: Parameters<ProtocolEvents[K]>) => void;
+        on: <K extends keyof ProtocolEvents>(event: K, callback: ProtocolEvents[K]) => void;
+        off: <K extends keyof ProtocolEvents>(event: K, callback: ProtocolEvents[K]) => void;
+    };
+    dispatch: (data: DataView, dataLength: number) => void;
+    getSystemInfo: () => {
+        model: "Headless" | "Beta M8" | "M8 Model:01" | "M8 Model:02";
+        version: string;
+        fontMode: 0 | 1 | 2;
+    } | undefined;
+    getSystemInfos: () => SystemInfos;
+};
+export {};

package/types/engine/queuedReaders.d.ts

@@ -0,0 +1,18 @@
+export type SlipState = 'read' | 'escape' | 'error';
+export declare const createSlipParser: () => {
+    feed: (byte: number) => DataView | undefined;
+};
+export declare const queuedUsbReader: (device: USBDevice) => () => Promise<{
+    terminated: true;
+    data?: undefined;
+} | {
+    terminated: false;
+    data: DataView<ArrayBufferLike>;
+}>;
+export declare const queuedSerialReader: (reader: ReadableStreamDefaultReader<Uint8Array<ArrayBufferLike>>) => () => Promise<{
+    terminated: true;
+    data?: undefined;
+} | {
+    terminated: false;
+    data: DataView<ArrayBufferLike>;
+}>;

package/types/engine/store.d.ts

@@ -0,0 +1,65 @@
+import type { CursorPos, CursorRect, RGB } from '../types';
+/** Model, font mode and the layout metrics derived from them (from the M8's system command). */
+export interface M8SystemInfo {
+    model: string;
+    fontMode: number;
+    spacingX: number;
+    spacingY: number;
+    offX: number;
+    offY: number;
+    screenWidth: number;
+    screenHeight: number;
+    rectOffset: number;
+}
+export interface M8CellMetrics {
+    cellW: number;
+    cellH: number;
+    offX: number;
+    offY: number;
+}
+export interface M8MacroStatus {
+    running: boolean;
+    currentStep?: number;
+    sequenceLength?: number;
+}
+export interface M8StoreState {
+    /** Current view name (lowercased, cleaned). */
+    viewName: string | null;
+    /** Raw title row text. */
+    viewTitle: string | null;
+    minimapKey: string | null;
+    /** Cursor position in character grid coordinates (0..39, 0..23). */
+    cursorPos: CursorPos | null;
+    /** Cursor rectangle in M8 pixel space. */
+    cursorRect: CursorRect | null;
+    /** Whether the cursor is drawn as a 1px selection rectangle. */
+    selectionMode: boolean;
+    /** Foreground colour of the text under the cursor. */
+    highlightColor: RGB | null;
+    /** Colour of the cursor rectangle corners as last drawn. */
+    cursorColor: RGB | null;
+    textUnderCursor: string | null;
+    /** The whole screen row the cursor is on. */
+    currentLine: string | null;
+    titleColor: RGB | null;
+    backgroundColor: RGB | null;
+    deviceModel: string | null;
+    fontMode: number | null;
+    /** Pixel size and offset of one character cell (model and font dependent). */
+    cellMetrics: M8CellMetrics;
+    systemInfo: M8SystemInfo | null;
+    macroStatus: M8MacroStatus;
+}
+export type M8StoreKey = keyof M8StoreState;
+export interface M8Store {
+    get<K extends M8StoreKey>(key: K): M8StoreState[K];
+    /** Sets a value; listeners run synchronously, and only when the value changed (by identity). */
+    set<K extends M8StoreKey>(key: K, value: M8StoreState[K]): void;
+    /** Listens to one key. Returns the unsubscribe function. */
+    sub(key: M8StoreKey, listener: () => void): () => void;
+    /** Listens to every key. Returns the unsubscribe function. */
+    subAll(listener: (key: M8StoreKey) => void): () => void;
+    snapshot(): M8StoreState;
+}
+export declare const initialStoreState: () => M8StoreState;
+export declare const createM8Store: (initial?: Partial<M8StoreState>) => M8Store;

package/types/engine/viewExtractor.d.ts

@@ -0,0 +1,27 @@
+import type { CharacterCommand, RectCommand, SystemInfos } from './protocol';
+import type { M8Store } from './store';
+export declare const SCREEN_ROWS = 24;
+export declare const SCREEN_COLUMNS = 40;
+/** Colour of every character cell, row by row ('#rrggbb', null where nothing was drawn). */
+export type ScreenCellColors = {
+    fg: (string | null)[][];
+    bg: (string | null)[][];
+};
+/** The protocol events the extractor listens to (a ConnectedBus's protocol.eventBus fits). */
+export interface DrawEventSource {
+    on(event: 'text', callback: (data: CharacterCommand) => void): void;
+    on(event: 'rect', callback: (data: RectCommand) => void): void;
+    on(event: 'systemInfo', callback: (data: SystemInfos) => void): void;
+    off(event: 'text', callback: (data: CharacterCommand) => void): void;
+    off(event: 'rect', callback: (data: RectCommand) => void): void;
+    off(event: 'systemInfo', callback: (data: SystemInfos) => void): void;
+}
+export interface ViewExtractor {
+    /** Whole M8 screen as text rows, one string per row (columns preserved, trailing spaces trimmed). */
+    getScreenLines(): string[];
+    /** Colours of the whole M8 screen, same grid as getScreenLines. */
+    getScreenCellColors(): ScreenCellColors;
+    dispose(): void;
+}
+/** Listens to the draw stream and keeps `store` up to date. */
+export declare function registerViewExtractor(events: DrawEventSource, store: M8Store): ViewExtractor;

package/types/engine/viewGraph.d.ts

@@ -0,0 +1,9 @@
+import type { Graph } from './astar';
+export interface M8ViewGraph {
+    graph: Graph;
+    /** Explicit key frame sequences per edge: from -> to -> frames. */
+    edgeKeys: Map<string, Map<string, number[]>>;
+}
+export declare const getViewGraph: () => M8ViewGraph;
+/** Names of the M8 views, lowercased (as viewName reports them). */
+export declare const getViewNames: () => Set<string>;

package/types/engine/viewNavigation.d.ts

@@ -0,0 +1,16 @@
+import { type Direction } from './astar';
+import type { MacroRunner } from './macroRunner';
+import type { M8Store } from './store';
+/** Shift+direction frames, used for edges without an explicit key sequence. */
+export declare const toKeyMasks: (directions: Direction[], opts?: {
+    shift?: boolean;
+}) => number[];
+export interface ViewNavigation {
+    /** Resolves when the view is reached, no path is found, or the step limit is hit. */
+    navigateToView(viewName: string): Promise<void>;
+    dispose(): void;
+}
+export declare const createViewNavigation: ({ store, runner }: {
+    store: M8Store;
+    runner: MacroRunner;
+}) => ViewNavigation;

package/types/index.d.ts

@@ -1,4 +1,10 @@
-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 type { CursorPos, CursorRect, M8ClientEvents, M8ClientMethods, M8ClientMode, M8DeviceBus, M8DeviceConnectOptions, M8DeviceEvents, M8DeviceSupport, M8DeviceTransport, M8HostEvents, M8HostMethods, M8KeyName, M8Screen, M8ScreenCells, M8SdkConfig, M8State, M8TransportEvent, RGB, SystemInfos, } from './types';
+export { createM8Client, createM8ClientSync, getDeviceSupport, type M8Client, type M8Snapshot, YAM8D_FRAME_NAME } from './client';
+export { connection as createM8Connection, type ConnectedBus as M8ConnectedBus, type M8ConnectOptions } from './engine/connection';
+export { createM8Audio, getM8InputStream, type M8Audio, M8_AUDIO_CAPTURE_CONSTRAINTS } from './engine/audio';
+export { createM8Engine, type M8Engine, type M8EngineOptions } from './engine/engine';
+export { M8KeyMask, pressKeys } from './engine/keys';
+export type { M8MacroStatus, M8Store, M8StoreKey, M8StoreState } from './engine/store';
+export { getSemanticContext, parseGridScreen, readPlayPositions, parseViewTitle, SCREEN_MARGIN, describeContext, describeContextParts, formatFieldValue, lookupFxCommand, getInstrumentFxCommands, RELATIVE_FX_RULE, type M8FieldType, type M8ParsedField, type M8ParsedRow, type M8ScreenGridRow, type M8PlayPositions, 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 { parseThemeScreen, observeThemeColors, M8_THEME_ROLES, M8_THEME_VIEW, type M8Theme, type M8ThemeRole, } from './theme';
 export { default } from './client';

package/types/scaleInsight.d.ts

@@ -11,7 +11,7 @@ export interface M8ScaleNote {
     interval: string;
     /** Semitones above the first row ('C'), 0-11. */
     semitone: number;
-    /** true = ON, false = OFF, null = unset ('--'). */
+    /** true = ON, false = out of the scale ('--' on the device, 'OFF' if shown), null = not read. */
     enabled: boolean | null;
     /** Detune in semitones (-24..+24), null when unreadable. */
     offset: number | null;

package/types/theme.d.ts

@@ -0,0 +1,42 @@
+/**
+ * theme.ts
+ *
+ * The device theme: the 13 colours of the Theme View (System Settings > EDIT THEME),
+ * read off its screen, and the few colours any screen shows on its own.
+ */
+import type { M8Screen, M8State } from './types';
+export type M8ThemeRole = 'background' | 'textEmpty' | 'textInfo' | 'textDefault' | 'textValue' | 'textTitles' | 'playMarkers' | 'cursor' | 'selection' | 'scopeSlider' | 'meterLow' | 'meterMid' | 'meterPeak';
+/** The Theme View rows, top to bottom, with the label the device shows. */
+export declare const M8_THEME_ROLES: readonly {
+    role: M8ThemeRole;
+    label: string;
+}[];
+/** View name the SDK reports on the Theme View (title "THEME SETTINGS"). */
+export declare const M8_THEME_VIEW = "themesettings";
+export interface M8Theme {
+    /** Every theme colour as '#rrggbb'. */
+    colors: Record<M8ThemeRole, string>;
+    /** Colour model the Theme View was showing. HSV values are converted to RGB (H, S and V read as 00-FF). */
+    mode: 'rgb' | 'hsv';
+    /** THEME NAME, or null when unnamed. */
+    name: string | null;
+}
+/**
+ * Reads the theme off the Theme View screen (from getScreen()). Returns null unless
+ * all 13 colour rows are found, so a half-drawn screen is never taken for a theme.
+ *
+ * @example
+ * ```ts
+ * if (m8.state.viewName === M8_THEME_VIEW) {
+ *   const theme = parseThemeScreen(await m8.getScreen())
+ *   theme?.colors.textValue // '#ffffff'
+ * }
+ * ```
+ */
+export declare function parseThemeScreen(screen: M8Screen): M8Theme | null;
+/**
+ * The theme colours any screen gives away without opening the Theme View: the
+ * background and the title colour. (The cursor rectangle is animated on the device, so
+ * `state.cursorColor` is not the theme's CURSOR colour.)
+ */
+export declare function observeThemeColors(state: M8State): Partial<Record<M8ThemeRole, string>>;

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;
@@ -41,7 +46,32 @@ export interface M8Screen {
     /** 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>;
@@ -56,6 +86,11 @@ export interface M8HostMethods {
     sendKeyUp(): Promise<void>;
     getState(): Promise<M8State>;
     getScreen(): Promise<M8Screen>;
+    getScreenCells(): Promise<M8ScreenCells>;
+    enableMidiTransport(): Promise<{
+        ok: boolean;
+        error?: string;
+    }>;
 }
 export interface M8ClientMethods {
     ping(): Promise<string>;
@@ -78,6 +113,7 @@ export interface M8HostEvents {
     keyPressed: {
         keys: number;
     };
+    transport: M8TransportEvent;
 }
 export interface M8ClientEvents {
     ready: undefined;
@@ -85,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

@@ -219,6 +219,12 @@ 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
@@ -226,6 +232,37 @@ export interface M8DescriptionPart {
  * 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;
+}
+/**
+ * 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 readPlayPositions(viewName: string, screen: M8Screen): M8PlayPositions | null;
 /**
  * Derives a full semantic context from the current M8State.
  *