@hraness/dawg 0.6.0 → 0.7.0

package/core/chords.ts

@@ -49,6 +49,7 @@ export const QUALITIES = [
   "mb6",
   "b6",
   "7#9",
+  "b5",
 ] as const;
 export type Quality = (typeof QUALITIES)[number];
 
@@ -65,6 +66,7 @@ const QUALITY_INTERVALS: Readonly<Record<Quality, readonly number[]>> =
     mb6: [0, 3, 7, 8],
     b6: [0, 4, 7, 8],
     "7#9": [0, 4, 7, 10, 15],
+    b5: [0, 4, 6],
   });
 
 /**
@@ -111,6 +113,17 @@ export type Chord = Readonly<{
   extensions: readonly Extension[];
   /** Slash bass pitch class, when not the root. */
   bass?: number | undefined;
+  /**
+   * Upper tensions beyond the four extension buttons, as semitones above
+   * the root (13 b9, 15 #9, 17 11, 18 #11, 21 13): only typed symbols
+   * such as `C11`, `G13` or `A7b9` carry them (0.6.1).
+   */
+  tensions?: readonly number[] | undefined;
+  /**
+   * The root's letter, 0..6 for C..B, when a roman numeral spelled it:
+   * `bVII` in C names Bb (not A#) and `vii` in F# names E# (not F).
+   */
+  letter?: number | undefined;
 }>;
 
 export function makeChord(
@@ -118,6 +131,7 @@ export function makeChord(
   quality: Quality,
   extensions: Iterable<Extension> = [],
   bass?: number,
+  tensions: readonly number[] = [],
 ): Chord {
   const held = new Set(extensions);
   const own = SECRET_EXTENSION[quality];
@@ -129,6 +143,11 @@ export function makeChord(
     quality,
     extensions: Object.freeze(ext),
     ...(slash !== undefined && slash !== pc ? { bass: slash } : {}),
+    ...(tensions.length > 0
+      ? {
+          tensions: Object.freeze([...new Set(tensions)].sort((a, b) => a - b)),
+        }
+      : {}),
   });
 }
 
