@wenathlan/cadria 2.0.93 → 2.0.117

package/tests/synthtexture.test.ts

@@ -0,0 +1,256 @@
+// # synthtexture.test — the texture layer's contract, runnable with vitest:
+//   pnpm vitest run tests/synthtexture.test.ts
+// The tests watch four promises: the timbre → texture ramps are monotonic in
+// their documented drivers (noise densifies, warmth softens and thickens,
+// brightness sheens, contrast agitates, flatness stacks, flux jitters, zcr
+// refines), every answer stays finite inside TEXTURE_RANGES with the
+// grainOpacity coupling intact, damaged input falls back to the neutral
+// canvas preset, and everything — synthesis, scatter fields, presets,
+// blends — is deterministic bit-for-bit.
+import assert from "node:assert/strict";
+import { describe, it } from "vitest";
+import type { AudioDescriptor } from "../audioattributes.ts";
+import { DIM_ORDER } from "../audiofeatures.ts";
+import type { TexturePresetName, TextureSpec } from "../synthtexture.ts";
+import {
+  GRAIN_COUPLING,
+  JITTER_FIELD_CAP,
+  jitterField,
+  sanitizeTexture,
+  synthTexture,
+  synthTextureFromPreset,
+  TEXTURE_RANGES,
+  textureDistance,
+  texturePresets,
+} from "../synthtexture.ts";
+
+/** neutral base vector: mid-low everywhere so single-dim overrides read clean. */
+const BASE = 0.3;
+
+/** builds a descriptor by overriding contract positions (3, 4, 16-21). */
+function descriptor(dims: Record<number, number>): AudioDescriptor {
+  const vector = new Array<number>(32).fill(BASE);
+  for (const [k, v] of Object.entries(dims)) vector[Number(k)] = v;
+  return { version: 1, seed: "feedface00ffaa11", vector, scalar: {} };
+}
+
+const WHITE_NOISE = descriptor({ 3: 0.95, 4: 0.9, 16: 0.98, 17: 0.3, 18: 0.85, 20: 0.45, 21: 0.75 });
+const PURE_TONE = descriptor({ 3: 0.03, 4: 0.05, 16: 0.02, 17: 0.5, 18: 0.3, 20: 0.04, 21: 0.25 });
+const WARM_DARK = descriptor({ 17: 0.9, 18: 0.08 });
+const BRIGHT = descriptor({ 18: 0.95 });
+/** every consumed dim broken at once — the whole descriptor is distrusted. */
+const DAMAGED = descriptor({ 3: NaN, 4: 0.5, 16: 0.5, 17: 0.5, 18: 0.5, 20: 0.5, 21: 0.5 });
+
+/** every documented bound holds (range, whole layers, grain coupling). */
+function assertInRanges(spec: TextureSpec, label: string): void {
+  for (const key of Object.keys(TEXTURE_RANGES) as (keyof TextureSpec)[]) {
+    const { min, max } = TEXTURE_RANGES[key];
+    const v = spec[key];
+    assert.ok(Number.isFinite(v), `${label}.${key} finite`);
+    assert.ok(v >= min && v <= max, `${label}.${key} ${v} in [${min}, ${max}]`);
+  }
+  assert.ok(Number.isInteger(spec.glazeLayers), `${label}.glazeLayers whole`);
+  assert.ok(spec.grainOpacity <= spec.grainDensity + GRAIN_COUPLING + 1e-9, `${label} grain coupling`);
+}
+
+describe("timbre → texture ramps", () => {
+  it("noise walls speckle: noisiness densifies and coarsens the grain", () => {
+    const noise = synthTexture(WHITE_NOISE);
+    const pure = synthTexture(PURE_TONE);
+    assert.ok(noise.grainDensity > 0.7, `density ${noise.grainDensity}`);
+    assert.ok(noise.grainSize > 4, `size ${noise.grainSize}`);
+    assert.ok(pure.grainDensity < 0.2, `density ${pure.grainDensity}`);
+    assert.ok(pure.grainSize <= 1.5, `size ${pure.grainSize}`);
+  });
+  it("warm mixes paint soft: warmth lifts strokeSoftness", () => {
+    const soft = synthTexture(WARM_DARK);
+    assert.ok(soft.strokeSoftness > 0.7, `softness ${soft.strokeSoftness}`);
+  });
+  it("warm + dark goes soft with the sheen off", () => {
+    const spec = synthTexture(WARM_DARK);
+    assert.ok(spec.strokeSoftness > 0.7, `softness ${spec.strokeSoftness}`);
+    assert.ok(spec.specular < 0.2, `specular ${spec.specular}`);
+  });
+  it("bright mixes sheen: specular high and glazeOpacity lifts", () => {
+    const bright = synthTexture(BRIGHT);
+    const dark = synthTexture(WARM_DARK);
+    assert.ok(bright.specular > 0.8, `specular ${bright.specular}`);
+    assert.ok(bright.glazeOpacity > dark.glazeOpacity, "glazeOpacity climbs with brightness");
+  });
+  it("contrast agitates: turbulence climbs with dynamics range", () => {
+    const high = synthTexture(descriptor({ 21: 0.9 }));
+    const low = synthTexture(descriptor({ 21: 0.1 }));
+    assert.ok(high.turbulence > low.turbulence, `${high.turbulence} > ${low.turbulence}`);
+  });
+  it("flat spectra stack washes: flatness drives glazeLayers", () => {
+    const flat = synthTexture(descriptor({ 3: 0.95 }));
+    const tonal = synthTexture(descriptor({ 3: 0.03 }));
+    assert.equal(flat.glazeLayers, 6);
+    assert.equal(tonal.glazeLayers, 1);
+  });
+  it("spectral motion shakes the line: flux drives strokeJitter", () => {
+    const busy = synthTexture(descriptor({ 4: 0.9 }));
+    const still = synthTexture(descriptor({ 4: 0.05 }));
+    assert.ok(busy.strokeJitter > still.strokeJitter, "jitter climbs with flux");
+    assert.ok(synthTexture(WHITE_NOISE).strokeJitter > 0.7, "noise walls jitter hard");
+  });
+  it("high zero crossings refine the grain at fixed noisiness", () => {
+    const hissy = synthTexture(descriptor({ 16: 0.8, 20: 0.45 }));
+    const round = synthTexture(descriptor({ 16: 0.8, 20: 0.05 }));
+    assert.ok(hissy.grainSize < round.grainSize, `${hissy.grainSize} < ${round.grainSize}`);
+  });
+  it("strokeWeight grows with warmth", () => {
+    const light = synthTexture(descriptor({ 17: 0.2, 21: 0.3 }));
+    const mid = synthTexture(descriptor({ 17: 0.5, 21: 0.3 }));
+    const heavy = synthTexture(descriptor({ 17: 0.8, 21: 0.3 }));
+    assert.ok(light.strokeWeight < mid.strokeWeight && mid.strokeWeight < heavy.strokeWeight);
+  });
+  it("grainOpacity never outruns grainDensity + 0.2 across a sweep", () => {
+    const sweep = [
+      WHITE_NOISE,
+      PURE_TONE,
+      WARM_DARK,
+      BRIGHT,
+      descriptor({ 16: 0.5, 17: 0.5, 18: 0.5, 21: 0.5, 3: 0.5, 4: 0.5, 20: 0.5 }),
+      descriptor({ 16: 0.75, 20: 0.3 }),
+      descriptor({ 21: 1, 17: 1 }),
+      descriptor({}),
+    ];
+    for (const d of sweep) {
+      const spec = synthTexture(d);
+      assert.ok(spec.grainOpacity <= spec.grainDensity + GRAIN_COUPLING + 1e-9);
+    }
+  });
+  it("every synthesized spec is finite and inside TEXTURE_RANGES", () => {
+    assertInRanges(synthTexture(WHITE_NOISE), "white-noise");
+    assertInRanges(synthTexture(PURE_TONE), "pure-tone");
+    assertInRanges(synthTexture(WARM_DARK), "warm-dark");
+    assertInRanges(synthTexture(BRIGHT), "bright");
+    assertInRanges(synthTexture(descriptor({})), "neutral");
+  });
+});
+
+describe("damaged input", () => {
+  it("non-finite dims fall back to the neutral canvas preset", () => {
+    const canvas = texturePresets().canvas.spec;
+    assert.deepEqual(synthTexture(DAMAGED), canvas);
+    assert.deepEqual(synthTexture(descriptor({ 16: Infinity })), canvas);
+    assert.deepEqual(synthTexture(descriptor({ 21: -NaN })), canvas);
+  });
+  it("missing, short or non-object descriptors fall back to canvas", () => {
+    const canvas = texturePresets().canvas.spec;
+    assert.deepEqual(synthTexture(null as unknown as AudioDescriptor), canvas);
+    assert.deepEqual(synthTexture(undefined as unknown as AudioDescriptor), canvas);
+    assert.deepEqual(synthTexture({ version: 1, seed: "x", vector: [0, 0, 0], scalar: {} }), canvas);
+  });
+  it("sanitizeTexture repairs wild specs into the documented ranges", () => {
+    const wild = {
+      grainDensity: 0.5,
+      grainSize: -2,
+      grainOpacity: 0.9,
+      strokeSoftness: NaN,
+      strokeWeight: -10,
+      strokeJitter: 3,
+      glazeLayers: 0.4,
+      glazeOpacity: 1.5,
+      specular: Infinity,
+      turbulence: -1,
+    } as TextureSpec;
+    const fixed = sanitizeTexture(wild);
+    assertInRanges(fixed, "wild");
+    assert.equal(fixed.grainOpacity, fixed.grainDensity + GRAIN_COUPLING); // coupling clamps it down
+    assert.equal(fixed.grainSize, 1); // damaged → range floor
+  });
+});
+
+describe("jitterField", () => {
+  it("is deterministic for the same seed", () => {
+    assert.deepEqual(jitterField("feedface00ffaa11", 64), jitterField("feedface00ffaa11", 64));
+  });
+  it("stays in [-1, 1] and swings both signs", () => {
+    const field = jitterField("determinism", 256);
+    assert.equal(field.length, 256);
+    for (const v of field) assert.ok(v >= -1 && v <= 1, `value ${v}`);
+    assert.ok(
+      field.some((v) => v > 0.1),
+      "has positives",
+    );
+    assert.ok(
+      field.some((v) => v < -0.1),
+      "has negatives",
+    );
+  });
+  it("differs across seeds and prefixes across counts", () => {
+    const a = jitterField("seed-a", 32);
+    const b = jitterField("seed-b", 32);
+    assert.notDeepEqual(a, b);
+    assert.deepEqual(jitterField("seed-a", 128).slice(0, 32), a); // prefix property
+  });
+  it("guards the count: floors, rejects damage, caps runaway asks", () => {
+    assert.equal(jitterField("x", NaN).length, 0);
+    assert.equal(jitterField("x", -5).length, 0);
+    assert.equal(jitterField("x", 4.9).length, 4);
+    assert.equal(jitterField("x", JITTER_FIELD_CAP + 1000).length, JITTER_FIELD_CAP);
+  });
+});
+
+describe("presets + blending", () => {
+  it("ships the three named feels, all finite, in range and coupled", () => {
+    const presets = texturePresets();
+    assert.deepEqual(Object.keys(presets).sort(), ["canvas", "glass", "static"]);
+    assertInRanges(presets.glass.spec, "glass");
+    assertInRanges(presets.canvas.spec, "canvas");
+    assertInRanges(presets.static.spec, "static");
+  });
+  it("frozen fields hold their ground under blending", () => {
+    for (const preset of Object.values(texturePresets())) {
+      const blended = synthTextureFromPreset(preset.name, WHITE_NOISE);
+      for (const key of preset.frozen) {
+        assert.equal(blended[key], preset.spec[key], `${preset.name}.${String(key)} frozen`);
+      }
+    }
+  });
+  it("preset blends stay inside every documented range", () => {
+    for (const name of ["glass", "canvas", "static"] as const) {
+      assertInRanges(synthTextureFromPreset(name, WHITE_NOISE), `${name} × noise`);
+      assertInRanges(synthTextureFromPreset(name, PURE_TONE), `${name} × pure`);
+      assertInRanges(synthTextureFromPreset(name, DAMAGED), `${name} × damaged`);
+    }
+  });
+  it("pure tones sit closer to glass than to static", () => {
+    const target = synthTexture(PURE_TONE);
+    const glass = synthTextureFromPreset("glass", PURE_TONE);
+    const statik = synthTextureFromPreset("static", PURE_TONE);
+    assert.equal(textureDistance(target, target), 0);
+    assert.ok(
+      textureDistance(glass, target) < textureDistance(statik, target),
+      `${textureDistance(glass, target)} < ${textureDistance(statik, target)}`,
+    );
+  });
+  it("noise walls sit closer to static than to glass", () => {
+    const target = synthTexture(WHITE_NOISE);
+    const glass = synthTextureFromPreset("glass", WHITE_NOISE);
+    const statik = synthTextureFromPreset("static", WHITE_NOISE);
+    assert.ok(textureDistance(statik, target) < textureDistance(glass, target));
+  });
+  it("unknown preset names fall back to the canvas base", () => {
+    const viaCanvas = synthTextureFromPreset("canvas", WARM_DARK);
+    const viaGarbage = synthTextureFromPreset("velvet" as TexturePresetName, WARM_DARK);
+    assert.deepEqual(viaGarbage, viaCanvas);
+  });
+  it("the whole pipeline is deterministic", () => {
+    assert.deepEqual(synthTexture(WHITE_NOISE), synthTexture(WHITE_NOISE));
+    assert.deepEqual(synthTextureFromPreset("glass", WARM_DARK), synthTextureFromPreset("glass", WARM_DARK));
+    assert.deepEqual(sanitizeTexture(synthTexture(PURE_TONE)), synthTexture(PURE_TONE));
+  });
+  it("reads the contract dims by documented name", () => {
+    assert.equal(DIM_ORDER.length, 32);
+    assert.equal(DIM_ORDER[3], "flatness");
+    assert.equal(DIM_ORDER[4], "flux");
+    assert.equal(DIM_ORDER[16], "noisiness");
+    assert.equal(DIM_ORDER[17], "warmth");
+    assert.equal(DIM_ORDER[18], "timbreBrightness");
+    assert.equal(DIM_ORDER[20], "zeroCrossings");
+    assert.equal(DIM_ORDER[21], "contrast");
+  });
+});

