@hraness/dawg 0.2.0 → 0.3.0

package/src/commands/edit.ts

@@ -0,0 +1,170 @@
+/**
+ * Hand-editing commands the menus emit that the prompt grammar lacked. Each
+ * is one ScoreOperation, so it is one revision and one undo step.
+ *
+ *   track name <text>                       rename the focused track
+ *   meter <beats per bar>                   time signature numerator (1..16)
+ *   automate <lane> points <beat:value>...  merge points into a lane
+ *   automate <lane> remove <beat>           drop the point at a beat
+ *
+ * Lanes are every AUTOMATION_LANES key plus the effect aliases (`cutoff`,
+ * `res`, `feedback`, `delay-fb`). Parsing is pure; applying returns the next
+ * score and the session event, leaving persistence to the caller.
+ */
+import {
+  AUTOMATION_LANES,
+  SCORE_LIMITS,
+  applyScoreOperation,
+  type AutomationParameter,
+  type AutomationPoint,
+  type ScoreOperation,
+  type TrackScore,
+} from "../../core/score.ts";
+import { parseEffectLane } from "./music.ts";
+
+export type EditCommand =
+  | { type: "track-name"; name: string }
+  | { type: "meter"; beatsPerBar: number }
+  | {
+      type: "automation-points";
+      parameter: AutomationParameter;
+      points: readonly { beat: number; value: number }[];
+    }
+  | { type: "automation-remove"; parameter: AutomationParameter; beat: number };
+
+export function parseLane(name: string): AutomationParameter | undefined {
+  const lower = name.toLowerCase();
+  if (lower === "volume" || lower === "vol") return "volume";
+  if (lower === "pan") return "pan";
+  return parseEffectLane(lower);
+}
+
+const NUMBER = /^-?\d+(?:\.\d+)?$/;
+
+export function parseEditCommand(prompt: string): EditCommand | undefined {
+  const text = prompt.trim().replace(/\s+/g, " ");
+  if (text.length > 1_024) return undefined;
+  const name = text.match(/^track name (.+)$/i);
+  if (name) {
+    const value = name[1]!.trim();
+    return value.length > 0 && value.length <= SCORE_LIMITS.maxNameLength
+      ? { type: "track-name", name: value }
+      : undefined;
+  }
+  const meter = text.match(/^meter (\d+)$/i);
+  if (meter) {
+    const beatsPerBar = Number(meter[1]);
+    return beatsPerBar >= 1 && beatsPerBar <= SCORE_LIMITS.maxBeatsPerBar
+      ? { type: "meter", beatsPerBar }
+      : undefined;
+  }
+  const points = text.match(/^automate ([a-z-]+) points((?: \S+)+)$/i);
+  if (points) {
+    const parameter = parseLane(points[1]!);
+    if (!parameter) return undefined;
+    const { min, max } = AUTOMATION_LANES[parameter];
+    const parsed: { beat: number; value: number }[] = [];
+    for (const pair of points[2]!.trim().split(" ")) {
+      const [beatText, valueText, extra] = pair.split(":");
+      if (extra !== undefined || !beatText || !valueText) return undefined;
+      if (!NUMBER.test(beatText) || !NUMBER.test(valueText)) return undefined;
+      const beat = Number(beatText);
+      const value = Number(valueText);
+      if (beat > SCORE_LIMITS.maxTick) return undefined;
+      if (value < min || value > max) return undefined;
+      parsed.push({ beat, value });
+    }
+    if (parsed.length === 0 || parsed.length > SCORE_LIMITS.maxAutomationPoints)
+      return undefined;
+    return { type: "automation-points", parameter, points: parsed };
+  }
+  const remove = text.match(/^automate ([a-z-]+) remove (\d+(?:\.\d+)?)$/i);
+  if (remove) {
+    const parameter = parseLane(remove[1]!);
+    return parameter
+      ? { type: "automation-remove", parameter, beat: Number(remove[2]) }
+      : undefined;
+  }
+  return undefined;
+}
+
+export type EditResult = Readonly<{
+  ok: boolean;
+  message: string;
+  next?: TrackScore;
+  kind?: string;
+  payload?: Record<string, unknown>;
+}>;
+
+/** Apply `command` to `trackId` as one ScoreOperation. */
+export function applyEditCommand(
+  score: TrackScore,
+  trackId: string,
+  command: EditCommand,
+): EditResult {
+  const track = score.tracks.find((candidate) => candidate.id === trackId);
+  if (command.type === "meter") {
+    const operation: ScoreOperation = {
+      type: "setMeter",
+      beatsPerBar: command.beatsPerBar,
+    };
+    return {
+      ok: true,
+      message: `meter · ${command.beatsPerBar}/4`,
+      next: applyScoreOperation(score, operation),
+      kind: "score.meter",
+      payload: { beatsPerBar: command.beatsPerBar },
+    };
+  }
+  if (!track) return { ok: false, message: `no track ${trackId}` };
+  if (command.type === "track-name") {
+    const patch = { name: command.name };
+    return {
+      ok: true,
+      message: `track name · ${command.name}`,
+      next: applyScoreOperation(score, {
+        type: "updateTrack",
+        trackId,
+        patch,
+      }),
+      kind: "score.track",
+      payload: { trackId, patch },
+    };
+  }
+  const field = AUTOMATION_LANES[command.parameter].field;
+  const current: readonly AutomationPoint[] = track[field] ?? [];
+  let points: AutomationPoint[];
+  if (command.type === "automation-points") {
+    const byTick = new Map(current.map((point) => [point.tick, point]));
+    for (const point of command.points) {
+      const tick = Math.max(0, Math.round(point.beat * score.ticksPerBeat));
+      byTick.set(tick, { tick, value: point.value });
+    }
+    points = [...byTick.values()].sort((left, right) => left.tick - right.tick);
+    if (points.length > SCORE_LIMITS.maxAutomationPoints)
+      return {
+        ok: false,
+        message: `${command.parameter} automation holds ${SCORE_LIMITS.maxAutomationPoints} points`,
+      };
+  } else {
+    const tick = Math.round(command.beat * score.ticksPerBeat);
+    points = current.filter((point) => point.tick !== tick);
+    if (points.length === current.length)
+      return {
+        ok: false,
+        message: `no ${command.parameter} point at beat ${command.beat}`,
+      };
+  }
+  return {
+    ok: true,
+    message: `automation · ${command.parameter} ${points.length} point${points.length === 1 ? "" : "s"}`,
+    next: applyScoreOperation(score, {
+      type: "setAutomation",
+      trackId,
+      parameter: command.parameter,
+      points,
+    }),
+    kind: "score.automation",
+    payload: { trackId, parameter: command.parameter, points },
+  };
+}