@@ -136,6 +155,7 @@ export function makeChord(
 export function chordIntervals(chord: Chord): number[] {
   const set = new Set(QUALITY_INTERVALS[chord.quality]);
   for (const ext of chord.extensions) set.add(EXTENSION_INTERVAL[ext]);
+  for (const step of chord.tensions ?? []) set.add(step);
   // 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);
 }
@@ -182,12 +202,43 @@ export function noteName(pc: number, flats = false): string {
   return (flats ? FLAT_NAMES : SHARP_NAMES)[mod12(pc)]!;
 }
 
+const LETTERS = "CDEFGAB";
+const LETTER_PCS = [0, 2, 4, 5, 7, 9, 11] as const;
+
+/**
+ * `pc` spelled on letter `letter` (0..6, C..B) with one accidental at
+ * most (E#, Cb, Bb); undefined when that would need a double accidental.
+ */
+export function spellOnLetter(pc: number, letter: number): string | undefined {
+  const l = ((Math.trunc(letter) % 7) + 7) % 7;
+  const diff = ((mod12(pc) - LETTER_PCS[l]! + 18) % 12) - 6;
+  if (Math.abs(diff) > 1) return undefined;
+  return `${LETTERS[l]}${diff === 1 ? "#" : diff === -1 ? "b" : ""}`;
+}
+
+/** The letter (0..6, C..B) a key's tonic is spelled on. */
+function tonicLetter(key: Key): number {
+  return LETTERS.indexOf(noteName(key.tonic, keyUsesFlats(key))[0]!);
+}
+
 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`. */
 export function chordSuffix(chord: Chord): string {
+  if (chord.tensions?.length) {
+    // A typed extended chord keeps the symbol it was typed as.
+    const typed = TENSION_SUFFIXES.find(
+      ([, quality, ext, tensions]) =>
+        quality === chord.quality &&
+        ext.join() === chord.extensions.join() &&
+        tensions.join() === chord.tensions!.join(),
+    );
+    if (typed) return typed[0];
+    const names = chord.tensions.map((step) => TENSION_NAMES[step] ?? step);
+    return `${chordSuffix({ ...chord, tensions: undefined })}(${names.join(",")})`;
+  }
   const ext = new Set(chord.extensions);
   const b7 = ext.has("m7");
   const M7 = ext.has("M7");
@@ -248,6 +299,9 @@ export function chordSuffix(chord: Chord): string {
         base = `${seventh}(no3)`;
         if (nine) extras.push("9");
         break;
+      case "b5":
+        base = `${ninth}b5`;
+        break;
       default:
         base = seventh; // secret qualities returned above
     }
@@ -266,6 +320,7 @@ export function chordSuffix(chord: Chord): string {
     mb6: "m(b6)",
     b6: "(b6)",
     "7#9": "7#9",
+    b5: "(b5)",
   };
   base = triad[q];
   if (six && nine && (q === "maj" || q === "min")) return `${base}6/9`;
@@ -285,7 +340,11 @@ export function chordSuffix(chord: Chord): string {
 export function chordName(chord: Chord, flats = false): string {
   const slash =
     chord.bass === undefined ? "" : `/${noteName(chord.bass, flats)}`;
-  return `${noteName(chord.root, flats)}${chordSuffix(chord)}${slash}`;
+  const root =
+    (chord.letter === undefined
+      ? undefined
+      : spellOnLetter(chord.root, chord.letter)) ?? noteName(chord.root, flats);
+  return `${root}${chordSuffix(chord)}${slash}`;
 }
 
 /** Suffix → quality and extensions, longest first when parsing. */
@@ -350,10 +409,74 @@ const SUFFIXES: readonly (readonly [string, Quality, readonly Extension[]])[] =
     ["(b6)", "b6", []],
     ["addb6", "b6", []],
     ["7#9", "7#9", []],
+    // 0.7: more spellings of the same chords.
+    ["-maj7", "min", ["M7"]],
+    ["mmaj7", "min", ["M7"]],
+    ["mMaj7", "min", ["M7"]],
+    ["m(maj7)", "min", ["M7"]],
+    ["-Δ7", "min", ["M7"]],
+    ["mΔ7", "min", ["M7"]],
+    ["add2", "maj", ["9"]],
+    ["2", "maj", ["9"]],
+    ["madd2", "min", ["9"]],
+    ["6add9", "maj", ["6", "9"]],
+    ["m6add9", "min", ["6", "9"]],
+    ["-6", "min", ["6"]],
+    ["-9", "min", ["m7", "9"]],
+    ["dom9", "maj", ["m7", "9"]],
+    ["aug(maj7)", "aug", ["M7"]],
+    ["augmaj7", "aug", ["M7"]],
+    ["+maj7", "aug", ["M7"]],
+    ["aug9", "aug", ["m7", "9"]],
+    ["+9", "aug", ["m7", "9"]],
+    ["m(maj9)", "min", ["M7", "9"]],
+    ["mmaj9", "min", ["M7", "9"]],
+    ["dim(maj7)", "dim", ["M7"]],
+    ["7(no3)", "5", ["m7"]],
+    ["maj7(no3)", "5", ["M7"]],
   ];
-const SUFFIX_TABLE = new Map(
-  SUFFIXES.map(([suffix, quality, ext]) => [suffix, { quality, ext }]),
-);
+
+/** Typed upper-tension chords (0.6.1): suffix, quality, buttons, tensions. */
+const TENSION_SUFFIXES: readonly (readonly [
+  string,
+  Quality,
+  readonly Extension[],
+  readonly number[],
+])[] = [
+  ["11", "maj", ["m7", "9"], [17]],
+  ["m11", "min", ["m7", "9"], [17]],
+  ["maj11", "maj", ["M7", "9"], [17]],
+  ["add11", "maj", [], [17]],
+  ["madd11", "min", [], [17]],
+  ["13", "maj", ["m7", "9"], [21]],
+  ["m13", "min", ["m7", "9"], [21]],
+  ["maj13", "maj", ["M7", "9"], [21]],
+  ["7b9", "maj", ["m7"], [13]],
+  ["7#11", "maj", ["m7"], [18]],
+  ["maj7#11", "maj", ["M7"], [18]],
+  ["M7#11", "maj", ["M7"], [18]],
+  ["7b13", "maj", ["m7"], [20]],
+  ["13b9", "maj", ["m7"], [13, 21]],
+];
+
+const TENSION_NAMES: Readonly<Record<number, string>> = Object.freeze({
+  13: "b9",
+  15: "#9",
+  17: "11",
+  18: "#11",
+  20: "b13",
+  21: "13",
+});
+
+const SUFFIX_TABLE = new Map<string, SuffixEntry>([
+  ...SUFFIXES.map(
+    ([suffix, quality, ext]) => [suffix, { quality, ext }] as const,
+  ),
+  ...TENSION_SUFFIXES.map(
+    ([suffix, quality, ext, tensions]) =>
+      [suffix, { quality, ext, tensions }] as const,
+  ),
+]);
 
 const LETTER: Readonly<Record<string, number>> = Object.freeze({
   c: 0,
@@ -378,6 +501,81 @@ export function parsePitchClass(text: string): number | undefined {
   return mod12(LETTER[match[1]!.toLowerCase()]! + accidental);
 }
 
+/** Alteration → upper tension (semitones above the root). */
+const ALTERATION_TENSION: Readonly<Record<string, number>> = Object.freeze({
+  b9: 13,
+  "#9": 15,
+  "11": 17,
+  "#11": 18,
+  "+11": 18,
+  b13: 20,
+  "13": 21,
+});
+
+const TOKEN = "b5|#5|\\+5|b9|#9|#11|\\+11|b13|alt|add9|add11|add13|11|13|9|6";
+/** Bare alterations or parenthesized comma lists of them, in any order. */
+const ALTERATIONS = new RegExp(
+  `^(?:(?:${TOKEN})|\\((?:${TOKEN})(?:,(?:${TOKEN}))*\\))+$`,
+);
+
+type SuffixEntry = {
+  quality: Quality;
+  ext: readonly Extension[];
+  tensions?: readonly number[];
+};
+
+/**
+ * A suffix the table does not list, read as a listed base followed by
+ * alterations, bare or in parentheses: `7#5`, `9#11`, `13#11`, `7b9b13`,
+ * `9b5`, `maj7+5`, `7alt`, `7(b9,#9)`. A raised fifth makes the triad
+ * augmented, a lowered one makes a major triad `b5` (a minor one
+ * diminished); `alt` is b9, #9, #11 and b13 over a dominant seventh.
+ */
+function parseAlteredSuffix(suffix: string): SuffixEntry | undefined {
+  for (let cut = suffix.length - 1; cut >= 0; cut -= 1) {
+    const base = SUFFIX_TABLE.get(suffix.slice(0, cut));
+    if (!base) continue;
+    const raw = suffix.slice(cut);
+    if (!ALTERATIONS.test(raw)) continue;
+    const rest = raw.replace(/[(),]/g, "");
+    const tokens = rest.match(
+      /b5|#5|\+5|b9|#9|#11|\+11|b13|alt|add9|add11|add13|11|13|9|6/g,
+    );
+    if (!tokens || tokens.join("") !== rest) continue;
+    let quality: Quality = base.quality;
+    const ext = new Set<Extension>(base.ext);
+    const tensions = new Set<number>(base.tensions ?? []);
+    let ok = true;
+    for (const token of tokens) {
+      if (token === "#5" || token === "+5") {
+        if (quality === "maj" || quality === "aug") quality = "aug";
+        else ok = false;
+      } else if (token === "b5") {
+        if (quality === "maj" || quality === "b5") quality = "b5";
+        else if (quality === "min" || quality === "dim") quality = "dim";
+        else ok = false;
+      } else if (token === "alt") {
+        if (quality !== "maj") ok = false;
+        ext.add("m7");
+        for (const step of [13, 15, 18, 20]) tensions.add(step);
+      } else if (token === "9" || token === "add9") ext.add("9");
+      else if (token === "6") ext.add("6");
+      else {
+        const step = ALTERATION_TENSION[token.replace(/^add/, "")];
+        if (step === undefined) ok = false;
+        else tensions.add(step);
+      }
+    }
+    if (!ok) continue;
+    return {
+      quality,
+      ext: [...ext],
+      tensions: [...tensions].sort((a, b) => a - b),
+    };
+  }
+  return undefined;
+}
+
 /** Parse a chord symbol (`Cm7`, `F#dim`, `Bbmaj9`, `G7sus4`, `C/E`). */
 export function parseChord(symbol: string): Chord | undefined {
   if (typeof symbol !== "string" || symbol.length > 24) return undefined;
@@ -388,14 +586,15 @@ export function parseChord(symbol: string): Chord | undefined {
   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] ?? "");
+  const entry =
+    SUFFIX_TABLE.get(match[3] ?? "") ?? parseAlteredSuffix(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);
+  return makeChord(root, entry.quality, entry.ext, bass, entry.tensions);
 }
 
 // ---------------------------------------------------------------------------
