@wenathlan/cadria 2.0.93 → 2.0.117

package/tests/generation.test.ts

@@ -0,0 +1,228 @@
+// # generation.test — the storage seam of the generation pipeline, runnable
+// with vitest:
+//   pnpm vitest run tests/generation.test.ts
+// Two documented patterns live in the prologue below: (1) the TEMP database is
+// chosen by setting process.env.DATABASE_URL to file:./.tmp/generation.test.db
+// BEFORE the dynamic import of the db modules — db.ts resolves the url once at
+// module load, so static imports would hoist past it — and .tmp is wiped before
+// and after the run; (2) db.ts imports './seed' extensionless (vite-style), so
+// a resolve fallback hook (specifier + '.ts' on ERR_MODULE_NOT_FOUND) must be
+// registered before the import. The suites watch: idempotent schema boot, the
+// save/get round trip (deep-equal minus nothing), newest-first listing with the
+// 1–200 limit clamp, delete truthiness, the analysis side of the seam, the
+// 512 KiB JSON cap, id validation, bpm clamping, determinism of read after
+// write, and isolation between the two tables.
+import assert from "node:assert/strict";
+import { rmSync } from "node:fs";
+import { registerHooks } from "node:module";
+import { afterAll, describe, it } from "vitest";
+import type { AnalysisRecord, GenerationRecord } from "../generation.ts";
+
+const TMP_DIR = ".tmp";
+rmSync(TMP_DIR, { recursive: true, force: true });
+
+registerHooks({
+  resolve(specifier, context, next) {
+    try {
+      return next(specifier, context);
+    } catch (error) {
+      const code = (error as { code?: string }).code;
+      const relative = specifier.startsWith("./") || specifier.startsWith("../");
+      const last = specifier.split("/").pop() ?? "";
+      if (code === "ERR_MODULE_NOT_FOUND" && relative && !last.includes(".")) {
+        return next(`${specifier}.ts`, context);
+      }
+      throw error;
+    }
+  },
+});
+
+process.env.DATABASE_URL = `file:./${TMP_DIR}/generation.test.db`;
+const { ensureGenerationSchema, generationStore } = await import("../generation.ts");
+const { db } = await import("../db.ts");
+
+const store = generationStore();
+const MAX_JSON = 512 * 1024;
+
+afterAll(() => {
+  db.close();
+  rmSync(TMP_DIR, { recursive: true, force: true });
+});
+
+// one monotonic iso clock for every save, so newest-first stays exact even when
+// several suites share the temp database (vitest runs the its in order).
+const BASE = 1_700_000_000_000;
+let step = 0;
+function stamp(): string {
+  step += 1;
+  return new Date(BASE + step * 1_000).toISOString();
+}
+
+function generation(id: string, overrides: Partial<GenerationRecord> = {}): GenerationRecord {
+  return {
+    id,
+    seed: "9a7c1e2b44d0f836",
+    style: "opaline",
+    bpm: 124,
+    keyTonic: 9,
+    keyMode: "minor",
+    durationMs: 96000,
+    descriptorJson: JSON.stringify({ version: 1, seed: id }),
+    projectJson: JSON.stringify({ version: 1, width: 1080, height: 1080 }),
+    svgDigest: "d41d8cd98f00b204e9800998ecf8427e",
+    createdAt: stamp(),
+    ...overrides,
+  };
+}
+
+function analysis(id: string, overrides: Partial<AnalysisRecord> = {}): AnalysisRecord {
+  return {
+    id,
+    sourceKind: "file",
+    sampleRate: 44100,
+    durationMs: 96000,
+    bpm: 98,
+    keyName: "A minor",
+    reportJson: JSON.stringify({ version: 1, bpm: 98, tonic: 9, minor: 1 }),
+    createdAt: stamp(),
+    ...overrides,
+  };
+}
+
+function ids(records: { id: string }[]): string[] {
+  return records.map((record) => record.id);
+}
+
+describe("generation schema boot", () => {
+  it("is idempotent across two boots (no throw, tables intact)", () => {
+    assert.doesNotThrow(() => {
+      ensureGenerationSchema();
+      ensureGenerationSchema();
+    });
+    assert.ok(store.listGenerations(1).length <= 1);
+  });
+});
+
+describe("generation records", () => {
+  it("saves and reads a generation back as a deep-equal round trip", () => {
+    const record = generation("trip-a");
+    assert.deepEqual(store.saveGeneration(record), { ok: true });
+    assert.deepEqual(store.getGeneration("trip-a"), record);
+  });
+
+  it("answers null for a missing generation id", () => {
+    assert.equal(store.getGeneration("trip-nope"), null);
+  });
+
+  it("lists generations newest-first", () => {
+    for (const id of ["order-a", "order-b", "order-c"]) store.saveGeneration(generation(id));
+    assert.deepEqual(ids(store.listGenerations(3)), ["order-c", "order-b", "order-a"]);
+  });
+
+  it("honours a positive limit over the newest-first order", () => {
+    assert.deepEqual(ids(store.listGenerations(2)), ["order-c", "order-b"]);
+  });
+
+  it("clamps a limit below 1 up to one row", () => {
+    assert.equal(store.listGenerations(0).length, 1);
+    assert.equal(store.listGenerations(-10).length, 1);
+  });
+
+  it("caps the limit at 200 rows", () => {
+    for (let i = 0; i < 205; i += 1) store.saveGeneration(generation(`bulk-${i}`));
+    const page = store.listGenerations(Number.MAX_SAFE_INTEGER);
+    assert.equal(page.length, 200);
+    assert.equal(page[0].id, "bulk-204");
+  });
+
+  it("deletes an existing id (true) then reports the miss (false)", () => {
+    store.saveGeneration(generation("del-a"));
+    assert.equal(store.deleteGeneration("del-a"), true);
+    assert.equal(store.getGeneration("del-a"), null);
+    assert.equal(store.deleteGeneration("del-a"), false);
+    assert.equal(store.deleteGeneration("del-nope"), false);
+  });
+
+  it("rejects oversized JSON payloads with ok:false and writes nothing", () => {
+    const fat = "x".repeat(MAX_JSON + 1);
+    const fatDescriptor = store.saveGeneration(generation("fat-descriptor", { descriptorJson: fat }));
+    assert.equal(fatDescriptor.ok, false);
+    if (!fatDescriptor.ok) assert.match(fatDescriptor.error, /descriptorJson/);
+    const fatProject = store.saveGeneration(generation("fat-project", { projectJson: fat }));
+    assert.equal(fatProject.ok, false);
+    assert.equal(store.getGeneration("fat-descriptor"), null);
+    assert.equal(store.getGeneration("fat-project"), null);
+    const thin = store.saveGeneration(generation("fat-edge", { descriptorJson: "x".repeat(MAX_JSON) }));
+    assert.deepEqual(thin, { ok: true });
+  });
+
+  it("rejects invalid ids on every accessor", () => {
+    assert.equal(store.saveGeneration(generation("")).ok, false);
+    assert.equal(store.saveGeneration(generation("x".repeat(129))).ok, false);
+    assert.equal(store.getGeneration(""), null);
+    assert.equal(store.getGeneration("x".repeat(129)), null);
+    assert.equal(store.deleteGeneration(""), false);
+    assert.equal(store.deleteGeneration("x".repeat(129)), false);
+  });
+
+  it("clamps bpm into 20–300 and refuses non-finite values", () => {
+    store.saveGeneration(generation("bpm-hi", { bpm: 999 }));
+    assert.equal(store.getGeneration("bpm-hi")?.bpm, 300);
+    store.saveGeneration(generation("bpm-lo", { bpm: 5 }));
+    assert.equal(store.getGeneration("bpm-lo")?.bpm, 20);
+    store.saveGeneration(generation("bpm-frac", { bpm: 123.6 }));
+    assert.equal(store.getGeneration("bpm-frac")?.bpm, 124);
+    const nan = store.saveGeneration(generation("bpm-nan", { bpm: Number.NaN }));
+    assert.equal(nan.ok, false);
+    const inf = store.saveGeneration(generation("bpm-inf", { bpm: Number.POSITIVE_INFINITY }));
+    assert.equal(inf.ok, false);
+    assert.equal(store.getGeneration("bpm-nan"), null);
+  });
+
+  it("reads back deterministically after write", () => {
+    const record = generation("det-a", { descriptorJson: JSON.stringify({ deep: { nested: [1, 2, 3] } }) });
+    store.saveGeneration(record);
+    const first = store.getGeneration("det-a");
+    const second = store.getGeneration("det-a");
+    assert.deepEqual(first, second);
+    assert.deepEqual(first, record);
+    assert.equal(typeof first?.createdAt, "string");
+  });
+});
+
+describe("analysis records", () => {
+  it("saves and reads an analysis back as a deep-equal round trip", () => {
+    const record = analysis("an-trip");
+    assert.deepEqual(store.saveAnalysis(record), { ok: true });
+    assert.deepEqual(store.getAnalysis("an-trip"), record);
+  });
+
+  it("lists analyses newest-first with the limit applied", () => {
+    for (const id of ["an-a", "an-b", "an-c"]) store.saveAnalysis(analysis(id));
+    assert.deepEqual(ids(store.listAnalyses(200)), ["an-c", "an-b", "an-a", "an-trip"]);
+    assert.deepEqual(ids(store.listAnalyses(2)), ["an-c", "an-b"]);
+    assert.equal(store.listAnalyses(0).length, 1);
+  });
+
+  it("rejects an oversized reportJson with ok:false", () => {
+    const result = store.saveAnalysis(analysis("an-fat", { reportJson: "y".repeat(MAX_JSON + 1) }));
+    assert.equal(result.ok, false);
+    if (!result.ok) assert.match(result.error, /reportJson/);
+    assert.equal(store.getAnalysis("an-fat"), null);
+  });
+});
+
+describe("isolation", () => {
+  it("keeps generations and analyses in separate tables", () => {
+    store.saveGeneration(generation("shared"));
+    store.saveAnalysis(analysis("shared"));
+    const gen = store.getGeneration("shared");
+    const an = store.getAnalysis("shared");
+    assert.ok(gen && "svgDigest" in gen);
+    assert.ok(an && "keyName" in an);
+    assert.equal(store.deleteGeneration("shared"), true);
+    assert.equal(store.getGeneration("shared"), null);
+    assert.equal(store.getAnalysis("shared")?.id, "shared");
+    assert.equal(store.deleteGeneration("shared"), false);
+  });
+});