package/src/commands/help.ts

@@ -0,0 +1,247 @@
+/**
+ * The command reference, in one place: `/help` renders it in the overlay,
+ * `dawg --help` prints it, and the docs mirror it. Music words are bare;
+ * app commands take a slash (bare aliases keep working but are listed once,
+ * in their canonical form).
+ */
+
+export type HelpGroup = "music" | "session" | "window" | "keys";
+
+export type HelpEntry = Readonly<{
+  /** Canonical form, e.g. `pan <-1..1>`. */
+  command: string;
+  /** What it does, short enough for one overlay row. */
+  summary: string;
+}>;
+
+export type HelpSection = Readonly<{
+  group: HelpGroup;
+  entries: readonly HelpEntry[];
+}>;
+
+export const HELP_SECTIONS: readonly HelpSection[] = [
+  {
+    group: "music",
+    entries: [
+      { command: "play", summary: "start the transport" },
+      { command: "pause", summary: "stop the transport" },
+      { command: "tempo <bpm>", summary: "20–300 BPM" },
+      { command: "add <note> at <beat> [for <beats>]", summary: "add C4 at 0" },
+      { command: "remove <id>", summary: "delete a note" },
+      { command: "move <id> to <beat>", summary: "shift a note" },
+      { command: "length <id> <beats>", summary: "resize a note" },
+      { command: "velocity <id> <0..1>", summary: "note loudness" },
+      { command: "bars <count>", summary: "loop length, 1–256" },
+      { command: "extend <count> bars", summary: "lengthen the loop" },
+      {
+        command: "instrument <name>",
+        summary: "sine piano pluck bass saw square triangle kit",
+      },
+      { command: "volume <0..1>", summary: "track level" },
+      { command: "pan <-1..1>", summary: "left … right" },
+      { command: "mute", summary: "silence this track" },
+      { command: "unmute", summary: "hear it again" },
+      { command: "solo", summary: "only this track" },
+      { command: "unsolo", summary: "every track again" },
+      { command: "clear", summary: "remove this track's notes" },
+      { command: "filter <hz> [res]", summary: "low-pass · filter off" },
+      { command: "delay <beats> [fb] [mix]", summary: "ping-pong · delay off" },
+      { command: "reverb <mix> [size]", summary: "room · reverb off" },
+      {
+        command: "automate <lane> at <beat> <value>",
+        summary: "volume pan filter resonance delay-feedback delay-mix",
+      },
+      {
+        command: "automate <lane> points <b:v>...",
+        summary: "several points · automate pan points 0:-1 4:1",
+      },
+      {
+        command: "automate <lane> remove <beat>",
+        summary: "drop one point",
+      },
+      { command: "clear [<lane>] automation", summary: "drop a lane's points" },
+      { command: "track name <text>", summary: "rename this track" },
+      { command: "meter <1..16>", summary: "beats per bar" },
+      {
+        command: "hit <voice> at <beat>",
+        summary: "kit tracks · hit kick at 0",
+      },
+      {
+        command: "pattern <voice> <beats...> | every <step>",
+        summary: "pattern kick every 1",
+      },
+      { command: "clear <voice>", summary: "remove one drum voice" },
+      { command: "undo", summary: "step back · Ctrl-Z" },
+      { command: "redo", summary: "step forward · Ctrl-Y" },
+    ],
+  },
+  {
+    group: "session",
+    entries: [
+      { command: "/sessions", summary: "list sessions in this workspace" },
+      { command: "/resume [<n>|<name>|<id>]", summary: "switch session" },
+      { command: "/rename <name>|--auto", summary: "name this session" },
+      { command: "/fork [<name>]", summary: "copy into a new session" },
+      { command: "/status", summary: "name · revision · digest · storage" },
+      { command: "/export <file>", summary: "write track.loop/v1 JSON" },
+      { command: "/import <file>", summary: "replace the score from a file" },
+      {
+        command: "/sample [<path> [as <voice>]]",
+        summary: "add a sample voice · list voices",
+      },
+    ],
+  },
+  {
+    group: "window",
+    entries: [
+      {
+        command: "/track <name>",
+        summary: "focus a track, creating it if new",
+      },
+      { command: "/tracks", summary: "list tracks" },
+      { command: "/view focus|all", summary: "one track or every track" },
+      { command: "/transcript", summary: "scrollable log · Ctrl-O" },
+      { command: "/theme default|high-contrast|mono", summary: "colors" },
+      { command: "/motion on|off", summary: "animation" },
+      { command: "/model [alias]", summary: "pick a model · cost per prompt" },
+      {
+        command: "/login [gateway|openrouter|codex|claude]",
+        summary: "sign in to a provider",
+      },
+      {
+        command: "/logout [provider]",
+        summary: "forget keys and the saved choice",
+      },
+      { command: "/auth [--check]", summary: "provider and audio status" },
+      { command: "/play [on|off]", summary: "keyboard play mode · Ctrl-P" },
+      {
+        command: "/menu [section]",
+        summary: "edit by hand · Ctrl-K · track effects automation …",
+      },
+      {
+        command: "/click on|off|<volume>",
+        summary: "metronome · /count-in 0-2 · /grid 1/16",
+      },
+      { command: "/help", summary: "this list · ?" },
+    ],
+  },
+  {
+    group: "keys",
+    entries: [
+      { command: "Enter", summary: "submit" },
+      { command: "Shift-Enter", summary: "newline" },
+      { command: "Alt-Enter", summary: "queue the request" },
+      { command: "Ctrl-Q", summary: "toggle queue mode" },
+      { command: "Ctrl-Z / Ctrl-Y", summary: "undo / redo" },
+      { command: "Ctrl-O", summary: "transcript" },
+      { command: "Esc", summary: "cancel the agent · close an overlay" },
+      { command: "Space", summary: "play/pause on an empty prompt" },
+      {
+        command: "Ctrl-P",
+        summary: "play mode: A–' W–P keys · Z/X octave · R rec · M click",
+      },
+      {
+        command: "Ctrl-K",
+        summary: "menu: ↑↓/jk move · enter · ←→/+- nudge · / filter",
+      },
+      { command: "Ctrl-C", summary: "exit" },
+    ],
+  },
+];
+
+/** Overlay rows: a heading per group, then `command  summary` lines. */
+export function helpLines(width = 80): string[] {
+  const lines: string[] = [];
+  const column = Math.min(
+    40,
+    Math.max(
+      ...HELP_SECTIONS.flatMap((s) => s.entries.map((e) => e.command.length)),
+    ) + 2,
+  );
+  for (const section of HELP_SECTIONS) {
+    if (lines.length > 0) lines.push("");
+    lines.push(`── ${section.group}`);
+    for (const entry of section.entries) {
+      const pad = Math.max(1, column - entry.command.length);
+      lines.push(
+        `${entry.command}${" ".repeat(pad)}${entry.summary}`.slice(0, width),
+      );
+    }
+  }
+  return lines;
+}
+
+/** The `Commands:` block of `dawg --help`. */
+export function helpText(): string {
+  return HELP_SECTIONS.filter((section) => section.group !== "keys")
+    .map(
+      (section) =>
+        `${section.group}:\n${section.entries
+          .map((entry) => `  ${entry.command}`)
+          .join("\n")}`,
+    )
+    .join("\n");
+}
+
+/** Usage for a known verb, shown instead of sending a near-miss to the agent. */
+const USAGE: Readonly<Record<string, string>> = {
+  click: "/click on|off|<volume> · /click 50%",
+  "count-in": "/count-in 0|1|2",
+  grid: "/grid 1/4|1/8|1/8T|1/16|1/16T|1/32",
+  tempo: "tempo takes 20…300 · tempo 120",
+  bpm: "tempo takes 20…300 · tempo 120",
+  add: "add <note> at <beat> [for <beats>] · add C4 at 0",
+  put: "add <note> at <beat> [for <beats>] · add C4 at 0",
+  remove: "remove <id> · ids show in the transcript",
+  delete: "remove <id> · ids show in the transcript",
+  move: "move <id> to <beat>",
+  length: "length <id> <beats>",
+  velocity: "velocity <id> <0..1>",
+  vel: "velocity <id> <0..1>",
+  bars: "bars takes 1…256 · bars 8",
+  extend: "extend <count> bars · extend 4 bars",
+  instrument:
+    "instrument <name> · sine piano pluck bass saw square triangle kit",
+  volume: "volume takes 0…1 · volume 0.8",
+  vol: "volume takes 0…1 · volume 0.8",
+  pan: "pan takes -1…1 · pan -0.5",
+  filter: "filter <hz> [res] · filter 800 0.3 · filter off",
+  delay: "delay <beats> [fb] [mix] · delay 0.75 0.4 0.3 · delay off",
+  reverb: "reverb <mix> [size] · reverb 0.3 0.6 · reverb off",
+  automate: "automate <lane> at <beat> <value> · automate volume at 0 0.5",
+  automation: "automate <lane> at <beat> <value> · automate volume at 0 0.5",
+  hit: "hit <voice> at <beat> · hit kick at 0",
+  pattern: "pattern <voice> <beats...> | every <step> · pattern kick every 1",
+  clear: "clear · clear <voice> · clear [<lane>] automation",
+  track: "/track <name> · /track drums",
+  tracks: "/tracks",
+  sessions: "/sessions",
+  resume: "/resume [<n>|<name>|<id>]",
+  rename: "/rename <name> | --auto",
+  fork: "/fork [<name>]",
+  status: "/status",
+  export: "/export <file> · /export loop.track.json",
+  import: "/import <file> · /import loop.track.json",
+  sample: "/sample <path> [as <voice>] · /sample kick.wav as kick",
+  samples: "/sample · lists the focused track's voices",
+  view: "/view focus | all",
+  transcript: "/transcript",
+  log: "/transcript",
+  theme: "/theme default | high-contrast | mono",
+  motion: "/motion on | off",
+  model: "/model [alias | vendor/model]",
+  login: "/login [gateway | openrouter | codex | claude]",
+  logout: "/logout [provider]",
+  auth: "/auth [--check]",
+  help: "/help",
+};
+
+/**
+ * A usage hint when `command` starts with a known verb but did not parse
+ * (`pan 3`, `volume 2`, `add H4 at 0`, `/export` with no file); undefined for
+ * free text that should go to the agent.
+ */
+export function usageHint(command: string): string | undefined {
+  const verb = command.trim().toLowerCase().replace(/^\//, "").split(/\s+/)[0];
+  return verb ? USAGE[verb] : undefined;
+}

package/src/commands/history.ts

@@ -1,22 +1,32 @@
 /**
  * Undo/redo over the shared session event log.
  *
- * Every score edit records `before`, the composition it replaced. Undo and
- * redo append ordinary events (`score.undo` / `score.redo`) whose `before` is
- * the composition they replaced, so history is linear, shared by every
- * window, and survives restarts. Replaying the log rebuilds two stacks:
+ * Every event carries a `rewind` (see `src/session/delta.ts`): how to turn
+ * the composition it produced back into the one it replaced. Undo and redo
+ * append ordinary events (`score.undo` / `score.redo`), so history is linear,
+ * shared by every window, and survives restarts. Replaying the log rebuilds
+ * two stacks over the events that changed the composition:
  *
  *   edit  -> push onto undo, clear redo
  *   undo  -> pop undo, push the undo event onto redo
  *   redo  -> pop redo, push the redo event onto undo
  *
- * Undoing restores the top undo entry's `before`; redoing restores the top
- * redo entry's `before` (the composition the undo replaced).
+ * Undoing restores the composition before the top undo entry; redoing
+ * restores the composition before the top redo entry (the one the undo
+ * replaced). Both are recovered by rewinding the current composition through
+ * every newer event. Events whose rewind was compacted away, and events that
+ * did not change the composition (transport), take no part.
  */
+import {
+  isIdentityRewind,
+  rewindComposition,
+  type Rewind,
+} from "../session/delta.ts";
+
 export type HistoryEvent = Readonly<{
   revision: number;
   kind: string;
-  payload: unknown;
+  rewind?: Rewind | undefined;
 }>;
 
 export type HistoryTarget = Readonly<{
@@ -30,27 +40,30 @@ export const UNDO_KIND = "score.undo";
 export const REDO_KIND = "score.redo";
 
 export function historyTarget(
+  composition: unknown,
   events: readonly HistoryEvent[],
   direction: "undo" | "redo",
 ): HistoryTarget | undefined {
-  const undo: HistoryEvent[] = [];
-  const redo: HistoryEvent[] = [];
-  for (const event of events) {
-    if (!hasBefore(event.payload)) continue;
+  const undo: number[] = [];
+  const redo: number[] = [];
+  events.forEach((event, index) => {
+    if (!changesComposition(event)) return;
     if (event.kind === UNDO_KIND) {
-      if (undo.pop()) redo.push(event);
+      if (undo.pop() !== undefined) redo.push(index);
     } else if (event.kind === REDO_KIND) {
-      if (redo.pop()) undo.push(event);
+      if (redo.pop() !== undefined) undo.push(index);
     } else {
-      undo.push(event);
+      undo.push(index);
       redo.length = 0;
     }
-  }
+  });
   const top = (direction === "undo" ? undo : redo).at(-1);
-  if (!top || !hasBefore(top.payload)) return undefined;
-  return { revision: top.revision, composition: top.payload.before };
+  if (top === undefined) return undefined;
+  const restored = rewindComposition(composition, events, top);
+  if (restored === undefined) return undefined;
+  return { revision: events[top]!.revision, composition: restored };
 }
 
-function hasBefore(payload: unknown): payload is { before: unknown } {
-  return typeof payload === "object" && payload !== null && "before" in payload;
+function changesComposition(event: HistoryEvent): boolean {
+  return event.rewind !== undefined && !isIdentityRewind(event.rewind);
 }

package/src/commands/music.ts

@@ -102,6 +102,8 @@ export function parseEffectLane(
 }
 
 export type MusicResult = Readonly<{
+  /** `true` when the command applied; `false` carries a failure message. */
+  ok: boolean;
   message: string;
   next?: TrackScore;
   kind?: string;
@@ -264,11 +266,12 @@ export function applyMusicCommand(
   newId: (index: number) => string,
 ): MusicResult {
   const track = score.tracks.find((candidate) => candidate.id === trackId);
-  if (!track) return { message: `no track · ${trackId}` };
+  if (!track) return { ok: false, message: `no track · ${trackId}` };
 
   if (command.type === "solo") {
     const next = updateTrack(score, trackId, { solo: command.solo });
     return {
+      ok: true,
       message: `${command.solo ? "solo" : "unsolo"} · ${trackId}`,
       next,
       kind: "score.track",
@@ -281,6 +284,7 @@ export function applyMusicCommand(
         ? { cutoff: command.cutoff, resonance: command.resonance }
         : null;
     return {
+      ok: true,
       message: filter
         ? `filter · ${filter.cutoff} Hz res ${filter.resonance}`
         : "filter · off",
@@ -295,6 +299,7 @@ export function applyMusicCommand(
         ? { beats: command.beats, feedback: command.feedback, mix: command.mix }
         : null;
     return {
+      ok: true,
       message: delay
         ? `delay · ${delay.beats} beats fb ${delay.feedback} mix ${delay.mix}`
         : "delay · off",
@@ -309,6 +314,7 @@ export function applyMusicCommand(
         ? { mix: command.mix, size: command.size }
         : null;
     return {
+      ok: true,
       message: reverb
         ? `reverb · mix ${reverb.mix} size ${reverb.size}`
         : "reverb · off",
@@ -334,9 +340,10 @@ export function applyMusicCommand(
       merged.set(tick, { tick, value: command.value });
       points = [...merged.values()].sort((a, b) => a.tick - b.tick);
       if (points.length > SCORE_LIMITS.maxAutomationPoints)
-        return { message: `${parameter} automation is full` };
+        return { ok: false, message: `${parameter} automation is full` };
     }
     return {
+      ok: true,
       message: `automation · ${parameter} ${points.length} point${points.length === 1 ? "" : "s"}`,
       next: setTrackAutomation(score, trackId, parameter, points),
       kind: "score.automation",
@@ -345,7 +352,10 @@ export function applyMusicCommand(
   }
 
   if (!isDrumInstrument(track.instrument))
-    return { message: `${trackId} is not a drum track · try instrument kit` };
+    return {
+      ok: false,
+      message: `${trackId} is not a drum track · try instrument kit`,
+    };
 
   if (command.type === "drum-clear") {
     const removed = score.notes.filter(
@@ -353,12 +363,14 @@ export function applyMusicCommand(
         note.trackId === trackId &&
         drumVoiceForPitch(note.pitch) === command.voice,
     );
-    if (removed.length === 0) return { message: `no ${command.voice} hits` };
+    if (removed.length === 0)
+      return { ok: false, message: `no ${command.voice} hits` };
     const next = createScore({
       ...score.toJSON(),
       notes: score.notes.filter((note) => !removed.includes(note)),
     });
     return {
+      ok: true,
       message: `cleared ${removed.length} ${command.voice} hit${removed.length === 1 ? "" : "s"}`,
       next,
       kind: "score.drums",
@@ -371,7 +383,7 @@ export function applyMusicCommand(
       ? command.beats
       : everyBeats(command.from, command.step, score.bars * score.beatsPerBar);
   if (beats.length > MAX_PATTERN_HITS)
-    return { message: `pattern exceeds ${MAX_PATTERN_HITS} hits` };
+    return { ok: false, message: `pattern exceeds ${MAX_PATTERN_HITS} hits` };
   const pitch = drumVoicePitch(command.voice);
   const existing = new Set(
     score.notes
@@ -393,14 +405,19 @@ export function applyMusicCommand(
       velocity: command.velocity,
     });
   }
-  if (hits.length === 0) return { message: `${command.voice} already there` };
+  if (hits.length === 0)
+    return { ok: false, message: `${command.voice} already there` };
   if (score.notes.length + hits.length > SCORE_LIMITS.maxNotes)
-    return { message: `score is full (${SCORE_LIMITS.maxNotes} notes)` };
+    return {
+      ok: false,
+      message: `score is full (${SCORE_LIMITS.maxNotes} notes)`,
+    };
   const next = createScore({
     ...score.toJSON(),
     notes: [...score.notes, ...hits],
   });
   return {
+    ok: true,
     message: `+${hits.length} ${command.voice} hit${hits.length === 1 ? "" : "s"}`,
     next,
     kind: "score.drums",