@wenathlan/cadria 2.0.94 → 2.0.118

package/tests/audiotimbre.test.ts

@@ -0,0 +1,270 @@
+// # audiotimbre.test — the timbre layer of the audio→image paint feed
+// (mel/MFCC, envelopes, dynamics, onset shapes and the spectral descriptors),
+// runnable with vitest:
+//   pnpm vitest run tests/audiotimbre.test.ts
+// Every test watches the three invariants the module promises: the
+// descriptors separate the fixtures they were built for (noise vs tone, pad
+// vs click, warm vs bright, loud vs quiet), every answer stays finite under
+// damaged input, and the whole layer is deterministic — the same buffer
+// answers the same numbers on every run. Fixtures are synthesized (sines,
+// ramps, an LCG pseudo-noise) so the suite never touches the filesystem.
+import assert from "node:assert/strict";
+import { describe, it } from "vitest";
+import {
+  brightness,
+  DEFAULT_COEFFICIENTS,
+  dctii,
+  hztomel,
+  MEL_BANDS,
+  melFilterbank,
+  meltohz,
+  mfcc,
+  noisinessIndex,
+  rolloffSharpness,
+  spectralSlope,
+  timbreStats,
+  warmthIndex,
+} from "../audiotimbre.ts";
+import { DB_FLOOR, dynamicStats, onsetShapes, rmsEnvelope, todb, zcr, zcrrate } from "../audiotimbreenv.ts";
+
+const SR = 16000;
+
+function sine(freq: number, seconds: number, amp = 0.8, sr = SR): Float32Array {
+  const n = Math.round(seconds * sr);
+  const out = new Float32Array(n);
+  for (let i = 0; i < n; i++) out[i] = amp * Math.sin((2 * Math.PI * freq * i) / sr);
+  return out;
+}
+
+/** deterministic pseudo-noise (LCG — no Math.random anywhere in this suite). */
+function lcgNoise(n: number, seed = 7): Float32Array {
+  let state = seed >>> 0 || 1;
+  const out = new Float32Array(n);
+  for (let i = 0; i < n; i++) {
+    state = (Math.imul(state, 1103515245) + 12345) >>> 0;
+    out[i] = state / 2147483648 - 1;
+  }
+  return out;
+}
+
+/** one-bin magnitude spectrum (bin k of 257 covers k·31.25 Hz at the suite rate). */
+function spikeAt(bin: number, bins = 257): Float32Array {
+  const out = new Float32Array(bins);
+  out[bin] = 1;
+  return out;
+}
+
+function finiteDeep(value: unknown): boolean {
+  if (typeof value === "number") return Number.isFinite(value);
+  if (value instanceof Float32Array || value instanceof Float64Array) return Array.from(value).every(finiteDeep);
+  if (Array.isArray(value)) return value.every(finiteDeep);
+  if (value && typeof value === "object") return Object.values(value).every(finiteDeep);
+  return true;
+}
+
+describe("audiotimbre", () => {
+  it("answers 26 overlapping mel triangles with unit peaks", () => {
+    const bank = melFilterbank(257, SR);
+    assert.equal(bank.length, MEL_BANDS);
+    for (const row of bank) {
+      let peak = 0;
+      for (const w of row) {
+        assert.ok(w >= 0 && w <= 1);
+        peak = Math.max(peak, w);
+      }
+      assert.ok(peak > 0.9);
+    }
+    assert.deepEqual(melFilterbank(257, SR), bank);
+    assert.deepEqual(melFilterbank(257, Number.NaN)[0], new Float32Array(257));
+  });
+
+  it("round-trips the HTK mel scale", () => {
+    assert.ok(Math.abs(hztomel(1000) - 1000.5) < 1);
+    assert.ok(Math.abs(meltohz(hztomel(440)) - 440) < 1e-6);
+    assert.equal(hztomel(0), 0);
+    assert.equal(hztomel(Number.NaN), 0);
+    assert.equal(meltohz(-5), 0);
+  });
+
+  it("matches the known DCT-II of [1, 2, 3, 4]", () => {
+    const out = dctii([1, 2, 3, 4]);
+    assert.ok(Math.abs(out[0] - 10) < 1e-9);
+    assert.ok(Math.abs(out[1] + 3.1543220298889496) < 1e-9);
+    assert.ok(Math.abs(out[2]) < 1e-9);
+    assert.ok(Math.abs(out[3] + 0.2241707645839828) < 1e-9);
+    const flat = dctii([3, 3, 3, 3]);
+    assert.ok(Math.abs(flat[0] - 12) < 1e-9);
+    for (let k = 1; k < 4; k++) assert.ok(Math.abs(flat[k]) < 1e-9);
+    assert.equal(dctii([]).length, 0);
+  });
+
+  it("answers 13 finite coefficients for a sine-like magnitude frame", () => {
+    const out = mfcc(spikeAt(16), SR);
+    assert.equal(out.length, DEFAULT_COEFFICIENTS);
+    for (const v of out) assert.ok(Number.isFinite(v));
+    const again = mfcc(spikeAt(16), SR);
+    assert.deepEqual(again, out);
+  });
+
+  it("keeps the first mfcc coefficient stable across same-pitch frames", () => {
+    const stats = timbreStats(sine(440, 0.6), SR);
+    assert.ok(stats.mfccStd[0] < 0.5);
+    assert.ok(finiteDeep(stats.mfccMean) && finiteDeep(stats.mfccStd));
+  });
+
+  it("holds a constant-level sine steady in the rms envelope", () => {
+    const env = rmsEnvelope(sine(440, 0.5, 0.5));
+    assert.ok(env.length >= 14);
+    const target = 0.5 / Math.SQRT2;
+    for (const v of env) assert.ok(Math.abs(v - target) < 0.05 * target);
+  });
+
+  it("floors silence at −90 dB and reads full scale as 0 dB", () => {
+    assert.equal(todb(0), DB_FLOOR);
+    assert.equal(todb(1e-12), DB_FLOOR);
+    assert.equal(todb(Number.NaN), DB_FLOOR);
+    assert.equal(todb(1), 0);
+    assert.ok(Math.abs(todb(0.1) + 20) < 1e-9);
+    const silent = dynamicStats(rmsEnvelope(new Float32Array(4096)));
+    assert.equal(silent.minDb, DB_FLOOR);
+    assert.equal(silent.maxDb, DB_FLOOR);
+    assert.equal(silent.rangeDb, 0);
+    assert.equal(silent.crestFactor, 1);
+  });
+
+  it("reads a crescendo with a wide dynamic range", () => {
+    const n = SR;
+    const crescendo = new Float32Array(n);
+    for (let i = 0; i < n; i++) crescendo[i] = 0.01 + (0.99 * i) / (n - 1);
+    const stats = dynamicStats(rmsEnvelope(crescendo));
+    assert.ok(stats.rangeDb > 10);
+    assert.ok(stats.crestFactor >= 1);
+    assert.ok(stats.maxDb > stats.meanDb && stats.meanDb > stats.minDb);
+    assert.ok(finiteDeep(stats));
+  });
+
+  it("separates a fast click attack from a slow pad attack", () => {
+    const click = new Float32Array(4000);
+    for (let i = 0; i < 64; i++) click[i] = 0.9 * Math.exp(-i / 16);
+    const clickShape = onsetShapes(rmsEnvelope(click, { size: 256, hop: 128 }), [0], 8000, { hop: 128 })[0];
+    assert.ok(clickShape.attackMs < 10);
+    assert.ok(clickShape.peak > 0);
+    const pad = new Float32Array(8000);
+    for (let i = 0; i < 8000; i++) {
+      const t = i / 8000;
+      pad[i] = (t < 0.3 ? 0.01 + (0.99 * t) / 0.3 : 1) * Math.sin((2 * Math.PI * 220 * i) / 8000);
+    }
+    const padShape = onsetShapes(rmsEnvelope(pad, { size: 512, hop: 128 }), [0], 8000, { hop: 128 })[0];
+    assert.ok(padShape.attackMs > 50);
+    assert.ok(Number.isFinite(clickShape.decayMs) && clickShape.decayMs >= 0);
+    assert.ok(Number.isFinite(padShape.decayMs) && padShape.decayMs >= 0);
+  });
+
+  it("tolerates empty and out-of-range onset lists", () => {
+    const env = rmsEnvelope(sine(440, 0.25));
+    assert.deepEqual(onsetShapes(env, [], SR), []);
+    const shapes = onsetShapes(env, [-100, Number.NaN, 1e9], SR);
+    assert.equal(shapes.length, 3);
+    for (const shape of shapes) {
+      assert.ok(finiteDeep(shape) && shape.peak >= 0 && shape.attackMs >= 0 && shape.decayMs >= 0);
+    }
+  });
+
+  it("ranks the zero-crossing rate of a high sine above a low one", () => {
+    const high = zcrrate(sine(3000, 0.25));
+    const low = zcrrate(sine(300, 0.25));
+    assert.ok(high > 0.2 && low < 0.1);
+    assert.ok(high > low);
+    const frames = zcr(sine(3000, 0.25));
+    assert.ok(frames.length > 0 && Array.from(frames).every((v) => v > 0.2));
+    assert.equal(zcrrate(new Float32Array(0)), 0);
+  });
+
+  it("prefers the low-passed fixture in warmth", () => {
+    assert.ok(warmthIndex(spikeAt(8), SR) > 0.99);
+    assert.ok(warmthIndex(spikeAt(128), SR) < 0.01);
+    const warmStats = timbreStats(sine(250, 0.5), SR);
+    const brightStats = timbreStats(sine(4000, 0.5), SR);
+    assert.ok(warmStats.warmth > 0.9);
+    assert.ok(brightStats.warmth < 0.1);
+    assert.ok(warmStats.warmth > brightStats.warmth);
+  });
+
+  it("ranks noise above a tone in noisiness", () => {
+    const flat = new Float32Array(257).fill(1);
+    const tone = spikeAt(40);
+    const noiseMags = new Float32Array(257);
+    const rng = lcgNoise(257, 3);
+    for (let k = 0; k < 257; k++) noiseMags[k] = 0.1 + Math.abs(rng[k]) * 0.9;
+    assert.ok(noisinessIndex(flat) > 0.99);
+    assert.ok(noisinessIndex(tone) < 0.01);
+    assert.ok(noisinessIndex(noiseMags) > noisinessIndex(tone));
+    const noiseStats = timbreStats(lcgNoise(8000), SR);
+    const toneStats = timbreStats(sine(440, 0.5), SR);
+    assert.ok(noiseStats.noisiness > 0.2);
+    assert.ok(toneStats.noisiness < 0.1);
+    assert.ok(noiseStats.noisiness > toneStats.noisiness);
+  });
+
+  it("reads slope, rolloff sharpness and centroid from tilted spectra", () => {
+    const bins = 257;
+    const falling = new Float32Array(bins);
+    const rising = new Float32Array(bins);
+    const even = new Float32Array(bins);
+    for (let k = 0; k < bins; k++) {
+      falling[k] = 1 / (k + 1);
+      rising[k] = k + 1;
+      even[k] = 1;
+    }
+    assert.ok(spectralSlope(falling, SR) < -0.8);
+    assert.ok(spectralSlope(rising, SR) > 0.8);
+    assert.ok(Math.abs(spectralSlope(even, SR)) < 1e-6);
+    assert.ok(Math.abs(rolloffSharpness(spikeAt(8)) - 8 / 256) < 1e-9);
+    assert.ok(Math.abs(rolloffSharpness(spikeAt(240)) - 240 / 256) < 1e-9);
+    assert.equal(rolloffSharpness(new Float32Array(257)), 0);
+    assert.ok(Math.abs(brightness(spikeAt(8), SR) - 8 / 256) < 1e-9);
+    assert.ok(Math.abs(brightness(spikeAt(128), SR) - 0.5) < 1e-9);
+  });
+
+  it("answers the full TimbreStats contract shape", () => {
+    const stats = timbreStats(sine(440, 0.6), SR);
+    assert.equal(stats.mfccMean.length, 13);
+    assert.equal(stats.mfccStd.length, 13);
+    for (const v of stats.mfccMean) assert.ok(Number.isFinite(v));
+    for (const v of stats.mfccStd) assert.ok(v >= 0 && Number.isFinite(v));
+    assert.ok(stats.zcrMean >= 0 && stats.zcrMean <= 1);
+    assert.ok(stats.noisiness >= 0 && stats.noisiness <= 1);
+    assert.ok(stats.warmth >= 0 && stats.warmth <= 1);
+    assert.ok(stats.brightness >= 0 && stats.brightness <= 1);
+    assert.ok(Number.isFinite(stats.slopeMean));
+    assert.ok(stats.dynamics.rangeDb >= 0 && stats.dynamics.crestFactor >= 1);
+    const silent = timbreStats(new Float32Array(4096), SR);
+    assert.equal(silent.brightness, 0);
+    assert.equal(silent.noisiness, 0);
+    assert.equal(silent.warmth, 0.5);
+    assert.equal(silent.dynamics.minDb, DB_FLOOR);
+  });
+
+  it("is deterministic across runs", () => {
+    const mixed = new Float32Array(8000);
+    const noise = lcgNoise(8000, 11);
+    for (let i = 0; i < 8000; i++) mixed[i] = 0.5 * Math.sin((2 * Math.PI * 440 * i) / SR) + 0.2 * noise[i];
+    assert.deepEqual(timbreStats(mixed, SR), timbreStats(mixed, SR));
+  });
+
+  it("stays finite on damaged input everywhere", () => {
+    const broken = new Float32Array([Number.NaN, 1, Number.POSITIVE_INFINITY, -2, 0]);
+    assert.ok(finiteDeep(rmsEnvelope(broken)));
+    assert.ok(finiteDeep(dynamicStats([Number.NaN, 0.5, Number.POSITIVE_INFINITY, 0])));
+    assert.ok(finiteDeep(zcr(broken)) && finiteDeep(zcrrate(broken)));
+    assert.ok(finiteDeep(mfcc([Number.NaN, 2, Number.NaN, 1, 0, 3], SR)));
+    assert.ok(finiteDeep(spectralSlope([Number.NaN, 1, 2, 0, 4], SR)));
+    assert.ok(Number.isFinite(noisinessIndex([Number.NaN, 1, Number.NaN])));
+    assert.ok(Number.isFinite(warmthIndex([Number.NaN, 1, 2], Number.NaN)));
+    assert.ok(Number.isFinite(brightness([Number.NaN, 1], SR)));
+    const shapes = onsetShapes(new Float32Array(0), [Number.NaN], SR);
+    assert.equal(shapes.length, 1);
+    assert.ok(finiteDeep(shapes));
+    assert.ok(finiteDeep(timbreStats(broken, SR)));
+  });
+});

