@wenathlan/cadria 2.0.94 → 2.0.117

package/tests/onboardingstate.test.ts

@@ -0,0 +1,73 @@
+// # onboardingstate.test — the pure contract of the seen flags: the host
+//   validation of the platform base (https only, public hosts only) and the
+//   seen-wins stage merge the accessor and the pages share. runnable with
+//   vitest: pnpm vitest run tests/onboardingstate.test.ts
+import assert from "node:assert/strict";
+import { describe, it } from "vitest";
+import { entrytarget, hostallowed, mergeStage } from "../onboardingstate.ts";
+
+describe("onboarding state", () => {
+  it("accepts public https bases", () => {
+    assert.equal(hostallowed("https://gateway.wenathlan.dev"), true);
+    assert.equal(hostallowed("https://gateway.wenathlan.dev/"), true);
+    assert.equal(hostallowed("https://cadria.example.com:8443"), true);
+  });
+
+  it("refuses plaintext, localhost, loopback and every private or reserved range", () => {
+    const refused = [
+      "http://gateway.wenathlan.dev",
+      "https://localhost",
+      "https://localhost:8787",
+      "https://app.localhost",
+      "https://box.local",
+      "https://service.internal",
+      "https://127.0.0.1",
+      "https://0.0.0.0",
+      "https://10.0.0.9",
+      "https://172.16.0.1",
+      "https://172.31.255.255",
+      "https://192.168.1.4",
+      "https://169.254.10.10",
+      "https://100.64.0.1",
+      "https://192.0.2.7",
+      "https://198.51.100.7",
+      "https://203.0.113.9",
+      "https://[::1]",
+      "https://[::ffff:127.0.0.1]",
+      "https://[fd00::1]",
+      "https://[fe80::1]",
+      "not a url",
+      "",
+    ];
+    for (const base of refused) assert.equal(hostallowed(base), false, base);
+  });
+
+  it("merges stages seen-wins — a stage never unsees", () => {
+    const fresh = { introseen: false, onboardingseen: false };
+    assert.deepEqual(mergeStage(fresh, "intro"), { introseen: true, onboardingseen: false });
+    assert.deepEqual(mergeStage(fresh, "onboarding"), { introseen: false, onboardingseen: true });
+    const half = { introseen: true, onboardingseen: false };
+    assert.deepEqual(mergeStage(half, "onboarding"), { introseen: true, onboardingseen: true });
+    assert.deepEqual(mergeStage(mergeStage(half, "onboarding"), "intro"), {
+      introseen: true,
+      onboardingseen: true,
+    });
+  });
+
+  it("never mutates the state it merges", () => {
+    const state = { introseen: false, onboardingseen: false };
+    mergeStage(state, "intro");
+    assert.deepEqual(state, { introseen: false, onboardingseen: false });
+  });
+
+  it("hands the entry gate over in the reform order: intro, onboarding, home", () => {
+    const unseen = { introseen: false, onboardingseen: false };
+    const halfseen = mergeStage(unseen, "intro");
+    const fullseen = mergeStage(halfseen, "onboarding");
+    assert.equal(entrytarget(unseen), "/intro");
+    assert.equal(entrytarget(halfseen), "/onboarding");
+    assert.equal(entrytarget(fullseen), "/");
+    // the seen-wins merge can never send a visitor back through the flow
+    assert.equal(entrytarget(mergeStage(fullseen, "intro")), "/");
+  });
+});

package/tests/shadercomp.test.ts

