@hraness/dawg 0.7.0 → 0.8.0

package/src/commands/help.ts

@@ -382,6 +382,14 @@ export const HELP_SECTIONS: readonly HelpSection[] = [
     entries: [
       { command: "volume <0..1>", summary: "track level" },
       { command: "pan <-1..1>", summary: "left … right" },
+      {
+        command: "knobs [sound|mix|master|tempo|fx <effect>]",
+        summary: "four knobs ● moves ▲ sizes ■ shapes ◆ level · tab all params",
+      },
+      {
+        command: "mix | volume <track> <0..1> | pan <track> <-1..1>",
+        summary: "the mixer page · volume drums 0.5 sets drums, focus stays",
+      },
       { command: "mute", summary: "silence this track" },
       { command: "unmute", summary: "hear it again" },
       { command: "solo", summary: "only this track" },
@@ -463,8 +471,61 @@ export const HELP_SECTIONS: readonly HelpSection[] = [
         command: "style list|search|info · style blend <a> <b> [w]",
         summary: "the style tree · style search maqam",
       },
-      { command: "bars <count>", summary: "loop length, 1–256" },
-      { command: "extend <count> bars", summary: "lengthen the loop" },
+      { command: "bars <count>", summary: "song length, 1–256" },
+      { command: "extend <count> bars", summary: "lengthen the song" },
+    ],
+  },
+  {
+    group: "arrange · range",
+    entries: [
+      {
+        command: "/tape [on|off]",
+        summary: "every track across the bars · c copy x cut v paste · ctrl-t",
+      },
+      {
+        command: "keys record [replace|off]",
+        summary: "record the loop in play · one undo step a pass · r R on tape",
+      },
+      {
+        command: "loop <a>-<b> | <section> | next | prev | off",
+        summary: "the loop range · loop 5-6 · loop next steps it along",
+      },
+      {
+        command: "copy [<track>|all] <a>-<b> to <bar> [x<N>] [insert|merge]",
+        summary: "copy bass 5-6 to 7 x2 · copy all chorus to 17 insert",
+      },
+      {
+        command: "move [<track>|all] <a>-<b> to <bar> [insert]",
+        summary: "move bass 5-6 to 9 · the source empties",
+      },
+      {
+        command: "clear [<track>|all] <a>-<b>",
+        summary: "clear bass 5-6 · empty bars, the bars stay",
+      },
+      {
+        command: "copy [<track>|all] <a>-<b> · paste [at <bar>] [x<N>]",
+        summary: "the clipboard · copy all 1-4 · paste at 9",
+      },
+      {
+        command: "reverse [<track>|all] <a>-<b>",
+        summary: "mirror the bars · reverse bass 5-6",
+      },
+      {
+        command: "bars insert <n> at <bar> | bars remove <a>-<b>",
+        summary: "shift later music · sections, clips, automation, tempo",
+      },
+      {
+        command: "jump <bar>[.<beat>] | <section>",
+        summary: "move the playhead · jump 5 · jump 5.3 · jump chorus",
+      },
+      {
+        command: "section split <name> at <bar> | join <name>",
+        summary: "section split chorus at 13 · section join chorus",
+      },
+      {
+        command: "form print",
+        summary: "print form to tape · alias of form bake",
+      },
     ],
   },
   {
@@ -508,8 +569,14 @@ export const HELP_SECTIONS: readonly HelpSection[] = [
         command: "calibration [0|1|latest|off]",
         summary: "sound fixes · 1 chokes hats, levels keys · 0 legacy",
       },
-      { command: "undo", summary: "step back · Ctrl-Z" },
-      { command: "redo", summary: "step forward · Ctrl-Y" },
+      {
+        command: "undo [all]",
+        summary: "this pane's last edit · Ctrl-Z · all: anyone's",
+      },
+      {
+        command: "redo [all]",
+        summary: "step forward · Ctrl-Y · all: anyone's",
+      },
       { command: "/status", summary: "name · revision · digest · storage" },
     ],
   },
@@ -540,6 +607,39 @@ export const HELP_SECTIONS: readonly HelpSection[] = [
       { command: "/fork [<name>]", summary: "copy into a new session" },
     ],
   },