package/tests/audiotonality.test.ts

@@ -0,0 +1,289 @@
+// # audiotonality.test — the tonality layer: the hann-windowed STFT stand-in,
+// the a440 bin→pitch-class chroma fold, the Krumhansl-Schmuckler key estimate,
+// the chord timeline with greedy smoothing and the HarmonicStats summary,
+// runnable with vitest:
+//   pnpm vitest run tests/audiotonality.test.ts
+// Every fixture is a deterministic synthetic waveform (sines at
+// equal-tempered a440 pitches, octave 4+) and every test watches the two
+// invariants the module promises: clean tonal input lands on the right
+// tonic/chord, and damaged or silent input answers zeros or an empty
+// timeline instead of NaN.
+import assert from "node:assert/strict";
+import { describe, it } from "vitest";
+import {
+  chromagram,
+  chromaVector,
+  estimateKey,
+  harmonicStats,
+  keyName,
+  keyProfiles,
+  pitchClassNames,
+  spectrumFrames,
+} from "../audiotonality.ts";
+import { CHORD_INTERVALS, chordTemplates, detectChords } from "../audiotonalitychords.ts";
+
+const RATE = 44100;
+const FRAME_MS = (1000 * 2048) / 44100;
+
+function noteHz(midi: number): number {
+  return 440 * 2 ** ((midi - 69) / 12);
+}
+
+function tone(freq: number, seconds: number, amp: number): Float32Array {
+  const count = Math.round(seconds * RATE);
+  const out = new Float32Array(count);
+  for (let i = 0; i < count; i += 1) out[i] = amp * Math.sin((2 * Math.PI * freq * i) / RATE);
+  return out;
+}
+
+function chord(parts: readonly Float32Array[]): Float32Array {
+  const total = Math.max(...parts.map((part) => part.length));
+  const out = new Float32Array(total);
+  for (const part of parts) for (let i = 0; i < part.length; i += 1) out[i] += part[i];
+  return out;
+}
+
+function sequence(parts: readonly Float32Array[]): Float32Array {
+  const total = parts.reduce((sum, part) => sum + part.length, 0);
+  const out = new Float32Array(total);
+  let at = 0;
+  for (const part of parts) {
+    out.set(part, at);
+    at += part.length;
+  }
+  return out;
+}
+
+function meanChromaOf(frames: readonly Float32Array[]): Float32Array {
+  const mean = new Float32Array(12);
+  for (const frame of frames) for (let i = 0; i < 12; i += 1) mean[i] += frame[i];
+  for (let i = 0; i < 12; i += 1) mean[i] /= frames.length;
+  return mean;
+}
+
+/** sustained triad chroma frame (1/3 per chord tone) built from the shared interval table. */
+function triadChroma(root: number, quality: "maj" | "min"): Float32Array {
+  const chroma = new Float32Array(12);
+  for (const interval of CHORD_INTERVALS[quality]) chroma[(root + interval) % 12] = 1 / 3;
+  return chroma;
+}
+
+// sustained c major scale (c4…b4) with the tonic triad twice the amplitude of the passing tones
+const C_MAJOR_SAMPLES = chord([
+  tone(noteHz(60), 1, 0.3),
+  tone(noteHz(62), 1, 0.12),
+  tone(noteHz(64), 1, 0.3),
+  tone(noteHz(65), 1, 0.12),
+  tone(noteHz(67), 1, 0.3),
+  tone(noteHz(69), 1, 0.12),
+  tone(noteHz(71), 1, 0.12),
+]);
+
+// sustained a natural minor (a3…g4) with the a minor triad doubled in amplitude
+const A_MINOR_SAMPLES = chord([
+  tone(noteHz(57), 1, 0.3),
+  tone(noteHz(59), 1, 0.12),
+  tone(noteHz(60), 1, 0.3),
+  tone(noteHz(62), 1, 0.12),
+  tone(noteHz(64), 1, 0.3),
+  tone(noteHz(65), 1, 0.12),
+  tone(noteHz(67), 1, 0.12),
+]);
+
+// the c–f–g–c progression, four 0.4 s major triads in octave 4/5
+const CHORD_SECONDS = 0.4;
+function triadSamples(rootMidi: number): Float32Array {
+  return chord([0, 4, 7].map((interval) => tone(noteHz(rootMidi + interval), CHORD_SECONDS, 0.25)));
+}
+const PROGRESSION_SAMPLES = sequence([triadSamples(60), triadSamples(65), triadSamples(67), triadSamples(60)]);
+
+const SINE_SAMPLES = tone(440, 1, 0.2); // pure a440
+const PROGRESSION_CHROMA = chromagram(spectrumFrames(PROGRESSION_SAMPLES), RATE);
+
+describe("audiotonality chroma", () => {
+  it("folds a pure a440 sine into chroma bin 9", () => {
+    const [frame] = spectrumFrames(SINE_SAMPLES);
+    assert.ok(frame);
+    const chroma = chromaVector(frame, RATE);
+    for (let pc = 0; pc < 12; pc += 1) {
+      if (pc === 9) continue;
+      assert.ok(chroma[9] > chroma[pc], `bin 9 dominates bin ${pc}`);
+    }
+    assert.ok(chroma[9] > 0.7);
+  });
+
+  it("normalizes chroma to a unit l1 sum and guards NaN magnitudes", () => {
+    const magnitudes = new Float32Array(513);
+    magnitudes[5] = 2; // 5 × 44100/1024 ≈ 215 Hz → pitch class 9
+    magnitudes[2] = Number.NaN;
+    magnitudes[7] = Number.POSITIVE_INFINITY;
+    const chroma = chromaVector(magnitudes, RATE);
+    const sum = chroma.reduce((total, value) => total + value, 0);
+    assert.ok(Math.abs(sum - 1) < 1e-3);
+    assert.ok(Math.abs(chroma[9] - 1) < 1e-3);
+    assert.equal(
+      chroma.some((value) => !Number.isFinite(value)),
+      false,
+    );
+    const poisoned = new Float32Array(513).fill(Number.NaN);
+    const silent = chromaVector(poisoned, RATE);
+    assert.equal(
+      silent.reduce((total, value) => total + value, 0),
+      0,
+    );
+    assert.equal(
+      silent.some((value) => !Number.isFinite(value)),
+      false,
+    );
+  });
+
+  it("shapes one 12-bin frame per stft hop", () => {
+    const frames = spectrumFrames(SINE_SAMPLES);
+    assert.equal(frames.length, Math.floor((SINE_SAMPLES.length - 4096) / 2048) + 1);
+    assert.equal(frames[0].length, 2049);
+    const chroma = chromagram(frames, RATE);
+    assert.equal(chroma.length, frames.length);
+    for (const frame of chroma) {
+      assert.equal(frame.length, 12);
+      assert.ok(Math.abs(frame.reduce((total, value) => total + value, 0) - 1) < 1e-3);
+    }
+    assert.equal(chromagram(frames, RATE, 0).length, 0);
+  });
+});
+
+describe("audiotonality key", () => {
+  it("names pitch classes and keys in lowercase", () => {
+    assert.deepEqual([...pitchClassNames], ["c", "c#", "d", "d#", "e", "f", "f#", "g", "g#", "a", "a#", "b"]);
+    assert.equal(keyName({ tonic: 0, mode: "major" }), "c major");
+    assert.equal(keyName({ tonic: 9, mode: "minor" }), "a minor");
+    assert.equal(keyName({ tonic: Number.NaN, mode: "major" }), "");
+    assert.equal(keyProfiles.major.length, 12);
+    assert.equal(keyProfiles.minor.length, 12);
+  });
+
+  it("hears c major in the c major scale fixture", () => {
+    const chroma = chromagram(spectrumFrames(C_MAJOR_SAMPLES), RATE);
+    const key = estimateKey(meanChromaOf(chroma));
+    assert.equal(key.tonic, 0);
+    assert.equal(key.mode, "major");
+    assert.ok(key.strength > 0.5, `strength ${key.strength}`);
+    assert.equal(keyName(key), "c major");
+  });
+
+  it("hears a minor in the a minor fixture", () => {
+    const chroma = chromagram(spectrumFrames(A_MINOR_SAMPLES), RATE);
+    const key = estimateKey(meanChromaOf(chroma));
+    assert.equal(key.tonic, 9);
+    assert.equal(key.mode, "minor");
+    assert.ok(key.strength > 0.5, `strength ${key.strength}`);
+    assert.equal(keyName(key), "a minor");
+  });
+
+  it("ranks the 23 alternatives below the winner", () => {
+    const key = estimateKey(meanChromaOf(chromagram(spectrumFrames(C_MAJOR_SAMPLES), RATE)));
+    assert.equal(key.alternatives.length, 23);
+    assert.ok(key.alternatives.every((candidate) => candidate.strength <= key.strength));
+    for (let i = 1; i < key.alternatives.length; i += 1) {
+      assert.ok(key.alternatives[i - 1].strength >= key.alternatives[i].strength, `rank ${i}`);
+    }
+    assert.ok(key.alternatives.every((candidate) => candidate.tonic >= 0 && candidate.tonic <= 11));
+    assert.ok(key.alternatives.every((candidate) => candidate.mode === "major" || candidate.mode === "minor"));
+  });
+});
+
+describe("audiotonalitychords", () => {
+  it("folds the 7 qualities over 12 roots into 84 templates", () => {
+    assert.equal(chordTemplates.length, 84);
+    assert.equal(new Set(chordTemplates.map((template) => template.quality)).size, 7);
+    const maj = chordTemplates[0];
+    assert.equal(maj.root, 0);
+    assert.equal(maj.quality, "maj");
+    for (let pc = 0; pc < 12; pc += 1) {
+      assert.equal(maj.weights[pc], CHORD_INTERVALS.maj.includes(pc) ? 1 : 0);
+    }
+    assert.ok(chordTemplates.every((template) => template.weights.reduce((total, value) => total + value, 0) >= 1));
+  });
+
+  it("traces the c–f–g–c progression into four major segments", () => {
+    const timeline = detectChords(PROGRESSION_CHROMA, { minFramesPerChord: 4, frameMs: FRAME_MS });
+    assert.equal(timeline.length, 4);
+    assert.deepEqual(
+      timeline.map((segment) => segment.root),
+      [0, 5, 7, 0],
+    );
+    assert.ok(timeline.every((segment) => segment.quality === "maj"));
+    for (let i = 0; i < timeline.length; i += 1) {
+      assert.ok(Number.isFinite(timeline[i].startMs) && Number.isFinite(timeline[i].endMs));
+      assert.ok(timeline[i].endMs > timeline[i].startMs);
+      assert.ok(timeline[i].confidence > 0 && timeline[i].confidence <= 1);
+      if (i > 0) assert.ok(timeline[i].startMs >= timeline[i - 1].endMs, `segment ${i} monotonic`);
+    }
+  });
+
+  it("merges rapid chord flips into one segment", () => {
+    const frames: Float32Array[] = [];
+    for (let i = 0; i < 12; i += 1) frames.push(i % 2 === 0 ? triadChroma(0, "maj") : triadChroma(5, "maj"));
+    const timeline = detectChords(frames, { minFramesPerChord: 3, frameMs: 100 });
+    assert.equal(timeline.length, 1);
+    assert.equal(timeline[0].quality, "maj");
+    assert.equal(timeline[0].startMs, 0);
+    assert.equal(timeline[0].endMs, 1200);
+    assert.ok(Number.isFinite(timeline[0].confidence) && timeline[0].confidence <= 1);
+  });
+
+  it("answers an empty timeline for empty or silent chromagrams", () => {
+    assert.equal(detectChords([], { minFramesPerChord: 1 }).length, 0);
+    assert.equal(detectChords([new Float32Array(12), new Float32Array(12)], { minFramesPerChord: 1 }).length, 0);
+  });
+});
+
+describe("harmonicstats", () => {
+  it("scores flat noise more dissonant than a major triad", () => {
+    const flat: Float32Array[] = Array.from({ length: 12 }, () => new Float32Array(12).fill(1 / 12));
+    const triad: Float32Array[] = Array.from({ length: 12 }, () => triadChroma(0, "maj"));
+    const flatStats = harmonicStats(flat, RATE);
+    const triadStats = harmonicStats(triad, RATE);
+    assert.ok(flatStats.dissonanceIndex > triadStats.dissonanceIndex);
+    assert.ok(flatStats.dissonanceIndex > 0.95);
+    assert.ok(triadStats.dissonanceIndex < 0.6);
+  });
+
+  it("counts chord changes per second across the progression", () => {
+    const stats = harmonicStats(PROGRESSION_CHROMA, RATE);
+    assert.ok(stats.harmonicChangeRate > 2 && stats.harmonicChangeRate < 3.5, `rate ${stats.harmonicChangeRate}`);
+    const energy = stats.chromaEnergy.reduce((total, value) => total + value, 0);
+    assert.ok(Math.abs(energy - 1) < 1e-3);
+    assert.equal(stats.chromaEnergy.length, 12);
+  });
+
+  it("repeats bit-identical stats for the same fixture", () => {
+    const mean = meanChromaOf(PROGRESSION_CHROMA);
+    assert.deepEqual(estimateKey(mean), estimateKey(mean));
+    assert.deepEqual(harmonicStats(PROGRESSION_CHROMA, RATE), harmonicStats(PROGRESSION_CHROMA, RATE, { hop: 2048 }));
+  });
+
+  it("keeps every stats field finite and NaN-free", () => {
+    const stats = harmonicStats(PROGRESSION_CHROMA, RATE);
+    const flat = harmonicStats(
+      Array.from({ length: 4 }, () => new Float32Array(12)),
+      RATE,
+    );
+    const empty = harmonicStats([], RATE);
+    for (const candidate of [stats, flat, empty]) {
+      assert.ok(Number.isFinite(candidate.key.strength));
+      assert.ok(Number.isFinite(candidate.harmonicChangeRate));
+      assert.ok(Number.isFinite(candidate.dissonanceIndex));
+      assert.ok(candidate.chromaEnergy.every(Number.isFinite));
+      assert.ok(candidate.key.alternatives.every((alternative) => Number.isFinite(alternative.strength)));
+    }
+    assert.equal(empty.key.strength, 0);
+    assert.equal(empty.harmonicChangeRate, 0);
+    assert.equal(empty.dissonanceIndex, 0);
+    const timeline = detectChords(PROGRESSION_CHROMA, { frameMs: FRAME_MS });
+    assert.ok(
+      timeline.every((segment) =>
+        [segment.startMs, segment.endMs, segment.root, segment.confidence].every(Number.isFinite),
+      ),
+    );
+  });
+});