package/tests/imageexport.test.ts

@@ -0,0 +1,443 @@
+// # imageexport.test — the export/integration layer contract AND the wave-2
+// end-to-end. Runnable with vitest:
+//   pnpm vitest run tests/imageexport.test.ts
+// The fixture is a fully documented 32-dim AudioDescriptor (every value pinned
+// to its audiofeatures.ts DIM_ORDER position), and the integration chain runs
+// exactly what wave 2 shipped: synthPalette (b1) → compositionGrid /
+// compositionBlocks + rhythmScatter (b2) → synthTexture (b3) → synthMotion
+// (b4) → exportBundle (b8). b5 imagestyles (styleForDescriptor), b6 imageproject
+// (buildImageProject) and b7 imagerender (renderSvg) had not landed when this
+// suite was written — toExportProject stands in for buildImageProject at the
+// documented structural contract (see imageexport.ts header). Every assertion
+// is deterministic: no randomness, no clock, same inputs → same digests.
+import assert from "node:assert/strict";
+import { describe, it } from "vitest";
+import type { AudioDescriptor } from "../audioattributes.ts";
+import type { ExportProject } from "../imageexport.ts";
+import {
+  ANIMATION_FPS,
+  buildAnimationManifest,
+  buildSvgArtifact,
+  ExportError,
+  exportBundle,
+  exportPlan,
+  fnv1aHex,
+  MANIFEST_FRAME_CAP,
+  PNG_COMPRESS_FACTOR,
+  PNG_SIZE_LADDER,
+  perturbFrame,
+  thumbnailSignature,
+  toExportProject,
+} from "../imageexport.ts";
+import { compositionBlocks, compositionGrid, rhythmScatter } from "../synthcomposition.ts";
+import { synthMotion } from "../synthmotion.ts";
+import { synthPalette } from "../synthpalette.ts";
+import { synthTexture } from "../synthtexture.ts";
+
+// ---- the documented 32-dim fixture (values per DIM_ORDER position) ----
+// 0-6 spectral: centroid .42, spread .38, rolloff .55, flatness .18, flux .35,
+//   fluxVariance .28, brightness .60 — a bright, tonal, moving mix.
+// 7-11 rhythm: tempo .50 (bpm pinned via scalar), pulseConfidence .82,
+//   onsetDensity .42 (→ 3.36 onsets/s), grooveRegularity .71, swing .58.
+// 12-15 harmony: tonalCenter .75 (tonic 8 = g#), keyStrength .64,
+//   harmonicChange .40, dissonance .22 — a strong minor-leaning key.
+// 16-21 timbre: noisiness .34, warmth .61, timbreBrightness .58, textureSlope
+//   .45, zeroCrossings .11, contrast .52 — warm mid mix, bold dynamics.
+// 22-27 energy/structure: punch .66, duration .35, peakMass .72, repetition
+//   .42, narrativeContour .75 (arch), sectionDensity .60 — punchy arch build.
+// 28-31 cross: brightnessPulse .30, energyDrive .68, bandTilt .40,
+//   moodShadow .35 — energetic drive, mild minor depth.
+const FIXTURE_VECTOR: number[] = [
+  0.42, 0.38, 0.55, 0.18, 0.35, 0.28, 0.6, 0.5, 0.82, 0.42, 0.71, 0.58, 0.75, 0.64, 0.4, 0.22, 0.34, 0.61, 0.58, 0.45,
+  0.11, 0.52, 0.66, 0.35, 0.72, 0.42, 0.75, 0.6, 0.3, 0.68, 0.4, 0.35,
+];
+
+/** the fused fixture descriptor: 32 dims above, bpm 120 → 500 ms motion loop. */
+function fixture(): AudioDescriptor {
+  return { version: 1, seed: "b7e5a1c93d204f68", vector: [...FIXTURE_VECTOR], scalar: { bpm: 120, downbeat: 4 } };
+}
+
+/** runs the shipped wave-2 chain (b1 → b4) and hands the stack to b8's seam. */
+function chainProject(id = "e2e-loop"): ExportProject {
+  const d = fixture();
+  const blocks = rhythmScatter(d, compositionBlocks(d, compositionGrid(d)));
+  return toExportProject(id, {
+    descriptor: d,
+    palette: synthPalette(d), // b1 imagestyles/styleForDescriptor lands upstream of this
+    blocks, // b2 compositionBlocks + rhythmScatter
+    texture: synthTexture(d), // b3
+    motion: synthMotion(
+      d,
+      blocks.map((b) => b.role),
+    ), // b4
+  });
+}
+
+/** asserts fn throws ExportError and answers its taxonomy code. */
+function codeOf(fn: () => unknown): string {
+  try {
+    fn();
+  } catch (e) {
+    assert.ok(e instanceof ExportError, `expected ExportError, got ${String(e)}`);
+    return (e as ExportError).code;
+  }
+  assert.fail("expected ExportError, nothing thrown");
+  return "";
+}
+
+const HEX8 = /^[0-9a-f]{8}$/;
+
+describe("wave-2 fixture + chain", () => {
+  it("fixture is a documented 32-dim descriptor", () => {
+    const d = fixture();
+    assert.equal(d.vector.length, 32);
+    for (const v of d.vector) assert.ok(Number.isFinite(v) && v >= 0 && v <= 1, `dim out of range: ${v}`);
+    assert.match(d.seed, /^[0-9a-f]{16}$/);
+    assert.equal(d.scalar.bpm, 120);
+  });
+
+  it("the full wave-2 chain runs deterministically end to end", () => {
+    const a = chainProject();
+    const b = chainProject();
+    assert.deepStrictEqual(a.palette, b.palette);
+    assert.deepStrictEqual(a.blocks, b.blocks);
+    assert.deepStrictEqual(a.texture, b.texture);
+    assert.deepStrictEqual(a.motion, b.motion);
+    const roles = new Set(a.blocks.map((x) => x.role));
+    for (const role of roles) assert.ok(["hero", "cadre", "field", "edge"].includes(role));
+    assert.ok(a.blocks.length >= 5); // hero + ring + fill from a 6-col grid
+    for (const x of a.blocks) {
+      for (const v of [x.rect.x, x.rect.y, x.rect.w, x.rect.h]) assert.ok(v >= 0 && v <= 1);
+    }
+    assert.equal(a.motion.loopMs, 500); // 120 bpm → one beat per 500 ms
+  });
+});
+
+describe("exportPlan", () => {
+  it("svg plan measures the real master and leaves timing null", () => {
+    const p = chainProject();
+    const plan = exportPlan(p, { format: "svg" });
+    assert.equal(plan.format, "svg");
+    assert.equal(plan.width, 1080);
+    assert.equal(plan.height, 1080);
+    assert.equal(plan.fps, null);
+    assert.equal(plan.loopMs, null);
+    assert.equal(plan.frames, null);
+    assert.ok(plan.qualityNote.length > 0);
+    assert.equal(plan.estimatedBytes, buildSvgArtifact(p, { width: 1080, height: 1080 }).bytes.length);
+    assert.ok(plan.estimatedBytes > 0);
+  });
+
+  it("png plan locks to the documented ladder and models RGBA deflate", () => {
+    const p = chainProject();
+    for (const rung of PNG_SIZE_LADDER) {
+      const plan = exportPlan(p, { format: "png", width: rung.width });
+      assert.equal(plan.width, rung.width);
+      assert.equal(plan.height, rung.height);
+      assert.equal(plan.estimatedBytes, Math.ceil(rung.width * rung.height * 4 * PNG_COMPRESS_FACTOR));
+      assert.equal(plan.fps, null);
+    }
+    assert.equal(
+      codeOf(() => exportPlan(p, { format: "png", width: 720 })),
+      "export-size",
+    );
+    assert.equal(
+      codeOf(() => exportPlan(p, { format: "png", width: 1440, height: 2160 })),
+      "export-size",
+    );
+  });
+
+  it("webm/gif require loopMs > 0 — export-loop-required", () => {
+    const p = chainProject();
+    assert.equal(
+      codeOf(() => exportPlan(p, { format: "webm", fps: 30 })),
+      "export-loop-required",
+    );
+    assert.equal(
+      codeOf(() => exportPlan(p, { format: "webm", fps: 30, loopMs: 0 })),
+      "export-loop-required",
+    );
+    assert.equal(
+      codeOf(() => exportPlan(p, { format: "gif", fps: 30, loopMs: -5 })),
+      "export-loop-required",
+    );
+    const plan = exportPlan(p, { format: "webm", fps: 30, loopMs: 500 });
+    assert.equal(plan.loopMs, 500);
+    assert.equal(plan.fps, 30);
+    assert.equal(plan.frames, 15); // round(500·30/1000)
+    assert.ok(plan.estimatedBytes > 0);
+  });
+
+  it("animation fps rungs are exactly 24/30/60 — export-format", () => {
+    const p = chainProject();
+    assert.deepStrictEqual([...ANIMATION_FPS], [24, 30, 60]);
+    assert.equal(
+      codeOf(() => exportPlan(p, { format: "webm", fps: 25, loopMs: 500 })),
+      "export-format",
+    );
+    assert.equal(
+      codeOf(() => exportPlan(p, { format: "gif", fps: 60.5, loopMs: 500 })),
+      "export-format",
+    );
+    assert.equal(
+      codeOf(() => exportPlan(p, { format: "webm", fps: 12, loopMs: 500 })),
+      "export-format",
+    );
+    assert.equal(exportPlan(p, { format: "webm", loopMs: 500 }).fps, 30); // documented default
+    assert.equal(exportPlan(p, { format: "webm", fps: 24, loopMs: 500 }).fps, 24);
+  });
+
+  it("unknown formats and wild sizes refuse", () => {
+    const p = chainProject();
+    assert.equal(
+      codeOf(() => exportPlan(p, { format: "jpeg" as never })),
+      "export-format",
+    );
+    assert.equal(
+      codeOf(() => exportPlan(p, { format: "mp4" as never })),
+      "export-format",
+    );
+    assert.equal(
+      codeOf(() => exportPlan(p, { format: "svg", width: 32 })),
+      "export-size",
+    );
+    assert.equal(
+      codeOf(() => exportPlan(p, { format: "svg", width: 8192 })),
+      "export-size",
+    );
+    assert.equal(
+      codeOf(() => exportPlan(p, { format: "webm", width: 8192, fps: 30, loopMs: 500 })),
+      "export-size",
+    );
+    assert.equal(
+      codeOf(() => exportPlan(p, { format: "svg", width: 800.5 })),
+      "export-size",
+    );
+  });
+
+  it("plans are deterministic and estimates finite + positive for every format", () => {
+    const p = chainProject();
+    for (const format of ["svg", "png", "webm", "gif"] as const) {
+      const options = { format, width: 1080, fps: 30, loopMs: 500 } as const;
+      const a = exportPlan(p, options);
+      const b = exportPlan(p, options);
+      assert.deepStrictEqual(a, b, `${format} plan drifted`);
+      assert.ok(Number.isFinite(a.estimatedBytes) && a.estimatedBytes > 0);
+      assert.ok(a.width > 0 && a.height > 0);
+    }
+  });
+});
+
+describe("svg master artifact", () => {
+  it("svg artifact: filename, well-formed bytes, fnv1a digest", () => {
+    const p = chainProject();
+    const a = buildSvgArtifact(p);
+    assert.equal(a.filename, "e2e-loop.svg");
+    assert.ok(a.bytes.startsWith('<svg xmlns="http://www.w3.org/2000/svg"'));
+    assert.ok(a.bytes.endsWith("</svg>"));
+    assert.equal(a.digest, fnv1aHex(a.bytes));
+    assert.match(a.digest, HEX8);
+    assert.ok(!a.bytes.includes("NaN") && !a.bytes.includes("undefined"));
+    const rects = a.bytes.split("<rect").length - 1;
+    assert.ok(rects >= p.blocks.length + 1); // every block + the surface ground
+    assert.ok(a.bytes.includes(p.palette.surface) && a.bytes.includes(p.palette.anchor));
+  });
+
+  it("svg artifact is byte-stable across runs and size-aware", () => {
+    const p = chainProject();
+    assert.deepStrictEqual(buildSvgArtifact(p), buildSvgArtifact(chainProject()));
+    const small = buildSvgArtifact(p, { width: 512, height: 384 });
+    assert.deepStrictEqual(small, buildSvgArtifact(p, { width: 512, height: 384 }));
+    assert.ok(small.bytes.startsWith('<svg xmlns="http://www.w3.org/2000/svg" width="512" height="384"'));
+    assert.notEqual(small.bytes, buildSvgArtifact(p).bytes);
+  });
+
+  it("export-empty: blank id, unreadable palette, empty cast", () => {
+    const p = chainProject();
+    assert.equal(
+      codeOf(() => toExportProject("", { descriptor: fixture() })),
+      "export-empty",
+    );
+    assert.equal(
+      codeOf(() => buildSvgArtifact({ ...p, blocks: [] })),
+      "export-empty",
+    );
+    const bad = { ...p, palette: { anchor: 1 } } as unknown as ExportProject;
+    assert.equal(
+      codeOf(() => buildSvgArtifact(bad)),
+      "export-empty",
+    );
+  });
+});
+
+describe("animation manifest + frame signatures", () => {
+  it("webm manifest: 15 even frames, sorted, strictly inside the loop", () => {
+    const p = chainProject();
+    const plan = exportPlan(p, { format: "webm", fps: 30, loopMs: 500 });
+    const m = buildAnimationManifest(p, plan);
+    assert.equal(m.fps, 30);
+    assert.equal(m.loopMs, 500);
+    assert.ok(m.frames.length <= MANIFEST_FRAME_CAP);
+    assert.equal(m.frames.length, 15);
+    m.frames.forEach((f, i) => {
+      assert.equal(f.index, i);
+      assert.match(f.signature, HEX8);
+      assert.ok(f.tMs >= 0 && f.tMs < 500);
+    });
+    for (let i = 1; i < m.frames.length; i += 1) assert.ok(m.frames[i].tMs > m.frames[i - 1].tMs);
+    assert.equal(new Set(m.frames.map((f) => f.signature)).size, m.frames.length);
+  });
+
+  it("manifest caps at exactly 128 frames for long loops", () => {
+    const p = chainProject();
+    const plan = exportPlan(p, { format: "gif", fps: 60, loopMs: 60000 });
+    assert.equal(plan.frames, MANIFEST_FRAME_CAP);
+    const m = buildAnimationManifest(p, plan);
+    assert.equal(m.frames.length, MANIFEST_FRAME_CAP);
+    for (let i = 1; i < m.frames.length; i += 1) assert.ok(m.frames[i].tMs > m.frames[i - 1].tMs);
+    assert.ok(m.frames[m.frames.length - 1].tMs < 60000);
+  });
+
+  it("manifest refuses static plans and loopless plans", () => {
+    const p = chainProject();
+    const svgPlan = exportPlan(p, { format: "svg" });
+    assert.equal(
+      codeOf(() => buildAnimationManifest(p, svgPlan)),
+      "export-format",
+    );
+    const webmPlan = exportPlan(p, { format: "webm", fps: 30, loopMs: 500 });
+    assert.equal(
+      codeOf(() => buildAnimationManifest(p, { ...webmPlan, loopMs: 0 })),
+      "export-loop-required",
+    );
+  });
+
+  it("perturbFrame: deterministic, resting camera at phase 0, riding the loop", () => {
+    const p = chainProject();
+    const p0 = perturbFrame(p, 0);
+    assert.equal(p0.phase, 0);
+    assert.equal(p0.dx, 0);
+    assert.equal(p0.dy, 0);
+    assert.equal(p0.rotate, 0);
+    assert.ok(Number.isFinite(p0.scale) && p0.scale > 0);
+    const pm = perturbFrame(p, 250);
+    assert.deepStrictEqual(perturbFrame(p, 250), pm); // deterministic
+    assert.equal(pm.phase, 0.5);
+    // arch contour (0.75) → drift {x:9, y:-5, rotation:1}, half-loop phase
+    assert.equal(pm.dx, 4.5);
+    assert.equal(pm.dy, -2.5);
+    assert.equal(pm.rotate, 0.5);
+    assert.ok(pm.scale > 1 && pm.scale < 1.2); // beat breath inside the documented band
+  });
+
+  it("thumbnailSignature: stable, 8-hex, sensitive to time and viewport", () => {
+    const p = chainProject();
+    const s0 = thumbnailSignature(p, 0);
+    assert.equal(s0, thumbnailSignature(p, 0));
+    assert.match(s0, HEX8);
+    assert.notEqual(thumbnailSignature(p, 250), s0);
+    assert.notEqual(thumbnailSignature(p, 0, 512, 384), s0);
+  });
+});
+
+describe("exportBundle — the wave-2 end-to-end", () => {
+  const opts = { format: ["svg", "png", "webm"] as const, width: 1080, fps: 30, loopMs: 500 };
+
+  it("E2E bundle: one svg master always ships plus each requested format", () => {
+    const b = exportBundle(chainProject(), opts);
+    assert.deepStrictEqual(
+      b.artifacts.map((a) => a.kind),
+      ["svg", "png", "webm"],
+    );
+    assert.deepStrictEqual(
+      b.artifacts.map((a) => a.filename),
+      ["e2e-loop.svg", "e2e-loop.png", "e2e-loop.webm"],
+    );
+    const digests = new Set<string>();
+    for (const a of b.artifacts) {
+      assert.match(a.digest, HEX8);
+      digests.add(a.digest);
+    }
+    assert.equal(digests.size, 3); // pairwise distinct
+    assert.equal(b.plan.format, "svg"); // primary = first requested
+    assert.equal(b.plan.width, 1080);
+    assert.ok(b.plan.estimatedBytes > 0);
+  });
+
+  it("digests are stable across two independent full-chain runs", () => {
+    const a = exportBundle(chainProject(), opts);
+    const b = exportBundle(chainProject(), opts);
+    assert.deepStrictEqual(a.artifacts, b.artifacts);
+    assert.deepStrictEqual(a.plan, b.plan);
+  });
+
+  it("png-only request still ships the svg master; primary plan is png", () => {
+    const p = chainProject();
+    const b = exportBundle(p, { format: "png", width: 1440 });
+    assert.deepStrictEqual(
+      b.artifacts.map((a) => a.kind),
+      ["svg", "png"],
+    );
+    assert.equal(b.plan.format, "png");
+    assert.equal(b.plan.width, 1440);
+    assert.equal(b.plan.height, 1440);
+    assert.equal(b.artifacts[0].digest, buildSvgArtifact(p, { width: 1440, height: 1440 }).digest);
+  });
+
+  it("gif artifact rides the documented frame arithmetic", () => {
+    const p = chainProject();
+    const b = exportBundle(p, { format: "gif", fps: 24, loopMs: 375 });
+    assert.deepStrictEqual(
+      b.artifacts.map((a) => a.kind),
+      ["svg", "gif"],
+    );
+    assert.equal(b.plan.frames, 9); // round(375·24/1000)
+    assert.ok(b.artifacts[1].digest !== b.artifacts[0].digest);
+  });
+
+  it("bundle refuses bad entries and empty requests", () => {
+    const p = chainProject();
+    assert.equal(
+      codeOf(() => exportBundle(p, { format: ["svg", "mp4"] as never })),
+      "export-format",
+    );
+    assert.equal(
+      codeOf(() => exportBundle(p, { format: [] })),
+      "export-format",
+    );
+    assert.equal(
+      codeOf(() => exportBundle(p, {} as never)),
+      "export-format",
+    );
+  });
+
+  it("ExportError carries its taxonomy code, name and message", () => {
+    try {
+      exportPlan(chainProject(), { format: "jpeg" as never });
+      assert.fail("expected throw");
+    } catch (e) {
+      assert.ok(e instanceof ExportError && e instanceof Error);
+      assert.equal((e as ExportError).code, "export-format");
+      assert.equal(e.name, "ExportError");
+      assert.ok(e.message.length > 0);
+    }
+  });
+
+  it("toExportProject derives and sanitizes damaged or missing pieces", () => {
+    const d = fixture();
+    const full = chainProject();
+    assert.deepStrictEqual(full.palette, synthPalette(d));
+    assert.deepStrictEqual(full.blocks, rhythmScatter(d, compositionBlocks(d, compositionGrid(d))));
+    assert.ok(full.texture.grainOpacity <= full.texture.grainDensity + 0.2); // documented coupling
+    assert.equal(full.motion.loopMs, 500);
+    // damaged palette → re-derived from the descriptor, bit-for-bit
+    const healed = toExportProject("e2e-loop", { descriptor: d, palette: { anchor: 1 } as never });
+    assert.deepStrictEqual(healed.palette, synthPalette(d));
+    // everything missing → every layer still derivable
+    const bare = toExportProject("bare", { descriptor: d });
+    assert.deepStrictEqual(bare.palette, synthPalette(d));
+    assert.ok(bare.blocks.length >= 1);
+    assert.ok(Number.isFinite(bare.texture.glazeLayers) && bare.texture.glazeLayers >= 1);
+    assert.ok(bare.motion.loopMs > 0);
+  });
+});