@hraness/dawg 0.3.0 → 0.4.1

package/core/sdk/v1.ts

@@ -27,7 +27,7 @@
  */
 
 /** SDK release; dawg refreshes the vendored copy when its own is newer. */
-export const SDK_VERSION = "1.0.0";
+export const SDK_VERSION = "1.13.0";
 /** Major of `SDK_VERSION`; `dawg.json` records it as `sdk`. */
 export const SDK_MAJOR = 1;
 
@@ -305,13 +305,723 @@ export function every(step: number, options: EveryOptions = {}): number[] {
   return beats;
 }
 
+// ---------------------------------------------------------------------------
+// Rhythm rows (Euclidean generators, Torso T-1 style)
+
+/** Per-pass variation of a rhythm row (T-1 Cycles). */
+export type RhythmCycleSpec = Readonly<{
+  pulses?: number;
+  rotate?: number;
+  repeats?: number;
+  probability?: number;
+  velocity?: number;
+}>;
+
+/**
+ * Parameters of one generated voice. Every field is optional; dawg checks
+ * ranges when the song loads. Note values are strings: `"1/16"`, `"1/8t"`.
+ */
+export type RhythmOptions = Readonly<{
+  /** Steps 1..64, default 16. */
+  steps?: number;
+  /** Hits 0..steps spread as evenly as possible, default 4. */
+  pulses?: number;
+  /** Shift the pattern later by this many steps (negative: earlier), like Strudel's `euclidRot`. */
+  rotate?: number;
+  /** Length of a step, default `"1/16"`. */
+  division?: string;
+  /** Explicit steps instead of a Euclidean pattern: `x` hit, `X` accent, `.` rest. */
+  grid?: string;
+  /** Extra triggers after each pulse, 0..16 (T-1 Repeats). Cut off by the next pulse. */
+  repeats?: number;
+  /** Spacing of the repeats as a note value, default the step (T-1 Time). */
+  time?: string;
+  /** -1..1: repeats accelerate (<0) or decelerate (>0) (T-1 Pace). */
+  pace?: number;
+  /** -1..1: repeats fade out (<0) or build up (>0). */
+  ramp?: number;
+  /** Base velocity 0..1, default 0.8. */
+  velocity?: number;
+  /** 0..1: how far accented pulses rise toward full velocity. */
+  accent?: number;
+  /** Accented pulses as E(accents, pulses); default 1 (the first). */
+  accents?: number;
+  /** Note length in steps, 0.05..4 (T-1 Sustain), default 1. */
+  gate?: number;
+  /** Every pulse lasts until the next one, like Strudel's `euclidLegato`. */
+  legato?: boolean;
+  /** Chance 0..1 that a pulse plays; deterministic for a given `seed`. */
+  probability?: number;
+  /** Integer 0..1000000 choosing which pulses `probability` drops. */
+  seed?: number;
+  /** -0.5..0.5 of a step: every second step later (>0) or earlier. */
+  swing?: number;
+  /** -0.5..0.5 of a step: the whole row later or earlier. */
+  nudge?: number;
+  /** Variations applied on successive passes of the row (T-1 Cycles). */
+  cycles?: readonly RhythmCycleSpec[];
+}>;
+
+/** One generated voice on a track's `rhythm` list. Build with `euclid()` or `grid()`. */
+export type RhythmSpec = Readonly<
+  RhythmOptions & {
+    kind: "rhythm";
+    voice: string;
+  }
+>;
+
+/**
+ * A Euclidean rhythm row: `pulses` hits spread over `steps`, rotated later
+ * by `rotate` steps. Same patterns and rotation direction as Strudel's
+ * `euclid`/`euclidRot` (`euclid("kick", 3, 8)` is `x..x..x.`). dawg expands
+ * the row into hits when the song loads, so you edit the parameters, not
+ * the notes; the row repeats every `steps` steps to the end of the loop.
+ *
+ * ```ts
+ * rhythm: [
+ *   euclid("kick", 4, 16),
+ *   euclid("hat", 7, 16, 2, { velocity: 0.5, accent: 0.6, accents: 3 }),
+ *   euclid({ voice: "snare", pulses: 2, steps: 16, rotate: 4 }),
+ * ]
+ * ```
+ */
+export function euclid(
+  voice: string | (RhythmOptions & { voice: string }),
+  pulses?: number,
+  steps?: number,
+  rotate?: number | RhythmOptions,
+  options: RhythmOptions = {},
+): RhythmSpec {
+  if (isRecord(voice)) {
+    const input = voice as RhythmOptions & { voice: string };
+    return rhythmSpec(input.voice, input);
+  }
+  // `euclid("hat", 7, 16, { velocity: 0.5 })`: options without a rotate.
+  if (isRecord(rotate)) {
+    options = { ...(rotate as RhythmOptions), ...options };
+    rotate = undefined;
+  }
+  const fields: Record<string, unknown> = { ...options };
+  if (pulses !== undefined) fields.pulses = pulses;
+  if (steps !== undefined) fields.steps = steps;
+  if (rotate !== undefined) fields.rotate = rotate;
+  return rhythmSpec(voice, fields as RhythmOptions);
+}
+
+/** `euclid(voice, pulses, steps, rotate)` under Strudel's name. */
+export function euclidRot(
+  voice: string,
+  pulses: number,
+  steps: number,
+  rotate: number,
+  options: RhythmOptions = {},
+): RhythmSpec {
+  return euclid(voice, pulses, steps, rotate, options);
+}
+
+/** A Euclidean row whose hits last until the next one (Strudel `euclidLegato`). */
+export function euclidLegato(
+  voice: string,
+  pulses: number,
+  steps: number,
+  rotate = 0,
+  options: RhythmOptions = {},
+): RhythmSpec {
+  return euclid(voice, pulses, steps, rotate, { ...options, legato: true });
+}
+
+/**
+ * An explicit step row: `grid("snare", "....x.......x...")`. `X` is an
+ * accented hit; the string's length is the step count.
+ */
+export function grid(
+  voice: string,
+  steps: string,
+  options: RhythmOptions = {},
+): RhythmSpec {
+  return rhythmSpec(voice, { ...options, grid: steps });
+}
+
+function rhythmSpec(voice: unknown, options: RhythmOptions): RhythmSpec {
+  if (
+    typeof voice !== "string" ||
+    voice.trim().length === 0 ||
+    voice.length > 32
+  )
+    throw new DawgSdkError("rhythm voice must be a short name");
+  if (!isRecord(options))
+    throw new DawgSdkError("rhythm options must be an object");
+  const out: Record<string, unknown> = { kind: "rhythm", voice: voice.trim() };
+  for (const [key, value] of Object.entries(options)) {
+    if (key === "voice" || key === "kind" || value === undefined) continue;
+    if (!RHYTHM_KEYS.includes(key))
+      throw new DawgSdkError(
+        `rhythm ${voice}: unknown option "${key}" (${RHYTHM_KEYS.join(" ")})`,
+      );
+    out[key] =
+      key === "cycles" && Array.isArray(value)
+        ? Object.freeze(value.map((cycle) => Object.freeze({ ...cycle })))
+        : value;
+  }
+  return Object.freeze(out) as RhythmSpec;
+}
+
+/** Row fields in the order dawg stores and prints them. */
+export const RHYTHM_KEYS: readonly string[] = Object.freeze([
+  "steps",
+  "pulses",
+  "rotate",
+  "division",
+  "grid",
+  "repeats",
+  "time",
+  "pace",
+  "ramp",
+  "velocity",
+  "accent",
+  "accents",
+  "gate",
+  "legato",
+  "probability",
+  "seed",
+  "swing",
+  "nudge",
+  "cycles",
+]);
+
+// ---------------------------------------------------------------------------
+// Drum pattern library
+
+/**
+ * A named starting groove: one rhythm row per voice, ready for a
+ * `instrument: "kit"` track. Rows are Euclidean where the part is
+ * Euclidean and explicit grids otherwise. All patterns are 4/4; `swing`
+ * is already applied to the rows.
+ */
+export type DrumPattern = Readonly<{
+  name: string;
+  label: string;
+  tags: readonly string[];
+  /** Usual tempo range and a suggested tempo, BPM. */
+  tempo: Readonly<{ min: number; max: number; bpm: number }>;
+  beatsPerBar: number;
+  /** Swing of the 16th rows, -0.5..0.5 of a step. */
+  swing: number;
+  /** A synthesized kit that suits it (see `kit` on `track()`). */
+  kit: string;
+  rows: readonly RhythmSpec[];
+}>;
+
+function drumPattern(
+  name: string,
+  label: string,
+  tags: readonly string[],
+  tempo: readonly [number, number, number],
+  kit: string,
+  swing: number,
+  rows: readonly RhythmSpec[],
+): DrumPattern {
+  return Object.freeze({
+    name,
+    label,
+    tags: Object.freeze([...tags]),
+    tempo: Object.freeze({ min: tempo[0], max: tempo[1], bpm: tempo[2] }),
+    beatsPerBar: 4,
+    swing,
+    kit,
+    rows: Object.freeze(
+      rows.map((row) =>
+        swing !== 0 && row.swing === undefined && row.division === undefined
+          ? Object.freeze({ ...row, swing })
+          : row,
+      ),
+    ),
+  });
+}
+
+/**
+ * The library. Written for dawg from common knowledge of each style (no
+ * transcriptions): the defining placements of kick, snare and hats, kept
+ * short so they are easy to vary.
+ */
+export const DRUM_PATTERNS: readonly DrumPattern[] = Object.freeze([
+  drumPattern(
+    "house",
+    "House four-on-the-floor",
+    ["house", "dance", "four-on-the-floor"],
+    [118, 128, 124],
+    "syn909",
+    0,
+    [
+      euclid("kick", 4, 16),
+      grid("clap", "....x.......x..."),
+      euclid("openhat", 4, 16, 2, { velocity: 0.6 }),
+      euclid("hat", 16, 16, 0, { velocity: 0.35, accent: 0.4, accents: 4 }),
+    ],
+  ),
+  drumPattern(
+    "disco",
+    "Disco",
+    ["disco", "dance", "four-on-the-floor"],
+    [110, 125, 118],
+    "acoustic",
+    0,
+    [
+      euclid("kick", 4, 16),
+      grid("snare", "....x.......x..."),
+      euclid("openhat", 4, 16, 2, { velocity: 0.65 }),
+      euclid("hat", 8, 16, 0, { velocity: 0.45 }),
+    ],
+  ),
+  drumPattern(
+    "techno",
+    "Techno",
+    ["techno", "dance", "four-on-the-floor"],
+    [125, 140, 132],
+    "syn909",
+    0,
+    [
+      euclid("kick", 4, 16),
+      euclid("openhat", 4, 16, 2, { velocity: 0.55 }),
+      euclid("hat", 16, 16, 0, {
+        velocity: 0.4,
+        accent: 0.5,
+        accents: 4,
+        probability: 0.9,
+        seed: 7,
+      }),
+      euclid("rim", 3, 8, 3, { velocity: 0.55 }),
+      grid("clap", "............x...", { velocity: 0.7 }),
+    ],
+  ),
+  drumPattern(
+    "minimal",
+    "Minimal Euclidean",
+    ["minimal", "techno", "euclidean"],
+    [120, 130, 124],
+    "electro",
+    0,
+    [
+      euclid("kick", 4, 16),
+      euclid("rim", 5, 16, 3, { velocity: 0.6 }),
+      euclid("hat", 7, 16, 2, { velocity: 0.45, accent: 0.5, accents: 3 }),
+      euclid("tom", 3, 16, 6, { velocity: 0.5 }),
+    ],
+  ),
+  drumPattern(
+    "electro",
+    "Electro",
+    ["electro", "breaks"],
+    [120, 135, 128],
+    "electro",
+    0,
+    [
+      grid("kick", "x.....x..x......"),
+      grid("snare", "....x.......x..."),
+      euclid("hat", 16, 16, 0, { velocity: 0.4, accent: 0.5, accents: 4 }),
+      grid("clap", "....x.......x..x", { velocity: 0.6 }),
+    ],
+  ),
+  drumPattern(
+    "breakbeat",
+    "Breakbeat",
+    ["breaks", "big beat"],
+    [120, 140, 130],
+    "acoustic",
+    0,
+    [
+      grid("kick", "x.........x.x...x.x.......x....."),
+      grid("snare", "....x.......x.......x..x....x..."),
+      euclid("hat", 8, 16, 0, { velocity: 0.5 }),
+    ],
+  ),
+  drumPattern(
+    "amen-style",
+    "Amen-style break",
+    ["breaks", "jungle", "drum and bass"],
+    [160, 176, 170],
+    "acoustic",
+    0,
+    [
+      grid("kick", "x.x.......xx....x.x.......x....."),
+      grid("snare", "....X..x.x..X..x....X..x.x....X.", {
+        velocity: 0.55,
+        accent: 0.4,
+      }),
+      euclid("hat", 8, 16, 0, { velocity: 0.45 }),
+    ],
+  ),
+  drumPattern(
+    "dnb",
+    "Drum & bass two-step",
+    ["drum and bass", "jungle"],
+    [168, 178, 174],
+    "syn909",
+    0,
+    [
+      grid("kick", "x.........x....."),
+      grid("snare", "....x.......x..."),
+      euclid("hat", 8, 16, 1, { velocity: 0.45 }),
+      grid("openhat", "..............x.", { velocity: 0.4 }),
+    ],
+  ),
+  drumPattern(
+    "halftime",
+    "Halftime",
+    ["halftime", "drum and bass", "dubstep"],
+    [140, 175, 170],
+    "syn909",
+    0,
+    [
+      grid("kick", "x.........x.....x......x.x......"),
+      grid("snare", "........x.......", { velocity: 0.95 }),
+      euclid("hat", 8, 16, 0, { velocity: 0.4, probability: 0.85, seed: 3 }),
+    ],
+  ),
+  drumPattern(
+    "boom-bap",
+    "Boom bap",
+    ["hip hop", "boom bap"],
+    [84, 96, 90],
+    "lofi",
+    0.12,
+    [
+      grid("kick", "x......x..x.....x.x....x..x....."),
+      grid("snare", "....x.......x..."),
+      euclid("hat", 8, 16, 0, { velocity: 0.5, accent: 0.4, accents: 4 }),
+    ],
+  ),
+  drumPattern(
+    "lofi",
+    "Lo-fi hip hop",
+    ["hip hop", "lo-fi", "chill"],
+    [70, 90, 80],
+    "lofi",
+    0.18,
+    [
+      grid("kick", "x.........x.....x......x..x....."),
+      grid("snare", "....x.......x..."),
+      euclid("hat", 8, 16, 0, { velocity: 0.4, probability: 0.9, seed: 11 }),
+      grid("rim", "...............x", { velocity: 0.4 }),
+    ],
+  ),
+  drumPattern(
+    "trap",
+    "Trap with hat rolls",
+    ["trap", "hip hop"],
+    [130, 160, 140],
+    "trap",
+    0,
+    [
+      grid("kick", "x......x..x.....x.x....x......x."),
+      grid("snare", "........x......."),
+      grid("hat", "x.x.x.x.x.x.x.x.x.x.x.x.x.xxxxxx", {
+        division: "1/32",
+        velocity: 0.45,
+      }),
+      grid("openhat", "..............x.", { velocity: 0.35 }),
+    ],
+  ),
+  drumPattern("drill", "Drill", ["drill", "trap"], [138, 146, 142], "trap", 0, [
+    grid("kick", "x.....x.........x..x......x....."),
+    grid("snare", "........x..........x....x......."),
+    grid("hat", "x..x..x.x..x..x.", { velocity: 0.45 }),
+  ]),
+  drumPattern(
+    "reggaeton",
+    "Reggaeton / dembow",
+    ["reggaeton", "dembow", "latin"],
+    [88, 100, 95],
+    "syn808",
+    0,
+    [
+      euclid("kick", 4, 16),
+      grid("snare", "...x..x....x..x."),
+      euclid("hat", 8, 16, 0, { velocity: 0.45 }),
+    ],
+  ),
+  drumPattern(
+    "dancehall",
+    "Dancehall",
+    ["dancehall", "caribbean"],
+    [90, 110, 100],
+    "syn808",
+    0,
+    [
+      euclid("kick", 3, 8),
+      grid("snare", "....x.......x..."),
+      euclid("rim", 5, 16, 2, { velocity: 0.5 }),
+      euclid("hat", 8, 16, 0, { velocity: 0.4 }),
+    ],
+  ),
+  drumPattern(
+    "one-drop",
+    "Reggae one drop",
+    ["reggae", "dub"],
+    [66, 80, 74],
+    "acoustic",
+    0.1,
+    [
+      grid("kick", "........x......."),
+      grid("rim", "........x......."),
+      euclid("hat", 8, 16, 0, { velocity: 0.45, accent: 0.4, accents: 2 }),
+    ],
+  ),
+  drumPattern(
+    "afrobeat",
+    "Afrobeat",
+    ["afrobeat", "african", "funk"],
+    [100, 120, 110],
+    "acoustic",
+    0.05,
+    [
+      grid("kick", "x.....x...x.....x.....x...x..x.."),
+      grid("snare", "....x..x....x..x", { velocity: 0.6 }),
+      euclid("openhat", 4, 16, 2, { velocity: 0.45 }),
+      euclid("hat", 12, 16, 0, { velocity: 0.4 }),
+      grid("rim", "x.x.xx.x.x.x....", { velocity: 0.5 }),
+    ],
+  ),
+  drumPattern(
+    "afrobeats",
+    "Afrobeats / afro-pop",
+    ["afrobeats", "afro-pop", "african"],
+    [100, 115, 106],
+    "syn808",
+    0.06,
+    [
+      euclid("kick", 4, 16),
+      grid("rim", "...x..x...x..x..", { velocity: 0.6 }),
+      euclid("hat", 8, 16, 0, { velocity: 0.4 }),
+      grid("clap", "............x...", { velocity: 0.6 }),
+    ],
+  ),
+  drumPattern(
+    "bembe",
+    "Bembé 12/8 bell",
+    ["afro-cuban", "african", "euclidean"],
+    [100, 130, 112],
+    "acoustic",
+    0,
+    [
+      euclid("kick", 4, 12, 0, { division: "1/8t" }),
+      euclid("rim", 7, 12, 9, { division: "1/8t", velocity: 0.6 }),
+      euclid("hat", 12, 12, 0, {
+        division: "1/8t",
+        velocity: 0.35,
+        accent: 0.4,
+        accents: 4,
+      }),
+    ],
+  ),
+  drumPattern(
+    "tresillo",
+    "Tresillo",
+    ["latin", "euclidean", "habanera"],
+    [90, 120, 100],
+    "syn808",
+    0,
+    [
+      euclid("kick", 3, 8),
+      grid("snare", "....x.......x..."),
+      euclid("hat", 8, 16, 0, { velocity: 0.4 }),
+    ],
+  ),
+  drumPattern(
+    "son-clave",
+    "Son clave groove",
+    ["afro-cuban", "salsa", "latin"],
+    [90, 120, 100],
+    "acoustic",
+    0,
+    [
+      grid("rim", "x..x..x...x.x...", { velocity: 0.65 }),
+      grid("kick", "...x.......x....", { velocity: 0.7 }),
+      euclid("hat", 8, 16, 0, { velocity: 0.35 }),
+    ],
+  ),
+  drumPattern(
+    "bossa-nova",
+    "Bossa nova",
+    ["bossa nova", "brazilian", "latin"],
+    [120, 145, 132],
+    "acoustic",
+    0,
+    [
+      grid("kick", "x..xx..xx..xx..x", { velocity: 0.6 }),
+      grid("rim", "x..x..x...x..x..", { velocity: 0.55 }),
+      euclid("hat", 16, 16, 0, { velocity: 0.3, accent: 0.4, accents: 4 }),
+    ],
+  ),
+  drumPattern(
+    "samba",
+    "Samba",
+    ["samba", "brazilian", "latin"],
+    [92, 110, 100],
+    "acoustic",
+    0.04,
+    [
+      grid("kick", "x..xX..xx..xX..x", { velocity: 0.6, accent: 0.5 }),
+      grid("rim", "x.x..x.x.x.x..x.", { velocity: 0.5 }),
+      euclid("hat", 16, 16, 0, { velocity: 0.35, accent: 0.5, accents: 4 }),
+    ],
+  ),
+  drumPattern(
+    "cumbia",
+    "Cumbia",
+    ["cumbia", "latin"],
+    [85, 105, 95],
+    "acoustic",
+    0,
+    [
+      grid("kick", "x.......x......."),
+      grid("rim", "....x.......x...", { velocity: 0.6 }),
+      euclid("hat", 12, 16, 0, { velocity: 0.35, accent: 0.5, accents: 4 }),
+      euclid("openhat", 4, 16, 2, { velocity: 0.4 }),
+    ],
+  ),
+  drumPattern(
+    "garage",
+    "UK garage 2-step",
+    ["uk garage", "2-step", "dance"],
+    [128, 136, 132],
+    "syn909",
+    0.15,
+    [
+      grid("kick", "x.........x..x..x.......x.x....."),
+      grid("snare", "....x.......x..."),
+      euclid("hat", 12, 16, 0, { velocity: 0.4 }),
+      euclid("openhat", 4, 16, 2, { velocity: 0.35 }),
+    ],
+  ),
+  drumPattern(
+    "jersey-club",
+    "Jersey club",
+    ["jersey club", "club"],
+    [135, 145, 140],
+    "syn808",
+    0,
+    [
+      grid("kick", "x...x...x..x.x..x...x...x.x.x.x."),
+      grid("clap", "....x.......x..."),
+      euclid("hat", 8, 16, 0, { velocity: 0.4 }),
+    ],
+  ),
+  drumPattern(
+    "footwork",
+    "Footwork / juke",
+    ["footwork", "juke", "chicago"],
+    [155, 165, 160],
+    "syn808",
+    0,
+    [
+      grid("kick", "x..x..x...x..x..x..x..x...x.x.x."),
+      grid("clap", "............x..."),
+      euclid("hat", 6, 16, 2, { velocity: 0.45 }),
+      euclid("tom", 3, 16, 8, { velocity: 0.5 }),
+    ],
+  ),
+  drumPattern(
+    "rock",
+    "Rock basic",
+    ["rock", "pop"],
+    [100, 140, 120],
+    "acoustic",
+    0,
+    [
+      grid("kick", "x.......x.x....."),
+      grid("snare", "....x.......x..."),
+      euclid("hat", 8, 16, 0, { velocity: 0.55, accent: 0.3, accents: 4 }),
+    ],
+  ),
+  drumPattern(
+    "funk",
+    "Funk with ghost notes",
+    ["funk", "soul"],
+    [95, 110, 102],
+    "acoustic",
+    0.08,
+    [
+      grid("kick", "x.x.......x..x.."),
+      grid("snare", ".x..X..x.x..X..x", { velocity: 0.4, accent: 0.9 }),
+      euclid("hat", 16, 16, 0, { velocity: 0.35, accent: 0.4, accents: 4 }),
+    ],
+  ),
+  drumPattern(
+    "shuffle",
+    "Shuffle",
+    ["blues", "shuffle", "rock"],
+    [90, 130, 110],
+    "acoustic",
+    0.33,
+    [
+      grid("kick", "x.......x......."),
+      grid("snare", "....x.......x..."),
+      euclid("hat", 16, 16, 0, { velocity: 0.35, accent: 0.5, accents: 8 }),
+    ],
+  ),
+  drumPattern(
+    "euclid-poly",
+    "Euclidean polymeter",
+    ["euclidean", "experimental", "polymeter"],
+    [110, 130, 120],
+    "electro",
+    0,
+    [
+      euclid("kick", 5, 16),
+      euclid("snare", 3, 8, 2, { velocity: 0.7 }),
+      euclid("hat", 7, 12, 0, { velocity: 0.45, accent: 0.5, accents: 3 }),
+      euclid("rim", 4, 10, 1, { velocity: 0.5, probability: 0.8, seed: 21 }),
+    ],
+  ),
+]);
+
+/** The pattern named `name` (case-insensitive), if any. */
+export function findPattern(name: string): DrumPattern | undefined {
+  const key = String(name)
+    .trim()
+    .toLowerCase()
+    .replace(/[\s_]+/g, "-");
+  return DRUM_PATTERNS.find((entry) => entry.name === key);
+}
+
+/**
+ * A library pattern's rows, for a kit track's `rhythm`:
+ *
+ * ```ts
+ * track({ name: "drums", instrument: "kit", kit: "lofi", rhythm: pattern("boom-bap") })
+ * ```
+ *
+ * Spread it to change or add rows: `[...pattern("house"), euclid("rim", 5, 16)]`.
+ * Rows with the same voice must not repeat, so drop the original first.
+ */
+export function pattern(name: string): readonly RhythmSpec[] {
+  const found = findPattern(name);
+  if (!found)
+    throw new DawgSdkError(
+      `unknown drum pattern "${String(name).slice(0, 40)}" (${DRUM_PATTERNS.map((entry) => entry.name).join(" ")})`,
+    );
+  return found.rows;
+}
+
 // ---------------------------------------------------------------------------
 // Sampler
 
 /** One sample voice. A bare string is `{ src }`. */
 export type SampleSpec = Readonly<{
-  /** Audio file: track-relative (`samples/kick.wav`) or project-relative (`tracks/x/samples/kick.wav`). */
+  /**
+   * Audio file: track-relative (`samples/kick.wav`) or project-relative
+   * (`tracks/x/samples/kick.wav`), or a pack sound
+   * `pack:<pack>/<sound>[:<n>]` such as `pack:tidal-drum-machines/RolandTR909_bd:0`
+   * (fetched once into the cache; see `/pack`).
+   */
   src: string;
+  /** Pack sounds: content hash dawg pinned when the sound was first used. */
+  sha256?: string;
+  /** Pack sounds: the pinned HTTPS file. */
+  url?: string;
+  /** Pack sounds: the pack's license, recorded for credits. */
+  license?: string;
   /** Pitch the file plays at, keyed mode only; default C4. */
   root?: Pitch;
   /** Start fraction 0..1 of the file, like Strudel `begin`. */
@@ -326,6 +1036,28 @@ export type SampleSpec = Readonly<{
   loop?: boolean;
   /** Choke group, like Strudel `cut`: a new hit stops the previous one in the group. */
   choke?: string;
+  /** Looped part, like Strudel `loopBegin`/`loopb` (fraction, ≥ begin). */
+  loopBegin?: number;
+  /** Alias of `loopBegin` (Strudel `loopb`). */
+  loopb?: number;
+  /** Looped part end, like Strudel `loopEnd`/`loope` (fraction, ≤ end). */
+  loopEnd?: number;
+  /** Alias of `loopEnd` (Strudel `loope`). */
+  loope?: number;
+  /** Like Strudel `clip`: the voice lasts note length × clip (0 < clip ≤ 16), cutting the sample. */
+  clip?: number;
+  /** Alias of `clip` (Strudel `legato`). */
+  legato?: number;
+  /** Like Tidal `unit`: `"r"` rate (default), `"c"` speed in cycles (bars), `"s"` speed in seconds. */
+  unit?: "r" | "c" | "s";
+  /** Like Strudel `fit`: the window lasts exactly the note's length. */
+  fit?: boolean;
+  /** Like Strudel `loopAt(n)`: the window lasts n bars (stored as `speed: 1/n, unit: "c"`). */
+  loopAt?: number;
+  /** Like Tidal `accelerate`: rate ramps by this × the start rate over the voice (−8..8). */
+  accelerate?: number;
+  /** Like Tidal `squiz`: pitch-raise ratio per zero-crossing cycle (1..32). */
+  squiz?: number;
 }>;
 
 /** Result of `sampler()`; pass it as a track's `instrument`. */
@@ -371,6 +1103,117 @@ export function sampler(
   return Object.freeze({ kind: "sampler", voices: Object.freeze(out), mode });
 }
 
+/** Instrument name that selects a track's wavetable oscillator. */
+export const WAVETABLE_INSTRUMENT = "wavetable";
+
+/** Strudel's `warpmode` names. */
+export type WarpMode =
+  "none" | "asym" | "bendp" | "bendm" | "bendmp" | "sync" | "quant";
+
+/** Wavetable parameters, with Strudel's names. Omitted means default. */
+export type WavetableParams = Readonly<{
+  /** Position 0..1 (default 0). */
+  wt?: number;
+  /** Position envelope amount -1..1 and its ADSR (seconds, sustain 0..1). */
+  wtenv?: number;
+  wtattack?: number;
+  wtdecay?: number;
+  wtsustain?: number;
+  wtrelease?: number;
+  /** Position LFO rate (Hz) and depth 0..1. */
+  wtrate?: number;
+  wtdepth?: number;
+  /** Phase warp amount 0..1 and mode. */
+  warp?: number;
+  warpmode?: WarpMode;
+  /** Start phase randomness 0..1 (seeded per note). */
+  wtphaserand?: number;
+}>;
+
+/** Result of `wavetable()`; pass it as a track's `instrument`. */
+export type WavetableSpec = Readonly<
+  { kind: "wavetable"; table: SampleSpec } & WavetableParams
+>;
+
+const WAVETABLE_KEYS = Object.freeze([
+  "wt",
+  "wtenv",
+  "wtattack",
+  "wtdecay",
+  "wtsustain",
+  "wtrelease",
+  "wtrate",
+  "wtdepth",
+  "warp",
+  "wtphaserand",
+] as const);
+
+/**
+ * A wavetable instrument. `table` is a built-in (`basic`, `pwm`,
+ * `formant`, `harmonics`), a Strudel `wt_` sound (`wt_digital:2` plays
+ * `pack:uzu-wavetables/wt_digital:2`), any `pack:` ref, a project WAV
+ * (`./wavetables/vox.wav`, relative to the track's directory, as the agent's
+ * make_wavetable writes it), or a pinned `{ src, sha256, url }` that dawg
+ * writes back after resolving it.
+ *
+ * ```ts
+ * instrument: wavetable("basic", { wt: 0.4 })
+ * instrument: wavetable("./wavetables/vox.wav", { wtenv: 0.5 })
+ * instrument: wavetable("wt_vgame:3", { wtenv: 0.6, wtdecay: 0.4, warp: 0.3, warpmode: "bendp" })
+ * ```
+ */
+export function wavetable(
+  table: string | SampleSpec,
+  params: WavetableParams = {},
+): WavetableSpec {
+  if (!isRecord(params))
+    throw new DawgSdkError("wavetable params must be an object");
+  const spec = typeof table === "string" ? { src: table } : table;
+  if (!isRecord(spec) || typeof spec.src !== "string" || spec.src.length === 0)
+    throw new DawgSdkError("wavetable needs a table name");
+  let src = spec.src.trim();
+  if (/\.wav$/i.test(src) && !src.startsWith("pack:")) {
+    // A project table (make_wavetable writes tracks/<slug>/wavetables/x.wav);
+    // `./wavetables/x.wav` is relative to the track's directory.
+    if (
+      src.includes("..") ||
+      src.includes(":") ||
+      src.startsWith("/") ||
+      src.includes("\\")
+    )
+      throw new DawgSdkError(
+        `wavetable file "${src.slice(0, 60)}" must be a project-relative path without ".."`,
+      );
+  } else if (!src.includes(":") || /^wt_[A-Za-z0-9_]+:[0-9]+$/.test(src))
+    src = src.startsWith("wt_")
+      ? `pack:uzu-wavetables/${src}`
+      : `builtin:${src.toLowerCase()}`;
+  else if (!/^(?:pack|builtin):/.test(src))
+    throw new DawgSdkError(
+      `wavetable table "${src.slice(0, 40)}" must be a built-in, wt_<set>:<n>, pack:<pack>/<sound> or a .wav file`,
+    );
+  const out: Record<string, unknown> = {
+    kind: "wavetable",
+    table: Object.freeze(
+      src.startsWith("builtin:") ? { src } : { ...spec, src },
+    ),
+  };
+  for (const key of Object.keys(params)) {
+    const value = (params as Record<string, unknown>)[key];
+    if (key === "warpmode") {
+      if (typeof value !== "string")
+        throw new DawgSdkError("wavetable warpmode must be a string");
+      out.warpmode = value;
+    } else if ((WAVETABLE_KEYS as readonly string[]).includes(key))
+      out[key] = finite(value, `wavetable ${key}`);
+    else
+      throw new DawgSdkError(
+        `wavetable has no parameter "${key}" (${WAVETABLE_KEYS.join(" ")} warpmode)`,
+      );
+  }
+  return Object.freeze(out) as WavetableSpec;
+}
+
 /**
  * `count` equal slices of one file as voices `prefix0 … prefixN-1`, for
  * chopped breaks: `sampler(slices("samples/break.wav", 8, "brk"))`, then
@@ -404,6 +1247,9 @@ function sample(value: string | SampleSpec, name: string): SampleSpec {
     throw new DawgSdkError(`sampler voice ${name} needs a src path`);
   const out: {
     src: string;
+    sha256?: string;
+    url?: string;
+    license?: string;
     root?: number;
     begin?: number;
     end?: number;
@@ -411,7 +1257,21 @@ function sample(value: string | SampleSpec, name: string): SampleSpec {
     speed?: number;
     loop?: boolean;
     choke?: string;
+    loopBegin?: number;
+    loopEnd?: number;
+    clip?: number;
+    unit?: "r" | "c" | "s";
+    fit?: boolean;
+    accelerate?: number;
+    squiz?: number;
   } = { src: spec.src };
+  if (spec.src.startsWith("pack:")) {
+    if (spec.sha256 !== undefined)
+      out.sha256 = text(spec.sha256, `${name} sha256`);
+    if (spec.url !== undefined) out.url = text(spec.url, `${name} url`);
+    if (spec.license !== undefined)
+      out.license = text(spec.license, `${name} license`);
+  }
   if (spec.root !== undefined) out.root = midi(spec.root);
   if (spec.begin !== undefined) out.begin = unit(spec.begin, `${name} begin`);
   if (spec.end !== undefined) out.end = unit(spec.end, `${name} end`);
@@ -427,6 +1287,32 @@ function sample(value: string | SampleSpec, name: string): SampleSpec {
       throw new DawgSdkError(`${name} choke must be a group name`);
     out.choke = spec.choke;
   }
+  const loopBegin = spec.loopBegin ?? spec.loopb;
+  if (loopBegin !== undefined)
+    out.loopBegin = unit(loopBegin, `${name} loopBegin`);
+  const loopEnd = spec.loopEnd ?? spec.loope;
+  if (loopEnd !== undefined) out.loopEnd = unit(loopEnd, `${name} loopEnd`);
+  const clip = spec.clip ?? spec.legato;
+  if (clip !== undefined) out.clip = finite(clip, `${name} clip`);
+  if (spec.unit !== undefined) {
+    if (spec.unit !== "r" && spec.unit !== "c" && spec.unit !== "s")
+      throw new DawgSdkError(`${name} unit must be "r", "c" or "s"`);
+    out.unit = spec.unit;
+  }
+  if (spec.loopAt !== undefined) {
+    const bars = finite(spec.loopAt, `${name} loopAt`);
+    if (bars <= 0) throw new DawgSdkError(`${name} loopAt must be positive`);
+    out.speed = (out.speed ?? 1) / bars;
+    out.unit = "c";
+  }
+  if (spec.fit !== undefined) {
+    if (typeof spec.fit !== "boolean")
+      throw new DawgSdkError(`${name} fit must be boolean`);
+    out.fit = spec.fit;
+  }
+  if (spec.accelerate !== undefined)
+    out.accelerate = finite(spec.accelerate, `${name} accelerate`);
+  if (spec.squiz !== undefined) out.squiz = finite(spec.squiz, `${name} squiz`);
   return Object.freeze(out);
 }
 
@@ -450,6 +1336,106 @@ export type AutomationInput = Readonly<{
   delayFeedback?: readonly Point[];
   /** 0..1 (needs `delay`). */
   delayMix?: readonly Point[];
+  /**
+   * Effect parameter lanes keyed `<effect>-<param>`, e.g.
+   * `"autofilter-cutoff"`, `"distort-drive"`, `"reverb-mix"` (needs the effect).
+   */
+  fx?: Readonly<Record<string, readonly Point[]>>;
+  /** Wavetable position 0..1 (needs `wavetable()`). */
+  wt?: readonly Point[];
+}>;
+
+/** One effect's parameters; omitted ones take dawg's defaults. */
+export type EffectParams = Readonly<Record<string, number | string | boolean>>;
+
+/**
+ * Insert effects by name, rendered in the fixed chain order
+ * filter → djf → autofilter → vowel → crush → distort → tremolo →
+ * compressor → pan → phaser → chorus → leslie → postgain → delay → reverb.
+ * Keys here: djf, autofilter, vowel, crush, distort, tremolo, compressor,
+ * phaser, chorus, leslie, postgain, plus the mix-bus keys `orbit`
+ * (`{ orbit: 2 }`, SDK 1.9.0) and `duck` (`{ orbit: 2, depth: 0.85 }`:
+ * this track's onsets duck every other track on that orbit). See
+ * docs/project-format.md for every parameter, its range and its Strudel name.
+ */
+export type FxInput = Readonly<Record<string, EffectParams>>;
+
+/**
+ * Synth voice parameters by Strudel name; only the ones given are stored
+ * and the rest take dawg's defaults. Lanes go under `automation.fx` as
+ * `"synth-<param>"` (e.g. `"synth-lpf"`), read at each note's onset.
+ * Every parameter, range and default: **Synth** in DAWG.md.
+ */
+export type SynthInput = Readonly<{
+  attack?: number;
+  decay?: number;
+  sustain?: number;
+  release?: number;
+  gain?: number;
+  /** Pink noise mixed into the oscillator, 0..1. */
+  noise?: number;
+  /** Crackle impulse density. */
+  density?: number;
+  /** Unison voices (supersaw defaults to 5). */
+  unison?: number;
+  /** Unison detune spread in semitones. */
+  detune?: number;
+  /** Stereo spread of the unison voices, 0..1. */
+  spread?: number;
+  /** Pulse width 0..1 (`pulse`). */
+  pw?: number;
+  pwrate?: number;
+  pwsweep?: number;
+  /** Vibrato rate (Hz) and depth (semitones). */
+  vib?: number;
+  vibmod?: number;
+  /** Pitch envelope depth (semitones) and shape. */
+  penv?: number;
+  pattack?: number;
+  pdecay?: number;
+  psustain?: number;
+  prelease?: number;
+  pcurve?: number;
+  panchor?: number;
+  lpf?: number;
+  lpq?: number;
+  lpenv?: number;
+  hpf?: number;
+  hpq?: number;
+  hpenv?: number;
+  bpf?: number;
+  bpq?: number;
+  bpenv?: number;
+  /** `12db`, `24db` or `ladder`. */
+  ftype?: string;
+  /** FM index and harmonicity ratio; `fm2`…`fm8` add operators. */
+  fm?: number;
+  fmh?: number;
+  fmattack?: number;
+  fmdecay?: number;
+  fmsustain?: number;
+  fmrelease?: number;
+  /** `lin` or `exp`. */
+  fmenv?: string;
+  /** `sine`, `sawtooth`, `square` or `triangle`. */
+  fmwave?: string;
+  /** Harmonic amplitudes for `user` (or any basic waveform). */
+  partials?: readonly number[];
+  phases?: readonly number[];
+  /** ZzFX controls for `z_*` sounds (units: DAWG.md "Synth"). */
+  zrand?: number;
+  curve?: number;
+  slide?: number;
+  deltaSlide?: number;
+  pitchJump?: number;
+  pitchJumpTime?: number;
+  lfo?: number;
+  zmod?: number;
+  zcrush?: number;
+  zdelay?: number;
+  tremolo?: number;
+  /** Any other Strudel synth parameter, e.g. `lpattack`, `fmh3`. */
+  [param: string]: number | string | boolean | readonly number[] | undefined;
 }>;
 
 /** Input to `track()`. Omitted fields keep dawg's defaults. */
