@wenathlan/debonair 2.0.94 → 2.0.117

package/docs/planning.v2.28-completo.md

@@ -0,0 +1,69 @@
+# planning.v2.28-completo — the ladder to the complete debonair app
+
+> owner directive: make the app COMPLETE (suno.com generation x FL studio desk),
+> house tree, no src/, no ui/ folder, doctrine of #oficial 4 + DESIGN_MAP v2.
+> this plan is the single source of truth for the wave that closes the gaps
+> listed in DEBONAI-RULEMAP.md section 7 and DEBONAI-VERSIONS.md backlog.
+> step ladder generated from the live inventory: docs/planning.ladder.md
+
+## where the app stands (inherited, verified this session)
+
+- native app at `debonair/debonair/` (house tree: pure ts engines at the root,
+  Sol/ theme, docs/, tests/). 28 engines + kathesis b2 (spectrum, fingerprint,
+  analyze, vocalsynth). 261 vitest cases green, tsc 0, biome 0. commit 504b8ae
+  on branch kathesis/b2-wave, pushed.
+- served in the sandbox by the next.js gateway (single launcher page, iframe of
+  the built bundle under public/debonair/). nothing is duplicated in the gateway.
+- auth: device flow token persisted (iakadion). pushes land on
+  github.com/wenathlan/devthink.
+
+## gaps this wave closes (the definition of "complete")
+
+| gap (inherited) | wave | delivery |
+|---|---|---|
+| daw editing is cosmetic (algebra exists, ui does not edit) | K3 | timeline editor in seconds: move (drag+snap), trim, split, duplicate, delete, clip selection; piano roll editor over the scheduled notes with add/remove/move/resize/quantize; honest re-schedule through takeevents + audioengine; aria + keyboard paths |
+| no wav / midi / stems writers | K4 | wavwriter.ts (16/24/32f encoder, riff-correct), midiwriter.ts (smf format 1, vlq, tempo meta), stems.ts (per-role stem plans + manifest schema v1); export actions in the studio desk |
+| no live visualization (analyser to canvas) | K5 | spectrum scope + waveform overview wired to the real analyser tap; playhead clock; reduced-motion guard |
+| no server persistence (RenderJob idle) | K6 | gateway api projects (list/upsert/delete) on sqlite via prisma; cloudsync.ts engine (seam: fetch first, sessionStorage fallback, 2.5s timeout like onboardingstate); settings page shows sync state honestly |
+| competitors dissected but not written down | K1 | docs/competitor-dissection.md from the five clones in allan/temp (libsonare, pulsegridstudio, magenta-js, acestep.cpp, heartlib) |
+| planning ladder + version ladder | K2 | this file + docs/planning.ladder.md (900+ steps from the live inventory) |
+
+## waves (task ids continue the worklog ladder)
+
+- K1 — competitor dissection (read-only on allan/temp; writes docs/).
+- K2 — planning: this document + generated ladder.
+- K3 — studio daw editing (pianoroll.ts engine + Sol/studio/timeline + pianoroll ui + tests).
+- K4 — writers: wavwriter.ts, midiwriter.ts, stems.ts + contract tests.
+- K5 — live viz (spectrum scope, waveform overview, clock) on the real analyser.
+- K6 — gateway persistence (api + cloudsync.ts engine + settings surface).
+- K7 — gates: vitest full suite, tsc strict, biome zero; vite build; sync
+  public/debonair; commit as iakadion on kathesis/b3-wave; fetch before push.
+- K8 — browser verification of the served app (agent-browser) + worklog close.
+
+## doctrine invariants every wave must keep
+
+1. engines are pure ts at the root: no DOM, no AudioContext, no storage;
+   tables first, orchestrator last, ~300 correlated logics per file, JSDoc on
+   every export, typed results or error classes with machine codes.
+2. determinism: same prompt + same seed = same take; mulberry32(hashSeed(fnv-1a))
+   is the only rng; editors (pianoroll, timeline) are deterministic algebras.
+3. sol.css is the single design source; windows accent #4cc2ff only in chrome
+   focus, amber #d9962e only in brand/cta; zero emoji icons (lucide only);
+   zero pills; reduced-motion guards; solcss.test.ts must stay green.
+4. ui speaks english, lowercase chrome voice; mono tabular for bpm/key/lufs.
+5. one audible transport: playerbus; studio hushes the bus on mount.
+6. no touch on sibling apps (devthink, cadria, getry, vault, saddle...).
+   getry/vault integration stays an adapter seam, never reimplemented.
+7. gates before any push: biome 0, tsc 0, vitest green. commits as iakadion.
+8. honest ui: no fake metrics, no invented reviews; export is real (wav/midi
+   download of rendered audio), sync states read real endpoints with timeouts.
+
+## acceptance criteria (the wave is done when)
+
+- [ ] all six gaps above closed with green gates.
+- [ ] vitest suite green with the new engine contract tests.
+- [ ] served app (gateway iframe) verified in a real browser: generate a take,
+      open the desk, edit a clip, edit a note, export wav + midi + stems,
+      see the spectrum move, save to cloud, reload, find the take.
+- [ ] worklog carries every task id; version ladder updated (v2.28/2.29/2.30
+      delivered; v2.31 speechalign recording and v3.0 render queue remain).