@@ -0,0 +1,120 @@
+// # shadercomp test — determinism of compiled programs, the typed-outcome
+// contract for damaged input, sha-256 integrity against the versawase
+// PrecompiledShader manifest, and the monotone ramps of the dissolve planner.
+// Every suite is pure: no GPU, no DOM, no timers.
+
+import { describe, expect, it } from "vitest";
+import {
+  compileEffectProgram,
+  dissolvePlan,
+  libraryManifestComplete,
+  SHADER_EFFECTS,
+  shaderIdsKnown,
+  shaderManifest,
+} from "../shadercomp.ts";
+import { shaderManifestComplete } from "../versawase.ts";
+
+describe("shadercomp library", () => {
+  it("ships every effect with a real film-technique vocabulary and honest ranges", () => {
+    expect(SHADER_EFFECTS.length).toBe(12);
+    for (const effect of SHADER_EFFECTS) {
+      expect(effect.label.length).toBeGreaterThan(0);
+      expect(effect.minAmount).toBeLessThanOrEqual(effect.defaultAmount);
+      expect(effect.defaultAmount).toBeLessThanOrEqual(effect.maxAmount);
+      expect(effect.glsl).toContain("vec4 effect(");
+      expect(effect.glsl).toContain("}");
+    }
+  });
+
+  it("compiles a program that is a complete, stable fragment source", () => {
+    const compiled = compileEffectProgram("halation", 0.4);
+    expect(compiled).not.toBeNull();
+    if (!compiled) return;
+    expect(compiled.program.startsWith("#version 300 es")).toBe(true);
+    expect(compiled.program).toContain("uniform sampler2D uSource;");
+    expect(compiled.program).toContain("void main()");
+    expect(compiled.sha256).toMatch(/^[0-9a-f]{64}$/);
+  });
+
+  it("answers the same sha-256 for the same id regardless of amount", () => {
+    const small = compileEffectProgram("grainfilm", 0.1);
+    const big = compileEffectProgram("grainfilm", 0.9);
+    expect(small?.sha256).toBe(big?.sha256);
+  });
+
+  it("clamps amounts into the effect range instead of leaking NaN", () => {
+    const low = compileEffectProgram("vignette", -5);
+    const high = compileEffectProgram("vignette", 99);
+    expect(low?.amount).toBe(0);
+    expect(high?.amount).toBe(1);
+    const broken = compileEffectProgram("vignette", Number.NaN);
+    expect(broken?.amount).toBe(compileEffectProgram("vignette", 0.45)?.amount);
+  });
+
+  it("returns null for unknown ids — no throw on damaged input", () => {
+    expect(compileEffectProgram("does-not-exist", 0.5)).toBeNull();
+    expect(shaderIdsKnown(["halation", "vignette"])).toBe(true);
+    expect(shaderIdsKnown(["halation", "ghost"])).toBe(false);
+  });
+
+  it("builds a PrecompiledShader manifest versawase.ts accepts as complete", () => {
+    const manifest = shaderManifest();
+    expect(manifest.length).toBe(12);
+    expect(shaderManifestComplete(manifest)).toBe(true);
+    expect(libraryManifestComplete()).toBe(true);
+    for (const row of manifest) {
+      expect(row.stage).toBe("fragment");
+      expect(row.artifact.startsWith("inline://shadercomp/")).toBe(true);
+    }
+  });
+
+  it("skips unknown ids inside a manifest request instead of failing the batch", () => {
+    const manifest = shaderManifest(["halation", "ghost", "vignette"]);
+    expect(manifest.length).toBe(2);
+    expect(manifest.map((row) => row.id)).toEqual(["halation-fragment", "vignette-fragment"]);
+  });
+});
+
+describe("shadercomp dissolve planner", () => {
+  it("crossfades a lap dissolve with layers always summing to one", () => {
+    const outcome = dissolvePlan("lap-dissolve", 2, 9);
+    expect(outcome.ok).toBe(true);
+    if (!outcome.ok) return;
+    expect(outcome.plan.steps.length).toBe(9);
+    for (const step of outcome.plan.steps) {
+      expect(step.baseOpacity + step.overlayOpacity).toBeCloseTo(1, 5);
+    }
+    expect(outcome.plan.steps[0].baseOpacity).toBe(1);
+    expect(outcome.plan.steps[8].overlayOpacity).toBe(1);
+  });
+
+  it("keeps a straight cut binary — no half-opaque frames", () => {
+    const outcome = dissolvePlan("straight-cut", 1, 5);
+    expect(outcome.ok).toBe(true);
+    if (!outcome.ok) return;
+    for (const step of outcome.plan.steps) {
+      for (const opacity of [step.baseOpacity, step.overlayOpacity]) {
+        expect(opacity === 0 || opacity === 1).toBe(true);
+      }
+    }
+  });
+
+  it("dips a fade-through-black to black at the midpoint", () => {
+    const outcome = dissolvePlan("fade-through-black", 4, 21);
+    expect(outcome.ok).toBe(true);
+    if (!outcome.ok) return;
+    const mid = outcome.plan.steps[10];
+    expect(mid.baseOpacity).toBeLessThanOrEqual(0.2);
+    expect(mid.overlayOpacity).toBeLessThanOrEqual(0.2);
+    expect(outcome.plan.steps[0].baseOpacity).toBe(1);
+    expect(outcome.plan.steps[20].overlayOpacity).toBe(1);
+  });
+
+  it("answers typed errors for unknown technique, bad duration and bad steps", () => {
+    expect(dissolvePlan("cube-spin", 2, 9)).toEqual({ ok: false, error: "dissolve-unknown-technique" });
+    expect(dissolvePlan("lap-dissolve", 0, 9)).toEqual({ ok: false, error: "dissolve-bad-duration" });
+    expect(dissolvePlan("lap-dissolve", Number.NaN, 9)).toEqual({ ok: false, error: "dissolve-bad-duration" });
+    expect(dissolvePlan("lap-dissolve", 2, 1)).toEqual({ ok: false, error: "dissolve-bad-steps" });
+    expect(dissolvePlan("lap-dissolve", 2, 2.5)).toEqual({ ok: false, error: "dissolve-bad-steps" });
+  });
+});

