@hraness/dawg 0.6.1 → 0.8.0

package/tui/highway.ts

@@ -10,6 +10,7 @@
  * lane per voice with a legend.
  */
 
+import { emptyHint } from "./hints.ts";
 import { CellBuffer } from "./screen.ts";
 import { truncate } from "./text.ts";
 import {
@@ -44,6 +45,24 @@ export interface NoteSnapshot {
    * from (`D` for a `D−47` tag), since the lane is the key, not the sound.
    */
   centsFrom?: string | undefined;
+  /** Sung syllable (`Note.lyric`), drawn beside the head like the cents tag. */
+  lyric?: string | undefined;
+}
+
+/** An audio clip on the focused track (0.7), drawn in the clip row. */
+export interface ClipSnapshot {
+  id: string;
+  /** Song beats where the clip sounds. */
+  startBeat: number;
+  durationBeats: number;
+  /** Normalised RMS over the clip's window (0..1), oldest first. */
+  peaks?: readonly number[] | undefined;
+  /** Take name and clip text, shown after the id. */
+  take?: string | undefined;
+  text?: string | undefined;
+  muted?: boolean | undefined;
+  /** The clip starts where another ends: a comp seam. */
+  seam?: boolean | undefined;
 }
 
 export interface TrackScoreSnapshot {
@@ -61,6 +80,8 @@ export interface TrackScoreSnapshot {
    */
   barBeats?: readonly number[] | undefined;
   loopBeats?: number | undefined;
+  /** The score's loop range (0-based start bar), for the header's `↻ 5–6`. */
+  loopRange?: Readonly<{ startBar: number; bars: number }> | undefined;
   laneCount?: number | undefined;
   /** Optional lane legend (drum voices) drawn just below the hit line. */
   laneLabels?: readonly string[] | undefined;
@@ -83,6 +104,49 @@ export interface TrackScoreSnapshot {
    * accent. Empty or omitted in focus view.
    */
   layers?: readonly HighwayLayer[] | undefined;
+  /** The focused track sings (instrument `vocal`): the empty hint says how. */
+  vocal?: boolean | undefined;
+  /** Audio clips on the focused track (0.7): the right-edge clip row. */
+  clips?: readonly ClipSnapshot[] | undefined;
+  /**
+   * Detected pitch of the focused track's audio (0.7 `/vocal pitch trace`),
+   * sorted by beat. Drawn as a dotted line under the notes, in the warning
+   * role where it sits more than 15 cents off the nearest semitone; hidden
+   * while one row spans more than a beat.
+   */
+  pitchTrace?: readonly PitchTracePoint[] | undefined;
+}
+
+/** One point of a pitch trace: score beats and fractional MIDI pitch. */
+export interface PitchTracePoint {
+  beat: number;
+  pitch: number;
+}
+
+/** Cents a trace point sits away from its nearest semitone before it warns. */
+export const TRACE_WARN_CENTS = 15;
+
+/** The trace point nearest `beat` within `half` beats, by binary search. */
+export function tracePointAt(
+  trace: readonly PitchTracePoint[],
+  beat: number,
+  half: number,
+): PitchTracePoint | undefined {
+  let lo = 0;
+  let hi = trace.length;
+  while (lo < hi) {
+    const mid = (lo + hi) >> 1;
+    if (trace[mid]!.beat < beat) lo = mid + 1;
+    else hi = mid;
+  }
+  let best: PitchTracePoint | undefined;
+  for (const i of [lo - 1, lo]) {
+    const point = trace[i];
+    if (!point || Math.abs(point.beat - beat) > half) continue;
+    if (!best || Math.abs(point.beat - beat) < Math.abs(best.beat - beat))
+      best = point;
+  }
+  return best;
 }
 
 /** One background track overlaid on the highway. */
@@ -216,7 +280,10 @@ export function pitchProjection(
 }
 
 /** Choose the projection a snapshot implies. */
-export function projectionFor(score: TrackScoreSnapshot): LaneProjection {
+export function projectionFor(
+  score: TrackScoreSnapshot,
+  minimumSpan = 12,
+): LaneProjection {
   if (score.projection) return score.projection;
   const explicit =
     score.laneLabels !== undefined ||
@@ -233,7 +300,7 @@ export function projectionFor(score: TrackScoreSnapshot): LaneProjection {
     .flatMap((layer) => layer.notes);
   return pitchProjection(
     melodic.length ? [...score.notes, ...melodic] : score.notes,
-    12,
+    minimumSpan,
     score.tuningPeriod,
   );
 }
@@ -413,6 +480,12 @@ export interface HighwayOptions {
   lookaheadBeats?: number;
   /** Background style painted under the highway. */
   background?: Style;
+  /** Seed and agent presence for the empty-state hint (tui/hints.ts). */
+  hint?: Readonly<{ seed: string; agent: boolean }> | undefined;
+  /** The first-loop sweep's head, 0..1 across the hit line (tui/delight.ts). */
+  sweep?: number | undefined;
+  /** Play keys sounding without recording: their lanes glow on the hit line. */
+  glows?: readonly Readonly<{ pitch: number; strength: number }>[] | undefined;
 }
 
 export interface HighwayLayout {
@@ -426,6 +499,28 @@ export interface HighwayLayout {
   legendRow: number | undefined;
 }
 
+/**
+ * The widest a lane gets. A wider terminal shows more pitches (up to
+ * `MAX_PITCH_SPAN`) instead of fatter tiles, and past that the lanes stay
+ * this wide, centred.
+ */
+export const MAX_LANE_WIDTH = 10;
+/** The most semitones a melodic highway spreads across on a wide terminal. */
+export const MAX_PITCH_SPAN = 36;
+/**
+ * The tallest a beat gets. A taller terminal looks further ahead (more bars
+ * coming) instead of stretching each note.
+ */
+export const MAX_ROWS_PER_BEAT = 4;
+
+/** The pitch span a highway `width` columns wide fits: one to three octaves. */
+export function pitchSpanFor(width: number): number {
+  return Math.max(
+    12,
+    Math.min(MAX_PITCH_SPAN, Math.floor((width - 3) / MAX_LANE_WIDTH)),
+  );
+}
+
 export function highwayLayout(
   region: HighwayRegion,
   projection: LaneProjection,
@@ -437,13 +532,21 @@ export function highwayLayout(
   const gutter = region.width >= 40 ? 3 : 0;
   const area = Math.max(1, region.width - gutter);
   const laneCount = projection.laneCount;
-  const laneWidth = laneCount <= area ? Math.floor(area / laneCount) : 0;
+  const laneWidth =
+    laneCount <= area
+      ? Math.min(MAX_LANE_WIDTH, Math.floor(area / laneCount))
+      : 0;
   const used = laneWidth > 0 ? laneWidth * laneCount : area;
   const laneLeft = gutter + Math.floor((area - used) / 2);
   const tileWidth =
     laneWidth >= 4 ? laneWidth - 1 : Math.max(1, laneWidth || 1);
   const lookahead =
-    lookaheadBeats ?? Math.max(2, Math.min(8, Math.round(hitRow / 2.5)));
+    lookaheadBeats ??
+    Math.max(
+      2,
+      Math.min(8, Math.round(hitRow / 2.5)),
+      Math.floor(hitRow / MAX_ROWS_PER_BEAT),
+    );
   return {
     hitRow,
     gutter,
@@ -473,6 +576,7 @@ interface Painter {
   put(x: number, y: number, ch: string, style: Style): void;
   restyle(x: number, y: number, style: Style): void;
   isBlank(x: number, y: number): boolean;
+  charAt(x: number, y: number): string | undefined;
 }
 
 /**
@@ -492,7 +596,7 @@ export function paintHighway(
   const glyphs = glyphsFor(capabilities);
   const background = options.background ?? roles.canvas;
   const bg = (style: Style): Style => onBackground(style, background);
-  const projection = projectionFor(score);
+  const projection = projectionFor(score, pitchSpanFor(region.width));
   const layout = highwayLayout(region, projection, options.lookaheadBeats);
   const { hitRow, rowsPerBeat, gutter } = layout;
   const areaWidth = Math.max(1, region.width - gutter);
@@ -516,6 +620,9 @@ export function paintHighway(
     isBlank(x, y) {
       return buffer.get(region.x + x, region.y + y)?.ch === " ";
     },
+    charAt(x, y) {
+      return buffer.get(region.x + x, region.y + y)?.ch;
+    },
   };
 
   const rowBeat = (row: number): number => beat + (hitRow - row) / rowsPerBeat;
@@ -525,13 +632,17 @@ export function paintHighway(
   // centred hint says how to start. The hit line and grid still draw.
   const empty =
     score.notes.length === 0 &&
+    (score.clips ?? []).length === 0 &&
     !(score.layers ?? []).some((layer) => layer.notes.length > 0);
 
   // Beat, bar, and loop rules of increasing strength.
   const barBeats =
     score.barBeats && score.barBeats.length > 0 ? score.barBeats : undefined;
+  // An empty highway reserves one row for its hint: no rule scrolls
+  // through it, so the words never sit on the ruler, playing or paused.
+  const hintRow = empty ? Math.max(0, Math.floor(hitRow / 2)) : undefined;
   for (let row = 0; row <= lastNoteRow; row += 1) {
-    if (row === hitRow) continue;
+    if (row === hitRow || row === hintRow) continue;
     const center = rowBeat(row);
     const half = 0.5 / rowsPerBeat;
     let k = Math.ceil(center - half - 1e-9);
@@ -613,37 +724,40 @@ export function paintHighway(
     );
   }
 
-  // Loop-wrap sweep: a bright band crosses the hit line during the first beat
-  // after the transport wraps.
-  if (loop && !reduced && score.playing && beat >= loop * 0.5) {
-    const loopPhase = ((beat % loop) + loop) % loop;
-    if (loopPhase < 1) {
-      const head = Math.round(gutter + loopPhase * areaWidth);
-      for (let offset = 0; offset < 6; offset += 1) {
-        const column = head - offset;
-        if (column < gutter || column >= region.width) continue;
-        painter.put(
-          column,
-          hitRow,
-          glyphs.loopRule,
-          shade(roles.loopRule, 0.5 - offset * 0.1),
-        );
-      }
+  // First-loop sweep: once per song, a faint band crosses the hit line
+  // when the loop first wraps (tui/delight.ts decides when).
+  if (options.sweep !== undefined && !reduced) {
+    const head = Math.round(gutter + options.sweep * areaWidth);
+    for (let offset = 0; offset < 6; offset += 1) {
+      const column = head - offset;
+      if (column < gutter || column >= region.width) continue;
+      painter.put(
+        column,
+        hitRow,
+        glyphs.loopRule,
+        shade(roles.loopRule, 0.5 - offset * 0.1),
+      );
     }
   }
 
   if (empty) {
     const name = score.trackName ?? score.trackId ?? "track";
-    const start = projection.kind === "pitch" ? "add C4 at 0" : "hit kick at 0";
-    // First run: name the three ways in (ask, play, menu); narrow
-    // windows fall back to one prompt command.
-    const full = `${name} · empty · type a request · ctrl-p play · ctrl-k menu`;
-    const text = truncate(
-      full.length <= areaWidth ? full : `${name} · empty · ${start} to start`,
+    // One seeded line names a way in that works in this session: a
+    // request with an agent, a command without one (tui/hints.ts).
+    const text = emptyHint(
+      {
+        seed: options.hint?.seed ?? score.sessionId ?? "dawg",
+        agent: options.hint?.agent ?? true,
+        filled: false,
+        drums: projection.kind !== "pitch",
+        vocal: score.vocal === true,
+        playing: score.playing === true,
+      },
+      name,
       areaWidth,
     );
     const x = gutter + Math.max(0, Math.floor((areaWidth - text.length) / 2));
-    const y = Math.max(0, Math.floor(hitRow / 2));
+    const y = hintRow ?? 0;
     for (let index = 0; index < text.length; index += 1)
       painter.put(x + index, y, text[index]!, roles.muted);
   }
@@ -668,6 +782,34 @@ export function paintHighway(
     }
   }
 
+  // 0.7 pitch trace: one dot per row under the notes, at the fractional
+  // lane of the detected pitch. Rows wider than a beat hide it.
+  const trace = score.pitchTrace;
+  if (trace && trace.length > 0 && rowsPerBeat >= 1) {
+    const half = 0.5 / rowsPerBeat;
+    const width = Math.max(1, layout.laneWidth || 1);
+    for (let row = 0; row <= lastNoteRow; row += 1) {
+      if (row === hitRow) continue;
+      let at = rowBeat(row);
+      if (loop) at = ((at % loop) + loop) % loop;
+      const point = tracePointAt(trace, at, half);
+      if (!point) continue;
+      const near = Math.round(point.pitch);
+      const lane = projection.laneOf({ startBeat: point.beat, pitch: near });
+      if (lane === undefined) continue;
+      const off = point.pitch - near;
+      const x =
+        laneX(layout, lane, areaWidth) +
+        Math.max(0, Math.min(width - 1, Math.floor((off + 0.5) * width)));
+      painter.put(
+        x,
+        row,
+        glyphs.muted,
+        Math.abs(off) * 100 > TRACE_WARN_CENTS ? roles.warning : roles.muted,
+      );
+    }
+  }
+
   // Note occurrences across loop repeats, ordered so active notes draw last.
   const belowBeats = (lastNoteRow - hitRow + 1) / rowsPerBeat;
   const aheadBeats = hitRow / rowsPerBeat + 1 / rowsPerBeat;
@@ -835,11 +977,13 @@ export function paintHighway(
             : shade(base, 0.45 * glow);
         if (headRow <= hitRow - 1) {
           tile(headRow, headGlyph, style);
-          const tag =
+          const cents =
             (note.cents !== undefined || note.centsFrom !== undefined) &&
             !note.muted
               ? centsTag(note.cents, note.centsFrom)
               : "";
+          const lyric = note.lyric && !note.muted ? note.lyric.slice(0, 8) : "";
+          const tag = [cents, lyric].filter(Boolean).join(" ");
           if (tag && x + width + tag.length <= region.width)
             for (let index = 0; index < tag.length; index += 1)
               painter.put(x + width + index, headRow, tag[index]!, roles.muted);
@@ -938,9 +1082,144 @@ export function paintHighway(
       }
     }
   }
+  // Ghost notes: a play key that is not recording lights its lane on the
+  // hit line for a moment, so the hand sees where the music would land.
+  if (options.glows && !reduced) {
+    const width = Math.max(1, layout.laneWidth || 1);
+    for (const glow of options.glows) {
+      const lane = projection.laneOf({ startBeat: beat, pitch: glow.pitch });
+      if (lane === undefined) continue;
+      const x = laneX(layout, lane, areaWidth);
+      const style = {
+        ...shade(accent, 0.45 * glow.strength),
+        bold: glow.strength > 0.5,
+      };
+      for (let offset = 0; offset < width; offset += 1)
+        painter.put(x + offset, hitRow, glyphs.hitStrong, style);
+    }
+  }
+  if (score.clips && score.clips.length > 0 && region.width >= 24)
+    paintClipRow(painter, score, {
+      beat,
+      hitRow,
+      lastNoteRow,
+      rowsPerBeat,
+      width: region.width,
+      loop,
+      glyphs,
+      accent,
+      roles,
+    });
   return layout;
 }
 
+function rowHasOnlyRule(
+  painter: Painter,
+  x: number,
+  length: number,
+  row: number,
+  glyphs: HighwayGlyphs,
+): boolean {
+  for (let index = 0; index < length; index += 1) {
+    const ch = painter.charAt(x + index, row);
+    if (ch !== " " && ch !== glyphs.beatRule) return false;
+  }
+  return true;
+}
+
+/** Shading for a clip's level, quiet to loud. */
+const CLIP_LEVELS_UNICODE = ["▏", "░", "▒", "▓", "█"];
+const CLIP_LEVELS_ASCII = [":", ".", "o", "O", "#"];
+
+/**
+ * The clip row: the rightmost column carries each clip's level as it
+ * falls toward the hit line, a seam (`┄`) where one clip continues
+ * another, and `id take · text` beside the clip's first row.
+ */
+function paintClipRow(
+  painter: Painter,
+  score: TrackScoreSnapshot,
+  at: {
+    beat: number;
+    hitRow: number;
+    lastNoteRow: number;
+    rowsPerBeat: number;
+    width: number;
+    loop: number | undefined;
+    glyphs: HighwayGlyphs;
+    accent: Style;
+    roles: Theme["roles"];
+  },
+): void {
+  const column = at.width - 1;
+  const levels =
+    at.glyphs === ASCII_GLYPHS ? CLIP_LEVELS_ASCII : CLIP_LEVELS_UNICODE;
+  const seamGlyph = at.glyphs === ASCII_GLYPHS ? "-" : "┄";
+  const rowBeat = (row: number) => at.beat + (at.hitRow - row) / at.rowsPerBeat;
+  const half = 0.5 / at.rowsPerBeat;
+  const occurrences = (clip: ClipSnapshot): number[] => {
+    if (!at.loop) return [clip.startBeat];
+    const base = Math.floor(at.beat / at.loop) * at.loop;
+    return [base - at.loop, base, base + at.loop].map(
+      (offset) => offset + clip.startBeat,
+    );
+  };
+  for (const clip of score.clips ?? []) {
+    const style = clip.muted ? at.roles.mutedNote : at.accent;
+    for (const start of occurrences(clip)) {
+      const end = start + clip.durationBeats;
+      for (let row = 0; row <= at.lastNoteRow; row += 1) {
+        if (row === at.hitRow) continue;
+        const center = rowBeat(row);
+        if (center + half <= start || center - half >= end) continue;
+        const isStart = start >= center - half && start < center + half;
+        if (isStart && clip.seam) {
+          painter.put(column, row, seamGlyph, at.roles.muted);
+        } else {
+          const peaks = clip.peaks;
+          const fraction = Math.max(
+            0,
+            Math.min(
+              0.999,
+              (center - start) / Math.max(1e-9, clip.durationBeats),
+            ),
+          );
+          const level =
+            peaks && peaks.length > 0
+              ? peaks[Math.floor(fraction * peaks.length)]!
+              : 0.6;
+          const index = clip.muted
+            ? 0
+            : Math.min(
+                levels.length - 1,
+                Math.round(level * (levels.length - 1)),
+              );
+          painter.put(column, row, levels[index]!, style);
+        }
+        if (isStart && row < at.hitRow) {
+          const label = [clip.id, clip.take, clip.text ? `· ${clip.text}` : ""]
+            .filter(Boolean)
+            .join(" ")
+            .slice(0, Math.max(0, Math.min(24, at.width - 6)));
+          const x = column - 1 - label.length;
+          // Over a beat rule the whole label draws; over notes it never does.
+          const ruled = rowHasOnlyRule(
+            painter,
+            x,
+            label.length,
+            row,
+            at.glyphs,
+          );
+          if (x > 3)
+            for (let index = 0; index < label.length; index += 1)
+              if (painter.isBlank(x + index, row) || ruled)
+                painter.put(x + index, row, label[index]!, at.roles.muted);
+        }
+      }
+    }
+  }
+}
+
 /**
  * A background track: a quiet head and sustain line in the track's accent,
  * no hit flash, sparks or ghosts, so the focused track stays readable.

package/tui/hints.ts

@@ -0,0 +1,197 @@
+/**
+ * Seeded hints: the empty-highway line and the prompt placeholder.
+ *
+ * Each list is chosen by what the session can do (an agent or commands
+ * only) and what the song holds (empty, pitched, drums), and one entry is
+ * picked by hashing the session id, so a session keeps the same words
+ * while it runs and the next session reads a different, equally short one.
+ * Every example is original and every command in it runs as typed.
+ */
+
+export type HintState = Readonly<{
+  /** The session id (or any stable string): the seed. */
+  seed: string;
+  /** An agent provider is ready, so prose requests work. */
+  agent: boolean;
+  /** The song has notes, clips or layers. */
+  filled: boolean;
+  /** The focused track is a drum kit. */
+  drums?: boolean;
+  /** The focused track is a vocal track. */
+  vocal?: boolean;
+  /** The transport is running. */
+  playing?: boolean;
+  /** The agent is busy and Enter queues for after it. */
+  queue?: boolean;
+}>;
+
+/** FNV-1a: a small, stable string hash. */
+export function seedHash(seed: string): number {
+  let hash = 0x811c9dc5;
+  for (let index = 0; index < seed.length; index += 1) {
+    hash ^= seed.charCodeAt(index);
+    hash = Math.imul(hash, 0x01000193) >>> 0;
+  }
+  return hash >>> 0;
+}
+
+/** The entry of `list` the seed picks; `salt` decorrelates two lists. */
+export function pick<T>(list: readonly T[], seed: string, salt = ""): T {
+  return list[seedHash(`${salt}:${seed}`) % list.length]!;
+}
+
+/** Prose requests an agent understands, for the placeholder. */
+const ASK_EMPTY = [
+  "describe a song — “a slow lofi loop in F with soft drums”",
+  "describe a song — “a four-bar house groove at 124 BPM”",
+  "describe a song — “a sad waltz for piano and cello”",
+  "describe a song — “a bright synth arpeggio in D major”",
+  "describe a song — “a dusty boom bap beat with a walking bass”",
+] as const;
+
+const ASK_FILLED = [
+  "describe a change — “add a walking bass in A minor”",
+  "describe a change — “make the drums swing a little”",
+  "describe a change — “double the melody an octave up”",
+  "describe a change — “add reverb to the keys”",
+  "describe a change — “slow it to 90 BPM and add a fill”",
+] as const;
+
+const ASK_DRUMS = [
+  "describe a change — “a ghost-note snare on the offbeats”",
+  "describe a change — “open hats on every and”",
+  "describe a change — “a crash on bar one, then a fill”",
+] as const;
+
+/**
+ * Commands that run without an agent, for the placeholder. `{style}` is the
+ * same seeded style the wide empty line suggests, so the two lines never
+ * offer competing first steps.
+ */
+const TYPE_EMPTY = [
+  "try: style {style} · space play · /help",
+  "try: style {style} 8 · then space to hear it",
+  "try: add C4 at 0 · add E4 at 1 · space play",
+  "try: style {style} · ctrl-z undo",
+] as const;
+
+const TYPE_FILLED = [
+  "try: tempo 96 · reverb 0.3 · space play",
+  "try: style again · ctrl-z undo",
+  "try: add G4 at 2 · bars 8 · space play",
+  "try: volume 0.6 · pan -0.2 · /help",
+  "try: ctrl-t tape · loop 1-2 · space play",
+  "try: copy all 1-4 to 5 · loop 5-8",
+  "try: knobs · mix · /help mix",
+  "try: panes · pane tape · /help panes",
+  "try: loop 1-2 · keys record · ctrl-z takes back a pass",
+] as const;
+
+const TYPE_DRUMS = [
+  "try: hit kick at 0 · hit snare at 1 · space play",
+  "try: euclid hat 7 16 · tempo 100",
+] as const;
+
+/**
+ * The keys on the empty line (design §8.5): transport, play mode and the
+ * menu while paused; while playing, how to stop and, with an agent, that a
+ * request still works.
+ */
+const KEYS_PAUSED = "space play · ctrl-p play mode · ctrl-k menu";
+const KEYS_PLAYING_AGENT = "space stop · type a request";
+const KEYS_PLAYING = "space stop · ctrl-p play mode";
+
+/** How to start a drum track or a vocal track, before the keys. */
+const LEAD_DRUMS = "hit kick at 0";
+const LEAD_VOCAL = 'lyrics "la la" · sing ooh · ctrl-k › Voice';
+
+/** Styles a wide empty line suggests, one per session (all have cards). */
+export const SUGGESTED_STYLES = [
+  "deep-house",
+  "lofi-hip-hop",
+  "bossa-nova",
+  "nu-disco",
+  "synthwave",
+  "golden-age",
+] as const;
+
+/** From this width the empty line also suggests a seeded style. */
+export const STYLE_HINT_WIDTH = 100;
+
+/** The prompt placeholder for this session and state. */
+export function placeholderHint(state: HintState): string {
+  if (state.agent && state.queue) return "queue a request for after this one…";
+  const list = state.agent
+    ? state.drums && state.filled
+      ? ASK_DRUMS
+      : state.filled
+        ? ASK_FILLED
+        : ASK_EMPTY
+    : state.drums
+      ? TYPE_DRUMS
+      : state.filled
+        ? TYPE_FILLED
+        : TYPE_EMPTY;
+  return pick(list, state.seed, "placeholder").replace(
+    "{style}",
+    sessionStyle(state.seed),
+  );
+}
+
+/** The one style this session suggests, on the empty line and the prompt. */
+export function sessionStyle(seed: string): string {
+  return pick(SUGGESTED_STYLES, seed, "style");
+}
+
+/**
+ * The empty-highway line, `<name> · empty · <lead> · <keys>`, shortened to
+ * `width`: the lead goes first, then the keys shrink to their first
+ * clause, then the name alone. A drum track leads with `hit kick at 0`, a
+ * vocal track with lyrics and sing, and from 100 columns a pitched track
+ * suggests a seeded style.
+ */
+export function emptyHint(
+  state: HintState,
+  name: string,
+  width: number,
+): string {
+  const keys = state.playing
+    ? state.agent
+      ? KEYS_PLAYING_AGENT
+      : KEYS_PLAYING
+    : KEYS_PAUSED;
+  const lead = state.drums
+    ? LEAD_DRUMS
+    : state.vocal
+      ? LEAD_VOCAL
+      : width >= STYLE_HINT_WIDTH && !state.playing
+        ? `try style ${sessionStyle(state.seed)}`
+        : undefined;
+  const head = `${name} · empty`;
+  const candidates = [
+    ...(lead ? [`${head} · ${lead} · ${keys}`] : []),
+    `${head} · ${keys}`,
+    `${head} · ${keys.split(" · ")[0]}`,
+  ];
+  for (const candidate of candidates)
+    if (candidate.length <= width) return candidate;
+  return head.slice(0, Math.max(0, width));
+}
+
+/** Every hint string, for the shipped-text and command checks. */
+export const ALL_HINTS: readonly string[] = [
+  ...ASK_EMPTY,
+  ...ASK_FILLED,
+  ...ASK_DRUMS,
+  ...TYPE_EMPTY.flatMap((hint) =>
+    SUGGESTED_STYLES.map((id) => hint.replace("{style}", id)),
+  ),
+  ...TYPE_FILLED,
+  ...TYPE_DRUMS,
+  KEYS_PAUSED,
+  KEYS_PLAYING_AGENT,
+  KEYS_PLAYING,
+  LEAD_DRUMS,
+  LEAD_VOCAL,
+  ...SUGGESTED_STYLES.map((id) => `try style ${id}`),
+];

package/tui/hits.ts

@@ -27,7 +27,13 @@ export type HitTarget =
   /** The piano roll / highway area. */
   | { kind: "highway" }
   /** Scrollable text (`/help`, the transcript, the `?` panel). */
-  | { kind: "text" };
+  | { kind: "text" }
+  /** TAPE's ruler: column `x - left + firstCell` is a cell (jump, loop drag). */
+  | { kind: "tape-ruler"; left: number; firstCell: number }
+  /** A TAPE track row (focus; shift-drag sets the loop). */
+  | { kind: "tape-row"; row: number; left: number; firstCell: number }
+  /** TAPE's clipboard chip (click pastes). */
+  | { kind: "tape-clipboard" };
 
 export interface HitRegion {
   x: number;