@hraness/dawg 0.6.1 → 0.7.0

package/tui/clip-row.ts

@@ -0,0 +1,132 @@
+/**
+ * Highway clip-row snapshots (0.7 clips lane): each clip on the focused
+ * track as song beats on the tempo map, its waveform peaks over the clip's
+ * window and whether it continues another clip (a comp seam).
+ *
+ * Peaks (`MEDIA_LIMITS.waveformBuckets` per file) come from a per-file cache filled off the frame path: the first
+ * frame shows flat blocks, and `loadClipPeaks` fills the cache and asks for
+ * a redraw.
+ */
+import { readFile } from "node:fs/promises";
+import { join } from "node:path";
+import { clipEndTick, clipLength, clipSongTick } from "../core/clips.ts";
+import type { TrackScore, Track } from "../core/score.ts";
+import { SCORE_LIMITS } from "../core/score.ts";
+import { waveformPeaks } from "../src/media/dsp.ts";
+import { parseWav } from "../src/media/vendor/wav.ts";
+import type { ClipSnapshot } from "./highway.ts";
+
+type FilePeaks = Readonly<{ seconds: number; peaks: readonly number[] }>;
+
+const cache = new Map<string, FilePeaks | null>();
+const pending = new Set<string>();
+
+/** Cache key: the clip's pin, or its path when not hashed yet. */
+function keyOf(src: string, sha256: string | undefined): string {
+  return sha256 ?? `path:${src}`;
+}
+
+/** Cached peaks for a file, without reading it. */
+export function cachedPeaks(
+  src: string,
+  sha256?: string,
+): FilePeaks | null | undefined {
+  return cache.get(keyOf(src, sha256));
+}
+
+/**
+ * Read and analyse every clip file of `track` not cached yet. Resolves true
+ * when anything new was cached (the caller redraws).
+ */
+export async function loadClipPeaks(
+  root: string,
+  track: Track | undefined,
+): Promise<boolean> {
+  let changed = false;
+  for (const clip of track?.clips ?? []) {
+    const key = keyOf(clip.src, clip.sha256);
+    if (cache.has(key) || pending.has(key) || clip.src.startsWith("pack:"))
+      continue;
+    pending.add(key);
+    try {
+      const wav = parseWav(
+        new Uint8Array(await readFile(join(root, clip.src))),
+        {
+          maximumBytes: SCORE_LIMITS.maxSampleFileBytes,
+          maximumDurationSeconds: SCORE_LIMITS.maxClipSeconds + 1,
+          maximumChannels: 2,
+        },
+      );
+      cache.set(key, {
+        seconds: wav.sampleCount / wav.sampleRate,
+        peaks: waveformPeaks(wav),
+      });
+    } catch {
+      cache.set(key, null);
+    } finally {
+      pending.delete(key);
+    }
+    changed = true;
+  }
+  return changed;
+}
+
+/** The peaks inside a clip's window (`offset .. offset + dur`), reversed for `rev`. */
+function windowPeaks(
+  file: FilePeaks,
+  offset: number,
+  seconds: number,
+  rev: boolean,
+): number[] {
+  const count = file.peaks.length;
+  const from = Math.floor((offset / file.seconds) * count);
+  const to = Math.max(
+    from + 1,
+    Math.ceil(((offset + seconds) / file.seconds) * count),
+  );
+  const slice = file.peaks.slice(Math.max(0, from), Math.min(count, to));
+  return rev ? slice.reverse() : slice;
+}
+
+/** Clip-row snapshots for `trackId`, undefined when it has no clips. */
+export function clipSnapshots(
+  score: TrackScore,
+  trackId: string,
+): ClipSnapshot[] | undefined {
+  const track = score.tracks.find((t) => t.id === trackId);
+  const clips = track?.clips;
+  if (!clips || clips.length === 0) return undefined;
+  const tpb = score.ticksPerBeat;
+  const ends = new Set<number>();
+  const shaped = clips.map((clip) => {
+    const file = cachedPeaks(clip.src, clip.sha256) ?? undefined;
+    const startTick = clipSongTick(clip, track.time);
+    const endTick = clipEndTick(score, clip, file?.seconds);
+    return { clip, file, startTick, endTick };
+  });
+  for (const item of shaped) ends.add(Math.round(item.endTick));
+  return shaped.map(({ clip, file, startTick, endTick }) => ({
+    id: clip.id,
+    startBeat: startTick / tpb,
+    durationBeats: Math.max(0, endTick - startTick) / tpb,
+    ...(file
+      ? {
+          peaks: windowPeaks(
+            file,
+            clip.offset ?? 0,
+            clipLength(clip, file.seconds),
+            clip.rev === true,
+          ),
+        }
+      : {}),
+    ...(clip.take !== undefined ? { take: clip.take } : {}),
+    ...(clip.text !== undefined ? { text: clip.text } : {}),
+    ...(clip.mute || track.muted ? { muted: true } : {}),
+    ...(startTick > 0 && ends.has(Math.round(startTick)) ? { seam: true } : {}),
+  }));
+}
+
+/** Test hook: forget cached peaks. */
+export function clearClipPeaks(): void {
+  cache.clear();
+}

