@yam8d/m8-sdk 0.3.3 → 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/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,10 @@
-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, 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/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 = 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;
+}
+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/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>>;