package/docs/planning.versions.2.0.97-3.0.md

@@ -0,0 +1,48 @@
+# planning.versions — the 2.0.97 → 3.0 ladder of debonair
+
+> the document the previous operation died creating (session corte at L2485-2495 of
+> the context corpus). the ladder runs in houses of ~200-300: each house closes a
+> capability block, ships green (biome 0/0 · tsc 0 · vitest green) and bumps the
+> lockstep version. tree wins; the engine is the debonair root; the family imports
+> the published `@wenathlan/debonair` library — never a path, never a bundle.
+
+## where the house stands (verified 2026-10-12)
+
+- `667c20a` head · katexis b1 + sol v2 trylle foundation · 240 tests green
+- wave b2 (kathesis) landed in this operation: `spectrum.ts`, `fingerprint.ts`,
+  `analyze.ts`, `vocalsynth.ts` + 4 suites → **261 tests green** (26 files)
+
+## the ladder
+
+### house 2.0.97 → 2.0.150 — the kathesis analysis core (this wave, b2)
+- [x] spectrum kernel (fft · hann · chroma · kk correlation)
+- [x] fingerprint identity (constellation · landmarks · db)
+- [x] analyze pipeline (flux tempo · octave law · key · lufs · structure · report.schema v1)
+- [x] formant voice (vowel table · seeded vibrato · syllable grid · level law)
+- [x] enginemap honest refresh
+- [ ] `report.schema.ts` — the json/txt formatters the corpus docs 12/26 prescribe
+- [ ] `restage.ts` — the reference→analysis→plan loop (doc 14→16): a real track's
+      report feeds the arranger so the take follows the reference structure
+
+### house 2.0.150 → 2.0.200 — the daw body
+- [ ] timeline editing for real: drag/split/trim wired to `timelinemodel` on the studio page
+- [ ] piano roll page (`#oficial4` APP-0491..0735: Onboarding/Login/Mixer/Timeline/PianoRoll/Library/Master/Settings)
+- [ ] wav/midi writers (export seam, `<50MB` validation before export)
+- [ ] speechalign → vocal recording with ducking (the mic leg)
+
+### house 2.0.200 → 2.1.0 — the ai acoustics seam
+- [ ] onnxruntime-node seat for the foundation embeddings (clap/beats, int8)
+- [ ] fpcalc/olaf binary orchestration via the saddle contract (node executes, binaries in `tools/bin/`)
+- [ ] whisper.cpp transcription of the vocal stem → the lyricist reads, "A SONORIDADE É INTOCÁVEL"
+- [ ] fingerprint dedup on every render job before the library accepts it
+
+### house 2.1.0 → 3.0 — the family contract
+- [ ] publish `@wenathlan/debonair` (npm/ghcr) — the engine leaves the house
+- [ ] devthink music/musicstudio imports the published engine (no duplication)
+- [ ] cadria/getry/vault consume the audio primitives through the same library
+- [ ] 44.1k/48k master spec locked: −14 lufs streaming · −1 dbtp · anti-nan · pre-export validation
+
+## the laws this ladder obeys
+1. tree wins · 2. one domain per file ≤300 lines · 3. tables at the top, orchestrator last
+4. seeded determinism in everything generated · 5. zero hardcode, zero consumer data in the engine
+6. gates green before any bump · 7. commits as iakadion · 8. actions by tag, never sha

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wenathlan/debonair",
-  "version": "2.0.94",
+  "version": "2.0.117",
   "repository": {
     "type": "git",
     "url": "https://github.com/wenathlan/devthink"
@@ -17,6 +17,24 @@
     "static-site"
   ],
   "license": "GPL-3.0-only",
