@wenathlan/cadria 2.0.94 → 2.0.117

package/tests/audiospectrum.test.ts

@@ -0,0 +1,257 @@
+// # audiospectrum.test — honest unit tests for the spectral layer, runnable
+// with vitest:
+//   pnpm vitest run tests/audiospectrum.test.ts
+// Fixtures are synthetic: pure sines on exact bins, DC, seeded noise and a
+// two-tone onset signal — every test is deterministic.
+import assert from "node:assert/strict";
+import { describe, it } from "vitest";
+import {
+  blackman,
+  FftError,
+  fft,
+  fftMagnitudes,
+  hamming,
+  hann,
+  stft,
+  stftFrameCount,
+  type WindowName,
+} from "../audiofft.ts";
+import {
+  BAND_EDGES_HZ,
+  BAND_NAMES,
+  bandEnergies,
+  hertzToMel,
+  melbands,
+  melToHertz,
+  spectralCentroid,
+  spectralFlatness,
+  spectralFlux,
+  spectralRolloff,
+  spectrogramImage,
+  summarizeSpectrum,
+} from "../audiospectrum.ts";
+
+const SAMPLE_RATE = 8000;
+const SIZE = 1024;
+const STEP = SAMPLE_RATE / SIZE; // 7.8125 Hz per bin
+
+/** one frame of a pure sine completing `cycles` periods inside the frame. */
+function sineFrame(cycles: number, size = SIZE): Float32Array {
+  const out = new Float32Array(size);
+  for (let i = 0; i < size; i++) out[i] = Math.sin((2 * Math.PI * cycles * i) / size);
+  return out;
+}
+
+/** deterministic seeded noise (LCG), values in [-1, 1). */
+function noiseFrame(size: number, seed: number): Float32Array {
+  let state = seed >>> 0;
+  const out = new Float32Array(size);
+  for (let i = 0; i < size; i++) {
+    state = (Math.imul(state, 1664525) + 1013904223) >>> 0;
+    out[i] = (state / 4294967296) * 2 - 1;
+  }
+  return out;
+}
+
+/** bin index of the largest magnitude. */
+function peakBin(magnitudes: Float32Array): number {
+  let best = 0;
+  for (let k = 1; k < magnitudes.length; k++) if (magnitudes[k] > magnitudes[best]) best = k;
+  return best;
+}
+
+/** sum of a typed array. */
+function total(values: ArrayLike<number>): number {
+  let acc = 0;
+  for (let i = 0; i < values.length; i++) acc += values[i];
+  return acc;
+}
+
+describe("audiofft", () => {
+  it("peaks a pure sine at the expected bin", () => {
+    const magnitudes = fftMagnitudes(sineFrame(8));
+    assert.equal(magnitudes.length, SIZE / 2 + 1);
+    const peak = peakBin(magnitudes);
+    assert.ok(Math.abs(peak - 8) <= 1, `peak at bin ${peak}, expected 8 ± 1`);
+  });
+
+  it("keeps DC energy at bin 0", () => {
+    const magnitudes = fftMagnitudes(new Float32Array(256).fill(1));
+    assert.ok(Math.abs(magnitudes[0] - 256) < 1e-3, `DC bin ${magnitudes[0]}`);
+    assert.equal(peakBin(magnitudes), 0);
+    assert.ok(total(magnitudes) - magnitudes[0] < 1e-2, "no energy outside bin 0");
+  });
+
+  it("conserves energy (Parseval)", () => {
+    const samples = noiseFrame(SIZE, 7);
+    const re = Float32Array.from(samples);
+    const im = new Float32Array(SIZE);
+    fft(re, im);
+    let timeEnergy = 0;
+    for (let i = 0; i < SIZE; i++) timeEnergy += samples[i] * samples[i];
+    let spectralEnergy = 0;
+    for (let k = 0; k < SIZE; k++) spectralEnergy += re[k] * re[k] + im[k] * im[k];
+    const ratio = spectralEnergy / (SIZE * timeEnergy);
+    assert.ok(Math.abs(ratio - 1) < 1e-4, `Parseval ratio ${ratio}`);
+  });
+
+  it("sums periodic windows to their documented totals", () => {
+    assert.ok(Math.abs(total(hann(SIZE)) - SIZE / 2) < 1e-6, `hann sums to ${total(hann(SIZE))}`);
+    assert.ok(Math.abs(total(hamming(SIZE)) - 0.54 * SIZE) < 1e-6);
+    assert.ok(Math.abs(total(blackman(SIZE)) - 0.42 * SIZE) < 1e-6);
+    assert.equal(hann(SIZE)[0], 0);
+  });
+
+  it("counts stft frames as ceil((n − size) / hop) + 1", () => {
+    assert.equal(stftFrameCount(5000, 1024, 300), Math.ceil((5000 - 1024) / 300) + 1);
+    assert.equal(stft(new Float32Array(5000), { size: 1024, hop: 300 }).length, 15);
+    assert.equal(stftFrameCount(200, 1024, 512), 0);
+    assert.equal(stft(new Float32Array(200), { size: 1024 }).length, 0);
+  });
+
+  it("returns one-sided magnitude frames, deterministically", () => {
+    const samples = noiseFrame(4096, 21);
+    const first = stft(samples, { size: 512, hop: 256, window: "hamming" });
+    const again = stft(samples, { size: 512, hop: 256, window: "hamming" });
+    assert.equal(first.length, stftFrameCount(4096, 512, 256));
+    for (let f = 0; f < first.length; f++) {
+      assert.equal(first[f].length, 512 / 2 + 1);
+      assert.deepEqual(first[f], again[f]);
+      for (const value of first[f]) assert.ok(Number.isFinite(value));
+    }
+  });
+
+  it("rejects invalid sizes and unknown windows", () => {
+    assert.throws(() => fft(new Float32Array(100), new Float32Array(100)), FftError);
+    assert.throws(() => fftMagnitudes(new Float32Array(32768)), FftError);
+    assert.throws(() => stft(new Float32Array(4096), { window: "kaiser" as WindowName }), FftError);
+  });
+});
+
+describe("audiospectrum", () => {
+  it("round-trips mel and hertz", () => {
+    assert.equal(melToHertz(0), 0);
+    assert.ok(Math.abs(hertzToMel(1000) - 1000) < 1, `1000 Hz is ${hertzToMel(1000)} mel`);
+    assert.ok(Math.abs(melToHertz(hertzToMel(440)) - 440) < 1e-9);
+  });
+
+  it("shapes the mel filterbank to the requested band count", () => {
+    const frame = fftMagnitudes(sineFrame(8));
+    assert.equal(melbands(frame, SAMPLE_RATE).length, 40);
+    assert.equal(melbands(frame, SAMPLE_RATE, 24).length, 24);
+    assert.equal(melbands(frame, SAMPLE_RATE, 1).length, 1);
+  });
+
+  it("reads a flat spectrum as equal mel bands", () => {
+    const bands = melbands(new Float32Array(SIZE / 2 + 1).fill(1), SAMPLE_RATE, 16);
+    for (let b = 0; b < bands.length; b++) {
+      assert.ok(Math.abs(bands[b] - 1) < 1e-6, `flat band ${b} reads ${bands[b]}, expected 1`);
+    }
+  });
+
+  it("keeps single-bin energy local to its mel triangles", () => {
+    const magnitudes = new Float32Array(SIZE / 2 + 1);
+    magnitudes[100] = 1; // 100 · 7.8125 Hz = 781.25 Hz
+    const bands = melbands(magnitudes, SAMPLE_RATE, 40);
+    let nonzero = 0;
+    let best = 0;
+    for (let b = 0; b < bands.length; b++) {
+      if (bands[b] > 0) nonzero++;
+      if (bands[b] > bands[best]) best = b;
+    }
+    assert.ok(nonzero >= 1 && nonzero <= 2, `${nonzero} bands lit by a single bin`);
+    const center = melToHertz((hertzToMel(SAMPLE_RATE / 2) * (best + 1)) / 41);
+    assert.ok(Math.abs(center - 781.25) < 100, `peak band center ${center} Hz, tone at 781.25 Hz`);
+  });
+
+  it("ranks centroids of low and high sines", () => {
+    const low = spectralCentroid(fftMagnitudes(sineFrame(8)), SAMPLE_RATE);
+    const high = spectralCentroid(fftMagnitudes(sineFrame(64)), SAMPLE_RATE);
+    assert.ok(low < high, `low centroid ${low} should sit under high ${high}`);
+    assert.ok(Math.abs(low - 8 * STEP) < STEP, `low centroid ${low}, expected near ${8 * STEP}`);
+    assert.ok(Math.abs(high - 64 * STEP) < STEP, `high centroid ${high}, expected near ${64 * STEP}`);
+  });
+
+  it("scores noise flatter than a sine", () => {
+    const tone = spectralFlatness(fftMagnitudes(sineFrame(8)));
+    const noise = spectralFlatness(fftMagnitudes(noiseFrame(SIZE, 3)));
+    assert.ok(tone >= 0 && tone <= 1 && noise >= 0 && noise <= 1);
+    assert.ok(noise > tone, `noise flatness ${noise} should beat tone ${tone}`);
+  });
+
+  it("reports zero flux for silence and steady frames", () => {
+    const silence = new Float32Array(513);
+    assert.equal(spectralFlux(silence, silence), 0);
+    const frame = fftMagnitudes(sineFrame(8));
+    assert.equal(spectralFlux(frame, frame), 0);
+  });
+
+  it("peaks flux at the note onsets of a two-tone fixture", () => {
+    const size = 256;
+    const toneA = sineFrame(4, size); // 125 Hz — bin 4
+    const toneB = sineFrame(24, size); // 750 Hz — bin 24
+    const both = new Float32Array(size);
+    for (let i = 0; i < size; i++) both[i] = toneA[i] + toneB[i];
+    const signal = new Float32Array(size * 5); // two silent frames, then the notes
+    for (let i = 0; i < size; i++) {
+      signal[size * 2 + i] = toneA[i];
+      signal[size * 3 + i] = toneA[i];
+      signal[size * 4 + i] = both[i];
+    }
+    const frames = stft(signal, { size, hop: size, window: "hann" });
+    assert.equal(frames.length, 5);
+    const fluxes = frames.map((frame, f) => (f === 0 ? 0 : spectralFlux(frame, frames[f - 1])));
+    assert.equal(fluxes[1], 0, "silence → silence is flat");
+    assert.equal(fluxes[3], 0, "steady tone A is flat");
+    assert.ok(fluxes[2] > 0 && fluxes[4] > 0, "both note onsets light up");
+    const peak = fluxes.indexOf(Math.max(...fluxes));
+    assert.ok(peak === 2 || peak === 4, `flux peak at frame ${peak}, expected an onset frame`);
+  });
+
+  it("normalizes bandBalance to sum 1", () => {
+    const frames = [fftMagnitudes(sineFrame(8)), fftMagnitudes(noiseFrame(SIZE, 11))];
+    assert.equal(bandEnergies(frames[0], SAMPLE_RATE).length, BAND_NAMES.length);
+    assert.equal(BAND_EDGES_HZ.length, BAND_NAMES.length + 1);
+    const summary = summarizeSpectrum(frames, SAMPLE_RATE);
+    assert.equal(summary.bandBalance.length, BAND_NAMES.length);
+    const balance = total(summary.bandBalance);
+    assert.ok(Math.abs(balance - 1) < 1e-9, `bandBalance sums to ${balance}`);
+    for (const share of summary.bandBalance) assert.ok(share >= 0 && share <= 1);
+    assert.ok(summary.brightnessIndex >= 0 && summary.brightnessIndex <= 1);
+    assert.ok(summary.centroidMean > 0 && summary.rolloffMean > 0);
+  });
+
+  it("decimates a spectrogram to width×height grayscale", () => {
+    const signal = new Float32Array(4096);
+    for (let i = 0; i < signal.length; i++) {
+      signal[i] = i < 2048 ? Math.sin((2 * Math.PI * 8 * i) / 512) : Math.sin((2 * Math.PI * 40 * i) / 512);
+    }
+    const frames = stft(signal, { size: 512, hop: 256 });
+    const image = spectrogramImage(frames, 12, 9);
+    assert.equal(image.length, 12 * 9);
+    let min = 255;
+    let max = 0;
+    for (const value of image) {
+      assert.ok(Number.isInteger(value) && value >= 0 && value <= 255, `gray value ${value} out of range`);
+      if (value < min) min = value;
+      if (value > max) max = value;
+    }
+    assert.equal(min, 0, "the quietest cell maps to 0");
+    assert.equal(max, 255, "the loudest cell maps to 255");
+    assert.deepEqual(image, spectrogramImage(frames, 12, 9));
+  });
+
+  it("maps digital silence to a black spectrogram", () => {
+    const image = spectrogramImage([new Float32Array(257), new Float32Array(257)], 4, 4);
+    assert.equal(image.length, 16);
+    for (const value of image) assert.equal(value, 0);
+  });
+
+  it("rises rolloff with tone frequency", () => {
+    const low = spectralRolloff(fftMagnitudes(sineFrame(8)), SAMPLE_RATE);
+    const high = spectralRolloff(fftMagnitudes(sineFrame(64)), SAMPLE_RATE);
+    assert.ok(low < high, `rolloff ${low} should sit under ${high}`);
+    assert.ok(Math.abs(low - 8 * STEP) < STEP, `low rolloff ${low}, expected near ${8 * STEP}`);
+    assert.ok(Math.abs(high - 64 * STEP) < STEP, `high rolloff ${high}, expected near ${64 * STEP}`);
+  });
+});

