@yam8d/m8-sdk 0.5.6 → 0.5.7

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@yam8d/m8-sdk",
-  "version": "0.5.6",
+  "version": "0.5.7",
   "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/fxInsight.d.ts

@@ -3,7 +3,12 @@
  *
  * 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.
+ * described in terms of the command it shifts.
+ *
+ * REP does not type the command above it again: it shifts the value that command
+ * computed, on every row, by its own value counted in quarters (01 = +0.25,
+ * 04 = +1, FC = -1). The value stops at 00 and FF, or at the RTO value (absolute);
+ * it never wraps.
  *
  * Purely structural: works on already-parsed cells, no dependency on viewContext.
  */
@@ -28,7 +33,7 @@ export type FxLaneEvent =
  | 'replace'
 /** REP XX (XX>0) starts repeating. */
  | 'rep'
-/** REP XX while another REP was already running (new increment). */
+/** REP XX while another REP was already running (new step). */
  | 'repChange'
 /** REP 00 stops the repeat. */
  | 'repStop'
@@ -36,7 +41,7 @@ export type FxLaneEvent =
  | 'orphan'
 /** RTO sets the limit for the running REP. */
  | 'rto'
-/** Empty cell while a REP is active: the repeated command fires again. */
+/** Empty cell while a REP is active: the value is shifted once more. */
  | 'continue';
 export interface M8FxLaneTrace {
     /** FX lane, 1-3. */
@@ -52,13 +57,25 @@ export interface M8FxLaneTrace {
     } | null;
     /** True when a REP is running after this step. */
     active: boolean;
-    /** Per-step increment of the running REP (0x01-0xFF, 0x80+ = negative). */
+    /** The running REP's step as typed (0x01-0x7F up, 0x80-0xFF down), in quarters: 04 = +1 per row. */
     increment: number | null;
-    /** Value set with RTO, if any. */
+    /** Value set with RTO, if any: an absolute value, not a shift. */
     limit: number | null;
-    /** Value the repeated command has at this step (null when unknown). */
+    /**
+     * Value of the command at this step while a REP runs, whole part (00-FF). Null for a
+     * relative command (the instrument's own value is not on this screen: see `offset`),
+     * and when unknown.
+     */
     value: number | null;
-    /** True when `value` was clamped by the RTO limit. */
+    /**
+     * While a REP runs on a relative command: how far the parameter is from the instrument's
+     * own value (the command's signed value plus the REP's steps; 0.25 units). The stop at
+     * 00, FF or the RTO value is not applied, since the instrument's value is unknown here.
+     */
+    offset: number | null;
+    /** Why the REP no longer moves `value`: it reached FF, 00 or the RTO value. */
+    held: 'max' | 'min' | 'limit' | null;
+    /** True when `value` is held at the RTO value. */
     atLimit: boolean;
     /** Step where the running REP began. */
     repStartStep: number | null;
@@ -66,8 +83,14 @@ export interface M8FxLaneTrace {
     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. */
+/** Signed decimal reading of a relative value: 70 -> '+112', F0 -> '−16', 00 -> '±0'. */
+export declare const formatSignedFxValue: (value: number) => string;
+/** Hex text of a value, with its signed decimal reading when the command is relative: '70 (+112)', 'F0 (−16)'. */
 export declare function formatFxValue(cmd: string, value: number): string;
+/** A REP value in quarters: 00-7F up, 80-FF down. */
+export declare const repStepQuarters: (step: number) => number;
+/** A REP value as the decimal step it is: 01 -> '+0.25', 04 -> '+1', FC -> '−1'. */
+export declare function formatRepStep(step: number): string;
 export interface FxValueContext {
     /** Note on the same step (used by ARP to spell out the notes). */
     note?: string | null;
@@ -85,9 +108,9 @@ export declare function describeFxValue(cmd: string, value: number, ctx?: FxValu
  * 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.
+ * Model: REP XX shifts the value the lane's last command computed by XX quarters on
+ * each row (its own row included), keeps going through empty cells, and stops on a
+ * new command or REP00. RTO XX in the same lane sets the absolute value it 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;
@@ -102,15 +125,15 @@ export declare function describeFxLane(t: M8FxLaneTrace): string | null;
  */
 export interface M8RelativeFxState {
     cmd: string;
-    /** Net change applied to the parameter (signed; the device clamps to the parameter's range). */
+    /** Net change applied to the parameter (signed, in 0.25 units when a REP is involved; the device stops at the parameter's range). */
     total: number;
-    /** Times the command was applied (REP-driven repeats included). */
+    /** Rows that moved the parameter (the rows of a running REP 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. */
+    /** True when some of the change came from a running REP. */
     viaRep: boolean;
 }
 /**
@@ -125,7 +148,8 @@ export declare function relativeResetBy(row: FxStepRow): M8RelativeFxState['rese
  * 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
+ * A row that triggers resets first, then applies its own commands. A REP under a
+ * relative command adds its own step (in quarters) on each row. 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>;