@hraness/dawg 0.2.0 → 0.3.0

package/src/tui/menu.ts

@@ -0,0 +1,1083 @@
+/**
+ * The hand-editing menu (`/menu`, Ctrl-K): every edit the agent can make,
+ * reachable with arrow keys. Pure: the tree is rebuilt from the score on
+ * every key, and a change is returned as the command it stands for, which
+ * the caller runs through the normal prompt path (one ScoreOperation, one
+ * receipt, one undo step). Each row shows its current value and that
+ * command, so the menu teaches the commands.
+ *
+ * Rendering reuses the TUI's picker overlay: `view()` returns a picker.
+ */
+import {
+  AUTOMATION_LANES,
+  SCORE_LIMITS,
+  type AutomationParameter,
+  type Track,
+  type TrackScore,
+} from "../../core/score.ts";
+import { AVAILABLE_INSTRUMENTS } from "../audio/wav.ts";
+import type { PickerItem } from "../../tui/app.ts";
+
+/** What the menu needs to know beyond the score. */
+export type MenuContext = Readonly<{
+  score: TrackScore;
+  trackId: string;
+  playing: boolean;
+  grid: string;
+  grids: readonly string[];
+  clickOn: boolean;
+  countInBars: number;
+}>;
+
+type NumberField = Readonly<{
+  kind: "number";
+  label: string;
+  /** `undefined` while the effect is off; a nudge then turns it on. */
+  value: number | undefined;
+  min: number;
+  max: number;
+  /** Next value one step in `direction`. */
+  step: (value: number, direction: 1 | -1) => number;
+  format: (value: number) => string;
+  command: (value: number) => string;
+  /** Shown while `value` is undefined. */
+  off?: string;
+  /** Starting value for a nudge while off. */
+  start?: number;
+}>;
+
+export type MenuNode =
+  | Readonly<{
+      kind: "menu";
+      id: string;
+      label: string;
+      detail: string;
+      build: (context: MenuContext) => MenuNode[];
+    }>
+  | NumberField
+  | Readonly<{
+      kind: "toggle";
+      label: string;
+      value: boolean;
+      command: (value: boolean) => string;
+    }>
+  | Readonly<{
+      kind: "choice";
+      label: string;
+      value: string;
+      options: readonly string[];
+      command: (option: string) => string;
+    }>
+  | Readonly<{
+      kind: "entry";
+      label: string;
+      value: string;
+      /** Shown in the title while typing. */
+      placeholder: string;
+      /** Command for the typed text; undefined when it cannot parse. */
+      command: (text: string) => string | undefined;
+      /** Shown as the slash-command equivalent. */
+      example: string;
+    }>
+  | Readonly<{ kind: "action"; label: string; command: string }>
+  | Readonly<{
+      kind: "point";
+      label: string;
+      lane: AutomationParameter;
+      beat: number;
+      value: number;
+    }>
+  | Readonly<{ kind: "info"; label: string; value: string }>;
+
+/** What a key did; `run` carries the command to execute. */
+export type MenuResult =
+  | { type: "handled" }
+  | { type: "close" }
+  | { type: "run"; command: string }
+  | { type: "pass" };
+
+export type MenuView = Readonly<{
+  title: string;
+  items: PickerItem[];
+  index: number;
+  hint: string;
+}>;
+
+// ── formatting and steps ──────────────────────────────────────────────
+
+export function num(value: number): string {
+  return String(Math.round(value * 1000) / 1000);
+}
+
+const linear =
+  (size: number, min: number, max: number) =>
+  (value: number, direction: 1 | -1) =>
+    clamp(Math.round((value + size * direction) / size) * size, min, max);
+
+/** Cutoff moves by thirds of an octave-ish so the low end stays usable. */
+const cutoffStep = (value: number, direction: 1 | -1) =>
+  clamp(
+    Math.round(direction > 0 ? value * 1.25 : value / 1.25),
+    SCORE_LIMITS.minFilterCutoff,
+    SCORE_LIMITS.maxFilterCutoff,
+  );
+
+const DELAY_BEATS = [
+  0.0625, 0.125, 0.1875, 0.25, 0.375, 0.5, 0.75, 1, 1.5, 2, 3, 4,
+] as const;
+const delayStep = (value: number, direction: 1 | -1) => {
+  if (direction > 0)
+    return DELAY_BEATS.find((beats) => beats > value + 1e-9) ?? 4;
+  return (
+    [...DELAY_BEATS].reverse().find((beats) => beats < value - 1e-9) ?? 0.0625
+  );
+};
+
+function clamp(value: number, min: number, max: number): number {
+  return Math.min(max, Math.max(min, value));
+}
+
+const LANE_STEP: Readonly<
+  Record<AutomationParameter, (value: number, direction: 1 | -1) => number>
+> = {
+  volume: linear(0.05, 0, SCORE_LIMITS.maxVolume),
+  pan: linear(0.1, -1, 1),
+  filter: cutoffStep,
+  resonance: linear(0.05, 0, SCORE_LIMITS.maxFilterResonance),
+  "delay-feedback": linear(0.05, 0, SCORE_LIMITS.maxDelayFeedback),
+  "delay-mix": linear(0.05, 0, SCORE_LIMITS.maxDelayMix),
+};
+
+const LANE_LABEL: Readonly<Record<AutomationParameter, string>> = {
+  volume: "volume",
+  pan: "pan",
+  filter: "filter cutoff (Hz)",
+  resonance: "filter resonance",
+  "delay-feedback": "delay feedback",
+  "delay-mix": "delay mix",
+};
+
+/** `volume 0.8`, `pan -0.3`: the command that sets a lane's static value. */
+function laneFormat(lane: AutomationParameter, value: number): string {
+  return lane === "filter" ? `${Math.round(value)}` : num(value);
+}
+
+// ── the tree ──────────────────────────────────────────────────────────
+
+function focused(context: MenuContext): Track | undefined {
+  return context.score.tracks.find((track) => track.id === context.trackId);
+}
+
+export function rootNodes(context: MenuContext): MenuNode[] {
+  const track = focused(context);
+  const name = track?.name ?? context.trackId;
+  const effects = [
+    track?.filter ? "filter" : undefined,
+    track?.delay ? "delay" : undefined,
+    track?.reverb ? "reverb" : undefined,
+  ].filter(Boolean);
+  const automated = (Object.keys(AUTOMATION_LANES) as AutomationParameter[])
+    .filter((lane) => (track?.[AUTOMATION_LANES[lane].field]?.length ?? 0) > 0)
+    .join(" ");
+  return [
+    {
+      kind: "menu",
+      id: "track",
+      label: "Track",
+      detail: `${name} · ${track?.instrument ?? "?"}`,
+      build: trackNodes,
+    },
+    {
+      kind: "menu",
+      id: "parameters",
+      label: "Parameters",
+      detail: `${track?.instrument ?? "?"}`,
+      build: parameterNodes,
+    },
+    {
+      kind: "menu",
+      id: "effects",
+      label: "Effects",
+      detail: effects.length ? effects.join(" · ") : "none",
+      build: effectNodes,
+    },
+    {
+      kind: "menu",
+      id: "automation",
+      label: "Automation",
+      detail: automated || "no lanes",
+      build: automationNodes,
+    },
+    {
+      kind: "menu",
+      id: "mix",
+      label: "Mix",
+      detail: `${context.score.tracks.length} track${context.score.tracks.length === 1 ? "" : "s"}`,
+      build: mixNodes,
+    },
+    {
+      kind: "menu",
+      id: "transport",
+      label: "Transport",
+      detail: `${num(context.score.tempoBpm)} BPM · ${context.score.beatsPerBar}/4 · ${context.score.bars} bars · grid ${context.grid}`,
+      build: transportNodes,
+    },
+  ];
+}
+
+function trackNodes(context: MenuContext): MenuNode[] {
+  const track = focused(context);
+  if (!track)
+    return [{ kind: "info", label: "no track", value: "/track <name>" }];
+  return [
+    {
+      kind: "entry",
+      label: "name",
+      value: track.name,
+      placeholder: "new name",
+      command: (text) =>
+        text.trim() ? `track name ${text.trim()}` : undefined,
+      example: `track name ${track.name}`,
+    },
+    instrumentNode(track),
+    {
+      kind: "toggle",
+      label: "mute",
+      value: track.muted,
+      command: (on) => (on ? "mute" : "unmute"),
+    },
+    {
+      kind: "toggle",
+      label: "solo",
+      value: track.solo === true,
+      command: (on) => (on ? "solo" : "unsolo"),
+    },
+    volumeNode(track),
+    panNode(track),
+  ];
+}
+
+function instrumentNode(track: Track): MenuNode {
+  const options: string[] = [...AVAILABLE_INSTRUMENTS];
+  if (!options.includes(track.instrument)) options.push(track.instrument);
+  return {
+    kind: "choice",
+    label: "instrument",
+    value: track.instrument,
+    options,
+    command: (option) => `instrument ${option}`,
+  };
+}
+
+function volumeNode(track: Track): MenuNode {
+  return {
+    kind: "number",
+    label: "volume",
+    value: track.volume,
+    min: 0,
+    max: SCORE_LIMITS.maxVolume,
+    step: LANE_STEP.volume,
+    format: num,
+    command: (value) => `volume ${num(value)}`,
+  };
+}
+
+function panNode(track: Track): MenuNode {
+  return {
+    kind: "number",
+    label: "pan",
+    value: track.pan,
+    min: -1,
+    max: 1,
+    step: LANE_STEP.pan,
+    format: num,
+    command: (value) => `pan ${num(value)}`,
+  };
+}
+
+function parameterNodes(context: MenuContext): MenuNode[] {
+  const track = focused(context);
+  if (!track) return [];
+  const nodes: MenuNode[] = [instrumentNode(track)];
+  if (track.sampler) {
+    nodes.push({
+      kind: "info",
+      label: "sampler mode",
+      value: track.sampler.mode,
+    });
+    for (const [voice, ref] of Object.entries(track.sampler.voices).sort()) {
+      const extras = [
+        ref.root !== undefined ? `root ${ref.root}` : "",
+        ref.gain !== undefined ? `gain ${num(ref.gain)}` : "",
+        ref.speed !== undefined ? `speed ${num(ref.speed)}` : "",
+      ].filter(Boolean);
+      nodes.push({
+        kind: "info",
+        label: voice,
+        value: [ref.src.split("/").at(-1), ...extras].join(" · "),
+      });
+    }
+    nodes.push({
+      kind: "info",
+      label: "add a voice",
+      value: "/sample <path> [as <voice>]",
+    });
+  } else {
+    nodes.push({
+      kind: "info",
+      label: "voice",
+      value:
+        "the synth has no knobs beyond the instrument; shape it with Effects",
+    });
+  }
+  return nodes;
+}
+
+function effectNodes(context: MenuContext): MenuNode[] {
+  const track = focused(context);
+  if (!track) return [];
+  const filter = track.filter;
+  const delay = track.delay;
+  const reverb = track.reverb;
+  return [
+    {
+      kind: "menu",
+      id: "filter",
+      label: "Filter",
+      detail: filter
+        ? `${Math.round(filter.cutoff)} Hz · res ${num(filter.resonance)}`
+        : "off",
+      build: () => [
+        {
+          kind: "toggle",
+          label: "on",
+          value: filter !== undefined,
+          command: (on) => (on ? "filter 2000 0.2" : "filter off"),
+        },
+        {
+          kind: "number",
+          label: "cutoff Hz",
+          value: filter?.cutoff,
+          start: 2000,
+          off: "off",
+          min: SCORE_LIMITS.minFilterCutoff,
+          max: SCORE_LIMITS.maxFilterCutoff,
+          step: cutoffStep,
+          format: (value) => `${Math.round(value)}`,
+          command: (value) =>
+            `filter ${Math.round(value)} ${num(filter?.resonance ?? 0)}`,
+        },
+        {
+          kind: "number",
+          label: "resonance",
+          value: filter?.resonance,
+          start: 0.2,
+          off: "off",
+          min: 0,
+          max: SCORE_LIMITS.maxFilterResonance,
+          step: LANE_STEP.resonance,
+          format: num,
+          command: (value) =>
+            `filter ${Math.round(filter?.cutoff ?? 2000)} ${num(value)}`,
+        },
+      ],
+    },
+    {
+      kind: "menu",
+      id: "delay",
+      label: "Delay",
+      detail: delay
+        ? `${num(delay.beats)} beats · fb ${num(delay.feedback)} · mix ${num(delay.mix)}`
+        : "off",
+      build: () => {
+        const beats = delay?.beats ?? 0.5;
+        const feedback = delay?.feedback ?? 0.3;
+        const mix = delay?.mix ?? 0.35;
+        return [
+          {
+            kind: "toggle",
+            label: "on",
+            value: delay !== undefined,
+            command: (on) => (on ? "delay 0.5 0.3 0.35" : "delay off"),
+          },
+          {
+            kind: "number",
+            label: "time beats",
+            value: delay?.beats,
+            start: 0.5,
+            off: "off",
+            min: SCORE_LIMITS.minDelayBeats,
+            max: SCORE_LIMITS.maxDelayBeats,
+            step: delayStep,
+            format: num,
+            command: (value) =>
+              `delay ${num(value)} ${num(feedback)} ${num(mix)}`,
+          },
+          {
+            kind: "number",
+            label: "feedback",
+            value: delay?.feedback,
+            start: 0.3,
+            off: "off",
+            min: 0,
+            max: SCORE_LIMITS.maxDelayFeedback,
+            step: LANE_STEP["delay-feedback"],
+            format: num,
+            command: (value) => `delay ${num(beats)} ${num(value)} ${num(mix)}`,
+          },
+          {
+            kind: "number",
+            label: "mix",
+            value: delay?.mix,
+            start: 0.35,
+            off: "off",
+            min: 0,
+            max: SCORE_LIMITS.maxDelayMix,
+            step: LANE_STEP["delay-mix"],
+            format: num,
+            command: (value) =>
+              `delay ${num(beats)} ${num(feedback)} ${num(value)}`,
+          },
+        ];
+      },
+    },
+    {
+      kind: "menu",
+      id: "reverb",
+      label: "Reverb",
+      detail: reverb
+        ? `mix ${num(reverb.mix)} · size ${num(reverb.size)}`
+        : "off",
+      build: () => [
+        {
+          kind: "toggle",
+          label: "on",
+          value: reverb !== undefined,
+          command: (on) => (on ? "reverb 0.3 0.5" : "reverb off"),
+        },
+        {
+          kind: "number",
+          label: "mix",
+          value: reverb?.mix,
+          start: 0.3,
+          off: "off",
+          min: 0,
+          max: SCORE_LIMITS.maxReverbMix,
+          step: linear(0.05, 0, SCORE_LIMITS.maxReverbMix),
+          format: num,
+          command: (value) =>
+            `reverb ${num(value)} ${num(reverb?.size ?? 0.5)}`,
+        },
+        {
+          kind: "number",
+          label: "size",
+          value: reverb?.size,
+          start: 0.5,
+          off: "off",
+          min: SCORE_LIMITS.minReverbSize,
+          max: SCORE_LIMITS.maxReverbSize,
+          step: linear(
+            0.05,
+            SCORE_LIMITS.minReverbSize,
+            SCORE_LIMITS.maxReverbSize,
+          ),
+          format: num,
+          command: (value) => `reverb ${num(reverb?.mix ?? 0.3)} ${num(value)}`,
+        },
+      ],
+    },
+  ];
+}
+
+function automationNodes(context: MenuContext): MenuNode[] {
+  const track = focused(context);
+  if (!track) return [];
+  return (Object.keys(AUTOMATION_LANES) as AutomationParameter[]).map(
+    (lane) => {
+      const count = track[AUTOMATION_LANES[lane].field]?.length ?? 0;
+      return {
+        kind: "menu",
+        id: `lane:${lane}`,
+        label: LANE_LABEL[lane],
+        detail: `${count} point${count === 1 ? "" : "s"}`,
+        build: (inner) => laneNodes(inner, lane),
+      };
+    },
+  );
+}
+
+/** `4:0.5 8:1` → `automate <lane> points 4:0.5 8:1`, when every pair parses. */
+function pointsCommand(
+  lane: AutomationParameter,
+  text: string,
+  exactly?: number,
+): string | undefined {
+  const pairs = text
+    .trim()
+    .split(/[\s,]+/)
+    .filter(Boolean);
+  if (pairs.length === 0 || (exactly !== undefined && pairs.length !== exactly))
+    return undefined;
+  const { min, max } = AUTOMATION_LANES[lane];
+  for (const pair of pairs) {
+    const match = pair.match(/^(\d+(?:\.\d+)?):(-?\d+(?:\.\d+)?)$/);
+    if (!match) return undefined;
+    const value = Number(match[2]);
+    if (value < min || value > max) return undefined;
+  }
+  return `automate ${lane} points ${pairs.join(" ")}`;
+}
+
+function laneNodes(
+  context: MenuContext,
+  lane: AutomationParameter,
+): MenuNode[] {
+  const track = focused(context);
+  if (!track) return [];
+  const { min, max, field } = AUTOMATION_LANES[lane];
+  const range = `${laneFormat(lane, min)}…${laneFormat(lane, max)}`;
+  const points = track[field] ?? [];
+  const nodes: MenuNode[] = [
+    {
+      kind: "entry",
+      label: "add points",
+      value: range,
+      placeholder: "beat:value [beat:value …]",
+      command: (text) => pointsCommand(lane, text),
+      example: `automate ${lane} points 0:${laneFormat(lane, min)} 4:${laneFormat(lane, max)}`,
+    },
+    {
+      kind: "entry",
+      label: "ramp",
+      value: "two points",
+      placeholder: "from-beat:value to-beat:value",
+      command: (text) => pointsCommand(lane, text, 2),
+      example: `automate ${lane} points 0:${laneFormat(lane, min)} ${context.score.beatsPerBar * context.score.bars}:${laneFormat(lane, max)}`,
+    },
+  ];
+  for (const point of points)
+    nodes.push({
+      kind: "point",
+      label: `beat ${num(point.tick / context.score.ticksPerBeat)}`,
+      lane,
+      beat: point.tick / context.score.ticksPerBeat,
+      value: point.value,
+    });
+  if (points.length > 0)
+    nodes.push({
+      kind: "action",
+      label: "clear lane",
+      command: `clear ${lane} automation`,
+    });
+  return nodes;
+}
+
+function mixNodes(context: MenuContext): MenuNode[] {
+  return context.score.tracks.map((track): MenuNode => {
+    const detail = `vol ${num(track.volume)} · pan ${num(track.pan)}${track.muted ? " · M" : ""}${track.solo ? " · S" : ""}`;
+    // Commands act on the focused track, so another track is focused first.
+    return track.id === context.trackId
+      ? {
+          kind: "menu",
+          id: `mix:${track.id}`,
+          label: `${track.name} ●`,
+          detail,
+          build: trackNodes,
+        }
+      : {
+          kind: "action",
+          label: `${track.name}  ${detail}`,
+          command: `/track ${track.id}`,
+        };
+  });
+}
+
+function transportNodes(context: MenuContext): MenuNode[] {
+  const score = context.score;
+  return [
+    {
+      kind: "action",
+      label: context.playing ? "pause" : "play",
+      command: context.playing ? "pause" : "play",
+    },
+    {
+      kind: "number",
+      label: "tempo BPM",
+      value: score.tempoBpm,
+      min: SCORE_LIMITS.minTempoBpm,
+      max: SCORE_LIMITS.maxTempoBpm,
+      step: linear(1, SCORE_LIMITS.minTempoBpm, SCORE_LIMITS.maxTempoBpm),
+      format: num,
+      command: (value) => `tempo ${num(value)}`,
+    },
+    {
+      kind: "number",
+      label: "beats per bar",
+      value: score.beatsPerBar,
+      min: 1,
+      max: SCORE_LIMITS.maxBeatsPerBar,
+      step: linear(1, 1, SCORE_LIMITS.maxBeatsPerBar),
+      format: (value) => `${value}/4`,
+      command: (value) => `meter ${Math.round(value)}`,
+    },
+    {
+      kind: "number",
+      label: "loop bars",
+      value: score.bars,
+      min: 1,
+      max: SCORE_LIMITS.maxBars,
+      step: linear(1, 1, SCORE_LIMITS.maxBars),
+      format: num,
+      command: (value) => `bars ${Math.round(value)}`,
+    },
+    {
+      kind: "choice",
+      label: "grid",
+      value: context.grid,
+      options: context.grids,
+      command: (option) => `/grid ${option}`,
+    },
+    {
+      kind: "toggle",
+      label: "click",
+      value: context.clickOn,
+      command: (on) => `/click ${on ? "on" : "off"}`,
+    },
+    {
+      kind: "choice",
+      label: "count-in bars",
+      value: String(context.countInBars),
+      options: ["0", "1", "2"],
+      command: (option) => `/count-in ${option}`,
+    },
+  ];
+}
+
+// ── controller ────────────────────────────────────────────────────────
+
+type Frame = {
+  title: string;
+  build: (context: MenuContext) => MenuNode[];
+  index: number;
+  query: string;
+};
+
+const KEY_UP = new Set(["\u001b[A", "\u001bOA", "k"]);
+const KEY_DOWN = new Set(["\u001b[B", "\u001bOB", "j"]);
+const KEY_LEFT = new Set(["\u001b[D", "\u001bOD", "h", "-", "_"]);
+const KEY_RIGHT = new Set(["\u001b[C", "\u001bOC", "l", "+", "="]);
+const KEY_ENTER = new Set(["\r", "\n"]);
+const KEY_BACKSPACE = new Set(["\u007f", "\b"]);
+const KEY_DELETE = new Set(["\u001b[3~", "x"]);
+const LABEL_WIDTH = 16;
+
+/**
+ * A submenu frame whose rows are rebuilt from the parent's fresh build, so
+ * values (and the commands closed over them) always follow the score.
+ */
+function childFrame(
+  parent: Frame,
+  node: Extract<MenuNode, { kind: "menu" }>,
+): Frame {
+  return {
+    title: node.label,
+    index: 0,
+    query: "",
+    build: (context) => {
+      const fresh = parent
+        .build(context)
+        .find(
+          (candidate): candidate is Extract<MenuNode, { kind: "menu" }> =>
+            candidate.kind === "menu" && candidate.id === node.id,
+        );
+      return (fresh ?? node).build(context);
+    },
+  };
+}
+
+export class EditMenu {
+  private stack: Frame[] = [];
+  private filtering = false;
+  /** Typed value for the selected row (`entry` holds the row's label). */
+  private entry: { label: string; buffer: string } | undefined;
+
+  get open(): boolean {
+    return this.stack.length > 0;
+  }
+
+  /** Open at the root, or at a section id (`effects`, `automation`). */
+  show(context: MenuContext, section?: string): void {
+    this.stack = [{ title: "menu", build: rootNodes, index: 0, query: "" }];
+    this.filtering = false;
+    this.entry = undefined;
+    if (section) {
+      const nodes = rootNodes(context);
+      const index = nodes.findIndex(
+        (node) => node.kind === "menu" && node.id === section.toLowerCase(),
+      );
+      const node = nodes[index];
+      if (node?.kind === "menu") {
+        this.stack[0]!.index = index;
+        this.stack.push(childFrame(this.stack[0]!, node));
+      }
+    }
+  }
+
+  close(): void {
+    this.stack = [];
+    this.filtering = false;
+    this.entry = undefined;
+  }
+
+  /** The visible rows of the current level (filtered). */
+  nodes(context: MenuContext): MenuNode[] {
+    const frame = this.stack.at(-1);
+    if (!frame) return [];
+    const all = frame.build(context);
+    const needle = frame.query.toLowerCase();
+    return needle
+      ? all.filter((node) => nodeText(node).toLowerCase().includes(needle))
+      : all;
+  }
+
+  private selected(context: MenuContext): MenuNode | undefined {
+    const frame = this.stack.at(-1);
+    const nodes = this.nodes(context);
+    if (!frame || nodes.length === 0) return undefined;
+    frame.index = clamp(frame.index, 0, nodes.length - 1);
+    return nodes[frame.index];
+  }
+
+  key(value: string, context: MenuContext): MenuResult {
+    const frame = this.stack.at(-1);
+    if (!frame) return { type: "pass" };
+    if (value === "\u0003" || value === "\u000c") return { type: "pass" };
+    if (this.entry) return this.entryKey(value, context);
+    if (this.filtering) {
+      if (value === "\u001b") {
+        frame.query = "";
+        this.filtering = false;
+        return { type: "handled" };
+      }
+      if (KEY_BACKSPACE.has(value)) {
+        frame.query = frame.query.slice(0, -1);
+        if (!frame.query) this.filtering = false;
+        frame.index = 0;
+        return { type: "handled" };
+      }
+      if (
+        KEY_ENTER.has(value) ||
+        value === "\u001b[B" ||
+        value === "\u001b[A"
+      ) {
+        this.filtering = false;
+        return this.key(value, context);
+      }
+      if (value.length === 1 && value >= " ") {
+        frame.query = (frame.query + value).slice(0, 40);
+        frame.index = 0;
+        return { type: "handled" };
+      }
+      return { type: "handled" };
+    }
+    const nodes = this.nodes(context);
+    const node = this.selected(context);
+    if (value === "\u001b") {
+      if (frame.query) {
+        frame.query = "";
+        return { type: "handled" };
+      }
+      this.stack.pop();
+      return this.stack.length ? { type: "handled" } : { type: "close" };
+    }
+    if (value === "/") {
+      this.filtering = true;
+      frame.query = "";
+      return { type: "handled" };
+    }
+    if (KEY_UP.has(value) || KEY_DOWN.has(value)) {
+      const step = KEY_UP.has(value) ? -1 : 1;
+      if (nodes.length)
+        frame.index = (frame.index + step + nodes.length) % nodes.length;
+      return { type: "handled" };
+    }
+    if (value === "\u001b[5~" || value === "\u001b[H") {
+      frame.index = 0;
+      return { type: "handled" };
+    }
+    if (value === "\u001b[6~" || value === "\u001b[F") {
+      frame.index = Math.max(0, nodes.length - 1);
+      return { type: "handled" };
+    }
+    if (!node) return { type: "handled" };
+    if (KEY_LEFT.has(value) || KEY_RIGHT.has(value)) {
+      const direction = KEY_RIGHT.has(value) ? 1 : -1;
+      return this.nudge(node, direction);
+    }
+    if (KEY_DELETE.has(value) && node.kind === "point")
+      return {
+        type: "run",
+        command: `automate ${node.lane} remove ${num(node.beat)}`,
+      };
+    if (
+      /^[0-9.]$/.test(value) &&
+      (node.kind === "number" || node.kind === "point")
+    ) {
+      this.entry = { label: node.label, buffer: value };
+      return { type: "handled" };
+    }
+    if (KEY_ENTER.has(value) || value === " ") {
+      if (node.kind === "menu") {
+        // Going back lands on the opened row with the filter cleared.
+        if (frame.query) {
+          frame.query = "";
+          frame.index = Math.max(
+            0,
+            this.nodes(context).findIndex(
+              (candidate) =>
+                candidate.kind === "menu" && candidate.id === node.id,
+            ),
+          );
+        }
+        this.stack.push(childFrame(frame, node));
+        return { type: "handled" };
+      }
+      if (node.kind === "toggle")
+        return { type: "run", command: node.command(!node.value) };
+      if (node.kind === "action") return { type: "run", command: node.command };
+      if (node.kind === "choice") {
+        const current = node.options.indexOf(node.value);
+        this.stack.push({
+          title: node.label,
+          index: Math.max(0, current),
+          query: "",
+          build: (fresh) => {
+            const parent = this.stack.at(-2);
+            const live =
+              parent
+                ?.build(fresh)
+                .find(
+                  (candidate): candidate is typeof node =>
+                    candidate.kind === "choice" &&
+                    candidate.label === node.label,
+                ) ?? node;
+            return live.options.map((option) => ({
+              kind: "action",
+              label: option === live.value ? `${option}  ✓` : option,
+              command: live.command(option),
+            }));
+          },
+        });
+        return { type: "handled" };
+      }
+      if (
+        node.kind === "entry" ||
+        node.kind === "number" ||
+        node.kind === "point"
+      ) {
+        this.entry = { label: node.label, buffer: "" };
+        return { type: "handled" };
+      }
+    }
+    return { type: "handled" };
+  }
+
+  private nudge(node: MenuNode, direction: 1 | -1): MenuResult {
+    if (node.kind === "menu") {
+      if (direction > 0) {
+        this.stack.push(childFrame(this.stack.at(-1)!, node));
+        return { type: "handled" };
+      }
+      if (this.stack.length > 1) this.stack.pop();
+      return { type: "handled" };
+    }
+    if (node.kind === "number") {
+      const next =
+        node.value === undefined
+          ? (node.start ?? node.min)
+          : clamp(node.step(node.value, direction), node.min, node.max);
+      if (node.value !== undefined && Math.abs(next - node.value) < 1e-9)
+        return { type: "handled" };
+      return { type: "run", command: node.command(next) };
+    }
+    if (node.kind === "point") {
+      const { min, max } = AUTOMATION_LANES[node.lane];
+      const next = clamp(LANE_STEP[node.lane](node.value, direction), min, max);
+      if (Math.abs(next - node.value) < 1e-9) return { type: "handled" };
+      return {
+        type: "run",
+        command: `automate ${node.lane} points ${num(node.beat)}:${laneFormat(node.lane, next)}`,
+      };
+    }
+    if (node.kind === "toggle") {
+      const want = direction > 0;
+      return want === node.value
+        ? { type: "handled" }
+        : { type: "run", command: node.command(want) };
+    }
+    if (node.kind === "choice") {
+      const at = node.options.indexOf(node.value);
+      const next =
+        node.options[clamp(at + direction, 0, node.options.length - 1)];
+      return next === undefined || next === node.value
+        ? { type: "handled" }
+        : { type: "run", command: node.command(next) };
+    }
+    if (direction < 0 && this.stack.length > 1) this.stack.pop();
+    return { type: "handled" };
+  }
+
+  private entryKey(value: string, context: MenuContext): MenuResult {
+    const entry = this.entry!;
+    if (value === "\u001b") {
+      this.entry = undefined;
+      return { type: "handled" };
+    }
+    if (KEY_BACKSPACE.has(value)) {
+      entry.buffer = entry.buffer.slice(0, -1);
+      return { type: "handled" };
+    }
+    if (KEY_ENTER.has(value)) {
+      const node = this.selected(context);
+      this.entry = undefined;
+      const command = node ? entryCommand(node, entry.buffer) : undefined;
+      if (!command) return { type: "handled" };
+      // A committed value clears the filter so its result (a new automation
+      // point, a renamed row) is in view, keeping the cursor on the row.
+      const frame = this.stack.at(-1)!;
+      if (frame.query && node) {
+        frame.query = "";
+        const index = this.nodes(context).findIndex(
+          (candidate) => candidate.label === node.label,
+        );
+        frame.index = Math.max(0, index);
+      }
+      return { type: "run", command };
+    }
+    if (value.length >= 1 && !value.startsWith("\u001b") && value >= " ") {
+      entry.buffer = (entry.buffer + value).slice(0, 200);
+    }
+    return { type: "handled" };
+  }
+
+  /** The picker the TUI draws for the current level. */
+  view(context: MenuContext): MenuView {
+    const frame = this.stack.at(-1);
+    const nodes = this.nodes(context);
+    const index = frame
+      ? clamp(frame.index, 0, Math.max(0, nodes.length - 1))
+      : 0;
+    const crumbs = this.stack.map((level) => level.title).join(" › ");
+    const selected = nodes[index];
+    let title = crumbs;
+    if (frame?.query || this.filtering) title += ` · /${frame?.query ?? ""}`;
+    if (this.entry)
+      title += ` · ${this.entry.label}: ${this.entry.buffer || placeholderFor(selected)}▏`;
+    const items = nodes.map((node, at) => ({
+      label: `${node.label.padEnd(LABEL_WIDTH)} ${valueText(node)}`.trimEnd(),
+      detail: commandText(node),
+      value: String(at),
+    }));
+    const hint = this.entry
+      ? " type a value · enter apply · esc cancel "
+      : this.filtering
+        ? " type to filter · enter choose · esc clear "
+        : selected?.kind === "point"
+          ? " ←→ nudge · digits set · x delete · esc back "
+          : selected?.kind === "number" ||
+              selected?.kind === "toggle" ||
+              selected?.kind === "choice"
+            ? " ←→/+- nudge · digits set · enter edit · / filter · esc back "
+            : " ↑↓ move · enter open · / filter · esc back ";
+    return { title, items, index, hint };
+  }
+}
+
+function placeholderFor(node: MenuNode | undefined): string {
+  if (!node) return "";
+  if (node.kind === "entry") return node.placeholder;
+  if (node.kind === "number")
+    return `${node.format(node.min)}…${node.format(node.max)}`;
+  if (node.kind === "point") return "value";
+  return "";
+}
+
+function entryCommand(node: MenuNode, text: string): string | undefined {
+  const trimmed = text.trim();
+  if (node.kind === "entry") return node.command(trimmed);
+  if (node.kind === "number") {
+    if (!/^-?\d+(?:\.\d+)?$/.test(trimmed)) return undefined;
+    const value = Number(trimmed);
+    if (value < node.min || value > node.max) return undefined;
+    return node.command(value);
+  }
+  if (node.kind === "point") {
+    // `0.8` sets the value; `6:0.8` moves to beat 6.
+    const { min, max } = AUTOMATION_LANES[node.lane];
+    const match = trimmed.match(/^(?:(\d+(?:\.\d+)?):)?(-?\d+(?:\.\d+)?)$/);
+    if (!match) return undefined;
+    const value = Number(match[2]);
+    if (value < min || value > max) return undefined;
+    if (match[1] !== undefined && Number(match[1]) !== node.beat)
+      return `automate ${node.lane} points ${match[1]}:${match[2]}`;
+    return `automate ${node.lane} points ${num(node.beat)}:${match[2]}`;
+  }
+  return undefined;
+}
+
+function valueText(node: MenuNode): string {
+  switch (node.kind) {
+    case "menu":
+      return node.detail;
+    case "number":
+      return node.value === undefined
+        ? (node.off ?? "—")
+        : node.format(node.value);
+    case "toggle":
+      return node.value ? "on" : "off";
+    case "choice":
+      return node.value;
+    case "entry":
+      return node.value;
+    case "point":
+      return laneFormat(node.lane, node.value);
+    case "info":
+      return node.value;
+    case "action":
+      return "";
+  }
+}
+
+/** The command a row stands for, shown so the menu teaches commands. */
+function commandText(node: MenuNode): string | undefined {
+  switch (node.kind) {
+    case "number":
+      return node.command(node.value ?? node.start ?? node.min);
+    case "toggle":
+      return node.command(!node.value);
+    case "choice":
+      return node.command(node.value);
+    case "entry":
+      return node.example;
+    case "action":
+      return node.command;
+    case "point":
+      return `automate ${node.lane} points ${num(node.beat)}:${laneFormat(node.lane, node.value)}`;
+    default:
+      return undefined;
+  }
+}
+
+function nodeText(node: MenuNode): string {
+  return `${node.label} ${valueText(node)} ${commandText(node) ?? ""}`;
+}
+
+/** Root sections, for `/menu <section>`. */
+export const MENU_SECTIONS = [
+  "track",
+  "parameters",
+  "effects",
+  "automation",
+  "mix",
+  "transport",
+] as const;