@hraness/dawg 0.6.0 → 0.7.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 {
@@ -83,6 +102,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. */
@@ -413,6 +475,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 {
@@ -473,6 +541,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;
 }
 
 /**
@@ -516,6 +585,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 +597,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 +689,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 +747,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 +942,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 +1047,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,192 @@
+/**
+ * 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",
+] 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/input.ts

@@ -7,16 +7,42 @@
 export type TerminalInputEvent =
   string | Readonly<{ type: "paste"; text: string }>;
 
+/** A bracketed paste longer than this is emitted as it stands. */
+export const MAX_PASTE_CHARS = 1 << 20;
+
+/** A chunk marker the read loop yields when input went idle mid-sequence. */
+export const INPUT_FLUSH = "\u0000flush";
+
+/** Idle time after which a partial escape prefix is a key of its own. */
+export const ESCAPE_FLUSH_MS = 50;
+/** Idle time after which an unterminated bracketed paste is emitted. */
+export const PASTE_FLUSH_MS = 1_000;
+
 export class TerminalInputDecoder {
   private buffer = "";
 
+  /**
+   * What the decoder holds back: `escape` for a partial escape sequence,
+   * `paste` for an unterminated bracketed paste. The caller flushes after
+   * `ESCAPE_FLUSH_MS` or `PASTE_FLUSH_MS` with no further input.
+   */
+  pending(): "escape" | "paste" | undefined {
+    if (this.buffer.length === 0) return undefined;
+    return this.buffer.startsWith("\u001b[200~") ? "paste" : "escape";
+  }
+
   push(chunk: string): TerminalInputEvent[] {
     this.buffer += chunk;
     const events: TerminalInputEvent[] = [];
     while (this.buffer.length > 0) {
       if (this.buffer.startsWith("\u001b[200~")) {
         const end = this.buffer.indexOf("\u001b[201~", 6);
-        if (end < 0) break;
+        if (end < 0) {
+          if (this.buffer.length - 6 < MAX_PASTE_CHARS) break;
+          events.push({ type: "paste", text: this.buffer.slice(6) });
+          this.buffer = "";
+          break;
+        }
         events.push({ type: "paste", text: this.buffer.slice(6, end) });
         this.buffer = this.buffer.slice(end + 6);
         continue;
@@ -38,12 +64,27 @@ export class TerminalInputDecoder {
     return events;
   }
 
+  /**
+   * Emits whatever is held back, once no more input is coming: a cut-off
+   * bracketed paste as a paste, a lone ESC as Esc, and a partial prefix such
+   * as `ESC [` (Alt+[) or `ESC O` (Alt+O) as one Alt key, then decodes the
+   * rest normally.
+   */
   flush(): TerminalInputEvent[] {
-    if (this.buffer === "\u001b") {
+    const events: TerminalInputEvent[] = [];
+    while (this.buffer.length > 0) {
+      if (this.buffer.startsWith("\u001b[200~")) {
+        events.push({ type: "paste", text: this.buffer.slice(6) });
+        this.buffer = "";
+        break;
+      }
+      const head =
+        this.buffer.length === 1 ? "\u001b" : this.buffer.slice(0, 2);
+      const rest = this.buffer.slice(head.length);
       this.buffer = "";
-      return ["\u001b"];
+      events.push(head, ...this.push(rest));
     }
-    return [];
+    return events;
   }
 
   private readEscapeSequence(): string | undefined {
@@ -59,12 +100,22 @@ export class TerminalInputDecoder {
       return this.buffer.length >= 6 ? this.buffer.slice(0, 6) : undefined;
     const final = this.buffer.match(/^\u001b\[[\x20-?]*[\x40-~]/)?.[0];
     if (final !== undefined) return final;
-    // SS3: arrows in application mode and F1-F4 (`ESC O P` is F1).
-    const ss3 = this.buffer.match(/^\u001bO[A-DHFPQRS]/)?.[0];
-    if (ss3 !== undefined) return ss3;
+    // A byte that cannot continue a CSI ends it: the `ESC [` was Alt+[.
+    if (this.buffer.startsWith("\u001b[")) {
+      const partial = this.buffer.match(/^\u001b\[[\x20-?]*/)![0];
+      if (partial.length < this.buffer.length) return "\u001b[";
+    }
+    // SS3: arrows in application mode and F1-F4 (`ESC O P` is F1). A bare
+    // `ESC O` waits for its final byte, which a PTY may deliver separately;
+    // `flush` turns it into Alt+O if nothing follows.
+    if (this.buffer.startsWith("\u001bO")) {
+      if (this.buffer.length === 2) return undefined;
+      const ss3 = this.buffer.match(/^\u001bO[A-DHFPQRS]/)?.[0];
+      if (ss3 !== undefined) return ss3;
+      return "\u001bO";
+    }
     // An unrecognised Alt-prefixed character is still one complete event.
-    if (this.buffer.length >= 2 && this.buffer[1] !== "[")
-      return this.buffer.slice(0, 2);
+    if (this.buffer[1] !== "[") return this.buffer.slice(0, 2);
     return undefined;
   }
 }

package/tui/keys.ts

@@ -3,7 +3,7 @@
  *
  * The prompt is always focused, so printable keys always type.  Control
  * chords carry the global actions:
- *   Ctrl+C quit · Ctrl+Q toggle STEER/QUEUE · Ctrl+Z undo · Ctrl+Y redo
+ *   Ctrl+C quit · Ctrl+Q toggle NOW/NEXT · Ctrl+Z undo · Ctrl+Y redo
  *   Ctrl+O transcript overlay · Esc closes the overlay
  */