@wenathlan/debonair 2.0.94 → 2.0.118

package/tests/pianoroll.test.ts

@@ -0,0 +1,336 @@
+// # pianoroll.test — the note editor of the katexis engine: every test
+// watches the contract the studio edits under — the import is deterministic,
+// the rebuild answers the schedule bit-for-bit (deep equal), the ids stay
+// stable and unique, the edit ops snap, clamp and honor the role overlap
+// policies, quantize straightens the swing by strength and the validator
+// answers the problems the plan's own grammar never allows.
+import assert from "node:assert/strict";
+import { describe, it } from "vitest";
+import { planTake, type TakePlan } from "../arranger.ts";
+import {
+  addNote,
+  type EditableNote,
+  moveNote,
+  notesToSchedule,
+  PIANOROLL_CONSTANTS,
+  PianoRollError,
+  quantizeNote,
+  removeNote,
+  resizeNote,
+  scheduleToNotes,
+  validateNotes,
+} from "../pianoroll.ts";
+import { scheduleTake } from "../takeevents.ts";
+
+/** the swung fixture (lofi swings 0.62 — the deep column offset the matrix carries) */
+const SWUNG_PLAN: TakePlan = planTake({ prompt: "dusty lofi swing, warm sub", seed: "k3-swung", genreId: "lofi" });
+/** the straight fixture (techno swings 0.5 — no column offset at all) */
+const STRAIGHT_PLAN: TakePlan = planTake({
+  prompt: "warehouse loop, four on the floor",
+  seed: "k3-straight",
+  genreId: "techno",
+});
+const BAR: { fromBar: number; bars: number } = { fromBar: 0, bars: 1 };
+
+/** builds a synthetic melodic note (the validator's fixture). */
+function keysNote(step: number, midi: number, idSuffix = `${step}-${midi}`): EditableNote {
+  return {
+    id: `keys-0-${idSuffix}`,
+    role: "keys",
+    lane: "keys",
+    midi,
+    bar: 0,
+    step,
+    steps: 4,
+    velocity: 0.8,
+    swing: 0,
+    gate: 0.4,
+  };
+}
+
+describe("pianoroll — scheduleToNotes", () => {
+  const swung = scheduleToNotes(scheduleTake(SWUNG_PLAN), SWUNG_PLAN);
+
+  it("is deterministic for the same schedule and plan", () => {
+    const again = scheduleToNotes(scheduleTake(SWUNG_PLAN), SWUNG_PLAN);
+    assert.equal(JSON.stringify(again), JSON.stringify(swung));
+  });
+
+  it("answers stable unique ids in the documented shape", () => {
+    const ids = swung.map((note) => note.id);
+    assert.equal(new Set(ids).size, ids.length, "the roll carried a duplicate id");
+    for (const id of ids) assert.match(id, /^[a-z]+-\d+-\d+-\d+$/);
+  });
+
+  it("maps every note inside the take with a step on the 16th grid", () => {
+    assert.ok(swung.length > 0);
+    for (const note of swung) {
+      assert.ok(note.bar >= 0 && note.bar < SWUNG_PLAN.bars);
+      assert.ok(note.step >= 0 && note.step < PIANOROLL_CONSTANTS.STEPS_PER_BAR);
+      assert.ok(note.steps >= PIANOROLL_CONSTANTS.MIN_NOTE_STEPS);
+      assert.ok(note.velocity >= 0 && note.velocity <= 1);
+      if (note.role !== "drums") {
+        assert.ok(note.midi >= PIANOROLL_CONSTANTS.NOTE_MIN && note.midi <= PIANOROLL_CONSTANTS.NOTE_MAX);
+      }
+    }
+  });
+
+  it("recovers the plan's swing column exactly (the deep offset)", () => {
+    // lofi swings 0.62 → the columns at step % 4 === 2 ride a 0.48 offset
+    const swungHat = swung.find((note) => note.role === "drums" && note.lane === "hat" && note.step === 2);
+    assert.ok(swungHat, "the lofi grid carries a hat on the swung column");
+    assert.ok(Math.abs(swungHat.swing - 0.48) < 1e-9);
+    // the straight plan carries no swing anywhere
+    const straight = scheduleToNotes(scheduleTake(STRAIGHT_PLAN), STRAIGHT_PLAN);
+    for (const note of straight) assert.equal(note.swing, 0);
+  });
+
+  it("rides the bass two octaves up into the C2 window", () => {
+    const bass = swung.find((note) => note.role === "bass");
+    assert.ok(bass, "the trap plan voices the bass");
+    assert.ok(bass.midi >= PIANOROLL_CONSTANTS.NOTE_MIN, "the bass roll pitch left the window");
+  });
+});
+
+describe("pianoroll — notesToSchedule", () => {
+  it("rebuilds the swung schedule bit-for-bit (deep equal)", () => {
+    const schedule = scheduleTake(SWUNG_PLAN);
+    const rebuilt = notesToSchedule(scheduleToNotes(schedule, SWUNG_PLAN), SWUNG_PLAN);
+    assert.deepEqual(rebuilt, schedule);
+  });
+
+  it("rebuilds the straight schedule bit-for-bit (deep equal)", () => {
+    const schedule = scheduleTake(STRAIGHT_PLAN);
+    const rebuilt = notesToSchedule(scheduleToNotes(schedule, STRAIGHT_PLAN), STRAIGHT_PLAN);
+    assert.deepEqual(rebuilt, schedule);
+  });
+
+  it("is deterministic for the same notes and plan", () => {
+    const notes = scheduleToNotes(scheduleTake(SWUNG_PLAN), SWUNG_PLAN);
+    const first = JSON.stringify(notesToSchedule(notes, SWUNG_PLAN));
+    const second = JSON.stringify(notesToSchedule(notes, SWUNG_PLAN));
+    assert.equal(first, second);
+  });
+
+  it("keeps the per-role counts consistent and the events time-ascending", () => {
+    const notes = scheduleToNotes(scheduleTake(SWUNG_PLAN), SWUNG_PLAN);
+    const rebuilt = notesToSchedule(notes, SWUNG_PLAN);
+    const counted = { drums: 0, bass: 0, keys: 0, lead: 0 };
+    for (const note of notes) counted[note.role] += 1;
+    assert.deepEqual(rebuilt.perRole, counted);
+    for (let index = 1; index < rebuilt.events.length; index++) {
+      assert.ok(rebuilt.events[index].time >= rebuilt.events[index - 1].time);
+    }
+  });
+
+  it("answers the drums zero midi and the plan's duration", () => {
+    const notes = scheduleToNotes(scheduleTake(SWUNG_PLAN), SWUNG_PLAN);
+    const rebuilt = notesToSchedule(notes, SWUNG_PLAN);
+    for (const event of rebuilt.events) if (event.role === "drums") assert.equal(event.midi, 0);
+    assert.equal(rebuilt.duration, SWUNG_PLAN.durationSeconds);
+  });
+});
+
+describe("pianoroll — addNote", () => {
+  const notes = scheduleToNotes(scheduleTake(SWUNG_PLAN), SWUNG_PLAN);
+
+  it("adds one note with the hard velocity, one step and the documented id", () => {
+    const next = addNote(notes, { role: "drums", lane: "tom", bar: 0, step: 7 }, BAR, SWUNG_PLAN);
+    assert.equal(next.length, notes.length + 1);
+    const added = next.find((note) => note.lane === "tom");
+    assert.ok(added);
+    assert.equal(added.id, "drums-0-7-7");
+    assert.equal(added.velocity, PIANOROLL_CONSTANTS.VELOCITY_STEPS.hard);
+    assert.equal(added.steps, 1);
+  });
+
+  it("blocks a doubled lane slot (the drums policy) and spares the other lanes", () => {
+    assert.throws(
+      () => addNote(notes, { role: "drums", lane: "kick", bar: 0, step: 0 }, BAR, SWUNG_PLAN),
+      (error: unknown) => {
+        assert.ok(error instanceof PianoRollError);
+        assert.equal(error.code, "overlap");
+        return true;
+      },
+    );
+    const next = addNote(notes, { role: "drums", lane: "snare", bar: 0, step: 0 }, BAR, SWUNG_PLAN);
+    assert.equal(next.length, notes.length + 1);
+  });
+
+  it("blocks the keys span overlap and spares the other pitches (the chord law)", () => {
+    const keys = notes.find((note) => note.role === "keys");
+    assert.ok(keys);
+    assert.throws(
+      () => addNote(notes, { role: "keys", midi: keys.midi, bar: 0, step: 4 }, BAR, SWUNG_PLAN),
+      (error: unknown) => error instanceof PianoRollError && error.code === "overlap",
+    );
+    const next = addNote(notes, { role: "keys", midi: PIANOROLL_CONSTANTS.NOTE_MAX, bar: 0, step: 0 }, BAR, SWUNG_PLAN);
+    assert.equal(next.length, notes.length + 1);
+  });
+
+  it("blocks the doubled bass onset and allows the retrigger a slot later", () => {
+    const bass = notes.find((note) => note.role === "bass");
+    assert.ok(bass);
+    // the bass enters with the verse, so the window rides the note's own bar
+    const win = { fromBar: bass.bar, bars: 1 };
+    assert.throws(
+      () => addNote(notes, { role: "bass", midi: bass.midi, bar: bass.bar, step: bass.step }, win, SWUNG_PLAN),
+      (error: unknown) => error instanceof PianoRollError && error.code === "overlap",
+    );
+    const next = addNote(notes, { role: "bass", midi: bass.midi, bar: bass.bar, step: bass.step + 1 }, win, SWUNG_PLAN);
+    assert.equal(next.length, notes.length + 1);
+  });
+
+  it("clamps the drop into the clip window and refuses a window off the take", () => {
+    const clamped = addNote(notes, { role: "drums", lane: "tom", bar: 5, step: 20 }, BAR, SWUNG_PLAN);
+    const dropped = clamped.find((note) => note.lane === "tom");
+    assert.ok(dropped);
+    assert.equal(dropped.bar, 0);
+    assert.equal(dropped.step, PIANOROLL_CONSTANTS.STEPS_PER_BAR - 1);
+    assert.throws(
+      () =>
+        addNote(
+          notes,
+          { role: "drums", lane: "tom", bar: 0, step: 0 },
+          { fromBar: SWUNG_PLAN.bars, bars: 1 },
+          SWUNG_PLAN,
+        ),
+      (error: unknown) => error instanceof PianoRollError && error.code === "out-of-window",
+    );
+  });
+
+  it("refuses a melodic midi off the C2..C6 window and a duplicate id", () => {
+    assert.throws(
+      () => addNote(notes, { role: "lead", midi: PIANOROLL_CONSTANTS.NOTE_MAX + 1, bar: 0, step: 0 }, BAR, SWUNG_PLAN),
+      (error: unknown) => error instanceof PianoRollError && error.code === "bad-note",
+    );
+    const keys = notes.find((note) => note.role === "keys");
+    assert.ok(keys);
+    const slot = { role: "keys" as const, midi: PIANOROLL_CONSTANTS.NOTE_MAX, bar: 0, step: 15 };
+    const seeded = addNote(notes, slot, BAR, SWUNG_PLAN);
+    assert.throws(
+      () => addNote(seeded, slot, BAR, SWUNG_PLAN),
+      (error: unknown) => error instanceof PianoRollError && error.code === "overlap",
+    );
+  });
+});
+
+describe("pianoroll — removeNote, moveNote, resizeNote", () => {
+  const notes = scheduleToNotes(scheduleTake(SWUNG_PLAN), SWUNG_PLAN);
+  const kick = notes.find((note) => note.role === "drums" && note.lane === "kick" && note.bar === 0);
+  assert.ok(kick);
+
+  it("removes by id and refuses a second removal", () => {
+    const next = removeNote(notes, kick.id);
+    assert.equal(next.length, notes.length - 1);
+    assert.ok(!next.some((note) => note.id === kick.id));
+    assert.throws(
+      () => removeNote(next, kick.id),
+      (error: unknown) => error instanceof PianoRollError && error.code === "bad-note",
+    );
+  });
+
+  it("moves on the straight grid, keeps the id stable and leaves the others untouched", () => {
+    const next = moveNote(notes, kick.id, 2, BAR, SWUNG_PLAN);
+    const moved = next.find((note) => note.id === kick.id);
+    assert.ok(moved);
+    assert.equal(moved.step, kick.step + 2);
+    assert.equal(moved.bar, 0);
+    assert.equal(next.length, notes.length);
+    const others = next.filter((note) => note.id !== kick.id);
+    assert.deepEqual(
+      others,
+      notes.filter((note) => note.id !== kick.id),
+    );
+  });
+
+  it("clamps the move into the clip window", () => {
+    const next = moveNote(notes, kick.id, 100, BAR, SWUNG_PLAN);
+    const moved = next.find((note) => note.id === kick.id);
+    assert.ok(moved);
+    assert.equal(moved.step, PIANOROLL_CONSTANTS.STEPS_PER_BAR - kick.steps);
+    assert.equal(moved.bar, 0);
+  });
+
+  it("refuses a move into a same-lane span and a move off the roll", () => {
+    const seeded = addNote(notes, { role: "drums", lane: "kick", bar: 0, step: 4 }, BAR, SWUNG_PLAN);
+    assert.throws(
+      () => moveNote(seeded, kick.id, 4, BAR, SWUNG_PLAN),
+      (error: unknown) => error instanceof PianoRollError && error.code === "overlap",
+    );
+    assert.throws(
+      () => moveNote(notes, "drums-9-9-9", 1, BAR, SWUNG_PLAN),
+      (error: unknown) => error instanceof PianoRollError && error.code === "bad-note",
+    );
+  });
+
+  it("resizes with the one-step floor, recomputes the gate and clamps at the window", () => {
+    const floored = resizeNote(notes, kick.id, 0, BAR, SWUNG_PLAN);
+    assert.equal(floored.find((note) => note.id === kick.id)?.steps, PIANOROLL_CONSTANTS.MIN_NOTE_STEPS);
+    const grown = resizeNote(notes, kick.id, 5, BAR, SWUNG_PLAN);
+    const resized = grown.find((note) => note.id === kick.id);
+    assert.ok(resized);
+    assert.equal(resized.steps, 5);
+    assert.equal(resized.gate, Number((5 * (60 / SWUNG_PLAN.bpm / 4)).toFixed(6)));
+    const tail = addNote(notes, { role: "drums", lane: "kick", bar: 0, step: 15 }, BAR, SWUNG_PLAN);
+    const clamped = resizeNote(
+      tail,
+      tail.find((note) => note.step === 15 && note.lane === "kick")?.id ?? "",
+      100,
+      BAR,
+      SWUNG_PLAN,
+    );
+    assert.equal(clamped.find((note) => note.lane === "kick" && note.step === 15)?.steps, 1);
+  });
+
+  it("refuses a resize into a same-lane span", () => {
+    const seeded = addNote(notes, { role: "drums", lane: "kick", bar: 0, step: 4 }, BAR, SWUNG_PLAN);
+    assert.throws(
+      () => resizeNote(seeded, kick.id, 5, BAR, SWUNG_PLAN),
+      (error: unknown) => error instanceof PianoRollError && error.code === "overlap",
+    );
+  });
+});
+
+describe("pianoroll — quantizeNote", () => {
+  const notes = scheduleToNotes(scheduleTake(SWUNG_PLAN), SWUNG_PLAN);
+  const swungHat = notes.find((note) => note.role === "drums" && note.lane === "hat" && note.step === 2);
+  assert.ok(swungHat);
+
+  it("straightens the onset at strength 1 and keeps it at strength 0", () => {
+    const straight = quantizeNote(notes, swungHat.id, 1);
+    assert.equal(straight.find((note) => note.id === swungHat.id)?.swing, 0);
+    const kept = quantizeNote(notes, swungHat.id, 0);
+    assert.ok(Math.abs((kept.find((note) => note.id === swungHat.id)?.swing ?? 1) - swungHat.swing) < 1e-9);
+  });
+
+  it("travels halfway at strength 0.5 and refuses strengths off the range", () => {
+    const half = quantizeNote(notes, swungHat.id, 0.5);
+    const halfSwing = half.find((note) => note.id === swungHat.id)?.swing ?? 1;
+    assert.ok(Math.abs(halfSwing - swungHat.swing * 0.5) < 1e-9);
+    assert.throws(
+      () => quantizeNote(notes, swungHat.id, 1.5),
+      (error: unknown) => error instanceof PianoRollError && error.code === "bad-note",
+    );
+  });
+});
+
+describe("pianoroll — validateNotes", () => {
+  it("answers no problems for the imported roll", () => {
+    for (const plan of [SWUNG_PLAN, STRAIGHT_PLAN]) {
+      const notes = scheduleToNotes(scheduleTake(plan), plan);
+      assert.deepEqual(validateNotes(notes, plan), []);
+    }
+  });
+
+  it("answers the overlap, the duplicate id and the bounds it finds", () => {
+    const overlapping = [keysNote(0, 60), keysNote(2, 60, "2-60")];
+    assert.ok(validateNotes(overlapping, SWUNG_PLAN).some((problem) => problem.includes("overlap")));
+    const doubled = [keysNote(0, 60), { ...keysNote(0, 60), velocity: 0.5 }];
+    assert.ok(validateNotes(doubled, SWUNG_PLAN).some((problem) => problem.includes("twice")));
+    const offWindow = [keysNote(0, PIANOROLL_CONSTANTS.NOTE_MAX + 12, "0-120")];
+    assert.ok(validateNotes(offWindow, SWUNG_PLAN).some((problem) => problem.includes("C2..C6")));
+    const offTake = [{ ...keysNote(0, 60), bar: SWUNG_PLAN.bars + 1, id: "keys-17-0-60" }];
+    assert.ok(validateNotes(offTake, SWUNG_PLAN).some((problem) => problem.includes("outside the take")));
+  });
+});