@@ -448,7 +647,15 @@ const MODE_ALIASES: Readonly<Record<string, ModeName>> = Object.freeze({
 });
 
 export type ScaleFamily =
-  "pentatonic" | "blues" | "maqam" | "dastgah" | "raga" | "messiaen";
+  | "pentatonic"
+  | "blues"
+  | "maqam"
+  | "dastgah"
+  | "raga"
+  | "messiaen"
+  | "chromatic"
+  | "overtone"
+  | "quarter-tone";
 
 /**
  * Scales beyond the chord modes, for keys such as `D bayati`, `C yaman` or
@@ -495,6 +702,12 @@ export const SCALES = Object.freeze({
     family: "blues",
     aliases: ["major blues"],
   },
+  "yonanuki-minor": {
+    steps: [0, 2, 3, 7, 8],
+    mode: "minor",
+    family: "pentatonic",
+    aliases: ["yonanuki", "yonanuki minor", "enka minor"],
+  },
   hijaz: {
     steps: [0, 1, 4, 5, 7, 8, 10],
     mode: "phrygian-dominant",
@@ -671,6 +884,32 @@ export const SCALES = Object.freeze({
     mode: "harmonic-minor",
     family: "messiaen",
   },
+  // All twelve pitch classes: the field of free atonality and the row.
+  chromatic: {
+    steps: [0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11],
+    mode: "minor",
+    family: "chromatic",
+    aliases: ["twelve-tone", "aggregate"],
+  },
+  // Partials 8 to 15 of the harmonic series over the tonic (Grisey,
+  // Murail): the acoustic scale with the 11th and 13th partials' and the
+  // 7th's just pitches, which its named tuning applies.
+  "harmonic-series": {
+    steps: [0, 2, 4, 6, 7, 9, 10, 11],
+    mode: "mixolydian",
+    family: "overtone",
+    intonation: [0, 204, 386, 551, 702, 841, 969, 1088],
+    aliases: ["overtone", "overtone-scale", "partials"],
+  },
+  // Each tempered degree of the major scale beside its quarter-tone
+  // shadow (Haba, Wyschnegradsky): neutral 2nd, 3rd, 6th and 7th and a
+  // quarter-sharp 4th, sounded as note cents over twelve-tone keys.
+  "quarter-tone": {
+    steps: [0, 1.5, 2, 3.5, 4, 5, 5.5, 7, 8.5, 9, 10.5],
+    mode: "major",
+    family: "quarter-tone",
+    aliases: ["quartertone", "24-tone"],
+  },
 } as const satisfies Record<string, ScaleInfo>);
 export type ScaleName = keyof typeof SCALES;
 export const SCALE_NAMES = Object.keys(SCALES) as ScaleName[];
@@ -877,9 +1116,14 @@ export function romanOf(key: Key, chord: Chord): string {
   if (degree < 0) {
     // Name chromatic roots against the major scale: bIII, #iv°.
     const major = MODES.major.map((step) => mod12(key.tonic + step));
+    const natural = major.indexOf(chord.root);
     const flat = major.indexOf(mod12(chord.root + 1));
     const sharp = major.indexOf(mod12(chord.root - 1));
-    if (flat >= 0) {
+    if (natural >= 0) {
+      // A major-scale note the mode alters: ♮II in Phrygian.
+      degree = natural;
+      accidental = "♮";
+    } else if (flat >= 0) {
       degree = flat;
       accidental = "b";
     } else {
@@ -890,7 +1134,6 @@ export function romanOf(key: Key, chord: Chord): string {
   const lower =
     chord.quality === "min" ||
     chord.quality === "dim" ||
-    chord.quality === "5" ||
     chord.quality === "madd4" ||
     chord.quality === "mb6";
   const numeral = NUMERALS[degree]!;
@@ -907,7 +1150,33 @@ export function romanOf(key: Key, chord: Chord): string {
         : ext.has("M7")
           ? "maj7"
           : "";
-  return `${accidental}${body}${mark}${seventh}`;
+  // The short numeral when it reads back as this chord; else the chord's
+  // own suffix in brackets (`I[7]`, `i[m6]`, `V[7#9]`), which is exact.
+  const plain = `${accidental}${body}${mark}${seventh}`;
+  const bare = makeChord(
+    chord.root,
+    chord.quality,
+    chord.extensions,
+    undefined,
+    chord.tensions,
+  );
+  for (const candidate of [
+    plain,
+    `${accidental}${body}${mark}${seventh === "7" ? "dom7" : seventh}`,
+  ])
+    if (sameChord(parseRoman(key, candidate), bare)) return candidate;
+  return `${accidental}${body}[${chordSuffix(bare)}]`;
+}
+
+function sameChord(a: Chord | undefined, b: Chord): boolean {
+  return (
+    a !== undefined &&
+    a.root === b.root &&
+    a.quality === b.quality &&
+    a.bass === b.bass &&
+    a.extensions.join() === b.extensions.join() &&
+    (a.tensions ?? []).join() === (b.tensions ?? []).join()
+  );
 }
 
 /**
@@ -920,31 +1189,64 @@ export function romanOf(key: Key, chord: Chord): string {
  * major). `7` adds the diatonic seventh; `maj7`/`M7` and `dom7` are exact.
  */
 export function parseRoman(key: Key, text: string): Chord | undefined {
-  if (typeof text !== "string" || text.length > 16) return undefined;
+  return romanIn(key, text, tonicLetter(key));
+}
+
+/** `parseRoman` with the tonic spelled on `tonic` (0..6, C..B). */
+function romanIn(key: Key, text: string, tonic: number): Chord | undefined {
+  if (typeof text !== "string" || text.length > 32) return undefined;
   const trimmed = text.trim();
+  const exact = trimmed.match(
+    /^(b|#|♭|♯|♮)?(vii|vi|v|iv|iii|ii|i|VII|VI|V|IV|III|II|I)\[([^\]]*)\]$/,
+  );
+  if (exact) {
+    // `I[7]`: the numeral names the root, the bracket is a chord suffix.
+    const degree = NUMERALS.indexOf(exact[2]!.toLowerCase());
+    const shift =
+      exact[1] === "b" || exact[1] === "♭"
+        ? -1
+        : exact[1] === "♮" || !exact[1]
+          ? 0
+          : 1;
+    const root = !exact[1]
+      ? scaleOf(key)[degree]
+      : mod12(key.tonic + MODES.major[degree]! + shift);
+    if (root === undefined) return undefined;
+    const letter = (tonic + degree) % 7;
+    const chord = parseChord(
+      `${spellOnLetter(root, letter) ?? noteName(root)}${exact[3]!}`,
+    );
+    return chord && Object.freeze({ ...chord, letter });
+  }
   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]!);
