@wenathlan/debonair 2.0.94 → 2.0.118

package/tests/midiwriter.test.ts

@@ -0,0 +1,183 @@
+// # midiwriter.test — the SMF writer contract: the MThd/MTrk magic and the
+// header fields, the VLQ round trip on the boundary values, the tempo meta
+// as microseconds per quarter, the balanced on/off pairs validateMidi
+// proves, the drums on the GM percussion channel 9, the schedule-to-tracks
+// conservation and the determinism of the bytes.
+import assert from "node:assert/strict";
+import { describe, it } from "vitest";
+import { planTake } from "../arranger.ts";
+import {
+  buildTracksFromSchedule,
+  decodeVlq,
+  encodeVlq,
+  MIDI_CONSTANTS,
+  MidiError,
+  secondsToTicks,
+  ticksToSeconds,
+  VLQ_MAX,
+  validateMidi,
+  writeMidi,
+} from "../midiwriter.ts";
+import { scheduleTake } from "../takeevents.ts";
+
+/** Reads a big-endian u16 out of the bytes (SMF is big-endian, the opposite of wav). */
+const u16be = (bytes: Uint8Array, offset: number): number => (bytes[offset] << 8) | bytes[offset + 1];
+
+/** Reads a big-endian u32 out of the bytes. */
+const u32be = (bytes: Uint8Array, offset: number): number =>
+  ((bytes[offset] << 24) | (bytes[offset + 1] << 16) | (bytes[offset + 2] << 8) | bytes[offset + 3]) >>> 0;
+
+describe("midiwriter — vlq", () => {
+  it("round trips the boundary values", () => {
+    for (const value of [0, 1, 0x7f, 0x80, 0xff, 0x3fff, 0x4000, 0x1fffff, 0x200000, VLQ_MAX]) {
+      const encoded = encodeVlq(value);
+      const decoded = decodeVlq(encoded);
+      assert.equal(decoded.value, value);
+      assert.equal(decoded.next, encoded.length);
+    }
+  });
+
+  it("encodes the documented byte shapes", () => {
+    assert.deepEqual([...encodeVlq(0)], [0x00]);
+    assert.deepEqual([...encodeVlq(127)], [0x7f]);
+    assert.deepEqual([...encodeVlq(128)], [0x81, 0x00]);
+    assert.deepEqual([...encodeVlq(0x200000)], [0x81, 0x80, 0x80, 0x00]);
+  });
+
+  it("refuses overflow and truncated streams", () => {
+    assert.throws(
+      () => encodeVlq(VLQ_MAX + 1),
+      (error: unknown) => error instanceof MidiError && error.code === "vlq-overflow",
+    );
+    assert.throws(
+      () => encodeVlq(-1),
+      (error: unknown) => error instanceof MidiError && error.code === "vlq-overflow",
+    );
+    assert.throws(
+      () => decodeVlq(new Uint8Array([0x80])),
+      (error: unknown) => error instanceof MidiError && error.code === "vlq-truncated",
+    );
+  });
+});
+
+describe("midiwriter — time math", () => {
+  it("maps seconds to ticks and back exactly", () => {
+    assert.equal(secondsToTicks(1, 120, 480), 960);
+    assert.equal(ticksToSeconds(960, 120, 480), 1);
+    for (const bpm of [90, 124, 174]) {
+      for (const seconds of [0, 0.5, 1.75, 30]) {
+        const ticks = secondsToTicks(seconds, bpm);
+        assert.equal(secondsToTicks(ticksToSeconds(ticks, bpm), bpm), ticks);
+      }
+    }
+  });
+
+  it("refuses impossible tempo inputs", () => {
+    assert.throws(
+      () => secondsToTicks(1, 0),
+      (error: unknown) => error instanceof MidiError && error.code === "bad-bpm",
+    );
+    assert.throws(
+      () => ticksToSeconds(1, 120, 0),
+      (error: unknown) => error instanceof MidiError && error.code === "bad-ppq",
+    );
+  });
+});
+
+describe("midiwriter — writeMidi", () => {
+  const plan = planTake({ prompt: "midnight techno, dark sub bass", seed: "k4-midi" });
+  const schedule = scheduleTake(plan);
+  const tracks = buildTracksFromSchedule(schedule, plan, plan.bpm);
+  const bytes = writeMidi(tracks, MIDI_CONSTANTS.ppqDefault, plan.bpm);
+
+  it("opens with MThd and declares format 1 with one track per role plus the tempo map", () => {
+    assert.equal(String.fromCharCode(...bytes.subarray(0, 4)), "MThd");
+    assert.equal(u32be(bytes, 4), 6);
+    assert.equal(u16be(bytes, 8), 1);
+    assert.equal(u16be(bytes, 10), 5);
+    assert.equal(u16be(bytes, 12), MIDI_CONSTANTS.ppqDefault);
+  });
+
+  it("opens every chunk with MTrk and walks them cleanly", () => {
+    let cursor = 14;
+    let count = 0;
+    while (cursor < bytes.length) {
+      assert.equal(String.fromCharCode(...bytes.subarray(cursor, cursor + 4)), "MTrk");
+      count += 1;
+      cursor += 8 + u32be(bytes, cursor + 4);
+    }
+    assert.equal(count, 5);
+  });
+
+  it("writes the tempo meta on track 0 as microseconds per quarter", () => {
+    const tempoAt = 14 + 8; // the first MTrk body
+    assert.equal(bytes[tempoAt], 0x00); // delta
+    assert.equal(bytes[tempoAt + 1], 0xff);
+    assert.equal(bytes[tempoAt + 2], 0x51);
+    assert.equal(bytes[tempoAt + 3], 0x03);
+    const us = (bytes[tempoAt + 4] << 16) | (bytes[tempoAt + 5] << 8) | bytes[tempoAt + 6];
+    assert.equal(us, Math.round(60e6 / plan.bpm)); // microseconds per quarter: 60e6 / bpm
+    const reference = writeMidi([{ name: "", channel: 0, program: -1, notes: [] }], 480, 120);
+    assert.equal((reference[26] << 16) | (reference[27] << 8) | reference[28], 500000); // 60e6 / 120 = 0x07a120
+  });
+
+  it("keeps the drums on the GM percussion channel 9", () => {
+    const drums = tracks.find((track) => track.name.endsWith("-drums"));
+    assert.ok(drums);
+    assert.equal(drums.channel, 9);
+    const drumsAt = 14 + 19; // the drums chunk rides right after the tempo map chunk (8 + 11 bytes)
+    const body = bytes.subarray(drumsAt + 8, drumsAt + 8 + u32be(bytes, drumsAt + 4));
+    assert.ok(body.includes(0x99)); // note on, channel 9
+    assert.ok(body.includes(0xc9)); // program change, channel 9
+  });
+
+  it("balances every note on with exactly one note off", () => {
+    assert.deepEqual(validateMidi(tracks), []);
+  });
+
+  it("is deterministic — the same schedule renders the same bytes", () => {
+    const again = writeMidi(
+      buildTracksFromSchedule(scheduleTake(plan), plan, plan.bpm),
+      MIDI_CONSTANTS.ppqDefault,
+      plan.bpm,
+    );
+    assert.deepEqual(again, bytes);
+  });
+
+  it("conserves the schedule into the tracks", () => {
+    const total = tracks.reduce((sum, track) => sum + track.notes.length, 0);
+    assert.equal(total, schedule.events.length);
+    for (const track of tracks) {
+      const role = track.name.slice(plan.id.length + 1);
+      assert.equal(track.notes.length, schedule.perRole[role]);
+    }
+  });
+
+  it("answers machine codes for broken tracks and options", () => {
+    assert.throws(
+      () => writeMidi(tracks, 0, plan.bpm),
+      (error: unknown) => error instanceof MidiError && error.code === "bad-ppq",
+    );
+    assert.throws(
+      () => writeMidi(tracks, 480, 0),
+      (error: unknown) => error instanceof MidiError && error.code === "bad-bpm",
+    );
+    const louder = tracks.map((track, index) =>
+      index === 0
+        ? { ...track, notes: track.notes.map((note, order) => (order === 0 ? { ...note, velocity: 300 } : note)) }
+        : track,
+    );
+    assert.ok(validateMidi(louder).some((problem) => problem.code === "bad-velocity"));
+    const gated = tracks.map((track, index) =>
+      index === 0
+        ? { ...track, notes: track.notes.map((note, order) => (order === 0 ? { ...note, duration: 0 } : note)) }
+        : track,
+    );
+    assert.ok(validateMidi(gated).some((problem) => problem.code === "unbalanced-pairs"));
+    assert.ok(
+      validateMidi([{ name: "x", channel: 16, program: 0, notes: [] }]).some(
+        (problem) => problem.code === "bad-channel",
+      ),
+    );
+  });
+});

