@hraness/dawg 0.5.0 → 0.6.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.19.0";
+export const SDK_VERSION = "1.31.0";
 /** Major of `SDK_VERSION`; `dawg.json` records it as `sdk`. */
 export const SDK_MAJOR = 1;
 
@@ -1277,6 +1277,36 @@ export type SampleSpec = Readonly<{
   accelerate?: number;
   /** Like Tidal `squiz`: pitch-raise ratio per zero-crossing cycle (1..32). */
   squiz?: number;
+  /** The file's own tempo (20..400, SDK 1.20.0): the window follows the song's tempo map. */
+  bpm?: number;
+  /** How a fitted window changes time (SDK 1.20.0): `"repitch"` (tape), `"beats"` (onset slices), `"tones"` (keeps pitch). */
+  fitmode?: "repitch" | "beats" | "tones";
+  /** Window length in beats (SDK 1.20.0); `fit` wins over `bpm`, `bpm` over `len`. */
+  len?: number;
+  /** Pitch shift in semitones at the same length (−24..24, SDK 1.29.0). */
+  shift?: number;
+  /** Formant shift in semitones with `shift` (SDK 1.29.0): absent follows the pitch, 0 keeps the formants. */
+  formant?: number;
+  /** Like Strudel `fadeTime`: release fade in seconds (0..2, SDK 1.29.0). */
+  fadeTime?: number;
+  /** Like Strudel `fadeInTime`: attack fade in seconds (0..2, SDK 1.29.0). */
+  fadeInTime?: number;
+  /** Where `resample` rendered the file from (informational, SDK 1.29.0). */
+  from?: SampleProvenanceSpec;
+  /** Velocity layer (SDK 1.31.0, SFZ lovel/hivel): MIDI velocities `[lo, hi]` this voice plays. */
+  vel?: readonly [number, number];
+  /** Round-robin group (SDK 1.31.0, SFZ seq_length): voices in a group take turns, A B A B. */
+  rr?: string;
+}>;
+
+/** `SampleSpec.from` (SDK 1.29.0): the source of a resampled file. */
+export type SampleProvenanceSpec = Readonly<{
+  /** `track:<id>`, `orbit:<n>` or `master`. */
+  source: string;
+  section?: string;
+  bars?: readonly [number, number];
+  /** sha256 of the score the file was rendered from. */
+  score: string;
 }>;
 
 /** Result of `sampler()`; pass it as a track's `instrument`. */
@@ -1317,7 +1347,7 @@ export function sampler(
       throw new DawgSdkError(
         `sampler voice "${name}" must be a short identifier`,
       );
-    out[name] = sample(voices[name]!, name);
+    out[name] = sampleSpec(voices[name]!, name);
   }
   return Object.freeze({ kind: "sampler", voices: Object.freeze(out), mode });
 }
@@ -1433,6 +1463,551 @@ export function wavetable(
   return Object.freeze(out) as WavetableSpec;
 }
 