+  {
+    group: "project · audio",
+    entries: [
+      {
+        command: "audio",
+        summary: "the output and input in use, and the lists",
+      },
+      {
+        command: "audio out <name|default>",
+        summary: "play through one output · saved on this machine",
+      },
+      {
+        command: "audio in <name|default>",
+        summary: "the input to meter (recording takes comes later)",
+      },
+      { command: "audio test", summary: "a short tone, then the input level" },
+    ],
+  },
+  {
+    group: "project · panes",
+    entries: [
+      { command: "panes", summary: "who has this session open, on what" },
+      {
+        command: "pane <screen> [<track>]",
+        summary: "copies dawg pane … for another terminal",
+      },
+      { command: "pin · unpin", summary: "keep this pane on its track" },
+      {
+        command: "follow [<letter>] · unfollow",
+        summary: "follow another pane's track · follow b",
+      },
+    ],
+  },
   {
     group: "agent",
     entries: [
@@ -599,6 +699,65 @@ export const HELP_GUIDE: readonly HelpSection[] = [
   },
 ];
 
+/**
+ * `/help arrange`: one screen around the range verbs (design F11), each row
+ * a line to type. The full syntax of every arranging command stays in
+ * `/help all` and `/help <command>` (`/help copy`, `/help section`).
+ */
+export const ARRANGE_PAGE: HelpSection = {
+  group: "arrange",
+  entries: [
+    {
+      command: "loop 5-6 · loop chorus",
+      summary: "loop the bars · loop next · loop off",
+    },
+    {
+      command: "copy bass 5-6 to 7",
+      summary: "copy bars · x2 repeats · all = every track",
+    },
+    {
+      command: "move bass 5-6 to 9",
+      summary: "move bars · the source empties",
+    },
+    {
+      command: "clear bass 5-6",
+      summary: "empty bars · reverse bass 5-6 mirrors",
+    },
+    {
+      command: "copy all 1-4 · paste at 9",
+      summary: "the clipboard, for later",
+    },
+    { command: "jump 5 · jump chorus", summary: "move the playhead" },
+    { command: "ctrl-t · tape", summary: "every track across the bars" },
+    {
+      command: "section chorus 9-16",
+      summary: "name bars · section loop chorus",
+    },
+    {
+      command: "form verse verse chorus",
+      summary: "song form · form print lays it out",
+    },
+    {
+      command: "build · drop · fill chorus",
+      summary: "riser · pre-drop cut · drum fill",
+    },
+    { command: "style deep-house 16", summary: "a whole song in a style" },
+  ],
+};
+
+/**
+ * `/help panes`: several terminals on one session (§12). Its rows are the
+ * `project · panes` reference group under a heading of its own.
+ */
+function panesLines(width: number): string[] {
+  const group = HELP_SECTIONS.find((s) => s.group === "project · panes")!;
+  return [
+    ...sectionLines([{ ...group, group: "panes" }], width),
+    "",
+    truncate("dawg pane tape in another terminal · guide panes", width),
+  ];
+}
+
 /** Topics `/help <topic>` takes, besides `all` (aliases resolve too). */
 export const HELP_TOPICS = TOPICS;
 
@@ -656,6 +815,8 @@ export function topicSections(id: TopicId): readonly HelpSection[] {
 /** One topic's page: its groups, then where else the topic opens. */
 function topicLines(id: TopicId, width: number): string[] {
   if (id === "keys") return [...keysLines(width), ...doors(id, width)];
+  if (id === "arrange")
+    return [...sectionLines([ARRANGE_PAGE], width), ...doors(id, width)];
   return [...sectionLines(topicSections(id), width), ...doors(id, width)];
 }
 
@@ -674,6 +835,7 @@ export function helpTopicLines(
     return helpLines(width);
   if ((TOPICS as readonly string[]).includes(name))
     return topicLines(name as TopicId, width);
+  if (name === "panes" || name === "pane") return panesLines(width);
   const spelled = HELP_COMMAND_ALIASES[name];
   if (spelled) return commandTopic(spelled, width, name);
   const alias = resolveTopic(name);
@@ -865,11 +1027,25 @@ export const USAGE: Readonly<Record<string, string>> = {
   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>",
+  move: "move <id> to <beat> · move [<track>|all] <a>-<b> to <bar> [insert] · move bass 5-6 to 9",
   length: "length <id> <beats>",
   velocity: "velocity <id> <0..1>",
   vel: "velocity <id> <0..1>",
-  bars: "bars takes 1…256 · bars 8",
+  bars: "bars <count> (1…256) | bars insert <n> at <bar> | bars remove <a>-<b> · bars 8 · bars insert 2 at 3",
+  copy: "copy [<track>|all] [<a>-<b>|<section>] [to <bar>] [x<N>] [insert|merge] · copy bass 5-6 to 7 x2",
+  paste:
+    "paste [at <bar>] [x<N>] [insert|merge] · paste at 9 · copy bass 5-6 fills the clipboard",
+  reverse: "reverse [<track>|all] [<a>-<b>|<section>] · reverse bass 5-6",
+  jump: "jump <bar>[.<beat>] | <section> · jump 5 · jump 5.3 · jump chorus",
+  loop: "loop <a>-<b> | <section> | next | prev | off · loop 5-6 · loop chorus · loop off",
+  pane: "pane home|play|tape|sound|menu [<track>] [pin|follow [<letter>]] · pane tape · pane sound bass pin",
+  follow: "follow [<letter>] · follow b · unfollow stops",
+  panes: "panes · who has this session open, on what · pane tape",
+  knobs:
+    "knobs [sound|mix|master|tempo|fx <effect>] · knobs mix · knobs fx reverb",
+  mix: "mix · the mixer page · volume drums 0.5 · pan drums -0.2",
+  audio:
+    "audio [out|in <name|default>] | test · audio out default · audio test",
   extend: "extend <count> bars · extend 4 bars",
   instrument:
     "instrument <name> · sine piano pluck bass sawtooth square triangle wavetable kit · pianos: grand upright felt honkytonk prepared · electric: epiano suitcase dyno wurli clav funkclav · synth: supersaw pulse white pink z_square · voices: vocal aah ooh choir chorale khoomei sygyt kargyraa vocoder…",
@@ -890,7 +1066,8 @@ export const USAGE: Readonly<Record<string, string>> = {
   automation: "automate <lane> at <beat> <value> · automate volume at 0 0.5",
   hit: "hit <drum> at <beat> · hit kick at 0",
   pattern: "pattern <drum> <beats...> | every <step> · pattern kick every 1",
-  clear: "clear · clear <drum> · clear [<lane>] automation",
+  clear:
+    "clear · clear <drum> · clear [<lane>] automation · clear [<track>|all] <a>-<b> · clear bass 5-6",
   track:
     "track <name> · track drums · track rm <name> · track move <name> <position> · track rate <0.125..8>|<a>/<b>|off · track phase <beats> · track loop <beats> · track phasing <beats> [over <beats>]",
   tracks: "tracks",
@@ -977,6 +1154,7 @@ export const USAGE: Readonly<Record<string, string>> = {
     "master <unit> on|off|preset <name>|<param> <value> · master streaming|club|loud · master target -14 · master measure · master off",
   try: "/try <sound command> · /try fx reverb mix 0.6",
   play: "/play [on|off|degrees|in-key|chromatic] · ctrl-p play mode · i toggles degrees",
+  tape: "/tape [on|off] · ctrl-t · every track across the bars · c copy · x cut · v paste · \\ loop",
   meter:
     "meter <1..16> · meter 3 · meter 7/8 [at bar <n>] · meter remove bar <n> · meter clear",
   art: EXPRESSION_USAGE.art,
@@ -990,9 +1168,9 @@ export const USAGE: Readonly<Record<string, string>> = {
   velcurve: EXPRESSION_USAGE.velcurve,
   humanize: EXPRESSION_USAGE.humanize,
   section:
-    "section [mark] <name> <a>-<b> | add [<name>] [<n>] | dup | move <name> to <bar> | rename <name> to <new> | delete | unmark | mute | vary | reset | loop <name>|off | jump <name> · section chorus 9-16",
+    "section [mark] <name> <a>-<b> | add [<name>] [<n>] | dup | move <name> to <bar> | rename <name> to <new> | delete | unmark | mute | vary | reset | loop <name>|off | jump <name> | split <name> at <bar> | join <name> · section chorus 9-16",
   sections: "section · lists sections, the form and the loop",
-  form: "form <section…> | off | bake · form verse verse chorus verse · form verse chorus*2",
+  form: "form <section…> | off | bake (print) · form verse verse chorus verse · form verse chorus*2",
   build:
     "build [into <section> | <section> | <a>-<b>] [<n> bars] [riser] [roll] [sweep] [uplifter] · build into chorus",
   drop: "drop [<section> | at <bar>] [cut <beats>] [no impact] · drop chorus",

package/src/commands/history.ts

@@ -17,7 +17,13 @@
  * every newer event. Events whose rewind was compacted away, and events that
  * did not change the composition (transport), take no part.
  */
-import type { TrackScore } from "../../core/score.ts";
+import { DiffError, diffScores } from "../../core/diff.ts";
+import {
+  scoreFromJSON,
+  type ScoreOperation,
+  type TrackScore,
+} from "../../core/score.ts";
+import { rebaseOperations } from "../session/rebase.ts";
 import { musicalReceipt } from "../session/receipt.ts";
 import {
   isIdentityRewind,
@@ -29,6 +35,9 @@ export type HistoryEvent = Readonly<{
   revision: number;
   kind: string;
   rewind?: Rewind | undefined;
+  payload?: unknown;
+  /** Who wrote it; per-pane undo keys on `clientId` (design §12.6). */
+  actor?: Readonly<{ clientId: string }> | undefined;
 }>;
 
 export type HistoryTarget = Readonly<{
@@ -41,31 +50,133 @@ export type HistoryTarget = Readonly<{
 export const UNDO_KIND = "score.undo";
 export const REDO_KIND = "score.redo";
 
-export function historyTarget(
-  composition: unknown,
+/**
+ * Replays the log into undo and redo stacks of event indexes, over the
+ * events `include` admits. An undo or redo event pops its stack only when
+ * it stepped that stack's top (its payload names the revision); otherwise
+ * it is an ordinary edit there. So a pane's own undo is an edit in the
+ * global history (`undo all` can undo it), and an `undo all` that undid
+ * another pane's edit is an edit in this pane's history. Old events without
+ * the payload revision pop unconditionally, as they always did.
+ */
+function historyStacks(
   events: readonly HistoryEvent[],
-  direction: "undo" | "redo",
-): HistoryTarget | undefined {
+  include: (event: HistoryEvent) => boolean,
+): { undo: number[]; redo: number[] } {
   const undo: number[] = [];
   const redo: number[] = [];
+  const steps = (stack: number[], event: HistoryEvent, key: string) => {
+    const top = stack.at(-1);
+    if (top === undefined) return false;
+    const named = (event.payload as Record<string, unknown> | null)?.[key];
+    return typeof named !== "number" || named === events[top]!.revision;
+  };
   events.forEach((event, index) => {
-    if (!changesComposition(event)) return;
-    if (event.kind === UNDO_KIND) {
-      if (undo.pop() !== undefined) redo.push(index);
-    } else if (event.kind === REDO_KIND) {
-      if (redo.pop() !== undefined) undo.push(index);
+    if (!changesComposition(event) || !include(event)) return;
+    if (event.kind === UNDO_KIND && steps(undo, event, "undoneRevision")) {
+      undo.pop();
+      redo.push(index);
+    } else if (
+      event.kind === REDO_KIND &&
+      steps(redo, event, "redoneRevision")
+    ) {
+      redo.pop();
+      undo.push(index);
     } else {
       undo.push(index);
       redo.length = 0;
     }
   });
-  const top = (direction === "undo" ? undo : redo).at(-1);
+  return { undo, redo };
+}
+
+/** `undo all` / `redo all`: the global history, whoever made each edit. */
+export function historyTarget(
+  composition: unknown,
+  events: readonly HistoryEvent[],
+  direction: "undo" | "redo",
+): HistoryTarget | undefined {
+  const stacks = historyStacks(events, () => true);
+  const top = stacks[direction].at(-1);
   if (top === undefined) return undefined;
   const restored = rewindComposition(composition, events, top);
   if (restored === undefined) return undefined;
   return { revision: events[top]!.revision, composition: restored };
 }
 
+export type PaneStep =
+  | Readonly<{ ok: true; revision: number; next: TrackScore }>
+  | Readonly<{
+      ok: false;
+      revision: number;
+      /** Why the inverse cannot land (rebase reason or session-wide). */
+      reason: string;
+      /** Other clients that changed the composition since, oldest first. */
+      others: readonly string[];
+    }>;
+
+/**
+ * Per-pane undo and redo (design §12.6): the newest edit `clientId` made,
+ * inverted as score operations and rebased onto the current score with the
+ * same touch rules as agent intents. Another pane's later edit to the same
+ * note or track property refuses with a reason; unrelated edits stay.
+ * Undefined when this pane has nothing to step.
+ */
+export function paneHistoryStep(
+  composition: unknown,
+  events: readonly HistoryEvent[],
+  direction: "undo" | "redo",
+  clientId: string,
+): PaneStep | undefined {
+  const stacks = historyStacks(
+    events,
+    (event) => event.actor?.clientId === clientId,
+  );
+  const top = stacks[direction].at(-1);
+  if (top === undefined) return undefined;
+  const revision = events[top]!.revision;
+  const others = [
+    ...new Set(
+      events
+        .slice(top + 1)
+        .filter(
+          (event) =>
+            changesComposition(event) && event.actor?.clientId !== clientId,
+        )
+        .map((event) => event.actor?.clientId ?? ""),
+    ),
+  ];
+  const refuse = (reason: string): PaneStep => ({
+    ok: false,
+    revision,
+    reason,
+    others,
+  });
+  const before = rewindComposition(composition, events, top);
+  const after =
+    top + 1 === events.length
+      ? composition
+      : rewindComposition(composition, events, top + 1);
+  if (before === undefined || after === undefined)
+    return refuse("history was compacted");
+  let operations: readonly ScoreOperation[];
+  let base: TrackScore;
+  let current: TrackScore;
+  try {
+    base = scoreFromJSON(after);
+    current = scoreFromJSON(composition);
+    operations = diffScores(base, scoreFromJSON(before));
+  } catch (error) {
+    if (error instanceof DiffError) return refuse("session-wide");
+    return refuse(error instanceof Error ? error.message : String(error));
+  }
+  if (operations.length === 0) return refuse("session-wide");
+  const result = rebaseOperations(base, current, operations);
+  return result.ok
+    ? { ok: true, revision, next: result.next }
+    : refuse(result.reason);
+}
+
 function changesComposition(event: HistoryEvent): boolean {
   return event.rewind !== undefined && !isIdentityRewind(event.rewind);
 }

package/src/commands/keys.ts

@@ -210,6 +210,23 @@ export function keysRowMismatch(
   return `${instrument} has no ${wrong.join(" ")} (${familiesReading(wrong[0]!).join("/")} row); its parameters: ${rows.join(" ")}`;
 }
 
+/**
+ * `keys record` / `keys record replace` / `keys record off` (op1-ux §4.7):
+ * arm recording in PLAY, overdub or replace each pass. Not a score write
+ * of its own; each pass the take commits is.
+ */
+export function parseRecordCommand(
+  prompt: string,
+): "overdub" | "replace" | "off" | undefined {
+  const match = prompt
+    .trim()
+    .match(/^\/?keys\s+record(?:\s+(overdub|replace|off))?$/i);
+  if (!match) return undefined;
+  return (match[1]?.toLowerCase() ?? "overdub") as
+    "overdub" | "replace" | "off";
+}
+
+/** Parse one keys / piano / organ command. */
 export function parseKeysCommand(prompt: string): KeysCommand | undefined {
   if (prompt.length > 1_024) return undefined;
   let words = prompt.trim().toLowerCase().split(/\s+/);

package/src/commands/parses.ts

@@ -7,6 +7,7 @@
 import type { TrackScore } from "../../core/score.ts";
 import { parsePrompt } from "../agent/ops.ts";
 import { parseSectionCommand } from "./arrange.ts";
+import { parseRangeCommand } from "./range.ts";
 import { parseAutotuneCommand } from "./autotune.ts";
 import { parseClipCommand, parseLyricsCommand } from "./clips.ts";
 import { parsePatternCommand } from "./drums.ts";
@@ -17,7 +18,7 @@ import { parseFitCommand } from "./fit.ts";
 import { parseFormantCommand, parseVowelCommand } from "./formant.ts";
 import { parseFxCommand } from "./fx.ts";
 import { parseGranularCommand } from "./granular.ts";
-import { parseKeysCommand } from "./keys.ts";
+import { parseKeysCommand, parseRecordCommand } from "./keys.ts";
 import { parseMasterCommand } from "./master.ts";
 import { parseModalCommand } from "./modal.ts";
 import { parseMusicCommand } from "./music.ts";
@@ -85,6 +86,9 @@ export function commandParses(text: string, score: TrackScore): boolean {
 
 function parsers(score: TrackScore): ((text: string) => unknown)[] {
   return [
+    function parseRange(value: string) {
+      return parseRangeCommand(value, score);
+    },
     parsePrompt,
     parseMusicCommand,
     parseEditCommand,
@@ -93,6 +97,7 @@ function parsers(score: TrackScore): ((text: string) => unknown)[] {
     parseSynthCommand,
     parseStringCommand,
     parseGranularCommand,
+    parseRecordCommand,
     parseKeysCommand,
     parseExpressionCommand,
     parseMasterCommand,