Migrate Demoscene integration from API v2 to v3

[axisrow]

Summary

Migrates the runtime Demoscene effects integration from API v2 → API v3 (closes #16).

v3 contract (confirmed against the source)

The demoscene_classics dist already serves an apiVersion: 3 manifest.json from the same base URL (/demoscene_classics/dist, the existing <meta name="demoscene-base"> default). The v3 surface is otherwise unchanged for this site:

• Top-level manifest fields identical: version (string), apiVersion (number, now 3), bundle (string) — plus a new optional effects[].
• Factory signature unchanged: Demoscene.<name>(target, options).
• Skin shape unchanged (runtime / render / motion / appearance / camera / algorithm / field).
• The three required effects (metaballs, plasma, mandelbrot) are all present in the v3 manifest.

So effect-skins.js and the base URL need no changes — the migration is a client-side contract bump plus a cache-buster.

Changes

• main.js — hard version gate now requires apiVersion === 3; the "expose the required API effects" error string references v3.
• index.html — cache-busters on effect-skins.js / main.js bumped api-v2-final → api-v3-final.
• tests/site-smoke.test.mjs — loader tests drive v3 manifests; the incompatible-version case now uses a v2 manifest to exercise the rejection path.

Tests

• npm test → 22/22 pass (node --check main.js && node --check effect-skins.js && node --test).
• python3 -m unittest discover -s profile/tests → 41/41 pass (unchanged layer, sanity check).

Manual verification (per issue)

Not run in CI (no browser): load the site → animated accents render (no demoscene-fallback), DevTools shows the v3 manifest fetched and libraryReady = true; pointing demoscene-base at an incompatible manifest → graceful static fallback, no uncaught errors. The loader unit tests cover the success, missing-manifest, incompatible-version, bundle-fail, and missing-effects paths.

Risks / follow-ups

• A v2 manifest served at the configured base would now be rejected with a static fallback — intended behaviour (the source already serves v3).
• Browser smoke is deferred to the user; the VM-based loader tests assert the contract paths.

🤖 Generated with Claude Code

[axisrow]

🔍 Local review (cycle 1/3)

Reviewed locally (/review + Codex companion, model sol / effort xhigh), no bots pinged. Head 4ef986e.

Verdict	Reviewer	Finding	Location
FIX	codex	API v3 rejects every effect mount — PR passes the legacy v2 flat-options object as the factory argument, but v3 requires a {skin, surface, device, config} descriptor	main.js:89
clean	claude	No critical issues in the version-gate / cache-buster / string bumps	main.js, index.html

FIX detail (confirmed empirically against the real demoscene_classics v3 bundle).
Demoscene.<name>(target, descriptor) changed in v3: src/install.js documents the descriptor { skin, surface, device, config }, and src/resolver.js detectLegacy() throws TypeError on any v2 top-level group (runtime/render/motion/appearance/field/camera/algorithm). The PR calls factory(element, definition.options) where definition.options is exactly such a legacy object, so the first mount throws, loadDemoscene() catches it, and all three animated accents fall back to static rendering — directly breaking the goal of issue #16. The existing runLoader tests miss it because their mock factories are no-ops that never call resolveDescriptor.

Verified empirically by loading dist/demoscene.js in a Node VM:

• legacy flat options → TypeError: the legacy v2 flat options object is no longer supported in API v3 (reproduces the bug);
• descriptor {skin:'classic', surface, device:'auto', config:{...}} → passes descriptor validation for metaballs/plasma/mandelbrot.

Fix plan: build a v3 descriptor at the call site and rework effect-skins.js so budgets (runtime/render.resolution) move to the library's profile slots (which v3 now owns), while algorithmic identity (field/camera/algorithm), motion, render.backend (mandelbrot) and appearance travel under config. Surfaces: metaballs=fullscreen, plasma/mandelbrot=preview; device: 'auto'.

[axisrow]

📋 Review summary — all cycles

Reviewed locally (/review + Codex companion sol/xhigh), no bots pinged. PR head reviewed: 6c29e87.

Cycle	Reviewer	Finding	Verdict	Resolution
1	codex	API v3 rejects every effect mount — legacy v2 flat-options object passed as the factory descriptor; detectLegacy() throws, all accents fall back to static	FIX	Fixed in 6c29e87
2	codex	— (clean) verdict: approve, 0 findings	clean	n/a
1–2	claude (/review)	No critical issues; version-gate/cache-buster/string bumps and the v3 descriptor all correct	clean	n/a
2	claude (/review)	Note (info, non-blocking): mandelbrot preview card now renders at the library's preview profile resolution (~0.2) instead of the site's former full resolution: 1 — intended v3 behaviour, budgets are library-owned	SKIP	Left as-is (v3 design)

Totals: 1 FIX (resolved in 6c29e87), 1 SKIP (info), 0 UNVERIFIED.

Verification: npm test 24/24, python3 -m unittest discover -s profile/tests 41/41. The v3 descriptor built by main.js was additionally checked against the real demoscene_classics dist/demoscene.js — 12/12 (effect × theme × device) pass the resolver's descriptor gate.

Local review mode does not merge automatically; merge is yours to trigger (CI is not configured for this repo).