package/tests/timelineedit.test.ts

@@ -1,15 +1,14 @@
 // # timelineedit.test — the editing algebra of the timeline: the
 // overwrite, insert, lift and extract spans, the split with the fresh
 // right id, the trims with handles and neighbours, the roll, slip,
-// slide and rate stretch, runnable with the node built-in runner (no
-// dependencies, no install):
-//   node --test tests/timelineedit.test.ts
+// slide and rate stretch, runnable with vitest:
+//   pnpm vitest run tests/timelineedit.test.ts
 // Every test watches the two invariants the module promises: edits
 // never throw — every refusal rides the outcome type — and the media
 // window of a piece only moves through the source in point its speed
 // computes.
 import assert from "node:assert/strict";
-import { describe, it } from "node:test";
+import { describe, it } from "vitest";
 import {
   type EditItem,
   type EditTrack,
@@ -21,13 +20,11 @@ import {
   overwrite,
   ratestretch,
   roll,
-  shapeof,
   slide,
   slip,
   sorttrack,
   split,
   syncconflict,
-  trackof,
   trim,
 } from "../timelineedit.ts";
 

package/tests/timelineview.test.ts

@@ -0,0 +1,248 @@
+// # timelineview.test — the pure view-model of the edit surface, runnable
+// with vitest:
+//   pnpm vitest run tests/timelineview.test.ts
+// Every test watches the three promises the module makes: the tick↔pixel
+// mapping never invents time (pixels floor, ticks saturate), the ruler picks
+// the smallest readable step deterministically and labels with the exact
+// SMPTE display, and the playhead helpers (edit points, magnet, quantized
+// advance) only ever land on boundaries the algebra itself knows about.
+import assert from "node:assert/strict";
+import { describe, it } from "vitest";
+import type { EditIssue, EditItem, EditTrack } from "../timelineedit.ts";
+import {
+  advanceplayhead,
+  clipgeometry,
+  DEFAULT_ZOOM_INDEX,
+  editpoints,
+  mediawindow,
+  pxtotick,
+  refusalnote,
+  rulerticks,
+  SLATE_FACES,
+  sequenceend,
+  slateface,
+  snapedit,
+  stockbin,
+  ticktopx,
+  visiblewindow,
+  ZOOM_LEVELS,
+} from "../timelineview.ts";
+import { frameduration, MAX_TICKS, TICKS_PER_SECOND, tickofframe } from "../timeticks.ts";
+
+const R24 = { num: 24, den: 1 };
+
+function item(id: number, start: number, duration: number, sourceIn = 0, speed = 1): EditItem {
+  return { id, start, duration, sourceIn, speed };
+}
+
+function track(items: EditItem[]): EditTrack {
+  return { id: 1, locked: false, syncLock: false, items };
+}
+
+describe("timelineview mapping", () => {
+  it("converts ticks to px and back without inventing time", () => {
+    const px = 64;
+    assert.equal(ticktopx(TICKS_PER_SECOND, px), px);
+    // a floored round trip: px→tick floors, so tick→px→tick lands on the same tick
+    const t = 2 * TICKS_PER_SECOND + 12345;
+    assert.equal(pxtotick(ticktopx(t, 64), 64), t);
+    // half a second at 64 px/s
+    assert.equal(ticktopx(TICKS_PER_SECOND / 2, 64), 32);
+    assert.equal(pxtotick(32, 64), TICKS_PER_SECOND / 2);
+  });
+
+  it("answers zero on damaged input instead of throwing", () => {
+    assert.equal(ticktopx(Number.NaN, 64), 0);
+    assert.equal(ticktopx(TICKS_PER_SECOND, 0), 0);
+    assert.equal(pxtotick(Number.NaN, 64), 0);
+    assert.equal(pxtotick(100, Number.NaN), 0);
+    assert.equal(pxtotick(-50, 64), 0);
+  });
+
+  it("floors pixels coarser than ticks and saturates at the tick ceiling", () => {
+    assert.equal(pxtotick(1, 64), Math.floor((1 / 64) * TICKS_PER_SECOND));
+    // an absurd pixel offset saturates at the tick ceiling instead of overflowing
+    assert.equal(pxtotick(1e9, 64), Number.MAX_SAFE_INTEGER);
+  });
+});
+
+describe("timelineview ruler", () => {
+  it("picks the smallest step whose majors clear 72 px", () => {
+    // 64 px/s: 0.5s = 32px (too tight), 1s = 64px (too tight), 2s = 128px ✓
+    const ticks = rulerticks(0, 10 * TICKS_PER_SECOND, R24, 64);
+    const majors = ticks.filter((entry) => entry.major);
+    assert.equal(majors.length, 6); // 0,2,4,6,8,10 — inclusive window
+    assert.equal(majors[0].label, "00:00:00:00");
+    assert.equal(majors[1].label, "00:00:02:00");
+  });
+
+  it("widens the step as the zoom drops and labels with exact timecode", () => {
+    // 8 px/s: even 60s = 480px, 0.5s = 4px… majors = 8s? no: 8*8=64 <72, 10s = 80 ✓
+    const ticks = rulerticks(0, 30 * TICKS_PER_SECOND, R24, 8);
+    const majors = ticks.filter((entry) => entry.major);
+    assert.equal(majors[0].label, "00:00:00:00");
+    assert.equal(majors[1].label, "00:00:10:00");
+  });
+
+  it("stays bounded and empty on damaged windows", () => {
+    assert.deepEqual(rulerticks(5, 5, R24, 64), []);
+    assert.deepEqual(rulerticks(10, 0, R24, 64), []);
+    const bounded = rulerticks(0, Number.MAX_SAFE_INTEGER, R24, 64);
+    assert.ok(bounded.length <= 1600);
+  });
+});
+
+describe("timelineview geometry", () => {
+  it("places clips and floors the width at 2 px", () => {
+    const one = item(1, TICKS_PER_SECOND, TICKS_PER_SECOND / 2);
+    assert.deepEqual(clipgeometry(one, 64), { left: 64, width: 32 });
+    const sliver = item(2, 0, 1); // one tick — invisible, but grabbable
+    assert.deepEqual(clipgeometry(sliver, 64), { left: 0, width: 2 });
+  });
+
+  it("maps the media window of a clip against its source", () => {
+    const clipped = item(1, 0, TICKS_PER_SECOND, 2 * TICKS_PER_SECOND, 1);
+    assert.deepEqual(mediawindow(clipped, 4 * TICKS_PER_SECOND), { from: 0.5, to: 0.75 });
+    // unknown source: the full window (the face paints whole)
+    assert.deepEqual(mediawindow(clipped, null), { from: 0, to: 1 });
+    assert.deepEqual(mediawindow(clipped, 0), { from: 0, to: 1 });
+    // over-speed reading clamps to the source end
+    const fast = item(2, 0, 4 * TICKS_PER_SECOND, 2 * TICKS_PER_SECOND, 4);
+    assert.equal(mediawindow(fast, 4 * TICKS_PER_SECOND).to, 1);
+  });
+});
+
+describe("timelineview sequence + playhead", () => {
+  it("answers the sequence end and the sorted edit points", () => {
+    const trk = track([item(1, 10, 5), item(2, 0, 5), item(3, 20, 5)]);
+    assert.equal(sequenceend(trk), 25);
+    assert.deepEqual(editpoints(trk), [0, 5, 10, 15, 20, 25]);
+    assert.deepEqual(editpoints(track([])), [0]);
+  });
+
+  it("magnet-snaps the playhead to the nearest edit point inside the threshold", () => {
+    const trk = track([item(1, 0, 10), item(2, 10, 10)]);
+    assert.equal(snapedit(trk, 9, 2), 10);
+    assert.equal(snapedit(trk, 9, 0.5), null);
+    // a tie answers the earlier point — the cut behind the playhead wins
+    assert.equal(snapedit(trk, 15, 5), 10);
+    assert.equal(snapedit(trk, 14.5, 5), 10);
+    assert.equal(snapedit(trk, 15, 0), null);
+  });
+
+  it("advances the playhead by wall clock, quantized to frames when asked", () => {
+    const frame = frameduration(R24);
+    const start = tickofframe(R24, 12);
+    const plain = advanceplayhead(R24, start, 1000, false);
+    assert.equal(plain, start + TICKS_PER_SECOND);
+    const quantized = advanceplayhead(R24, start + Math.round(frame * 0.4), 1000, true);
+    assert.equal(quantized, tickofframe(R24, 36)); // 12 frames + 1 s (24 frames), snapped nearest
+    // non-advance answers the (quantized) input
+    assert.equal(advanceplayhead(R24, start, 0, true), start);
+    assert.equal(advanceplayhead(R24, start, -5, false), start);
+  });
+
+  it("answers the visible tick window for a scroll offset", () => {
+    const win = visiblewindow(128, 64, 64);
+    assert.deepEqual(win, { from: 2 * TICKS_PER_SECOND, to: 3 * TICKS_PER_SECOND });
+    assert.deepEqual(visiblewindow(-10, 0, 64).from, 0);
+  });
+});
+
+describe("timelineview stock bin", () => {
+  it("ships deterministic slates with exact tick durations", () => {
+    const bin = stockbin();
+    assert.equal(bin.length, 5);
+    assert.equal(bin[0].id, "slate-01");
+    assert.equal(bin[0].duration, 4 * TICKS_PER_SECOND);
+    assert.equal(bin[4].duration, 2 * TICKS_PER_SECOND);
+    // every slate names itself and carries a detail line
+    for (const slate of bin) {
+      assert.ok(slate.name.length > 0);
+      assert.ok(slate.detail.length > 0);
+    }
+  });
+
+  it("wraps the rose face ramp for any bin index", () => {
+    assert.equal(slateface(0), "#f472b6");
+    assert.equal(slateface(5), slateface(0));
+    assert.equal(slateface(-1), slateface(4));
+  });
+});
+
+describe("timelineview refusal vocabulary", () => {
+  /** the full issue vocabulary of the algebra — the surface must answer every key. */
+  const ISSUES: readonly EditIssue[] = [
+    "locked",
+    "no-item",
+    "sync-lock-conflict",
+    "no-handles",
+    "too-short",
+    "overlap",
+    "nothing",
+  ];
+
+  it("answers an honest one-line note for every issue the algebra can return", () => {
+    const notes = new Set<string>();
+    for (const issue of ISSUES) {
+      const note = refusalnote(issue);
+      assert.ok(typeof note === "string" && note.length > 0, `${issue} must carry a note`);
+      assert.ok(!note.includes("undefined"), `${issue} must not leak undefined`);
+      notes.add(note);
+    }
+    // every note is distinct — the readout never blurs two refusals together
+    assert.equal(notes.size, ISSUES.length);
+  });
+
+  it("keeps the refusals honest — they say what was kept and why", () => {
+    assert.match(refusalnote("locked"), /unlock/);
+    assert.match(refusalnote("no-handles"), /master handles/);
+    assert.match(refusalnote("too-short"), /one frame/);
+    assert.match(refusalnote("overlap"), /neighbour/);
+    assert.match(refusalnote("nothing"), /nothing/);
+  });
+});
+
+describe("timelineview zoom ladder", () => {
+  it("keeps the ladder ascending with a sane default index", () => {
+    assert.ok(ZOOM_LEVELS.length >= 4);
+    for (let i = 1; i < ZOOM_LEVELS.length; i++) assert.ok(ZOOM_LEVELS[i] > ZOOM_LEVELS[i - 1]);
+    assert.ok(DEFAULT_ZOOM_INDEX >= 0 && DEFAULT_ZOOM_INDEX < ZOOM_LEVELS.length);
+    assert.equal(ZOOM_LEVELS[DEFAULT_ZOOM_INDEX], 64);
+  });
+});
+
+describe("timelineview saturation + honesty", () => {
+  const BANNED = new Set(["#3b82f6", "#2563eb", "#f97316"]);
+  const MASTER_TICKS = 20 * TICKS_PER_SECOND;
+
+  it("saturates the playhead at the tick ceiling instead of overflowing", () => {
+    // a wall clock absurdity (a tab left playing for years) must clamp, never wrap
+    assert.equal(advanceplayhead(R24, 0, Number.MAX_SAFE_INTEGER, false), Number.MAX_SAFE_INTEGER);
+    assert.equal(advanceplayhead(R24, 0, Number.MAX_SAFE_INTEGER, true), MAX_TICKS);
+    // the quantized ceiling is a real frame boundary, not NaN
+    assert.equal(advanceplayhead(R24, MAX_TICKS, 1000, true), MAX_TICKS);
+  });
+
+  it("keeps the stock bin deterministic and every cut inside the 20 s master", () => {
+    const bin = stockbin();
+    assert.deepEqual(bin, stockbin());
+    // the surface trims against a 20 s master: slate i reads from 2i s, so the
+    // furthest source out must clear the handles for every slate
+    for (let i = 0; i < bin.length; i++) {
+      const sourceOut = i * 2 * TICKS_PER_SECOND + bin[i].duration;
+      assert.ok(sourceOut <= MASTER_TICKS, `${bin[i].name} exceeds the master's handles`);
+    }
+  });
+
+  it("paints the clip faces in the house rose ramp only", () => {
+    assert.deepEqual(SLATE_FACES, ["#f472b6", "#ec4899", "#f9a8d4", "#db2777", "#f78dc3"]);
+    for (const face of SLATE_FACES) {
+      assert.ok(!BANNED.has(face), `a slate face rides a banned default: ${face}`);
+    }
+    // any index (even absurd ones) answers a face from the ramp — never invented
+    for (const index of [0, 1, 7, 999, -3, Number.NaN]) {
+      assert.ok(SLATE_FACES.includes(slateface(index)), `slateface(${index}) left the ramp`);
+    }
+  });
+});

package/tests/timeticks.test.ts

@@ -1,12 +1,12 @@
 // # timeticks.test — exact tick time: frame-rate math, sample clocks, the
-// rational container conversions and SMPTE drop-frame timecode, runnable with
-// the node built-in runner (no dependencies, no install):
-//   node --test tests/timeticks.test.ts
+// rational container conversions and SMPTE drop-frame timecode, runnable
+// with vitest:
+//   pnpm vitest run tests/timeticks.test.ts
 // Every test watches the two invariants the module promises: conversions are
 // exact inside the safe-integer range (no float drift) and nothing ever
 // throws — damaged input answers the default or null.
 import assert from "node:assert/strict";
-import { describe, it } from "node:test";
+import { describe, it } from "vitest";
 import {
   addticks,
   clampticks,

package/tests/transcodeplan.test.ts

@@ -1,17 +1,17 @@
-// # transcodeplan.test — honest unit tests for the transcode planner, runnable with
-// the node built-in runner (no install, no dependencies):
-//   node --test tests/transcodeplan.test.ts
+// # transcodeplan.test — honest unit tests for the transcode planner, runnable
+// with vitest:
+//   pnpm vitest run tests/transcodeplan.test.ts
 import assert from "node:assert/strict";
-import { describe, it } from "node:test";
+import { describe, it } from "vitest";
 import {
   buildTranscodePlan,
   estimateVariantBytes,
   evenDimension,
   parseBitrate,
-  TranscodeError,
-  validateRung,
   type SourceMedia,
+  TranscodeError,
   type TranscodeRung,
+  validateRung,
 } from "../transcodeplan.ts";
 
 /** The probed source the plan tests build from (the mediaprobe.ts shape). */
@@ -28,7 +28,15 @@ const SOURCE: SourceMedia = {
 const LADDER: TranscodeRung[] = [
   { id: "2160p", height: 2160, videoCodec: "avc1", audioCodec: "mp4a", videoBitrate: "16M", audioBitrate: "192K" },
   { id: "1080p", height: 1080, videoCodec: "avc1", audioCodec: "mp4a", videoBitrate: "4M", audioBitrate: "128K" },
-  { id: "720p", height: 720, videoCodec: "avc1", audioCodec: "mp4a", videoBitrate: "2500K", audioBitrate: "96K", fps: 24 },
+  {
+    id: "720p",
+    height: 720,
+    videoCodec: "avc1",
+    audioCodec: "mp4a",
+    videoBitrate: "2500K",
+    audioBitrate: "96K",
+    fps: 24,
+  },
   { id: "480p", height: 480, videoCodec: "vp09", audioCodec: "opus", videoBitrate: "1M", audioBitrate: "64K" },
 ];
 
@@ -116,7 +124,10 @@ describe("transcodeplan planner", () => {
   it("estimates the bytes per variant and the plan total", () => {
     const plan = buildTranscodePlan(SOURCE, LADDER);
     assert.equal(plan.variants[0].estimatedBytes, 30_960_000);
-    assert.equal(plan.estimatedBytes, plan.variants.reduce((sum, variant) => sum + variant.estimatedBytes, 0));
+    assert.equal(
+      plan.estimatedBytes,
+      plan.variants.reduce((sum, variant) => sum + variant.estimatedBytes, 0),
+    );
   });
 
   it("keeps the top of the ladder under maxRungs", () => {