@yam8d/m8-sdk 0.5.3 → 0.5.4

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@yam8d/m8-sdk",
-  "version": "0.5.3",
+  "version": "0.5.4",
   "description": "Client SDK for apps that read and drive a Dirtywave M8, inside a yam8d External Apps iframe or standalone over Web Serial, WebUSB or Web MIDI.",
   "type": "module",
   "main": "./dist/index.js",

package/types/client.d.ts

@@ -33,7 +33,7 @@ export interface M8Client {
     /** Standalone: the API the device is connected through, null while disconnected (always null in host mode). */
     readonly deviceTransport: M8DeviceTransport | null;
     navigateToView(viewName: string): Promise<boolean>;
-    navigateTo(x: number, y: number): Promise<void>;
+    navigateTo(x: number, y: number): Promise<boolean>;
     setValueToHex(targetHex: number): Promise<boolean>;
     setValueToInt(targetInt: number): Promise<boolean>;
     setValueFloat(targetFloat: number): Promise<boolean>;

package/types/engine/cursorMap.d.ts

@@ -0,0 +1,60 @@
+export type CursorDir = 'up' | 'down' | 'left' | 'right';
+export type CellRect = {
+    x: number;
+    y: number;
+    w: number;
+    h: number;
+};
+/** The cells and moves of one layout. A move to `null` means the key did not move the cursor. */
+export interface CursorLayout {
+    readonly cells: Map<string, CellRect>;
+    readonly moves: Map<string, Partial<Record<CursorDir, string | null>>>;
+    readonly unreachable: Set<string>;
+    /** Texts that failed once: one more failure makes them unreachable. */
+    readonly suspects: Set<string>;
+}
+export type CursorMapData = {
+    version: 1;
+    layouts: {
+        key: string;
+        cells: string[];
+        moves: [string, CursorDir, string | null][];
+        unreachable: string[];
+        suspects?: string[];
+    }[];
+};
+export interface CursorMap {
+    /** The layout, or undefined when nothing was learned for it. */
+    get(key: string): CursorLayout | undefined;
+    recordCell(key: string, rect: CellRect): void;
+    /** `to` null: the key was pressed and the cursor did not move. */
+    recordMove(key: string, from: CellRect, dir: CursorDir, to: CellRect | null): void;
+    /** A navigation could not reach this text: the second time, it is unreachable. */
+    markUnreachable(key: string, textKey: string): void;
+    toJSON(): CursorMapData;
+}
+export declare const DIRS: readonly CursorDir[];
+export declare const cellId: (rect: CellRect) => string;
+export declare const parseCellId: (id: string) => CellRect | null;
+export declare const createCursorMap: (options?: {
+    data?: CursorMapData | null;
+    onChange?: () => void;
+}) => CursorMap;
+/** Whether a move landed on the wrong side (Up landing lower...): a wrap, not a move on this screen. */
+export declare const wentBackwards: (from: CellRect, dir: CursorDir, to: CellRect) => boolean;
+/**
+ * Where a key not learned yet probably goes: Up/Down to the nearest cell above/below that shares
+ * columns with this one, Left/Right to the nearest cell of the same row. Null when there is none.
+ */
+export declare const guessMove: (layout: CursorLayout, from: CellRect, dir: CursorDir) => string | null;
+/**
+ * Cheapest key sequence from `fromId` to a cell that `isGoal` accepts, over the learned moves and,
+ * for keys not learned yet from a cell, the move `guessMove` expects (marked `guessed`). Moves
+ * listed in `skip` (`"<cellId>:<dir>"`) or refused by `forbid` are not used, learned or guessed,
+ * nor are learned moves that went backwards (a phrase wrapping to the next one). Null when no path exists.
+ */
+export declare const findPath: (layout: CursorLayout, fromId: string, isGoal: (id: string) => boolean, skip?: ReadonlySet<string>, forbid?: (rect: CellRect, dir: CursorDir) => boolean) => {
+    dir: CursorDir;
+    to: string;
+    guessed: boolean;
+}[] | null;

package/types/engine/cursorNavigator.d.ts

@@ -1,15 +1,22 @@
 import type { EngineBus } from './bus';
+import { type CursorMap } from './cursorMap';
+import { type Point } from './cursorTargets';
 import type { M8Store } from './store';
-export type Point = {
-    x: number;
-    y: number;
-};
+export type { Point } from './cursorTargets';
 export interface CursorNavigator {
-    /** Moves the cursor towards `target` (M8 pixel coordinates). Resolves when it stops. */
-    navigateTo(target: Point): Promise<void>;
+    /**
+     * Moves the cursor to the cell at or nearest to `target` (M8 pixel coordinates). Resolves true
+     * when it got there, false when it stopped on the closest cell it could reach (or was cancelled).
+     */
+    navigateTo(target: Point): Promise<boolean>;
     dispose(): void;
 }
-export declare const createCursorNavigator: ({ bus, store }: {
+export interface CursorNavigatorDeps {
     bus: EngineBus;
     store: M8Store;
-}) => CursorNavigator;
+    /** The screen text (one string per row, columns kept), used to find the cells near a click. */
+    getScreenLines?: () => string[];
+    /** Where the learned layouts are kept; a new empty map by default. */
+    cursorMap?: CursorMap;
+}
+export declare const createCursorNavigator: ({ bus, store, getScreenLines, cursorMap, }: CursorNavigatorDeps) => CursorNavigator;

package/types/engine/cursorTargets.d.ts

@@ -0,0 +1,86 @@
+import { type CellRect, type CursorLayout } from './cursorMap';
+import type { M8CellMetrics } from './store';
+export type Point = {
+    x: number;
+    y: number;
+};
+/**
+ * Where the cursor should go. `cell`: a learned cursor cell (reached when the cursor is that cell).
+ * `text`: text no learned cell covers yet; `rect` is the character aimed at (reached when the
+ * cursor covers it), `run` the whole run (one run can be two cells, as an FX command and value).
+ * `point`: no text near the point, or selection mode (reached when the cursor covers the point).
+ */
+export type CursorGoal = {
+    kind: 'cell';
+    id: string;
+    rect: CellRect;
+} | {
+    kind: 'text';
+    key: string;
+    rect: CellRect;
+    run: CellRect;
+    row: number;
+} | {
+    kind: 'point';
+    rect: CellRect;
+};
+export type TextRun = {
+    key: string;
+    rect: CellRect;
+    row: number;
+    col: number;
+    text: string;
+};
+export type GridRows = {
+    first: number;
+    last: number;
+    numberWidth: number;
+};
+/** The first and last rows that start with a row number, on grid views that have one; else null. */
+export declare const gridRows: (viewName: string | null, lines: readonly string[]) => GridRows | null;
+/** A cursor rectangle as the character cells it covers (column, row, width in characters). */
+export declare const snapToGrid: (rect: CellRect, metrics: M8CellMetrics) => CellRect;
+/** The screen row of a cursor cell. */
+export declare const rowOf: (rect: CellRect, metrics: M8CellMetrics) => number;
+/** First column of the track panel, or null when the layout has no 40 columns. */
+export declare const panelColumnFor: (screenWidth: number, metrics: M8CellMetrics) => number | null;
+/**
+ * The labels that start the rows (words with a letter outside hex digits, two characters or more).
+ * Values, row numbers and markers are left out, so the signature changes with the layout
+ * (instrument type, modulator type) but not with the song.
+ */
+export declare const layoutSignature: (lines: readonly string[], panelColumn: number | null) => string;
+/**
+ * Runs of text on the screen, in M8 pixels. Column 0 (the playback marker margin) is left out, and
+ * so are the characters `covered` says belong to a known cell.
+ */
+export declare const textRuns: (lines: readonly string[], metrics: M8CellMetrics, panelColumn: number | null, covered?: (row: number, col: number) => boolean) => TextRun[];
+/** Whether the screen has text under a cursor cell (the same columns as textUnderCursor). */
+export declare const cellHasText: (rect: CellRect, lines: readonly string[], metrics: M8CellMetrics) => boolean;
+/** Whether `cursor` covers `target` horizontally (at least half a character, or half the target). */
+export declare const coversX: (cursor: CellRect, target: CellRect, metrics: M8CellMetrics) => boolean;
+/** Whether `cursor` covers `target` vertically (at least half a row, or half the target). */
+export declare const coversY: (cursor: CellRect, target: CellRect, metrics: M8CellMetrics) => boolean;
+export declare const covers: (cursor: CellRect, target: CellRect, metrics: M8CellMetrics) => boolean;
+/** How far the cursor is from a target: the gap between the rectangles, plus a small centre term to break ties. */
+export declare const rectDistance: (a: CellRect, b: CellRect) => number;
+export declare const pointGoal: (point: Point) => CursorGoal;
+/** Whether the cursor rectangle has reached the goal. */
+export declare const goalReached: (goal: CursorGoal, cursor: CellRect, metrics: M8CellMetrics) => boolean;
+/**
+ * What a click can go to: the learned cells with text on screen, and the runs of the text they do
+ * not cover (an FX value stays a candidate once only its command is learned).
+ */
+export declare const candidates: (layout: CursorLayout | undefined, lines: readonly string[], metrics: M8CellMetrics, panelColumn: number | null, grid?: GridRows | null) => {
+    cells: {
+        id: string;
+        rect: CellRect;
+    }[];
+    runs: TextRun[];
+};
+/** The candidate nearest to `point`, or a point goal when the screen offers none. */
+export declare const pickGoal: (point: Point, layout: CursorLayout | undefined, lines: readonly string[], metrics: M8CellMetrics, panelColumn: number | null, grid?: GridRows | null, 
+/** Texts to leave out besides the unreachable ones (those that failed in this navigation). */
+skip?: ReadonlySet<string>, 
+/** After a text failed: only learned cells and texts beside the click (not the next label down the column). */
+knownFirst?: boolean) => CursorGoal;

package/types/engine/engine.d.ts

@@ -1,5 +1,6 @@
 import type { M8HostEvents, M8HostMethods, M8State } from '../types';
 import type { EngineBus } from './bus';
+import { type CursorMap } from './cursorMap';
 import { type Point } from './cursorNavigator';
 import { type MacroRunner } from './macroRunner';
 import { type M8Store } from './store';
@@ -10,6 +11,8 @@ export interface M8EngineOptions {
     cancelMacroOnKeydown?: boolean;
     /** Use this store instead of a new one (for tests, or to keep state across reconnects). */
     store?: M8Store;
+    /** Where the cursor navigator keeps the layouts it learns (share one to keep them across reconnects). */
+    cursorMap?: CursorMap;
 }
 export interface M8Engine {
     readonly bus: EngineBus;
@@ -17,8 +20,8 @@ export interface M8Engine {
     /** The SDK methods, as an iframe client or the standalone client calls them. */
     readonly methods: M8HostMethods;
     readonly macro: MacroRunner;
-    /** Moves the cursor towards a point in M8 pixel coordinates. */
-    navigateTo(point: Point): Promise<void>;
+    /** Moves the cursor to the cell at or nearest to a point in M8 pixel coordinates. Resolves true when it got there. */
+    navigateTo(point: Point): Promise<boolean>;
     /** Resolves true when the view is reached. */
     navigateToView(viewName: string): Promise<boolean>;
     getState(): M8State;

package/types/engine/host/hostMethods.d.ts

@@ -11,7 +11,7 @@ export type HostMethodsDeps = {
     navigateTo: (point: {
         x: number;
         y: number;
-    }) => Promise<void>;
+    }) => Promise<boolean>;
     enableMidiTransport: () => Promise<{
         ok: boolean;
         error?: string;

package/types/engine/index.d.ts

@@ -1,6 +1,7 @@
 export type { EngineBus, ProtocolEventBus } from './bus';
 export { connectWithRetry } from './connectWithRetry';
 export { type ConnectedBus, connection, decode7BitPacked, type M8ConnectOptions, type M8DeviceTransport } from './connection';
+export { type CellRect, type CursorDir, type CursorLayout, type CursorMap, type CursorMapData, createCursorMap } from './cursorMap';
 export { type CursorNavigator, createCursorNavigator, type Point } from './cursorNavigator';
 export { createM8Engine, type M8Engine, type M8EngineOptions } from './engine';
 export { createEventBus } from './eventBus';

package/types/engine/viewNavigation.d.ts

@@ -16,6 +16,6 @@ export interface ViewNavigationDeps {
     /** The 24 text rows of the screen, to find buttons by their label. */
     getScreenLines?: () => string[];
     /** Moves the cursor to a text grid cell. Without it, button edges are not used. */
-    moveCursor?: (x: number, y: number) => Promise<void>;
+    moveCursor?: (x: number, y: number) => Promise<unknown>;
 }
 export declare const createViewNavigation: ({ store, runner, getScreenLines, moveCursor }: ViewNavigationDeps) => ViewNavigation;

package/types/types.d.ts

@@ -74,7 +74,8 @@ export interface M8TransportEvent {
 }
 export interface M8HostMethods {
     navigateToView(viewName: string): Promise<boolean>;
-    navigateTo(x: number, y: number): Promise<void>;
+    /** Moves the cursor to the cell at or nearest to a text grid position. Resolves true when it got there. */
+    navigateTo(x: number, y: number): Promise<boolean>;
     setValueToHex(targetHex: number): Promise<boolean>;
     setValueToInt(targetInt: number): Promise<boolean>;
     setValueFloat(targetFloat: number): Promise<boolean>;