package/tests/motionpref.test.ts

@@ -0,0 +1,82 @@
+// # motionpref.test — the in-session reduce-motion switch the settings page
+// drives: the document flag (data-motion="reduced") and the session note ride
+// injectable stubs, so the honest toggle is pinned without a browser. The
+// stylesheet guards answer to the attribute; this test pins the attribute.
+import assert from "node:assert/strict";
+import { describe, it } from "vitest";
+import {
+  MOTION_PREF_KEY,
+  type MotionRoot,
+  memoryMotionStorage,
+  reduceMotionApplied,
+  reduceMotionStored,
+  setReduceMotion,
+  toggleReduceMotion,
+} from "../motionpref.ts";
+
+/** A root stub that answers like the <html> element. */
+function stubRoot(): MotionRoot & { attrs: Map<string, string> } {
+  const attrs = new Map<string, string>();
+  return {
+    attrs,
+    getAttribute: (name) => attrs.get(name) ?? null,
+    setAttribute: (name, value) => {
+      attrs.set(name, value);
+    },
+    removeAttribute: (name) => {
+      attrs.delete(name);
+    },
+  };
+}
+
+describe("motionpref", () => {
+  it("applies and clears the document flag with the session note", () => {
+    const root = stubRoot();
+    const storage = memoryMotionStorage();
+    setReduceMotion(true, storage, root);
+    assert.equal(reduceMotionApplied(root), true);
+    assert.equal(reduceMotionStored(storage), true);
+    assert.equal(root.attrs.get("data-motion"), "reduced");
+    assert.equal(storage.getItem(MOTION_PREF_KEY), "1");
+
+    setReduceMotion(false, storage, root);
+    assert.equal(reduceMotionApplied(root), false);
+    assert.equal(reduceMotionStored(storage), false);
+    assert.equal(root.attrs.has("data-motion"), false);
+    assert.equal(storage.getItem(MOTION_PREF_KEY), null);
+  });
+
+  it("toggles from the current document state", () => {
+    const root = stubRoot();
+    const storage = memoryMotionStorage();
+    assert.equal(toggleReduceMotion(storage, root), true);
+    assert.equal(reduceMotionApplied(root), true);
+    assert.equal(toggleReduceMotion(storage, root), false);
+    assert.equal(reduceMotionApplied(root), false);
+  });
+
+  it("degrades when the session storage refuses the write", () => {
+    const root = stubRoot();
+    const frozen = memoryMotionStorage();
+    const broken = {
+      getItem: () => null,
+      setItem: () => {
+        throw new Error("quota");
+      },
+      removeItem: () => {
+        throw new Error("quota");
+      },
+    };
+    setReduceMotion(true, broken as typeof frozen, root);
+    // the document flag still holds — the interface stays honest for this tab
+    assert.equal(reduceMotionApplied(root), true);
+    assert.equal(reduceMotionStored(frozen), false);
+  });
+
+  it("reads an untouched document and storage as motion allowed", () => {
+    const root = stubRoot();
+    const storage = memoryMotionStorage();
+    assert.equal(reduceMotionApplied(root), false);
+    assert.equal(reduceMotionStored(storage), false);
+  });
+});