package/tests/blendmodes.test.ts

@@ -1,17 +1,17 @@
 // # blendmodes.test — the separable blend formulas of the compositing
 // standard over the 0-1 and 0-255 domains, the non-separable luminance
-// modes and the W3C alpha composite, runnable with the node built-in
-// runner (no dependencies, no install):
-//   node --test tests/blendmodes.test.ts
+// modes and the W3C alpha composite, runnable with vitest:
+//   pnpm vitest run tests/blendmodes.test.ts
 // Every test watches the two invariants the module promises: the channel
 // formulas match the published equations exactly and clamped inputs
 // never throw — damaged input answers the clamped or source value.
 import assert from "node:assert/strict";
-import { describe, it } from "node:test";
+import { describe, it } from "vitest";
 import {
   alphacomposite,
   blendchannel,
   blendchannel01,
+  blendlayerstack,
   blendpixel,
   blendrgb,
   blendrgb01,
@@ -90,4 +90,31 @@ describe("blendmodes", () => {
     assert.deepEqual(blendpixel("multiply", [200, 200, 200], [100, 100, 100]), [78, 78, 78]);
     assert.deepEqual(blendpixel("normal", [200, 200, 200], [10, 20, 30]), [10, 20, 30]);
   });
+
+  it("folds the layer stack and answers null on any dimension mismatch", () => {
+    const backdrop = { width: 1, height: 1, data: new Uint8ClampedArray([200, 200, 200, 255]) };
+    const gray = { width: 1, height: 1, data: new Uint8ClampedArray([100, 100, 100, 255]) };
+    const odd = { width: 2, height: 1, data: new Uint8ClampedArray([0, 0, 0, 255, 0, 0, 0, 255]) };
+    const folded = blendlayerstack("multiply", backdrop, [gray]);
+    assert.ok(folded);
+    assert.deepEqual([...folded.data.slice(0, 3)], [78, 78, 78]);
+    assert.equal(blendlayerstack("multiply", backdrop, [odd]), null);
+    assert.equal(blendlayerstack("multiply", odd, [gray]), null);
+  });
+
+  it("lets one layer override the stack-wide mode with its own blend identity", () => {
+    const backdrop = { width: 1, height: 1, data: new Uint8ClampedArray([200, 200, 200, 255]) };
+    const gray = { width: 1, height: 1, data: new Uint8ClampedArray([100, 100, 100, 255]) };
+    // stack rides normal (source passthrough); the overriding layer rides multiply.
+    const overridden = blendlayerstack("normal", backdrop, [{ ...gray, mode: "multiply" }]);
+    assert.ok(overridden);
+    assert.deepEqual([...overridden.data.slice(0, 3)], [78, 78, 78]);
+    // without the override the same stack rides the stack-wide multiply anyway.
+    const plain = blendlayerstack("multiply", backdrop, [gray]);
+    assert.deepEqual([...(plain as { data: Uint8ClampedArray }).data.slice(0, 3)], [...overridden.data.slice(0, 3)]);
+    // an explicit normal layer over the multiply stack passes the source through.
+    const passthrough = blendlayerstack("multiply", backdrop, [{ ...gray, mode: "normal" }]);
+    assert.ok(passthrough);
+    assert.deepEqual([...passthrough.data.slice(0, 3)], [100, 100, 100]);
+  });
 });