+/** Instrument name of the 0.6 string engine (`Track.string`). */
+export const STRING_INSTRUMENT = "string";
+
+/**
+ * String engine settings (SDK 1.21.0): a `preset` (`nylon`, `steel`,
+ * `electric`, `jangle`, `ebass`, `slap`, `upright`, `sitar`, `tanpura`,
+ * `harpsichord`, `lute`, `oud`, `setar`, `tar`, `santur`, `dulcimer`, `koto`,
+ * `harp`, `banjo`, `tres`, `requinto`; bowed since SDK 1.31.0: `violin`,
+ * `viola`, `cello`, `contrabass`, `fiddle`, `erhu`, `kamancheh`, `violins`,
+ * `violas`, `cellos`, `contrabasses`, `pizz`, `trem`) plus any parameter to
+ * override (`ring`, `bright`, `damp`, `pos`, `mute`, `buzz`, `body`, `sym`,
+ * bow: `exciter: "bow"`, `pressure`, `speed`, `attack`, `vib`, `vibmod`,
+ * `vibdelay`, `tremhz`, `sord`, `dyn`). dawg validates names and ranges;
+ * see **Strings** in DAWG.md.
+ */
+export type StringInput = Readonly<
+  { preset?: string } & Record<string, number | string | undefined>
+>;
+
+/** Result of `stringed()`; pass it as a track's `instrument`. */
+export type StringSpec = Readonly<{ kind: "string" } & StringInput>;
+
+/**
+ * A plucked or bowed string instrument (SDK 1.21.0; bowed and the object
+ * form 1.31.0): a preset and overrides.
+ *
+ * instrument: stringed("nylon")
+ * instrument: stringed("sitar", { buzz: 0.8, sym: 0.5 })
+ * instrument: stringed({ preset: "cello", vib: 6 })
+ */
+export function stringed(
+  preset: string | StringInput = "nylon",
+  params: Readonly<Record<string, number | string>> = {},
+): StringSpec {
+  if (isRecord(preset)) {
+    const { preset: name, ...rest } = preset as Record<string, unknown>;
+    return stringed(name === undefined ? "nylon" : (name as string), {
+      ...(rest as Record<string, number | string>),
+      ...params,
+    });
+  }
+  if (typeof preset !== "string" || preset.length === 0)
+    throw new DawgSdkError("stringed needs a preset name");
+  if (!isRecord(params))
+    throw new DawgSdkError("stringed params must be an object");
+  const out: Record<string, number | string> = { kind: "string", preset };
+  for (const [key, value] of Object.entries(params)) {
+    if (value === undefined || key === "kind" || key === "preset") continue;
+    out[key] =
+      typeof value === "string" ? value : finite(value, `string ${key}`);
+  }
+  return Object.freeze(out) as StringSpec;
+}
+
+/** Instrument name of the 0.6 granular engine (`Track.granular`). */
+export const GRANULAR_INSTRUMENT = "granular";
+
+/**
+ * Granular settings (SDK 1.23.0). `src` is a sample (`sample(...)` shape,
+ * pinned like a sampler voice) or a built-in synth render
+ * `"synth:<preset>[@note]"` (default `synth:pad`, nothing to download);
+ * `preset` is `cloud`, `hold`, `sparkle`, `swarm`, `stutter`, `microloop`,
+ * `backwards` or `dust`; every other key overrides one parameter (`grain`
+ * seconds, `overlap`, `scan`, `pos`, `begin`, `end`, `spray`, `jitter`,
+ * `pitch`, `detune`, `shimmer`, `shimint`, `spread`, `window`, `reverse`,
+ * `freeze`, `repeat`, `hold`, `drift`, `drate`, `attack`, `release`,
+ * `veltone`, `gain`, `seed`, `root`). dawg validates names and ranges; see
+ * **Granular** in DAWG.md.
+ */
+export type GranularInput = Readonly<
+  {
+    src?: string | SampleSpec;
+    preset?: string;
+  } & Record<string, number | string | boolean | SampleSpec | undefined>
+>;
+
+/** Result of `granular()`; pass it as a track's `instrument`. */
+export type GranularSpec = Readonly<{ kind: "granular" } & GranularInput>;
+
+/**
+ * A granular instrument (SDK 1.23.0): an optional preset, then overrides.
+ *
+ * ```ts
+ * instrument: granular("cloud")
+ * instrument: granular("hold", { src: "samples/choir.wav", scan: 0 })
+ * instrument: granular({ src: "synth:bell@72", grain: 0.08, overlap: 6 })
+ * ```
+ */
+export function granular(
+  preset?: string | GranularInput,
+  params: GranularInput = {},
+): GranularSpec {
+  const fields =
+    typeof preset === "object" && preset !== null ? preset : params;
+  if (!isRecord(fields))
+    throw new DawgSdkError("granular params must be an object");
+  const out: Record<string, unknown> = { kind: "granular" };
+  if (typeof preset === "string") {
+    if (preset.length === 0)
+      throw new DawgSdkError("granular needs a preset name");
+    out.preset = preset;
+  } else if (preset !== undefined && (typeof preset !== "object" || !preset))
+    throw new DawgSdkError("granular takes a preset name or params");
+  for (const [key, value] of Object.entries(fields)) {
+    if (value === undefined || key === "kind") continue;
+    if (key === "src")
+      out.src =
+        typeof value === "string" && value.startsWith("synth:")
+          ? value
+          : sampleSpec(value as string | SampleSpec, "granular src");
+    else if (key === "preset" && typeof preset === "string") continue;
+    else if (key === "root" && typeof value === "string")
+      out.root = midi(value as Pitch);
+    else if (
+      typeof value === "number" ||
+      typeof value === "string" ||
+      typeof value === "boolean"
+    )
+      out[key] =
+        typeof value === "number" ? finite(value, `granular ${key}`) : value;
+    else throw new DawgSdkError(`granular ${key} must be a value`);
+  }
+  return Object.freeze(out) as GranularSpec;
+}
+
+/** Instrument name that selects the modal mallet-and-bell engine (SDK 1.25.0). */
+export const MODAL_INSTRUMENT = "modal";
+
+/** Modal presets (dawg's core/resonators.ts). */
+export type ModalPresetName =
+  | "marimba"
+  | "vibes"
+  | "xylophone"
+  | "glock"
+  | "celesta"
+  | "chimes"
+  | "kalimba"
+  | "mbira"
+  | "steelpan"
+  | "bowl"
+  | "gong"
+  | "timpani"
+  // SDK 1.30.0: gamelan, small bells and frame drums.
+  | "crotales"
+  | "musicbox"
+  | "toypiano"
+  | "saron"
+  | "demung"
+  | "slenthem"
+  | "gangsa"
+  | "gender"
+  | "bonang"
+  | "kenong"
+  | "kethuk"
+  | "kempul"
+  | "daf"
+  | "bodhran"
+  | "tabla";
+
+/** Modal overrides; omitted means the preset's value. dawg validates ranges. */
+export type ModalParams = Readonly<{
+  /** `yarn` `cord` `rubber` `plastic` `brass`: sets hardness. */
+  mallet?: "yarn" | "cord" | "rubber" | "plastic" | "brass";
+  /** Mallet hardness 0..1: brighter, shorter contact. */
+  hardness?: number;
+  /** Strike position 0..1 (0.5 is the bar's centre). */
+  position?: number;
+  /** Fundamental ring time (T60 seconds). */
+  ring?: number;
+  /** How much faster upper modes die (octaves of decay per octave). */
+  tilt?: number;
+  /** Damping on note-off 0..1 (0 lets the bar ring). */
+  damp?: number;
+  /** Choke time after note-off, seconds. */
+  release?: number;
+  /** Vibraphone motor rate Hz and depth 0..1. */
+  motor?: number;
+  motordepth?: number;
+  /** Beat between paired gamelan modes, Hz. */
+  ombak?: number;
+  /** Mbira buzz 0..1 and mallet click 0..1. */
+  buzz?: number;
+  click?: number;
+  /** Strike pitch bend in semitones and its decay seconds (Strudel penv/pdecay). */
+  strikebend?: number;
+  strikedecay?: number;
+  /** Output level 0..2 (1 is the preset level). */
+  gain?: number;
+  /** Mode table override (`marimba`, `bell`, `gong`, …). */
+  body?: string;
+  /**
+   * The partner track id of an ombak pair (SDK 1.30.0): this track (the
+   * pengisep) sounds `ombak` Hz above it. song() sets the partner's ombak
+   * to 0 (one straight voice) unless the partner gives its own.
+   */
+  pair?: string;
+}>;
+
+const MODAL_KEYS = Object.freeze([
+  "mallet",
+  "hardness",
+  "position",
+  "ring",
+  "tilt",
+  "damp",
+  "release",
+  "motor",
+  "motordepth",
+  "ombak",
+  "buzz",
+  "click",
+  "strikebend",
+  "strikedecay",
+  "gain",
+  "body",
+] as const);
+
+/** Mallet words (core/resonators.ts MODAL_MALLETS). */
+const MODAL_MALLET_WORDS: readonly string[] = Object.freeze([
+  "yarn",
+  "cord",
+  "rubber",
+  "plastic",
+  "brass",
+]);
+
+/** Mode tables a `body` override may name (core/resonators.ts MODAL_BODIES). */
+const MODAL_BODY_WORDS: readonly string[] = Object.freeze([
+  "marimba",
+  "vibraphone",
+  "xylophone",
+  "glockenspiel",
+  "celesta",
+  "chimes",
+  "crotale",
+  "mbira",
+  "kalimba",
+  "musicbox",
+  "toypiano",
+  "saron",
+  "bonang",
+  "gender",
+  "kempul",
+  "gong",
+  "bell",
+  "steelpan",
+  "bowl",
+  "timpani",
+  "tabla",
+  "frame",
+]);
+
+/** Numeric ranges (core/resonators.ts MODAL_PARAMS min..max). */
+const MODAL_RANGES: Readonly<Record<string, readonly [number, number]>> =
+  Object.freeze({
+    hardness: [0, 1],
+    position: [0, 1],
+    ring: [0.05, 30],
+    tilt: [0, 2],
+    damp: [0, 1],
+    release: [0.005, 2],
+    motor: [0, 12],
+    motordepth: [0, 1],
+    ombak: [0, 12],
+    buzz: [0, 1],
+    click: [0, 1],
+    strikebend: [-24, 24],
+    strikedecay: [0.001, 2],
+    gain: [0, 2],
+  });
+
+/** Modal presets whose default carries an ombak twin bank (core/resonators.ts). */
+const MODAL_TWIN_PRESETS: readonly string[] = Object.freeze(["gangsa"]);
+
+const MODAL_PRESET_WORDS: readonly string[] = Object.freeze([
+  "marimba",
+  "vibes",
+  "xylophone",
+  "glock",
+  "celesta",
+  "chimes",
+  "kalimba",
+  "mbira",
+  "steelpan",
+  "bowl",
+  "gong",
+  "timpani",
+  "crotales",
+  "musicbox",
+  "toypiano",
+  "saron",
+  "demung",
+  "slenthem",
+  "gangsa",
+  "gender",
+  "bonang",
+  "kenong",
+  "kethuk",
+  "kempul",
+  "daf",
+  "bodhran",
+  "tabla",
+]);
+
+/** Result of `modal()`; pass it as a track's `instrument`. */
+export type ModalSpec = Readonly<
+  { kind: "modal"; preset?: ModalPresetName } & ModalParams
+>;
+
+/**
+ * Mallets and bells on the modal engine (SDK 1.25.0): a preset and
+ * optional overrides. A preset word alone (`instrument: "vibes"`) is the
+ * same as `modal("vibes")`, except `"marimba"`, which stays the legacy
+ * marimba voice; `modal("marimba")` is the modal one.
+ *
+ * ```ts
+ * instrument: modal("vibes", { motor: 4, hardness: 0.6 })
+ * instrument: modal("marimba", { mallet: "rubber" })
+ * instrument: modal({ ring: 2 }) // default preset (marimba)
+ * ```
+ */
+export function modal(
+  preset?: ModalPresetName | ModalParams,
+  params: ModalParams = {},
+): ModalSpec {
+  const overrides = isRecord(preset) ? preset : params;
+  const name = isRecord(preset) ? undefined : preset;
+  if (!isRecord(overrides))
+    throw new DawgSdkError("modal params must be an object");
+  const out: Record<string, unknown> = { kind: "modal" };
+  if (name !== undefined) {
+    if (typeof name !== "string" || !MODAL_PRESET_WORDS.includes(name))
+      throw new DawgSdkError(
+        `modal preset "${String(name).slice(0, 32)}" is not one of ${MODAL_PRESET_WORDS.join(" ")}`,
+      );
+    out.preset = name;
+  }
+  for (const key of Object.keys(overrides)) {
+    const value = (overrides as Record<string, unknown>)[key];
+    if (value === undefined) continue;
+    if (key === "mallet" || key === "body") {
+      const words = key === "mallet" ? MODAL_MALLET_WORDS : MODAL_BODY_WORDS;
+      if (typeof value !== "string" || !words.includes(value))
+        throw new DawgSdkError(
+          `modal ${key} "${String(value).slice(0, 32)}" is not one of ${words.join(" ")}`,
+        );
+      out[key] = value;
+    } else if (key === "pair") {
+      if (typeof value !== "string" || !/^[A-Za-z0-9_-]{1,64}$/.test(value))
+        throw new DawgSdkError("modal pair must be a track id");
+      out.pair = value;
+    } else if ((MODAL_KEYS as readonly string[]).includes(key)) {
+      const number = finite(value, `modal ${key}`);
+      const [min, max] = MODAL_RANGES[key]!;
+      if (number < min || number > max)
+        throw new DawgSdkError(`modal ${key} must be ${min}..${max}`);
+      out[key] = number;
+    } else
+      throw new DawgSdkError(
+        `modal has no parameter "${key.slice(0, 32)}" (${MODAL_KEYS.join(" ")} pair)`,
+      );
+  }
+  return Object.freeze(out) as ModalSpec;
+}
+
+// ---- winds (f061-gamelan-winds, SDK 1.30.0) ----
+
+/** The instrument value of the wind engine (core/winds.ts). */
+export const WIND_INSTRUMENT = "wind";
+
+/** Wind presets (core/winds.ts WIND_PRESET_NAMES). */
+export type WindPresetName =
+  | "flute"
+  | "recorder"
+  | "whistle"
+  | "ney"
+  | "shakuhachi"
+  | "panpipe"
+  | "suling"
+  | "bansuri"
+  | "clarinet"
+  | "bassclarinet"
+  | "oboe"
+  | "bassoon"
+  | "sax"
+  | "altosax"
+  | "barisax"
+  | "trumpet"
+  | "harmon"
+  | "plunger"
+  | "trombone"
+  | "tuba"
+  | "horn";
+
+const WIND_PRESET_WORDS: readonly string[] = Object.freeze([
+  "flute",
+  "recorder",
+  "whistle",
+  "ney",
+  "shakuhachi",
+  "panpipe",
+  "suling",
+  "bansuri",
+  "clarinet",
+  "bassclarinet",
+  "oboe",
+  "bassoon",
+  "sax",
+  "altosax",
+  "barisax",
+  "trumpet",
+  "harmon",
+  "plunger",
+  "trombone",
+  "tuba",
+  "horn",
+]);
+
+/** Wind overrides (core/winds.ts WIND_PARAMS). */
+export type WindParams = Readonly<{
+  model?: "jet" | "reed" | "sax" | "lips";
+  breath?: number;
+  noise?: number;
+  attack?: number;
+  release?: number;
+  vib?: number;
+  vibmod?: number;
+  reed?: number;
+  bright?: number;
+  stopped?: boolean;
+  mute?: "open" | "straight" | "cup" | "harmon" | "plunger";
+  wah?: number;
+  wahenv?: number;
+  growl?: number;
+  flutter?: number;
+  players?: number;
+  gain?: number;
+}>;
+
+/** Enum words per wind parameter (core/winds.ts WIND_PARAMS). */
+const WIND_ENUMS: Readonly<Record<string, readonly string[]>> = Object.freeze({
+  model: Object.freeze(["jet", "reed", "sax", "lips"]),
+  mute: Object.freeze(["open", "straight", "cup", "harmon", "plunger"]),
+});
+
+/** Numeric ranges (core/winds.ts WIND_PARAMS min..max). */
+const WIND_RANGES: Readonly<Record<string, readonly [number, number]>> =
+  Object.freeze({
+    breath: [0, 1],
+    noise: [0, 1],
+    attack: [0.001, 2],
+    release: [0.005, 2],
+    vib: [0, 12],
+    vibmod: [0, 1],
+    reed: [0, 1],
+    bright: [0, 1],
+    wah: [0, 1],
+    wahenv: [0, 1],
+    growl: [0, 1],
+    flutter: [0, 1],
+    players: [1, 8],
+    gain: [0, 2],
+  });
+
+/** Result of `wind()`; pass it as a track's `instrument`. */
+export type WindSpec = Readonly<
+  { kind: "wind"; preset?: WindPresetName } & WindParams
+>;
+
+/**
+ * Winds and brass on the wind engine (SDK 1.30.0): a preset and optional
+ * overrides. A preset word alone (`instrument: "flute"`) is the same as
+ * `wind("flute")`; the bare word `"wind"` stays the legacy wind tone.
+ *
+ * ```ts
+ * instrument: wind("sax", { breath: 0.8, growl: 0.2 })
+ * instrument: wind("trumpet", { mute: "harmon", players: 3 })
+ * instrument: wind({ bright: 0.3 }) // default preset (flute)
+ * ```
+ */
+export function wind(
+  preset?: WindPresetName | WindParams,
+  params: WindParams = {},
+): WindSpec {
+  const overrides = isRecord(preset) ? preset : params;
+  const name = isRecord(preset) ? undefined : preset;
+  if (!isRecord(overrides))
+    throw new DawgSdkError("wind params must be an object");
+  const out: Record<string, unknown> = { kind: "wind" };
+  if (name !== undefined) {
+    if (typeof name !== "string" || !WIND_PRESET_WORDS.includes(name))
+      throw new DawgSdkError(
+        `wind preset "${String(name).slice(0, 32)}" is not one of ${WIND_PRESET_WORDS.join(" ")}`,
+      );
+    out.preset = name;
+  }
+  for (const key of Object.keys(overrides)) {
+    const value = (overrides as Record<string, unknown>)[key];
+    if (value === undefined) continue;
+    const words = WIND_ENUMS[key];
+    if (words) {
+      if (typeof value !== "string" || !words.includes(value))
+        throw new DawgSdkError(
+          `wind ${key} "${String(value).slice(0, 32)}" is not one of ${words.join(" ")}`,
+        );
+      out[key] = value;
+    } else if (key === "stopped") {
+      if (typeof value !== "boolean")
+        throw new DawgSdkError("wind stopped must be true or false");
+      out.stopped = value;
+    } else if (WIND_RANGES[key]) {
+      const number = finite(value, `wind ${key}`);
+      const [min, max] = WIND_RANGES[key]!;
+      if (number < min || number > max)
+        throw new DawgSdkError(`wind ${key} must be ${min}..${max}`);
+      if (key === "players" && !Number.isInteger(number))
+        throw new DawgSdkError("wind players must be a whole number");
+      out[key] = number;
+    } else
+      throw new DawgSdkError(
+        `wind has no parameter "${key.slice(0, 32)}" (${[...Object.keys(WIND_ENUMS), "stopped", ...Object.keys(WIND_RANGES)].join(" ")})`,
+      );
+  }
+  return Object.freeze(out) as WindSpec;
+}
+
+/**
+ * The wind field an instrument makes: `wind(...)`, or a wind preset word
+ * (`"flute"`, `"saxophone"`). The bare word `"wind"` keeps its pre-0.6.1
+ * meaning (the legacy tone) and makes none.
+ */
+function trackWind(
+  raw: unknown,
+): Readonly<{ preset?: WindPresetName } & WindParams> | undefined {
+  if (isRecord(raw) && raw.kind === "wind") {
+    const { kind: _kind, ...fields } = raw as WindSpec;
+    return Object.freeze(fields);
+  }
+  if (typeof raw !== "string" || raw === WIND_INSTRUMENT) return undefined;
+  const meaning = resolveInstrumentWord(raw);
+  if (meaning?.instrument !== WIND_INSTRUMENT || !meaning.preset)
+    return undefined;
+  return Object.freeze({ preset: meaning.preset as WindPresetName });
+}
+
 /**
  * `count` equal slices of one file as voices `prefix0 … prefixN-1`, for
  * chopped breaks: `sampler(slices("samples/break.wav", 8, "brk"))`, then
@@ -1445,7 +2020,7 @@ export function slices(
 ): Record<string, SampleSpec> {
   if (!Number.isInteger(count) || count < 1 || count > 64)
     throw new DawgSdkError("slices count must be an integer 1..64");
-  const base = sample(src, prefix);
+  const base = sampleSpec(src, prefix);
   const begin = base.begin ?? 0;
   const end = base.end ?? 1;
   const span = (end - begin) / count;
@@ -1460,7 +2035,7 @@ export function slices(
   return voices;
 }
 
-function sample(value: string | SampleSpec, name: string): SampleSpec {
+function sampleSpec(value: string | SampleSpec, name: string): SampleSpec {
   const spec = typeof value === "string" ? { src: value } : value;
   if (!isRecord(spec) || typeof spec.src !== "string" || spec.src.length === 0)
     throw new DawgSdkError(`sampler voice ${name} needs a src path`);
@@ -1483,6 +2058,16 @@ function sample(value: string | SampleSpec, name: string): SampleSpec {
     fit?: boolean;
     accelerate?: number;
     squiz?: number;
+    bpm?: number;
+    fitmode?: "repitch" | "beats" | "tones";
+    len?: number;
+    shift?: number;
+    formant?: number;
+    fadeTime?: number;
+    fadeInTime?: number;
+    from?: SampleProvenanceSpec;
+    vel?: readonly [number, number];
+    rr?: string;
   } = { src: spec.src };
   if (spec.src.startsWith("pack:")) {
     if (spec.sha256 !== undefined)
@@ -1532,9 +2117,57 @@ function sample(value: string | SampleSpec, name: string): SampleSpec {
   if (spec.accelerate !== undefined)
     out.accelerate = finite(spec.accelerate, `${name} accelerate`);
   if (spec.squiz !== undefined) out.squiz = finite(spec.squiz, `${name} squiz`);
+  if (spec.bpm !== undefined) out.bpm = finite(spec.bpm, `${name} bpm`);
+  if (spec.fitmode !== undefined) {
+    if (
+      spec.fitmode !== "repitch" &&
+      spec.fitmode !== "beats" &&
+      spec.fitmode !== "tones"
+    )
+      throw new DawgSdkError(
+        `${name} fitmode must be "repitch", "beats" or "tones"`,
+      );
+    out.fitmode = spec.fitmode;
+  }
+  if (spec.len !== undefined) out.len = finite(spec.len, `${name} len`);
+  if (spec.shift !== undefined) out.shift = finite(spec.shift, `${name} shift`);
+  if (spec.formant !== undefined)
+    out.formant = finite(spec.formant, `${name} formant`);
+  if (spec.fadeTime !== undefined)
+    out.fadeTime = finite(spec.fadeTime, `${name} fadeTime`);
+  if (spec.fadeInTime !== undefined)
+    out.fadeInTime = finite(spec.fadeInTime, `${name} fadeInTime`);
+  if (spec.from !== undefined) {
+    if (typeof spec.from !== "object" || spec.from === null)
+      throw new DawgSdkError(`${name} from must be an object`);
+    out.from = spec.from;
+  }
+  if (spec.vel !== undefined) {
+    if (!Array.isArray(spec.vel) || spec.vel.length !== 2)
+      throw new DawgSdkError(`${name} vel must be [lo, hi]`);
+    out.vel = Object.freeze([
+      finite(spec.vel[0], `${name} vel`),
+      finite(spec.vel[1], `${name} vel`),
+    ] as const);
+  }
+  if (spec.rr !== undefined) out.rr = text(spec.rr, `${name} rr`);
   return Object.freeze(out);
 }
 
+/**
+ * One sample file with options (SDK 1.20.0), for `sampler({ brk: ... })`:
+ * `sample("samples/break.wav", { bpm: 174, fitmode: "beats" })` plays a
+ * 174 BPM break in time with the song, cut at its hits.
+ */
+export function sample(
+  src: string,
+  options: Omit<SampleSpec, "src"> = {},
+): SampleSpec {
+  if (typeof src !== "string" || src.length === 0)
+    throw new DawgSdkError("sample() needs a src path");
+  return Object.freeze({ ...options, src });
+}
+
 // ---------------------------------------------------------------------------
 // Tracks
 
