@hraness/dawg 0.3.0 → 0.4.0

package/src/commands/help.ts

@@ -35,7 +35,7 @@ export const HELP_SECTIONS: readonly HelpSection[] = [
       { command: "extend <count> bars", summary: "lengthen the loop" },
       {
         command: "instrument <name>",
-        summary: "sine piano pluck bass saw square triangle kit",
+        summary: "sine piano pluck bass saw square triangle wavetable kit",
       },
       { command: "volume <0..1>", summary: "track level" },
       { command: "pan <-1..1>", summary: "left … right" },
@@ -44,12 +44,28 @@ export const HELP_SECTIONS: readonly HelpSection[] = [
       { command: "solo", summary: "only this track" },
       { command: "unsolo", summary: "every track again" },
       { command: "clear", summary: "remove this track's notes" },
+      {
+        command: "wt <table> | wt <0..1> | wt list",
+        summary: "wavetable synth · wt basic · wt wt_digital:2 · wt 0.5",
+      },
+      {
+        command: "wtenv|wtattack|wtdecay|wtrate|wtdepth|warp <n>",
+        summary: "scan the table · warpmode bendp",
+      },
+      {
+        command: "fx <effect> <param> <value> | on | off | preset <name>",
+        summary: "effects · fx delay mix 0.3 · fx reverb on · fx lists them",
+      },
+      {
+        command: "synth <param> <value> | preset <name>",
+        summary: "synth voice · synth lpf 1200 · synth lists every param",
+      },
       { 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",
+        summary: "volume pan filter resonance delay-feedback delay-mix wt",
       },
       {
         command: "automate <lane> points <b:v>...",
@@ -62,6 +78,10 @@ export const HELP_SECTIONS: readonly HelpSection[] = [
       { 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: "key <tonic> <mode> | none",
+        summary: "song key · key A minor · key F# dorian",
+      },
       {
         command: "hit <voice> at <beat>",
         summary: "kit tracks · hit kick at 0",
@@ -71,6 +91,15 @@ export const HELP_SECTIONS: readonly HelpSection[] = [
         summary: "pattern kick every 1",
       },
       { command: "clear <voice>", summary: "remove one drum voice" },
+      {
+        command: "euclid <voice> <pulses> [<steps>] [rotate <n>]",
+        summary: "generated rhythm · euclid hat 7 16 rotate 2",
+      },
+      {
+        command: "euclid <voice> <field> <value> | off | freeze",
+        summary: "repeats pace accent prob swing …",
+      },
+      { command: "grid <voice> <x.X.>", summary: "explicit steps · X accent" },
       { command: "undo", summary: "step back · Ctrl-Z" },
       { command: "redo", summary: "step forward · Ctrl-Y" },
     ],
@@ -114,15 +143,42 @@ export const HELP_SECTIONS: readonly HelpSection[] = [
       },
       { command: "/auth [--check]", summary: "provider and audio status" },
       { command: "/play [on|off]", summary: "keyboard play mode · Ctrl-P" },
+      {
+        command: "/pattern [name]",
+        summary: "drum groove picker · moving previews",
+      },
+      {
+        command: "/kit [name]",
+        summary: "drum kit picker · synth kits, then samples",
+      },
+      {
+        command: "/pack list|info|use|add",
+        summary: "sample packs · /pack use 909/bd",
+      },
+      {
+        command: "/euclid [voice]",
+        summary: "T-1 style rhythm editor · Rhythm in /menu",
+      },
       {
         command: "/menu [section]",
-        summary: "edit by hand · Ctrl-K · track effects automation …",
+        summary: "every setting by hand · Ctrl-K",
+      },
+      {
+        command: "/try <sound command>",
+        summary: "hear it on a loop first · a A/B · enter keep",
       },
       {
         command: "/click on|off|<volume>",
         summary: "metronome · /count-in 0-2 · /grid 1/16",
       },
-      { command: "/help", summary: "this list · ?" },
+      {
+        command: "/chords auto|manual|off",
+        summary: "play-mode chords · /chords for settings",
+      },
+      {
+        command: "/help [topic]",
+        summary: "start here · /help all for everything",
+      },
     ],
   },
   {
@@ -134,21 +190,146 @@ export const HELP_SECTIONS: readonly HelpSection[] = [
       { 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: "Esc", summary: "cancel the agent · back one level" },
+      { command: "?", summary: "keys for the screen you are on" },
       { 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",
+        summary: "play mode · Z/X octave · R record · Q chords",
       },
       {
         command: "Ctrl-K",
-        summary: "menu: ↑↓/jk move · enter · ←→/+- nudge · / filter",
+        summary: "menu · ←→ adjust · / filter · x reset",
       },
       { command: "Ctrl-C", summary: "exit" },
     ],
   },
 ];
 
+/**
+ * `/help` with no topic: a short, task-first guide. Each row is something to
+ * type or press, then what it does. The full reference is `/help all` (or one
+ * group: `/help music`).
+ */
+export const HELP_GUIDE: readonly HelpSection[] = [
+  {
+    group: "start here" as HelpGroup,
+    entries: [
+      { command: "type a request", summary: "“add a walking bass in A minor”" },
+      { command: "ctrl-p", summary: "play notes on the computer keyboard" },
+      {
+        command: "ctrl-k",
+        summary: "menu: every sound, effect, rhythm, chord",
+      },
+      { command: "?", summary: "keys for the screen you are on" },
+      {
+        command: "ctrl-z · ctrl-y",
+        summary: "undo · redo (every change is one)",
+      },
+    ],
+  },
+  {
+    group: "play notes" as HelpGroup,
+    entries: [
+      {
+        command: "ctrl-p, a s d f …",
+        summary: "piano keys · z x octave · esc leave",
+      },
+      {
+        command: "r, then space",
+        summary: "record over the loop (one undo a bar)",
+      },
+    ],
+  },
+  {
+    group: "make drums" as HelpGroup,
+    entries: [
+      { command: "/pattern", summary: "pick a groove · moving previews it" },
+      { command: "/kit", summary: "pick a drum kit" },
+      { command: "/euclid", summary: "rhythm editor: pulses, steps, rotation" },
+    ],
+  },
+  {
+    group: "shape the sound" as HelpGroup,
+    entries: [
+      {
+        command: "ctrl-k › Sound",
+        summary: "instrument, envelope, filter, wavetable",
+      },
+      { command: "ctrl-k › Effects", summary: "delay, reverb, distortion …" },
+      { command: "fx delay mix 0.3", summary: "the same from the prompt" },
+      { command: "/try fx reverb mix 0.6", summary: "hear it before keeping" },
+    ],
+  },
+  {
+    group: "chords" as HelpGroup,
+    entries: [
+      { command: "key A minor", summary: "set the song key" },
+      {
+        command: "ctrl-p, then q",
+        summary: "chord mode: one key plays a chord",
+      },
+      {
+        command: "1–4 · 5–8 · n",
+        summary: "chord type · extension · next chord",
+      },
+    ],
+  },
+  {
+    group: "more" as HelpGroup,
+    entries: [
+      { command: "/help all", summary: "every command and key" },
+      { command: "/help music", summary: "or session, window, keys" },
+    ],
+  },
+];
+
+/** Topics `/help <topic>` takes, besides `all`. */
+export const HELP_TOPICS = ["music", "session", "window", "keys"] as const;
+
+/**
+ * Rows for `/help [topic]`: the guide with no topic, the full reference for
+ * `all`, one group for its name; undefined for an unknown topic.
+ */
+export function helpTopicLines(
+  topic: string | undefined,
+  width = 80,
+): string[] | undefined {
+  const name = topic?.trim().toLowerCase().replace(/^\//, "");
+  if (!name) return sectionLines(HELP_GUIDE, width, 20);
+  if (name === "all" || name === "commands" || name === "reference")
+    return helpLines(width);
+  const group = HELP_SECTIONS.find((section) => section.group === name);
+  return group ? sectionLines([group], width) : undefined;
+}
+
+function sectionLines(
+  sections: readonly HelpSection[],
+  width: number,
+  fixedColumn?: number,
+): string[] {
+  const lines: string[] = [];
+  const column =
+    fixedColumn ??
+    Math.min(
+      40,
+      Math.max(
+        ...sections.flatMap((s) => s.entries.map((e) => e.command.length)),
+      ) + 2,
+    );
+  for (const section of 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;
+}
+
 /** Overlay rows: a heading per group, then `command  summary` lines. */
 export function helpLines(width = 80): string[] {
   const lines: string[] = [];
@@ -187,6 +368,9 @@ export function helpText(): string {
 const USAGE: Readonly<Record<string, string>> = {
   click: "/click on|off|<volume> · /click 50%",
   "count-in": "/count-in 0|1|2",
+  chords:
+    "/chords auto|manual|off · voicing <n> · spread · bass · perform · rate · octaves · sevenths · preset · style",
+  key: "key <tonic> <mode> | none · key A minor",
   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",
@@ -201,10 +385,13 @@ const USAGE: Readonly<Record<string, string>> = {
   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",
+    "instrument <name> · sine piano pluck bass saw square triangle wavetable kit · synth: sawtooth supersaw pulse white pink z_square…",
   volume: "volume takes 0…1 · volume 0.8",
   vol: "volume takes 0…1 · volume 0.8",
   pan: "pan takes -1…1 · pan -0.5",
+  wt: "wt <table> | wt <0..1> | wt list · wt basic · wt wt_digital:2",
+  wavetable: "wt <table> | wt <0..1> | wt list · wt basic · wt wt_digital:2",
+  warpmode: "warpmode none|asym|bendp|bendm|bendmp|sync|quant",
   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",
@@ -222,7 +409,8 @@ const USAGE: Readonly<Record<string, string>> = {
   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",
+  sample:
+    "/sample <path> [as <voice>] · /sample set <voice> <control> <value>… · /sample set brk fit on clip 1",
   samples: "/sample · lists the focused track's voices",
   view: "/view focus | all",
   transcript: "/transcript",
@@ -233,15 +421,115 @@ const USAGE: Readonly<Record<string, string>> = {
   login: "/login [gateway | openrouter | codex | claude]",
   logout: "/logout [provider]",
   auth: "/auth [--check]",
-  help: "/help",
+  help: "/help [topic] · /help all · /help music|session|window|keys",
+  fx: "fx <effect> <param> <value> | on | off | preset <name> · fx delay mix 0.3",
+  synth: "synth <param> <value> | preset <name> · synth lpf 1200",
+  pack: "/pack list | info <name> | use <pack>/<sound> | add <url>",
+  kit: "/kit [name] · /kit syn909",
+  euclid: "/euclid [voice] · euclid hat 7 16",
+  menu: "/menu [sound|effects|rhythm|chords|mix|project]",
+  try: "/try <sound command> · /try fx reverb mix 0.6",
+  play: "/play [on|off] · Ctrl-P",
+  meter: "meter <1..16> · meter 3",
+  undo: "undo · Ctrl-Z",
+  redo: "redo · Ctrl-Y",
 };
 
+/** Verbs a typo can be matched against, slash or bare as they are typed. */
+const KNOWN_VERBS: readonly string[] = [
+  ...new Set(
+    [
+      ...HELP_SECTIONS.flatMap((section) =>
+        section.group === "keys"
+          ? []
+          : section.entries.map((entry) => entry.command.split(/[\s|[]/)[0]!),
+      ),
+      ...Object.values(USAGE).map((usage) => usage.split(/[\s|[]/)[0]!),
+    ].filter((verb) => /^\/?[a-z][\w-]*$/i.test(verb)),
+  ),
+];
+
+function editDistance(a: string, b: string): number {
+  const row = Array.from({ length: b.length + 1 }, (_, index) => index);
+  for (let i = 1; i <= a.length; i += 1) {
+    let previous = row[0]!;
+    row[0] = i;
+    for (let j = 1; j <= b.length; j += 1) {
+      const current = row[j]!;
+      row[j] = Math.min(
+        row[j]! + 1,
+        row[j - 1]! + 1,
+        previous + (a[i - 1] === b[j - 1] ? 0 : 1),
+      );
+      previous = current;
+    }
+  }
+  return row[b.length]!;
+}
+
+/**
+ * The known command nearest to the first word of `command` (`/clik` →
+ * `/click`, `/fx` → `fx`), or undefined when nothing is close.
+ */
+export function nearestCommand(command: string): string | undefined {
+  const word = command.trim().split(/\s+/)[0]?.toLowerCase() ?? "";
+  const bare = word.replace(/^\//, "");
+  if (!bare) return undefined;
+  let best: { verb: string; distance: number; score: number } | undefined;
+  for (const verb of KNOWN_VERBS) {
+    const distance = editDistance(bare, verb.replace(/^\//, ""));
+    if (distance === 0 && verb === word) continue;
+    // Ties go to the form typed: `/patern` → `/pattern`, not `pattern`.
+    const sameForm = verb.startsWith("/") === word.startsWith("/");
+    const score = distance * 2 + (sameForm ? 0 : 1);
+    if (!best || score < best.score) best = { verb, distance, score };
+  }
+  const limit = bare.length <= 4 ? 1 : 2;
+  return best && best.distance <= limit ? best.verb : undefined;
+}
+
+/**
+ * `tempoo 90` → `tempo 90`: the first word one edit from a bare command
+ * whose arguments then parse (`parses` decides). Slash words and inputs
+ * whose rest is not that command's arguments (prose) return undefined.
+ */
+export function typoFix(
+  command: string,
+  parses: (candidate: string) => boolean,
+): string | undefined {
+  const text = command.trim();
+  if (!text || text.startsWith("/")) return undefined;
+  const [first, ...rest] = text.split(/\s+/);
+  const word = first!.toLowerCase();
+  for (const verb of KNOWN_VERBS) {
+    if (verb.startsWith("/") || verb === word) continue;
+    if (editDistance(word, verb) !== 1) continue;
+    const candidate = [verb, ...rest].join(" ");
+    if (parses(candidate)) return candidate;
+  }
+  return undefined;
+}
+
+/**
+ * True for a sentence that merely starts with a command verb (`add a walking
+ * bass in A minor`, `pan the hats left`): three or more words and no number
+ * or note name with an octave. Those are requests for the agent, not
+ * malformed commands. Slash words are never prose.
+ */
+export function looksLikeProse(command: string): boolean {
+  const text = command.trim();
+  if (text.startsWith("/")) return false;
+  const words = text.split(/\s+/);
+  return words.length >= 3 && !/\d/.test(text);
+}
+
 /**
  * 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 {
+  if (looksLikeProse(command)) return undefined;
   const verb = command.trim().toLowerCase().replace(/^\//, "").split(/\s+/)[0];
   return verb ? USAGE[verb] : undefined;
 }

package/src/commands/music.ts

@@ -26,7 +26,9 @@ import {
   createScore,
   updateTrack,
   setTrackAutomation,
-  AUTOMATION_LANES,
+  automationPoints,
+  automationRange,
+  isAutomationParameter,
   type AutomationParameter,
   type NoteInput,
   type TrackScore,
@@ -96,8 +98,11 @@ const LANE_ALIASES: Readonly<Record<string, EffectAutomationParameter>> =
 export function parseEffectLane(
   name: string,
 ): EffectAutomationParameter | undefined {
-  return Object.prototype.hasOwnProperty.call(LANE_ALIASES, name)
-    ? LANE_ALIASES[name]
+  if (Object.prototype.hasOwnProperty.call(LANE_ALIASES, name))
+    return LANE_ALIASES[name];
+  // `fx` lanes by name: `distort-drive`, `autofilter-cutoff`, `reverb-mix`.
+  return isAutomationParameter(name) && name !== "volume" && name !== "pan"
+    ? name
     : undefined;
 }
 
@@ -248,7 +253,7 @@ export function parseMusicCommand(prompt: string): MusicCommand | undefined {
     const beat = Number(automate[2]);
     const value = Number(automate[3]);
     if (!parameter || !validBeat(beat)) return undefined;
-    const { min, max } = AUTOMATION_LANES[parameter];
+    const { min, max } = automationRange(parameter);
     if (!Number.isFinite(value) || value < min || value > max) return undefined;
     return { type: "effect-automation", parameter, beat, value };
   }
@@ -332,10 +337,7 @@ export function applyMusicCommand(
     if (command.type === "effect-automation") {
       const tick = Math.round(command.beat * score.ticksPerBeat);
       const merged = new Map(
-        (track[AUTOMATION_LANES[parameter].field] ?? []).map((point) => [
-          point.tick,
-          point,
-        ]),
+        automationPoints(track, parameter).map((point) => [point.tick, point]),
       );
       merged.set(tick, { tick, value: command.value });
       points = [...merged.values()].sort((a, b) => a.tick - b.tick);