package/tui/delight.ts

@@ -0,0 +1,144 @@
+/**
+ * Small, quiet moments that answer the music: the header ▶ glints on each
+ * downbeat, the first wrap of a new song sweeps once across the hit line,
+ * and a play key that is not recording glows its lane. Every one is a pure
+ * function of the transport clock and a timestamp, so tests pin the clock;
+ * `/motion off` turns them all off. None of them touches the score.
+ */
+
+/** How long the header ▶ stays bright after a bar downbeat. */
+export const GLINT_MS = 120;
+/** How long the first-loop sweep takes to cross the hit line. */
+export const SWEEP_MS = 900;
+/** How long a play key's lane glows. */
+export const GHOST_MS = 150;
+/** The card the first wrap shows, once per song. */
+export const FIRST_LOOP_CARD = "↻ first loop";
+
+export type GlintInput = Readonly<{
+  playing: boolean;
+  /** Transport beat, unwrapped. */
+  beat: number;
+  bpm: number;
+  beatsPerBar: number;
+  /** Bar starts within the loop (meter changes); bars repeat when absent. */
+  barBeats?: readonly number[] | undefined;
+  loopBeats?: number | undefined;
+  reducedMotion: boolean;
+}>;
+
+/** Whether the header ▶ glints now: within `GLINT_MS` after a downbeat. */
+export function downbeatGlint(input: GlintInput): boolean {
+  if (!input.playing || input.reducedMotion) return false;
+  if (!Number.isFinite(input.beat) || input.beat < 0) return false;
+  const bpm = Math.max(1, input.bpm);
+  const loop =
+    input.loopBeats && input.loopBeats > 0 ? input.loopBeats : undefined;
+  const inLoop = loop ? input.beat % loop : input.beat;
+  let since: number;
+  if (input.barBeats && input.barBeats.length > 0) {
+    let start = 0;
+    for (const bar of input.barBeats) if (bar <= inLoop + 1e-9) start = bar;
+    since = inLoop - start;
+  } else {
+    const bar = Math.max(1, input.beatsPerBar);
+    since = inLoop % bar;
+  }
+  return (since * 60_000) / bpm < GLINT_MS;
+}
+
+/**
+ * The first-loop sweep's head, 0..1 across the hit line, or undefined when
+ * it is not running. It plays once, `SWEEP_MS` long, from `startedAtMs`.
+ */
+export function sweepProgress(
+  startedAtMs: number | undefined,
+  nowMs: number,
+  reducedMotion: boolean,
+): number | undefined {
+  if (startedAtMs === undefined || reducedMotion) return undefined;
+  const age = nowMs - startedAtMs;
+  if (age < 0 || age >= SWEEP_MS) return undefined;
+  return age / SWEEP_MS;
+}
+
+/** A glowing lane: its pitch and strength (1 at the press, fading to 0). */
+export type LaneGlow = Readonly<{ pitch: number; strength: number }>;
+
+/**
+ * Session-only delight state. The first loop is remembered per song in the
+ * session's metadata (`heardLoop`), handed in by the host, never the score.
+ */
+export class Delight {
+  /** The song has wrapped before (this window or an earlier session). */
+  heardLoop: boolean;
+  /** When this window's first-loop sweep started. */
+  sweepStartedAtMs: number | undefined;
+  private readonly ghosts = new Map<number, number>();
+  private songId: string | undefined;
+
+  constructor(options: { heardLoop?: boolean } = {}) {
+    this.heardLoop = options.heardLoop ?? false;
+  }
+
+  /**
+   * Watch the transport. Returns true once, on the first wrap of a song
+   * that has not wrapped before; the caller shows the card and records it.
+   */
+  observe(
+    input: Readonly<{
+      playing: boolean;
+      beat: number;
+      loopBeats?: number | undefined;
+      empty: boolean;
+    }>,
+    nowMs: number,
+  ): boolean {
+    if (this.heardLoop || !input.playing || input.empty) return false;
+    const loop = input.loopBeats;
+    if (!loop || loop <= 0 || !(input.beat >= loop)) return false;
+    this.heardLoop = true;
+    this.sweepStartedAtMs = nowMs;
+    return true;
+  }
+
+  /**
+   * Follow the open song: a different session starts fresh from its own
+   * metadata; the same one only ever learns that it has wrapped.
+   */
+  song(id: string, heardLoop: boolean): void {
+    if (id !== this.songId) {
+      this.songId = id;
+      this.heardLoop = heardLoop;
+      this.sweepStartedAtMs = undefined;
+    } else if (heardLoop) this.heardLoop = true;
+  }
+
+  /** A play key sounded without recording. */
+  ghost(pitch: number, nowMs: number): void {
+    this.ghosts.set(pitch, nowMs);
+  }
+
+  /** Lanes glowing now, strongest first; expired ones are dropped. */
+  glows(nowMs: number, reducedMotion: boolean): LaneGlow[] {
+    const glows: LaneGlow[] = [];
+    for (const [pitch, atMs] of this.ghosts) {
+      const age = nowMs - atMs;
+      if (age >= GHOST_MS || age < 0) {
+        if (age >= GHOST_MS) this.ghosts.delete(pitch);
+        continue;
+      }
+      if (!reducedMotion) glows.push({ pitch, strength: 1 - age / GHOST_MS });
+    }
+    return glows.sort((a, b) => b.strength - a.strength);
+  }
+
+  /** Whether anything is animating (the host keeps frames coming). */
+  animating(nowMs: number): boolean {
+    return (
+      this.ghosts.size > 0 ||
+      (this.sweepStartedAtMs !== undefined &&
+        nowMs - this.sweepStartedAtMs < SWEEP_MS)
+    );
+  }
+}

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        │
@@ -39,6 +39,8 @@ export type DrawerField =
       committedPosition?: number | undefined;
       minText: string;
       maxText: string;
+      /** Just caught by a detent: the bar brightens for one frame. */
+      flash?: string | undefined;
     }>
   | Readonly<{
       kind: "choice";
@@ -56,6 +58,8 @@ 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;
@@ -175,8 +179,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,
@@ -189,6 +198,9 @@ export function paintDrawer(
   if (region.height <= 0 || width < 16 || view.fields.length === 0)
     return undefined;
   const layout = drawerLayout(view, region);
+  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 +224,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(
@@ -306,13 +339,18 @@ 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,
           ...(hits ? { hits } : {}),
@@ -335,7 +373,7 @@ export function paintDrawer(
           inner.right,
           field,
           index,
-          { glyphs, focused, roles, on, ...(hits ? { hits } : {}) },
+          { glyphs, focused, flashing, roles, on, ...(hits ? { hits } : {}) },
         );
       }
     } else {
@@ -364,6 +402,8 @@ export function paintDrawer(
 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;
@@ -412,7 +452,15 @@ 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.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;
+  }
+}