@wenathlan/cadria 2.0.94 → 2.0.118

package/tests/imageproject.test.ts

@@ -0,0 +1,372 @@
+// # imageproject.test — the PROJECT layer's contract, runnable with vitest:
+//   pnpm vitest run tests/imageproject.test.ts
+// The tests watch five promises: the seeded rng replays bit-for-bit and stays
+// uniform, buildImageProject validates every field and derives the rest
+// (audio stats, id slug, orientation), the bundle is deep-frozen while its
+// inputs stay untouched, serialize→parse round trips exactly (and refuses
+// other versions), and projectVariants keep the audio while rotating seed +
+// anchor hue. Every damage path answers ProjectError with its taxonomy code.
+import assert from "node:assert/strict";
+import { describe, it } from "vitest";
+import type { AudioDescriptor } from "../audioattributes.ts";
+import type { ImageProject } from "../imageproject.ts";
+import {
+  buildImageProject,
+  ProjectError,
+  parseProject,
+  projectVariants,
+  rngFromSeed,
+  rngInt,
+  rngPick,
+  serializeProject,
+  VARIANT_HUE_STEP,
+} from "../imageproject.ts";
+import { compositionBlocks } from "../synthcomposition.ts";
+import { synthMotion } from "../synthmotion.ts";
+import { synthPalette } from "../synthpalette.ts";
+import { synthTexture } from "../synthtexture.ts";
+
+const SEED = "9a7c1e2b44d0f836";
+
+/** a contract-true fixture descriptor: 32 mid dims, a few peaks, real scalars. */
+function descriptor(): AudioDescriptor {
+  const vector = new Array<number>(32).fill(0.4);
+  vector[9] = 0.6;
+  vector[12] = 0.8;
+  vector[22] = 0.7;
+  vector[24] = 0.6;
+  vector[26] = 1;
+  vector[27] = 0.5;
+  vector[29] = 0.55;
+  return { version: 1, seed: SEED, vector, scalar: { bpm: 124, durationMs: 96000, tonic: 9, minor: 1 } };
+}
+
+/** a fully valid project assembled from the real wave-2 synth chain. */
+function project(width = 1080, height = 1080, seed?: string): ImageProject {
+  const d = descriptor();
+  return buildImageProject({
+    descriptor: d,
+    seed,
+    palette: synthPalette(d),
+    blocks: compositionBlocks(d),
+    texture: synthTexture(d),
+    motion: synthMotion(d),
+    width,
+    height,
+  });
+}
+
+/** the fixture's four wave-2 specs, ready to mix into damaged builds. */
+function specs() {
+  const d = descriptor();
+  return {
+    d,
+    palette: synthPalette(d),
+    blocks: compositionBlocks(d),
+    texture: synthTexture(d),
+    motion: synthMotion(d),
+  };
+}
+
+/** runs fn, asserts a ProjectError comes back, answers its taxonomy code. */
+function codeOf(run: () => unknown): string {
+  try {
+    run();
+  } catch (error) {
+    assert.ok(error instanceof ProjectError, "throws ProjectError");
+    return error.code;
+  }
+  assert.fail("expected a throw");
+}
+
+describe("seeded rng", () => {
+  it("same seed replays the identical 100-draw sequence; another seed differs", () => {
+    const a = Array.from({ length: 100 }, () => rngFromSeed(SEED)());
+    const b = Array.from({ length: 100 }, () => rngFromSeed(SEED)());
+    assert.deepEqual(a, b);
+    const other = Array.from({ length: 100 }, () => rngFromSeed("another-lane")());
+    assert.notDeepEqual(a, other);
+  });
+
+  it("draws land in [0,1) with a sane mean over 1000 draws", () => {
+    const rng = rngFromSeed("distribution-probe");
+    const draws = Array.from({ length: 1000 }, () => rng());
+    for (const v of draws) assert.ok(v >= 0 && v < 1, `draw ${v} in [0,1)`);
+    const mean = draws.reduce((sum, v) => sum + v, 0) / draws.length;
+    assert.ok(mean >= 0.4 && mean <= 0.6, `mean ${mean} in 0.4-0.6`);
+  });
+
+  it("rngInt is inclusive and deterministic; rngPick stays in the list; damage coded", () => {
+    const rng = rngFromSeed("int-probe");
+    const draws = Array.from({ length: 200 }, () => rngInt(rng, 2, 5));
+    for (const v of draws) assert.ok(Number.isInteger(v) && v >= 2 && v <= 5, `int ${v} in [2,5]`);
+    assert.ok(new Set(draws).size > 1, "both bounds reachable");
+    assert.deepEqual(
+      Array.from({ length: 8 }, () => rngInt(rngFromSeed("same-lane"), 0, 9)),
+      Array.from({ length: 8 }, () => rngInt(rngFromSeed("same-lane"), 0, 9)),
+    );
+    for (let i = 0; i < 20; i += 1) assert.ok(["a", "b", "c"].includes(rngPick(rng, ["a", "b", "c"])));
+    assert.equal(
+      codeOf(() => rngPick(rng, [] as string[])),
+      "project-shape",
+    );
+    assert.equal(
+      codeOf(() => rngInt(rng, 5, 2)),
+      "project-range",
+    );
+    assert.equal(
+      codeOf(() => rngInt(rng, 1.5, 4)),
+      "project-range",
+    );
+  });
+});
+
+describe("buildImageProject", () => {
+  it("validates and derives every field from the wave-2 chain", () => {
+    const p = project();
+    assert.equal(p.version, 1);
+    assert.equal(p.seed, SEED); // seed defaults to descriptor.seed
+    assert.equal(p.style, "atelier"); // style default
+    assert.equal(p.id, `${SEED}-atelier`); // slug of seed + style
+    assert.deepEqual(p.audio, { durationMs: 96000, bpm: 124, key: "am" });
+    assert.deepEqual(p.canvas, { width: 1080, height: 1080, orientation: "square" });
+    assert.equal(p.descriptor.seed, SEED);
+    assert.equal(p.descriptor.vector.length, 32);
+    assert.equal(Object.keys(p.texture).length, 10);
+    assert.ok(p.blocks.length >= 1 && p.motion.keyframes.length >= 1);
+    assert.equal(Number.isNaN(Date.parse(p.createdAt)), false); // ISO stamp present
+  });
+
+  it("orientation derives square / portrait / landscape from w×h", () => {
+    assert.equal(project(1080, 1080).canvas.orientation, "square");
+    assert.equal(project(1080, 1350).canvas.orientation, "portrait");
+    assert.equal(project(1350, 1080).canvas.orientation, "landscape");
+  });
+
+  it("id slug is deterministic, slugified and seed-sensitive", () => {
+    assert.equal(project(1080, 1080).id, project(1080, 1080).id);
+    assert.notEqual(project(1080, 1080, "aa11bb22cc33").id, project(1080, 1080, "dd44ee55ff66").id);
+    const d = descriptor();
+    const styled = buildImageProject({
+      descriptor: d,
+      style: "Atelier V2!",
+      palette: synthPalette(d),
+      blocks: compositionBlocks(d),
+      texture: synthTexture(d),
+      motion: synthMotion(d),
+    });
+    assert.equal(styled.id, `${SEED}-atelier-v2`);
+  });
+
+  it("the bundle is deep-frozen at every level; caller inputs stay untouched", () => {
+    const d = descriptor();
+    const palette = synthPalette(d);
+    const p = buildImageProject({
+      descriptor: d,
+      palette,
+      blocks: compositionBlocks(d),
+      texture: synthTexture(d),
+      motion: synthMotion(d),
+    });
+    for (const frozen of [
+      p,
+      p.audio,
+      p.descriptor,
+      p.descriptor.vector,
+      p.descriptor.scalar,
+      p.palette,
+      p.palette.support,
+      p.palette.accents,
+      p.palette.oklch.anchor,
+      p.blocks,
+      p.blocks[0].rect,
+      p.texture,
+      p.motion,
+      p.motion.keyframes[0],
+      p.canvas,
+    ])
+      assert.ok(Object.isFrozen(frozen), "frozen");
+    assert.equal(Object.isFrozen(d.vector), false); // the input replica is fresh
+    assert.equal(Object.isFrozen(palette), false);
+    assert.equal(d.vector[9], 0.6); // inputs unmutated
+  });
+
+  it("damaged input answers ProjectError code project-shape", () => {
+    const { d, palette, blocks, texture, motion } = specs();
+    const short = { version: 1, seed: "x", vector: new Array(31).fill(0.5), scalar: {} } as unknown as AudioDescriptor;
+    assert.equal(
+      codeOf(() => buildImageProject({ descriptor: short, palette, blocks, texture, motion })),
+      "project-shape",
+    );
+    assert.equal(
+      codeOf(() => buildImageProject({ descriptor: d, palette, blocks: [], texture, motion })),
+      "project-shape",
+    );
+    assert.equal(
+      codeOf(() =>
+        buildImageProject({ descriptor: d, palette: { ...palette, anchor: "red" }, blocks, texture, motion }),
+      ),
+      "project-shape",
+    );
+    assert.equal(
+      codeOf(() =>
+        buildImageProject({ descriptor: d, palette, blocks, texture, motion: { ...motion, easing: "elastic" } }),
+      ),
+      "project-shape",
+    );
+    assert.equal(
+      codeOf(() =>
+        buildImageProject({ descriptor: d, palette, blocks, texture: { ...texture, grainSize: "fat" }, motion }),
+      ),
+      "project-shape",
+    );
+    assert.equal(
+      codeOf(() => buildImageProject(null as never)),
+      "project-shape",
+    );
+  });
+
+  it("non-finite / out-of-range numbers answer ProjectError code project-range", () => {
+    const { d, palette, blocks, texture, motion } = specs();
+    const nanPalette = { ...palette, oklch: { ...palette.oklch, anchor: { ...palette.oklch.anchor, l: NaN } } };
+    assert.equal(
+      codeOf(() => buildImageProject({ descriptor: d, palette: nanPalette, blocks, texture, motion })),
+      "project-range",
+    );
+    const nanVector = descriptor();
+    nanVector.vector[3] = NaN;
+    assert.equal(
+      codeOf(() => buildImageProject({ descriptor: nanVector, palette, blocks, texture, motion })),
+      "project-range",
+    );
+    assert.equal(
+      codeOf(() =>
+        buildImageProject({ descriptor: d, palette, blocks, texture: { ...texture, grainDensity: 4 }, motion }),
+      ),
+      "project-range",
+    );
+    const fat = blocks.map((b, i) => (i === 0 ? { ...b, weight: 1.5 } : b));
+    assert.equal(
+      codeOf(() => buildImageProject({ descriptor: d, palette, blocks: fat, texture, motion })),
+      "project-range",
+    );
+    assert.equal(
+      codeOf(() => buildImageProject({ descriptor: d, palette, blocks, texture, motion, width: 99999 })),
+      "project-range",
+    );
+    assert.equal(
+      codeOf(() =>
+        buildImageProject({ descriptor: d, palette, blocks, texture, motion: { ...motion, parallaxDepth: 2 } }),
+      ),
+      "project-range",
+    );
+  });
+
+  it("an unreadable descriptor or bundle version answers project-version", () => {
+    const { palette, blocks, texture, motion } = specs();
+    const v2 = { ...descriptor(), version: 2 } as unknown as AudioDescriptor;
+    assert.equal(
+      codeOf(() => buildImageProject({ descriptor: v2, palette, blocks, texture, motion })),
+      "project-version",
+    );
+    const p = project();
+    const bumped = JSON.stringify({ ...JSON.parse(serializeProject(p)), version: 2 });
+    assert.equal(
+      codeOf(() => parseProject(bumped)),
+      "project-version",
+    );
+  });
+});
+
+describe("serialize / parse", () => {
+  it("serialize→parse round trips deep-equal, minus nothing", () => {
+    const p = project(1080, 1350);
+    assert.deepEqual(parseProject(serializeProject(p)), p);
+  });
+
+  it("the JSON round trip keeps everything frozen", () => {
+    const parsed = parseProject(serializeProject(project()));
+    for (const frozen of [
+      parsed,
+      parsed.audio,
+      parsed.descriptor.vector,
+      parsed.palette,
+      parsed.blocks[0].rect,
+      parsed.texture,
+      parsed.motion,
+      parsed.canvas,
+    ])
+      assert.ok(Object.isFrozen(frozen), "frozen");
+  });
+
+  it("parse refuses future versions and damaged payloads with the right code", () => {
+    const raw = JSON.parse(serializeProject(project()));
+    assert.equal(
+      codeOf(() => parseProject(JSON.stringify({ ...raw, version: 99 }))),
+      "project-version",
+    );
+    assert.equal(
+      codeOf(() => parseProject(JSON.stringify({ ...raw, version: 1.5 }))),
+      "project-version",
+    );
+    assert.equal(
+      codeOf(() => parseProject("{not json")),
+      "project-shape",
+    );
+    assert.equal(
+      codeOf(() => parseProject("[1,2]")),
+      "project-shape",
+    );
+    assert.equal(
+      codeOf(() => parseProject("")),
+      "project-shape",
+    );
+    delete raw.palette;
+    assert.equal(
+      codeOf(() => parseProject(JSON.stringify(raw))),
+      "project-shape",
+    );
+  });
+});
+
+describe("projectVariants", () => {
+  it("count + distinct derived seeds + identical audio/blocks/texture stats", () => {
+    const p = project();
+    const variants = projectVariants(p, 3);
+    assert.equal(variants.length, 3);
+    assert.equal(new Set(variants.map((v) => v.seed)).size, 3);
+    variants.forEach((v, i) => {
+      assert.equal(v.seed, `${SEED}::variant${i}`);
+      assert.deepEqual(v.audio, p.audio); // same audio stats
+      assert.deepEqual(v.blocks, p.blocks);
+      assert.deepEqual(v.texture, p.texture);
+      assert.notEqual(v.id, p.id); // fresh slug
+    });
+    assert.equal(projectVariants(p, 0).length, 0);
+    assert.equal(
+      codeOf(() => projectVariants(p, -1)),
+      "project-range",
+    );
+    assert.equal(
+      codeOf(() => projectVariants(p, 1.5)),
+      "project-range",
+    );
+  });
+
+  it("the documented golden-angle rotation moves the anchor hue, accents untouched", () => {
+    const p = project();
+    const baseHue = p.palette.oklch.anchor.h;
+    projectVariants(p, 2).forEach((v, i) => {
+      const delta = (v.palette.oklch.anchor.h - baseHue + 360) % 360;
+      assert.ok(Math.abs(delta - (((i + 1) * VARIANT_HUE_STEP) % 360)) < 1e-6, `delta ${delta} = (i+1)·step`);
+      assert.notEqual(v.palette.anchor, p.palette.anchor); // hex re-rendered
+      assert.deepEqual(v.palette.oklch.accents, p.palette.oklch.accents); // accents untouched
+    });
+  });
+
+  it("variants are frozen bundles that serialize too", () => {
+    const v = projectVariants(project(), 1)[0];
+    assert.ok(Object.isFrozen(v) && Object.isFrozen(v.palette));
+    assert.deepEqual(parseProject(serializeProject(v)), v);
+  });
+});