package/tests/musictheory.test.ts

@@ -0,0 +1,231 @@
+// # musictheory.test — honest unit tests for the theory kernel (scale table,
+// intervals, the chord vocabulary over all twelve roots, roman-numeral
+// parsing, voice-leading helpers), runnable with the vitest runner:
+//   pnpm test
+// Every fixture is a constant table — no randomness anywhere.
+import { describe, expect, it } from "vitest";
+import {
+  CHORD_SHAPES,
+  CHORD_SUFFIX,
+  chordNotes,
+  chordPcs,
+  chordSymbol,
+  commonTones,
+  degreeToPc,
+  diatonicTriad,
+  INTERVAL_NAMES,
+  intervalBetween,
+  intervalName,
+  makeChord,
+  nearestInversion,
+  noteName,
+  noteToPc,
+  parseChord,
+  parseRoman,
+  romanOf,
+  SCALE_NAMES,
+  SCALE_STEPS,
+  scalePcs,
+  transposePc,
+  voiceLeadDistance,
+} from "../musictheory.ts";
+
+const C = { tonic: 0, mode: "major" } as const;
+const Am = { tonic: 9, mode: "aeolian" } as const;
+
+/** Asserts an optional engine value landed and returns it (the non-null guard the suite pins). */
+function landed<T>(value: T | null | undefined, label: string): T {
+  expect(value, label).toBeTruthy();
+  return value as T;
+}
+
+describe("scale table", () => {
+  it("carries the thirteen documented scales", () => {
+    expect(SCALE_NAMES.length).toBe(13);
+    for (const name of SCALE_NAMES) {
+      const steps = SCALE_STEPS[name];
+      expect(steps[0], `${name} starts on the tonic`).toBe(0);
+      steps.forEach((step, i) => {
+        expect(i === 0 || step > steps[i - 1], `${name} ascends strictly`).toBe(true);
+      });
+      expect(steps[steps.length - 1] <= 11, `${name} stays inside the octave`).toBe(true);
+    }
+    expect(SCALE_STEPS.major).toEqual([0, 2, 4, 5, 7, 9, 11]);
+    expect(SCALE_STEPS["pentatonic-major"].length).toBe(5);
+    expect(SCALE_STEPS.blues.length).toBe(6);
+  });
+
+  it("answers relative keys with the same pitch classes", () => {
+    expect(scalePcs(C)).toEqual([0, 2, 4, 5, 7, 9, 11]);
+    expect([...scalePcs(Am)].sort((a, b) => a - b)).toEqual(scalePcs(C));
+    expect(scalePcs({ tonic: 0, mode: "phrygian" }).includes(1), "phrygian carries the flat second").toBe(true);
+  });
+
+  it("resolves degrees and accidentals", () => {
+    expect(degreeToPc(C, 3)).toBe(4);
+    expect(degreeToPc(C, 3, -1), "bIII of C major").toBe(3);
+    expect(degreeToPc(C, 4, 1), "#IV of C major").toBe(6);
+    expect(transposePc(11, 2)).toBe(1);
+    expect(transposePc(0, -1)).toBe(11);
+  });
+});
+
+describe("note names and intervals", () => {
+  it("spells all twelve classes both ways", () => {
+    for (let pc = 0; pc < 12; pc++) {
+      expect(noteToPc(noteName(pc))).toBe(pc);
+      expect(noteToPc(noteName(pc, true))).toBe(pc);
+    }
+    expect(noteToPc("Eb")).toBe(3);
+    expect(noteToPc("H")).toBeNull();
+    expect(noteToPc("")).toBeNull();
+  });
+
+  it("names the twelve intervals and reads them between classes", () => {
+    expect(INTERVAL_NAMES.length).toBe(12);
+    expect(intervalName(0)).toBe("unison");
+    expect(intervalName(6)).toBe("tritone");
+    expect(intervalName(7)).toBe("perfect fifth");
+    expect(intervalName(11)).toBe("major seventh");
+    expect(intervalBetween(0, 4)).toBe("major third");
+    expect(intervalBetween(4, 0)).toBe("minor sixth");
+  });
+});
+
+describe("chord vocabulary", () => {
+  it("keeps every shape ascending from the root", () => {
+    for (const [quality, shape] of Object.entries(CHORD_SHAPES)) {
+      expect(shape[0], `${quality} roots on 0`).toBe(0);
+      shape.forEach((step, i) => {
+        expect(i === 0 || step > shape[i - 1], `${quality} ascends`).toBe(true);
+      });
+      expect(shape[shape.length - 1] <= 14, `${quality} stays inside two octaves`).toBe(true);
+    }
+    for (const quality of Object.keys(CHORD_SUFFIX) as (keyof typeof CHORD_SUFFIX)[])
+      expect(CHORD_SHAPES[quality], `${quality} has a shape`).toBeTruthy();
+    for (const quality of Object.keys(CHORD_SHAPES))
+      expect(typeof CHORD_SUFFIX[quality as keyof typeof CHORD_SUFFIX]).toBe("string");
+  });
+
+  it("spells, stacks and voices chords", () => {
+    const cmaj7 = landed(parseChord("Cmaj7"), "Cmaj7 parses");
+    expect(chordPcs(cmaj7)).toEqual([0, 4, 7, 11]);
+    expect(chordNotes(cmaj7)).toEqual([60, 64, 67, 71]);
+    const slash = landed(parseChord("Am7/G"), "Am7/G parses");
+    expect(slash).toBeTruthy();
+    expect(chordPcs(slash), "the slash bass comes first").toEqual([7, 9, 0, 4, 7]);
+    expect(chordSymbol(slash)).toBe("Am7/G");
+  });
+
+  it("builds every quality over all twelve roots and round-trips the symbol", () => {
+    const qualities = ["maj", "min7", "dim", "sus4", "maj9"] as const;
+    for (let root = 0; root < 12; root++) {
+      for (const quality of qualities) {
+        const chord = makeChord(root, quality);
+        expect(chord.root).toBe(root);
+        const back = landed(parseChord(chordSymbol(chord)), `symbol ${chordSymbol(chord)} parses`);
+        expect(back.root).toBe(root);
+        expect(back.quality).toBe(quality);
+      }
+    }
+  });
+
+  it("parses the lead-sheet tokens and refuses the malformed ones", () => {
+    expect(parseChord("F#m7b5")?.quality).toBe("halfdim");
+    expect(parseChord("Db9")?.root).toBe(1);
+    expect(parseChord("C/E")?.bass).toBe(4);
+    expect(parseChord("Csus4")?.quality).toBe("sus4");
+    expect(parseChord("H")).toBeNull();
+    expect(parseChord("Cq")).toBeNull();
+    expect(parseChord("C/")).toBeNull();
+  });
+});
+
+describe("roman numerals", () => {
+  it("parses the documented table in C major", () => {
+    const symbolOf = (token: string) => chordSymbol(landed(parseRoman(token, C), `${token} parses in C`));
+    expect(symbolOf("I")).toBe("C");
+    expect(symbolOf("IV")).toBe("F");
+    expect(symbolOf("V7")).toBe("G7");
+    expect(symbolOf("vi")).toBe("Am");
+    expect(symbolOf("viio")).toBe("Bdim");
+    expect(symbolOf("bIII")).toBe("D#");
+    expect(symbolOf("#iv")).toBe("F#m");
+    expect(symbolOf("v7")).toBe("Gm7");
+    expect(symbolOf("VImaj7")).toBe("Amaj7");
+    expect(symbolOf("ii")).toBe("Dm");
+  });
+
+  it("parses against the key's own scale (A aeolian)", () => {
+    const symbolOf = (token: string) => chordSymbol(landed(parseRoman(token, Am), `${token} parses in Am`));
+    expect(symbolOf("i")).toBe("Am");
+    expect(symbolOf("VII")).toBe("G");
+    expect(symbolOf("III")).toBe("C");
+    expect(symbolOf("iv7")).toBe("Dm7");
+    expect(symbolOf("V"), "the upper case overrides the mode's minor fifth").toBe("E");
+    expect(parseRoman("IX", C)).toBeNull();
+    expect(parseRoman("x", C)).toBeNull();
+    expect(parseRoman("IVmaj", C)).toBeNull();
+  });
+
+  it("reads the diatonic triads of the seven-note scales", () => {
+    expect([1, 2, 3, 4, 5, 6, 7].map((d) => diatonicTriad(C, d)?.quality)).toEqual([
+      "maj",
+      "min",
+      "min",
+      "maj",
+      "maj",
+      "min",
+      "dim",
+    ]);
+    expect([1, 2, 3, 4, 5, 6, 7].map((d) => diatonicTriad(Am, d)?.quality)).toEqual([
+      "min",
+      "dim",
+      "maj",
+      "min",
+      "min",
+      "maj",
+      "maj",
+    ]);
+    expect(diatonicTriad({ tonic: 0, mode: "blues" }, 1), "short scales carry no triads").toBeNull();
+  });
+
+  it("serialises numerals back from chords (romanOf round-trips)", () => {
+    for (const [key, tokens] of [
+      [C, ["I", "ii", "iii", "IV", "V", "vi", "viio", "V7"]],
+      [Am, ["i", "iio", "III", "iv", "v", "VI", "VII", "V7"]],
+    ] as const) {
+      for (const token of tokens) {
+        const chord = landed(parseRoman(token, key), `${token} parses`);
+        const numeral = landed(romanOf(chord, key), `${token} re-annotates`);
+        const back = landed(parseRoman(numeral, key), `${numeral} parses back`);
+        expect(back.root, `${token} -> ${numeral} keeps the root`).toBe(chord.root);
+        expect(back.quality, `${token} -> ${numeral} keeps the quality`).toBe(chord.quality);
+      }
+    }
+  });
+});
+
+describe("voice-leading helpers", () => {
+  it("counts common tones and nearest movement", () => {
+    const c = chordPcs(landed(parseChord("C"), "C parses"));
+    const am = chordPcs(landed(parseChord("Am"), "Am parses"));
+    expect(commonTones(c, am)).toBe(2);
+    expect(voiceLeadDistance(c, am), "G->A and B->A cost two semitones").toBe(2);
+    expect(voiceLeadDistance(c, c)).toBe(0);
+    expect(voiceLeadDistance(c, chordPcs(landed(parseChord("F#dim7"), "F#dim7 parses")))).toBeGreaterThan(0);
+  });
+
+  it("picks the inversion whose bass sits nearest the reference", () => {
+    const c = landed(parseChord("C"), "C parses");
+    const fromG = nearestInversion(c, 55);
+    expect(fromG.inversion, "G sits a fifth below middle C").toBe(2);
+    expect(fromG.notes).toEqual([55, 60, 64]);
+    const fromC = nearestInversion(c, 60);
+    expect(fromC.inversion).toBe(0);
+    expect(fromC.notes).toEqual([60, 64, 67]);
+    const fromE = nearestInversion(c, 52);
+    expect(fromE.inversion).toBe(1);
+    expect(fromE.notes, "E G C stacks ascending from the reference").toEqual([52, 55, 60]);
+  });
+});

