@wenathlan/debonair 2.0.81 → 2.0.84

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wenathlan/debonair",
-  "version": "2.0.81",
+  "version": "2.0.84",
   "repository": {
     "type": "git",
     "url": "https://github.com/wenathlan/devthink"

package/tests/mixer.graph.test.ts

@@ -0,0 +1,165 @@
+// # mixer.graph.test — honest unit tests for the mixing graph model, runnable
+// with the node built-in runner (no dependencies, no install):
+//   node --test tests/mixer.graph.test.ts
+// The desk fixtures reuse the real mixer strips the site seed serves.
+import assert from "node:assert/strict";
+import { describe, it } from "node:test";
+import {
+  assertAcyclic,
+  assertGraph,
+  dbToLinear,
+  effectiveGainDb,
+  effectiveGains,
+  graphFromStrips,
+  linearToDb,
+  MixerGraphError,
+  patchChannel,
+  resolvePaths,
+  type MixerChannel,
+} from "../mixer.graph.ts";
+import { seedMixerStrips } from "../seed.ts";
+
+describe("mixer graph construction", () => {
+  it("builds the desk from the real seed strips, master included", () => {
+    const graph = graphFromStrips(seedMixerStrips);
+    assert.equal(graph.channels.length, seedMixerStrips.length);
+    assert.equal(graph.masterid, "Master");
+    assert.equal(graph.channels.find((channel) => channel.id === "Drums")?.gaindb, -4);
+  });
+
+  it("refuses a desk without a master row", () => {
+    const orphans = seedMixerStrips.map((strip) => ({ ...strip, master: false }));
+    assert.throws(() => graphFromStrips(orphans), (error: unknown) => {
+      assert.ok(error instanceof MixerGraphError);
+      assert.equal(error.code, "missing-master");
+      return true;
+    });
+    assert.throws(() => graphFromStrips([]), MixerGraphError);
+  });
+
+  it("validates duplicate ids, unknown sends and non finite gains", () => {
+    const graph = graphFromStrips(seedMixerStrips);
+    const duplicated: MixerChannel = { id: "Drums", name: "Drums", gaindb: 0, mute: false, solo: false, sends: [] };
+    assert.throws(() => assertGraph({ ...graph, channels: [...graph.channels, duplicated] }), (error: unknown) => {
+      assert.ok(error instanceof MixerGraphError);
+      assert.equal(error.code, "duplicate-channel");
+      return true;
+    });
+    const withbadsend = patchChannel(graph, "Drums", { sends: [{ targetid: "ghost", gaindb: -3 }] });
+    assert.throws(() => assertGraph(withbadsend), (error: unknown) => {
+      assert.ok(error instanceof MixerGraphError);
+      assert.equal(error.code, "unknown-send");
+      return true;
+    });
+    const withnangain = patchChannel(graph, "Drums", { gaindb: Number.NaN });
+    assert.throws(() => assertGraph(withnangain), (error: unknown) => {
+      assert.ok(error instanceof MixerGraphError);
+      assert.equal(error.code, "bad-gain");
+      return true;
+    });
+  });
+});
+
+describe("mixer graph cycles", () => {
+  const graph = graphFromStrips(seedMixerStrips);
+
+  it("rejects a send loop between two strips", () => {
+    const looped = patchChannel(
+      patchChannel(graph, "Drums", { sends: [{ targetid: "Bass", gaindb: -3 }] }),
+      "Bass",
+      { sends: [{ targetid: "Drums", gaindb: -3 }] },
+    );
+    assert.throws(() => assertAcyclic(looped), (error: unknown) => {
+      assert.ok(error instanceof MixerGraphError);
+      assert.equal(error.code, "cycle");
+      assert.equal(error.channelid, "Drums");
+      return true;
+    });
+  });
+
+  it("rejects a strip that sends to itself", () => {
+    const selfsend = patchChannel(graph, "Bass", { sends: [{ targetid: "Bass", gaindb: 0 }] });
+    assert.throws(() => assertAcyclic(selfsend), MixerGraphError);
+  });
+
+  it("accepts every strip sending straight to the master", () => {
+    const fanned = patchChannel(graph, "Drums", { sends: [{ targetid: "Master", gaindb: -6 }] });
+    assert.doesNotThrow(() => assertAcyclic(fanned));
+  });
+});
+
+describe("mixer graph gains", () => {
+  it("converts dB to linear and back", () => {
+    assert.equal(dbToLinear(0), 1);
+    assert.ok(Math.abs(dbToLinear(-6) - 0.501) < 0.001);
+    assert.equal(dbToLinear(Number.NEGATIVE_INFINITY), 0);
+    assert.equal(linearToDb(1), 0);
+    assert.ok(Math.abs(linearToDb(dbToLinear(-6)) - -6) < 1e-9, `expected the -6 dB roundtrip to hold, got ${linearToDb(dbToLinear(-6))}`);
+    assert.equal(linearToDb(0), Number.NEGATIVE_INFINITY);
+  });
+
+  it("chains the fader and the master additively in dB", () => {
+    const graph = graphFromStrips(seedMixerStrips);
+    // Drums -4 dB fader over the -2 dB master bus
+    assert.ok(Math.abs(effectiveGainDb(graph, "Drums") - -6) < 1e-9);
+    assert.equal(effectiveGainDb(graph, "Master"), -2);
+  });
+
+  it("mutes a strip to negative infinity and never mutates the input graph", () => {
+    const graph = graphFromStrips(seedMixerStrips);
+    const muted = patchChannel(graph, "Drums", { mute: true });
+    assert.equal(effectiveGainDb(muted, "Drums"), Number.NEGATIVE_INFINITY);
+    assert.equal(effectiveGainDb(graph, "Drums"), -6);
+  });
+
+  it("lets solo win: a soloed strip stays audible even muted, the rest falls silent", () => {
+    const graph = patchChannel(graphFromStrips(seedMixerStrips), "Bass", { solo: true, mute: true });
+    // solo wins over its own mute
+    assert.equal(effectiveGainDb(graph, "Bass"), -8);
+    // every unsoloed strip is silenced while a solo runs
+    assert.equal(effectiveGainDb(graph, "Drums"), Number.NEGATIVE_INFINITY);
+    assert.equal(effectiveGains(graph).Keys, Number.NEGATIVE_INFINITY);
+  });
+
+  it("answers the whole desk in one pass", () => {
+    const gains = effectiveGains(graphFromStrips(seedMixerStrips));
+    assert.equal(Object.keys(gains).length, seedMixerStrips.length);
+    assert.equal(gains.Master, -2);
+  });
+});
+
+describe("mixer graph routing paths", () => {
+  it("resolves the direct desk path when a strip sends nowhere", () => {
+    const graph = graphFromStrips(seedMixerStrips);
+    const paths = resolvePaths(graph, "Drums");
+    assert.equal(paths.length, 1);
+    assert.deepEqual(paths[0].hops, ["Drums", "Master"]);
+    assert.ok(Math.abs(paths[0].gaindb - -6) < 1e-9);
+    assert.ok(Math.abs(paths[0].linear - dbToLinear(-6)) < 1e-9);
+  });
+
+  it("resolves the send path with the send and master gains chained", () => {
+    const graph = patchChannel(graphFromStrips(seedMixerStrips), "Drums", { sends: [{ targetid: "Master", gaindb: -6 }] });
+    const paths = resolvePaths(graph, "Drums");
+    assert.equal(paths.length, 2);
+    assert.ok(Math.abs(paths[0].gaindb - -6) < 1e-9); // direct: -4 + -2
+    assert.ok(Math.abs(paths[1].gaindb - -12) < 1e-9); // send: -4 + -6 + -2
+  });
+
+  it("answers the master itself as a single hop", () => {
+    const graph = graphFromStrips(seedMixerStrips);
+    const paths = resolvePaths(graph, "Master");
+    assert.equal(paths.length, 1);
+    assert.deepEqual(paths[0].hops, ["Master"]);
+    assert.equal(paths[0].gaindb, -2);
+  });
+
+  it("refuses an unknown channel", () => {
+    const graph = graphFromStrips(seedMixerStrips);
+    assert.throws(() => resolvePaths(graph, "ghost"), (error: unknown) => {
+      assert.ok(error instanceof MixerGraphError);
+      assert.equal(error.code, "unknown-channel");
+      return true;
+    });
+  });
+});

package/tests/timeline.model.test.ts

@@ -0,0 +1,182 @@
+// # timeline.model.test — honest unit tests for the arrangement timeline
+// model (snap, overlap, split, trim, move), runnable with the node runner:
+//   node --test tests/timeline.model.test.ts
+// The clip fixtures mirror the shapes the studio timeline serves.
+import assert from "node:assert/strict";
+import { describe, it } from "node:test";
+import {
+  activeAt,
+  clipsOverlap,
+  MINIMUMDURATION,
+  moveClip,
+  snapClip,
+  snapToGrid,
+  splitClip,
+  TimelineModelError,
+  totalDuration,
+  trimClip,
+  validatePlacement,
+  type TimelineClip,
+} from "../timeline.model.ts";
+
+const GRID = { stepseconds: 0.25 };
+
+/** builds one clip with the given span on a track. */
+function clip(id: string, track: string, start: number, duration: number, label = id): TimelineClip {
+  return { id, track, label, start, duration };
+}
+
+describe("timeline grid snap", () => {
+  it("snaps a time to the nearest step", () => {
+    assert.equal(snapToGrid(1.04, GRID), 1);
+    assert.equal(snapToGrid(1.13, GRID), 1.25);
+    assert.equal(snapToGrid(0, GRID), 0);
+  });
+
+  it("cleans the float noise of the division", () => {
+    assert.equal(snapToGrid(0.3, { stepseconds: 0.1 }), 0.3);
+  });
+
+  it("snaps a clip start and rounds its duration to whole steps", () => {
+    const snapped = snapClip(clip("c1", "Drums", 1.04, 1.1), GRID);
+    assert.equal(snapped.start, 1);
+    assert.equal(snapped.duration, 1);
+    assert.equal(snapped.track, "Drums");
+  });
+
+  it("refuses a bad time or a bad grid", () => {
+    assert.throws(() => snapToGrid(-1, GRID), TimelineModelError);
+    assert.throws(() => snapToGrid(1, { stepseconds: 0 }), (error: unknown) => {
+      assert.ok(error instanceof TimelineModelError);
+      assert.equal(error.code, "bad-grid");
+      return true;
+    });
+  });
+});
+
+describe("timeline overlap", () => {
+  it("flags same track sharing time and spares touching edges", () => {
+    assert.equal(clipsOverlap(clip("a", "Drums", 0, 1), clip("b", "Drums", 0.5, 1)), true);
+    assert.equal(clipsOverlap(clip("a", "Drums", 0, 1), clip("b", "Drums", 1, 1)), false);
+  });
+
+  it("never flags different tracks", () => {
+    assert.equal(clipsOverlap(clip("a", "Drums", 0, 1), clip("b", "Bass", 0, 1)), false);
+  });
+
+  it("validates the placement and reports the offending pair", () => {
+    const arrangement = [clip("a", "Drums", 0, 2), clip("b", "Bass", 0, 4)];
+    assert.doesNotThrow(() => validatePlacement(clip("c", "Bass", 5, 1), arrangement));
+    assert.throws(() => validatePlacement(clip("c", "Drums", 1, 2), arrangement), (error: unknown) => {
+      assert.ok(error instanceof TimelineModelError);
+      assert.equal(error.code, "overlap");
+      assert.equal(error.clipid, "c");
+      return true;
+    });
+  });
+
+  it("skips the clip itself and honors the allowoverlap escape hatch", () => {
+    const arrangement = [clip("a", "Drums", 0, 2)];
+    assert.doesNotThrow(() => validatePlacement(clip("a", "Drums", 0, 2), arrangement));
+    assert.doesNotThrow(() => validatePlacement(clip("c", "Drums", 1, 2), arrangement, { allowoverlap: true }));
+  });
+});
+
+describe("timeline split", () => {
+  it("cuts one clip into two spans that cover the original", () => {
+    const [left, right] = splitClip(clip("c1", "Bass", 2, 1.5), 2.5);
+    assert.equal(left.id, "c1.a");
+    assert.equal(left.start, 2);
+    assert.equal(left.duration, 0.5);
+    assert.equal(right.id, "c1.b");
+    assert.equal(right.start, 2.5);
+    assert.equal(right.duration, 1);
+    assert.ok(!clipsOverlap(left, right));
+  });
+
+  it("refuses a split on the edges or outside the span", () => {
+    const target = clip("c1", "Bass", 2, 1.5);
+    assert.throws(() => splitClip(target, 2), (error: unknown) => {
+      assert.ok(error instanceof TimelineModelError);
+      assert.equal(error.code, "split-outside");
+      assert.equal(error.clipid, "c1");
+      return true;
+    });
+    assert.throws(() => splitClip(target, 3.5), TimelineModelError);
+    assert.throws(() => splitClip(target, 9), TimelineModelError);
+  });
+});
+
+describe("timeline trim", () => {
+  it("slides the start right and keeps the end", () => {
+    const trimmed = trimClip(clip("c1", "Drums", 2, 1.5), "start", 2.5);
+    assert.equal(trimmed.start, 2.5);
+    assert.equal(trimmed.duration, 1);
+  });
+
+  it("slides the end left and keeps the start", () => {
+    const trimmed = trimClip(clip("c1", "Drums", 2, 1.5), "end", 3);
+    assert.equal(trimmed.start, 2);
+    assert.equal(trimmed.duration, 1);
+  });
+
+  it("refuses a trim that leaves the span or breaks the minimum duration", () => {
+    const target = clip("c1", "Drums", 2, 1.5);
+    assert.throws(() => trimClip(target, "start", 1.9), (error: unknown) => {
+      assert.ok(error instanceof TimelineModelError);
+      assert.equal(error.code, "trim-invalid");
+      return true;
+    });
+    assert.throws(() => trimClip(target, "start", 3.5 - MINIMUMDURATION + 0.01), TimelineModelError);
+    assert.throws(() => trimClip(target, "end", 2 + MINIMUMDURATION - 0.01), TimelineModelError);
+    assert.throws(() => trimClip(target, "end", 9), TimelineModelError);
+  });
+});
+
+describe("timeline move", () => {
+  const arrangement = [clip("a", "Drums", 0, 2), clip("b", "Drums", 4, 2), clip("c", "Bass", 0, 4)];
+
+  it("moves a clip into a free span", () => {
+    const moved = moveClip(clip("d", "Drums", 7, 1), -0.5, arrangement);
+    assert.equal(moved.start, 6.5);
+  });
+
+  it("clamps the landing at zero", () => {
+    const moved = moveClip(clip("d", "Lead", 1, 1), -9, arrangement);
+    assert.equal(moved.start, 0);
+  });
+
+  it("rejects the landing on an occupied spot", () => {
+    assert.throws(() => moveClip(clip("d", "Drums", 2, 1), 1.5, arrangement), (error: unknown) => {
+      assert.ok(error instanceof TimelineModelError);
+      assert.equal(error.code, "overlap");
+      return true;
+    });
+  });
+
+  it("snaps the landing when a grid is passed and moves across tracks", () => {
+    const moved = moveClip(clip("d", "Drums", 6, 1), 0.9, arrangement, { grid: GRID });
+    assert.equal(moved.start, 7);
+    const rebassed = moveClip(clip("d", "Drums", 6, 1), 0, arrangement, { track: "Bass", allowoverlap: true });
+    assert.equal(rebassed.track, "Bass");
+  });
+});
+
+describe("timeline queries", () => {
+  const arrangement = [clip("a", "Drums", 0, 1), clip("b", "Bass", 0.5, 2), clip("c", "Lead", 5, 1)];
+
+  it("answers the clips playing at one instant", () => {
+    assert.deepEqual(activeAt(arrangement, 0.75).map((row) => row.id), ["a", "b"]);
+    assert.deepEqual(activeAt(arrangement, 1).map((row) => row.id), ["b"]);
+    assert.deepEqual(activeAt(arrangement, 10), []);
+  });
+
+  it("refuses a negative instant", () => {
+    assert.throws(() => activeAt(arrangement, -0.1), TimelineModelError);
+  });
+
+  it("measures the arrangement length by the last clip end", () => {
+    assert.equal(totalDuration(arrangement), 6);
+    assert.equal(totalDuration([]), 0);
+  });
+});