@@ -460,9 +1446,20 @@ export type TrackInput = Readonly<{
   name: string;
   /**
    * Synth voice (`sine`, `piano`, `pluck`, `bass`, `saw`, `square`,
-   * `triangle`), `kit` for drums, or `sampler(...)`. Default `sine`.
+   * `triangle`, and Strudel's `sawtooth`, `supersaw`, `pulse`, `user`,
+   * `white`, `pink`, `brown`, `crackle`, and the ZzFX sounds `z_sine`,
+   * `z_triangle`, `z_sawtooth`, `z_square`, `z_tan`, `z_noise`), `kit` for drums,
+   * `sampler(...)` or `wavetable(...)`. Default `sine`.
+   */
+  instrument?: string | SamplerSpec | WavetableSpec;
+  /**
+   * Synthesized drum kit for an `instrument: "kit"` track: `syn808`,
+   * `syn909`, `acoustic`, `lofi`, `electro` or `trap`. Omit for the default
+   * voices.
    */
-  instrument?: string | SamplerSpec;
+  kit?: string;
+  /** Synth voice parameters, Strudel names (`{ attack: 0.01, lpf: 800 }`). */
+  synth?: SynthInput;
   muted?: boolean;
   /** When any track is soloed only soloed tracks play. */
   solo?: boolean;
@@ -470,15 +1467,70 @@ export type TrackInput = Readonly<{
   volume?: number;
   /** -1 (left) .. 1 (right), default 0. */
   pan?: number;
-  /** Low-pass filter; `null` or omitted means none. */
-  filter?: Readonly<{ cutoff: number; resonance?: number }> | null;
-  /** Tempo-synced ping-pong delay send in beats. */
-  delay?: Readonly<{ beats: number; feedback?: number; mix?: number }> | null;
+  /** Filter (low-pass unless `type`); `null` or omitted means none. */
+  filter?: FilterInput | null;
+  /** Tempo-synced delay send in beats. */
+  delay?: DelayInput | null;
   /** Stereo reverb send. */
-  reverb?: Readonly<{ mix: number; size?: number }> | null;
+  reverb?: ReverbInput | null;
+  /** Insert effects by name (`{ distort: { drive: 3 }, chorus: {} }`). */
+  fx?: FxInput;
   automation?: AutomationInput;
   /** `note()`/`seq()` for pitched tracks, `hit()`/`hits()` for kits and one-shot samplers. */
   notes?: readonly (NoteSpec | HitSpec)[];
+  /**
+   * Generated voices, one row per voice: `euclid()`/`grid()`. dawg expands
+   * them into hits when the song loads; a row owns its voice, so `notes`
+   * on the same voice are replaced.
+   */
+  rhythm?: readonly RhythmSpec[];
+}>;
+
+export type FilterInput = Readonly<{
+  cutoff: number;
+  resonance?: number;
+  /** `lpf` (default), `hpf` or `bpf`. */
+  type?: "lpf" | "hpf" | "bpf";
+  /** Slope: `12db` (default), `24db` or `ladder`. */
+  ftype?: "12db" | "24db" | "ladder";
+}>;
+
+export type DelayInput = Readonly<{
+  beats: number;
+  feedback?: number;
+  mix?: number;
+  /** Seconds; overrides `beats` when set (Strudel `delaytime`). */
+  time?: number;
+  /** Repeats alternate left/right. */
+  pingpong?: boolean;
+  /** Low-pass on the repeats, Hz. */
+  highcut?: number;
+}>;
+
+export type ReverbInput = Readonly<{
+  mix: number;
+  size?: number;
+  /** Decay to -60 dB in seconds (Strudel `roomfade`). */
+  fade?: number;
+  /** Low-pass on the input, Hz (Strudel `roomlp`). */
+  lowpass?: number;
+  /** Damping toward this Hz as the tail decays (Strudel `roomdim`). */
+  dim?: number;
+  /** Seconds before the tail. */
+  predelay?: number;
+  /**
+   * Convolution reverb (Strudel `iresponse`/`ir`): `"room"`, `"hall"`,
+   * `"plate"` (generated), a pack sound `pack:<pack>/<sound>[:<n>]` or a
+   * track-relative audio file. `size`, `fade` and `dim` then do nothing.
+   */
+  ir?:
+    | string
+    | Readonly<{
+        src: string;
+        sha256?: string;
+        url?: string;
+        license?: string;
+      }>;
 }>;
 
 /** Frozen track built by `track()`; `song()` consumes it. Beats, not ticks. */
@@ -492,15 +1544,97 @@ export type TrackSpec = Readonly<{
   solo: boolean;
   volume: number;
   pan: number;
-  filter: Readonly<{ cutoff: number; resonance: number }> | null;
-  delay: Readonly<{ beats: number; feedback: number; mix: number }> | null;
-  reverb: Readonly<{ mix: number; size: number }> | null;
+  filter: Readonly<
+    { cutoff: number; resonance: number } & Partial<FilterInput>
+  > | null;
+  delay: Readonly<
+    { beats: number; feedback: number; mix: number } & Partial<DelayInput>
+  > | null;
+  reverb: Readonly<{ mix: number; size: number } & Partial<ReverbInput>> | null;
+  fx: FxInput | null;
+  synth: SynthInput | null;
   sampler: SamplerSpec | null;
+  wavetable: WavetableSpec | null;
   automation: Readonly<Required<AutomationInput>>;
   /** Every hit resolved to its pitch slot. */
   notes: readonly NoteSpec[];
+  /** Rhythm rows in order (voice names as written). */
+  rhythm: readonly RhythmSpec[];
+  kit: string | null;
 }>;
 
+/**
+ * A raw ZzFX parameter array (Strudel `zzfx([...])`, ZzFX's own layout:
+ * volume, randomness, frequency, attack, sustain, release, shape,
+ * shapeCurve, slide, deltaSlide, pitchJump, pitchJumpTime, repeatTime,
+ * noise, modulation, bitCrush, delay, sustainVolume, decay, tremolo,
+ * filter) as a `z_*` instrument and synth parameters to spread into a
+ * track. Empty slots take ZzFX's defaults; frequency and sustain time come
+ * from each note. `filter` > 0 is a high-pass in Hz, < 0 a low-pass.
+ *
+ * ```ts
+ * track({ name: "blip", ...zzfx([, , , 0.01, , 0.15, 2, , 5]), notes })
+ * ```
+ */
+export function zzfx(
+  values: readonly (number | null | undefined)[],
+): Readonly<{ instrument: string; synth: SynthInput }> {
+  if (!Array.isArray(values) || values.length > ZZFX_LAYOUT.length)
+    throw new DawgSdkError(
+      `zzfx takes an array of at most ${ZZFX_LAYOUT.length} numbers`,
+    );
+  const synth: Record<string, number> = {
+    zrand: 0.05,
+    attack: 0,
+    release: 0.1,
+  };
+  let instrument = "z_sine";
+  ZZFX_LAYOUT.forEach((name, index) => {
+    const value: unknown = values[index];
+    if (name === null || value === undefined || value === null) return;
+    const n = finite(value, `zzfx[${index}]`);
+    if (name === "shape")
+      instrument = ZZFX_SHAPES[Math.max(0, Math.min(5, Math.round(n)))]!;
+    else if (name === "filter") {
+      if (n !== 0) synth[n > 0 ? "hpf" : "lpf"] = Math.abs(n);
+    } else synth[name] = n;
+  });
+  return Object.freeze({ instrument, synth: Object.freeze(synth) });
+}
+
+const ZZFX_LAYOUT = Object.freeze([
+  "gain",
+  "zrand",
+  null,
+  "attack",
+  null,
+  "release",
+  "shape",
+  "curve",
+  "slide",
+  "deltaSlide",
+  "pitchJump",
+  "pitchJumpTime",
+  "lfo",
+  "noise",
+  "zmod",
+  "zcrush",
+  "zdelay",
+  "sustain",
+  "decay",
+  "tremolo",
+  "filter",
+] as const);
+
+const ZZFX_SHAPES = Object.freeze([
+  "z_sine",
+  "z_triangle",
+  "z_sawtooth",
+  "z_tan",
+  "z_noise",
+  "z_square",
+] as const);
+
 /**
  * Build a track. Hits are resolved to pitches here: GM numbers on a kit,
  * voice slots (36, 37, … in voice-name order) on a one-shot sampler.
@@ -523,18 +1657,24 @@ export function track(input: TrackInput): TrackSpec {
     isRecord(rawInstrument) && rawInstrument.kind === "sampler"
       ? localizeSampler(rawInstrument as SamplerSpec, slug)
       : null;
+  const wavetableSpec =
+    isRecord(rawInstrument) && rawInstrument.kind === "wavetable"
+      ? localizeWavetable(rawInstrument as WavetableSpec, slug)
+      : null;
   const instrument = samplerSpec
     ? SAMPLER_INSTRUMENT
-    : typeof rawInstrument === "string"
-      ? rawInstrument
-      : undefined;
+    : wavetableSpec
+      ? WAVETABLE_INSTRUMENT
+      : typeof rawInstrument === "string"
+        ? rawInstrument
+        : undefined;
   if (
     instrument === undefined ||
     instrument.length === 0 ||
     instrument.length > 64
   )
     throw new DawgSdkError(
-      `track ${name}: instrument must be a voice name, "kit" or sampler(...)`,
+      `track ${name}: instrument must be a voice name, "kit", sampler(...) or wavetable(...)`,
     );
   if (instrument === SAMPLER_INSTRUMENT && !samplerSpec)
     throw new DawgSdkError(
@@ -573,10 +1713,29 @@ export function track(input: TrackInput): TrackSpec {
   });
   if (notes.length > 4096)
     throw new DawgSdkError(`track ${name}: at most 4096 notes`);
+  const rhythm = input.rhythm ?? [];
+  if (!Array.isArray(rhythm) || rhythm.length > 16)
+    throw new DawgSdkError(`track ${name}: rhythm must be at most 16 rows`);
+  rhythm.forEach((row, index) => {
+    if (!isRecord(row) || row.kind !== "rhythm")
+      throw new DawgSdkError(
+        `track ${name}: rhythm[${index}] must come from euclid() or grid()`,
+      );
+  });
+  const drumKit = input.kit ?? null;
+  if (
+    drumKit !== null &&
+    (typeof drumKit !== "string" || drumKit.trim().length === 0 || !kit)
+  )
+    throw new DawgSdkError(
+      `track ${name}: kit needs instrument "kit" and a kit name`,
+    );
   const automation = input.automation ?? {};
   if (!isRecord(automation))
     throw new DawgSdkError(`track ${name}: automation must be an object`);
-  const lane = (key: keyof AutomationInput): readonly Point[] => {
+  const lane = (
+    key: Exclude<keyof AutomationInput, "fx">,
+  ): readonly Point[] => {
     const points = (automation as Record<string, unknown>)[key];
     if (points === undefined) return Object.freeze([]);
     if (!Array.isArray(points) || points.length > 256)
@@ -610,6 +1769,7 @@ export function track(input: TrackInput): TrackSpec {
             input.filter.resonance ?? 0,
             `${name} filter.resonance`,
           ),
+          ...extras(input.filter, ["type", "ftype"], `${name} filter`),
         });
   const delay =
     input.delay === undefined || input.delay === null
@@ -621,6 +1781,11 @@ export function track(input: TrackInput): TrackSpec {
             `${name} delay.feedback`,
           ),
           mix: finite(input.delay.mix ?? 0.35, `${name} delay.mix`),
+          ...extras(
+            input.delay,
+            ["time", "pingpong", "highcut"],
+            `${name} delay`,
+          ),
         });
   const reverb =
     input.reverb === undefined || input.reverb === null
@@ -628,7 +1793,17 @@ export function track(input: TrackInput): TrackSpec {
       : Object.freeze({
           mix: finite(input.reverb.mix, `${name} reverb.mix`),
           size: finite(input.reverb.size ?? 0.5, `${name} reverb.size`),
+          ...extras(
+            input.reverb,
+            ["fade", "lowpass", "dim", "predelay"],
+            `${name} reverb`,
+          ),
+          ...(input.reverb.ir === undefined
+            ? {}
+            : { ir: reverbIr(input.reverb.ir, name, slug) }),
         });
+  const fx = fxInput(input.fx, name);
+  const synth = synthInput(input.synth, name);
   return Object.freeze({
     kind: "track",
     id,
@@ -642,7 +1817,10 @@ export function track(input: TrackInput): TrackSpec {
     filter,
     delay,
     reverb,
+    fx,
+    synth,
     sampler: samplerSpec,
+    wavetable: wavetableSpec,
     automation: Object.freeze({
       volume: lane("volume"),
       pan: lane("pan"),
@@ -650,8 +1828,12 @@ export function track(input: TrackInput): TrackSpec {
       resonance: lane("resonance"),
       delayFeedback: lane("delayFeedback"),
       delayMix: lane("delayMix"),
+      fx: fxLanes(automation.fx, name),
+      wt: lane("wt"),
     }),
     notes: Object.freeze(notes),
+    rhythm: Object.freeze([...rhythm]),
+    kit: drumKit === null ? null : drumKit.trim(),
   });
 }
 
@@ -662,8 +1844,92 @@ const AUTOMATION_KEYS: readonly (keyof AutomationInput)[] = Object.freeze([
   "resonance",
   "delayFeedback",
   "delayMix",
+  "fx",
+  "wt",
 ]);
 
+type EffectValue = number | string | boolean;
+
+function effectValue(value: unknown, label: string): EffectValue {
+  if (typeof value === "string" || typeof value === "boolean") return value;
+  return finite(value, label);
+}
+
+/** The optional effect fields that are set; dawg validates their ranges. */
+function extras(
+  input: object,
+  keys: readonly string[],
+  label: string,
+): Record<string, EffectValue> {
+  const out: Record<string, EffectValue> = {};
+  for (const key of keys) {
+    const value = (input as Record<string, unknown>)[key];
+    if (value !== undefined) out[key] = effectValue(value, `${label}.${key}`);
+  }
+  return out;
+}
+
+function fxInput(input: unknown, name: string): FxInput | null {
+  if (input === undefined || input === null) return null;
+  if (!isRecord(input))
+    throw new DawgSdkError(`track ${name}: fx must be an object of effects`);
+  const out: Record<string, EffectParams> = {};
+  for (const [effect, params] of Object.entries(input)) {
+    if (!isRecord(params))
+      throw new DawgSdkError(`track ${name}: fx.${effect} must be an object`);
+    const values: Record<string, EffectValue> = {};
+    for (const [key, value] of Object.entries(params))
+      values[key] = effectValue(value, `${name} fx.${effect}.${key}`);
+    out[effect] = Object.freeze(values);
+  }
+  return Object.keys(out).length > 0 ? Object.freeze(out) : null;
+}
+
+function synthInput(input: unknown, name: string): SynthInput | null {
+  if (input === undefined || input === null) return null;
+  if (!isRecord(input))
+    throw new DawgSdkError(`track ${name}: synth must be an object`);
+  const out: Record<string, EffectValue | readonly number[]> = {};
+  for (const [key, value] of Object.entries(input)) {
+    if (value === undefined) continue;
+    out[key] = Array.isArray(value)
+      ? Object.freeze(
+          value.map((n, index) => finite(n, `${name} synth.${key}[${index}]`)),
+        )
+      : effectValue(value, `${name} synth.${key}`);
+  }
+  return Object.keys(out).length > 0 ? Object.freeze(out) : null;
+}
+
+function fxLanes(
+  input: unknown,
+  name: string,
+): Readonly<Record<string, readonly Point[]>> {
+  if (input === undefined) return Object.freeze({});
+  if (!isRecord(input))
+    throw new DawgSdkError(`track ${name}: automation.fx must be an object`);
+  const out: Record<string, readonly Point[]> = {};
+  for (const [key, points] of Object.entries(input)) {
+    if (!Array.isArray(points) || points.length > 256)
+      throw new DawgSdkError(
+        `track ${name}: automation.fx["${key}"] must be an array of at most 256 [beat, value] points`,
+      );
+    out[key] = Object.freeze(
+      points.map((point: unknown, index: number): Point => {
+        if (!Array.isArray(point) || point.length !== 2)
+          throw new DawgSdkError(
+            `track ${name}: automation.fx["${key}"][${index}] must be [beat, value]`,
+          );
+        return Object.freeze([
+          beat(point[0], `automation.fx["${key}"][${index}] beat`),
+          finite(point[1], `automation.fx["${key}"][${index}] value`),
+        ] as const);
+      }),
+    );
+  }
+  return Object.freeze(out);
+}
+
 /**
  * Directory name for a track: lowercase, spaces and runs of punctuation
  * become one `-` (`"Keys 2"` → `keys-2`); empty input becomes `track`.
@@ -691,13 +1957,55 @@ export function voiceSlots(spec: SamplerSpec): ReadonlyMap<string, number> {
   return slots;
 }
 
+/** `reverb.ir`: built-in names stay bare; files become project-relative. */
+function reverbIr(
+  value: unknown,
+  name: string,
+  slug: string,
+):
+  | string
+  | Readonly<{ src: string; sha256?: string; url?: string; license?: string }> {
+  const spec = typeof value === "string" ? { src: value } : value;
+  if (!isRecord(spec) || typeof spec.src !== "string" || spec.src.length === 0)
+    throw new DawgSdkError(`track ${name}: reverb.ir needs a src`);
+  const src = spec.src.trim().replace(/^\.\//, "");
+  if (src.startsWith("pack:")) {
+    const ref = sample(spec as SampleSpec, `${name} reverb.ir`);
+    return Object.freeze({
+      src: ref.src,
+      ...(ref.sha256 ? { sha256: ref.sha256 } : {}),
+      ...(ref.url ? { url: ref.url } : {}),
+      ...(ref.license ? { license: ref.license } : {}),
+    });
+  }
+  if (src.startsWith("builtin:") || !/[./]/.test(src)) return src;
+  return src.startsWith("tracks/") ? src : `tracks/${slug}/${src}`;
+}
+
+/** `./wavetables/x.wav` → `tracks/<slug>/wavetables/x.wav`, like sampler files. */
+function localizeWavetable(spec: WavetableSpec, slug: string): WavetableSpec {
+  const src = spec.table.src;
+  if (!/\.wav$/i.test(src) || src.startsWith("pack:")) return spec;
+  const bare = src.replace(/^\.\//, "");
+  return Object.freeze({
+    ...spec,
+    table: Object.freeze({
+      ...spec.table,
+      src: bare.startsWith("tracks/") ? bare : `tracks/${slug}/${bare}`,
+    }),
+  });
+}
+
 function localizeSampler(spec: SamplerSpec, slug: string): SamplerSpec {
   const voices: Record<string, SampleSpec> = {};
   for (const [name, voice] of Object.entries(spec.voices)) {
     const src = voice.src.replace(/^\.\//, "");
     voices[name] = Object.freeze({
       ...voice,
-      src: src.startsWith("tracks/") ? src : `tracks/${slug}/${src}`,
+      src:
+        src.startsWith("tracks/") || src.startsWith("pack:")
+          ? src
+          : `tracks/${slug}/${src}`,
     });
   }
   return Object.freeze({ ...spec, voices: Object.freeze(voices) });
@@ -739,6 +2047,8 @@ export type ScorePoint = Readonly<{ tick: number; value: number }>;
 export type ScoreSampleRef = Readonly<{
   src: string;
   sha256?: string;
+  url?: string;
+  license?: string;
   root?: number;
   begin?: number;
   end?: number;
@@ -746,6 +2056,13 @@ export type ScoreSampleRef = Readonly<{
   speed?: number;
   loop?: boolean;
   choke?: string;
+  loopBegin?: number;
+  loopEnd?: number;
+  clip?: number;
+  unit?: "r" | "c" | "s";
+  fit?: boolean;
+  accelerate?: number;
+  squiz?: number;
 }>;
 
 /** A stored track; optional fields are present only when set. */
@@ -759,17 +2076,26 @@ export type ScoreTrack = Readonly<{
   volumeAutomation: readonly ScorePoint[];
   panAutomation: readonly ScorePoint[];
   solo?: boolean;
-  filter?: Readonly<{ cutoff: number; resonance: number }>;
-  delay?: Readonly<{ beats: number; feedback: number; mix: number }>;
+  filter?: TrackSpec["filter"] & object;
+  delay?: TrackSpec["delay"] & object;
   filterAutomation?: readonly ScorePoint[];
   resonanceAutomation?: readonly ScorePoint[];
   delayFeedbackAutomation?: readonly ScorePoint[];
   delayMixAutomation?: readonly ScorePoint[];
-  reverb?: Readonly<{ mix: number; size: number }>;
+  reverb?: TrackSpec["reverb"] & object;
+  fx?: FxInput;
+  fxAutomation?: Readonly<Record<string, readonly ScorePoint[]>>;
+  synth?: SynthInput;
   sampler?: Readonly<{
     voices: Readonly<Record<string, ScoreSampleRef>>;
     mode: "oneshot" | "keyed";
   }>;
+  /** Rhythm rows without `kind`; dawg validates and expands them. */
+  rhythm?: readonly Readonly<Record<string, unknown>>[];
+  /** Synth kit name; dawg validates it. */
+  kit?: string;
+  wavetable?: Readonly<{ table: ScoreSampleRef } & WavetableParams>;
+  wtAutomation?: readonly ScorePoint[];
 }>;
 
 /**
@@ -836,6 +2162,7 @@ export function song(input: SongInput): Song {
     const resonanceAutomation = points(t.automation.resonance);
     const delayFeedbackAutomation = points(t.automation.delayFeedback);
     const delayMixAutomation = points(t.automation.delayMix);
+    const wtAutomation = points(t.automation.wt ?? []);
     const stored: Record<string, unknown> = {
       id: t.id,
       name: t.name,
@@ -857,11 +2184,31 @@ export function song(input: SongInput): Song {
     if (delayMixAutomation.length > 0)
       stored.delayMixAutomation = delayMixAutomation;
     if (t.reverb) stored.reverb = t.reverb;
+    if (t.fx) stored.fx = t.fx;
+    if (t.synth) stored.synth = t.synth;
+    const fxLaneEntries = Object.entries(t.automation.fx ?? {})
+      .map(([key, lane]) => [key, points(lane)] as const)
+      .filter(([, lane]) => lane.length > 0);
+    if (fxLaneEntries.length > 0)
+      stored.fxAutomation = Object.freeze(Object.fromEntries(fxLaneEntries));
+    if (t.wavetable) {
+      const { kind: _kind, ...fields } = t.wavetable;
+      stored.wavetable = Object.freeze(fields);
+    }
+    if (wtAutomation.length > 0) stored.wtAutomation = wtAutomation;
     if (t.sampler)
       stored.sampler = Object.freeze({
         voices: t.sampler.voices,
         mode: t.sampler.mode,
       });
+    if (t.kit) stored.kit = t.kit;
+    if (t.rhythm && t.rhythm.length > 0)
+      stored.rhythm = Object.freeze(
+        t.rhythm.map((row) => {
+          const { kind: _kind, ...fields } = row;
+          return Object.freeze(fields);
+        }),
+      );
     tracks.push(Object.freeze(stored) as ScoreTrack);
     const ids = new Set<string>();
     for (const n of t.notes) {
@@ -898,6 +2245,1858 @@ export function song(input: SongInput): Song {
   });
 }
 
+// ---------------------------------------------------------------------------
+// Chords
+
+/** Options shared by `chord()` and `progression()`. */
+export type ChordOptions = Readonly<{
+  /** Voicing dial: each step moves the lowest note up an octave (negative: the highest down), -12..12. */
+  voicing?: number;
+  /** `close` (default), `open` (drop 2) or `wide` (drop 2 and 4). */
+  spread?: "close" | "open" | "wide";
+  /** `block` (default), `strum-up`, `strum-down`, `arp-up`, `arp-down`, `arp-updown`, `arp-random`, `harp`, `slop`, `pattern` (SDK 1.7.0). */
+  perform?:
+    | "block"
+    | "strum-up"
+    | "strum-down"
+    | "arp-up"
+    | "arp-down"
+    | "arp-updown"
+    | "arp-random"
+    | "harp"
+    | "slop"
+    | "pattern";
+  /**
+   * With `perform: "pattern"`: a rhythm pattern by name or 1-based number
+   * (SDK 1.7.0): `eighths`, `sixteenths`, `offbeat`, `pop`, `charleston`,
+   * `bossa`, `skank`, `gallop`, `half-time`, `tresillo`, `oom-pah`, `roll`,
+   * `pick`. Default 1.
+   */
+  pattern?: string | number;
+  /** Arpeggio step in beats, default 0.25. */
+  rate?: number;
+  /** Arpeggio/harp octaves 1..4, default 1. */
+  octaves?: number;
+  /** Strum gap between voices in beats, default 1/32. */
+  strum?: number;
+  /** Seed for `arp-random`, default 0. */
+  seed?: number;
+  /** Velocity, default 0.8. */
+  vel?: number;
+  /** Lowest root position: the root lands at or above this pitch, default C4. */
+  anchor?: Pitch;
+  /** `chords` (default), `bass` (root or slash bass in octave 2, one per chord) or `both`. */
+  part?: "chords" | "bass" | "both";
+  /**
+   * Orchid bass mode (SDK 1.7.0; overrides `part`): `off` (chords only),
+   * `chords` and `single` (chords plus root or slash bass), `unison`
+   * (chords plus the chord's root, ignoring a slash) or `solo` (bass only).
+   */
+  bass?: "off" | "chords" | "unison" | "single" | "solo";
+}>;
+
+/** Options for `progression()`. */
+export type ProgressionOptions = ChordOptions &
+  Readonly<{
+    /** Key the numerals read in: `"C major"`, `"a minor"`, `"F# dorian"`; default C major. */
+    key?: string;
+    /** Beat of the first chord, default 0. */
+    from?: number;
+    /** Beats per chord, default 4. */
+    each?: number;
+    /** Voice-lead each chord to the inversion nearest the previous, default true. */
+    lead?: boolean;
+  }>;
+
+/**
+ * One chord from a symbol (`"Cm7"`, `"F#dim"`, `"Bbmaj9"`, `"G7sus4"`,
+ * `"C/E"`) as notes from `start` for `length` beats.
+ *
+ * ```ts
+ * notes: [...chord("Am7", 0, 4), ...chord("D9", 4, 4, { perform: "strum-up" })]
+ * ```
+ */
+export function chord(
+  symbol: string,
+  start = 0,
+  length = 4,
+  options: ChordOptions = {},
+): readonly NoteSpec[] {
+  if (typeof symbol !== "string" || parseChord(symbol) === undefined)
+    throw new DawgSdkError(`unknown chord symbol ${JSON.stringify(symbol)}`);
+  return progression([symbol], {
+    ...options,
+    from: start,
+    each: length,
+    lead: false,
+  });
+}
+
+/**
+ * A voice-led progression: roman numerals in `key` (`"ii7"`, `"V"`,
+ * `"bVII"`, `"V/V"`) or chord symbols, as an array or a space-separated
+ * string, one chord per `each` beats from `from`. Each chord takes the
+ * inversion nearest the previous one, so common tones hold. Same input,
+ * same notes; dawg's play mode and agent tools use the same engine.
+ *
+ * ```ts
+ * notes: progression("ii7 V7 Imaj7 Imaj7", { key: "C major", perform: "arp-up", rate: 0.5 })
+ * notes: progression(["i", "VI", "III", "VII"], { key: "a minor", part: "bass" })
+ * ```
+ */
+export function progression(
+  chords: string | readonly string[],
+  options: ProgressionOptions = {},
+): readonly NoteSpec[] {
+  const symbols =
+    typeof chords === "string" ? chords.trim().split(/\s+/) : [...chords];
+  if (symbols.length === 0 || symbols.length > 256 || symbols[0] === "")
+    throw new DawgSdkError("progression needs 1..256 chords");
+  const key = parseKey(options.key ?? "C major");
+  if (!key)
+    throw new DawgSdkError(`unknown key ${JSON.stringify(options.key)}`);
+  const parsed = symbols.map((symbol) => {
+    const value =
+      typeof symbol === "string" ? resolveChord(key, symbol) : undefined;
+    if (!value)
+      throw new DawgSdkError(
+        `unknown chord ${JSON.stringify(symbol)} (roman numeral or symbol)`,
+      );
+    return value;
+  });
+  const from = beat(options.from ?? 0, "progression from");
+  const each = positive(options.each ?? 4, "progression each");
+  const vel = unit(options.vel ?? DEFAULT_VELOCITY, "chord vel");
+  const voicing = finite(options.voicing ?? 0, "chord voicing");
+  const spread = options.spread ?? "close";
+  if (!(SPREADS as readonly string[]).includes(spread))
+    throw new DawgSdkError('chord spread must be "close", "open" or "wide"');
+  const mode = options.perform ?? "block";
+  if (!(PERFORM_MODES as readonly string[]).includes(mode))
+    throw new DawgSdkError(`unknown chord perform ${JSON.stringify(mode)}`);
+  if (
+    options.bass !== undefined &&
+    !(BASS_MODES as readonly string[]).includes(options.bass)
+  )
+    throw new DawgSdkError(
+      `chord bass must be one of ${BASS_MODES.map((m) => JSON.stringify(m)).join(", ")}`,
+    );
+  if (options.pattern !== undefined && !findChordPattern(options.pattern))
+    throw new DawgSdkError(
+      `unknown chord pattern ${JSON.stringify(options.pattern)} (1..${CHORD_PATTERNS.length} or ${CHORD_PATTERNS.map((p) => p.name).join(", ")})`,
+    );
+  const part =
+    options.bass === undefined
+      ? (options.part ?? "chords")
+      : options.bass === "off"
+        ? "chords"
+        : options.bass === "solo"
+          ? "bass"
+          : "both";
+  if (part !== "chords" && part !== "bass" && part !== "both")
+    throw new DawgSdkError('chord part must be "chords", "bass" or "both"');
+  const rendered = renderProgression({
+    key,
+    chords: parsed,
+    beatsPerChord: each,
+    start: from,
+    inversion: voicing,
+    spread,
+    bass: part !== "chords",
+    ...(options.bass === "unison" ? { bassMode: "unison" as const } : {}),
+    lead: options.lead ?? true,
+    anchor: midi(options.anchor ?? 60),
+    perform: {
+      mode,
+      rate: positive(options.rate ?? DEFAULT_ARP_RATE, "chord rate"),
+      octaves: finite(options.octaves ?? 1, "chord octaves"),
+      ...(options.strum !== undefined
+        ? { strum: beat(options.strum, "chord strum") }
+        : {}),
+      seed: finite(options.seed ?? 0, "chord seed"),
+      ...(options.pattern !== undefined ? { pattern: options.pattern } : {}),
+      velocity: vel,
+    },
+  });
+  const out = [
+    ...(part === "bass" ? [] : rendered.notes),
+    ...(part === "chords" ? [] : rendered.bass),
+  ];
+  if (out.length > 4096)
+    throw new DawgSdkError("progression would produce over 4096 notes");
+  return Object.freeze(
+    out.map((n) => note(n.pitch, round(n.start), n.length, n.velocity)),
+  );
+}
+
+// BEGIN chord engine: generated from core/chords.ts by core/sdk/sync-chords.ts
+// ---------------------------------------------------------------------------
+// Vocabulary
+
+/** The four Orchid chord-type buttons. */
+const CHORD_TYPES = ["dim", "min", "maj", "sus"] as const;
+type ChordType = (typeof CHORD_TYPES)[number];
+
+/** The four Orchid extension buttons. */
+const EXTENSIONS = ["6", "m7", "M7", "9"] as const;
+type Extension = (typeof EXTENSIONS)[number];
+
+/** Triad qualities: the four buttons plus dawg's two-button combinations. */
+const QUALITIES = [
+  "maj",
+  "min",
+  "dim",
+  "sus4",
+  "aug",
+  "sus2",
+  "5",
+  "madd4",
+  "mb6",
+  "b6",
+  "7#9",
+] as const;
+type Quality = (typeof QUALITIES)[number];
+
+const QUALITY_INTERVALS: Readonly<Record<Quality, readonly number[]>> =
+  Object.freeze({
+    maj: [0, 4, 7],
+    min: [0, 3, 7],
+    dim: [0, 3, 6],
+    sus4: [0, 5, 7],
+    aug: [0, 4, 8],
+    sus2: [0, 2, 7],
+    "5": [0, 7],
+    madd4: [0, 3, 5, 7],
+    mb6: [0, 3, 7, 8],
+    b6: [0, 4, 7, 8],
+    "7#9": [0, 4, 7, 10, 15],
+  });
+
+/**
+ * The extension button a secret chord is built with: it is part of the
+ * chord, so `makeChord` drops it rather than stacking it again.
+ */
+const SECRET_EXTENSION: Readonly<Partial<Record<Quality, Extension>>> =
+  Object.freeze({ mb6: "6", b6: "6", "7#9": "m7" });
+
+const EXTENSION_INTERVAL: Readonly<Record<Extension, number>> = Object.freeze({
+  "6": 9,
+  m7: 10,
+  M7: 11,
+  "9": 14,
+});
+
+/**
+ * Two chord-type buttons held together: Orchid's "secret chords" (manual
+ * section 14.8). min+dim and maj+dim are listed with the 6 button and
+ * maj+min with m7; dawg plays them without it too.
+ */
+const COMBINED_TYPES: Readonly<Record<string, Quality>> = Object.freeze({
+  "dim+sus": "5",
+  "maj+sus": "aug",
+  "min+sus": "madd4",
+  "dim+min": "mb6",
+  "dim+maj": "b6",
+  "maj+min": "7#9",
+});
+
+/** Quality for a set of held chord-type buttons, or undefined for none. */
+function qualityOf(types: Iterable<ChordType>): Quality | undefined {
+  const held = [...new Set(types)].sort();
+  if (held.length === 0) return undefined;
+  if (held.length === 1) return held[0] === "sus" ? "sus4" : held[0]!;
+  return COMBINED_TYPES[held.slice(0, 2).join("+")] ?? "maj";
+}
+
+/** A chord: root pitch class, triad quality, extensions, optional bass. */
+type Chord = Readonly<{
+  /** 0..11, C = 0. */
+  root: number;
+  quality: Quality;
+  extensions: readonly Extension[];
+  /** Slash bass pitch class, when not the root. */
+  bass?: number | undefined;
+}>;
+
+function makeChord(
+  root: number,
+  quality: Quality,
+  extensions: Iterable<Extension> = [],
+  bass?: number,
+): Chord {
+  const held = new Set(extensions);
+  const own = SECRET_EXTENSION[quality];
+  const ext = EXTENSIONS.filter((value) => held.has(value) && value !== own);
+  const pc = mod12(root);
+  const slash = bass === undefined ? undefined : mod12(bass);
+  return Object.freeze({
+    root: pc,
+    quality,
+    extensions: Object.freeze(ext),
+    ...(slash !== undefined && slash !== pc ? { bass: slash } : {}),
+  });
+}
+
+/** Semitones above the root, ascending and unique (9 sits at 14). */
+function chordIntervals(chord: Chord): number[] {
+  const set = new Set(QUALITY_INTERVALS[chord.quality]);
+  for (const ext of chord.extensions) set.add(EXTENSION_INTERVAL[ext]);
+  // m7 and M7 together keep both; 6 with m7 on a dim triad is the dim7's bb7.
+  return [...set].sort((a, b) => a - b);
+}
+
+/** Pitch classes of the chord (bass excluded), root first. */
+function chordPitchClasses(chord: Chord): number[] {
+  return chordIntervals(chord).map((step) => mod12(chord.root + step));
+}
+
+// ---------------------------------------------------------------------------
+// Names
+
+const SHARP_NAMES = [
+  "C",
+  "C#",
+  "D",
+  "D#",
+  "E",
+  "F",
+  "F#",
+  "G",
+  "G#",
+  "A",
+  "A#",
+  "B",
+];
+const FLAT_NAMES = [
+  "C",
+  "Db",
+  "D",
+  "Eb",
+  "E",
+  "F",
+  "Gb",
+  "G",
+  "Ab",
+  "A",
+  "Bb",
+  "B",
+];
+
+/** Note name for a pitch class; flats when `flats`. */
+function noteName(pc: number, flats = false): string {
+  return (flats ? FLAT_NAMES : SHARP_NAMES)[mod12(pc)]!;
+}
+
+const SECRET_SUFFIX: Readonly<Partial<Record<Quality, string>>> = Object.freeze(
+  { madd4: "m(add4)", mb6: "m(b6)", b6: "(b6)", "7#9": "7#9" },
+);
+
+/** Chord symbol suffix: `m7`, `maj9`, `7sus4`, `dim7`, `m7b5`, `6/9`. */
+function chordSuffix(chord: Chord): string {
+  const ext = new Set(chord.extensions);
+  const b7 = ext.has("m7");
+  const M7 = ext.has("M7");
+  const six = ext.has("6");
+  const nine = ext.has("9");
+  const q = chord.quality;
+  const add = (base: string, parts: string[]) =>
+    parts.length === 0 ? base : `${base}(${parts.join(",")})`;
+  const extras: string[] = [];
+  let base: string;
+  const secret = SECRET_SUFFIX[q];
+  if (secret !== undefined) {
+    const names: Readonly<Record<Extension, string>> = {
+      "6": "6",
+      m7: "7",
+      M7: "maj7",
+      "9": "9",
+    };
+    const parts = chord.extensions.map((e) => names[e]);
+    if (parts.length === 0 || !secret.endsWith(")")) return add(secret, parts);
+    return `${secret.slice(0, -1)},${parts.join(",")})`;
+  }
+  if (q === "dim" && six && !b7 && !M7) {
+    base = "dim7";
+    if (nine) extras.push("add9");
+    return add(base, extras);
+  }
+  if (b7 && M7) {
+    // Both sevenths: name the dominant and list the major seventh.
+    extras.push("maj7");
+  }
+  const seventh = b7 ? "7" : M7 ? "maj7" : "";
+  if (seventh) {
+    const ninth = nine ? (seventh === "7" ? "9" : "maj9") : seventh;
+    switch (q) {
+      case "maj":
+        base = ninth;
+        break;
+      case "min":
+        base = b7 ? (nine ? "m9" : "m7") : nine ? "m(maj9)" : "m(maj7)";
+        break;
+      case "dim":
+        base = b7 ? (nine ? "m9b5" : "m7b5") : "dim(maj7)";
+        if (!b7 && nine) extras.push("9");
+        break;
+      case "aug":
+        base = b7 ? (nine ? "aug9" : "aug7") : "aug(maj7)";
+        if (!b7 && nine) extras.push("9");
+        break;
+      case "sus4":
+        base = `${ninth}sus4`;
+        break;
+      case "sus2":
+        base = `${seventh}sus2`;
+        if (nine) extras.push("9");
+        break;
+      case "5":
+        base = `${seventh}(no3)`;
+        if (nine) extras.push("9");
+        break;
+      default:
+        base = seventh; // secret qualities returned above
+    }
+    if (six) extras.push("13");
+    return add(base, b7 && M7 ? extras : extras.filter((e) => e !== "maj7"));
+  }
+  const triad: Record<Quality, string> = {
+    maj: "",
+    min: "m",
+    dim: "dim",
+    sus4: "sus4",
+    aug: "aug",
+    sus2: "sus2",
+    "5": "5",
+    madd4: "m(add4)",
+    mb6: "m(b6)",
+    b6: "(b6)",
+    "7#9": "7#9",
+  };
+  base = triad[q];
+  if (six && nine && (q === "maj" || q === "min")) return `${base}6/9`;
+  if (six) {
+    if (q === "maj" || q === "min") base = `${base}6`;
+    else extras.push("6");
+  }
+  if (nine) {
+    if (extras.length === 0 && (q === "maj" || q === "min"))
+      return `${base}${q === "min" && !six ? "(add9)" : "add9"}`;
+    extras.push("9");
+  }
+  return add(base, extras);
+}
+
+/** Chord symbol: `Cm7`, `F#dim`, `Bbmaj9`, `G7sus4`, `C/E`. */
+function chordName(chord: Chord, flats = false): string {
+  const slash =
+    chord.bass === undefined ? "" : `/${noteName(chord.bass, flats)}`;
+  return `${noteName(chord.root, flats)}${chordSuffix(chord)}${slash}`;
+}
+
+/** Suffix → quality and extensions, longest first when parsing. */
+const SUFFIXES: readonly (readonly [string, Quality, readonly Extension[]])[] =
+  [
+    ["", "maj", []],
+    ["maj", "maj", []],
+    ["M", "maj", []],
+    ["m", "min", []],
+    ["min", "min", []],
+    ["-", "min", []],
+    ["dim", "dim", []],
+    ["°", "dim", []],
+    ["o", "dim", []],
+    ["aug", "aug", []],
+    ["+", "aug", []],
+    ["sus", "sus4", []],
+    ["sus4", "sus4", []],
+    ["sus2", "sus2", []],
+    ["5", "5", []],
+    ["6", "maj", ["6"]],
+    ["m6", "min", ["6"]],
+    ["6/9", "maj", ["6", "9"]],
+    ["69", "maj", ["6", "9"]],
+    ["m6/9", "min", ["6", "9"]],
+    ["m69", "min", ["6", "9"]],
+    ["7", "maj", ["m7"]],
+    ["dom7", "maj", ["m7"]],
+    ["maj7", "maj", ["M7"]],
+    ["M7", "maj", ["M7"]],
+    ["Δ", "maj", ["M7"]],
+    ["Δ7", "maj", ["M7"]],
+    ["m7", "min", ["m7"]],
+    ["min7", "min", ["m7"]],
+    ["-7", "min", ["m7"]],
+    ["m(maj7)", "min", ["M7"]],
+    ["mM7", "min", ["M7"]],
+    ["m7b5", "dim", ["m7"]],
+    ["ø", "dim", ["m7"]],
+    ["ø7", "dim", ["m7"]],
+    ["dim7", "dim", ["6"]],
+    ["°7", "dim", ["6"]],
+    ["o7", "dim", ["6"]],
+    ["aug7", "aug", ["m7"]],
+    ["+7", "aug", ["m7"]],
+    ["9", "maj", ["m7", "9"]],
+    ["maj9", "maj", ["M7", "9"]],
+    ["M9", "maj", ["M7", "9"]],
+    ["m9", "min", ["m7", "9"]],
+    ["add9", "maj", ["9"]],
+    ["madd9", "min", ["9"]],
+    ["m(add9)", "min", ["9"]],
+    ["7sus4", "sus4", ["m7"]],
+    ["7sus", "sus4", ["m7"]],
+    ["9sus4", "sus4", ["m7", "9"]],
+    ["7sus2", "sus2", ["m7"]],
+    ["maj7sus4", "sus4", ["M7"]],
+    ["m(add4)", "madd4", []],
+    ["madd4", "madd4", []],
+    ["m(b6)", "mb6", []],
+    ["mb6", "mb6", []],
+    ["(b6)", "b6", []],
+    ["addb6", "b6", []],
+    ["7#9", "7#9", []],
+  ];
+const SUFFIX_TABLE = new Map(
+  SUFFIXES.map(([suffix, quality, ext]) => [suffix, { quality, ext }]),
+);
+
+const LETTER: Readonly<Record<string, number>> = Object.freeze({
+  c: 0,
+  d: 2,
+  e: 4,
+  f: 5,
+  g: 7,
+  a: 9,
+  b: 11,
+});
+
+/** Pitch class of a note name (`C`, `f#`, `Bb`), or undefined. */
+function parsePitchClass(text: string): number | undefined {
+  const match = text.trim().match(/^([a-gA-G])(#|b|♯|♭)?$/);
+  if (!match) return undefined;
+  const accidental =
+    match[2] === "#" || match[2] === "♯"
+      ? 1
+      : match[2] === "b" || match[2] === "♭"
+        ? -1
+        : 0;
+  return mod12(LETTER[match[1]!.toLowerCase()]! + accidental);
+}
+
+/** Parse a chord symbol (`Cm7`, `F#dim`, `Bbmaj9`, `G7sus4`, `C/E`). */
+function parseChord(symbol: string): Chord | undefined {
+  if (typeof symbol !== "string" || symbol.length > 24) return undefined;
+  const trimmed = symbol
+    .trim()
+    .replace(/6\/9$/, "69")
+    .replace(/6\/9\//, "69/");
+  const match = trimmed.match(/^([A-Ga-g])(#|b|♯|♭)?([^/]*)(?:\/(.+))?$/);
+  if (!match) return undefined;
+  const root = parsePitchClass(`${match[1]}${match[2] ?? ""}`);
+  const entry = SUFFIX_TABLE.get(match[3] ?? "");
+  if (root === undefined || !entry) return undefined;
+  let bass: number | undefined;
+  if (match[4] !== undefined) {
+    bass = parsePitchClass(match[4]);
+    if (bass === undefined) return undefined;
+  }
+  return makeChord(root, entry.quality, entry.ext, bass);
+}
+
+// ---------------------------------------------------------------------------
+// Keys and modes
+
+const MODES = Object.freeze({
+  major: [0, 2, 4, 5, 7, 9, 11],
+  minor: [0, 2, 3, 5, 7, 8, 10],
+  dorian: [0, 2, 3, 5, 7, 9, 10],
+  phrygian: [0, 1, 3, 5, 7, 8, 10],
+  lydian: [0, 2, 4, 6, 7, 9, 11],
+  mixolydian: [0, 2, 4, 5, 7, 9, 10],
+  locrian: [0, 1, 3, 5, 6, 8, 10],
+  "harmonic-minor": [0, 2, 3, 5, 7, 8, 11],
+} as const);
+type ModeName = keyof typeof MODES;
+const MODE_NAMES = Object.keys(MODES) as ModeName[];
+
+const MODE_ALIASES: Readonly<Record<string, ModeName>> = Object.freeze({
+  "": "major",
+  maj: "major",
+  major: "major",
+  ionian: "major",
+  m: "minor",
+  min: "minor",
+  minor: "minor",
+  aeolian: "minor",
+  dorian: "dorian",
+  phrygian: "phrygian",
+  lydian: "lydian",
+  mixolydian: "mixolydian",
+  mixo: "mixolydian",
+  locrian: "locrian",
+  "harmonic-minor": "harmonic-minor",
+  "harmonic minor": "harmonic-minor",
+  harmonic: "harmonic-minor",
+});
+
+type Key = Readonly<{ tonic: number; mode: ModeName }>;
+
+/**
+ * Parse a key: `C`, `c major`, `Am`, `a minor`, `F# dorian`, `Eb mixo`.
+ * Accepts the `<note> <mode>` form `core/key.ts` writes.
+ */
+function parseKey(text: string | null | undefined): Key | undefined {
+  if (typeof text !== "string" || text.length > 40) return undefined;
+  const match = text
+    .trim()
+    .match(/^([a-gA-G])(#|b|♯|♭)?\s*(m(?![a-z])|[a-zA-Z][a-zA-Z -]*)?$/);
+  if (!match) return undefined;
+  const tonic = parsePitchClass(`${match[1]}${match[2] ?? ""}`);
+  const word = (match[3] ?? "").trim();
+  const mode = MODE_ALIASES[word === "m" ? "m" : word.toLowerCase()];
+  if (tonic === undefined || mode === undefined) return undefined;
+  return Object.freeze({ tonic, mode });
+}
+
+/** True when names in the key read better with flats (F, Bb, Eb, d minor…). */
+function keyUsesFlats(key: Key): boolean {
+  // The parent major scale's tonic decides: F, Bb, Eb, Ab, Db read in flats.
+  const parentOffset: Record<ModeName, number> = {
+    major: 0,
+    dorian: 2,
+    phrygian: 4,
+    lydian: 5,
+    mixolydian: 7,
+    minor: 9,
+    locrian: 11,
+    "harmonic-minor": 9,
+  };
+  const parent = mod12(key.tonic - parentOffset[key.mode]);
+  return [5, 10, 3, 8, 1].includes(parent);
+}
+
+/** `C major`, `F# dorian`, `Bb minor`. */
+function keyName(key: Key): string {
+  return `${noteName(key.tonic, keyUsesFlats(key))} ${key.mode}`;
+}
+
+/** Pitch classes of the key's scale, tonic first. */
+function scaleOf(key: Key): number[] {
+  return MODES[key.mode].map((step) => mod12(key.tonic + step));
+}
+
+function qualityFromThirds(third: number, fifth: number): Quality {
+  if (third === 4 && fifth === 7) return "maj";
+  if (third === 3 && fifth === 7) return "min";
+  if (third === 3 && fifth === 6) return "dim";
+  if (third === 4 && fifth === 8) return "aug";
+  return "maj";
+}
+
+/**
+ * The diatonic chord on scale degree `degree` (0-based): stacked thirds
+ * from the scale. `sevenths` adds the scale's seventh above the root.
+ */
+function diatonicChord(key: Key, degree: number, sevenths = false): Chord {
+  const scale = MODES[key.mode];
+  const at = (index: number) => {
+    const octave = Math.floor(index / 7);
+    return scale[((index % 7) + 7) % 7]! + 12 * octave;
+  };
+  const d = ((degree % 7) + 7) % 7;
+  const root = at(d);
+  const third = at(d + 2) - root;
+  const fifth = at(d + 4) - root;
+  const quality = qualityFromThirds(third, fifth);
+  const ext: Extension[] = [];
+  if (sevenths) {
+    const seventh = at(d + 6) - root;
+    if (quality === "dim" && seventh === 9) ext.push("6");
+    else ext.push(seventh === 11 ? "M7" : "m7");
+  }
+  return makeChord(key.tonic + root, quality, ext);
+}
+
+/** The seven diatonic chords of the key. */
+function diatonicChords(key: Key, sevenths = false): Chord[] {
+  return Array.from({ length: 7 }, (_, degree) =>
+    diatonicChord(key, degree, sevenths),
+  );
+}
+
+/** Scale degree (0-based) of a pitch class, or undefined when not in key. */
+function degreeOf(key: Key, pc: number): number | undefined {
+  const index = scaleOf(key).indexOf(mod12(pc));
+  return index < 0 ? undefined : index;
+}
+
+/**
+ * Orchid Key mode: the chord a key plays. In-scale pitches play their
+ * diatonic chord (C major: D → Dm). Out-of-scale pitches are dawg's
+ * choice: the chord borrowed from the parallel major/minor when that
+ * scale contains the pitch (C major: Eb → Eb, Ab → Ab, Bb → Bb), otherwise
+ * a passing diminished seventh (C major: C# → C#dim7, F# → F#dim7).
+ * `types` and `extensions` are the held Orchid buttons: a type overrides
+ * the quality ("unorthodox" choices), extensions add on top.
+ */
+function keyModeChord(
+  key: Key,
+  pitch: number,
+  options: Readonly<{
+    types?: Iterable<ChordType>;
+    extensions?: Iterable<Extension>;
+    sevenths?: boolean;
+  }> = {},
+): Chord {
+  const pc = mod12(pitch);
+  const extensions = [...(options.extensions ?? [])];
+  const forced = qualityOf(options.types ?? []);
+  const degree = degreeOf(key, pc);
+  let base: Chord;
+  if (degree !== undefined) base = diatonicChord(key, degree, options.sevenths);
+  else {
+    const parallel: Key = {
+      tonic: key.tonic,
+      mode: MODES[key.mode][2] === 4 ? "minor" : "major",
+    };
+    const borrowed = degreeOf(parallel, pc);
+    base =
+      borrowed !== undefined
+        ? diatonicChord(parallel, borrowed, options.sevenths)
+        : makeChord(pc, "dim", ["6"]);
+  }
+  if (forced === undefined && extensions.length === 0) return base;
+  const quality = forced ?? base.quality;
+  const ext =
+    forced === undefined ? [...base.extensions, ...extensions] : extensions;
+  return makeChord(pc, quality, ext);
+}
+
+/** Manual (non-key) mode: the held buttons on the pressed root. */
+function manualChord(
+  pitch: number,
+  types: Iterable<ChordType>,
+  extensions: Iterable<Extension> = [],
+): Chord | undefined {
+  const quality = qualityOf(types);
+  const ext = [...extensions];
+  if (quality === undefined && ext.length === 0) return undefined;
+  return makeChord(pitch, quality ?? "maj", ext);
+}
+
+// ---------------------------------------------------------------------------
+// Roman numerals
+
+const NUMERALS = ["i", "ii", "iii", "iv", "v", "vi", "vii"];
+
+/** Roman numeral for a chord in a key (`ii`, `V7`, `bVII`, `vii°`). */
+function romanOf(key: Key, chord: Chord): string {
+  const scale = scaleOf(key);
+  let degree = scale.indexOf(chord.root);
+  let accidental = "";
+  if (degree < 0) {
+    // Name chromatic roots against the major scale: bIII, #iv°.
+    const major = MODES.major.map((step) => mod12(key.tonic + step));
+    const flat = major.indexOf(mod12(chord.root + 1));
+    const sharp = major.indexOf(mod12(chord.root - 1));
+    if (flat >= 0) {
+      degree = flat;
+      accidental = "b";
+    } else {
+      degree = Math.max(0, sharp);
+      accidental = "#";
+    }
+  }
+  const lower =
+    chord.quality === "min" ||
+    chord.quality === "dim" ||
+    chord.quality === "5" ||
+    chord.quality === "madd4" ||
+    chord.quality === "mb6";
+  const numeral = NUMERALS[degree]!;
+  const body = lower ? numeral : numeral.toUpperCase();
+  const ext = new Set(chord.extensions);
+  let mark = "";
+  if (chord.quality === "dim") mark = ext.has("m7") ? "ø" : "°";
+  else if (chord.quality === "aug") mark = "+";
+  const seventh =
+    ext.has("6") && chord.quality === "dim"
+      ? "7"
+      : ext.has("m7")
+        ? "7"
+        : ext.has("M7")
+          ? "maj7"
+          : "";
+  return `${accidental}${body}${mark}${seventh}`;
+}
+
+/**
+ * Parse a roman numeral in a key: `I`, `ii`, `V7`, `vii°`, `bVII`, `iv`,
+ * `IVmaj7`, `ii7`, `V/V` (secondary dominant), `Vsus4`.
+ *
+ * A numeral whose case matches the diatonic chord (lowercase for minor or
+ * diminished) takes the diatonic quality, so `vii` is diminished in major;
+ * a mismatched case is explicit (`iv` in major is minor, `IV` in minor is
+ * major). `7` adds the diatonic seventh; `maj7`/`M7` and `dom7` are exact.
+ */
+function parseRoman(key: Key, text: string): Chord | undefined {
+  if (typeof text !== "string" || text.length > 16) return undefined;
+  const trimmed = text.trim();
+  const slash = trimmed.match(/^(.+)\/(.+)$/);
+  if (slash) {
+    // V/x: the chord built on the degree of x in the key (secondary function).
+    const target = parseRoman(key, slash[2]!);
+    if (!target) return undefined;
+    const sub = parseRoman({ tonic: target.root, mode: "major" }, slash[1]!);
+    return sub;
+  }
+  const match = trimmed.match(
+    /^(b|#|♭|♯)?(vii|vi|v|iv|iii|ii|i|VII|VI|V|IV|III|II|I)(°|o|ø|\+)?(maj7|M7|dom7|7|9|maj9|6|sus4|sus2|sus|add9)?$/,
+  );
+  if (!match) return undefined;
+  const accidental =
+    match[1] === "b" || match[1] === "♭" ? -1 : match[1] ? 1 : 0;
+  const numeral = match[2]!;
+  const lower = numeral === numeral.toLowerCase();
+  const degree = NUMERALS.indexOf(numeral.toLowerCase());
+  const mark = match[3];
+  const suffix = match[4] ?? "";
+  const root =
+    accidental === 0
+      ? scaleOf(key)[degree]!
+      : mod12(key.tonic + MODES.major[degree]! + accidental);
+  const inKey = degreeOf(key, root);
+  const triad = inKey === undefined ? undefined : diatonicChord(key, inKey);
+  const seventh =
+    inKey === undefined ? undefined : diatonicChord(key, inKey, true);
+  const diatonicLower =
+    triad !== undefined && (triad.quality === "min" || triad.quality === "dim");
+  const matches = triad !== undefined && diatonicLower === lower;
+  let quality: Quality;
+  if (mark === "°" || mark === "o" || mark === "ø") quality = "dim";
+  else if (mark === "+") quality = "aug";
+  else if (matches) quality = triad.quality;
+  else quality = lower ? "min" : "maj";
+  // The diatonic seventh when the triad is the diatonic one, else b7.
+  const diatonicSeventh = (): Extension[] =>
+    mark === "ø"
+      ? ["m7"]
+      : seventh && seventh.quality === quality
+        ? [...seventh.extensions]
+        : quality === "dim" && mark !== undefined
+          ? ["6"]
+          : ["m7"];
+  let ext: Extension[] = mark === "ø" ? ["m7"] : [];
+  switch (suffix) {
+    case "7":
+      ext = diatonicSeventh();
+      break;
+    case "dom7":
+      ext = ["m7"];
+      break;
+    case "maj7":
+    case "M7":
+      ext = ["M7"];
+      break;
+    case "9":
+      ext = [...diatonicSeventh(), "9"];
+      break;
+    case "maj9":
+      ext = ["M7", "9"];
+      break;
+    case "6":
+      ext = ["6"];
+      break;
+    case "add9":
+      ext = ["9"];
+      break;
+    case "sus4":
+    case "sus":
+      quality = "sus4";
+      break;
+    case "sus2":
+      quality = "sus2";
+      break;
+  }
+  return makeChord(root, quality, ext);
+}
+
+// ---------------------------------------------------------------------------
+// Voicing
+
+/** Default chord register: a voicing is kept inside [low, high]. */
+const VOICING_RANGE = Object.freeze({ low: 48, high: 79 });
+/** Voicing dial: Orchid-style rotation steps, -12..12. */
+const MAX_VOICING_STEP = 12;
+const SPREADS = ["close", "open", "wide"] as const;
+type Spread = (typeof SPREADS)[number];
+
+type VoicingOptions = Readonly<{
+  /** Rotation steps from root position (Orchid's voicing dial). */
+  inversion?: number;
+  spread?: Spread;
+  /** Voice-lead from this voicing (minimal movement). */
+  previous?: readonly number[] | undefined;
+  /** Root-position anchor: the root lands at or above this pitch. */
+  anchor?: number;
+  low?: number;
+  high?: number;
+}>;
+
+/**
+ * Root position of a chord with its root at or above `anchor`, then the
+ * Orchid voicing dial: each positive step moves the lowest note up an
+ * octave, each negative step the highest note down.
+ */
+function rotate(pitches: readonly number[], steps: number): number[] {
+  const notes = [...pitches].sort((a, b) => a - b);
+  if (notes.length === 0) return notes;
+  for (let i = 0; i < Math.abs(Math.trunc(steps)); i += 1) {
+    if (steps > 0) notes.push(notes.shift()! + 12);
+    else notes.unshift(notes.pop()! - 12);
+  }
+  return notes;
+}
+
+function rootPosition(chord: Chord, anchor = 60): number[] {
+  const rootPitch = anchor + mod12(chord.root - anchor);
+  return chordIntervals(chord).map((step) => rootPitch + step);
+}
+
+/** Open voicings: `open` drops the second voice from the top an octave
+ * (drop 2); `wide` also drops the fourth from the top (drop 2+4). */
+function applySpread(pitches: readonly number[], spread: Spread): number[] {
+  const notes = [...pitches].sort((a, b) => a - b);
+  if (spread === "close" || notes.length < 3) return notes;
+  const n = notes.length;
+  notes[n - 2] = notes[n - 2]! - 12;
+  if (spread === "wide" && n >= 4) notes[n - 4] = notes[n - 4]! - 12;
+  return notes.sort((a, b) => a - b);
+}
+
+/**
+ * Movement between two voicings: each voice of the new chord pays its
+ * distance to the nearest previous voice and vice versa, so voicings of
+ * different sizes compare and common tones are free.
+ */
+function movement(a: readonly number[], b: readonly number[]): number {
+  if (a.length === 0 || b.length === 0) return 0;
+  const nearest = (pitch: number, set: readonly number[]) =>
+    Math.min(...set.map((other) => Math.abs(other - pitch)));
+  let total = 0;
+  for (const pitch of b) total += nearest(pitch, a);
+  for (const pitch of a) total += nearest(pitch, b);
+  return total;
+}
+
+/**
+ * Voice a chord. Without `previous`, root position at `anchor` rotated by
+ * `inversion` (the Orchid dial). With `previous` (voice leading), every
+ * rotation within an octave either side of the dial is tried and the one
+ * with the least movement wins; ties go to the voicing nearest the dial,
+ * then the lower one. Results stay within [low, high] when they fit.
+ */
+function voiceChord(chord: Chord, options: VoicingOptions = {}): number[] {
+  const anchor = options.anchor ?? 60;
+  const spread = options.spread ?? "close";
+  const low = options.low ?? VOICING_RANGE.low;
+  const high = options.high ?? VOICING_RANGE.high;
+  const dial = clampInt(
+    options.inversion ?? 0,
+    -MAX_VOICING_STEP,
+    MAX_VOICING_STEP,
+  );
+  const base = rootPosition(chord, anchor);
+  const size = base.length;
+  const fit = (notes: number[]) =>
+    notes.every((pitch) => pitch >= low && pitch <= high);
+  const clampMidi = (notes: number[]) =>
+    notes.map((pitch) => Math.max(0, Math.min(127, pitch)));
+  const at = (steps: number) => applySpread(rotate(base, steps), spread);
+  if (!options.previous || options.previous.length === 0)
+    return clampMidi(at(dial));
+  let best: { notes: number[]; cost: number; distance: number } | undefined;
+  for (let offset = -size; offset <= size; offset += 1) {
+    const notes = at(dial + offset);
+    if (!fit(notes) && offset !== 0) continue;
+    const cost = movement(options.previous, notes);
+    const distance = Math.abs(offset);
+    if (
+      !best ||
+      cost < best.cost ||
+      (cost === best.cost && distance < best.distance)
+    )
+      best = { notes, cost, distance };
+  }
+  return clampMidi(best!.notes);
+}
+
+/** Bass under a chord: its slash bass or root, in C2..B2 by default. */
+function bassNote(chord: Chord, low = 36): number {
+  return low + mod12((chord.bass ?? chord.root) - low);
+}
+
+/**
+ * Orchid's bass behaviours (manual 10.2 and the "How to use Bass" article),
+ * plus `off`. Labels in BASS_MODE_TEXT; `chords` is Orchid's default
+ * "Chords Only".
+ */
+const BASS_MODES = ["off", "chords", "unison", "single", "solo"] as const;
+type BassMode = (typeof BASS_MODES)[number];
+
+const BASS_MODE_TEXT: Readonly<Record<BassMode, string>> = {
+  off: "no bass",
+  chords: "bass root under chords only",
+  unison: "bass doubles single notes; root under chords",
+  single: "single notes play bass only; chords play treble and root",
+  solo: "bass only: the treble is muted, even for chords",
+};
+
+/** What one key press sounds once the bass mode has routed it. */
+type BassRoute = Readonly<{
+  /** Whether the treble (chord or single note) sounds. */
+  treble: boolean;
+  /** Bass pitch, or undefined for none. */
+  bass: number | undefined;
+}>;
+
+/**
+ * Route a key press through a bass mode. `chord` is the chord the key
+ * played (undefined for a single note); `pitch` the pressed key; `low` the
+ * bottom of the bass octave. Sourced semantics (Orchid manual 10.2, support
+ * article "How to use Bass on Orchid"): `chords` adds the chord's root only
+ * when a chord plays; `unison` plays bass and treble together on single
+ * notes; `single` plays only bass on single notes and the treble only on
+ * chords; `solo` mutes the treble entirely, even for chords. dawg's
+ * reading where the sources are silent: every mode that sounds bass under
+ * a chord uses the chord's root (or slash bass), and a single note's bass
+ * is the pressed pitch class in the bass octave.
+ */
+function routeBass(
+  mode: BassMode,
+  chord: Chord | undefined,
+  pitch: number,
+  low = 36,
+): BassRoute {
+  const under = chord ? bassNote(chord, low) : low + mod12(pitch - low);
+  switch (mode) {
+    case "off":
+      return { treble: true, bass: undefined };
+    case "chords":
+      return { treble: true, bass: chord ? under : undefined };
+    case "unison":
+      return { treble: true, bass: under };
+    case "single":
+      return { treble: chord !== undefined, bass: under };
+    case "solo":
+      return { treble: false, bass: under };
+  }
+}
+
+function parseBassMode(value: string | undefined): BassMode | undefined {
+  const text = (value ?? "").trim().toLowerCase();
+  if (text === "on" || text === "true") return "chords";
+  if (text === "false" || text === "none") return "off";
+  if (text === "single-notes" || text === "singles") return "single";
+  return (BASS_MODES as readonly string[]).includes(text)
+    ? (text as BassMode)
+    : undefined;
+}
+
+// ---------------------------------------------------------------------------
+// Performance
+
+const PERFORM_MODES = [
+  "block",
+  "strum-up",
+  "strum-down",
+  "arp-up",
+  "arp-down",
+  "arp-updown",
+  "arp-random",
+  "harp",
+  "slop",
+  "pattern",
+] as const;
+type PerformMode = (typeof PERFORM_MODES)[number];
+
+type PerformOptions = Readonly<{
+  mode?: PerformMode;
+  /** Arp step in beats (the grid), default 1/8 beat... 0.25. */
+  rate?: number;
+  /** Arp/harp octaves, 1..4. */
+  octaves?: number;
+  /** Strum gap between voices in beats, default 1/32 beat. */
+  strum?: number;
+  /** Seed for arp-random and slop. */
+  seed?: number;
+  /** Slop amount 0..1: each voice lands up to `slop` × 1/8 beat late. */
+  slop?: number;
+  /** Pattern mode: a CHORD_PATTERNS name or 1-based number, default 1. */
+  pattern?: string | number;
+  /** 0..1. */
+  velocity?: number;
+}>;
+
+type PerformedNote = Readonly<{
+  pitch: number;
+  /** Beats. */
+  start: number;
+  length: number;
+  velocity: number;
+}>;
+
+const DEFAULT_ARP_RATE = 0.25;
+const DEFAULT_STRUM = 1 / 32;
+const DEFAULT_SLOP = 0.5;
+/** Latest a slopped voice can land, in beats, at slop 1. */
+const MAX_SLOP = 1 / 8;
+
+// ---------------------------------------------------------------------------
+// Patterns
+
+/**
+ * One hit of a chord pattern. `voices` picks chord tones by index, low to
+ * high: `all`, `upper` (all but the lowest), or a list where an index past
+ * the top wraps an octave up (index 3 of a triad is the root +12) and a
+ * negative index counts down from the top (-1 is the highest voice).
+ */
+type PatternHit = Readonly<{
+  /** Beats from the cycle start. */
+  at: number;
+  /** Beats. */
+  length: number;
+  voices: "all" | "upper" | readonly number[];
+  /** 0..1, scaled by the press velocity. */
+  velocity: number;
+  /** Octave shift for these voices (the bass half of oom-pah is -1). */
+  octave?: number;
+}>;
+
+type ChordPattern = Readonly<{
+  name: string;
+  description: string;
+  /** Cycle length in beats; the pattern repeats from the press. */
+  beats: number;
+  hits: readonly PatternHit[];
+}>;
+
+const everyStep = (
+  step: number,
+  beats: number,
+  hit: (index: number) => Omit<PatternHit, "at">,
+): PatternHit[] =>
+  Array.from({ length: Math.round(beats / step) }, (_, index) => ({
+    at: index * step,
+    ...hit(index),
+  }));
+
+/**
+ * Pattern mode. Orchid's own patterns are not published (manual 7.2: "Plays
+ * chord notes in pre-determined rhythmic patterns", tempo-synced, the
+ * rhythm independent of the chord's note count, with per-note velocities
+ * scaled by the press; 11 at launch and two more in firmware 3.84). These
+ * 13 are dawg's own design in that spirit: each hit names voices by index
+ * so the rhythm holds for triads and 9th chords alike.
+ */
+const CHORD_PATTERNS: readonly ChordPattern[] = Object.freeze([
+  {
+    name: "eighths",
+    description: "straight 8ths, beats accented",
+    beats: 4,
+    hits: everyStep(0.5, 4, (i) => ({
+      length: 0.45,
+      voices: "all",
+      velocity: i % 2 === 0 ? 1 : 0.7,
+    })),
+  },
+  {
+    name: "sixteenths",
+    description: "straight 16ths, 1-e-&-a accents",
+    beats: 4,
+    hits: everyStep(0.25, 4, (i) => ({
+      length: 0.2,
+      voices: "all",
+      velocity: [1, 0.55, 0.8, 0.55][i % 4]!,
+    })),
+  },
+  {
+    name: "offbeat",
+    description: "short stabs on every &",
+    beats: 4,
+    hits: everyStep(1, 4, () => ({
+      length: 0.25,
+      voices: "all",
+      velocity: 0.9,
+    })).map((hit) => ({ ...hit, at: hit.at + 0.5 })),
+  },
+  {
+    name: "pop",
+    description: "syncopated pop comp with 16th pushes",
+    beats: 4,
+    hits: [
+      { at: 0, length: 0.5, voices: "all", velocity: 1 },
+      { at: 0.75, length: 0.5, voices: "upper", velocity: 0.7 },
+      { at: 1.5, length: 0.75, voices: "all", velocity: 0.85 },
+      { at: 2.5, length: 0.5, voices: "upper", velocity: 0.7 },
+      { at: 3, length: 0.25, voices: "all", velocity: 0.6 },
+      { at: 3.5, length: 0.5, voices: "all", velocity: 0.85 },
+    ],
+  },
+  {
+    name: "charleston",
+    description: "dotted quarter, then the & of 2",
+    beats: 4,
+    hits: [
+      { at: 0, length: 0.75, voices: "all", velocity: 1 },
+      { at: 1.5, length: 0.5, voices: "all", velocity: 0.85 },
+    ],
+  },
+  {
+    name: "bossa",
+    description: "two-bar bossa comp over a root-fifth pulse",
+    beats: 8,
+    hits: [
+      ...everyStep(2, 8, () => ({
+        length: 1.5,
+        voices: [0],
+        velocity: 0.85,
+        octave: -1,
+      })),
+      ...[0, 1.5, 3, 4.5, 6].map((at) => ({
+        at,
+        length: 0.5,
+        voices: "upper" as const,
+        velocity: at === 0 ? 0.9 : 0.75,
+      })),
+    ],
+  },
+  {
+    name: "skank",
+    description: "reggae skank: short upper stabs on 2 and 4",
+    beats: 4,
+    hits: [1, 3].map((at) => ({
+      at,
+      length: 0.2,
+      voices: "upper" as const,
+      velocity: 0.95,
+    })),
+  },
+  {
+    name: "gallop",
+    description: "gallop: an 8th and two 16ths per beat",
+    beats: 4,
+    hits: everyStep(1, 4, () => ({
+      length: 0.4,
+      voices: "all",
+      velocity: 1,
+    })).flatMap((hit) => [
+      hit,
+      { ...hit, at: hit.at + 0.5, length: 0.2, velocity: 0.7 },
+      { ...hit, at: hit.at + 0.75, length: 0.2, velocity: 0.75 },
+    ]),
+  },
+  {
+    name: "half-time",
+    description: "half-time: a long hit and a pickup per two bars",
+    beats: 8,
+    hits: [
+      { at: 0, length: 3.5, voices: "all", velocity: 1 },
+      { at: 4, length: 1.5, voices: "all", velocity: 0.8 },
+      { at: 7.5, length: 0.5, voices: "upper", velocity: 0.65 },
+    ],
+  },
+  {
+    name: "tresillo",
+    description: "tresillo 3+3+2",
+    beats: 4,
+    hits: [
+      { at: 0, length: 1.25, voices: "all", velocity: 1 },
+      { at: 1.5, length: 1.25, voices: "all", velocity: 0.8 },
+      { at: 3, length: 0.75, voices: "all", velocity: 0.9 },
+    ],
+  },
+  {
+    name: "oom-pah",
+    description: "alternating bass and chord: low root, upper chord",
+    beats: 4,
+    hits: everyStep(1, 4, (i) =>
+      i % 2 === 0
+        ? { length: 0.9, voices: [0], velocity: 1, octave: -1 }
+        : { length: 0.8, voices: "upper", velocity: 0.75 },
+    ),
+  },
+  {
+    name: "roll",
+    description: "broken-chord roll up in 16ths, ringing to the half bar",
+    beats: 4,
+    hits: [0, 2].flatMap((bar) =>
+      [0, 1, 2, 3].map((step) => ({
+        at: bar + step * 0.25,
+        length: 2 - step * 0.25,
+        voices: [step],
+        velocity: 0.7 + step * 0.08,
+      })),
+    ),
+  },
+  {
+    name: "pick",
+    description: "broken-chord picking: low, high, middle, high in 8ths",
+    beats: 4,
+    hits: everyStep(0.5, 4, (i) => ({
+      length: 0.5,
+      voices: [[0, -1, 1, -1][i % 4]!],
+      velocity: i % 4 === 0 ? 0.95 : 0.7,
+    })),
+  },
+]);
+
+/** A pattern by name or 1-based number, or undefined. */
+function findChordPattern(
+  value: string | number | undefined,
+): ChordPattern | undefined {
+  if (value === undefined) return undefined;
+  const text = String(value).trim().toLowerCase();
+  const number = Number(text);
+  if (/^\d+$/.test(text)) return CHORD_PATTERNS[number - 1];
+  return CHORD_PATTERNS.find((pattern) => pattern.name === text);
+}
+
+function patternVoices(notes: readonly number[], hit: PatternHit): number[] {
+  const n = notes.length;
+  const indices =
+    hit.voices === "all"
+      ? notes.map((_, i) => i)
+      : hit.voices === "upper"
+        ? n > 1
+          ? notes.slice(1).map((_, i) => i + 1)
+          : [0]
+        : hit.voices;
+  const shift = 12 * (hit.octave ?? 0);
+  const out = new Set<number>();
+  for (const index of indices) {
+    const i = index < 0 ? ((index % n) + n) % n : index;
+    const wrapped = ((i % n) + n) % n;
+    const pitch = notes[wrapped]! + 12 * Math.floor(i / n) + shift;
+    if (pitch >= 0 && pitch <= 127) out.add(pitch);
+  }
+  return [...out].sort((a, b) => a - b);
+}
+
+/**
+ * Lay a voiced chord out in time over [start, start + length). Block holds
+ * every voice; strums offset voices by `strum` beats and hold to the end;
+ * arpeggios step one voice per `rate` beats across `octaves`, aligned to
+ * multiples of `rate` from `start`; harp is an upward strum across the
+ * octaves that rings to the end; slop (Orchid's humanised timing) holds
+ * every voice like block but delays each by a seeded random fraction of
+ * `slop` × MAX_SLOP, so each seed lands differently; pattern repeats a
+ * CHORD_PATTERNS rhythm from `start`, each hit's velocity scaled by
+ * `velocity`.
+ */
+function perform(
+  pitches: readonly number[],
+  start: number,
+  length: number,
+  options: PerformOptions = {},
+): PerformedNote[] {
+  const mode = options.mode ?? "block";
+  const velocity = options.velocity ?? 0.8;
+  const notes = [...pitches].sort((a, b) => a - b);
+  if (notes.length === 0 || !(length > 0)) return [];
+  const end = start + length;
+  const octaves = clampInt(options.octaves ?? 1, 1, 4);
+  const spanned: number[] = [];
+  for (let o = 0; o < octaves; o += 1)
+    for (const pitch of notes)
+      if (pitch + 12 * o <= 127) spanned.push(pitch + 12 * o);
+  const at = (pitch: number, from: number, to: number): PerformedNote => ({
+    pitch,
+    start: round6(from),
+    length: round6(Math.max(1e-6, to - from)),
+    velocity,
+  });
+  switch (mode) {
+    case "block":
+      return notes.map((pitch) => at(pitch, start, end));
+    case "strum-up":
+    case "strum-down": {
+      const gap = Math.max(0, options.strum ?? DEFAULT_STRUM);
+      const order = mode === "strum-up" ? notes : [...notes].reverse();
+      return order
+        .map((pitch, index) =>
+          at(pitch, Math.min(end - gap, start + index * gap), end),
+        )
+        .filter((note) => note.length > 0);
+    }
+    case "slop": {
+      const amount = Math.min(1, Math.max(0, options.slop ?? DEFAULT_SLOP));
+      const random = mulberry32(options.seed ?? 0);
+      const late = Math.min(amount * MAX_SLOP, length / 2);
+      return notes.map((pitch) => at(pitch, start + random() * late, end));
+    }
+    case "pattern": {
+      const pattern =
+        findChordPattern(options.pattern ?? 1) ?? CHORD_PATTERNS[0]!;
+      const out: PerformedNote[] = [];
+      for (let cycle = start; cycle < end - 1e-9; cycle += pattern.beats)
+        for (const hit of pattern.hits) {
+          const from = cycle + hit.at;
+          if (from >= end - 1e-9) continue;
+          const to = Math.min(end, from + hit.length);
+          for (const pitch of patternVoices(notes, hit))
+            out.push({
+              ...at(pitch, from, to),
+              velocity: round6(velocity * hit.velocity),
+            });
+        }
+      return out.sort((a, b) => a.start - b.start || a.pitch - b.pitch);
+    }
+    case "harp": {
+      const gap = Math.max(0, options.strum ?? DEFAULT_STRUM * 2);
+      return spanned.map((pitch, index) =>
+        at(pitch, Math.min(end - 1e-3, start + index * gap), end),
+      );
+    }
+    default: {
+      const rate =
+        options.rate && options.rate > 0 ? options.rate : DEFAULT_ARP_RATE;
+      const steps = Math.max(1, Math.floor(length / rate + 1e-9));
+      let order: number[];
+      if (mode === "arp-down") order = [...spanned].reverse();
+      else if (mode === "arp-updown")
+        order =
+          spanned.length > 2
+            ? [...spanned, ...spanned.slice(1, -1).reverse()]
+            : spanned;
+      else order = spanned;
+      const random = mulberry32(options.seed ?? 0);
+      const out: PerformedNote[] = [];
+      for (let step = 0; step < steps; step += 1) {
+        const from = start + step * rate;
+        const to = Math.min(end, from + rate);
+        const pitch =
+          mode === "arp-random"
+            ? spanned[Math.floor(random() * spanned.length)]!
+            : order[step % order.length]!;
+        out.push(at(pitch, from, to));
+      }
+      return out;
+    }
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Progressions
+
+/** A progression preset: roman numerals and the mode they read in. */
+type ProgressionPreset = Readonly<{
+  name: string;
+  mode: "major" | "minor" | "dorian" | "mixolydian";
+  numerals: readonly string[];
+  /** Use diatonic sevenths. */
+  sevenths?: boolean;
+  description: string;
+}>;
+
+const PROGRESSION_PRESETS: readonly ProgressionPreset[] = Object.freeze([
+  {
+    name: "axis",
+    mode: "major",
+    numerals: ["I", "V", "vi", "IV"],
+    description: "I–V–vi–IV, the four-chord pop loop",
+  },
+  {
+    name: "sad-pop",
+    mode: "major",
+    numerals: ["vi", "IV", "I", "V"],
+    description: "vi–IV–I–V, the same loop from the relative minor",
+  },
+  {
+    name: "fifties",
+    mode: "major",
+    numerals: ["I", "vi", "IV", "V"],
+    description: "I–vi–IV–V doo-wop",
+  },
+  {
+    name: "ii-v-i",
+    mode: "major",
+    numerals: ["ii", "V", "I", "I"],
+    sevenths: true,
+    description: "ii7–V7–Imaj7, the jazz cadence",
+  },
+  {
+    name: "turnaround",
+    mode: "major",
+    numerals: ["I", "vi", "ii", "V"],
+    sevenths: true,
+    description: "Imaj7–vi7–ii7–V7 turnaround",
+  },
+  {
+    name: "canon",
+    mode: "major",
+    numerals: ["I", "V", "vi", "iii", "IV", "I", "IV", "V"],
+    description: "Pachelbel's canon",
+  },
+  {
+    name: "aeolian",
+    mode: "minor",
+    numerals: ["i", "VI", "III", "VII"],
+    description: "i–VI–III–VII minor anthem",
+  },
+  {
+    name: "andalusian",
+    mode: "minor",
+    numerals: ["i", "VII", "VI", "V"],
+    description: "i–VII–VI–V descending (major V)",
+  },
+  {
+    name: "minor-ii-v",
+    mode: "minor",
+    numerals: ["iiø", "V7", "i", "i"],
+    sevenths: true,
+    description: "iiø7–V7–i minor cadence",
+  },
+  {
+    name: "dorian-vamp",
+    mode: "dorian",
+    numerals: ["i", "IV"],
+    sevenths: true,
+    description: "i7–IV7 dorian vamp",
+  },
+  {
+    name: "mixolydian-rock",
+    mode: "mixolydian",
+    numerals: ["I", "bVII", "IV", "I"],
+    description: "I–bVII–IV–I mixolydian rock",
+  },
+]);
+
+const PROGRESSION_STYLES = ["pop", "jazz", "modal", "classical"] as const;
+type ProgressionStyle = (typeof PROGRESSION_STYLES)[number];
+
+/**
+ * Functional-harmony transition weights between scale degrees (0 = I),
+ * per style. Tonic (I, vi, iii) moves to predominant (IV, ii), which moves
+ * to dominant (V, vii°), which resolves to tonic; pop adds the plagal and
+ * vi–IV moves, jazz favours the cycle of fifths, modal keeps to the tonic
+ * and its neighbours.
+ */
+const TRANSITIONS: Readonly<
+  Record<ProgressionStyle, readonly (readonly number[])[]>
+> = Object.freeze({
+  //            I  ii iii IV  V  vi vii
+  pop: [
+    [0, 1, 1, 4, 4, 4, 0], // I
+    [1, 0, 0, 2, 5, 1, 0], // ii
+    [0, 0, 0, 3, 1, 4, 0], // iii
+    [4, 1, 0, 0, 4, 2, 0], // IV
+    [4, 0, 0, 2, 0, 4, 0], // V
+    [1, 2, 1, 5, 3, 0, 0], // vi
+    [5, 0, 1, 0, 0, 1, 0], // vii°
+  ],
+  jazz: [
+    [0, 4, 1, 2, 1, 4, 0],
+    [0, 0, 0, 0, 8, 0, 1],
+    [0, 0, 0, 1, 0, 6, 0],
+    [2, 2, 0, 0, 2, 0, 3],
+    [6, 0, 0, 0, 0, 2, 0],
+    [0, 7, 0, 1, 1, 0, 0],
+    [2, 0, 5, 0, 0, 0, 0],
+  ],
+  modal: [
+    [0, 3, 1, 4, 1, 2, 2],
+    [5, 0, 1, 1, 0, 0, 1],
+    [3, 1, 0, 1, 0, 0, 1],
+    [5, 1, 0, 0, 1, 0, 2],
+    [3, 0, 0, 2, 0, 1, 1],
+    [3, 1, 0, 1, 0, 0, 1],
+    [5, 0, 0, 2, 0, 0, 0],
+  ],
+  classical: [
+    [0, 2, 1, 4, 5, 3, 1],
+    [0, 0, 0, 0, 6, 0, 2],
+    [0, 0, 0, 2, 0, 5, 0],
+    [2, 3, 0, 0, 5, 0, 1],
+    [6, 0, 0, 0, 0, 2, 0],
+    [0, 4, 0, 4, 1, 0, 0],
+    [6, 0, 1, 0, 0, 0, 0],
+  ],
+});
+
+/** Seeded PRNG (mulberry32): same seed, same sequence. */
+function mulberry32(seed: number): () => number {
+  let state = Math.trunc(seed) >>> 0;
+  return () => {
+    state = (state + 0x6d2b79f5) >>> 0;
+    let t = state;
+    t = Math.imul(t ^ (t >>> 15), t | 1);
+    t ^= t + Math.imul(t ^ (t >>> 7), t | 61);
+    return ((t ^ (t >>> 14)) >>> 0) / 4294967296;
+  };
+}
+
+function pick(weights: readonly number[], random: () => number): number {
+  const total = weights.reduce((sum, w) => sum + w, 0);
+  if (!(total > 0)) return 0;
+  let roll = random() * total;
+  for (let i = 0; i < weights.length; i += 1) {
+    roll -= weights[i]!;
+    if (roll < 0) return i;
+  }
+  return weights.length - 1;
+}
+
+function findPreset(name: string): ProgressionPreset | undefined {
+  const wanted = name.trim().toLowerCase();
+  return PROGRESSION_PRESETS.find((preset) => preset.name === wanted);
+}
+
+/** The next degree the graph favours most after `degree` (no randomness). */
+function likelyNext(degree: number, style: ProgressionStyle = "pop"): number {
+  const row = TRANSITIONS[style][((degree % 7) + 7) % 7]!;
+  let best = 0;
+  for (let i = 1; i < row.length; i += 1) if (row[i]! > row[best]!) best = i;
+  return best;
+}
+
+/**
+ * The chord play mode shows as "next": with a preset, the preset chord
+ * after the last one played (matched by root); otherwise the strongest
+ * graph transition from the last chord's degree, or I when there is none.
+ */
+function suggestNext(
+  key: Key,
+  last: Chord | undefined,
+  options: Readonly<{
+    preset?: string;
+    style?: ProgressionStyle;
+    sevenths?: boolean;
+  }> = {},
+): Chord {
+  const preset = options.preset ? findPreset(options.preset) : undefined;
+  if (preset) {
+    const chords = presetChords(key, preset);
+    const index = last
+      ? chords.findIndex((chord) => chord.root === last.root)
+      : -1;
+    return chords[(index + 1) % chords.length]!;
+  }
+  const degree = last ? degreeOf(key, last.root) : undefined;
+  const next = degree === undefined ? 0 : likelyNext(degree, options.style);
+  return diatonicChord(key, next, options.sevenths);
+}
+
+/** A preset's chords in `key` (numerals read in the key's own mode). */
+function presetChords(key: Key, preset: ProgressionPreset): Chord[] {
+  return preset.numerals.map((numeral) => {
+    const chord = parseRoman(key, numeral);
+    if (!chord) throw new Error(`bad preset numeral ${numeral}`);
+    if (!preset.sevenths || chord.extensions.length > 0) return chord;
+    const withSeventh = parseRoman(key, `${numeral}7`);
+    return withSeventh ?? chord;
+  });
+}
+
+type ProgressionRequest = Readonly<{
+  key: Key;
+  /** Number of chords, 1..64. */
+  length: number;
+  /** A preset name or a style for the random walk. */
+  style?: ProgressionStyle | string;
+  seed?: number;
+  sevenths?: boolean;
+}>;
+
+/**
+ * A progression of `length` chords. A preset name cycles the preset. A
+ * style walks the transition graph from I with a seeded PRNG; when the
+ * progression is 4+ chords long, the last chord is drawn from the
+ * dominant-function chords (V, vii°, or IV in modal) so the loop leads
+ * back to I. Same request, same chords.
+ */
+function generateProgression(request: ProgressionRequest): Chord[] {
+  const length = clampInt(request.length, 1, 64);
+  const preset = request.style ? findPreset(request.style) : undefined;
+  if (preset) {
+    const chords = presetChords(request.key, preset);
+    return Array.from({ length }, (_, i) => chords[i % chords.length]!);
+  }
+  const style = (PROGRESSION_STYLES as readonly string[]).includes(
+    request.style ?? "",
+  )
+    ? (request.style as ProgressionStyle)
+    : "pop";
+  const sevenths = request.sevenths ?? style === "jazz";
+  const random = mulberry32(request.seed ?? 1);
+  const degrees: number[] = [0];
+  for (let i = 1; i < length; i += 1) {
+    const row: number[] = [...TRANSITIONS[style][degrees[i - 1]!]!];
+    if (i === length - 1 && length >= 4) {
+      const cadence = style === "modal" ? [3, 6] : [4, 6];
+      for (let d = 0; d < 7; d += 1) if (!cadence.includes(d)) row[d] = 0;
+      if (!row.some((w) => w > 0)) row[cadence[0]!] = 1;
+    }
+    degrees.push(pick(row, random));
+  }
+  return degrees.map((degree) => diatonicChord(request.key, degree, sevenths));
+}
+
+/** A chord with its voicing, as tools and the SDK report it. */
+type VoicedChord = Readonly<{
+  name: string;
+  roman: string;
+  pitches: readonly number[];
+  bass?: number | undefined;
+}>;
+
+/** Voice a progression with minimal movement chord to chord. */
+function voiceProgression(
+  key: Key,
+  chords: readonly Chord[],
+  options: Readonly<{
+    inversion?: number;
+    spread?: Spread;
+    bass?: boolean;
+    anchor?: number;
+    lead?: boolean;
+  }> = {},
+): VoicedChord[] {
+  const flats = keyUsesFlats(key);
+  let previous: number[] | undefined;
+  return chords.map((chord) => {
+    const pitches = voiceChord(chord, {
+      ...(options.inversion !== undefined
+        ? { inversion: options.inversion }
+        : {}),
+      ...(options.spread ? { spread: options.spread } : {}),
+      ...(options.anchor !== undefined ? { anchor: options.anchor } : {}),
+      previous: options.lead === false ? undefined : previous,
+    });
+    previous = pitches;
+    return Object.freeze({
+      name: chordName(chord, flats),
+      roman: romanOf(key, chord),
+      pitches: Object.freeze(pitches),
+      ...(options.bass ? { bass: bassNote(chord) } : {}),
+    });
+  });
+}
+
+// ---------------------------------------------------------------------------
+// Helpers
+
+function mod12(value: number): number {
+  return ((Math.trunc(value) % 12) + 12) % 12;
+}
+
+function clampInt(value: number, min: number, max: number): number {
+  if (!Number.isFinite(value)) return min;
+  return Math.max(min, Math.min(max, Math.round(value)));
+}
+
+function round6(value: number): number {
+  return Math.round(value * 1e6) / 1e6;
+}
+
+// ---------------------------------------------------------------------------
+// Rendering a progression to notes (tools, SDK, recording)
+
+/** A roman numeral (`ii7`, `bVII`) or chord symbol (`Cm7`, `F/A`) in `key`. */
+function resolveChord(key: Key, text: string): Chord | undefined {
+  return parseRoman(key, text) ?? parseChord(text);
+}
+
+type RenderOptions = Readonly<{
+  key: Key;
+  chords: readonly Chord[];
+  /** Beats each chord lasts (one bar of 4/4 by default). */
+  beatsPerChord?: number;
+  /** First chord's start in beats. */
+  start?: number;
+  perform?: PerformOptions;
+  inversion?: number;
+  spread?: Spread;
+  /** Add a bass note under each chord. */
+  bass?: boolean;
+  /**
+   * Bass behaviour (overrides `bass`). Every progression step is a chord,
+   * so `chords` and `single` add the root (or slash bass), `unison` the
+   * chord's root (the key a player would press), and `solo` drops the
+   * treble and keeps only that bass.
+   */
+  bassMode?: BassMode;
+  /** Voice-lead chord to chord (default true). */
+  lead?: boolean;
+  anchor?: number;
+}>;
+
+type RenderedProgression = Readonly<{
+  voiced: readonly VoicedChord[];
+  notes: readonly PerformedNote[];
+  bass: readonly PerformedNote[];
+}>;
+
+/**
+ * A progression as notes: voice-led voicings performed over consecutive
+ * spans of `beatsPerChord`, plus one sustained bass note per chord. The
+ * arp-random seed advances per chord so repeated chords vary but the
+ * whole render stays deterministic.
+ */
+function renderProgression(options: RenderOptions): RenderedProgression {
+  const span =
+    options.beatsPerChord && options.beatsPerChord > 0
+      ? options.beatsPerChord
+      : 4;
+  const start = options.start ?? 0;
+  const voiced = voiceProgression(options.key, options.chords, {
+    ...(options.inversion !== undefined
+      ? { inversion: options.inversion }
+      : {}),
+    ...(options.spread ? { spread: options.spread } : {}),
+    ...(options.anchor !== undefined ? { anchor: options.anchor } : {}),
+    ...(options.lead !== undefined ? { lead: options.lead } : {}),
+    bass: true,
+  });
+  const notes: PerformedNote[] = [];
+  const bass: PerformedNote[] = [];
+  const velocity = options.perform?.velocity ?? 0.8;
+  const mode: BassMode = options.bassMode ?? (options.bass ? "chords" : "off");
+  voiced.forEach((chord, index) => {
+    const at = start + index * span;
+    if (mode !== "solo")
+      notes.push(
+        ...perform(chord.pitches, at, span, {
+          ...options.perform,
+          seed: (options.perform?.seed ?? 0) + index,
+        }),
+      );
+    const source = options.chords[index]!;
+    const under =
+      mode === "off"
+        ? undefined
+        : mode === "unison"
+          ? bassNote({ ...source, bass: undefined })
+          : chord.bass;
+    if (under !== undefined)
+      bass.push({
+        pitch: under,
+        start: round6(at),
+        length: round6(span),
+        velocity,
+      });
+  });
+  return {
+    voiced:
+      mode !== "off"
+        ? voiced
+        : voiced.map(({ bass: _bass, ...rest }) => Object.freeze(rest)),
+    notes,
+    bass,
+  };
+}
+// END chord engine
+
 // ---------------------------------------------------------------------------
 // Internals
 
@@ -911,6 +4110,12 @@ function finite(value: unknown, label: string): number {
   return value;
 }
 
+function text(value: unknown, label: string): string {
+  if (typeof value !== "string" || value.length === 0 || value.length > 1024)
+    throw new DawgSdkError(`${label} must be a short string`);
+  return value;
+}
+
 function beat(value: unknown, label: string): number {
   const number = finite(value, label);
   if (number < 0) throw new DawgSdkError(`${label} must be ≥ 0 beats`);