package/tests/synthcomposition.test.ts

@@ -0,0 +1,257 @@
+// # synthcomposition.test — the composition grammar of the cadria image wave,
+// runnable with vitest:
+//   pnpm vitest run tests/synthcomposition.test.ts
+// The tests watch the promises the module makes: the grid grammar tracks
+// section density and repetition (dense → more columns, repetitive → a tight
+// regular lattice), the role cast is exact (one hero, always the largest and
+// heaviest; ≤ 8 cadre; edge blocks own the border), the contour anchors the
+// hero vertically (rise high, fall low, arch centered, wave two peaks), the
+// geometry is total (rects inside 0-1, no overlap beyond the gutter
+// tolerance, weights summing to 1) and everything is deterministic — same
+// descriptor, same blocks; different seed, different jitter.
+import assert from "node:assert/strict";
+import { describe, it } from "vitest";
+import type { AudioDescriptor } from "../audioattributes.ts";
+import { DIM_ORDER, NARRATIVE_CONTOUR } from "../audiofeatures.ts";
+import {
+  type Block,
+  compositionBalance,
+  compositionBlocks,
+  compositionGrid,
+  GRID_MAX,
+  GRID_MIN,
+  HISTOGRAM_BINS,
+  rhythmScatter,
+} from "../synthcomposition.ts";
+
+/** builds a descriptor from named dim overrides over a 0.5 mid field. */
+function desc(over: Record<string, number> = {}, seed = "9a2f41c07b3d5e88"): AudioDescriptor {
+  const vector = new Array<number>(32).fill(0.5);
+  for (const [name, value] of Object.entries(over)) vector[DIM_ORDER.indexOf(name)] = value;
+  return { version: 1, seed, vector, scalar: {} };
+}
+
+const CONTOUR = NARRATIVE_CONTOUR;
+/** dense modern production: many sections, some repetition, a real peak. */
+const dense = desc({ sectionDensity: 0.9, repetition: 0.2, peakMass: 0.8, narrativeContour: CONTOUR.arch });
+/** sparse through-composed clip: few sections, little repetition. */
+const sparse = desc({ sectionDensity: 0.05, repetition: 0.05, peakMass: 0.3 });
+/** loop-pack tile: maximal repetition over dense sections. */
+const repetitive = desc({ sectionDensity: 0.9, repetition: 1, peakMass: 0.5 });
+/** every structure dim broken at once. */
+const damaged = desc({
+  sectionDensity: NaN,
+  repetition: NaN,
+  peakMass: NaN,
+  narrativeContour: NaN,
+  onsetDensity: NaN,
+  swing: NaN,
+});
+
+function heroOf(blocks: Block[]): Block {
+  const heroes = blocks.filter((b) => b.role === "hero");
+  assert.equal(heroes.length, 1);
+  return heroes[0];
+}
+
+function area(b: Block): number {
+  return b.rect.w * b.rect.h;
+}
+
+/** a block touches the canvas border when one of its edges sits on 0 or 1. */
+function touchesBorder(b: Block): boolean {
+  const r = b.rect;
+  return r.x === 0 || r.y === 0 || Math.abs(r.x + r.w - 1) < 1e-9 || Math.abs(r.y + r.h - 1) < 1e-9;
+}
+
+describe("synthcomposition grid", () => {
+  it("tracks section density into more columns, inside the documented 3-12 range", () => {
+    const denseGrid = compositionGrid(dense);
+    const sparseGrid = compositionGrid(sparse);
+    assert.ok(denseGrid.columns > sparseGrid.columns);
+    for (const grid of [denseGrid, sparseGrid]) {
+      assert.ok(grid.columns >= GRID_MIN && grid.columns <= GRID_MAX);
+      assert.ok(grid.rows >= GRID_MIN && grid.rows <= GRID_MAX);
+    }
+    assert.equal(compositionGrid(desc({ sectionDensity: 1 })).columns, GRID_MAX);
+    assert.equal(compositionGrid(desc({ sectionDensity: 0 })).columns, GRID_MIN);
+  });
+
+  it("tiles repetitive audio as a tight regular lattice with uniform cells", () => {
+    const tight = compositionGrid(repetitive);
+    const loose = compositionGrid(sparse);
+    assert.equal(tight.rows, tight.columns); // regular: square lattice
+    assert.ok(tight.gutter <= 0.012);
+    assert.ok(tight.margin < 0.03);
+    assert.ok(loose.gutter > 0.03);
+    const fields = compositionBlocks(repetitive).filter((b) => b.role === "field");
+    assert.ok(fields.length > 0);
+    for (const b of fields) {
+      assert.equal(b.rect.w, fields[0].rect.w);
+      assert.equal(b.rect.h, fields[0].rect.h);
+    }
+  });
+
+  it("keeps the grammar total on damaged descriptors", () => {
+    const grid = compositionGrid(damaged);
+    assert.ok(Number.isInteger(grid.columns) && Number.isInteger(grid.rows));
+    assert.ok(grid.columns >= GRID_MIN && grid.columns <= GRID_MAX);
+    assert.ok(grid.rows >= GRID_MIN && grid.rows <= GRID_MAX);
+    assert.ok(Number.isFinite(grid.gutter) && grid.gutter >= 0);
+    assert.ok(Number.isFinite(grid.margin) && grid.margin >= 0);
+  });
+});
+
+describe("synthcomposition blocks", () => {
+  it("casts exactly one hero and it is the largest, heaviest block", () => {
+    const blocks = compositionBlocks(dense);
+    const hero = heroOf(blocks);
+    for (const b of blocks) {
+      if (b.role !== "hero") assert.ok(area(hero) > area(b));
+    }
+    const top = blocks.reduce((max, b) => Math.max(max, b.weight), 0);
+    assert.equal(hero.weight, top);
+  });
+
+  it("rings the hero with at most 8 cadre and fills field and edge roles", () => {
+    const blocks = compositionBlocks(dense);
+    const cadres = blocks.filter((b) => b.role === "cadre");
+    const edges = blocks.filter((b) => b.role === "edge");
+    const fields = blocks.filter((b) => b.role === "field");
+    assert.ok(cadres.length >= 1 && cadres.length <= 8);
+    assert.equal(cadres.length, 8); // the dense hero always gets its full ring
+    assert.ok(edges.length > 0 && fields.length > 0);
+    for (const b of edges) assert.ok(touchesBorder(b));
+    for (const b of fields) assert.ok(!touchesBorder(b));
+  });
+
+  it("places the hero high on a rise contour", () => {
+    const rise = desc({ sectionDensity: 0.9, repetition: 0.2, peakMass: 0.8, narrativeContour: CONTOUR.rise });
+    const hero = heroOf(compositionBlocks(rise));
+    const centerY = hero.rect.y + hero.rect.h / 2;
+    assert.ok(centerY < 0.45, `rise hero centerY ${centerY} should sit above 0.45`);
+  });
+
+  it("places the hero low on a fall contour", () => {
+    const fall = desc({ sectionDensity: 0.9, repetition: 0.2, peakMass: 0.8, narrativeContour: CONTOUR.fall });
+    const hero = heroOf(compositionBlocks(fall));
+    const centerY = hero.rect.y + hero.rect.h / 2;
+    assert.ok(centerY > 0.55, `fall hero centerY ${centerY} should sit below 0.55`);
+  });
+
+  it("centers the hero on an arch contour", () => {
+    const hero = heroOf(compositionBlocks(dense));
+    const centerY = hero.rect.y + hero.rect.h / 2;
+    assert.ok(Math.abs(centerY - 0.5) <= 0.05, `arch hero centerY ${centerY} should sit near 0.5`);
+  });
+
+  it("splits a wave contour into two peaks", () => {
+    const wave = desc({ sectionDensity: 0.9, repetition: 0.2, peakMass: 0.4, narrativeContour: CONTOUR.wave });
+    const blocks = compositionBlocks(wave);
+    const hero = heroOf(blocks);
+    assert.ok(hero.rect.y + hero.rect.h / 2 < 0.5);
+    const lowCadre = blocks.filter((b) => b.role === "cadre" && b.rect.y + b.rect.h / 2 > 0.55);
+    assert.ok(lowCadre.length >= 1, "the mirrored second peak should ring low");
+  });
+
+  it("keeps every rect finite and inside the normalized canvas", () => {
+    for (const d of [dense, sparse, repetitive, damaged]) {
+      for (const b of compositionBlocks(d)) {
+        for (const v of [b.rect.x, b.rect.y, b.rect.w, b.rect.h]) {
+          assert.ok(Number.isFinite(v) && v >= 0 && v <= 1);
+        }
+      }
+    }
+  });
+
+  it("never lets blocks overlap beyond the gutter tolerance", () => {
+    const jittery = desc({
+      sectionDensity: 0.9,
+      repetition: 0.2,
+      peakMass: 0.8,
+      narrativeContour: CONTOUR.arch,
+      onsetDensity: 1,
+      swing: 0,
+    });
+    const tol = compositionGrid(jittery).gutter + 1e-9;
+    const scattered = rhythmScatter(jittery, compositionBlocks(jittery));
+    for (let i = 0; i < scattered.length; i += 1) {
+      for (let j = i + 1; j < scattered.length; j += 1) {
+        const a = scattered[i].rect;
+        const b = scattered[j].rect;
+        const ox = Math.min(a.x + a.w, b.x + b.w) - Math.max(a.x, b.x);
+        const oy = Math.min(a.y + a.h, b.y + b.h) - Math.max(a.y, b.y);
+        assert.ok(!(ox > tol && oy > tol), `blocks ${i} and ${j} overlap beyond the gutter`);
+      }
+    }
+  });
+
+  it("normalizes weights to sum 1, each inside (0, 1]", () => {
+    for (const d of [dense, sparse, repetitive, damaged]) {
+      const blocks = compositionBlocks(d);
+      const sum = blocks.reduce((acc, b) => acc + b.weight, 0);
+      assert.ok(Math.abs(sum - 1) < 1e-9);
+      for (const b of blocks) assert.ok(b.weight > 0 && b.weight <= 1 + 1e-12);
+    }
+  });
+});
+
+describe("synthcomposition rhythm scatter", () => {
+  it("answers identical blocks for identical descriptors and grids", () => {
+    assert.deepEqual(compositionBlocks(dense), compositionBlocks(dense));
+    assert.deepEqual(compositionBlocks(dense, compositionGrid(dense)), compositionBlocks(dense));
+    const blocks = compositionBlocks(dense);
+    assert.deepEqual(rhythmScatter(dense, blocks), rhythmScatter(dense, blocks));
+  });
+
+  it("jitters differently under different seeds, same roles and weights", () => {
+    const a = desc({ sectionDensity: 0.9, repetition: 0.1, peakMass: 0.5, onsetDensity: 1 }, "1111111111111111");
+    const b = desc({ sectionDensity: 0.9, repetition: 0.1, peakMass: 0.5, onsetDensity: 1 }, "2222222222222222");
+    const blocks = compositionBlocks(a);
+    const scatteredA = rhythmScatter(a, blocks);
+    const scatteredB = rhythmScatter(b, blocks);
+    assert.deepEqual(
+      scatteredA.map((s) => [s.role, s.weight]),
+      scatteredB.map((s) => [s.role, s.weight]),
+    );
+    assert.ok(
+      scatteredA.some((s, i) => s.rect.x !== scatteredB[i].rect.x || s.rect.y !== scatteredB[i].rect.y),
+      "distinct seeds must move at least one block",
+    );
+  });
+
+  it("leans the jitter late under swing", () => {
+    const base = { sectionDensity: 0.9, repetition: 0.1, peakMass: 0.5, onsetDensity: 1 };
+    const straight = rhythmScatter(desc(base, "feedfacefeedface"), compositionBlocks(desc(base)));
+    const swung = rhythmScatter(desc({ ...base, swing: 1 }, "feedfacefeedface"), compositionBlocks(desc(base)));
+    const meanX = (blocks: Block[]): number => blocks.reduce((acc, b) => acc + b.rect.x, 0) / blocks.length;
+    assert.ok(meanX(swung) > meanX(straight), "swing should push the jitter field in +x");
+  });
+});
+
+describe("synthcomposition balance", () => {
+  it("audits a symmetric fixture near the canvas center with a full histogram", () => {
+    const symmetric = desc({ sectionDensity: 0.5, repetition: 0.5, peakMass: 0.2, narrativeContour: CONTOUR.arch });
+    const report = compositionBalance(compositionBlocks(symmetric));
+    assert.ok(Math.abs(report.centerX - 0.5) <= 0.15, `centerX ${report.centerX}`);
+    assert.ok(Math.abs(report.centerY - 0.5) <= 0.15, `centerY ${report.centerY}`);
+    assert.equal(report.densityHistogram.length, HISTOGRAM_BINS);
+    const histSum = report.densityHistogram.reduce((acc, v) => acc + v, 0);
+    assert.ok(Math.abs(histSum - 1) < 1e-9);
+    for (const v of report.densityHistogram) assert.ok(Number.isFinite(v) && v >= 0);
+  });
+
+  it("stays finite and neutral on damaged input", () => {
+    const blocks = compositionBlocks(damaged);
+    assert.equal(blocks.length, 9); // the quiet 3x3 fallback: one hero, a full ring, no fill
+    for (const b of blocks) {
+      for (const v of [b.rect.x, b.rect.y, b.rect.w, b.rect.h, b.weight]) assert.ok(Number.isFinite(v));
+    }
+    const report = compositionBalance(blocks);
+    for (const v of [report.centerX, report.centerY, ...report.densityHistogram]) assert.ok(Number.isFinite(v));
+    const scattered = rhythmScatter(damaged, blocks);
+    for (const b of scattered) {
+      for (const v of [b.rect.x, b.rect.y, b.rect.w, b.rect.h]) assert.ok(Number.isFinite(v) && v >= 0 && v <= 1);
+    }
+  });
+});