@hraness/dawg 0.6.1 → 0.8.0

package/src/commands/history.ts

@@ -17,6 +17,14 @@
  * every newer event. Events whose rewind was compacted away, and events that
  * did not change the composition (transport), take no part.
  */
+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,
   rewindComposition,
@@ -27,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<{
@@ -39,31 +50,149 @@ 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);
 }
+
+/**
+ * The card after undo or redo names the musical change it made
+ * (`undid · −1 note on bass (C3)`, `redid · 96 BPM`), and falls back to the
+ * revision when the change is not in the music (a rename, a section label).
+ */
+export function historyReceipt(
+  direction: "undo" | "redo",
+  before: TrackScore,
+  after: TrackScore,
+  revision: number,
+): string {
+  const verb = direction === "undo" ? "undid" : "redid";
+  const change = musicalReceipt(before, after);
+  return change ? `${verb} · ${change}` : `${verb} · rev ${revision}`;
+}

package/src/commands/keys.ts

@@ -1,7 +1,7 @@
 /**
- * The modelled piano commands (0.6 keys lane, `core/keys.ts`):
+ * The modeled piano commands (0.6 keys lane, `core/keys.ts`):
  *
- *   piano                         the focused track becomes the modelled grand
+ *   piano                         the focused track becomes the modeled grand
  *   piano <preset>                grand ballad upright felt lofi honkytonk prepared
  *   grand | upright | felt …      the same, by the preset word alone
  *   keys                          list this track's piano settings
@@ -210,11 +210,28 @@ 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+/);
   // `instrument piano` / `sound grand`: the generic instrument command with
-  // a keys word is a new write, so it stores the modelled piano.
+  // a keys word is a new write, so it stores the modeled piano.
   if (
     words.length === 2 &&
     ["instrument", "sound", "voice"].includes(words[0]!) &&
@@ -455,8 +472,8 @@ export function applyKeysCommand(
   const piano = isKeysFamily(track.instrument);
   const elsewhere =
     track.instrument === "organ"
-      ? `keys · ${trackId} is the legacy organ; type tonewheel (or combo, pipe) for drawbars and rotary, or piano for the modelled piano`
-      : `keys · ${trackId} is ${track.instrument}; type piano first (${PIANO_FAMILIES.join(" ")}), ${ELECTRIC_FAMILIES.join(" ")} or ${ORGAN_FAMILIES.join(" ")} for modelled keys`;
+      ? `keys · ${trackId} is the legacy organ; type tonewheel (or combo, pipe) for drawbars and rotary, or piano for the modeled piano`
+      : `keys · ${trackId} is ${track.instrument}; type piano first (${PIANO_FAMILIES.join(" ")}), ${ELECTRIC_FAMILIES.join(" ")} or ${ORGAN_FAMILIES.join(" ")} for modeled keys`;
   if (command.type === "keys-list")
     return {
       ok: true,
@@ -483,7 +500,7 @@ export function applyKeysCommand(
   if (track.sampler && command.type !== "keys-preset")
     return {
       ok: false,
-      message: `keys · ${trackId} is a sampler track; type piano to make it a modelled piano`,
+      message: `keys · ${trackId} is a sampler track; type piano to make it a modeled piano`,
     };
   let patch: TrackPatch;
   if (command.type === "keys-preset") {
@@ -516,7 +533,7 @@ export function applyKeysCommand(
     return {
       ok: false,
       message: keysSynth
-        ? `keys · keys shapes the modelled piano; ${trackId} is the keys synth: use synth ${first ?? "decay"} …, or type piano`
+        ? `keys · keys shapes the modeled piano; ${trackId} is the keys synth: use synth ${first ?? "decay"} …, or type piano`
         : elsewhere,
     };
   } else if (command.type === "keys-rotary-at") {
@@ -605,7 +622,7 @@ export function applyKeysCommand(
 
 /**
  * The fields a new track named after a piano word starts with
- * (`/track piano` → the modelled grand); empty for any other name. `lofi`
+ * (`/track piano` → the modeled grand); empty for any other name. `lofi`
  * is left out: it also names a drum kit and pattern.
  */
 export function newPianoTrack(name: string): {

package/src/commands/modal.ts

@@ -86,7 +86,7 @@ export function parseModalCommand(prompt: string): ModalCommand | undefined {
   if (rest.length === 1 && rest[0] === "gamelan")
     return {
       type: "modal-hint",
-      message: `gamelan · ${GAMELAN_PRESETS.join(" ")} · modal gangsa to start · pair two tracks with modal pair <track> · tuning slendro or pelog · ctrl-k Sound › browse sounds › Mallets and bells › Gamelan`,
+      message: `gamelan · ${GAMELAN_PRESETS.join(" ")} · modal gangsa to start · pair two tracks with modal pair <track> · tuning slendro or pelog · ctrl-k Sound › instruments › mallets › gamelan`,
     };
   if (rest[0] === "preset") {
     const preset = rest.length === 2 ? modalPresetFor(rest[1]!) : undefined;

package/src/commands/music.ts

@@ -83,7 +83,7 @@ export type EffectAutomationParameter = Exclude<
   "volume" | "pan"
 >;
 
-const LANE_ALIASES: Readonly<Record<string, EffectAutomationParameter>> =
+export const LANE_ALIASES: Readonly<Record<string, EffectAutomationParameter>> =
   Object.freeze({
     filter: "filter",
     cutoff: "filter",

package/src/commands/nearest.ts

@@ -0,0 +1,53 @@
+/**
+ * One vocabulary matcher for every "did you mean" in dawg: instruments,
+ * effects, styles, kits, rigs, sections, presets, params and verbs.
+ */
+
+/**
+ * Optimal-string-alignment distance: insert, delete, substitute, and an
+ * adjacent swap (`/hlep` → `/help`) each cost one edit.
+ */
+export function editDistance(a: string, b: string): number {
+  let before: number[] = [];
+  let previous = Array.from({ length: b.length + 1 }, (_, index) => index);
+  for (let i = 1; i <= a.length; i += 1) {
+    const row = [i];
+    for (let j = 1; j <= b.length; j += 1) {
+      const cost = a[i - 1] === b[j - 1] ? 0 : 1;
+      let best = Math.min(
+        previous[j]! + 1,
+        row[j - 1]! + 1,
+        previous[j - 1]! + cost,
+      );
+      if (i > 1 && j > 1 && a[i - 1] === b[j - 2] && a[i - 2] === b[j - 1])
+        best = Math.min(best, before[j - 2]! + 1);
+      row.push(best);
+    }
+    before = previous;
+    previous = row;
+  }
+  return previous[b.length]!;
+}
+
+/**
+ * The word in `vocabulary` nearest to `word` (edit distance, adjacent swaps
+ * cost one), within one edit for words of four letters or fewer and two
+ * otherwise; undefined when nothing is that close or `word` is itself in it.
+ */
+export function nearest(
+  word: string,
+  vocabulary: Iterable<string>,
+): string | undefined {
+  const typed = word.trim().toLowerCase();
+  if (!typed) return undefined;
+  const limit = typed.length <= 4 ? 1 : 2;
+  let best: { word: string; distance: number } | undefined;
+  for (const candidate of vocabulary) {
+    const lower = candidate.toLowerCase();
+    if (lower === typed) return undefined;
+    const distance = editDistance(typed, lower);
+    if (distance <= limit && (!best || distance < best.distance))
+      best = { word: candidate, distance };
+  }
+  return best?.word;
+}

package/src/commands/pack.ts

@@ -124,10 +124,10 @@ export type KitCommand =
 
 /** `/kit [bank]` (default kit) and `/kit list`; undefined for other commands. */
 export function parseKitCommand(command: string): KitCommand | undefined {
-  const match = command.trim().match(/^\/kit(?:\s+(\S+))?\s*$/i);
+  const match = command.trim().match(/^\/?kits?(?:\s+(\S+))?\s*$/i);
   if (!match) return undefined;
   const bank = match[1];
-  if (bank && /^(list|ls)$/i.test(bank)) return { kind: "list" };
+  if (bank && /^(list|ls|presets)$/i.test(bank)) return { kind: "list" };
   return { kind: "set", bank: bank ?? DEFAULT_KIT };
 }
 
@@ -389,6 +389,8 @@ export function kitListLines(aliases: BankAliases): string[] {
 export type CacheReport = Readonly<{
   packs: CacheUsage & { max: number };
   assets: CacheUsage & { max: number };
+  /** Pitch curves in `.dawg/analysis` (0.7); omitted when empty. */
+  analysis?: CacheUsage & { max: number };
   freed?: Readonly<{ files: number; bytes: number }>;
 }>;
 
@@ -408,6 +410,11 @@ export function cacheLines(report: CacheReport): string[] {
       : []),
     row("pack downloads", report.packs, "DAWG_PACKS_CACHE_MAX"),
     row("decoded audio (this project)", report.assets, "DAWG_ASSETS_CACHE_MAX"),
+    ...(report.analysis?.files
+      ? [
+          `pitch analysis (this project) · ${formatBytes(report.analysis.bytes)} of ${formatBytes(report.analysis.max)} · ${report.analysis.files} curve${report.analysis.files === 1 ? "" : "s"} · .dawg/analysis, re-tracked on demand`,
+        ]
+      : []),
     "least recently used files go first; this project's sounds are never evicted",
     "evicted sounds re-fetch by their pinned sha256 on next use",
     "/pack cache prune [size] · /pack cache clear",

package/src/commands/param-range.ts

@@ -0,0 +1,56 @@
+/**
+ * `✗ synth lpf 99999 · lpf takes 20…20000 Hz · synth lpf 1200`: the range
+ * card for a synth or effect parameter, built from the same specs that
+ * validate it (core/params), so the card and the check never disagree.
+ */
+import type { ParamSpec } from "../../core/params.ts";
+import { SYNTH_PARAMS, synthParamName } from "../../core/synth.ts";
+import { effectSpec } from "../../core/fx.ts";
+import { parseEffectName, parseParamName } from "./fx.ts";
+import { usageError } from "./grammar.ts";
+
+/** The range card for the first out-of-range number in the line, if any. */
+export function paramRangeError(line: string): string | undefined {
+  const words = line.trim().replace(/^\//, "").split(/\s+/);
+  const verb = words[0]?.toLowerCase();
+  if (verb === "synth")
+    return firstOutOfRange(line, words.slice(1), "synth", (word) => {
+      const name = synthParamName(word);
+      return name ? [name, SYNTH_PARAMS[name]] : undefined;
+    });
+  if (verb === "fx" && words[1]) {
+    const effect = parseEffectName(words[1]);
+    if (!effect) return undefined;
+    const params = effectSpec(effect).params;
+    return firstOutOfRange(line, words.slice(2), `fx ${effect}`, (word) => {
+      const name = parseParamName(effect, word);
+      return name ? [name, params[name]] : undefined;
+    });
+  }
+  return undefined;
+}
+
+function firstOutOfRange(
+  line: string,
+  rest: readonly string[],
+  prefix: string,
+  lookup: (word: string) => [string, ParamSpec | undefined] | undefined,
+): string | undefined {
+  for (let index = 0; index + 1 < rest.length; index += 2) {
+    const found = lookup(rest[index]!);
+    if (!found) continue;
+    const [name, spec] = found;
+    if (spec?.kind !== "number") continue;
+    const value = Number(rest[index + 1]);
+    if (!Number.isFinite(value)) continue;
+    if (value >= spec.min && value <= spec.max) continue;
+    return usageError(line.trim(), {
+      command: name,
+      min: spec.min,
+      max: spec.max,
+      unit: spec.unit ?? "",
+      example: `${prefix} ${name} ${spec.default}`,
+    });
+  }
+  return undefined;
+}

package/src/commands/parses.ts

@@ -0,0 +1,135 @@
+/**
+ * Whether a prompt line is a command the human prompt bar runs locally (no
+ * model call): every command parser the prompt tries, in one list. The TUI
+ * uses it for typo fixes; show-me (src/agent/show-me.ts) uses it in tests to
+ * prove every command it ghost-types is one a human can type.
+ */
+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";
+import { parseProgressionCommand } from "./progression.ts";
+import { parseEditCommand } from "./edit.ts";
+import { parseExpressionCommand } from "./expression.ts";
+import { parseFitCommand } from "./fit.ts";
+import { parseFormantCommand, parseVowelCommand } from "./formant.ts";
+import { parseFxCommand } from "./fx.ts";
+import { parseGranularCommand } from "./granular.ts";
+import { parseKeysCommand, parseRecordCommand } from "./keys.ts";
+import { parseMasterCommand } from "./master.ts";
+import { parseModalCommand } from "./modal.ts";
+import { parseMusicCommand } from "./music.ts";
+import { parseKitCommand, parsePackCommand } from "./pack.ts";
+import { parseResampleCommand } from "./resample.ts";
+import { parseRhythmCommand } from "./rhythm.ts";
+import { parseRigCommand } from "./rig.ts";
+import { parseSampleCommand } from "./sample.ts";
+import { parseShiftCommand } from "./shift.ts";
+import { parseSingCommand } from "./sing.ts";
+import { parseStringCommand } from "./string.ts";
+import { parseGuitarCommand, parseStrumCommand } from "./strum.ts";
+import { parseSynthCommand } from "./synth.ts";
+import { parseTimeCommand } from "./time.ts";
+import { parseTuningCommand } from "./tuning.ts";
+import { parseVocalCommand } from "./vocal.ts";
+import { parseVocoderCommand } from "./vocoder.ts";
+import { parseWavetableCommand } from "./wavetable.ts";
+import { parseWindCommand } from "./wind.ts";
+import {
+  candidates,
+  parseExportCommand,
+  parseLoopCommand,
+  parseTrackEdit,
+} from "./grammar.ts";
+
+/** One parser's reading of a line: its name and what it parsed. */
+export type ParsedCommand = Readonly<{ parser: string; value: unknown }>;
+
+/**
+ * The first parser that takes `text` exactly as typed, with its result
+ * (no grammar rewrites): what the prompt bar would run for this spelling.
+ */
+export function parseExact(
+  text: string,
+  score: TrackScore,
+): ParsedCommand | undefined {
+  for (const parse of parsers(score)) {
+    const value = parse(text);
+    if (value !== undefined)
+      return { parser: parse.name || "anonymous", value };
+  }
+  return undefined;
+}
+
+/**
+ * What `text` runs as: the exact spelling first, then the grammar's other
+ * readings (`/x` ≡ `x`, aliases, remove and list words) in order.
+ */
+export function parseCommand(
+  text: string,
+  score: TrackScore,
+): ParsedCommand | undefined {
+  for (const line of [text, ...candidates(text)]) {
+    const parsed = parseExact(line, score);
+    if (parsed) return parsed;
+  }
+  return undefined;
+}
+
+/** Whether a line runs locally, in any spelling the grammar accepts. */
+export function commandParses(text: string, score: TrackScore): boolean {
+  return parseCommand(text, score) !== undefined;
+}
+
+function parsers(score: TrackScore): ((text: string) => unknown)[] {
+  return [
+    function parseRange(value: string) {
+      return parseRangeCommand(value, score);
+    },
+    parsePrompt,
+    parseMusicCommand,
+    parseEditCommand,
+    parseRhythmCommand,
+    parseFxCommand,
+    parseSynthCommand,
+    parseStringCommand,
+    parseGranularCommand,
+    parseRecordCommand,
+    parseKeysCommand,
+    parseExpressionCommand,
+    parseMasterCommand,
+    function parseSection(value: string) {
+      return parseSectionCommand(value, score);
+    },
+    parsePatternCommand,
+    parseKitCommand,
+    parsePackCommand,
+    parseSampleCommand,
+    parseFitCommand,
+    parseShiftCommand,
+    parseResampleCommand,
+    parseWavetableCommand,
+    parseTimeCommand,
+    parseTuningCommand,
+    parseRigCommand,
+    parseModalCommand,
+    parseGuitarCommand,
+    parseStrumCommand,
+    parseProgressionCommand,
+    parseWindCommand,
+    parseAutotuneCommand,
+    parseSingCommand,
+    parseVocoderCommand,
+    parseVocalCommand,
+    parseFormantCommand,
+    parseVowelCommand,
+    parseClipCommand,
+    parseLyricsCommand,
+    parseExportCommand,
+    parseLoopCommand,
+    parseTrackEdit,
+  ];
+}