package/tests/imagerender.test.ts

@@ -0,0 +1,291 @@
+// # imagerender.test — the render layer of the cadria image wave, runnable
+// with vitest:
+//   pnpm vitest run tests/imagerender.test.ts
+// The tests watch the promises the module makes: the same project compiles to
+// bit-identical commands, svg and signature; geometry stays normalized 0-1 and
+// every color is well-formed hex; the z bands are monotonic (background first,
+// specular last); the 4096-command budget truncates grain first and keeps the
+// specular; the svg is well-formed (regex tag balance, no NaN/Infinity/exponent
+// tokens); the signature is stable across runs but moves when commands change;
+// perturbations are pure (pulse scales the hero by pulseScale at strength 1 and
+// is the identity at 0, wipe shifts exactly the documented middle-third band);
+// an empty cast renders background-only; grain count tracks grainDensity.
+import assert from "node:assert/strict";
+import { describe, it } from "vitest";
+import {
+  COMMAND_BUDGET,
+  type DrawCommand,
+  RENDER_DEFAULT_SIZE,
+  renderCommands,
+  renderKeyframePerturbation,
+  renderThumbnailSignature,
+  WIPE_BAND,
+  WIPE_SHIFT,
+  Z_SPECULAR,
+} from "../imagerender.ts";
+import { renderSvg } from "../imagerenderpaint.ts";
+import type { Block } from "../synthcomposition.ts";
+import type { Palette } from "../synthpalette.ts";
+
+/** a layout block shorthand. */
+function block(x: number, y: number, w: number, h: number, role: Block["role"], weight = 0.1): Block {
+  return { rect: { x, y, w, h }, weight, role };
+}
+
+const PALETTE: Palette = {
+  anchor: "#c2643f",
+  support: ["#8fa38a", "#5d6e63"],
+  ink: "#131a16",
+  surface: "#f2ede4",
+  accents: ["#3f7fc2", "#c23f7f", "#7fc23f"],
+  oklch: {
+    anchor: { l: 0.6, c: 0.12, h: 40 },
+    accents: [
+      { l: 0.55, c: 0.12, h: 250 },
+      { l: 0.55, c: 0.12, h: 340 },
+      { l: 0.6, c: 0.12, h: 110 },
+    ],
+  },
+};
+/** cadre1 sits above the wipe band, cadre2 inside it; edge/field sit outside. */
+const BLOCKS: Block[] = [
+  block(0.3, 0.35, 0.4, 0.3, "hero", 0.4),
+  block(0.1, 0.15, 0.15, 0.15, "cadre"),
+  block(0.7, 0.4, 0.15, 0.15, "cadre"),
+  block(0.1, 0.7, 0.15, 0.2, "field", 0.05),
+  block(0, 0, 1, 0.1, "edge", 0.05),
+];
+const TEXTURE = {
+  grainDensity: 0.4,
+  grainSize: 2,
+  grainOpacity: 0.3,
+  strokeSoftness: 0.5,
+  strokeWeight: 6,
+  strokeJitter: 0.4,
+  glazeLayers: 3,
+  glazeOpacity: 0.4,
+  specular: 0.5,
+  turbulence: 0.4,
+};
+const PROJECT = { seed: "b7render", palette: PALETTE, blocks: BLOCKS, texture: TEXTURE };
+
+/** horizontal x anchor of one command's geometry (wipe displacement probe). */
+function xOf(c: DrawCommand): number {
+  if (c.kind === "ellipse") return c.cx;
+  if (c.kind === "path" || c.kind === "strokepath") return c.points[0];
+  return c.x;
+}
+/** vertical center of one command's geometry (wipe band membership). */
+function cyOf(c: DrawCommand): number {
+  if (c.kind === "rect" || c.kind === "gradientwash") return c.y + c.h / 2;
+  if (c.kind === "ellipse") return c.cy;
+  if (c.kind === "path" || c.kind === "strokepath")
+    return c.points.reduce((s, _, i) => (i % 2 === 1 ? s + c.points[i] : s), 0) / (c.points.length / 2);
+  return c.y;
+}
+type Wash = Extract<DrawCommand, { kind: "gradientwash" }>;
+type Ellipse = Extract<DrawCommand, { kind: "ellipse" }>;
+const washOf = (list: readonly DrawCommand[]): Wash => list.find((c): c is Wash => c.kind === "gradientwash") as Wash;
+const ellipseOf = (list: readonly DrawCommand[]): Ellipse =>
+  list.find((c): c is Ellipse => c.kind === "ellipse") as Ellipse;
+
+describe("renderCommands determinism and geometry", () => {
+  it("same project → identical commands, svg and signature", () => {
+    const a = renderCommands(PROJECT);
+    const b = renderCommands(PROJECT);
+    assert.deepEqual(a, b);
+    assert.equal(renderSvg(a), renderSvg(b));
+    assert.equal(renderThumbnailSignature(a.commands), renderThumbnailSignature(b.commands));
+  });
+
+  it("geometry stays inside [0,1] for every command", () => {
+    const { commands } = renderCommands(PROJECT);
+    for (const c of commands) {
+      if (c.kind === "rect" || c.kind === "gradientwash") {
+        assert.ok(c.x >= 0 && c.y >= 0 && c.x + c.w <= 1 + 1e-9 && c.y + c.h <= 1 + 1e-9, c.kind);
+      } else if (c.kind === "ellipse") {
+        assert.ok(
+          c.cx - c.rx >= -1e-9 && c.cx + c.rx <= 1 + 1e-9 && c.cy - c.ry >= -1e-9 && c.cy + c.ry <= 1 + 1e-9,
+          "ellipse",
+        );
+      } else if (c.kind === "grainfield") {
+        assert.ok(c.x >= 0 && c.x < 1 && c.y >= 0 && c.y < 1, "grain");
+      } else {
+        for (const v of c.points) assert.ok(v >= 0 && v <= 1 + 1e-9, c.kind);
+      }
+    }
+  });
+
+  it("every color field is a well-formed #rrggbb hex", () => {
+    const { commands } = renderCommands(PROJECT);
+    const hex = /^#[0-9a-f]{6}$/;
+    for (const c of commands) {
+      const colors = c.kind === "gradientwash" ? [c.from, c.to] : c.kind === "strokepath" ? [c.stroke] : [c.fill];
+      for (const value of colors) assert.ok(hex.test(value), `${c.kind}: ${value}`);
+    }
+  });
+
+  it("empty blocks render background-only", () => {
+    const frame = renderCommands({ seed: "solo", palette: PALETTE, texture: TEXTURE });
+    assert.equal(frame.commands.length, 1);
+    assert.equal(frame.commands[0].kind, "rect");
+    assert.equal(frame.commands[0].z, 0);
+    assert.equal(frame.background, PALETTE.surface);
+    assert.equal((frame.commands[0] as Extract<DrawCommand, { kind: "rect" }>).fill, PALETTE.surface);
+    assert.match(renderSvg(frame), new RegExp(`width="${RENDER_DEFAULT_SIZE}" height="${RENDER_DEFAULT_SIZE}"`));
+  });
+
+  it("all six command kinds appear; glaze opacity follows the layer stack", () => {
+    const { commands } = renderCommands(PROJECT);
+    for (const kind of ["rect", "ellipse", "gradientwash", "path", "strokepath", "grainfield"]) {
+      assert.ok(
+        commands.some((c) => c.kind === kind),
+        kind,
+      );
+    }
+    const glaze = 1 - (1 - 0.4) ** 3;
+    const field = commands.find((c) => c.kind === "rect" && c.role === "field") as Extract<
+      DrawCommand,
+      { kind: "rect" }
+    >;
+    const edge = commands.find((c) => c.kind === "rect" && c.role === "edge") as Extract<DrawCommand, { kind: "rect" }>;
+    assert.equal(field.opacity, glaze);
+    assert.equal(edge.opacity, 0.4);
+  });
+
+  it("damaged input is total: defaults hold and nothing is NaN", () => {
+    const frame = renderCommands({
+      canvas: { width: NaN, height: Infinity },
+      texture: { grainDensity: NaN, glazeLayers: 99, strokeWeight: -4 },
+      blocks: [{ rect: { x: NaN, y: 0.2, w: -1, h: 0.5 }, weight: 0.5, role: "cadre" }],
+    });
+    assert.equal(frame.width, RENDER_DEFAULT_SIZE);
+    assert.equal(frame.height, RENDER_DEFAULT_SIZE);
+    assert.match(frame.background, /^#[0-9a-f]{6}$/);
+    assert.ok(frame.commands.length > 1);
+    for (const c of frame.commands) {
+      assert.ok(Number.isFinite(c.z) && Number.isFinite(c.opacity) && Number.isFinite(c.blur), c.kind);
+      if (c.kind === "grainfield") assert.ok(Number.isFinite(c.x) && Number.isFinite(c.y) && Number.isFinite(c.r));
+    }
+  });
+
+  it("command count tracks grainDensity monotonically (two fixtures)", () => {
+    const sparse = renderCommands({ ...PROJECT, texture: { ...TEXTURE, grainDensity: 0.1 } });
+    const rich = renderCommands({ ...PROJECT, texture: { ...TEXTURE, grainDensity: 0.9 } });
+    const sparseGrains = sparse.commands.filter((c) => c.kind === "grainfield").length;
+    const richGrains = rich.commands.filter((c) => c.kind === "grainfield").length;
+    assert.ok(richGrains > sparseGrains);
+    const base = (RENDER_DEFAULT_SIZE * RENDER_DEFAULT_SIZE) / 1600;
+    assert.equal(sparseGrains, Math.ceil(0.1 * base));
+    assert.equal(richGrains, Math.ceil(0.9 * base));
+  });
+});
+
+describe("budget and paint order", () => {
+  it("dense canvas truncates to exactly the 4096 budget, specular kept last", () => {
+    const dense = renderCommands({
+      ...PROJECT,
+      canvas: { width: 8192, height: 8192 },
+      texture: { ...TEXTURE, grainDensity: 1 },
+    });
+    assert.equal(dense.commands.length, COMMAND_BUDGET);
+    assert.equal(dense.commands[dense.commands.length - 1].kind, "path");
+    assert.equal(dense.commands[dense.commands.length - 1].z, Z_SPECULAR);
+    assert.ok(dense.commands.some((c) => c.kind === "grainfield"));
+  });
+
+  it("z-order monotonic: background first, specular last", () => {
+    const { commands } = renderCommands(PROJECT);
+    for (let i = 1; i < commands.length; i += 1) assert.ok(commands[i - 1].z <= commands[i].z, `z at ${i}`);
+    assert.equal(commands[0].z, 0);
+    assert.equal(commands[0].kind, "rect");
+    assert.equal(commands[commands.length - 1].kind, "path");
+    assert.equal(commands[commands.length - 1].z, Z_SPECULAR);
+  });
+});
+
+describe("renderSvg serialization", () => {
+  it("svg is well-formed: one root, balanced tags, unique ids", () => {
+    const svg = renderSvg(renderCommands(PROJECT));
+    assert.equal(svg.match(/<svg[ >]/g)?.length, 1);
+    const ids = [...svg.matchAll(/id="([^"]+)"/g)].map((m) => m[1]);
+    assert.equal(new Set(ids).size, ids.length);
+    const stack: string[] = [];
+    for (const m of svg.matchAll(/<(\/?)([a-zA-Z][\w:-]*)((?:"[^"]*"|[^>"'])*)>/g)) {
+      const closing = m[1] === "/";
+      const self = /\/\s*$/.test(m[3]);
+      if (closing) assert.equal(stack.pop(), m[2]);
+      else if (!self) stack.push(m[2]);
+    }
+    assert.deepEqual(stack, []);
+  });
+
+  it("svg carries no NaN, Infinity or exponent tokens", () => {
+    const svg = renderSvg(renderCommands(PROJECT));
+    assert.doesNotMatch(svg, /NaN|Infinity|[eE][+-][0-9]/);
+    assert.match(svg, /fill="#f2ede4"/);
+    assert.match(svg, /url\(#wash-\d+\)/);
+  });
+});
+
+describe("thumbnail signature", () => {
+  it("signature is stable across runs and moves when commands change", () => {
+    const { commands } = renderCommands(PROJECT);
+    assert.equal(renderThumbnailSignature(commands), renderThumbnailSignature(renderCommands(PROJECT).commands));
+    assert.notEqual(renderThumbnailSignature(commands), renderThumbnailSignature(commands.slice(0, -1)));
+    const moved = renderKeyframePerturbation(commands, { kind: "shift", strength: 0.5, targets: [], tMs: 0 });
+    assert.notEqual(renderThumbnailSignature(commands), renderThumbnailSignature(moved));
+  });
+});
+
+describe("perturbation hooks", () => {
+  it("pulse at strength 1 scales hero geometry by pulseScale (±0.01)", () => {
+    const { commands } = renderCommands(PROJECT);
+    const out = renderKeyframePerturbation(commands, { kind: "pulse", strength: 1, targets: [], tMs: 0 }, 1.08);
+    const washA = washOf(commands);
+    const washB = washOf(out);
+    const ellipseA = ellipseOf(commands);
+    const ellipseB = ellipseOf(out);
+    assert.ok(Math.abs(washB.w / washA.w - 1.08) <= 0.01);
+    assert.ok(Math.abs(washB.h / washA.h - 1.08) <= 0.01);
+    assert.ok(Math.abs(ellipseB.rx / ellipseA.rx - 1.08) <= 0.01);
+    assert.ok(Math.abs(ellipseB.ry / ellipseA.ry - 1.08) <= 0.01);
+    const nonHero = out.filter((c) => c.role !== "hero");
+    const nonHeroBefore = commands.filter((c) => c.role !== "hero");
+    assert.deepEqual(nonHero, nonHeroBefore);
+  });
+
+  it("pulse at strength 0 is the identity and never mutates the input", () => {
+    const { commands } = renderCommands(PROJECT);
+    const snapshot = structuredClone(commands);
+    const out = renderKeyframePerturbation(commands, { kind: "pulse", strength: 0, targets: [], tMs: 0 }, 1.08);
+    assert.deepEqual(out, commands);
+    assert.deepEqual(commands, snapshot);
+  });
+
+  it("wipe shifts exactly the documented middle-third band", () => {
+    const { commands } = renderCommands(PROJECT);
+    const out = renderKeyframePerturbation(commands, { kind: "wipe", strength: 1, targets: [], tMs: 0 });
+    let sawInBand = false;
+    for (let i = 0; i < commands.length; i += 1) {
+      const a = commands[i];
+      const inBand = a.z > 0 && a.kind !== "grainfield" && cyOf(a) >= WIPE_BAND.top && cyOf(a) <= WIPE_BAND.bottom;
+      const dx = xOf(out[i]) - xOf(a);
+      if (inBand) {
+        sawInBand = true;
+        assert.ok(Math.abs(dx - WIPE_SHIFT) < 1e-9, `${a.kind} dx=${dx}`);
+      } else {
+        assert.equal(dx, 0, `${a.kind} dy-shift`);
+      }
+    }
+    assert.ok(sawInBand);
+  });
+
+  it("reveal scales non-background opacity by strength; background holds", () => {
+    const { commands } = renderCommands(PROJECT);
+    const out = renderKeyframePerturbation(commands, { kind: "reveal", strength: 0.5, targets: [], tMs: 0 });
+    assert.equal(out[0].opacity, 1);
+    assert.equal(out[1].opacity, commands[1].opacity * 0.5);
+    assert.equal(out.length, commands.length);
+  });
+});