@hraness/dawg 0.6.1 → 0.8.0

package/tui/drawer.ts

@@ -5,7 +5,7 @@
  * habit). The piano roll stays visible above it while the terminal is tall
  * enough.
  *
- *   ╭ fader · filter ────────────────────── ● staged  [keep] [revert] ╮
+ *   ╭ Effects › filter ─── A/B: 1 change staged · enter keep · esc revert ╮
  *   │ › cutoff           1200 Hz ← 800 Hz               20 … 20000 Hz │
  *   │   [−] ━━━━━━━━━━━━━━━━━━●──────────────────────────────────  [+] │
  *   │   type             lowpass │ highpass │ bandpass │ notch        │
@@ -24,6 +24,7 @@ import type { HitMap } from "./hits.ts";
 import { onBackground, type Style, type Theme } from "./theme.ts";
 import { displayWidth, truncate } from "./text.ts";
 import { asciiHint, fitHint } from "./grammar.ts";
+import { knobGlyph, knobStyle, type KnobIndex } from "./knobs.ts";
 
 export type DrawerField =
   | Readonly<{
@@ -39,6 +40,12 @@ export type DrawerField =
       committedPosition?: number | undefined;
       minText: string;
       maxText: string;
+      /** Just caught by a detent: the bar brightens for one frame. */
+      flash?: string | undefined;
+      /** Other panes with this parameter open (`B C`), dim at the right. */
+      peers?: string | undefined;
+      /** The knob this row is (front page): its glyph and colour. */
+      knob?: KnobIndex | undefined;
     }>
   | Readonly<{
       kind: "choice";
@@ -46,6 +53,8 @@ export type DrawerField =
       options: readonly string[];
       index: number;
       committedIndex?: number | undefined;
+      peers?: string | undefined;
+      knob?: KnobIndex | undefined;
     }>;
 
 export type DrawerView = Readonly<{
@@ -56,11 +65,40 @@ export type DrawerView = Readonly<{
   typing?: string | undefined;
   /** Edits differ from the committed score. */
   dirty: boolean;
+  /** `A/B: 1 change staged · enter keep · esc revert` while dirty. */
+  badge?: string | undefined;
   /** `♪ solo · B` while the audition loop plays. */
   status?: string | undefined;
   hint: string;
+  /**
+   * Every param on the page behind Tab, while the drawer shows the four
+   * knobs: a wide drawer lists them beside the knobs (`DRAWER_MEASURE`).
+   */
+  aside?: readonly DrawerAside[] | undefined;
 }>;
 
+/** One row of the drawer's side list: a param and its value. */
+export type DrawerAside = Readonly<{
+  label: string;
+  text: string;
+  knob?: KnobIndex | undefined;
+}>;
+
+/**
+ * The widest a drawer row (label, value, bar, range) runs: a fader bar past
+ * this is no easier to read or aim. Room right of it lists the page's other
+ * params when the view has an aside, else stays panel.
+ */
+export const DRAWER_MEASURE = 96;
+/** The fewest columns the side list needs beside the rows. */
+export const ASIDE_MIN_WIDTH = 28;
+
+/** Columns the side list gets in a drawer `width` wide (0: none). */
+export function asideWidth(width: number): number {
+  const room = width - 4 - DRAWER_MEASURE - 3;
+  return room >= ASIDE_MIN_WIDTH ? Math.min(room, 48) : 0;
+}
+
 export type DrawerMode = "full" | "compact" | "line";
 
 export interface DrawerLayout {
@@ -85,12 +123,20 @@ export function keepAbove(regionHeight: number): number {
  * its bottom, as tall as its fields need within the budget.
  */
 export function drawerLayout(
-  view: Pick<DrawerView, "fields" | "focus">,
+  view: Pick<DrawerView, "fields" | "focus"> &
+    Partial<Pick<DrawerView, "aside">>,
   region: { y: number; height: number },
+  width = 0,
 ): DrawerLayout {
   const total = Math.max(1, view.fields.length);
   const bottom = region.y + region.height;
   const budget = region.height - keepAbove(region.height);
+  // A side list beside the knobs may make a full drawer taller, never
+  // past half the region.
+  const aside =
+    view.aside && asideWidth(width) > 0
+      ? Math.min(view.aside.length + 1, Math.floor(region.height / 2) - 2)
+      : 0;
   const window = (rows: number): { first: number; count: number } => {
     const count = Math.max(1, Math.min(total, rows));
     const focus = Math.min(Math.max(0, view.focus), total - 1);
@@ -98,7 +144,7 @@ export function drawerLayout(
     return { first, count };
   };
   if (2 + 2 * total <= Math.floor(region.height / 2)) {
-    const height = 2 + 2 * total;
+    const height = 2 + Math.max(2 * total, aside);
     return {
       mode: "full",
       top: bottom - height,
@@ -175,8 +221,13 @@ const ASCII: Glyphs = {
 export interface DrawerPaint {
   theme: Theme;
   unicode: boolean;
+  /** /motion off: detents still snap, the flash is not drawn. */
+  reducedMotion?: boolean;
 }
 
+/** Views whose detent flash has been drawn: a flash lasts one frame. */
+const flashed = new WeakSet<DrawerView>();
+
 /** Paint the drawer into the highway region; returns its layout. */
 export function paintDrawer(
   buffer: CellBuffer,
@@ -188,7 +239,10 @@ export function paintDrawer(
 ): DrawerLayout | undefined {
   if (region.height <= 0 || width < 16 || view.fields.length === 0)
     return undefined;
-  const layout = drawerLayout(view, region);
+  const layout = drawerLayout(view, region, width);
+  const flashing = !options.reducedMotion && !flashed.has(view);
+  if (view.fields.some((field) => field.kind === "number" && field.flash))
+    flashed.add(view);
   const roles = options.theme.roles;
   const glyphs = options.unicode ? UNICODE : ASCII;
   const panel = roles.panel;
@@ -212,37 +266,58 @@ export function paintDrawer(
       buffer.set(width - 1, y, box.v, border);
     }
     inner = { left: 2, right: width - 2 };
-    // Title left; staged state and the keep / revert buttons right.
-    const keep = "[keep]";
-    const revert = "[revert]";
-    const buttons = view.dirty ? `${keep} ${revert}` : "";
-    const state = view.dirty ? `${options.unicode ? "●" : "*"} staged` : "";
-    const status = [view.status, state].filter(Boolean).join(" · ");
-    const right = [status, buttons].filter(Boolean).join("  ");
+    // Title left; the status and the staged badge right. The badge's
+    // `enter keep` and `esc revert` are click targets; when room is short
+    // the breadcrumb truncates first, then the badge drops its key words.
+    const room = width - 6;
+    const full = view.badge ?? (view.dirty ? "A/B: changes staged" : "");
+    // The badge already counts staged changes; the audition status's
+    // `B staged N` would say it twice.
+    const status = (view.status ?? "")
+      .split(" · ")
+      .filter((part) => !(full && /^B staged \d+$/.test(part)))
+      .join(" · ");
+    const short = full.replace(/ · enter keep · esc revert$/, "");
+    const join = (badge: string) => [status, badge].filter(Boolean).join(" · ");
+    const minTitle = Math.min(displayWidth(view.title), 12) + 2;
+    let right = join(full);
+    if (displayWidth(right) + 3 + minTitle > room) right = join(short);
+    if (displayWidth(right) + 3 + minTitle > room) right = short;
+    if (displayWidth(right) + 3 + minTitle > room) right = "";
     const rightWidth = displayWidth(right);
-    const titleRoom = Math.max(0, width - 6 - (right ? rightWidth + 3 : 0));
+    const titleRoom = Math.max(0, room - (right ? rightWidth + 3 : 0));
     buffer.text(
       2,
       top,
       ` ${truncate(view.title, Math.max(0, titleRoom - 2))} `,
       on({ ...roles.text, bold: true }),
     );
-    if (right && rightWidth + 4 < width - displayWidth(view.title)) {
+    if (right) {
       const rx = width - 3 - rightWidth;
       buffer.text(
         rx - 1,
         top,
-        ` ${status}${status && buttons ? "  " : ""}`,
+        ` ${right}`,
         on(view.dirty ? roles.warning : roles.muted),
       );
-      if (buttons) {
-        const kx = width - 3 - displayWidth(buttons);
-        buffer.text(kx, top, `${keep} `, on({ ...roles.success, bold: true }));
-        buffer.text(kx + keep.length + 1, top, revert, on(roles.muted));
-        hits?.add(kx, top, keep.length, 1, { kind: "fader-keep" });
-        hits?.add(kx + keep.length + 1, top, revert.length, 1, {
-          kind: "fader-revert",
-        });
+      for (const [word, kind] of [
+        ["enter keep", "fader-keep"],
+        ["esc revert", "fader-revert"],
+      ] as const) {
+        const at = right.lastIndexOf(word);
+        if (at < 0) continue;
+        const x = rx + displayWidth(right.slice(0, at));
+        buffer.text(
+          x,
+          top,
+          word,
+          on(
+            kind === "fader-keep"
+              ? { ...roles.success, bold: true }
+              : roles.muted,
+          ),
+        );
+        hits?.add(x, top, word.length, 1, { kind });
       }
     }
     const hint = fitHint(
@@ -257,6 +332,19 @@ export function paintDrawer(
         on(roles.muted),
       );
   }
+  const outer = inner;
+  inner = {
+    left: inner.left,
+    right: Math.min(inner.right, inner.left + DRAWER_MEASURE),
+  };
+  if (layout.bordered && view.aside)
+    paintAside(buffer, layout, outer.right, view.aside, {
+      glyphs,
+      roles,
+      on,
+      theme: options.theme,
+      unicode: options.unicode,
+    });
   const labelWidth = Math.min(
     layout.mode === "full" ? 22 : 16,
     Math.max(...view.fields.map((field) => displayWidth(field.label))),
@@ -275,12 +363,25 @@ export function paintDrawer(
     const labelStyle = focused
       ? on({ ...roles.borderFocus, bold: true })
       : on(roles.text);
-    buffer.text(inner.left, y, marker, labelStyle);
+    if (field.knob !== undefined) {
+      // A knob row: its shape glyph in its colour, then the marker, so
+      // colour is never the only cue (NO_COLOR keeps the shape).
+      buffer.text(
+        inner.left,
+        y,
+        knobGlyph(field.knob, options.unicode),
+        on(knobStyle(field.knob, options.theme)),
+      );
+      buffer.text(inner.left + 1, y, focused ? glyphs.marker : " ", labelStyle);
+    } else buffer.text(inner.left, y, marker, labelStyle);
     buffer.text(
       inner.left + 2,
       y,
       truncate(field.label, labelWidth),
-      labelStyle,
+      // The selected knob's label is reverse video (§7.2).
+      field.knob !== undefined && focused
+        ? on({ ...roles.text, bold: true, reverse: true })
+        : labelStyle,
     );
     const valueX = inner.left + 2 + labelWidth + 2;
     const typing = focused && view.typing !== undefined;
@@ -306,15 +407,21 @@ export function paintDrawer(
             on(roles.muted),
             inner.right - valueX - used,
           );
-        const range = `${field.minText} … ${field.maxText}`;
+        // For the frame a detent catches, the range gives way to its name.
+        const range =
+          flashing && field.flash !== undefined
+            ? field.flash
+            : `${field.minText} … ${field.maxText}`;
         const rangeX = inner.right - displayWidth(range);
         if (rangeX > valueX + used + displayWidth(committed) + 2)
           buffer.text(rangeX, y, range, on(roles.faint));
         paintBar(buffer, y + 1, inner.left + 2, inner.right, field, index, {
           glyphs,
           focused,
+          flashing,
           roles,
           on,
+          knob: knobFill(field, options.theme),
           ...(hits ? { hits } : {}),
         });
       } else {
@@ -335,7 +442,15 @@ export function paintDrawer(
           inner.right,
           field,
           index,
-          { glyphs, focused, roles, on, ...(hits ? { hits } : {}) },
+          {
+            glyphs,
+            focused,
+            flashing,
+            roles,
+            on,
+            knob: knobFill(field, options.theme),
+            ...(hits ? { hits } : {}),
+          },
         );
       }
     } else {
@@ -357,16 +472,97 @@ export function paintDrawer(
           );
       }
     }
+    // Other panes with this parameter open: their letters, dim, at the
+    // row's right edge (design §12.7).
+    if (field.peers) {
+      const peers = ` ${field.peers}`;
+      buffer.text(
+        Math.max(valueX, inner.right - displayWidth(peers)),
+        y,
+        peers,
+        on(roles.muted),
+      );
+    }
   }
   return layout;
 }
 
+/**
+ * `all params · tab` and every param on the page, one per row, beside the
+ * knobs: what Tab would show, without leaving the knobs.
+ */
+function paintAside(
+  buffer: CellBuffer,
+  layout: DrawerLayout,
+  right: number,
+  aside: readonly DrawerAside[],
+  paint: {
+    glyphs: Glyphs;
+    roles: Theme["roles"];
+    on: (style: Style) => Style;
+    theme: Theme;
+    unicode: boolean;
+  },
+): void {
+  const width = asideWidth(right + 2);
+  if (width === 0) return;
+  const { roles, on } = paint;
+  const left = right - width;
+  const rows = layout.height - 2;
+  if (rows < 2) return;
+  const top = layout.top + 1;
+  const rule = paint.unicode ? "│" : "|";
+  for (let y = top; y < top + rows; y += 1)
+    buffer.set(left - 2, y, rule, on(roles.faint));
+  buffer.text(left, top, truncate("all params · tab", width), on(roles.muted));
+  const room = rows - 1;
+  const shown =
+    aside.length > room ? aside.slice(0, Math.max(0, room - 1)) : aside;
+  const labelWidth = Math.min(
+    Math.floor(width / 2),
+    Math.max(0, ...shown.map((row) => displayWidth(row.label))),
+  );
+  shown.forEach((row, index) => {
+    const y = top + 1 + index;
+    if (row.knob !== undefined)
+      buffer.text(
+        left,
+        y,
+        knobGlyph(row.knob, paint.unicode),
+        on(knobStyle(row.knob, paint.theme)),
+      );
+    buffer.text(left + 2, y, truncate(row.label, labelWidth), on(roles.text));
+    const valueX = left + 2 + labelWidth + 1;
+    buffer.text(
+      valueX,
+      y,
+      truncate(row.text, Math.max(0, right - valueX)),
+      on(roles.muted),
+    );
+  });
+  if (shown.length < aside.length)
+    buffer.text(
+      left + 2,
+      top + room,
+      truncate(`+${aside.length - shown.length} more · tab`, width - 2),
+      on(roles.faint),
+    );
+}
+
+function knobFill(field: DrawerField, theme: Theme): Style | undefined {
+  return field.knob === undefined ? undefined : knobStyle(field.knob, theme);
+}
+
 interface RowPaint {
   glyphs: Glyphs;
   focused: boolean;
+  /** Draw this field's detent flash (motion on, first frame only). */
+  flashing?: boolean;
   roles: Theme["roles"];
   on: (style: Style) => Style;
   hits?: HitMap;
+  /** A knob row's bar fills in its knob colour. */
+  knob?: Style | undefined;
 }
 
 /** `[−] ━━━━━●─────── [+]` from `left` to `right`, with its hit regions. */
@@ -412,7 +608,17 @@ function paintBar(
     field.committedPosition === undefined
       ? undefined
       : at(field.committedPosition);
-  const filled = on(paint.focused ? roles.borderFocus : roles.text);
+  // A detent catch brightens the bar for one frame (motion on).
+  const flash = paint.flashing === true && field.flash !== undefined;
+  const filled = on(
+    flash
+      ? { ...roles.success, bold: true }
+      : paint.knob
+        ? paint.knob
+        : paint.focused
+          ? roles.borderFocus
+          : roles.text,
+  );
   const empty = on(roles.faint);
   for (let column = 0; column < barWidth; column += 1) {
     const x = barLeft + column;

package/tui/frame-gate.ts

@@ -0,0 +1,76 @@
+/**
+ * When the interactive loop builds a frame.  The 30 fps timer used to build
+ * the whole view (score snapshot, layout, every panel) on every tick even
+ * with nothing moving, only for the differential writer to find no change.
+ * The gate builds a frame when something can have changed: a forced frame
+ * (input, resize, an edit landing), a change the caller reports (activity,
+ * a different score or status key), or a running animation (transport,
+ * play mode, an audition, a spinner, a card's glow).  Otherwise it builds
+ * one heartbeat frame every `heartbeatMs`, which catches anything slow that
+ * nothing reported (a loudness reading, a card ageing out).
+ */
+export const IDLE_HEARTBEAT_MS = 500;
+/**
+ * The shortest gap between two built frames in the interactive loop: a
+ * burst of forced frames (keystrokes, edits landing, agent events) is
+ * coalesced to at most about 30 a second. A deferred frame stays dirty, so
+ * the next 33 ms timer tick builds it; nothing is dropped.
+ */
+export const MIN_FRAME_GAP_MS = 33;
+
+export class FrameGate {
+  private dirty = true;
+  private lastBuiltMs = Number.NEGATIVE_INFINITY;
+  private lastKeys: readonly unknown[] = [];
+  /** Frames built and ticks skipped, for tests and diagnostics. */
+  built = 0;
+  skipped = 0;
+
+  constructor(
+    readonly heartbeatMs = IDLE_HEARTBEAT_MS,
+    readonly minGapMs = 0,
+  ) {}
+
+  /** Something visible changed; the next tick builds. */
+  markDirty(): void {
+    this.dirty = true;
+  }
+
+  /**
+   * True when this tick should build a frame; counts it as built.  Each of
+   * `keys` is compared by identity (a score object) or value (a status
+   * string) with the last built frame's: any difference builds.
+   */
+  shouldBuild(options: {
+    nowMs: number;
+    force?: boolean;
+    animating?: boolean;
+    keys?: readonly unknown[];
+  }): boolean {
+    const keys = options.keys ?? [];
+    const keyChanged =
+      keys.length !== this.lastKeys.length ||
+      keys.some((key, index) => !Object.is(key, this.lastKeys[index]));
+    const build =
+      options.force === true ||
+      options.animating === true ||
+      this.dirty ||
+      keyChanged ||
+      options.nowMs - this.lastBuiltMs >= this.heartbeatMs;
+    if (!build) {
+      this.skipped += 1;
+      return false;
+    }
+    if (options.nowMs - this.lastBuiltMs < this.minGapMs) {
+      // Too soon after the last frame: build on the next tick instead.
+      this.dirty = true;
+      this.skipped += 1;
+      return false;
+    }
+    this.dirty = false;
+    this.lastKeys = keys;
+    this.lastBuiltMs = options.nowMs;
+    this.built += 1;
+    return true;
+  }
+}