+    const target = romanIn(key, slash[2]!, tonic);
     if (!target) return undefined;
-    const sub = parseRoman({ tonic: target.root, mode: "major" }, slash[1]!);
-    return sub;
+    return romanIn(
+      { tonic: target.root, mode: "major" },
+      slash[1]!,
+      target.letter ?? tonic,
+    );
   }
   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)?$/,
+    /^(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;
+    match[1] === "b" || match[1] === "♭"
+      ? -1
+      : match[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 root = !match[1]
+    ? 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 =
@@ -998,7 +1300,10 @@ export function parseRoman(key: Key, text: string): Chord | undefined {
       quality = "sus2";
       break;
   }
-  return makeChord(root, quality, ext);
+  return Object.freeze({
+    ...makeChord(root, quality, ext),
+    letter: (tonic + degree) % 7,
+  });
 }
 
 // ---------------------------------------------------------------------------
@@ -1040,7 +1345,17 @@ export function rotate(pitches: readonly number[], steps: number): number[] {
 
 export function rootPosition(chord: Chord, anchor = 60): number[] {
   const rootPitch = anchor + mod12(chord.root - anchor);
-  return chordIntervals(chord).map((step) => rootPitch + step);
+  const steps = chordIntervals(chord);
+  // A natural 11 over a major 3rd and a 7th is the avoid-note clash (E
+  // under F a minor 9th up in C11), so the voicing drops the 3rd: C11 is
+  // C G Bb D F, the sus voicing; C13 already leaves the 11 out.
+  const clash =
+    steps.includes(4) &&
+    steps.includes(17) &&
+    (steps.includes(10) || steps.includes(11));
+  return steps
+    .filter((step) => !(clash && step === 4))
+    .map((step) => rootPitch + step);
 }
 
 /** Open voicings: `open` drops the second voice from the top an octave
@@ -1209,6 +1524,8 @@ export const PERFORM_MODES = [
   "harp",
   "slop",
   "pattern",
+  // 0.6.1: fretboard-voiced strokes (see `voiceGuitar`, `strokeVoicing`).
+  "guitar",
 ] as const;
 export type PerformMode = (typeof PERFORM_MODES)[number];
 
@@ -1228,6 +1545,23 @@ export type PerformOptions = Readonly<{
   pattern?: string | number;
   /** 0..1. */
   velocity?: number;
+  /** Guitar mode: the stroke grid (a STROKE_PATTERNS name or D U d u x - .). */
+  strokes?: string;
+  /** Guitar mode: grid step in beats, default 1/2. */
+  step?: number;
+  /** Guitar mode: seconds a full six-string down stroke takes, default 0.022. */
+  speed?: number;
+  /** Guitar mode: tempo in BPM that `speed` converts with, default 120. */
+  tempo?: number;
+  /** Guitar mode: the guitar's tuning, capo, hand, ring and position. */
+  guitar?: GuitarSetup;
+  /** Guitar mode: the chord's root pitch class (default: the lowest note). */
+  root?: number;
+  /**
+   * Guitar mode: a slash bass pitch class that must sound lowest, even when
+   * it is not a chord tone (B/E keeps its E pedal). Default: the lowest note.
+   */
+  slash?: number;
 }>;
 
 export type PerformedNote = Readonly<{
@@ -1544,6 +1878,24 @@ export function perform(
         }
       return out.sort((a, b) => a.start - b.start || a.pitch - b.pitch);
     }
+    case "guitar": {
+      const bass = options.slash ?? notes[0]!;
+      const voicing = voiceGuitar(
+        notes.map(mod12),
+        mod12(bass),
+        options.root ?? mod12(bass),
+        options.guitar,
+      );
+      if (!voicing) return notes.map((pitch) => at(pitch, start, end));
+      return strokeVoicing(voicing, start, length, {
+        ...(options.strokes !== undefined ? { strokes: options.strokes } : {}),
+        ...(options.step !== undefined ? { step: options.step } : {}),
+        ...(options.speed !== undefined ? { speed: options.speed } : {}),
+        ...(options.tempo !== undefined ? { tempo: options.tempo } : {}),
+        velocity,
+        strings: guitarStrings(options.guitar?.tune).length,
+      });
+    }
     case "harp": {
       const gap = Math.max(0, options.strum ?? DEFAULT_STRUM * 2);
       return spanned.map((pitch, index) =>
@@ -1578,6 +1930,382 @@ export function perform(
   }
 }
 
+// ---------------------------------------------------------------------------
+// Fretboard (0.6.1): guitar voicings and strokes
+
+/**
+ * Open-string MIDI pitches, low string to high, for `guitar tune <name>`.
+ * Ported from the guitar design lane (proto/guitar/strum.ts TUNINGS).
+ */
+export const GUITAR_TUNINGS = Object.freeze({
+  standard: [40, 45, 50, 55, 59, 64],
+  dropd: [38, 45, 50, 55, 59, 64],
+  doubledropd: [38, 45, 50, 55, 59, 62],
+  dadgad: [38, 45, 50, 55, 57, 62],
+  openg: [38, 43, 50, 55, 59, 62],
+  opend: [38, 45, 50, 54, 57, 62],
+  opene: [40, 47, 52, 56, 59, 64],
+  halfdown: [39, 44, 49, 54, 58, 63],
+  nashville: [52, 57, 62, 67, 59, 64],
+  bass: [28, 33, 38, 43],
+  ukulele: [67, 60, 64, 69],
+  requinto: [45, 50, 55, 60, 64, 69],
+} as const satisfies Record<string, readonly number[]>);
+export type GuitarTuningName = keyof typeof GUITAR_TUNINGS;
+export const GUITAR_TUNING_NAMES = Object.keys(
+  GUITAR_TUNINGS,
+) as GuitarTuningName[];
+
+/** How a guitar is set up for voicing chords (`Track.guitar`). */
+export type GuitarSetup = Readonly<{
+  /** A GUITAR_TUNINGS name or open-string pitches low to high. */
+  tune?: string | readonly number[];
+  /** Capo fret 0..12. */
+  capo?: number;
+  /** Hand stretch in frets 3..6 (default 4: one fret per finger). */
+  hand?: number;
+  /** 0 closed shapes (no open strings) .. 1 prefer ringing open strings. */
+  ring?: number;
+  /** Preferred fret position 0..12 (0 open position). */
+  position?: number;
+}>;
+
+/** One fretted chord: frets per string low to high (-1 muted). */
+export type GuitarVoicing = Readonly<{
+  frets: readonly number[];
+  /** Sounding pitches, low string to high. */
+  pitches: readonly number[];
+  /** The string each pitch sounds on. */
+  strings: readonly number[];
+}>;
+
+/** Open-string pitches for a tuning name or list (standard when unknown). */
+export function guitarStrings(tune: GuitarSetup["tune"]): readonly number[] {
+  if (Array.isArray(tune)) return tune as readonly number[];
+  const name = String(tune ?? "standard")
+    .toLowerCase()
+    .replace(/[\s_-]/g, "");
+  return (
+    (GUITAR_TUNINGS as Record<string, readonly number[]>)[name] ??
+    GUITAR_TUNINGS.standard
+  );
+}
+
+/**
+ * Fingers a fretting uses. Strings at the lowest fret count as one barre
+ * only when no open string lies between them (a barre cannot skip an open
+ * string); otherwise one finger each.
+ */
+export function guitarFingers(frets: readonly number[]): number {
+  const fretted = frets.filter((f) => f > 0);
+  if (fretted.length === 0) return 0;
+  const min = Math.min(...fretted);
+  const at = frets.flatMap((f, i) => (f === min ? [i] : []));
+  const between = frets.slice(at[0]!, at[at.length - 1]! + 1);
+  const barre = at.length > 1 && !between.includes(0);
+  return (barre ? 1 : at.length) + fretted.filter((f) => f > min).length;
+}
+
+/**
+ * The chord tones a voicing must keep, most required first, after dropping
+ * `drops` tones in the guitarist's order: the 5th, then the 9th; the root,
+ * the 3rd and the 7th always stay (after the design lane's review).
+ */
+function requiredTones(tones: readonly number[], root: number, drops: number) {
+  // The 5th, then the 11th (only beside a 3rd: a sus4 keeps its 4th), then
+  // the 9th. dawg's symbols reach an 11th through m(add4)/madd4 (+9).
+  const third = tones.some((pc) => [3, 4].includes(mod12(pc - root)));
+  const order = (third ? [7, 5, 2] : [7, 2]).map((step) => mod12(root + step));
+  const dropped = order.filter((pc) => tones.includes(pc)).slice(0, drops);
+  return tones.filter((pc) => !dropped.includes(pc));
+}
+
+/**
+ * The most playable fretting of pitch classes `tones` over `bass` on a
+ * guitar `setup`: the bass is the lowest sounding note, every required
+ * tone sounds, at most four fingers within a `hand`-fret stretch, mutes
+ * only under the bass or one inside, and no barre over an open string.
+ * Cost prefers more strings, low positions, open strings (by `ring`), a
+ * fifth present, no doubled third, and small moves from `previous`.
+ * Undefined when nothing fits. Ported from proto/guitar/strum.ts.
+ */
+export function voiceGuitar(
+  tones: readonly number[],
+  bass: number,
+  root: number,
+  setup: GuitarSetup = {},
+  previous?: readonly number[],
+): GuitarVoicing | undefined {
+  // Play mode voices every pad press; dense chords at a wide hand take
+  // ~15 ms to search, so repeats come from a small LRU (results are frozen).
+  const key = JSON.stringify([
+    [...new Set([...tones, bass].map(mod12))],
+    mod12(bass),
+    mod12(root),
+    setup.tune ?? null,
+    setup.capo ?? null,
+    setup.hand ?? null,
+    setup.ring ?? null,
+    setup.position ?? null,
+    previous ?? null,
+  ]);
+  if (voicingCache.has(key)) {
+    const hit = voicingCache.get(key);
+    voicingCache.delete(key);
+    voicingCache.set(key, hit);
+    return hit;
+  }
+  const voiced = searchGuitar(tones, bass, root, setup, previous);
+  voicingCache.set(key, voiced);
+  if (voicingCache.size > VOICING_CACHE_SIZE)
+    voicingCache.delete(voicingCache.keys().next().value!);
+  return voiced;
+}
+
+const VOICING_CACHE_SIZE = 256;
+const voicingCache = new Map<string, GuitarVoicing | undefined>();
+
+function searchGuitar(
+  tones: readonly number[],
+  bass: number,
+  root: number,
+  setup: GuitarSetup,
+  previous?: readonly number[],
+): GuitarVoicing | undefined {
+  const pcs = [...new Set([...tones, bass].map(mod12))];
+  const capo = clampInt(setup.capo ?? 0, 0, 12);
+  const open = guitarStrings(setup.tune).map((pitch) => pitch + capo);
+  const n = open.length;
+  const ring = Math.min(1, Math.max(0, setup.ring ?? 0.5));
+  const stretch = clampInt(setup.hand ?? 4, 3, 6);
+  const fifth = mod12(root + 7);
+  const third = pcs.find((pc) => [3, 4].includes(mod12(pc - root)));
+  const prev = previous ? [...previous].sort((a, b) => a - b) : undefined;
+  for (let drops = 0; drops <= 3; drops += 1) {
+    const required = requiredTones(pcs, root, drops);
+    let best: { frets: number[]; cost: number } | undefined;
+    const choose = (frets: readonly number[]) => {
+      const idx = frets.flatMap((f, i) => (f < 0 ? [] : [i]));
+      if (idx.length < Math.min(n, n >= 6 ? 4 : 3)) return;
+      const interior = frets.slice(idx[0]).filter((f) => f < 0).length;
+      if (interior > (n >= 6 ? 1 : 0)) return;
+      const pitches = idx.map((i) => open[i]! + frets[i]!);
+      if (mod12(Math.min(...pitches)) !== mod12(bass)) return;
+      const sounding = new Set(pitches.map(mod12));
+      if (required.some((pc) => !sounding.has(pc))) return;
+      const fingers = guitarFingers(frets);
+      if (fingers > 4) return;
+      const fretted = frets.filter((f) => f > 0);
+      const span = fretted.length
+        ? Math.max(...fretted) - Math.min(...fretted)
+        : 0;
+      if (span > stretch - 1) return;
+      const opens = frets.filter((f) => f === 0).length;
+      if (ring === 0 && opens > 0) return;
+      const pos = fretted.length ? Math.min(...fretted) : 0;
+      let cost =
+        span * 0.6 +
+        pos * 0.25 +
+        fingers * 0.4 -
+        idx.length -
+        opens * 0.7 * ring;
+      cost += interior * 1.5;
+      if (!sounding.has(fifth) && pcs.includes(fifth)) cost += 0.6;
+      if (
+        third !== undefined &&
+        pitches.filter((p) => mod12(p) === third).length > 1
+      )
+        cost += 0.5;
+      if (setup.position !== undefined)
+        cost += Math.abs(pos - setup.position) * 0.5;
+      if (prev && prev.length) {
+        const cur = [...pitches].sort((a, b) => a - b);
+        let move = 0;
+        for (let i = 0; i < cur.length; i += 1)
+          move += Math.abs(cur[i]! - prev[Math.min(i, prev.length - 1)]!);
+        cost += move * 0.05;
+      }
+      if (
+        !best ||
+        cost < best.cost - 1e-9 ||
+        (Math.abs(cost - best.cost) <= 1e-9 && frets.join() < best.frets.join())
+      )
+        best = { frets: [...frets], cost };
+    };
+    for (let p = 1; p <= 12; p += 1) {
+      const options = open.map((o) => {
+        const list = [-1];
+        if (pcs.includes(mod12(o))) list.push(0);
+        for (let f = p; f < p + stretch; f += 1)
+          if (pcs.includes(mod12(o + f))) list.push(f);
+        return list;
+      });
+      const frets = new Array<number>(n).fill(-1);
+      const walk = (s: number): void => {
+        if (s === n) return choose(frets);
+        for (const f of options[s]!) {
+          frets[s] = f;
+          walk(s + 1);
+        }
+      };
+      walk(0);
+    }
+    if (best) {
+      const { frets } = best as { frets: number[] };
+      const strings = frets.flatMap((f, i) => (f < 0 ? [] : [i]));
+      return Object.freeze({
+        frets: Object.freeze(frets),
+        pitches: Object.freeze(strings.map((i) => open[i]! + frets[i]!)),
+        strings: Object.freeze(strings),
+      });
+    }
+  }
+  return undefined;
+}
+
+/** A voicing as tab, low string first: `x 3 2 0 1 0`. */
+export function guitarTab(frets: readonly number[]): string {
+  return frets.map((f) => (f < 0 ? "x" : String(f))).join(" ");
+}
+
+/**
+ * Stroke grids for perform mode `guitar`, one character per step: D down
+ * (all strings), U up (top four), d light down (top four), u light up (top
+ * three), x muted chuck, `-` or `.` rest (strings ring on). After the
+ * design lane's STRUM_PATTERNS.
+ */
+export const STROKE_PATTERNS = Object.freeze({
+  down: "D",
+  folk: "D-DU-UDU",
+  pop: "D-DU-UD-",
+  punk: "DDDDDDDD",
+  funk: "xUxUDUxUxUDUxUxU",
+  reggae: "-D-D",
+  waltz: "Ddd",
+  jangle: "D-DUDUDU",
+  island: "D-DU-UDU",
+} as const satisfies Record<string, string>);
+export const STROKE_PATTERN_NAMES = Object.keys(STROKE_PATTERNS);
+const STROKE_CHARS = /^[DUdux.\-]+$/;
+
+/** Default seconds a full six-string down stroke takes (22 ms). */
+export const DEFAULT_STROKE_SPEED = 0.022;
+/** Default stroke grid step in beats (8ths). */
+export const DEFAULT_STROKE_STEP = 0.5;
+
+/** A stroke grid by name, or a literal grid of D U d u x - .; undefined if bad. */
+export function strokeGrid(text: string | undefined): string | undefined {
+  const raw = (text ?? "down").trim();
+  const named = (STROKE_PATTERNS as Record<string, string>)[raw.toLowerCase()];
+  if (named) return named;
+  const grid = raw.replace(/[|\s]/g, "");
+  return grid.length > 0 && grid.length <= 64 && STROKE_CHARS.test(grid)
+    ? grid
+    : undefined;
+}
+
+/**
+ * Strum fretted `voicing` from `start` for `length` beats with stroke grid
+ * `strokes` (repeats every grid length, one step per `step` beats). A full
+ * down stroke sweeps the six strings in `speed` seconds at `tempo` BPM;
+ * each struck string rings until it is struck again or the chord ends; a
+ * chuck (x) is a short muted hit that stops the strings. Velocity accents
+ * downbeats and lightens upstrokes.
+ */
+export function strokeVoicing(
+  voicing: GuitarVoicing,
+  start: number,
+  length: number,
+  options: Readonly<{
+    strokes?: string;
+    step?: number;
+    speed?: number;
+    tempo?: number;
+    velocity?: number;
+    strings?: number;
+  }> = {},
+): PerformedNote[] {
+  const grid = strokeGrid(options.strokes) ?? "D";
+  const step =
+    options.step && options.step > 0 ? options.step : DEFAULT_STROKE_STEP;
+  const tempo = options.tempo && options.tempo > 0 ? options.tempo : 120;
+  const sweep =
+    (Math.max(0, options.speed ?? DEFAULT_STROKE_SPEED) * tempo) / 60;
+  const base = options.velocity ?? 0.8;
+  const total = Math.max(2, options.strings ?? 6);
+  const sounding = voicing.strings;
+  const end = start + length;
+  type Open = { note: PerformedNote; index: number };
+  const ringing = new Map<number, Open>();
+  const out: PerformedNote[] = [];
+  const stop = (string: number, at: number) => {
+    const held = ringing.get(string);
+    if (!held) return;
+    const cut = round6(
+      Math.max(1e-3, Math.min(held.note.length, at - held.note.start)),
+    );
+    out[held.index] = { ...held.note, length: cut };
+    ringing.delete(string);
+  };
+  const steps = Math.max(1, Math.round(length / step));
+  for (let s = 0; s < steps; s += 1) {
+    const ch = grid[s % grid.length]!;
+    if (ch === "-" || ch === ".") continue;
+    const t0 = start + s * step;
+    if (t0 >= end - 1e-9) break;
+    const beat = s * step;
+    const accent =
+      Math.abs(beat - Math.round(beat)) < 1e-9
+        ? Math.round(beat) % 2 === 0
+          ? 1
+          : 0.92
+        : 0.82;
+    let order: number[];
+    let velocity = base * accent;
+    let ring = end - t0;
+    const all = sounding.map((_, k) => k);
+    switch (ch) {
+      case "D":
+        order = all;
+        break;
+      case "U":
+        order = all.slice(-4).reverse();
+        velocity *= 0.85;
+        break;
+      case "d":
+        order = all.slice(-4);
+        velocity *= 0.62;
+        break;
+      case "u":
+        order = all.slice(-3).reverse();
+        velocity *= 0.55;
+        break;
+      default:
+        order = all;
+        velocity *= 0.5;
+        ring = Math.min(ring, 0.03 * (tempo / 60));
+    }
+    const first = sounding[order[0]!]!;
+    order.forEach((k, position) => {
+      const string = sounding[k]!;
+      const at = t0 + (Math.abs(string - first) / (total - 1)) * sweep;
+      if (at >= end - 1e-9) return;
+      stop(string, at);
+      const note: PerformedNote = {
+        pitch: voicing.pitches[k]!,
+        start: round6(at),
+        length: round6(Math.max(1e-3, Math.min(ring, end - at))),
+        velocity: round6(
+          Math.max(0.05, Math.min(1, velocity * (1 - 0.04 * position))),
+        ),
+      };
+      out.push(note);
+      if (ch !== "x") ringing.set(string, { note, index: out.length - 1 });
+    });
+  }
+  return out.sort((a, b) => a.start - b.start || a.pitch - b.pitch);
+}
+
 // ---------------------------------------------------------------------------
 // Progressions
 
@@ -1969,6 +2697,14 @@ export function renderProgression(options: RenderOptions): RenderedProgression {
         ...perform(chord.pitches, at, span, {
           ...options.perform,
           seed: (options.perform?.seed ?? 0) + index,
+          ...(options.perform?.mode === "guitar"
+            ? {
+                root: options.chords[index]!.root,
+                ...(options.chords[index]!.bass !== undefined
+                  ? { slash: options.chords[index]!.bass }
+                  : {}),
+              }
+            : {}),
         }),
       );
     const source = options.chords[index]!;
@@ -2000,6 +2736,6 @@ export function renderProgression(options: RenderOptions): RenderedProgression {
 export const CHORD_PROCESS = [
   "Chords (Orchid-style): pick chords from the song key's diatonic set (in C major: C Dm Em F G Am Bdim; minor keys i ii° III iv v VI VII, V major for cadences).",
   "Move tonic (I vi iii) → predominant (IV ii) → dominant (V vii°) → tonic; loops end on V or IV to lead home.",
-  "Add sevenths/9ths as colour (6, m7, M7, 9 extensions); voice-lead each chord to the inversion nearest the previous one in C3–G5 so common tones hold; put the root an octave or two below as bass.",
+  "Add sevenths/9ths as color (6, m7, M7, 9 extensions); voice-lead each chord to the inversion nearest the previous one in C3–G5 so common tones hold; put the root an octave or two below as bass.",
   "Use suggest_progression to get voice-led chords and write_chords to write them (block, strum, arpeggio, harp, slop or a rhythm pattern; bassMode chords|unison|single|solo), instead of hand-placing chord notes with add_notes.",
 ].join(" ");