@@ -1564,14 +2197,248 @@ export type AutomationInput = Readonly<{
   wt?: readonly Point[];
 }>;
 
+/**
+ * Every rig preset (SDK 1.22.0), kept equal to `RIG_PRESETS` in
+ * core/fx.ts by `print-rig.test.ts`: the stomp, head and cab stages plus
+ * the companion effects a few rigs need (funk's and wah's autofilter,
+ * bachata's chorus, jangle's compressor). `spring`'s short room is the
+ * track's `reverb`, not `fx`: give it as
+ * `reverb: { mix: 0.3, size: 0.35, fade: 1.5, predelay: 0, dim: 3500 }`.
+ */
+export const RIG_PRESETS: Readonly<
+  Record<
+    string,
+    Readonly<
+      Record<"stomp" | "head" | "cab", EffectParams | undefined> &
+        Readonly<Record<string, EffectParams | undefined>>
+    >
+  >
+> = Object.freeze({
+  clean: {
+    stomp: undefined,
+    head: { type: "clean", gain: 3, treble: 6 },
+    cab: { type: "1x12" },
+  },
+  crunch: {
+    stomp: undefined,
+    head: { type: "crunch", gain: 5 },
+    cab: { type: "4x12" },
+  },
+  punk: {
+    stomp: undefined,
+    head: { type: "crunch", gain: 7, mid: 6, master: 6 },
+    cab: { type: "4x12", mic: 0.2 },
+  },
+  ragged: {
+    stomp: { type: "face", gain: 6, tone: 0.6 },
+    head: { type: "chime", gain: 4 },
+    cab: { type: "2x12" },
+  },
+  lead: {
+    stomp: { type: "od", gain: 3, tone: 0.5, level: 3 },
+    head: { type: "lead", gain: 6, mid: 6 },
+    cab: { type: "4x12" },
+  },
+  metal: {
+    stomp: { type: "od", gain: 0, tone: 0.6, level: 6 },
+    head: { type: "high", gain: 7, bass: 6, mid: 3, treble: 7, gate: -55 },
+    cab: { type: "4x12", mic: 0.2 },
+  },
+  fuzz: {
+    stomp: { type: "fuzz", gain: 7, tone: 0.5 },
+    head: { type: "clean", gain: 4 },
+    cab: { type: "2x12" },
+  },
+  octave: {
+    stomp: { type: "octave", gain: 6, tone: 0.6, octave: 0.8 },
+    head: { type: "clean", gain: 3 },
+    cab: { type: "1x12" },
+  },
+  funk: {
+    stomp: undefined,
+    head: { type: "clean", gain: 2, treble: 7, presence: 6 },
+    cab: { type: "2x12" },
+    autofilter: {
+      type: "bpf",
+      sync: 0,
+      rate: 0.01,
+      depth: 0,
+      follow: 3,
+      cutoff: 500,
+      resonance: 0.6,
+    },
+  },
+  wah: {
+    stomp: undefined,
+    head: { type: "crunch", gain: 4 },
+    cab: { type: "2x12" },
+    autofilter: {
+      type: "bpf",
+      sync: 0.5,
+      depth: 2,
+      shape: "sine",
+      cutoff: 700,
+      resonance: 0.6,
+    },
+  },
+  bachata: {
+    stomp: undefined,
+    head: { type: "clean", gain: 2, mid: 6, treble: 7 },
+    cab: { type: "1x12", mic: 0.2 },
+    chorus: { rate: 0.8, depth: 0.25, mix: 0.3 },
+  },
+  spring: {
+    stomp: undefined,
+    head: { type: "clean", gain: 3, treble: 6 },
+    cab: { type: "open" },
+  },
+  bassdrive: {
+    stomp: { type: "od", gain: 4, tone: 0.5, mix: 0.6 },
+    head: { type: "bass", gain: 4 },
+    cab: { type: "8x10" },
+  },
+  reese: {
+    stomp: { type: "rat", gain: 3, tone: 0.3, mix: 0.5 },
+    head: { type: "bass", gain: 6, master: 6 },
+    cab: { type: "1x15" },
+  },
+  jangle: {
+    stomp: undefined,
+    head: { type: "chime", gain: 3, treble: 7 },
+    cab: { type: "2x12", mic: 0.2 },
+    compressor: { threshold: -20, ratio: 4, attack: 0.01, release: 0.15 },
+    // The `rig jangle` command adds `double` since 0.6.1; rig("jangle")
+    // keeps its 0.6.0 stages so older song.ts files sound the same. Add
+    // `double: { time: 12, drift: 1.5, width: 0.5 }` for the new one.
+  },
+  alt: {
+    stomp: { type: "rat", gain: 6, tone: 0.4 },
+    head: { type: "crunch", gain: 4 },
+    cab: { type: "4x12" },
+  },
+  // SDK 1.27.0 shoegaze rigs. Their long wash is the track's `reverb`
+  // (see `rigReverb` in the `rig` command), not part of `rig()`.
+  shoegaze: {
+    stomp: { type: "fuzz", gain: 7, tone: 0.45 },
+    head: { type: "chime", gain: 4 },
+    cab: { type: "2x12" },
+    wobble: { depth: 25, rate: 0.4, drift: 0.4 },
+    bloom: { amount: 0.4, harm: 2, delay: 0.6, time: 1 },
+    double: { time: 18, drift: 2.5, width: 0.4 },
+    postgain: { gain: 0.86 },
+  },
+  glide: {
+    stomp: { type: "face", gain: 5, tone: 0.5 },
+    head: { type: "clean", gain: 4, treble: 5 },
+    cab: { type: "2x12" },
+    wobble: { depth: 35, rate: 0.4, drift: 0.4 },
+    postgain: { gain: 0.8 },
+  },
+  dreampop: {
+    stomp: undefined,
+    head: { type: "clean", gain: 2, treble: 6 },
+    cab: { type: "1x12" },
+    chorus: { rate: 0.6, depth: 0.3, mix: 0.35 },
+    double: { time: 14, drift: 2, width: 0.4 },
+    postgain: { gain: 1.45 },
+  },
+  swell: {
+    stomp: undefined,
+    head: { type: "clean", gain: 3, treble: 5 },
+    cab: { type: "1x12" },
+    swell: { time: 0.5 },
+    postgain: { gain: 1.25 },
+  },
+  ebow: {
+    stomp: { type: "od", gain: 3, tone: 0.5, level: 3 },
+    head: { type: "lead", gain: 5, mid: 6 },
+    cab: { type: "4x12" },
+    swell: { time: 0.25 },
+    bloom: { amount: 0.8, harm: 1, delay: 0.1, time: 0.6 },
+  },
+});
+
+/**
+ * The long wash a rig preset sets as the track's `reverb` (SDK 1.27.0),
+ * as the `rig` command stores it. `rig()` returns `fx` only, so give it
+ * as `reverb: rigReverb("shoegaze")`; `instrument: "shoegaze"` adds it
+ * when the track has no `reverb` of its own.
+ */
+const RIG_REVERBS: Readonly<Record<string, ReverbInput & { mix: number }>> =
+  Object.freeze({
+    spring: { mix: 0.3, size: 0.35, fade: 1.5, predelay: 0, dim: 3500 },
+    shoegaze: { mix: 0.35, size: 0.9, fade: 4, predelay: 0.02, dim: 6000 },
+    glide: { mix: 0.35, size: 0.7, fade: 2.5, predelay: 0.01, dim: 6000 },
+    dreampop: { mix: 0.4, size: 0.85, fade: 5, predelay: 0.03, dim: 7000 },
+    swell: { mix: 0.45, size: 0.8, fade: 4, predelay: 0.02, dim: 6500 },
+  });
+
+/** A rig preset's track reverb (`spring`, the shoegaze rigs), if any. */
+export function rigReverb(name: string): ReverbInput | undefined {
+  if (
+    typeof name !== "string" ||
+    !Object.prototype.hasOwnProperty.call(RIG_PRESETS, name)
+  )
+    throw new DawgSdkError(
+      `unknown rig "${String(name)}" (rigs: ${Object.keys(RIG_PRESETS).join(", ")})`,
+    );
+  const values = RIG_REVERBS[name];
+  return values === undefined ? undefined : Object.freeze({ ...values });
+}
+
+/**
+ * A guitar rig for a track's `fx` (SDK 1.22.0): the stomp → head → cab
+ * stages of rig preset `name` and its companion effects (as the `rig`
+ * command sets them), with optional per-stage overrides. Spread it
+ * into `fx` next to other effects:
+ *
+ * ```ts
+ * fx: { ...rig("crunch"), chorus: {} }
+ * fx: { ...rig("metal", { head: { gain: 9 } }) }
+ * ```
+ */
+export function rig(
+  name: string,
+  overrides: Readonly<
+    Partial<Record<"stomp" | "head" | "cab", EffectParams>>
+  > = {},
+): FxInput {
+  if (
+    typeof name !== "string" ||
+    !Object.prototype.hasOwnProperty.call(RIG_PRESETS, name)
+  )
+    throw new DawgSdkError(
+      `unknown rig "${String(name)}" (rigs: ${Object.keys(RIG_PRESETS).join(", ")})`,
+    );
+  if (!isRecord(overrides))
+    throw new DawgSdkError("rig overrides must be an object");
+  const out: Record<string, EffectParams> = {};
+  // Companion effects first, then the stages in chain order.
+  for (const [effect, values] of Object.entries(RIG_PRESETS[name]!))
+    if (values && effect !== "stomp" && effect !== "head" && effect !== "cab")
+      out[effect] = Object.freeze({ ...values });
+  for (const stage of ["stomp", "head", "cab"] as const) {
+    const base = RIG_PRESETS[name]![stage];
+    const extra = overrides[stage];
+    if (extra !== undefined && !isRecord(extra))
+      throw new DawgSdkError(`rig ${stage} overrides must be an object`);
+    if (base || extra)
+      out[stage] = Object.freeze({ ...(base ?? {}), ...(extra ?? {}) });
+  }
+  return Object.freeze(out);
+}
+
 /** 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,
+ * filter → djf → autofilter → vowel → crush → distort → stomp → head →
+ * cab → tremolo → compressor → pan → phaser → chorus → leslie → postgain →
+ * delay → reverb. The guitar rig (stomp, head, cab; SDK 1.22.0) is easiest
+ * as `...rig("crunch")`.
+ * Keys here: djf, autofilter, vowel, crush, distort, stomp, head, cab,
+ * 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
@@ -1585,6 +2452,106 @@ export type FxInput = Readonly<Record<string, EffectParams>>;
  * `"synth-<param>"` (e.g. `"synth-lpf"`), read at each note's onset.
  * Every parameter, range and default: **Synth** in DAWG.md.
  */