package/tests/audiostructure.test.ts

@@ -0,0 +1,292 @@
+// # audiostructure.test — honest unit tests for the structure layer, runnable
+// with vitest:
+//   pnpm vitest run tests/audiostructure.test.ts
+import assert from "node:assert/strict";
+import { describe, it } from "vitest";
+import {
+  analyzeStructure,
+  energyCurve,
+  frameEnergies,
+  labelSections,
+  noveltyCurve,
+  type Section,
+  type StructureStats,
+  structureBoundaries,
+  tensionCurve,
+} from "../audiostructure.ts";
+
+const RATE = 100; // 100 Hz analysis frames → 10 ms per frame
+const INTRO = [1, 0.2, 0.1, 0.05] as const;
+const BUILD = [0.2, 1, 0.5, 0.3] as const;
+const PEAK = [0.8, 0.1, 0.4, 1] as const;
+const OUTRO = [0.05, 0.3, 0.15, 0.1] as const;
+
+function scaled(dir: readonly number[], k: number): Float32Array {
+  return Float32Array.from(dir, (v) => v * k);
+}
+
+/** The synthetic song: quiet intro (9 s) → rising build (12 s) → loud peak (12 s) → quiet outro (9 s). */
+function songFrames(): Float32Array[] {
+  const frames: Float32Array[] = [];
+  for (let i = 0; i < 900; i += 1) frames.push(scaled(INTRO, 0.12));
+  for (let i = 0; i < 1200; i += 1) frames.push(scaled(BUILD, 0.4 + (0.6 * i) / 1199));
+  for (let i = 0; i < 1200; i += 1) frames.push(scaled(PEAK, 1.6));
+  for (let i = 0; i < 900; i += 1) frames.push(scaled(OUTRO, 0.1));
+  return frames;
+}
+
+/** The arch: quiet — loud — quiet, symmetric thirds. */
+function archFrames(): Float32Array[] {
+  const frames: Float32Array[] = [];
+  for (let i = 0; i < 1000; i += 1) frames.push(scaled(INTRO, 0.12));
+  for (let i = 0; i < 1000; i += 1) frames.push(scaled(PEAK, 1.6));
+  for (let i = 0; i < 1000; i += 1) frames.push(scaled(INTRO, 0.12));
+  return frames;
+}
+
+/** The flat line: one constant texture, no joints at all. */
+function flatFrames(): Float32Array[] {
+  const frames: Float32Array[] = [];
+  for (let i = 0; i < 1200; i += 1) frames.push(scaled([0.5, 0.4, 0.3, 0.2], 0.5));
+  return frames;
+}
+
+/** The wave: loud — quiet — loud — quiet, 8 s blocks. */
+function waveFrames(): Float32Array[] {
+  const frames: Float32Array[] = [];
+  for (let block = 0; block < 4; block += 1) {
+    const loud = block % 2 === 0;
+    for (let i = 0; i < 800; i += 1) frames.push(scaled(loud ? PEAK : INTRO, loud ? 1.6 : 0.12));
+  }
+  return frames;
+}
+
+/** Three identical 8 s blocks (A/B halves inside each block) — perfectly periodic. */
+function repeatingFrames(): Float32Array[] {
+  const frames: Float32Array[] = [];
+  for (let block = 0; block < 3; block += 1) {
+    for (let j = 0; j < 800; j += 1) {
+      const dir = j < 400 ? [1, 0.1, 0.3, 0.2] : [0.1, 0.9, 0.2, 0.6];
+      frames.push(scaled(dir, 0.7 + (0.2 * (j % 400)) / 399));
+    }
+  }
+  return frames;
+}
+
+/** The same internal motion, but every block shifts its directions — through-composed. */
+function throughFrames(): Float32Array[] {
+  const base = [
+    [1, 0.1, 0.3, 0.2],
+    [0.1, 0.9, 0.2, 0.6],
+  ] as const;
+  const frames: Float32Array[] = [];
+  for (let block = 0; block < 3; block += 1) {
+    for (let j = 0; j < 800; j += 1) {
+      const dir = base[j < 400 ? 0 : 1];
+      const vec = scaled(
+        [dir[(0 + block) % 4], dir[(1 + block) % 4], dir[(2 + block) % 4], dir[(3 + block) % 4]],
+        0.7 + (0.2 * (j % 400)) / 399,
+      );
+      frames.push(vec);
+    }
+  }
+  return frames;
+}
+
+function jointMax(novelty: Float32Array, ms: number): number {
+  const frame = Math.round((ms / 1000) * RATE);
+  let top = 0;
+  for (let i = Math.max(0, frame - 120); i <= Math.min(novelty.length - 1, frame + 120); i += 1)
+    top = Math.max(top, novelty[i]);
+  return top;
+}
+
+function maxOf(values: Float32Array): number {
+  let top = 0;
+  for (const v of values) top = Math.max(top, v);
+  return top;
+}
+
+describe("audiostructure novelty", () => {
+  it("spikes at the section joints and stays quiet inside sections", () => {
+    const novelty = noveltyCurve(songFrames(), { frameRate: RATE });
+    assert.equal(novelty.length, 4200);
+    for (const v of novelty) assert.ok(Number.isFinite(v) && v >= 0 && v <= 1);
+    assert.ok(jointMax(novelty, 9000) > 0.3, "intro → build joint spikes");
+    assert.ok(jointMax(novelty, 21000) > 0.3, "build → peak joint spikes");
+    assert.ok(jointMax(novelty, 33000) > 0.3, "peak → outro joint spikes");
+    for (let f = 300; f <= 500; f += 1) assert.ok(novelty[f] < 0.02, "intro interior stays quiet");
+    for (let f = 1400; f <= 1700; f += 1)
+      assert.ok(novelty[f] < 0.02, "the rising build keeps one direction, so it stays quiet");
+  });
+
+  it("answers empty for empty input or a broken frame rate", () => {
+    assert.equal(noveltyCurve([], { frameRate: RATE }).length, 0);
+    assert.equal(noveltyCurve(songFrames(), { frameRate: 0 }).length, 0);
+    assert.equal(noveltyCurve(songFrames(), { frameRate: Number.NaN }).length, 0);
+    assert.equal(frameEnergies([]).length, 0);
+  });
+});
+
+describe("audiostructure boundaries", () => {
+  it("finds one boundary per joint and respects minSectionMs", () => {
+    const novelty = noveltyCurve(songFrames(), { frameRate: RATE });
+    const bounds = structureBoundaries(novelty, RATE);
+    assert.equal(bounds.length, 3);
+    for (const joint of [9000, 21000, 33000]) {
+      assert.ok(
+        bounds.some((b) => Math.abs(b - joint) <= 1200),
+        `a boundary lands near ${joint}ms`,
+      );
+    }
+    for (let i = 1; i < bounds.length; i += 1)
+      assert.ok(bounds[i] - bounds[i - 1] >= 8000, "kept boundaries honor the minimum section");
+  });
+
+  it("a huge minSectionMs keeps only the strongest joint; a high threshold drops all", () => {
+    const novelty = noveltyCurve(songFrames(), { frameRate: RATE });
+    const starved = structureBoundaries(novelty, RATE, { minSectionMs: 60000 });
+    assert.equal(starved.length, 1, "strongest-first greedy keeps the single strongest boundary");
+    const apexMs = (novelty.reduce((best, v, i) => (v > novelty[best] ? i : best), 0) / RATE) * 1000;
+    assert.equal(
+      starved[0],
+      structureBoundaries(novelty, RATE).reduce((a, b) => (Math.abs(b - apexMs) < Math.abs(a - apexMs) ? b : a), 0),
+      "…which sits on the strongest novelty peak (the curve's global maximum, not its latest boundary)",
+    );
+    assert.deepEqual(structureBoundaries(novelty, RATE, { threshold: 2 }), []);
+    assert.deepEqual(structureBoundaries(new Float32Array(0), RATE), []);
+  });
+});
+
+describe("audiostructure sections", () => {
+  it("tiles the song into intro/build/peak/outro without gaps or overlaps", () => {
+    const rms = frameEnergies(songFrames());
+    const novelty = noveltyCurve(songFrames(), { frameRate: RATE });
+    const sections: Section[] = labelSections(structureBoundaries(novelty, RATE), rms, RATE);
+    assert.deepEqual(
+      sections.map((s) => s.role),
+      ["intro", "build", "peak", "outro"],
+    );
+    assert.equal(sections[0].startMs, 0);
+    assert.equal(sections[sections.length - 1].endMs, 42000);
+    for (let i = 1; i < sections.length; i += 1)
+      assert.equal(sections[i].startMs, sections[i - 1].endMs, "adjacent sections share their edge");
+    const [first, build, peak] = sections;
+    assert.ok(peak.energyMean > build.energyMean, "the peak section out-louds the build");
+    assert.ok(build.energyMean > first.energyMean, "the build out-louds the intro");
+    for (const s of sections) assert.ok(s.energyPeak >= s.energyMean);
+  });
+
+  it("a lone section is its own peak and broken inputs answer empty", () => {
+    const rms = frameEnergies(flatFrames());
+    assert.deepEqual(
+      labelSections([], rms, RATE).map((s) => ({ role: s.role, startMs: s.startMs, endMs: s.endMs })),
+      [{ role: "peak", startMs: 0, endMs: 12000 }],
+    );
+    assert.deepEqual(labelSections([6000], rms, 0), []);
+    assert.deepEqual(labelSections([6000], new Float32Array(0), RATE), []);
+    assert.deepEqual(
+      labelSections([60000, -5, Number.NaN], rms, RATE).map((s) => s.role),
+      ["peak"],
+      "out-of-range and NaN boundaries clamp or drop into one section",
+    );
+  });
+});
+
+describe("audiostructure curves", () => {
+  it("resamples the rms into a 0–1 peak-normalized energy curve", () => {
+    const rms = frameEnergies(songFrames());
+    const curve = energyCurve(rms);
+    assert.equal(curve.length, 64);
+    for (const v of curve) assert.ok(Number.isFinite(v) && v >= 0 && v <= 1);
+    assert.equal(maxOf(curve), 1, "the loudest sample normalizes to exactly 1");
+    assert.ok(curve[63] < 0.1, "the quiet outro tail stays near zero");
+    assert.equal(energyCurve(rms, { points: 16 }).length, 16);
+    const silent = energyCurve(new Float32Array(0));
+    assert.equal(silent.length, 64);
+    assert.ok([...silent].every((v) => v === 0));
+  });
+
+  it("blends novelty and energy with the documented weights", () => {
+    const rms = frameEnergies(songFrames());
+    const novelty = noveltyCurve(songFrames(), { frameRate: RATE });
+    const energy = energyCurve(rms);
+    const tension = tensionCurve(novelty, energy);
+    assert.equal(tension.length, energy.length);
+    for (const v of tension) assert.ok(Number.isFinite(v) && v >= 0 && v <= 1);
+    assert.ok(maxOf(tension) >= 0.6, "peak loudness alone carries the 0.6 energy weight");
+    assert.equal(tensionCurve(novelty, new Float32Array(0)).length, 0);
+  });
+});
+
+describe("audiostructure analyzeStructure", () => {
+  it("reads the synthetic song end to end", () => {
+    const stats: StructureStats = analyzeStructure(songFrames(), RATE);
+    assert.equal(stats.durationMs, 42000);
+    assert.deepEqual(
+      stats.sections.map((s) => s.role),
+      ["intro", "build", "peak", "outro"],
+    );
+    assert.equal(stats.narrativeShape, "rise", "the song rises into its peak");
+    assert.ok(
+      stats.peakSectionMs >= 20000 && stats.peakSectionMs <= 23000,
+      "peakSectionMs points at the peak section start",
+    );
+    assert.ok(stats.repetitionIndex >= 0 && stats.repetitionIndex <= 1);
+  });
+
+  it("classifies arch, flat and wave narratives", () => {
+    assert.equal(analyzeStructure(archFrames(), RATE).narrativeShape, "arch");
+    assert.equal(analyzeStructure(flatFrames(), RATE).narrativeShape, "flat");
+    assert.equal(analyzeStructure(waveFrames(), RATE).narrativeShape, "wave");
+  });
+
+  it("scores a repeating pattern above a through-composed twin", () => {
+    const repeating = analyzeStructure(repeatingFrames(), RATE).repetitionIndex;
+    const through = analyzeStructure(throughFrames(), RATE).repetitionIndex;
+    assert.ok(Number.isFinite(repeating) && Number.isFinite(through));
+    assert.ok(repeating >= 0 && repeating <= 1 && through >= 0 && through <= 1);
+    assert.ok(repeating - through > 0.3, `repeating ${repeating} must beat through-composed ${through}`);
+  });
+
+  it("is deterministic across runs", () => {
+    assert.deepEqual(analyzeStructure(songFrames(), RATE), analyzeStructure(songFrames(), RATE));
+    assert.deepEqual(analyzeStructure(archFrames(), RATE), analyzeStructure(archFrames(), RATE));
+    assert.deepEqual(noveltyCurve(songFrames(), { frameRate: RATE }), noveltyCurve(songFrames(), { frameRate: RATE }));
+  });
+
+  it("carries no NaN anywhere across every fixture", () => {
+    for (const frames of [songFrames(), archFrames(), flatFrames(), waveFrames(), repeatingFrames(), throughFrames()]) {
+      const novelty = noveltyCurve(frames, { frameRate: RATE });
+      const bounds = structureBoundaries(novelty, RATE);
+      const rms = frameEnergies(frames);
+      const energy = energyCurve(rms);
+      const stats = analyzeStructure(frames, RATE);
+      for (const v of novelty) assert.ok(Number.isFinite(v));
+      for (const b of bounds) assert.ok(Number.isFinite(b));
+      for (const s of stats.sections) {
+        for (const v of [s.startMs, s.endMs, s.energyMean, s.energyPeak]) assert.ok(Number.isFinite(v));
+      }
+      for (const v of energy) assert.ok(Number.isFinite(v));
+      for (const v of tensionCurve(novelty, energy)) assert.ok(Number.isFinite(v));
+      for (const v of [stats.durationMs, stats.peakSectionMs, stats.repetitionIndex]) assert.ok(Number.isFinite(v));
+    }
+  });
+
+  it("degenerate inputs answer total zeroed values", () => {
+    assert.deepEqual(analyzeStructure([], RATE), {
+      sections: [],
+      durationMs: 0,
+      peakSectionMs: 0,
+      repetitionIndex: 0,
+      narrativeShape: "flat",
+    });
+    const single = analyzeStructure([Float32Array.from([1, 1, 1, 1])], RATE);
+    assert.equal(single.durationMs, 10);
+    assert.equal(single.sections.length, 1);
+    assert.equal(single.sections[0].role, "peak");
+    assert.equal(single.narrativeShape, "flat");
+    assert.equal(single.repetitionIndex, 0);
+    assert.equal(analyzeStructure(songFrames(), 0).durationMs, 0);
+  });
+});