@hraness/dawg 0.6.1 → 0.8.0

package/src/tui/fader.ts

@@ -9,7 +9,27 @@
  * field, so repeated nudges replace one staged edit and Enter keeps them
  * all as one revision.
  */
-import type { DrawerField, DrawerView } from "../../tui/drawer.ts";
+import type { DrawerAside, DrawerField, DrawerView } from "../../tui/drawer.ts";
+import type { KnobIndex } from "../../tui/knobs.ts";
+import {
+  KEY_BACKSPACE,
+  KEY_BACKTAB,
+  KEY_COARSE_LEFT,
+  KEY_COARSE_RIGHT,
+  KEY_DOWN,
+  KEY_END,
+  KEY_ENTER,
+  KEY_FINE_LEFT,
+  KEY_FINE_RIGHT,
+  KEY_HOME,
+  KEY_LEFT,
+  KEY_PAGE_DOWN,
+  KEY_PAGE_UP,
+  KEY_RESET,
+  KEY_RIGHT,
+  KEY_TAB,
+  KEY_UP,
+} from "../../tui/grammar.ts";
 
 export type FaderNumber = Readonly<{
   kind: "number";
@@ -22,7 +42,7 @@ export type FaderNumber = Readonly<{
   command: (value: number) => string;
   /** Typed text → command; undefined when it does not parse or fit. */
   parse: (text: string) => string | undefined;
-  /** The command `0` / `d` runs to put the value back to its default. */
+  /** The command `x` / `d` / Delete runs to put the value back. */
   reset?: string | undefined;
   /** Starting value for a nudge while off. */
   start?: number | undefined;
@@ -44,6 +64,8 @@ export interface FaderState {
   label: string;
   /** Digits typed for the focused field. */
   typing?: string | undefined;
+  /** The field that just snapped onto a detent: flashes for one frame. */
+  flash?: string | undefined;
 }
 
 export type FaderResult =
@@ -111,6 +133,85 @@ function snap(spec: FaderNumber, raw: number): number {
   return Math.min(spec.max, Math.max(spec.min, best));
 }
 
+/**
+ * Detents: values a fader catches on its way past, so the common resting
+ * points are easy to hit by feel. Volume 1 (0 dB), pan 0 (center), whole
+ * BPM, mix 0 / 0.5 / 1 and filter cutoffs on the octaves of A (27.5 Hz,
+ * 55 Hz … 14080 Hz). Read off the field's command, so every row that runs
+ * `volume`, `pan`, `tempo`, `… mix` or a cutoff gets them.
+ */
+export type Detents = readonly number[] | "integer";
+
+/** How close (as a share of the bar) a value must be to catch a detent. */
+export const DETENT_REACH = 0.02;
+
+const A_OCTAVES = Object.freeze(
+  Array.from({ length: 10 }, (_, octave) => 27.5 * 2 ** octave),
+);
+
+export function detentsFor(spec: FaderNumber): Detents | undefined {
+  const probe = spec.value ?? spec.start ?? spec.min;
+  const command = spec.command(probe).replace(/\s+\S+$/, "");
+  const words = command.split(/\s+/);
+  const verb = words[0]?.replace(/^\//, "");
+  if (verb === "tempo" && words.length === 1) return "integer";
+  if (words.includes("volume")) return [1];
+  if (words.includes("pan")) return [0];
+  if (words.at(-1) === "mix") return [0, 0.5, 1];
+  if (/^(cutoff|lpf|hpf)$/.test(words.at(-1) ?? "")) return A_OCTAVES;
+  return undefined;
+}
+
+/** The detents of `spec` that fall inside its range. */
+function detentList(spec: FaderNumber, detents: Detents): number[] {
+  if (detents === "integer") return [];
+  return detents.filter((d) => d >= spec.min - 1e-9 && d <= spec.max + 1e-9);
+}
+
+/**
+ * `value` caught by a detent, or undefined when none is in reach. With
+ * `from` (a key step) a detent also catches a step that jumps over it or
+ * lands near it while moving toward it, so leaving a detent never sticks.
+ */
+export function detentSnap(
+  spec: FaderNumber,
+  value: number,
+  from?: number,
+): number | undefined {
+  const detents = detentsFor(spec);
+  if (!detents) return undefined;
+  if (detents === "integer") {
+    const whole = Math.min(spec.max, Math.max(spec.min, Math.round(value)));
+    return Math.abs(whole - value) < 1e-9 ? undefined : whole;
+  }
+  const at = (v: number) => faderPosition(spec, v);
+  let best: number | undefined;
+  for (const detent of detentList(spec, detents)) {
+    // Landing on a detent exactly counts as a catch (it flashes) unless
+    // the value was already there.
+    if (Math.abs(detent - value) < 1e-9)
+      return from !== undefined && Math.abs(detent - from) > 1e-9
+        ? detent
+        : undefined;
+    const near = Math.abs(at(value) - at(detent)) <= DETENT_REACH;
+    let caught = near;
+    if (from !== undefined) {
+      const toward = Math.sign(detent - from) === Math.sign(value - from);
+      const crossed =
+        (from < detent && detent < value) || (value < detent && detent < from);
+      caught = Math.abs(detent - from) > 1e-9 && (crossed || (near && toward));
+    }
+    if (
+      caught &&
+      (best === undefined ||
+        Math.abs(at(detent) - at(from ?? value)) <
+          Math.abs(at(best) - at(from ?? value)))
+    )
+      best = detent;
+  }
+  return best;
+}
+
 /** Fine (a tenth of a step), normal, coarse (five steps) or page (twenty). */
 export type StepSize = "fine" | "normal" | "coarse" | "page";
 
@@ -142,20 +243,9 @@ export function stepValue(
   return value;
 }
 
-const LEFT = new Set(["\u001b[D", "\u001bOD", "h", "-", "_"]);
-const RIGHT = new Set(["\u001b[C", "\u001bOC", "l", "+", "="]);
-const COARSE_LEFT = new Set(["\u001b[1;2D", "{"]);
-const COARSE_RIGHT = new Set(["\u001b[1;2C", "}"]);
-const FINE_LEFT = new Set(["\u001b[1;3D", "\u001b[1;5D", "\u001bb", "["]);
-const FINE_RIGHT = new Set(["\u001b[1;3C", "\u001b[1;5C", "\u001bf", "]"]);
-const UP = new Set(["\u001b[A", "\u001bOA", "k", "\u001b[Z"]);
-const DOWN = new Set(["\u001b[B", "\u001bOB", "j", "\t"]);
-const PAGE_UP = "\u001b[5~";
-const PAGE_DOWN = "\u001b[6~";
-const HOME = new Set(["\u001b[H", "\u001bOH", "\u001b[1~"]);
-const END = new Set(["\u001b[F", "\u001bOF", "\u001b[4~"]);
-const ENTER = new Set(["\r", "\n"]);
-const BACKSPACE = new Set(["\u007f", "\b"]);
+/** ↑ and shift-tab: the previous param; ↓ and tab: the next. */
+const isUp = (value: string) => KEY_UP.has(value) || KEY_BACKTAB.has(value);
+const isDown = (value: string) => KEY_DOWN.has(value) || KEY_TAB.has(value);
 
 export interface FaderKeyOptions {
   /** Edits are staged (Enter keeps, Esc reverts). */
@@ -185,6 +275,32 @@ function setNumber(spec: FaderNumber, value: number): FaderResult {
   };
 }
 
+/**
+ * Set `value`, caught by a detent unless the step is fine. `from` is the
+ * value a key step left (undefined for a drag or a click on the bar).
+ */
+function setSnapped(
+  state: FaderState,
+  spec: FaderNumber,
+  value: number,
+  from: number | undefined,
+  size: StepSize | "drag",
+): FaderResult {
+  const snapped =
+    size === "fine"
+      ? undefined
+      : size === "drag"
+        ? (detentSnap(spec, value) ??
+          (spec.value !== undefined &&
+          detentSnap(spec, value, spec.value) === value
+            ? value
+            : undefined))
+        : detentSnap(spec, value, from);
+  const result = setNumber(spec, snapped ?? value);
+  if (snapped !== undefined && result.type === "set") state.flash = spec.label;
+  return result;
+}
+
 function setChoice(spec: FaderChoice, index: number): FaderResult {
   const option =
     spec.options[Math.min(spec.options.length - 1, Math.max(0, index))];
@@ -215,12 +331,12 @@ export function faderKeyPress(
       state.typing = undefined;
       return { type: "handled" };
     }
-    if (BACKSPACE.has(value)) {
+    if (KEY_BACKSPACE.has(value)) {
       state.typing = state.typing.slice(0, -1);
       if (!state.typing) state.typing = undefined;
       return { type: "handled" };
     }
-    if (ENTER.has(value) || value === "\t") {
+    if (KEY_ENTER.has(value) || KEY_TAB.has(value)) {
       const text = state.typing;
       state.typing = undefined;
       const command = field.kind === "number" ? field.parse(text) : undefined;
@@ -236,9 +352,9 @@ export function faderKeyPress(
   }
   if (value === "\u001b")
     return options.dirty ? { type: "revert" } : { type: "close" };
-  if (ENTER.has(value))
+  if (KEY_ENTER.has(value))
     return options.dirty ? { type: "keep" } : { type: "close" };
-  const move = UP.has(value) ? -1 : DOWN.has(value) ? 1 : 0;
+  const move = isUp(value) ? -1 : isDown(value) ? 1 : 0;
   if (move) {
     state.label = fields[(index + move + fields.length) % fields.length]!.label;
     return { type: "handled" };
@@ -250,30 +366,46 @@ export function faderKeyPress(
   }
   if (field.kind === "choice") {
     const at = Math.max(0, field.options.indexOf(field.value));
-    if (LEFT.has(value) || FINE_LEFT.has(value) || COARSE_LEFT.has(value))
+    if (
+      KEY_LEFT.has(value) ||
+      KEY_FINE_LEFT.has(value) ||
+      KEY_COARSE_LEFT.has(value)
+    )
       return setChoice(field, at - 1);
-    if (RIGHT.has(value) || FINE_RIGHT.has(value) || COARSE_RIGHT.has(value))
+    if (
+      KEY_RIGHT.has(value) ||
+      KEY_FINE_RIGHT.has(value) ||
+      KEY_COARSE_RIGHT.has(value)
+    )
       return setChoice(field, at + 1);
-    if (HOME.has(value) || value === PAGE_DOWN) return setChoice(field, 0);
-    if (END.has(value) || value === PAGE_UP)
+    if (KEY_HOME.has(value) || KEY_PAGE_DOWN.has(value))
+      return setChoice(field, 0);
+    if (KEY_END.has(value) || KEY_PAGE_UP.has(value))
       return setChoice(field, field.options.length - 1);
     // 1…9 picks an option by number.
     if (/^[1-9]$/.test(value)) return setChoice(field, Number(value) - 1);
     return { type: "handled" };
   }
   const step = (direction: 1 | -1, size: StepSize) =>
-    setNumber(field, stepValue(field, direction, size));
-  if (LEFT.has(value)) return step(-1, "normal");
-  if (RIGHT.has(value)) return step(1, "normal");
-  if (COARSE_LEFT.has(value)) return step(-1, "coarse");
-  if (COARSE_RIGHT.has(value)) return step(1, "coarse");
-  if (FINE_LEFT.has(value)) return step(-1, "fine");
-  if (FINE_RIGHT.has(value)) return step(1, "fine");
-  if (value === PAGE_UP) return step(1, "page");
-  if (value === PAGE_DOWN) return step(-1, "page");
-  if (HOME.has(value)) return setNumber(field, field.min);
-  if (END.has(value)) return setNumber(field, field.max);
-  if (value === "0" || value === "d") {
+    setSnapped(
+      state,
+      field,
+      stepValue(field, direction, size),
+      field.value,
+      size,
+    );
+  if (KEY_LEFT.has(value)) return step(-1, "normal");
+  if (KEY_RIGHT.has(value)) return step(1, "normal");
+  if (KEY_COARSE_LEFT.has(value)) return step(-1, "coarse");
+  if (KEY_COARSE_RIGHT.has(value)) return step(1, "coarse");
+  if (KEY_FINE_LEFT.has(value)) return step(-1, "fine");
+  if (KEY_FINE_RIGHT.has(value)) return step(1, "fine");
+  if (KEY_PAGE_UP.has(value)) return step(1, "page");
+  if (KEY_PAGE_DOWN.has(value)) return step(-1, "page");
+  if (KEY_HOME.has(value)) return setNumber(field, field.min);
+  if (KEY_END.has(value)) return setNumber(field, field.max);
+  // x, d and Delete put the value back; 0-9 and . start typing.
+  if (KEY_RESET.has(value)) {
     const reset =
       field.reset ??
       (field.start !== undefined ? field.command(field.start) : undefined);
@@ -281,7 +413,7 @@ export function faderKeyPress(
       ? { type: "set", command: reset, key: faderKey(field.label) }
       : { type: "handled" };
   }
-  if (/^[1-9.]$/.test(value)) {
+  if (/^[0-9.]$/.test(value)) {
     state.typing = value === "." ? "0." : value;
     return { type: "handled" };
   }
@@ -302,7 +434,13 @@ export function faderSetPosition(
       field,
       Math.round(position * Math.max(0, field.options.length - 1)),
     );
-  return setNumber(field, faderValueAt(field, position));
+  return setSnapped(
+    state,
+    field,
+    faderValueAt(field, position),
+    undefined,
+    "drag",
+  );
 }
 
 /** A [−] / [+] click or a wheel notch on a field. */
@@ -319,7 +457,13 @@ export function faderStep(
     const at = Math.max(0, field.options.indexOf(field.value));
     return setChoice(field, at + direction);
   }
-  return setNumber(field, stepValue(field, direction, size));
+  return setSnapped(
+    state,
+    field,
+    stepValue(field, direction, size),
+    field.value,
+    size,
+  );
 }
 
 /** A click on one option of a choice field. */
@@ -334,8 +478,33 @@ export function faderChoose(
   return setChoice(field, option);
 }
 
-const HINT =
-  "←→ adjust · ⇧←→ coarse · [ ] fine · ↑↓ param · 0-9 type · d default · enter keep · esc revert";
+/**
+ * Most important first: fitHint trims the middle from the right, so at 80
+ * columns the coarse and fine steps go before `enter keep` or `x reset`.
+ */
+export const FADER_HINT =
+  "←→ adjust · enter keep · x reset · 0-9 type · ↑↓ param · ⇧←→ coarse · [ ] fine · esc revert";
+
+/**
+ * The hint for a field the loop cannot stage (tempo, meter, loop length):
+ * each step is a new revision, so there is nothing to keep or revert.
+ */
+/** The knob front page (design §8.6): the four knobs, then Tab for all. */
+export const KNOB_FADER_HINT =
+  "↑↓ knob · ←→ turn · tab all · enter keep · ⇧ coarse · x reset · esc revert";
+
+/** Every param behind Tab: Tab goes back to the four knobs. */
+export const ALL_FADER_HINT =
+  "←→ adjust · ↑↓ param · tab knobs · enter keep · ⇧ coarse · x reset · esc revert";
+
+export const FADER_HINT_AT_ONCE =
+  "←→ adjust · applies at once · x reset · 0-9 type · ↑↓ param · ⇧←→ coarse · [ ] fine · esc back";
+
+/** The value a field's next step starts from (for checking what it runs). */
+export function faderCommand(field: FaderSpec): string {
+  if (field.kind === "choice") return field.command(field.value);
+  return field.command(field.value ?? field.start ?? field.min);
+}
 
 /** The drawer's paint model for `fields` (staged) beside `committed`. */
 export function drawerView(
@@ -345,11 +514,20 @@ export function drawerView(
   options: {
     title: string;
     dirty: boolean;
+    /** How many edits are staged (defaults to 1 while dirty). */
+    staged?: number | undefined;
     status?: string | undefined;
     hint?: string;
+    /** The focused field applies at once (cannot stage on the loop). */
+    atOnce?: boolean | undefined;
+    /** The drawer has a knob page: which side of Tab is up. */
+    knobs?: "knobs" | "all" | undefined;
   },
 ): DrawerView {
   const before = new Map(committed.map((field) => [field.label, field]));
+  // A detent flash lasts one view: consume it here.
+  const flash = state.flash;
+  state.flash = undefined;
   const drawn: DrawerField[] = fields.map((field) => {
     const was = before.get(field.label);
     if (field.kind === "choice") {
@@ -361,6 +539,7 @@ export function drawerView(
       return {
         kind: "choice",
         label: field.label,
+        knob: knobOf(field),
         options: field.options,
         index,
         committedIndex:
@@ -383,6 +562,7 @@ export function drawerView(
     return {
       kind: "number",
       label: field.label,
+      knob: knobOf(field),
       text,
       committed: changed ? wasText : undefined,
       position:
@@ -395,15 +575,75 @@ export function drawerView(
           : undefined,
       minText: field.format(field.min),
       maxText: field.format(field.max),
+      ...(flash === field.label && field.value !== undefined
+        ? { flash: detentLabel(field, field.value) }
+        : {}),
     };
   });
+  const staged = options.staged ?? (options.dirty ? 1 : 0);
   return {
     title: options.title,
     fields: drawn,
     focus: focusIndex(state, fields),
     typing: state.typing,
     dirty: options.dirty,
+    badge: options.dirty ? stagedBadge(staged) : undefined,
     status: options.status,
-    hint: options.hint ?? HINT,
+    hint:
+      options.hint ??
+      (options.knobs
+        ? (options.knobs === "knobs" ? KNOB_FADER_HINT : ALL_FADER_HINT)
+            .replace(
+              "enter keep",
+              options.atOnce ? "applies at once" : "enter keep",
+            )
+            .replace("esc revert", options.atOnce ? "esc back" : "esc revert")
+        : options.atOnce
+          ? FADER_HINT_AT_ONCE
+          : FADER_HINT),
   };
 }
+
+/**
+ * The drawer's side list: every param on the page with its value, each one
+ * a knob also drives wearing that knob (matched by label).
+ */
+export function drawerAside(
+  page: readonly FaderSpec[],
+  knobs: readonly FaderSpec[],
+): DrawerAside[] {
+  const knobByLabel = new Map(
+    knobs.map((field) => [field.label, knobOf(field)] as const),
+  );
+  return page.map((field) => ({
+    label: field.label,
+    text:
+      field.kind === "choice"
+        ? field.value
+        : field.value === undefined
+          ? (field.off ?? "off")
+          : field.format(field.value),
+    knob: knobByLabel.get(field.label),
+  }));
+}
+
+/** A knob field's knob (0 blue … 3 orange); plain rows have none. */
+function knobOf(field: FaderSpec): KnobIndex | undefined {
+  const knob = (field as FaderSpec & { knob?: KnobIndex }).knob;
+  return knob;
+}
+
+/** `A/B: 1 change staged · enter keep · esc revert`. */
+export function stagedBadge(count: number): string {
+  const n = Math.max(1, count);
+  return `A/B: ${n} change${n === 1 ? "" : "s"} staged · enter keep · esc revert`;
+}
+
+/** The faint word a detent flashes: `0 dB`, `center`, or the value. */
+export function detentLabel(spec: FaderNumber, value: number): string {
+  const text = spec.format(value);
+  // Volume formats as `1 · 0.0 dB`; the flash names the detent itself.
+  const db = /(-?[\d.]+) dB$/.exec(text);
+  if (db && Number(db[1]) === 0) return "0 dB";
+  return text;
+}

package/src/tui/granular-menu.ts

@@ -135,9 +135,7 @@ export function granularMenuLabel(
 ): string | undefined {
   if (!track || track.kit || isDrumInstrument(track.instrument))
     return undefined;
-  return isGranularInstrument(track.instrument)
-    ? "granular"
-    : "granular (convert)";
+  return isGranularInstrument(track.instrument) ? "granular" : "granular";
 }
 
 /** One-line state for the subsection's detail column. */
@@ -265,7 +263,7 @@ export function granularMenuNodes(
   return nodes;
 }
 
-/** Sound > browse sounds > Granular: one row per preset. */
+/** Sound › instruments › granular: one row per preset. */
 export function granularBrowseNodes(): GranularMenuNode[] {
   return GRANULAR_PRESET_NAMES.map((name) => ({
     kind: "action",

package/src/tui/knob-fields.ts

@@ -0,0 +1,107 @@
+/**
+ * The four knobs of a page as fader fields: each path of a KNOB_MAPS row
+ * (src/tui/knob-map.ts) resolved in the live Ctrl-K tree, so a knob turns
+ * exactly what that menu row turns and runs the same typed command.
+ */
+import type { KnobIndex } from "../../tui/knobs.ts";
+import type { FaderSpec } from "./fader.ts";
+import { knobMap, type KnobMap } from "./knob-map.ts";
+import {
+  faderSpecs,
+  rootNodes,
+  type MenuContext,
+  type MenuNode,
+} from "./menu.ts";
+
+export type KnobField = FaderSpec & { knob: KnobIndex };
+
+const norm = (text: string) => text.trim().toLowerCase();
+
+function matches(node: MenuNode, segment: string): boolean {
+  const want = norm(segment);
+  if (want.endsWith("*"))
+    return node.kind === "menu" && norm(node.id).startsWith(want.slice(0, -1));
+  if (node.kind === "menu" && norm(node.id) === want) return true;
+  return norm(node.label) === want;
+}
+
+/** The row a knob path reaches from the root, or undefined. */
+export function resolveKnobPath(
+  context: MenuContext,
+  path: string,
+): MenuNode | undefined {
+  let nodes: readonly MenuNode[] = rootNodes(context);
+  let found: MenuNode | undefined;
+  for (const segment of path.split("/")) {
+    found = nodes.find((node) => matches(node, segment));
+    if (!found) {
+      // Effects beyond the first few live under "more effects".
+      const more = nodes.find(
+        (node) => node.kind === "menu" && node.id === "more effects",
+      );
+      if (more?.kind === "menu")
+        found = more.build(context).find((node) => matches(node, segment));
+    }
+    if (!found) return undefined;
+    nodes = found.kind === "menu" ? found.build(context) : [];
+  }
+  return found;
+}
+
+/**
+ * The knob label: the row's own label, or `reverb mix` when the row lives in
+ * another effect than the page's (the mixer's reverb send).
+ */
+function knobLabel(page: string, path: string, label: string): string {
+  const segments = path.split("/");
+  if (segments[0] === "effects" && segments.length >= 3) {
+    const effect = segments[1]!;
+    if (page !== `fx:${effect}`) return `${effect} ${label}`;
+  }
+  return label;
+}
+
+/**
+ * The four slots of `page` for `context`: a field per slot whose path
+ * resolves to a number or choice row, else undefined (drawn `·`, skipped).
+ * A page without a row (an effect not in the table) derives one from
+ * `fallback`: its first three number rows, and `mix` on orange.
+ */
+export function knobSlots(
+  context: MenuContext,
+  page: string,
+  fallback: readonly FaderSpec[] = [],
+): (KnobField | undefined)[] {
+  const map: KnobMap | undefined = knobMap(page);
+  if (!map) {
+    const numbers = fallback.filter(
+      (field) => field.kind === "number" && field.label !== "mix",
+    );
+    const mix = fallback.find((field) => field.label === "mix");
+    return [numbers[0], numbers[1], numbers[2], mix].map((field, index) =>
+      field ? { ...field, knob: index as KnobIndex } : undefined,
+    );
+  }
+  return map.map((path, index) => {
+    if (!path || path.startsWith("@") || !path.includes("/")) return undefined;
+    const node = resolveKnobPath(context, path);
+    const spec = node ? faderSpecs([node])[0] : undefined;
+    if (!spec) return undefined;
+    return {
+      ...spec,
+      label: knobLabel(page, path, spec.label),
+      knob: index as KnobIndex,
+    } as KnobField;
+  });
+}
+
+/** The present knobs of `page`, in knob order: the drawer's front page. */
+export function knobFields(
+  context: MenuContext,
+  page: string,
+  fallback: readonly FaderSpec[] = [],
+): KnobField[] {
+  return knobSlots(context, page, fallback).filter(
+    (field): field is KnobField => field !== undefined,
+  );
+}