@yam8d/m8-sdk 0.3.3 → 0.4.0

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,108 @@ 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;
 }
 /**
- * Look up the description of a 3-character FX command name.
- * Returns undefined if the command is unknown.
+ * 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 function lookupFxCommand(cmd: string): {
-    description: string;
-} | undefined;
+export declare const SCREEN_MARGIN = 1;
 /**
  * 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 +244,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;