package/tests/onboardingstate.test.ts

@@ -0,0 +1,68 @@
+// # onboardingstate.test — the pure contract of the seen flags: the host
+//   validation of the platform base (https only, public hosts only, mapped
+//   ipv6 normalized) and the seen-wins stage merge the accessor and the
+//   pages share. runnable with vitest: pnpm vitest run tests/onboardingstate.test.ts
+import assert from "node:assert/strict";
+import { describe, it } from "vitest";
+import { hostallowed, mergeStage } from "../onboardingstate.ts";
+
+describe("onboarding state", () => {
+  it("accepts public https bases", () => {
+    assert.equal(hostallowed("https://gateway.wenathlan.dev"), true);
+    assert.equal(hostallowed("https://gateway.wenathlan.dev/"), true);
+    assert.equal(hostallowed("https://debonair.example.com:8443"), true);
+  });
+
+  it("refuses plaintext, localhost, loopback and every private or reserved range", () => {
+    const refused = [
+      "http://gateway.wenathlan.dev",
+      "https://localhost",
+      "https://localhost:8787",
+      "https://app.localhost",
+      "https://box.local",
+      "https://service.internal",
+      "https://studio.home.arpa",
+      "https://127.0.0.1",
+      "https://0.0.0.0",
+      "https://10.0.0.9",
+      "https://172.16.0.1",
+      "https://172.31.255.255",
+      "https://192.168.1.4",
+      "https://169.254.10.10",
+      "https://100.64.0.1",
+      "https://192.0.2.7",
+      "https://198.51.100.7",
+      "https://203.0.113.9",
+      "https://198.18.0.4",
+      "https://224.0.0.1",
+      "https://[::1]",
+      "https://[::]",
+      "https://[::ffff:127.0.0.1]",
+      "https://[fd00::1]",
+      "https://[fe80::1]",
+      "not a url",
+      "",
+    ];
+    for (const base of refused) assert.equal(hostallowed(base), false, base);
+  });
+
+  it("normalizes the mapped ipv6 spelling the url parser produces", () => {
+    // `https://[::ffff:8.8.8.8]` arrives at the validator as the hex form
+    assert.equal(hostallowed("https://[::ffff:0808:0808]"), true);
+    assert.equal(hostallowed("https://[::ffff:7f00:1]"), false);
+  });
+
+  it("merges stages seen-wins — a stage never unsees", () => {
+    const fresh = { introseen: false, onboardingseen: false };
+    assert.deepEqual(mergeStage(fresh, "intro"), { introseen: true, onboardingseen: false });
+    assert.deepEqual(mergeStage(fresh, "onboarding"), { introseen: true, onboardingseen: true });
+    const half = { introseen: true, onboardingseen: false };
+    assert.deepEqual(mergeStage(half, "onboarding"), { introseen: true, onboardingseen: true });
+  });
+
+  it("never mutates the state it merges", () => {
+    const state = { introseen: false, onboardingseen: false };
+    mergeStage(state, "onboarding");
+    assert.deepEqual(state, { introseen: false, onboardingseen: false });
+  });
+});