package/tests/rhythmgrammar.test.ts

@@ -0,0 +1,205 @@
+// # rhythmgrammar.test — honest unit tests for the drum-pattern grammar
+// (velocity glyphs, the eight family tables, swing offsets, seeded fills,
+// accent curves and the half/double-time folding), runnable with the
+// vitest runner:
+//   pnpm test
+// The only randomness is the engine's own mulberry32 driven by fixed seeds;
+// every glyph string is a constant fixture readable by eye.
+import { describe, expect, it } from "vitest";
+import { hashSeed, mulberry32 } from "../harmonyengine.ts";
+import {
+  accentMap,
+  applyAccents,
+  applySwing,
+  cloneGrid,
+  emptyGrid,
+  FAMILIES,
+  FAMILY_NAMES,
+  foldPattern,
+  gridFromSpec,
+  LANES,
+  type LaneName,
+  laneDensity,
+  maybeFill,
+  STEPS,
+  swingOffsets,
+  validateGrid,
+} from "../rhythmgrammar.ts";
+
+/** A spec where every lane not listed stays silent (the documented default). */
+const spec = (overrides: Partial<Record<LaneName, string>>): Record<LaneName, string> =>
+  overrides as Record<LaneName, string>;
+
+/** Sixteen zeroes, the shape of a silent lane. */
+const ZEROS = new Array<number>(STEPS).fill(0);
+
+describe("grid constants and parsing", () => {
+  it("documents eight lanes, eight families and sixteen steps", () => {
+    expect(LANES).toEqual(["kick", "snare", "hat", "openhat", "clap", "perc", "ride", "tom"]);
+    expect(new Set(LANES).size).toBe(8);
+    expect(FAMILY_NAMES).toEqual(["trap", "drill", "house", "dnb", "lofi", "pop", "techno", "ambient"]);
+    expect(new Set(FAMILY_NAMES).size).toBe(8);
+    expect(STEPS).toBe(16);
+  });
+
+  it("parses the documented velocity glyphs", () => {
+    const grid = gridFromSpec(spec({ kick: "Xx:o------------" }));
+    expect(grid.steps).toBe(STEPS);
+    expect(grid.lanes.kick).toEqual([1, 0.85, 0.35, 0.6, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0]);
+  });
+
+  it("defaults missing lanes to a silent sixteen-step row", () => {
+    const grid = gridFromSpec(spec({ hat: "x---------------" }));
+    expect(grid.lanes.hat[0]).toBe(0.85);
+    for (const name of LANES) {
+      if (name === "hat") continue;
+      expect(grid.lanes[name], `lane ${name} defaults silent`).toEqual(ZEROS);
+    }
+    const empty = emptyGrid();
+    expect(empty.steps).toBe(STEPS);
+    for (const name of LANES) expect(empty.lanes[name]).toEqual(ZEROS);
+    expect(validateGrid(empty)).toEqual([]);
+  });
+
+  it("refuses malformed rows outright", () => {
+    expect(() => gridFromSpec(spec({ kick: "X--------------" }))).toThrow(/lane must hold 16 glyphs/);
+    expect(() => gridFromSpec(spec({ kick: "Xq--------------" }))).toThrow(/unknown velocity glyph: q/);
+  });
+});
+
+describe("family tables", () => {
+  it("yields a valid eight-lane grid for every family", () => {
+    for (const family of FAMILY_NAMES) {
+      const grid = FAMILIES[family];
+      expect(grid.steps).toBe(STEPS);
+      for (const name of LANES) {
+        expect(grid.lanes[name].length, `${family}/${name} spans the bar`).toBe(STEPS);
+        for (const v of grid.lanes[name])
+          expect(Number.isFinite(v) && v >= 0 && v <= 1, `${family}/${name} velocity ${v}`).toBe(true);
+      }
+      expect(validateGrid(grid), `${family} validates clean`).toEqual([]);
+      expect(laneDensity(grid, "kick") > 0, `${family} kicks`).toBe(true);
+    }
+  });
+
+  it("drives house and techno four on the floor", () => {
+    for (const family of ["house", "techno"] as const)
+      expect(FAMILIES[family].lanes.kick).toEqual([1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0]);
+    expect(laneDensity(FAMILIES.house, "kick")).toBe(4);
+    expect(laneDensity(emptyGrid(), "tom")).toBe(0);
+  });
+
+  it("clones deeply so mutations never reach the tables", () => {
+    const copy = cloneGrid(FAMILIES.trap);
+    expect(copy).toEqual(FAMILIES.trap);
+    expect(copy.lanes.kick).not.toBe(FAMILIES.trap.lanes.kick);
+    copy.lanes.snare[8] = 0.5;
+    expect(FAMILIES.trap.lanes.snare[8]).toBe(0.85);
+  });
+});
+
+describe("swing", () => {
+  it("stays straight at 0.5 and clamps outside the band", () => {
+    expect(swingOffsets(0.5)).toEqual(ZEROS);
+    expect(swingOffsets(0.4)).toEqual(ZEROS);
+    expect(swingOffsets(0.8)).toEqual(ZEROS);
+    expect(swingOffsets(Number.NaN)).toEqual(ZEROS);
+    expect(swingOffsets(0.625).every(Number.isFinite)).toBe(true);
+  });
+
+  it("shifts the offbeat 8ths by 4r - 2 on division 2", () => {
+    expect(swingOffsets(0.625, 2)).toEqual([0, 0, 0.5, 0, 0, 0, 0.5, 0, 0, 0, 0.5, 0, 0, 0, 0.5, 0]);
+    expect(swingOffsets(0.75, 2)[2]).toBe(1);
+  });
+
+  it("shifts every odd 16th by 2r - 1 on division 4", () => {
+    const offsets = swingOffsets(0.625, 4);
+    expect(offsets.filter((_, step) => step % 2 === 1)).toEqual(new Array(8).fill(0.25));
+    expect(offsets.filter((_, step) => step % 2 === 0)).toEqual(new Array(8).fill(0));
+  });
+
+  it("attaches the offsets without touching the velocities", () => {
+    const swung = applySwing(FAMILIES.house, 0.58, 2);
+    expect(swung.grid).toEqual(FAMILIES.house);
+    expect(swung.grid).not.toBe(FAMILIES.house);
+    expect(swung.offsets).toEqual(swingOffsets(0.58, 2));
+  });
+});
+
+describe("accents", () => {
+  it("peaks every accent map on the downbeats", () => {
+    for (const family of FAMILY_NAMES) {
+      const curve = accentMap(family);
+      expect(curve.length).toBe(STEPS);
+      expect(curve[0], `${family} peaks on the one`).toBe(Math.max(...curve));
+      expect(curve.every(Number.isFinite), `${family} curve stays finite`).toBe(true);
+    }
+  });
+
+  it("writes the documented per-style curves", () => {
+    expect(accentMap("house")).toEqual([
+      1.2, 0.8, 0.95, 0.8, 1.2, 0.8, 0.95, 0.8, 1.2, 0.8, 0.95, 0.8, 1.2, 0.8, 0.95, 0.8,
+    ]);
+    expect(accentMap("trap")).toEqual([
+      1.2, 0.8, 0.95, 0.8, 1.1, 0.8, 0.95, 0.8, 1.2, 0.8, 0.95, 0.8, 1.1, 0.8, 0.95, 0.8,
+    ]);
+    expect(accentMap("ambient")).toEqual([1.05, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1]);
+  });
+
+  it("multiplies the grid by the curve and clamps to the unit band", () => {
+    const accented = applyAccents(FAMILIES.house, "house");
+    expect(accented.lanes.kick, "1.2 clamps back to 1").toEqual([1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0]);
+    expect(accented.lanes.hat[2]).toBeCloseTo(0.57, 12);
+    expect(accented.lanes.snare).toEqual(ZEROS);
+  });
+});
+
+describe("seeded fills", () => {
+  const filled = (seed: string) => maybeFill(FAMILIES.trap, mulberry32(hashSeed(seed)));
+
+  it("passes the grid through untouched when the rng draws over the chance", () => {
+    const untouched = filled("alpha"); // first draw 0.500 >= 0.25
+    expect(untouched).toEqual(FAMILIES.trap);
+    expect(untouched.lanes.snare).toEqual(FAMILIES.trap.lanes.snare);
+    expect(untouched.lanes.hat).toEqual(FAMILIES.trap.lanes.hat);
+  });
+
+  it("replays the same fill for the same seed", () => {
+    expect(filled("c")).toEqual(filled("c"));
+    expect(filled("l")).toEqual(filled("l"));
+  });
+
+  it("cascades the snare over the last four steps and halves the hats", () => {
+    const grid = filled("l"); // second draw 0.910 -> no tom tail
+    expect(grid.lanes.snare.slice(12)).toEqual([0.85, 0.6, 0.85, 1]);
+    expect(grid.lanes.hat.slice(12)).toEqual([0.425, 0.3, 0.5, 0.5]);
+    expect(grid.lanes.tom.slice(14)).toEqual([0, 0]);
+  });
+
+  it("lands different fills for different seeds", () => {
+    const withTom = filled("c"); // second draw 0.372 -> tom tail fires
+    const withoutTom = filled("l");
+    expect(withTom.lanes.tom.slice(14)).toEqual([0.85, 1]);
+    expect(withTom).not.toEqual(withoutTom);
+    expect(filled("c")).not.toEqual(filled("alpha"));
+  });
+});
+
+describe("half/double-time folding", () => {
+  const marker = gridFromSpec(spec({ kick: "X-------x-------", hat: "XxXxXxXxXxXxXxXx" }));
+
+  it("folds half-time inside one bar: even steps carry the phrase, odd steps and the back half drop", () => {
+    const folded = foldPattern(marker, 0.5);
+    expect(folded.steps).toBe(STEPS);
+    for (const name of LANES) for (let step = 1; step < STEPS; step += 2) expect(folded.lanes[name][step]).toBe(0);
+    expect(folded.lanes.kick).toEqual([1, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0]);
+    expect(folded.lanes.kick.includes(0.85)).toBe(false);
+    expect(folded.lanes.hat).toEqual([1, 0, 0.85, 0, 1, 0, 0.85, 0, 1, 0, 0.85, 0, 1, 0, 0.85, 0]);
+  });
+
+  it("loops the phrase twice per bar in double time", () => {
+    const folded = foldPattern(marker, 2);
+    expect(folded.lanes.kick).toEqual([1, 0, 0, 0, 0.85, 0, 0, 0, 1, 0, 0, 0, 0.85, 0, 0, 0]);
+    expect(folded.lanes.hat).toEqual(new Array(STEPS).fill(1));
+  });
+});