+/**
+ * Modelled keys settings (SDK 1.24.0), for a track whose instrument is a
+ * piano family (`"grand"`, `"upright"`, `"felt"`, `"honkytonk"`,
+ * `"prepared"`; the words `"ballad"` and `"lofi"` pick presets) or, from
+ * SDK 1.26.0, an electric family (`"epiano"`, `"wurli"`, `"clav"`; presets
+ * epiano suitcase dyno wurli clav funkclav). Every field is optional; `{}`
+ * is the family's own sound. Automate a parameter with
+ * `automation.fx["keys-<param>"]` (hardness, touch, decay, release, knock,
+ * noise, felt; electric tone, vibe, trem), read at each note's onset.
+ * Ranges: **Keys** in DAWG.md.
+ */
+export type KeysInput = Readonly<{
+  /**
+   * A named preset: grand ballad upright felt lofi honkytonk prepared, or
+   * electric epiano suitcase dyno wurli clav funkclav.
+   */
+  preset?: string;
+  /** Hammer hardness 0..1: brightness at a given velocity (0.5). */
+  hardness?: number;
+  /** Velocity sensitivity 0..1 (1). */
+  touch?: number;
+  /** Inharmonicity multiplier 0..4 (1 grand, 2.5 upright, 0 harmonic). */
+  inharm?: number;
+  /** Unison detune in cents 0..30 (0.7; honkytonk 16). */
+  unison?: number;
+  /** Sustain time multiplier 0.1..4 (1). */
+  decay?: number;
+  /** Damper time multiplier 0.1..4 (1). */
+  release?: number;
+  /** Hammer position along the string 0.04..0.3 (0.12). */
+  strike?: number;
+  /** Aftersound share 0..1 (0.3). */
+  after?: number;
+  /** Soundboard knock 0..1 (0.5). */
+  knock?: number;
+  /** Key and damper mechanics 0..1 (0.25). */
+  noise?: number;
+  /** Felt strip 0..1 (0; felt family 1). */
+  felt?: number;
+  /** Share of prepared keys 0..1 (0; prepared family 0.6). */
+  prep?: number;
+  /** Keyboard stereo width 0..1 (0.6). */
+  width?: number;
+  /** Octave stretch 0..1 (1); 0 keeps every key exactly on its tuning. */
+  stretch?: number;
+  /** Body EQ: grand upright felt honkytonk prepared (the family's own). */
+  body?: string;
+  /** Pitch wobble rate in Hz (tape wow), 0 off. */
+  vib?: number;
+  /** Pitch wobble depth in semitones (0.5). */
+  vibmod?: number;
+  // keys-electric (SDK 1.26.0)
+  /** Sympathetic string resonance 0..1 under the sustain pedal (0; pianos). */
+  sym?: number;
+  /** Pickup drive 0..1: growl when played hard (0.35; epiano, wurli). */
+  bark?: number;
+  /** Tine or reed bell ping 0..1 (0.5; epiano, wurli). */
+  bell?: number;
+  /** Output low-pass in Hz, 0 off (electric keys). */
+  tone?: number;
+  /** Clav pickup switch: neck bridge both out ("both"). */
+  pickup?: "neck" | "bridge" | "both" | "out";
+  /** Clav mute slider 0..1 (0). */
+  mute?: number;
+  /** Suitcase stereo vibrato depth 0..1 (0; epiano). */
+  vibe?: number;
+  /** Suitcase vibrato rate in Hz 0.5..12 (4; epiano). */
+  vibehz?: number;
+  // Organs (SDK 1.28.0), for instrument `"tonewheel"`, `"combo"` or
+  // `"pipe"` (presets tonewheel gospel jazzorgan combo vox pipe flutes
+  // cornet reeds celeste). `"organ"` stays the legacy sine voice.
+  /** Tonewheel drawbars, nine digits 0-8, 16' to 1' (`"888000000"`). */
+  drawbars?: string;
+  /** Tonewheel percussion: off 2nd 3rd. */
+  perc?: string;
+  /** Percussion decay: fast slow. */
+  percdecay?: string;
+  /** Key click 0..1. */
+  click?: number;
+  /** Scanner vibrato/chorus: off v1 v2 v3 c1 c2 c3. */
+  scanner?: string;
+  /** Preamp drive 0..1 (lane `keys-drive`). */
+  drive?: number;
+  /** Rotary speaker: slow fast stop (lane `keys-rotary`). */
+  rotary?: string;
+  /** Combo registers, five digits 0-8, 16' 8' 4' 2⅔' 2' (`"08800"`). */
+  registers?: string;
+  /**
+   * Pipe stops: names or a registration (plenum flutes cornet reeds strings
+   * full), as one string or a list (`["principal8", "octave4"]`).
+   */
+  stops?: string | readonly string[];
+  /** Pipe chiff 0..1. */
+  chiff?: number;
+  /** Pipe wind unsteadiness 0..1. */
+  wind?: number;
+  /** Tremolo depth 0..1: reed piano (0; wurli), pipe tremulant (0; pipe). */
+  trem?: number;
+}>;
+
 export type SynthInput = Readonly<{
   attack?: number;
   decay?: number;
@@ -1668,9 +2635,27 @@ export type TrackInput = Readonly<{
    * `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`.
+   * `sampler(...)` or `wavetable(...)`, or a mallet or bell (`vibes`,
+   * `glock`, `gong`, … or `modal(...)`, SDK 1.25.0). Default `sine`.
    */
-  instrument?: string | SamplerSpec | WavetableSpec;
+  instrument?:
+    | string
+    | SamplerSpec
+    | WavetableSpec
+    | StringSpec
+    | GranularSpec
+    | ModalSpec
+    | WindSpec;
+  /**
+   * The sampler a `granular(...)` track keeps while it grains one of its
+   * voices (SDK 1.23.0); `grain off` plays it again.
+   */
+  sampler?: SamplerSpec | null;
+  /**
+   * Granular engine (SDK 1.23.0) for an `instrument: "granular"` track, or
+   * use `instrument: granular("cloud", {...})` or a word (`"cloud"`).
+   */
+  granular?: GranularInput | null;
   /**
    * Synthesized drum kit for an `instrument: "kit"` track: `syn808`,
    * `syn909`, `acoustic`, `lofi`, `electro` or `trap`. Omit for the default
@@ -1694,6 +2679,17 @@ export type TrackInput = Readonly<{
   tuning?: TuningInput | null;
   /** Synth voice parameters, Strudel names (`{ attack: 0.01, lpf: 800 }`). */
   synth?: SynthInput;
+  /**
+   * String engine (SDK 1.21.0) for an `instrument: "string"` track, or use
+   * `instrument: stringed("sitar", {...})` or a preset word (`"nylon"`).
+   */
+  string?: StringInput | null;
+  /**
+   * Modelled piano settings (SDK 1.24.0) for `instrument: "grand"` and the
+   * other piano families; `{}` is the family's sound. The word `"piano"`
+   * keeps the classic 0.4 tone; use `"grand"` for the modelled piano.
+   */
+  keys?: KeysInput;
   muted?: boolean;
   /** When any track is soloed only soloed tracks play. */
   solo?: boolean;
@@ -1720,6 +2716,16 @@ export type TrackInput = Readonly<{
   glide?: number | Readonly<{ time?: number; mode?: GlideMode }>;
   /** Sustain pedal changes as `[beat, "down" | "half" | "up"]` (SDK 1.15.0). */
   pedal?: readonly (readonly [number, PedalState])[];
+  /**
+   * Una corda on a modelled piano (SDK 1.26.0): `[beat, "down" | "half" |
+   * "up"]`; while down each note strikes fewer strings, softer and darker.
+   */
+  softPedal?: readonly (readonly [number, PedalState])[];
+  /**
+   * Sostenuto on a modelled piano (SDK 1.26.0): `[beat, "down" | "up"]`;
+   * holds only the keys already down when it presses.
+   */
+  sostenuto?: readonly (readonly [number, "down" | "up"])[];
   /**
    * Velocity response (SDK 1.15.0): `soft` (quiet notes louder), `hard`
    * (needs a firm touch), `fixed` (every note at 0.8, like an organ) or
@@ -1738,6 +2744,12 @@ export type TrackInput = Readonly<{
     length?: number;
     seed?: number;
   }>;
+  /**
+   * How chords are fretted on this track (SDK 1.27.0): `{ tune: "dadgad",
+   * capo: 2 }`. dawg's `strum` command and perform mode `guitar` use it;
+   * it changes no sound by itself.
+   */
+  guitar?: GuitarInput;
   /** `note()`/`seq()` for pitched tracks, `hit()`/`hits()` for kits and one-shot samplers. */
   notes?: readonly (NoteSpec | HitSpec)[];
   /**
@@ -1833,6 +2845,10 @@ export type TrackSpec = Readonly<{
   synth: SynthInput | null;
   sampler: SamplerSpec | null;
   wavetable: WavetableSpec | null;
+  /** String engine settings (SDK 1.21.0); present only when set. */
+  string?: StringInput;
+  /** Granular engine settings (SDK 1.23.0); null when not granular. */
+  granular?: GranularInput | null;
   automation: Readonly<Required<AutomationInput>>;
   /** Every hit resolved to its pitch slot. */
   notes: readonly NoteSpec[];
@@ -1844,6 +2860,9 @@ export type TrackSpec = Readonly<{
   /** Performance (SDK 1.15.0); present only when set. */
   glide?: Readonly<{ time: number; mode: GlideMode }>;
   pedal?: readonly (readonly [number, PedalState])[];
+  /** Soft and sostenuto pedals (SDK 1.26.0); present only when set. */
+  softPedal?: readonly (readonly [number, PedalState])[];
+  sostenuto?: readonly (readonly [number, PedalState])[];
   velocityCurve?: Readonly<{
     curve: Exclude<VelocityCurveName, "linear">;
     fixed?: number;
@@ -1855,6 +2874,14 @@ export type TrackSpec = Readonly<{
     seed: number;
   }>;
   tuning: ScoreTuning | null;
+  /** Modelled piano settings (SDK 1.24.0); present only when set. */
+  keys?: KeysInput;
+  /** Modal settings (SDK 1.25.0); present only on a modal track. */
+  modal?: Readonly<{ preset?: ModalPresetName } & ModalParams>;
+  /** Guitar fretting (SDK 1.27.0); present only when set. */
+  guitar?: GuitarSetup;
+  /** Wind settings (SDK 1.30.0); present only on a wind-engine track. */
+  wind?: Readonly<{ preset?: WindPresetName } & WindParams>;
 }>;
 
 export type GlideMode = "legato" | "mono" | "poly";
@@ -1868,10 +2895,17 @@ const DEFAULT_FIXED_VELOCITY = 0.8;
 function trackPerformance(
   input: TrackInput,
   name: string,
-): Partial<Pick<TrackSpec, "glide" | "pedal" | "velocityCurve" | "humanize">> {
+): Partial<
+  Pick<
+    TrackSpec,
+    "glide" | "pedal" | "softPedal" | "sostenuto" | "velocityCurve" | "humanize"
+  >
+> {
   const out: {
     glide?: TrackSpec["glide"];
     pedal?: TrackSpec["pedal"];
+    softPedal?: TrackSpec["softPedal"];
+    sostenuto?: TrackSpec["sostenuto"];
     velocityCurve?: TrackSpec["velocityCurve"];
     humanize?: TrackSpec["humanize"];
   } = {};
@@ -1892,29 +2926,38 @@ function trackPerformance(
       mode,
     });
   }
-  if (input.pedal !== undefined) {
-    if (!Array.isArray(input.pedal) || input.pedal.length > 1024)
+  const pedalLane = (
+    key: "pedal" | "softPedal" | "sostenuto",
+    states: readonly PedalState[],
+  ) => {
+    const value: unknown = input[key];
+    if (value === undefined) return;
+    const shape = `[beat, ${states.map((state) => `"${state}"`).join(" | ")}]`;
+    if (!Array.isArray(value) || value.length > 1024)
       throw new DawgSdkError(
-        `track ${name}: pedal must be at most 1024 [beat, "down" | "half" | "up"] events`,
+        `track ${name}: ${key} must be at most 1024 ${shape} events`,
       );
-    if (input.pedal.length > 0)
-      out.pedal = Object.freeze(
-        input.pedal.map((event: unknown, index: number) => {
+    if (value.length > 0)
+      out[key] = Object.freeze(
+        value.map((event: unknown, index: number) => {
           if (
             !Array.isArray(event) ||
             event.length !== 2 ||
-            !["down", "half", "up"].includes(event[1] as string)
+            !states.includes(event[1] as PedalState)
           )
             throw new DawgSdkError(
-              `track ${name}: pedal[${index}] must be [beat, "down" | "half" | "up"]`,
+              `track ${name}: ${key}[${index}] must be ${shape}`,
             );
           return Object.freeze([
-            beat(event[0], `${name} pedal[${index}] beat`),
+            beat(event[0], `${name} ${key}[${index}] beat`),
             event[1] as PedalState,
           ] as const);
         }),
       );
-  }
+  };
+  pedalLane("pedal", ["down", "half", "up"]);
+  pedalLane("softPedal", ["down", "half", "up"]);
+  pedalLane("sostenuto", ["down", "up"]);
   if (input.velocityCurve !== undefined) {
     const raw =
       typeof input.velocityCurve === "string"
@@ -2056,34 +3099,81 @@ export function track(input: TrackInput): TrackSpec {
   if (typeof id !== "string" || id.length === 0 || id.length > 64)
     throw new DawgSdkError(`track ${name}: id must be 1..64 characters`);
   const rawInstrument = input.instrument ?? "sine";
+  // A granular track may keep the sampler it grains (`grain off` goes back).
+  const keptSampler =
+    isRecord(input.sampler) &&
+    input.sampler.kind === "sampler" &&
+    isRecord(rawInstrument) &&
+    rawInstrument.kind === "granular"
+      ? localizeSampler(input.sampler as SamplerSpec, slug)
+      : null;
+  if (input.sampler !== undefined && input.sampler !== null && !keptSampler)
+    throw new DawgSdkError(
+      `track ${name}: sampler: is only for a granular(...) track; use instrument: sampler({...})`,
+    );
   const samplerSpec =
     isRecord(rawInstrument) && rawInstrument.kind === "sampler"
       ? localizeSampler(rawInstrument as SamplerSpec, slug)
-      : null;
+      : keptSampler;
   const wavetableSpec =
     isRecord(rawInstrument) && rawInstrument.kind === "wavetable"
       ? localizeWavetable(rawInstrument as WavetableSpec, slug)
       : null;
-  const instrument = samplerSpec
-    ? SAMPLER_INSTRUMENT
-    : wavetableSpec
-      ? WAVETABLE_INSTRUMENT
-      : typeof rawInstrument === "string"
-        ? rawInstrument
-        : undefined;
+  const stringFromInstrument =
+    isRecord(rawInstrument) && rawInstrument.kind === "string"
+      ? stringInput(rawInstrument, name)
+      : null;
+  const granularFromInstrument =
+    isRecord(rawInstrument) && rawInstrument.kind === "granular"
+      ? granularInput(rawInstrument, name, slug)
+      : null;
+  const word =
+    typeof rawInstrument === "string"
+      ? resolveInstrumentWord(rawInstrument)
+      : undefined;
+  const modalSpec = trackModal(rawInstrument);
+  const guitarSpec = guitarInput(input.guitar, `track ${name}`);
+  const windSpec = trackWind(rawInstrument);
+  const instrument = granularFromInstrument
+    ? GRANULAR_INSTRUMENT
+    : samplerSpec
+      ? SAMPLER_INSTRUMENT
+      : wavetableSpec
+        ? WAVETABLE_INSTRUMENT
+        : stringFromInstrument
+          ? STRING_INSTRUMENT
+          : modalSpec
+            ? MODAL_INSTRUMENT
+            : windSpec
+              ? WIND_INSTRUMENT
+              : typeof rawInstrument === "string"
+                ? (word?.instrument ?? rawInstrument)
+                : undefined;
+  // A granular word (`"cloud"`) turns the engine on with its preset.
+  const granularSpec =
+    granularInput(input.granular, name, slug) ??
+    granularFromInstrument ??
+    (word?.field === "granular" && word.preset
+      ? Object.freeze({ preset: word.preset })
+      : instrument === GRANULAR_INSTRUMENT
+        ? Object.freeze({})
+        : null);
   if (
     instrument === undefined ||
     instrument.length === 0 ||
     instrument.length > 64
   )
     throw new DawgSdkError(
-      `track ${name}: instrument must be a voice name, "kit", sampler(...) or wavetable(...)`,
+      `track ${name}: instrument must be a voice name, "kit", sampler(...), wavetable(...), stringed(...), granular(...) or modal(...)`,
     );
   if (instrument === SAMPLER_INSTRUMENT && !samplerSpec)
     throw new DawgSdkError(
       `track ${name}: use instrument: sampler({...}) for a sampler track`,
     );
-  const slots = samplerSpec ? voiceSlots(samplerSpec) : undefined;
+  const slots =
+    samplerSpec && instrument === SAMPLER_INSTRUMENT
+      ? voiceSlots(samplerSpec)
+      : undefined;
   const kit = KIT_INSTRUMENTS.includes(instrument.trim().toLowerCase());
   const notes = (input.notes ?? []).map((item, index) => {
     if (!isRecord(item) || (item.kind !== "note" && item.kind !== "hit"))
@@ -2158,6 +3248,23 @@ export function track(input: TrackInput): TrackSpec {
       throw new DawgSdkError(
         `track ${name}: unknown automation lane "${key}" (${AUTOMATION_KEYS.join(" ")})`,
       );
+  // A keys preset word (`"lofi"`, `"ballad"`) brings its preset's effects,
+  // as the prompt does; explicit filter, fx and reverb win.
+  const presetFx = keysPresetFx(input.keys, rawInstrument);
+  if (presetFx) {
+    input = {
+      ...input,
+      ...(input.filter === undefined && presetFx.filter
+        ? { filter: presetFx.filter }
+        : {}),
+      ...(input.reverb === undefined && presetFx.reverb
+        ? { reverb: presetFx.reverb }
+        : {}),
+      ...(presetFx.fx && input.fx !== null
+        ? { fx: { ...presetFx.fx, ...(isRecord(input.fx) ? input.fx : {}) } }
+        : {}),
+    };
+  }
   const filter =
     input.filter === undefined || input.filter === null
       ? null
@@ -2185,6 +3292,13 @@ export function track(input: TrackInput): TrackSpec {
             `${name} delay`,
           ),
         });
+  // A rig alias with a wash (`instrument: "shoegaze"`) sets the track
+  // reverb the `track shoegaze` prompt sets, unless `reverb` is given.
+  if (input.reverb === undefined && typeof rawInstrument === "string") {
+    const rigName = resolveInstrumentWord(rawInstrument)?.fx;
+    const wash = rigName === undefined ? undefined : RIG_REVERBS[rigName];
+    if (wash) input = { ...input, reverb: wash };
+  }
   const reverb =
     input.reverb === undefined || input.reverb === null
       ? null
@@ -2200,8 +3314,26 @@ export function track(input: TrackInput): TrackSpec {
             ? {}
             : { ir: reverbIr(input.reverb.ir, name, slug) }),
         });
-  const fx = fxInput(input.fx, name);
+  // A guitar alias (`instrument: "jangle"`) also loads its rig; stages and
+  // effects the track's own `fx` names win.
+  const aliasRig =
+    typeof rawInstrument === "string"
+      ? resolveInstrumentWord(rawInstrument)?.fx
+      : undefined;
+  const fx = fxInput(
+    aliasRig === undefined
+      ? input.fx
+      : { ...rig(aliasRig), ...(isRecord(input.fx) ? input.fx : {}) },
+    name,
+  );
   const synth = synthInput(input.synth, name);
+  // A string preset word (`"nylon"`) turns the engine on with its preset.
+  const string =
+    stringInput(input.string, name) ??
+    stringFromInstrument ??
+    (word?.field === "string" && word.preset
+      ? Object.freeze({ preset: word.preset })
+      : null);
   return Object.freeze({
     kind: "track",
     id,
@@ -2219,6 +3351,8 @@ export function track(input: TrackInput): TrackSpec {
     synth,
     sampler: samplerSpec,
     wavetable: wavetableSpec,
+    ...(string ? { string } : {}),
+    ...(granularSpec ? { granular: granularSpec } : {}),
     automation: Object.freeze({
       volume: lane("volume"),
       pan: lane("pan"),
@@ -2235,9 +3369,115 @@ export function track(input: TrackInput): TrackSpec {
     ...trackTime(input.time, name),
     ...trackPerformance(input, name),
     tuning: tuningSpec(input.tuning, `track ${name}`),
+    ...keysSpec(input.keys, rawInstrument, name),
+    ...(modalSpec ? { modal: modalSpec } : {}),
+    ...(guitarSpec ? { guitar: guitarSpec } : {}),
+    ...(windSpec ? { wind: windSpec } : {}),
   });
 }
 
+/**
+ * Effects the keys presets set with the voice: a copy of `KEYS_PRESETS`
+ * filter, fx and reverb in core/keys.ts (core/keys.test.ts checks they
+ * match the prompt's `piano <preset>`).
+ */
+const KEYS_PRESET_FX: Readonly<
+  Record<
+    string,
+    Readonly<{
+      filter?: FilterInput;
+      fx?: FxInput;
+      reverb?: ReverbInput;
+    }>
+  >
+> = Object.freeze({
+  ballad: { reverb: { mix: 0.25, size: 0.7 } },
+  felt: { reverb: { mix: 0.2, size: 0.5 } },
+  lofi: {
+    filter: { cutoff: 3500, resonance: 0.1 },
+    fx: { crush: { bits: 10 } },
+  },
+  // f061-organ: the pipe presets sound in a church.
+  pipe: { reverb: { mix: 0.35, size: 0.9 } },
+  flutes: { reverb: { mix: 0.3, size: 0.8 } },
+  cornet: { reverb: { mix: 0.3, size: 0.8 } },
+  reeds: { reverb: { mix: 0.3, size: 0.85 } },
+  celeste: { reverb: { mix: 0.35, size: 0.9 } },
+});
+
+/**
+ * The preset effects an instrument word brings: a preset word that is not
+ * also its family (`"lofi"`, `"ballad"`), or any preset word without
+ * `keys` (`"felt"`). A printed track names its family and always prints
+ * `keys`, so print → eval never adds them twice.
+ */
+function keysPresetFx(
+  keys: unknown,
+  word: unknown,
+): (typeof KEYS_PRESET_FX)[string] | undefined {
+  if (typeof word !== "string") return undefined;
+  const meaning = resolveInstrumentWord(word);
+  if (meaning?.field !== "keys" || !meaning.preset) return undefined;
+  if (keys !== undefined && keys !== null && word === meaning.instrument)
+    return undefined;
+  return KEYS_PRESET_FX[meaning.preset];
+}
+
+/**
+ * `keys` for `track()`: the input as given, or `{ preset }` when the
+ * instrument word names a keys preset (`"grand"`, `"lofi"`), so the word
+ * alone plays the modelled piano. dawg validates the values.
+ */
+function keysSpec(
+  input: unknown,
+  word: unknown,
+  name: string,
+): { keys?: KeysInput } {
+  const meaning =
+    typeof word === "string" ? resolveInstrumentWord(word) : undefined;
+  const preset = meaning?.field === "keys" ? meaning.preset : undefined;
+  if (input === undefined || input === null)
+    return preset ? { keys: Object.freeze({ preset }) } : {};
+  if (!isRecord(input))
+    throw new DawgSdkError(`track ${name}: keys must be an object`);
+  const out: Record<string, EffectValue> = {};
+  // A preset word (`"lofi"`) keeps its preset under given overrides; a
+  // family word (`"upright"`) with `keys` is exactly the given keys.
+  if (preset && input.preset === undefined && word !== meaning?.instrument)
+    out.preset = preset;
+  for (const [key, value] of Object.entries(input)) {
+    if (value === undefined) continue;
+    // Pipe stops may be a list: stored as one space-separated string.
+    if (key === "stops" && Array.isArray(value)) {
+      if (!value.every((stop) => typeof stop === "string"))
+        throw new DawgSdkError(`track ${name}: keys.stops must be stop names`);
+      out[key] = value.join(" ");
+      continue;
+    }
+    out[key] = effectValue(value, `${name} keys.${key}`);
+  }
+  return { keys: Object.freeze(out) };
+}
+
+/**
+ * The modal field an instrument makes: `modal(...)`, or a modal preset
+ * word (`"vibes"`, `"glockenspiel"`). The bare words `"modal"` and
+ * `"marimba"` keep their pre-0.6 meaning and make none.
+ */
+function trackModal(
+  raw: unknown,
+): Readonly<{ preset?: ModalPresetName } & ModalParams> | undefined {
+  if (isRecord(raw) && raw.kind === "modal") {
+    const { kind: _kind, ...fields } = raw as ModalSpec;
+    return Object.freeze(fields);
+  }
+  if (typeof raw !== "string" || raw === MODAL_INSTRUMENT) return undefined;
+  const meaning = resolveInstrumentWord(raw);
+  if (meaning?.instrument !== MODAL_INSTRUMENT || !meaning.preset)
+    return undefined;
+  return Object.freeze({ preset: meaning.preset as ModalPresetName });
+}
+
 function trackTime(input: unknown, name: string): { time?: TrackTimeInput } {
   if (input === undefined || input === null) return {};
   if (!isRecord(input))
@@ -2348,6 +3588,21 @@ function fxInput(input: unknown, name: string): FxInput | null {
   return Object.keys(out).length > 0 ? Object.freeze(out) : null;
 }
 
+function stringInput(input: unknown, name: string): StringInput | null {
+  if (input === undefined || input === null) return null;
+  if (!isRecord(input))
+    throw new DawgSdkError(`track ${name}: string must be an object`);
+  const out: Record<string, number | string> = {};
+  for (const [key, value] of Object.entries(input)) {
+    if (value === undefined || key === "kind") continue;
+    out[key] =
+      typeof value === "string"
+        ? value
+        : finite(value, `${name} string.${key}`);
+  }
+  return Object.freeze(out);
+}
+
 function synthInput(input: unknown, name: string): SynthInput | null {
   if (input === undefined || input === null) return null;
   if (!isRecord(input))
@@ -2433,7 +3688,7 @@ function reverbIr(
     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`);
+    const ref = sampleSpec(spec as SampleSpec, `${name} reverb.ir`);
     return Object.freeze({
       src: ref.src,
       ...(ref.sha256 ? { sha256: ref.sha256 } : {}),
@@ -2445,6 +3700,41 @@ function reverbIr(
   return src.startsWith("tracks/") ? src : `tracks/${slug}/${src}`;
 }
 
+/** Validates `granular` input and localizes a sample source like a voice. */
+function granularInput(
+  input: unknown,
+  name: string,
+  slug: string,
+): GranularInput | null {
+  if (input === undefined || input === null) return null;
+  if (!isRecord(input))
+    throw new DawgSdkError(`track ${name}: granular must be an object`);
+  const out: Record<string, unknown> = {};
+  for (const [key, value] of Object.entries(input)) {
+    if (value === undefined || key === "kind") continue;
+    if (key === "src" && isRecord(value)) {
+      const ref = sampleSpec(value as SampleSpec, `${name} granular src`);
+      const src = ref.src.replace(/^\.\//, "");
+      out.src = Object.freeze({
+        ...ref,
+        src:
+          src.startsWith("tracks/") || src.startsWith("pack:")
+            ? src
+            : `tracks/${slug}/${src}`,
+      });
+    } else if (key === "src" && typeof value === "string")
+      out.src = value.startsWith("synth:")
+        ? value
+        : granularInput({ src: { src: value } }, name, slug)!.src;
+    else if (typeof value === "number")
+      out[key] = finite(value, `${name} granular.${key}`);
+    else if (typeof value === "string" || typeof value === "boolean")
+      out[key] = value;
+    else throw new DawgSdkError(`${name} granular.${key} must be a value`);
+  }
+  return Object.freeze(out) as GranularInput;
+}
+
 /** `./wavetables/x.wav` → `tracks/<slug>/wavetables/x.wav`, like sampler files. */
 function localizeWavetable(spec: WavetableSpec, slug: string): WavetableSpec {
   const src = spec.table.src;
@@ -2617,6 +3907,14 @@ export type ScoreSampleRef = Readonly<{
   fit?: boolean;
   accelerate?: number;
   squiz?: number;
+  bpm?: number;
+  fitmode?: "repitch" | "beats" | "tones";
+  len?: number;
+  shift?: number;
+  formant?: number;
+  fadeTime?: number;
+  fadeInTime?: number;
+  from?: SampleProvenanceSpec;
 }>;
 
 /** A stored track; optional fields are present only when set. */
@@ -2640,6 +3938,7 @@ export type ScoreTrack = Readonly<{
   fx?: FxInput;
   fxAutomation?: Readonly<Record<string, readonly ScorePoint[]>>;
   synth?: SynthInput;
+  keys?: KeysInput;
   sampler?: Readonly<{
     voices: Readonly<Record<string, ScoreSampleRef>>;
     mode: "oneshot" | "keyed";
@@ -2659,8 +3958,20 @@ export type ScoreTrack = Readonly<{
   tuning?: ScoreTuning;
   wavetable?: Readonly<{ table: ScoreSampleRef } & WavetableParams>;
   wtAutomation?: readonly ScorePoint[];
+  /** String engine settings; dawg validates them (SDK 1.21.0). */
+  string?: StringInput;
+  /** Granular settings (SDK 1.23.0); present only when set. */
+  granular?: GranularInput;
+  /** Modal settings (SDK 1.25.0). */
+  modal?: TrackSpec["modal"];
+  /** Guitar fretting (SDK 1.27.0). */
+  guitar?: GuitarSetup;
+  /** Wind settings (SDK 1.30.0). */
+  wind?: TrackSpec["wind"];
   glide?: TrackSpec["glide"];
   pedal?: readonly Readonly<{ tick: number; state: PedalState }>[];
+  softPedal?: readonly Readonly<{ tick: number; state: PedalState }>[];
+  sostenuto?: readonly Readonly<{ tick: number; state: PedalState }>[];
   velocityCurve?: TrackSpec["velocityCurve"];
   humanize?: TrackSpec["humanize"];
 }>;
@@ -2926,6 +4237,7 @@ export function song(input: SongInput): Song {
       stored.wavetable = Object.freeze(fields);
     }
     if (wtAutomation.length > 0) stored.wtAutomation = wtAutomation;
+    if (t.granular) stored.granular = t.granular;
     if (t.sampler)
       stored.sampler = Object.freeze({
         voices: t.sampler.voices,
@@ -2949,11 +4261,13 @@ export function song(input: SongInput): Song {
       if (Object.keys(time).length > 0) stored.time = Object.freeze(time);
     }
     if (t.glide) stored.glide = t.glide;
-    if (t.pedal && t.pedal.length > 0) {
+    for (const key of ["pedal", "softPedal", "sostenuto"] as const) {
+      const lane = t[key];
+      if (!lane || lane.length === 0) continue;
       // One event per tick (the last wins), in tick order, as dawg stores it.
       const byTick = new Map<number, PedalState>();
-      for (const [at, state] of t.pedal) byTick.set(ticks(at), state);
-      stored.pedal = Object.freeze(
+      for (const [at, state] of lane) byTick.set(ticks(at), state);
+      stored[key] = Object.freeze(
         [...byTick.entries()]
           .sort((a, b) => a[0] - b[0])
           .map(([tick, state]) => Object.freeze({ tick, state })),
@@ -2962,6 +4276,11 @@ export function song(input: SongInput): Song {
     if (t.velocityCurve) stored.velocityCurve = t.velocityCurve;
     if (t.humanize) stored.humanize = t.humanize;
     if (t.tuning) stored.tuning = t.tuning;
+    if (t.string) stored.string = t.string;
+    if (t.keys) stored.keys = t.keys;
+    if (t.modal) stored.modal = t.modal;
+    if (t.guitar) stored.guitar = t.guitar;
+    if (t.wind) stored.wind = t.wind;
     if (t.rhythm && t.rhythm.length > 0)
       stored.rhythm = Object.freeze(
         t.rhythm.map((row) => {
@@ -3006,6 +4325,25 @@ export function song(input: SongInput): Song {
       );
     }
   });
+  // An ombak pair (SDK 1.30.0): a partner (pengumbang) whose preset carries
+  // its own ombak twin bank plays one straight voice instead, as `modal
+  // pair` and set_modal leave it, unless it sets ombak itself.
+  for (const track of [...tracks]) {
+    const pair = (track as { modal?: { pair?: string } }).modal?.pair;
+    if (pair === undefined) continue;
+    const at = tracks.findIndex((candidate) => candidate.id === pair);
+    const partner = tracks[at] as
+      (ScoreTrack & { modal?: Readonly<Record<string, unknown>> }) | undefined;
+    if (
+      partner?.modal &&
+      partner.modal.ombak === undefined &&
+      MODAL_TWIN_PRESETS.includes(String(partner.modal.preset))
+    )
+      tracks[at] = Object.freeze({
+        ...partner,
+        modal: Object.freeze({ ...partner.modal, ombak: 0 }),
+      }) as ScoreTrack;
+  }
   const arrangement: {
     sections?: readonly SongSection[];
     form?: readonly SongFormEntry[];
@@ -3670,7 +5008,22 @@ export type ChordOptions = Readonly<{
     | "arp-random"
     | "harp"
     | "slop"
-    | "pattern";
+    | "pattern"
+    | "guitar";
+  /**
+   * With `perform: "guitar"` (SDK 1.27.0): the stroke grid, a name (`down`
+   * `folk` `pop` `punk` `funk` `reggae` `waltz` `jangle` `island`) or
+   * characters D (down) U (up) d u (light) x (muted chuck) - . (rest).
+   */
+  strokes?: string;
+  /** Guitar: grid step in beats, default 0.5 (8ths). */
+  step?: number;
+  /** Guitar: milliseconds a full six-string down stroke takes, default 22. */
+  speed?: number;
+  /** Guitar: the song tempo `speed` converts with, default 120. */
+  tempo?: number;
+  /** Guitar: tuning, capo, hand, ring and position (as a track's `guitar`). */
+  guitar?: GuitarInput;
   /**
    * With `perform: "pattern"`: a rhythm pattern by name or 1-based number
    * (SDK 1.7.0): `eighths`, `sixteenths`, `offbeat`, `pop`, `charleston`,
@@ -3821,6 +5174,7 @@ export function progression(
       seed: finite(options.seed ?? 0, "chord seed"),
       ...(options.pattern !== undefined ? { pattern: options.pattern } : {}),
       velocity: vel,
+      ...(mode === "guitar" ? guitarPerform(options) : {}),
     },
   });
   const out = [
@@ -3834,6 +5188,543 @@ export function progression(
   );
 }
 
+/** A track's guitar setup (SDK 1.27.0): see `TrackInput.guitar`. */
+export type GuitarInput = Readonly<{
+  /** `standard` `dropd` `doubledropd` `dadgad` `openg` `opend` `opene` `halfdown` `nashville` `bass` `ukulele` `requinto`, or open-string pitches low to high. */
+  tune?: string | readonly Pitch[];
+  /** Capo fret 0..12. */
+  capo?: number;
+  /** Hand stretch in frets 3..6, default 4. */
+  hand?: number;
+  /** 0 closed shapes .. 1 ringing open strings, default 0.5. */
+  ring?: number;
+  /** Preferred fret position 0..12. */
+  position?: number;
+}>;
+
+function guitarInput(
+  input: GuitarInput | undefined,
+  where: string,
+): GuitarSetup | undefined {
+  if (input === undefined) return undefined;
+  if (!isRecord(input))
+    throw new DawgSdkError(`${where} guitar must be an object`);
+  const out: Record<string, unknown> = {};
+  for (const key of Object.keys(input))
+    if (!["tune", "capo", "hand", "ring", "position"].includes(key))
+      throw new DawgSdkError(
+        `${where} guitar has no field "${key.slice(0, 32)}" (tune capo hand ring position)`,
+      );
+  if (input.tune !== undefined) {
+    if (typeof input.tune === "string") {
+      const name = input.tune.toLowerCase().replace(/[\s_-]/g, "");
+      if (!(GUITAR_TUNING_NAMES as readonly string[]).includes(name))
+        throw new DawgSdkError(
+          `${where} guitar tune must be one of ${GUITAR_TUNING_NAMES.join(" ")} or a list of pitches`,
+        );
+      out.tune = name;
+    } else if (
+      Array.isArray(input.tune) &&
+      input.tune.length >= 3 &&
+      input.tune.length <= 12
+    )
+      out.tune = Object.freeze(input.tune.map((p) => midi(p)));
+    else
+      throw new DawgSdkError(
+        `${where} guitar tune must be a name or 3..12 pitches`,
+      );
+  }
+  const int = (key: "capo" | "hand" | "position", min: number, max: number) => {
+    const value = input[key];
+    if (value === undefined) return;
+    if (!Number.isInteger(value) || value < min || value > max)
+      throw new DawgSdkError(
+        `${where} guitar ${key} must be an integer ${min}..${max}`,
+      );
+    out[key] = value;
+  };
+  int("capo", 0, 12);
+  int("hand", 3, 6);
+  if (input.ring !== undefined)
+    out.ring =
+      Math.round(unit(input.ring, `${where} guitar ring`) * 1000) / 1000;
+  int("position", 0, 12);
+  return Object.keys(out).length > 0 ? Object.freeze(out) : undefined;
+}
+
+function guitarPerform(options: ChordOptions): Partial<PerformOptions> {
+  if (options.strokes !== undefined && !strokeGrid(options.strokes))
+    throw new DawgSdkError(
+      `chord strokes must be one of ${STROKE_PATTERN_NAMES.join(" ")} or a grid of D U d u x - .`,
+    );
+  const setup = guitarInput(options.guitar, "chord");
+  return {
+    ...(options.strokes !== undefined ? { strokes: options.strokes } : {}),
+    ...(options.step !== undefined
+      ? { step: positive(options.step, "chord step") }
+      : {}),
+    ...(options.speed !== undefined
+      ? {
+          speed:
+            Math.min(200, Math.max(0, finite(options.speed, "chord speed"))) /
+            1000,
+        }
+      : {}),
+    ...(options.tempo !== undefined
+      ? { tempo: positive(options.tempo, "chord tempo") }
+      : {}),
+    ...(setup ? { guitar: setup } : {}),
+  };
+}
+
+/**
+ * Strummed guitar chords (SDK 1.27.0): `progression()` with
+ * `perform: "guitar"`. Each chord is fretted on the guitar (`tune`, `capo`,
+ * no barre over an open string) and strummed with a stroke grid; a down
+ * stroke sweeps the strings in `speed` ms. Pair with `guitar` on the track
+ * so dawg's prompt strums the same shapes.
+ *
+ * ```ts
+ * notes: strum("G D Em C", { strokes: "folk", speed: 25, tempo: 96 })
+ * notes: strum("i VI III VII", { key: "e minor", strokes: "D-DU-UDU", guitar: { capo: 2 } })
+ * ```
+ */
+export function strum(
+  chords: string | readonly string[],
+  options: Omit<ProgressionOptions, "perform"> = {},
+): readonly NoteSpec[] {
+  return progression(chords, { ...options, perform: "guitar" });
+}
+
+// BEGIN instrument words: generated from core/instruments.ts by core/sdk/sync-instruments.ts
+/** What an instrument word stores on a track. */
+type InstrumentWord = Readonly<{
+  /** The `Track.instrument` value. */
+  instrument: string;
+  /** The optional Track field the engine reads (created with defaults). */
+  field?: string;
+  /** A preset of that engine to apply. */
+  preset?: string;
+  /** An insert-effect preset to apply with it (rig aliases). */
+  fx?: string;
+}>;
+
+/** A word and what it means. */
+type InstrumentWordRow = Readonly<{
+  word: string;
+  /**
+   * Borrow the voice (instrument, field, preset) of this other word's row
+   * when it exists; `instrument` is the fallback when it does not.
+   */
+  voice?: string;
+}> &
+  InstrumentWord;
+
+/**
+ * Words that keep their pre-0.6 meaning forever: they resolve to
+ * themselves, whatever rows the lanes add.
+ */
+const LEGACY_WORDS: readonly string[] = Object.freeze([
+  "piano",
+  "pluck",
+  "bass",
+  "saw",
+  "square",
+  "triangle",
+  "marimba",
+  "wind",
+  "cello",
+  "contrabass",
+  "ebass",
+  "sitar",
+  "organ",
+  "strings",
+  "bell",
+  "keys",
+  "lead",
+]);
+
+/** 0.6 instrument words; each lane appends its own block. */
+const INSTRUMENT_WORDS: readonly InstrumentWordRow[] = Object.freeze([
+  // strings (f06-strings): plucked presets of the string engine. Legacy
+  // sitar/ebass keep today's voice (`string preset sitar` reaches the
+  // engine), jangle is the rig alias (the guitar lane maps its 12string to the
+  // preset; `string jangle` reaches it) and
+  // upright is the keys lane's piano (doublebass reaches the preset).
+  { word: "nylon", instrument: "string", field: "string", preset: "nylon" },
+  { word: "steel", instrument: "string", field: "string", preset: "steel" },
+  {
+    word: "electric",
+    instrument: "string",
+    field: "string",
+    preset: "electric",
+  },
+  { word: "slap", instrument: "string", field: "string", preset: "slap" },
+  { word: "motown", instrument: "string", field: "string", preset: "motown" },
+  { word: "tanpura", instrument: "string", field: "string", preset: "tanpura" },
+  {
+    word: "harpsichord",
+    instrument: "string",
+    field: "string",
+    preset: "harpsichord",
+  },
+  { word: "lute", instrument: "string", field: "string", preset: "lute" },
+  { word: "oud", instrument: "string", field: "string", preset: "oud" },
+  { word: "setar", instrument: "string", field: "string", preset: "setar" },
+  { word: "tar", instrument: "string", field: "string", preset: "tar" },
+  { word: "santur", instrument: "string", field: "string", preset: "santur" },
+  {
+    word: "dulcimer",
+    instrument: "string",
+    field: "string",
+    preset: "dulcimer",
+  },
+  { word: "koto", instrument: "string", field: "string", preset: "koto" },
+  { word: "harp", instrument: "string", field: "string", preset: "harp" },
+  { word: "banjo", instrument: "string", field: "string", preset: "banjo" },
+  { word: "tres", instrument: "string", field: "string", preset: "tres" },
+  {
+    word: "requinto",
+    instrument: "string",
+    field: "string",
+    preset: "requinto",
+  },
+  { word: "acoustic", instrument: "string", field: "string", preset: "steel" },
+  { word: "classical", instrument: "string", field: "string", preset: "nylon" },
+  {
+    word: "bassguitar",
+    instrument: "string",
+    field: "string",
+    preset: "ebass",
+  },
+  { word: "fender", instrument: "string", field: "string", preset: "ebass" },
+  {
+    word: "doublebass",
+    instrument: "string",
+    field: "string",
+    preset: "upright",
+  },
+  {
+    word: "cembalo",
+    instrument: "string",
+    field: "string",
+    preset: "harpsichord",
+  },
+  {
+    word: "hammered",
+    instrument: "string",
+    field: "string",
+    preset: "dulcimer",
+  },
+  { word: "sehtar", instrument: "string", field: "string", preset: "setar" },
+  // bowed (f061-bowed): bowed presets of the string engine. `cello`,
+  // `contrabass` and `strings` stay legacy words (today's voice);
+  // `bowed-cello`, `string cello` or `bowed cello` reach the engine.
+  { word: "violin", instrument: "string", field: "string", preset: "violin" },
+  { word: "viola", instrument: "string", field: "string", preset: "viola" },
+  { word: "fiddle", instrument: "string", field: "string", preset: "fiddle" },
+  { word: "erhu", instrument: "string", field: "string", preset: "erhu" },
+  {
+    word: "kamancheh",
+    instrument: "string",
+    field: "string",
+    preset: "kamancheh",
+  },
+  {
+    word: "kemence",
+    instrument: "string",
+    field: "string",
+    preset: "kamancheh",
+  },
+  { word: "violins", instrument: "string", field: "string", preset: "violins" },
+  { word: "violas", instrument: "string", field: "string", preset: "violas" },
+  { word: "cellos", instrument: "string", field: "string", preset: "cellos" },
+  {
+    word: "contrabasses",
+    instrument: "string",
+    field: "string",
+    preset: "contrabasses",
+  },
+  { word: "pizzicato", instrument: "string", field: "string", preset: "pizz" },
+  { word: "tremolo", instrument: "string", field: "string", preset: "trem" },
+  {
+    word: "bowed-cello",
+    instrument: "string",
+    field: "string",
+    preset: "cello",
+  },
+  // f06-rig: guitar track aliases, a guitar voice plus a whole rig. The
+  // voice is the strings lane's `electric` row (jangle: its 12-string
+  // `jangle` preset); the pluck only while that row is absent. Never `lead`
+  // or `bass`.
+  {
+    word: "jangle",
+    instrument: "string",
+    field: "string",
+    preset: "jangle",
+    fx: "jangle",
+  },
+  { word: "punk", instrument: "pluck", voice: "electric", fx: "punk" },
+  { word: "funk", instrument: "pluck", voice: "electric", fx: "funk" },
+  { word: "ragged", instrument: "pluck", voice: "electric", fx: "ragged" },
+  { word: "gtr-lead", instrument: "pluck", voice: "electric", fx: "lead" },
+  { word: "gtr-metal", instrument: "pluck", voice: "electric", fx: "metal" },
+  { word: "bachata", instrument: "pluck", voice: "electric", fx: "bachata" },
+  // granular (f06-granular): the instrument and its texture presets. Each
+  // starts from a built-in synth source, so nothing downloads.
+  {
+    word: "granular",
+    instrument: "granular",
+    field: "granular",
+    preset: "cloud",
+  },
+  {
+    word: "grains",
+    instrument: "granular",
+    field: "granular",
+    preset: "cloud",
+  },
+  { word: "cloud", instrument: "granular", field: "granular", preset: "cloud" },
+  {
+    word: "sparkle",
+    instrument: "granular",
+    field: "granular",
+    preset: "sparkle",
+  },
+  { word: "swarm", instrument: "granular", field: "granular", preset: "swarm" },
+  {
+    word: "microloop",
+    instrument: "granular",
+    field: "granular",
+    preset: "microloop",
+  },
+  // keys (f06-piano): modelled pianos. `piano` stays legacy here; the typed
+  // surfaces store a new `piano` as `grand` (core/keys.ts `pianoWrite`).
+  { word: "grand", instrument: "grand", field: "keys", preset: "grand" },
+  { word: "ballad", instrument: "grand", field: "keys", preset: "ballad" },
+  { word: "upright", instrument: "upright", field: "keys", preset: "upright" },
+  { word: "felt", instrument: "felt", field: "keys", preset: "felt" },
+  { word: "lofi", instrument: "felt", field: "keys", preset: "lofi" },
+  {
+    word: "honkytonk",
+    instrument: "honkytonk",
+    field: "keys",
+    preset: "honkytonk",
+  },
+  {
+    word: "prepared",
+    instrument: "prepared",
+    field: "keys",
+    preset: "prepared",
+  },
+  // keys (f061-organ): tonewheel, combo and pipe organs on the keys
+  // engine. `organ` stays legacy (the sine voice).
+  {
+    word: "tonewheel",
+    instrument: "tonewheel",
+    field: "keys",
+    preset: "tonewheel",
+  },
+  {
+    word: "hammond",
+    instrument: "tonewheel",
+    field: "keys",
+    preset: "tonewheel",
+  },
+  { word: "b3", instrument: "tonewheel", field: "keys", preset: "tonewheel" },
+  { word: "gospel", instrument: "tonewheel", field: "keys", preset: "gospel" },
+  {
+    word: "jazzorgan",
+    instrument: "tonewheel",
+    field: "keys",
+    preset: "jazzorgan",
+  },
+  { word: "combo", instrument: "combo", field: "keys", preset: "combo" },
+  { word: "farfisa", instrument: "combo", field: "keys", preset: "combo" },
+  { word: "vox", instrument: "combo", field: "keys", preset: "vox" },
+  { word: "pipe", instrument: "pipe", field: "keys", preset: "pipe" },
+  { word: "church", instrument: "pipe", field: "keys", preset: "pipe" },
+  { word: "pipeorgan", instrument: "pipe", field: "keys", preset: "pipe" },
+  { word: "churchorgan", instrument: "pipe", field: "keys", preset: "pipe" },
+  { word: "flutes", instrument: "pipe", field: "keys", preset: "flutes" },
+  { word: "cornet", instrument: "pipe", field: "keys", preset: "cornet" },
+  { word: "reeds", instrument: "pipe", field: "keys", preset: "reeds" },
+  { word: "celeste", instrument: "pipe", field: "keys", preset: "celeste" },
+  // f06-modal: mallets and bells (core/resonators.ts). `marimba` is legacy;
+  // `modal` alone gives the modal marimba.
+  { word: "modal", instrument: "modal", field: "modal", preset: "marimba" },
+  { word: "vibes", instrument: "modal", field: "modal", preset: "vibes" },
+  { word: "vibraphone", instrument: "modal", field: "modal", preset: "vibes" },
+  {
+    word: "xylophone",
+    instrument: "modal",
+    field: "modal",
+    preset: "xylophone",
+  },
+  { word: "glock", instrument: "modal", field: "modal", preset: "glock" },
+  {
+    word: "glockenspiel",
+    instrument: "modal",
+    field: "modal",
+    preset: "glock",
+  },
+  { word: "celesta", instrument: "modal", field: "modal", preset: "celesta" },
+  { word: "chimes", instrument: "modal", field: "modal", preset: "chimes" },
+  { word: "tubular", instrument: "modal", field: "modal", preset: "chimes" },
+  { word: "kalimba", instrument: "modal", field: "modal", preset: "kalimba" },
+  {
+    word: "thumbpiano",
+    instrument: "modal",
+    field: "modal",
+    preset: "kalimba",
+  },
+  { word: "mbira", instrument: "modal", field: "modal", preset: "mbira" },
+  { word: "steelpan", instrument: "modal", field: "modal", preset: "steelpan" },
+  { word: "bowl", instrument: "modal", field: "modal", preset: "bowl" },
+  { word: "gong", instrument: "modal", field: "modal", preset: "gong" },
+  { word: "gongageng", instrument: "modal", field: "modal", preset: "gong" },
+  { word: "timpani", instrument: "modal", field: "modal", preset: "timpani" },
+  {
+    word: "steeldrum",
+    instrument: "modal",
+    field: "modal",
+    preset: "steelpan",
+  },
+  { word: "singingbowl", instrument: "modal", field: "modal", preset: "bowl" },
+  {
+    word: "kettledrum",
+    instrument: "modal",
+    field: "modal",
+    preset: "timpani",
+  },
+  {
+    word: "tubularbells",
+    instrument: "modal",
+    field: "modal",
+    preset: "chimes",
+  },
+  // keys-electric (0.6.1): electric pianos and clavinet. `keys` stays legacy.
+  { word: "epiano", instrument: "epiano", field: "keys", preset: "epiano" },
+  { word: "rhodes", instrument: "epiano", field: "keys", preset: "epiano" },
+  {
+    word: "suitcase",
+    instrument: "epiano",
+    field: "keys",
+    preset: "suitcase",
+  },
+  { word: "dyno", instrument: "epiano", field: "keys", preset: "dyno" },
+  { word: "wurli", instrument: "wurli", field: "keys", preset: "wurli" },
+  { word: "wurlitzer", instrument: "wurli", field: "keys", preset: "wurli" },
+  { word: "clav", instrument: "clav", field: "keys", preset: "clav" },
+  { word: "clavinet", instrument: "clav", field: "keys", preset: "clav" },
+  { word: "funkclav", instrument: "clav", field: "keys", preset: "funkclav" },
+  // f061-guitar: the shoegaze alias, an electric guitar voice plus the
+  // shoegaze rig and its long wash.
+  { word: "shoegaze", instrument: "pluck", voice: "electric", fx: "shoegaze" },
+  // f061 integration: the two rig names that are free as instrument words
+  // (glide and swell are taken by commands; reach them with `rig glide`).
+  { word: "dreampop", instrument: "pluck", voice: "electric", fx: "dreampop" },
+  { word: "ebow", instrument: "pluck", voice: "electric", fx: "ebow" },
+  // f061-gamelan-winds: gamelan, small bells and frame drums.
+  { word: "crotales", instrument: "modal", field: "modal", preset: "crotales" },
+  { word: "crotale", instrument: "modal", field: "modal", preset: "crotales" },
+  { word: "musicbox", instrument: "modal", field: "modal", preset: "musicbox" },
+  { word: "toypiano", instrument: "modal", field: "modal", preset: "toypiano" },
+  { word: "saron", instrument: "modal", field: "modal", preset: "saron" },
+  { word: "demung", instrument: "modal", field: "modal", preset: "demung" },
+  { word: "slenthem", instrument: "modal", field: "modal", preset: "slenthem" },
+  { word: "gangsa", instrument: "modal", field: "modal", preset: "gangsa" },
+  { word: "gender", instrument: "modal", field: "modal", preset: "gender" },
+  { word: "bonang", instrument: "modal", field: "modal", preset: "bonang" },
+  { word: "kenong", instrument: "modal", field: "modal", preset: "kenong" },
+  { word: "kethuk", instrument: "modal", field: "modal", preset: "kethuk" },
+  { word: "kempul", instrument: "modal", field: "modal", preset: "kempul" },
+  { word: "daf", instrument: "modal", field: "modal", preset: "daf" },
+  { word: "bodhran", instrument: "modal", field: "modal", preset: "bodhran" },
+  { word: "framedrum", instrument: "modal", field: "modal", preset: "bodhran" },
+  { word: "tabla", instrument: "modal", field: "modal", preset: "tabla" },
+  // f061-gamelan-winds: blown waveguides (core/winds.ts). The legacy word
+  // `wind` keeps its tone; these words and their aliases pick a wind preset.
+  { word: "flute", instrument: "wind", field: "wind", preset: "flute" },
+  { word: "recorder", instrument: "wind", field: "wind", preset: "recorder" },
+  { word: "whistle", instrument: "wind", field: "wind", preset: "whistle" },
+  { word: "ney", instrument: "wind", field: "wind", preset: "ney" },
+  {
+    word: "shakuhachi",
+    instrument: "wind",
+    field: "wind",
+    preset: "shakuhachi",
+  },
+  { word: "panpipe", instrument: "wind", field: "wind", preset: "panpipe" },
+  { word: "suling", instrument: "wind", field: "wind", preset: "suling" },
+  { word: "bansuri", instrument: "wind", field: "wind", preset: "bansuri" },
+  { word: "clarinet", instrument: "wind", field: "wind", preset: "clarinet" },
+  {
+    word: "bassclarinet",
+    instrument: "wind",
+    field: "wind",
+    preset: "bassclarinet",
+  },
+  { word: "oboe", instrument: "wind", field: "wind", preset: "oboe" },
+  { word: "bassoon", instrument: "wind", field: "wind", preset: "bassoon" },
+  { word: "sax", instrument: "wind", field: "wind", preset: "sax" },
+  { word: "altosax", instrument: "wind", field: "wind", preset: "altosax" },
+  { word: "barisax", instrument: "wind", field: "wind", preset: "barisax" },
+  { word: "trumpet", instrument: "wind", field: "wind", preset: "trumpet" },
+  { word: "harmon", instrument: "wind", field: "wind", preset: "harmon" },
+  { word: "plunger", instrument: "wind", field: "wind", preset: "plunger" },
+  { word: "trombone", instrument: "wind", field: "wind", preset: "trombone" },
+  { word: "tuba", instrument: "wind", field: "wind", preset: "tuba" },
+  { word: "horn", instrument: "wind", field: "wind", preset: "horn" },
+  { word: "tinwhistle", instrument: "wind", field: "wind", preset: "whistle" },
+  {
+    word: "pennywhistle",
+    instrument: "wind",
+    field: "wind",
+    preset: "whistle",
+  },
+  { word: "nay", instrument: "wind", field: "wind", preset: "ney" },
+  { word: "panflute", instrument: "wind", field: "wind", preset: "panpipe" },
+  { word: "panpipes", instrument: "wind", field: "wind", preset: "panpipe" },
+  { word: "saxophone", instrument: "wind", field: "wind", preset: "sax" },
+  { word: "tenorsax", instrument: "wind", field: "wind", preset: "sax" },
+  { word: "tenor", instrument: "wind", field: "wind", preset: "sax" },
+  { word: "alto", instrument: "wind", field: "wind", preset: "altosax" },
+  { word: "bari", instrument: "wind", field: "wind", preset: "barisax" },
+  { word: "baritonesax", instrument: "wind", field: "wind", preset: "barisax" },
+  { word: "frenchhorn", instrument: "wind", field: "wind", preset: "horn" },
+  { word: "mutedtrumpet", instrument: "wind", field: "wind", preset: "harmon" },
+  { word: "wahtrumpet", instrument: "wind", field: "wind", preset: "plunger" },
+]);
+
+/**
+ * What an instrument word means: a legacy word is itself, a row word is its
+ * row, anything else is undefined (callers keep the word as typed).
+ */
+function resolveInstrumentWord(word: string): InstrumentWord | undefined {
+  if (LEGACY_WORDS.includes(word)) return Object.freeze({ instrument: word });
+  const row = INSTRUMENT_WORDS.find((entry) => entry.word === word);
+  if (!row) return undefined;
+  const { word: _word, voice, ...meaning } = row;
+  const borrowed =
+    voice === undefined
+      ? undefined
+      : INSTRUMENT_WORDS.find((entry) => entry.word === voice && !entry.voice);
+  if (!borrowed) return Object.freeze(meaning);
+  return Object.freeze({
+    instrument: borrowed.instrument,
+    ...(borrowed.field === undefined ? {} : { field: borrowed.field }),
+    ...(borrowed.preset === undefined ? {} : { preset: borrowed.preset }),
+    ...(meaning.fx === undefined ? {} : { fx: meaning.fx }),
+  });
+}
+
+/** The `Track.instrument` value a word stores (the word itself if unknown). */
+function instrumentForWord(word: string): string {
+  return resolveInstrumentWord(word)?.instrument ?? word;
+}
+// END instrument words
+
 // BEGIN chord engine: generated from core/chords.ts by core/sdk/sync-chords.ts
 // ---------------------------------------------------------------------------
 // Vocabulary
@@ -3921,6 +5812,12 @@ 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;
 }>;
 
 function makeChord(
@@ -3928,6 +5825,7 @@ function makeChord(
   quality: Quality,
   extensions: Iterable<Extension> = [],
   bass?: number,
+  tensions: readonly number[] = [],
 ): Chord {
   const held = new Set(extensions);
   const own = SECRET_EXTENSION[quality];
@@ -3939,6 +5837,11 @@ 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)),
+        }
+      : {}),
   });
 }
 
@@ -3946,6 +5849,7 @@ function makeChord(
 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);
 }
@@ -3998,6 +5902,18 @@ const SECRET_SUFFIX: Readonly<Partial<Record<Quality, string>>> = Object.freeze(
 
 /** Chord symbol suffix: `m7`, `maj9`, `7sus4`, `dim7`, `m7b5`, `6/9`. */
 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");
@@ -4161,9 +6077,51 @@ const SUFFIXES: readonly (readonly [string, Quality, readonly Extension[]])[] =
     ["addb6", "b6", []],
     ["7#9", "7#9", []],
   ];
-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,
+  { quality: Quality; ext: readonly Extension[]; tensions?: readonly number[] }
+>([
+  ...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,
@@ -4205,7 +6163,7 @@ function parseChord(symbol: string): Chord | 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);
 }
 
 // ---------------------------------------------------------------------------
@@ -5003,6 +6961,8 @@ const PERFORM_MODES = [
   "harp",
   "slop",
   "pattern",
+  // 0.6.1: fretboard-voiced strokes (see `voiceGuitar`, `strokeVoicing`).
+  "guitar",
 ] as const;
 type PerformMode = (typeof PERFORM_MODES)[number];
 
@@ -5022,6 +6982,23 @@ 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;
 }>;
 
 type PerformedNote = Readonly<{
@@ -5338,6 +7315,24 @@ 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) =>
@@ -5372,6 +7367,380 @@ 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).
+ */
+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[]>);
+type GuitarTuningName = keyof typeof GUITAR_TUNINGS;
+const GUITAR_TUNING_NAMES = Object.keys(GUITAR_TUNINGS) as GuitarTuningName[];
+
+/** How a guitar is set up for voicing chords (`Track.guitar`). */
+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). */
+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). */
+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.
+ */
+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.
+ */
+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`. */
+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.
+ */
+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>);
+const STROKE_PATTERN_NAMES = Object.keys(STROKE_PATTERNS);
+const STROKE_CHARS = /^[DUdux.\-]+$/;
+
+/** Default seconds a full six-string down stroke takes (22 ms). */
+const DEFAULT_STROKE_SPEED = 0.022;
+/** Default stroke grid step in beats (8ths). */
+const DEFAULT_STROKE_STEP = 0.5;
+
+/** A stroke grid by name, or a literal grid of D U d u x - .; undefined if bad. */
+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.
+ */
+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
 
@@ -5755,6 +8124,14 @@ 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]!;