package/tests/colorconvert.test.ts

@@ -1,14 +1,13 @@
 // # colorconvert.test — the color space conversions of the studio: the
 // sRGB transfer curve through the decode table, the HSL and HSV cylinders,
 // the OKLab and OKLCH spheres, the studio-swing YCbCr families and the
-// hex round trip, runnable with the node built-in runner (no dependencies,
-// no install):
-//   node --test tests/colorconvert.test.ts
+// hex round trip, runnable with vitest:
+//   pnpm vitest run tests/colorconvert.test.ts
 // Every test watches the two invariants the module promises: conversions
 // round trip inside one byte of drift and clamped or damaged input never
 // throws — the channel clamp answers the nearest legal byte.
 import assert from "node:assert/strict";
-import { describe, it } from "node:test";
+import { describe, it } from "vitest";
 import {
   clamp01,
   clamprgb,

package/tests/easecurves.test.ts

@@ -1,13 +1,12 @@
 // # easecurves.test — the influence and speed easing model: the handle
 // algebra of the presets, the cubic bezier solver, the linear detection
-// and the key track evaluation with hold segments, runnable with the
-// node built-in runner (no dependencies, no install):
-//   node --test tests/easecurves.test.ts
+// and the key track evaluation with hold segments, runnable with vitest:
+//   pnpm vitest run tests/easecurves.test.ts
 // Every test watches the two invariants the module promises: the linear
 // preset answers the identity of its parameter and damaged curves or
 // times answer null or the nearest key instead of throwing.
 import assert from "node:assert/strict";
-import { describe, it } from "node:test";
+import { describe, it } from "vitest";
 import {
   bezierprogress,
   curvefromhandles,