+  "engines": {
+    "bare": "^1.18.0",
+    "bun": "^1.4.2",
+    "chrome": "^16.0.912",
+    "cnpm": "^9.4.0",
+    "corepack": "^0.35.0",
+    "deno": "^2.9.5",
+    "ecmascript": "^5.0.0",
+    "firefox": ">=0.8.0",
+    "iojs": "^1.0.0",
+    "node": "^26.8.2",
+    "npm": "^12.1.0",
+    "pnpm": "^12.6.0",
+    "teleport": ">=0.2.0",
+    "typescript": "^5.8.0",
+    "vscode": "^1.118.0",
+    "yarn": "^4.17.1"
+  },
   "files": [
     "README.md",
     "docs",
@@ -38,9 +56,14 @@
     "start": "vite preview --host",
     "preview": "vite preview --host",
     "check": "tsc --noEmit",
+    "typecheck": "tsc --noEmit",
+    "restore:entry": "node -e \"const{readFileSync}=require('node:fs');const{execSync}=require('node:child_process');const face=/script[^>]*App\\\\.tsx/;const cdn=/fonts\\\\.googleapis\\\\.com/;if(face.test(readFileSync('index.html','utf8'))){console.log('index.html already rides the source face');process.exit(0)}const head=execSync('git show HEAD:./index.html',{encoding:'utf8'});if(!face.test(head)){console.error('refusing: HEAD index.html is not the source face yet - land the source-face fix first; nothing was touched');process.exit(1)}if(cdn.test(head)){console.error('refusing: HEAD index.html still rides the font CDN - land the self-host fix first; nothing was touched');process.exit(1)}execSync('git checkout -- index.html',{stdio:'inherit'});console.log('index.html restored from HEAD (the source face)')\"",
     "test": "vitest run"
   },
   "dependencies": {
+    "@fontsource-variable/bricolage-grotesque": "^5.3.0",
+    "@fontsource-variable/jetbrains-mono": "^5.3.0",
+    "@fontsource-variable/outfit": "^5.3.0",
     "@hono/node-server": "^2.1.3",
     "@prisma/adapter-libsql": "^7.10.0",
     "hono": "^4.13.12",
@@ -58,6 +81,7 @@
     "@capacitor/cli": "^8.5.2",
     "@capacitor/core": "^8.5.2",
     "@capacitor/ios": "^8.5.2",
+    "@fluentui/react-icons": "^2.0.344",
     "@hookform/resolvers": "^5.9.1",
     "@libsql/client": "^0.18.0",
     "@opencode-ai/sdk": "^1.18.34",

package/tests/analyze.test.ts

@@ -0,0 +1,54 @@
+// # analyze.test — the analysis pipeline: a synthetic click track answers
+// its true bpm, a pure-tone key answers its pitch class, the report carries
+// the schema v1 shape and the structure segments stay inside the duration.
+import assert from "node:assert/strict";
+import { describe, it } from "vitest";
+import { analyze, BAND_LABELS } from "../analyze.ts";
+
+/** Builds a percussive click track at the given bpm (deterministic). */
+function clicks(bpm: number, seconds: number, sampleRate = 44100): number[] {
+  const out = new Array<number>(Math.round(seconds * sampleRate)).fill(0);
+  const beat = (60 / bpm) * sampleRate;
+  for (let hit = 0; hit * beat < out.length; hit++) {
+    const start = Math.round(hit * beat);
+    for (let i = 0; i < 900 && start + i < out.length; i++) {
+      out[start + i] = Math.exp((-3 * i) / 300) * Math.sin((2 * Math.PI * 1000 * i) / sampleRate);
+    }
+  }
+  return out;
+}
+
+describe("analyze — the pipeline", () => {
+  it("reads the tempo of a 120 bpm click track", () => {
+    const report = analyze(clicks(120, 6), 44100);
+    assert.ok(Math.abs(report.rhythm.bpm - 120) <= 6, `bpm ${report.rhythm.bpm} drifted past 6`);
+  });
+
+  it("keys a 220hz-dominant tone to the A pitch class", () => {
+    const tone = Array.from({ length: 44100 * 2 }, (_, i) => 0.6 * Math.sin((2 * Math.PI * 220 * i) / 44100));
+    const report = analyze(tone, 44100);
+    assert.equal(report.key.tonicName, "A");
+  });
+
+  it("answers the schema v1 shape", () => {
+    const report = analyze(clicks(90, 4), 44100);
+    assert.equal(report.sampleRate, 44100);
+    assert.ok(Math.abs(report.durationSeconds - 4) < 0.1);
+    assert.equal(report.spectrum.bands.length, BAND_LABELS.length);
+    assert.ok(report.loudness.integrated < 0, "integrated lufs must be negative");
+    assert.ok(Array.isArray(report.structure));
+  });
+
+  it("keeps structure sections inside the duration", () => {
+    const report = analyze(clicks(140, 5), 44100);
+    for (const section of report.structure) {
+      assert.ok(section.start >= 0 && section.end <= report.durationSeconds + 0.2);
+      assert.ok(section.energy > 0 && section.energy <= 1);
+    }
+  });
+
+  it("counts fingerprint hashes when the switch is on", () => {
+    const report = analyze(clicks(120, 2), 44100, { fingerprint: true });
+    assert.ok(report.fingerprintHashes > 0);
+  });
+});

package/tests/arrangement.test.ts

@@ -0,0 +1,109 @@
+// # arrangement.test — the clip binding of the katexis engine: every test
+// watches the law the desk rides — the identity (feeding the plan's own
+// clips answers the seeded schedule), the move (a clip plays what it played,
+// from its new start), the delete (the survivors re-slice the material), the
+// split (the children share the parent's slice), the determinism (same plan,
+// same clips, same schedule) and the refusals (unsound clips are named).
+import assert from "node:assert/strict";
+import { describe, it } from "vitest";
+import { ArrangementError, rebaseSchedule, validateArrangement } from "../arrangement.ts";
+import { planTake } from "../arranger.ts";
+import { scheduleTake, validateSchedule } from "../takeevents.ts";
+
+describe("arrangement — rebaseSchedule", () => {
+  const plan = planTake({ prompt: "midnight techno, dark sub bass, hypnotic arp", seed: "demo-1" });
+  const seeded = scheduleTake(plan);
+
+  it("is the identity when the desk carries the plan's own clips", () => {
+    const rebased = rebaseSchedule(plan, plan.clips, seeded);
+    assert.equal(rebased.events.length, seeded.events.length);
+    for (let index = 0; index < seeded.events.length; index++) {
+      assert.equal(rebased.events[index].role, seeded.events[index].role);
+      assert.ok(Math.abs(rebased.events[index].time - seeded.events[index].time) < 1e-6, `event ${index} drifted`);
+    }
+    assert.deepEqual(rebased.perRole, seeded.perRole);
+  });
+
+  it("moves a clip's material to the clip's new start", () => {
+    const role = "drums";
+    const clip = plan.clips.find((entry) => entry.track === role);
+    assert.ok(clip);
+    const shifted = plan.clips.map((entry) =>
+      entry.id === clip.id ? { ...entry, start: entry.start + entry.duration } : entry,
+    );
+    const rebased = rebaseSchedule(plan, shifted, seeded);
+    const sourceTimes = seeded.events
+      .filter((event) => event.role === role && event.time >= clip.start && event.time < clip.start + clip.duration)
+      .map((event) => event.time - clip.start + clip.start + clip.duration);
+    const playedTimes = rebased.events.filter((event) => event.role === role).map((event) => event.time);
+    assert.ok(sourceTimes.length > 0, "the source window carried no events");
+    for (const expected of sourceTimes) {
+      assert.ok(
+        playedTimes.some((time) => Math.abs(time - expected) < 1e-6),
+        `no event landed at ${expected.toFixed(3)}`,
+      );
+    }
+  });
+
+  it("re-slices the material across the survivors when a clip is deleted", () => {
+    const role = "bass";
+    const clips = plan.clips.filter((entry) => entry.track === role);
+    assert.ok(clips.length > 1, "the test needs more than one bass clip");
+    const removed = clips[0];
+    const survivors = clips.slice(1);
+    const rebased = rebaseSchedule(plan, survivors, seeded);
+    const sourceCount = seeded.events.filter(
+      (event) => event.role === role && event.time >= removed.start && event.time < removed.start + removed.duration,
+    ).length;
+    const playedCount = rebased.events.filter((event) => event.role === role).length;
+    const expected = seeded.events.filter((event) => event.role === role).length - sourceCount;
+    assert.equal(playedCount, expected, "the survivors must carry the remaining material");
+  });
+
+  it("keeps every event inside its clip's own gate after the re-slice", () => {
+    const shrunk = plan.clips.map((entry) =>
+      entry.track === "keys" ? { ...entry, duration: entry.duration / 2 } : entry,
+    );
+    const rebased = rebaseSchedule(plan, shrunk, seeded);
+    for (const event of rebased.events) {
+      const clip = shrunk.find(
+        (entry) =>
+          entry.track === event.role &&
+          event.time >= entry.start - 1e-6 &&
+          event.time < entry.start + entry.duration - 1e-6,
+      );
+      assert.ok(clip, `event at ${event.time} sits outside every clip of ${event.role}`);
+    }
+  });
+
+  it("answers a valid schedule the transport validator accepts", () => {
+    const edited = plan.clips.map((entry) =>
+      entry.track === "lead" ? { ...entry, start: entry.start + 0.5 * entry.duration } : entry,
+    );
+    const rebased = rebaseSchedule(plan, edited, seeded);
+    assert.deepEqual(validateSchedule(rebased), []);
+  });
+
+  it("is deterministic: same plan, same clips, same schedule", () => {
+    const edited = plan.clips.map((entry) => ({ ...entry, start: entry.start + 0.25 * entry.duration }));
+    const left = JSON.parse(JSON.stringify(rebaseSchedule(plan, edited, seeded)));
+    const right = JSON.parse(JSON.stringify(rebaseSchedule(plan, edited, seeded)));
+    assert.deepEqual(left, right);
+  });
+
+  it("refuses unsound clips with the clip's own id", () => {
+    const broken = plan.clips.map((entry) => (entry.track === "drums" ? { ...entry, duration: -1 } : entry));
+    assert.throws(
+      () => rebaseSchedule(plan, broken, seeded),
+      (error: unknown) => {
+        assert.ok(error instanceof ArrangementError);
+        assert.equal(error.code, "bad-clips");
+        return true;
+      },
+    );
+  });
+
+  it("validates the edit base and names a sound plan empty", () => {
+    assert.deepEqual(validateArrangement(plan), []);
+  });
+});

package/tests/arranger.test.ts

@@ -0,0 +1,116 @@
+// # arranger.test — the composer of the katexis engine: every test watches
+// the contract the DAW surfaces ride — the plan is deterministic (same
+// prompt+seed, same take), the genre resolves from the matrix, the bpm stays
+// inside the genre band, the chord timeline covers the bars, the clips sit
+// on their roles without overlap, the desk carries a master and the
+// validator answers empty for a sound plan.
+import assert from "node:assert/strict";
+import { describe, it } from "vitest";
+import {
+  planTake,
+  RACK_LANES,
+  resolveGenre,
+  SECTION_PLAN,
+  stepSecondsOf,
+  TOTAL_BARS,
+  takeId,
+  validatePlan,
+} from "../arranger.ts";
+import { GENRES } from "../genrematrix.ts";
+import { clipsOverlap, totalDuration } from "../timelinemodel.ts";
+
+describe("arranger — planTake", () => {
+  const plan = planTake({ prompt: "midnight techno, dark sub bass, hypnotic arp", seed: "demo-1" });
+
+  it("is deterministic: same prompt and seed rebuild the exact take", () => {
+    const again = planTake({ prompt: "midnight techno, dark sub bass, hypnotic arp", seed: "demo-1" });
+    assert.deepEqual(JSON.parse(JSON.stringify(again)), JSON.parse(JSON.stringify(plan)));
+  });
+
+  it("carries the prompt name, the id and the seed back on the plan", () => {
+    assert.equal(plan.name, "Midnight techno, dark sub");
+    assert.equal(plan.seed, "demo-1");
+    assert.equal(plan.id, takeId("demo-1", "midnight techno, dark sub bass, hypnotic arp"));
+  });
+
+  it("resolves the genre from the matrix and keeps the bpm inside its band", () => {
+    const genre = GENRES.find((entry) => entry.id === plan.genreId);
+    assert.ok(genre);
+    assert.equal(plan.genreLabel, genre.label);
+    assert.ok(plan.bpm >= genre.bpmin && plan.bpm <= genre.bpmax);
+    assert.equal(plan.pattern, genre.pattern);
+    assert.equal(plan.lufsTarget, genre.lufs);
+  });
+
+  it("honours a pinned genre over the prompt match", () => {
+    const pinned = planTake({ prompt: "midnight techno", seed: "demo-1", genreId: "lofi" });
+    assert.equal(pinned.genreId, "lofi");
+  });
+
+  it("covers the sixteen bars with chords, one per bar", () => {
+    assert.equal(TOTAL_BARS, 16);
+    assert.equal(plan.bars, 16);
+    assert.equal(plan.chords.length, 16);
+    for (const bar of plan.chords) assert.ok(bar.symbol.length > 0);
+  });
+
+  it("splits the sections over the section plan and sums back to the bars", () => {
+    const sum = SECTION_PLAN.reduce((total, section) => total + section.bars, 0);
+    assert.equal(sum, plan.bars);
+    assert.equal(plan.sections.length, SECTION_PLAN.length);
+  });
+
+  it("places non-overlapping clips on the four roles", () => {
+    const roles = new Set(plan.clips.map((clip) => clip.track));
+    assert.deepEqual([...roles].sort(), ["bass", "drums", "keys", "lead"]);
+    for (let left = 0; left < plan.clips.length; left++) {
+      for (let right = left + 1; right < plan.clips.length; right++) {
+        assert.equal(clipsOverlap(plan.clips[left], plan.clips[right]), false);
+      }
+    }
+    assert.ok(totalDuration(plan.clips) <= plan.durationSeconds + 1e-6);
+  });
+
+  it("opens the desk with the four role strips plus the master", () => {
+    const names = plan.strips.map((strip) => strip.name);
+    assert.deepEqual(names, ["drums", "bass", "keys", "lead", "master"]);
+    assert.ok(plan.strips.some((strip) => strip.master));
+  });
+
+  it("carries a sixteen-step grid with every rack lane and swing offsets", () => {
+    assert.equal(plan.grid.steps, 16);
+    for (const lane of RACK_LANES) assert.equal(plan.grid.lanes[lane].length, 16);
+    assert.equal(plan.offsets.length, 16);
+    assert.equal(stepSecondsOf(plan), 60 / plan.bpm / 4);
+  });
+
+  it("validates clean: the sound plan answers no problems", () => {
+    assert.deepEqual(validatePlan(plan), []);
+  });
+
+  it("flags a broken plan (duration tampered)", () => {
+    const broken = { ...plan, durationSeconds: 1 };
+    assert.ok(validatePlan(broken).length > 0);
+  });
+
+  it("never fails for a short prompt (the fallback genre catches it)", () => {
+    const tiny = planTake({ prompt: "go", seed: "s" });
+    assert.ok(GENRES.some((genre) => genre.id === tiny.genreId));
+    assert.deepEqual(validatePlan(tiny), []);
+  });
+});
+
+describe("arranger — resolveGenre", () => {
+  it("matches a prompt that names the genre", () => {
+    assert.equal(resolveGenre("hard drill night")?.id, "drill");
+  });
+
+  it("pins the genre id when asked", () => {
+    assert.equal(resolveGenre("anything", "ambient")?.id, "ambient");
+  });
+
+  it("falls back into the matrix for a prompt with no hit", () => {
+    const genre = resolveGenre("qqzz wumpus");
+    assert.ok(GENRES.some((entry) => entry.id === genre.id));
+  });
+});

package/tests/dawview.test.ts

@@ -0,0 +1,104 @@
+// # dawview.test — the pure view math of the DAW surfaces: the clock format,
+// the clip geometry clamps, the fader travel round-trip, the meter percent
+// and the playhead percent. The studio reads these numbers; the tests pin
+// them.
+import assert from "node:assert/strict";
+import { describe, it } from "vitest";
+import {
+  clampFader,
+  clipStyle,
+  FADER_MAX_DB,
+  FADER_MIN_DB,
+  faderToUnit,
+  formatClock,
+  formatGain,
+  levelToPercent,
+  playheadPercent,
+  unitToFader,
+} from "../dawview.ts";
+
+describe("dawview — formatClock", () => {
+  it("formats the classic m:ss.t readout", () => {
+    assert.equal(formatClock(0), "0:00.0");
+    assert.equal(formatClock(4.12), "0:04.1");
+    assert.equal(formatClock(65.5), "1:05.5");
+    assert.equal(formatClock(601.25), "10:01.2");
+  });
+
+  it("answers the zero clock for junk input", () => {
+    assert.equal(formatClock(Number.NEGATIVE_INFINITY), "0:00.0");
+    assert.equal(formatClock(Number.NaN), "0:00.0");
+    assert.equal(formatClock(-3), "0:00.0");
+  });
+});
+
+describe("dawview — clipStyle", () => {
+  it("maps a clip onto its percent geometry", () => {
+    const geo = clipStyle(10, 5, 20);
+    assert.equal(geo.left, 50);
+    assert.equal(geo.width, 25);
+  });
+
+  it("clamps a clip that runs past the arrangement", () => {
+    const geo = clipStyle(15, 10, 20);
+    assert.equal(geo.left, 75);
+    assert.equal(geo.width, 25);
+  });
+
+  it("never answers negative or over-full geometry", () => {
+    const over = clipStyle(25, 5, 20);
+    assert.equal(over.left, 100);
+    assert.equal(over.width, 0);
+    const empty = clipStyle(1, 1, 0);
+    assert.deepEqual(empty, { left: 0, width: 0 });
+  });
+});
+
+describe("dawview — fader travel", () => {
+  it("maps the −60..+6 dB travel onto 0..1", () => {
+    assert.equal(faderToUnit(FADER_MIN_DB), 0);
+    assert.equal(faderToUnit(0), 60 / 66);
+    assert.equal(faderToUnit(FADER_MAX_DB), 1);
+  });
+
+  it("round-trips a fader value through the unit space", () => {
+    for (let db = FADER_MIN_DB; db <= FADER_MAX_DB; db += 0.5) {
+      assert.ok(Math.abs(unitToFader(faderToUnit(db)) - db) < 1e-9);
+    }
+  });
+
+  it("clamps out-of-travel values", () => {
+    assert.equal(clampFader(-100), FADER_MIN_DB);
+    assert.equal(clampFader(20), FADER_MAX_DB);
+    assert.equal(unitToFader(-2), FADER_MIN_DB);
+    assert.equal(unitToFader(2), FADER_MAX_DB);
+  });
+
+  it("snaps the unit walk onto 0.5 dB steps", () => {
+    const db = unitToFader(0.5);
+    assert.equal(db, Math.round(db * 2) / 2);
+  });
+});
+
+describe("dawview — meters and playhead", () => {
+  it("maps a dBFS level onto the 0..100 meter with the −48 floor", () => {
+    assert.equal(levelToPercent(Number.NEGATIVE_INFINITY), 0);
+    assert.equal(levelToPercent(-48), 0);
+    assert.equal(levelToPercent(-24), 50);
+    assert.equal(levelToPercent(0), 100);
+    assert.equal(levelToPercent(6), 100);
+    assert.equal(levelToPercent(Number.NaN), 0);
+  });
+
+  it("maps the playhead percent and clamps both ends", () => {
+    assert.equal(playheadPercent(5, 20), 25);
+    assert.equal(playheadPercent(-1, 20), 0);
+    assert.equal(playheadPercent(30, 20), 100);
+    assert.equal(playheadPercent(5, 0), 0);
+  });
+
+  it("formats gains with the silence glyph", () => {
+    assert.equal(formatGain(-4), "-4.0");
+    assert.equal(formatGain(Number.NEGATIVE_INFINITY), "−∞");
+  });
+});

package/tests/family.test.ts

@@ -0,0 +1,80 @@
+// # family.test — the family table the chrome rides (campaign 5-b, the
+// contract D): the eight siblings beside debonair are listed once, every
+// slug resolves through the familyurl contract into a climb-one-level url,
+// every member carries the spec §12 accent with its own dot ink, and no
+// accent ever collides with the banned palette. The rail foot, the landing
+// footer and this test consume the same table — the row cannot drift.
+import assert from "node:assert/strict";
+import { describe, it } from "vitest";
+import { FAMILY_ACCENTS, FAMILY_SLUGS, familyrow } from "../family.ts";
+import { familyurl } from "../familyurl.ts";
+
+const BANNED = new Set(["#3b82f6", "#2563eb", "#f97316"]);
+
+describe("family table", () => {
+  it("lists the eight siblings beside debonair, never debonair itself", () => {
+    assert.deepEqual(FAMILY_SLUGS, ["argan", "cadria", "forge", "foundry", "getry", "saddle", "stealthhead", "vault"]);
+    assert.ok(!FAMILY_SLUGS.includes("debonair"));
+    assert.ok(!FAMILY_SLUGS.includes("devthink"));
+  });
+
+  it("answers an accent for every listed sibling", () => {
+    for (const slug of FAMILY_SLUGS) {
+      const member = FAMILY_ACCENTS[slug];
+      assert.ok(member, `${slug} must carry an accent`);
+      assert.equal(member.slug, slug);
+      assert.match(member.accent, /^#[0-9a-f]{6}$/);
+      assert.match(member.dotInk, /^#[0-9a-f]{6}$/);
+    }
+    // the table holds exactly the siblings — no orphan accents
+    assert.deepEqual(Object.keys(FAMILY_ACCENTS).sort(), [...FAMILY_SLUGS].sort());
+  });
+
+  it("resolves every member through the familyurl contract", () => {
+    for (const slug of FAMILY_SLUGS) {
+      assert.equal(familyurl(slug), `../${slug}/`);
+    }
+  });
+
+  it("keeps the spec §12 accents stable", () => {
+    assert.equal(FAMILY_ACCENTS.argan.accent, "#34d8a8");
+    assert.equal(FAMILY_ACCENTS.cadria.accent, "#f472b6");
+    assert.equal(FAMILY_ACCENTS.forge.accent, "#a2cb3a");
+    assert.equal(FAMILY_ACCENTS.foundry.accent, "#2fb8b5");
+    assert.equal(FAMILY_ACCENTS.getry.accent, "#8b5cf6");
+    assert.equal(FAMILY_ACCENTS.saddle.accent, "#e86f2d");
+    assert.equal(FAMILY_ACCENTS.stealthhead.accent, "#e8563f");
+    assert.equal(FAMILY_ACCENTS.vault.accent, "#a3d7e6");
+  });
+
+  it("pairs every accent with its own spec ink", () => {
+    assert.equal(FAMILY_ACCENTS.argan.dotInk, "#04231a");
+    assert.equal(FAMILY_ACCENTS.cadria.dotInk, "#2a0715");
+    assert.equal(FAMILY_ACCENTS.forge.dotInk, "#161d03");
+    assert.equal(FAMILY_ACCENTS.foundry.dotInk, "#03211f");
+    assert.equal(FAMILY_ACCENTS.getry.dotInk, "#120533");
+    assert.equal(FAMILY_ACCENTS.saddle.dotInk, "#2a0f02");
+    assert.equal(FAMILY_ACCENTS.stealthhead.dotInk, "#2c0703");
+    assert.equal(FAMILY_ACCENTS.vault.dotInk, "#072330");
+  });
+
+  it("never ships a banned hue in the row", () => {
+    for (const member of familyrow()) {
+      assert.ok(!BANNED.has(member.accent), `${member.slug} rides a banned accent`);
+    }
+  });
+
+  it("keeps every accent distinct — the row never repeats a hue", () => {
+    const accents = familyrow().map((member) => member.accent);
+    assert.equal(new Set(accents).size, accents.length);
+  });
+
+  it("builds the rail row in slug order without gaps", () => {
+    const row = familyrow();
+    assert.equal(row.length, FAMILY_SLUGS.length);
+    assert.deepEqual(
+      row.map((member) => member.slug),
+      [...FAMILY_SLUGS],
+    );
+  });
+});