Merge design/cloudflare-static-publish into main: Cloudflare static publish + CC credits

Integrates the fully-static Cloudflare publish line (live at
benstull.art/human-experience-simulator) into main: the static build (Pages + R2,
manifest-only media tree, baked API JSON), the "Run simulation" start button, the
public CC-BY/BY-SA credits page with the "License & reuse" CC BY-SA 4.0 derivative
declaration (Option A + D1), the repeatable Cloudflare deploy script, and assorted
load/audio fixes (progressive boot, scaleAudioUrl via mediaBase).

Clean auto-merge with main's per-clip affect/feelings + i18n work — only app.js and
altitude-lock.spec.ts overlapped, both auto-resolved. Verified green on the merged
tree: node 29, pytest 315 passed / 2 skipped.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

simulator/e2e/README.md

@@ -32,3 +32,24 @@ npm test
 
 `playwright.config.ts` starts uvicorn on port 8099 automatically (`reuseExistingServer`
 locally) and points the tests at it.
+
+## Static-build E2E (Cloudflare publish)
+
+`tests/static-build.spec.ts` verifies the **built static site** (Cloudflare publish
+— see `deploy/cloudflare/README.md`): it boots with NO `/api/*` server (baked JSON),
+and the WebGL dream shader runs on **cross-origin** media without tainting the GL
+texture (the CORS path R2 will use in production).
+
+It uses `playwright.static.config.ts` (no uvicorn `webServer`) and a dual static
+server, `serve-static.mjs`, that serves the built `dist/` (app, :8077) and
+`dist-media/` (media with CORS + Range, :8078):
+
+```bash
+# from the repo root: build with the media base pointed at the local CORS server
+.venv/bin/python -m tools.build_static --media-base http://localhost:8078/
+
+# from this directory (simulator/e2e): start the dual server, then run the spec
+DIST_DIR="$PWD/../../dist" MEDIA_DIR_E2E="$PWD/../../dist-media" node serve-static.mjs &
+npx playwright test --config playwright.static.config.ts
+```
+

simulator/e2e/playwright.static.config.ts

@@ -0,0 +1,11 @@
+import { defineConfig } from "@playwright/test";
+
+// Static-build E2E: NO webServer — the built dist/ + dist-media/ are served by
+// serve-static.mjs (started manually, see README.md), so there is no uvicorn/API.
+// Run: npx playwright test --config playwright.static.config.ts
+export default defineConfig({
+  testDir: "./tests",
+  testMatch: /static-build\.spec\.ts/,
+  timeout: 60_000,
+  use: { actionTimeout: 10_000 },
+});

simulator/e2e/serve-static.mjs

@@ -0,0 +1,48 @@
+// Serves the built dist/ (app) and dist-media/ (media, with CORS + Range) on two
+// ports — a local stand-in for Pages + R2, so the static-build E2E exercises the
+// cross-origin media path exactly as production will (CORS for the WebGL dream
+// shader, Range for video scrubbing).
+//
+// Env: DIST_DIR (app root), MEDIA_DIR_E2E (media root). Ports: app 8077, media 8078.
+import http from "node:http";
+import { createReadStream, statSync } from "node:fs";
+import { join, extname, normalize } from "node:path";
+
+const TYPES = {
+  ".html": "text/html", ".js": "text/javascript", ".json": "application/json",
+  ".css": "text/css", ".mp4": "video/mp4", ".mp3": "audio/mpeg",
+};
+
+function serve(root, port, cors, indexFallback) {
+  http.createServer((req, res) => {
+    if (cors) { res.setHeader("Access-Control-Allow-Origin", "*"); res.setHeader("Accept-Ranges", "bytes"); }
+    let p = decodeURIComponent(req.url.split("?")[0]);
+    if (p.endsWith("/")) p += "index.html";
+    // contain to root (no path traversal)
+    const file = normalize(join(root, p));
+    if (!file.startsWith(normalize(root))) { res.writeHead(403); return res.end("forbidden"); }
+    try {
+      const st = statSync(file);
+      res.setHeader("Content-Type", TYPES[extname(file)] || "application/octet-stream");
+      const range = req.headers.range;                       // honor Range for video scrub
+      if (range && /^bytes=/.test(range)) {
+        const [s, e] = range.replace("bytes=", "").split("-");
+        const start = +s, end = e ? +e : st.size - 1;
+        res.writeHead(206, {
+          "Content-Range": `bytes ${start}-${end}/${st.size}`,
+          "Content-Length": end - start + 1,
+        });
+        createReadStream(file, { start, end }).pipe(res);
+      } else {
+        res.writeHead(200, { "Content-Length": st.size });
+        createReadStream(file).pipe(res);
+      }
+    } catch {
+      res.writeHead(404); res.end("not found");
+    }
+  }).listen(port);
+}
+
+serve(process.env.DIST_DIR, 8077, false);
+serve(process.env.MEDIA_DIR_E2E, 8078, true);
+console.log("static app :8077  media(cors) :8078");

simulator/e2e/tests/altitude-lock.spec.ts

@@ -83,15 +83,27 @@ test("audio is a 0-10 level dial", async ({ page }) => {
   expect(ctl.max).toBe("10");
 });
 
-test("boots silent (video off, audio 0); turning video on couples audio to 3/10", async ({ page }) => {
+test("boots silent (video off, audio 0); turning video on couples audio to 2/10 and dismisses the Run prompt", async ({ page }) => {
   await boot(page);
   // Boots SILENT — no un-gestured auto-start, so the browser autoplay block never bites.
   expect(await page.evaluate(() => (document.querySelector("#visual") as HTMLInputElement).checked)).toBe(false);
   expect(await page.evaluate(() => (document.querySelector("#audio") as HTMLInputElement).value)).toBe("0");
-  // Turning Video on (a click gesture) lifts the audio dial to a gentle 3/10.
+  // "Run simulation" is revealed once preload finishes — the obvious starting point.
+  expect(await page.evaluate(() => document.querySelector("#run-sim")?.classList.contains("hidden"))).toBe(false);
+  // Turning Video on directly (a click gesture) lifts the audio dial to a gentle 2/10
+  // and dismisses the Run prompt.
   await enableVideo(page);
-  await expect.poll(() => page.evaluate(() => (document.querySelector("#audio") as HTMLInputElement).value)).toBe("3");
-  expect(await page.evaluate(() => document.querySelector("#audio-level-val")?.textContent)).toBe("3");
+  await expect.poll(() => page.evaluate(() => (document.querySelector("#audio") as HTMLInputElement).value)).toBe("2");
+  expect(await page.evaluate(() => document.querySelector("#audio-level-val")?.textContent)).toBe("2");
+  expect(await page.evaluate(() => document.querySelector("#run-sim")?.classList.contains("hidden"))).toBe(true);
+});
+
+test("the Run simulation button starts video, snaps audio to 2/10, and dismisses itself", async ({ page }) => {
+  await boot(page);
+  await page.click("#run-sim");
+  await expect.poll(() => page.evaluate(() => (document.querySelector("#visual") as HTMLInputElement).checked)).toBe(true);
+  await expect.poll(() => page.evaluate(() => (document.querySelector("#audio") as HTMLInputElement).value)).toBe("2");
+  expect(await page.evaluate(() => document.querySelector("#run-sim")?.classList.contains("hidden"))).toBe(true);
 });
 
 test("dragging the dial scrubs morph currentTime and audio gains", async ({ page }) => {

simulator/e2e/tests/static-build.spec.ts

@@ -0,0 +1,30 @@
+import { test, expect } from "@playwright/test";
+
+// Runs against the BUILT static site: dist/ served on :8077, media (CORS) on :8078
+// by serve-static.mjs. Build with `--media-base http://localhost:8078/` so config.js
+// points media cross-origin — the production CORS path, locally. See README.md.
+const APP = "http://localhost:8077/human-experience-simulator/";
+
+test("boots fully static — no /api calls, ring + clips load from baked JSON", async ({ page }) => {
+  const apiCalls: string[] = [];
+  page.on("request", (r) => { if (r.url().includes("/api/")) apiCalls.push(r.url()); });
+  await page.goto(APP);
+  await expect(page.locator("#vid")).toBeVisible({ timeout: 30_000 });
+  expect(apiCalls, "static build must not call /api/*").toEqual([]);
+});
+
+test("dream shader runs on cross-origin media without tainting the GL texture", async ({ page }) => {
+  const errors: string[] = [];
+  page.on("pageerror", (e) => errors.push(String(e)));
+  await page.goto(APP);
+  await expect(page.locator("#vid")).toBeVisible({ timeout: 30_000 });
+  // crank the Feel (Right) knob to engage the dream, let a few frames render
+  await page.evaluate(() => {
+    const r = document.getElementById("right") as HTMLInputElement;
+    r.value = "4";
+    r.dispatchEvent(new Event("input", { bubbles: true }));
+  });
+  await page.waitForTimeout(2000);
+  // a tainted GL texture throws SecurityError on draw; assert none surfaced
+  expect(errors.filter((e) => /SecurityError|tainted|cross-origin/i.test(e))).toEqual([]);
+});

simulator/static/alteration.js

@@ -0,0 +1,52 @@
+// Client-side port of player/alteration.py + player/audio.py (the alteration
+// engine). Replaces the live POST /api/alteration in the static build — pure math,
+// unity calibration (the client never sends a calibration, so DEFAULT_CALIBRATION
+// = all gains 1.0 always applies). UMD so the browser gets `HEFAlteration` and
+// `node --test` can require() it. Keep IN SYNC with the Python — the numeric
+// contract is guarded by tests/test_alteration_js_parity.py.
+(function (root, factory) {
+  const api = factory();
+  if (typeof module !== "undefined" && module.exports) module.exports = api;
+  else root.HEFAlteration = api;
+})(typeof self !== "undefined" ? self : this, function () {
+  "use strict";
+  const KNOB_MAX = 4;                                   // player/alteration.py:25
+  const clamp = (x, lo, hi) => Math.max(lo, Math.min(hi, x));
+
+  // Mirror of player/alteration.py::plan_alteration with DEFAULT_CALIBRATION (unity).
+  function plan(c) {
+    const tone = clamp((c.light - c.dark) / KNOB_MAX, -1, 1);
+    const overlayIntensity = clamp(c.left / KNOB_MAX, 0, 1);
+    const dreamIntensity = clamp(c.right / KNOB_MAX, 0, 1);
+    const affectIntensity = clamp(c.right / KNOB_MAX, 0, 1);   // affect uses overlay_gain too
+    const is_identity = tone === 0 && c.left === 0 && c.right === 0;
+    return {
+      grade: { tone },
+      overlay: { level: c.left, intensity: overlayIntensity },
+      affect: { strength: c.right, intensity: affectIntensity },
+      dream: { strength: c.right, intensity: dreamIntensity },
+      is_identity,
+    };
+  }
+
+  // Mirror of player/audio.py::resolve_audio. `scaleAudio` is the current scale's
+  // `audio` filename (relative to <mediaBase>audio/); off → silence.
+  function renderAudio(source, scaleAudio, mediaBase) {
+    if (source === "off") return { source: "off", url: null, altitude_coupled: false };
+    const url = scaleAudio ? mediaBase + "audio/" + scaleAudio : null;
+    return { source: "soundtrack", url, altitude_coupled: true };
+  }
+
+  // The full /api/alteration response shape, computed locally.
+  function alteration(controls, scaleAudio, mediaBase) {
+    return {
+      plan: plan(controls),
+      render: {
+        video: { shown: controls.visual === "on" },   // player/audio.py::resolve_visual
+        audio: renderAudio(controls.audio, scaleAudio, mediaBase),
+      },
+    };
+  }
+
+  return { plan, renderAudio, alteration, KNOB_MAX };
+});

simulator/static/app.js

@@ -57,14 +57,19 @@ let activeLang = "en";     // session-only; no persistence (resets to en each lo
 let lastAffect = null;     // {strength, intensity, right} from the last renderAffect, for re-render on language switch
 
 async function loadData() {
-  const clips = (await (await fetch("/api/clips")).json()).clips || [];
+  // Static build: boot from baked JSON (no server). Dev: the live API. The baked
+  // files sit alongside index.html, so RELATIVE urls resolve under the deploy path.
+  const api = (window.HEF_CONFIG && window.HEF_CONFIG.static)
+    ? { clips: "clips.json", versions: "media-versions.json", ring: "ring.json" }
+    : { clips: "/api/clips", versions: "/api/media-versions", ring: "/api/ring" };
+  const clips = (await (await fetch(api.clips)).json()).clips || [];
   clipsById = Object.fromEntries(clips.map((c) => [c.id, c]));
   // Per-file content-hash tokens → appended to /media URLs as ?v=<hash> so a
   // re-baked clip (new bytes, same path) gets a fresh URL the browser can't serve
   // stale. Best-effort: an empty map just yields un-versioned URLs.
-  try { mediaVersions = (await (await fetch("/api/media-versions")).json()).versions || {}; }
+  try { mediaVersions = (await (await fetch(api.versions)).json()).versions || {}; }
   catch (_) { mediaVersions = {}; }
-  const r = await fetch("/api/ring");
+  const r = await fetch(api.ring);
   serverRing = r.ok;
   ring = r.ok ? await r.json() : null;
   if (!ring && clips.length) {
@@ -87,16 +92,12 @@ async function loadData() {
 async function pickRandomMember() {
   const scale = ring && ring.scales[ringIndex];
   if (!scale) return null;
-  if (serverRing) {
-    try {
-      const resp = await fetch("/api/ring/advance", {
-        method: "POST", headers: { "content-type": "application/json" },
-        body: JSON.stringify({ from_index: ringIndex, delta: 0 }),
-      });
-      if (resp.ok) return (await resp.json()).target_clip_id;
-    } catch (_) { /* fall through to the primary member */ }
-  }
-  return scale.clip_id;
+  // Uniform random pool member, client-side (mirrors hef.selection.pick_clip_id).
+  // The drag/scroll navigation already resolves picks + morphs client-side via
+  // scrub.js; this removes the last /api/ring/advance dependency so the build is
+  // fully static. The synthesized fallback ring has a pool of one → returns it.
+  const pool = (scale.pool && scale.pool.length) ? scale.pool : [{ clip_id: scale.clip_id }];
+  return pool[Math.floor(Math.random() * pool.length)].clip_id;
 }
 
 // Land on the current scale: pick a random pool member and force its media to load.
@@ -118,9 +119,11 @@ let mediaVersions = {};   // file -> content-hash token (from /api/media-version
 // Network path for a media file, content-hash-versioned so a re-baked clip's URL
 // changes with its bytes (permanent cache-bust). The blob cache, when present,
 // wins — those bytes are already the current ones for this session.
-function mediaNetUrl(file) { const v = mediaVersions[file]; return "/media/" + file + (v ? "?v=" + v : ""); }
+function mediaBase() { return (window.HEF_CONFIG && window.HEF_CONFIG.mediaBase) || "/media/"; }
+function mediaNetUrl(file) { const v = mediaVersions[file]; return mediaBase() + file + (v ? "?v=" + v : ""); }
 function mediaUrl(file) {
-  if (file.startsWith("/media/")) return file;   // already a resolved absolute url (audio layer)
+  // Already a resolved absolute url (audio layer, or R2 in static mode): pass through.
+  if (/^https?:\/\//.test(file) || file.startsWith("/media/")) return file;
   return mediaBlobs[file] || mediaNetUrl(file);
 }
 
@@ -168,7 +171,12 @@ function preloadOrder() {
     }
   }
   for (const f of reachableMorphFiles()) add(f);
-  for (const f of preloadList()) add(f);   // sweep up anything not on the ring
+  for (const f of preloadList()) add(f);   // sweep up every base not already on the ring
+  // ALL morphs last: preloading every transition before interaction guarantees a
+  // smooth knob turn anywhere (any random pool re-roll lands on an already-cached
+  // morph). They're ordered last so the first scenes + nearest transitions cache
+  // first and the loading bar fills meaningfully.
+  for (const f of Object.values(morphByPair)) add(f);
   return ordered;
 }
 
@@ -702,12 +710,21 @@ function controls() {
 let timer = null;
 async function update() {
   if (busy) return;
-  const resp = await fetch("/api/alteration", {
-    method: "POST", headers: { "content-type": "application/json" },
-    body: JSON.stringify({ controls: controls(), altitude_index: ringIndex }),
-  });
-  if (!resp.ok) { readout.textContent = "invalid: " + resp.status; return; }
-  const data = await resp.json();
+  let data;
+  if (window.HEF_CONFIG && window.HEF_CONFIG.static) {
+    // Static build: compute the alteration locally (HEFAlteration is the JS port of
+    // player.alteration/audio). Audio couples to the current altitude's asset.
+    const scale = ring && ring.scales[ringIndex];
+    const scaleAudio = (scale && scale.audio) || "";
+    data = HEFAlteration.alteration(controls(), scaleAudio, mediaBase());
+  } else {
+    const resp = await fetch("/api/alteration", {
+      method: "POST", headers: { "content-type": "application/json" },
+      body: JSON.stringify({ controls: controls(), altitude_index: ringIndex }),
+    });
+    if (!resp.ok) { readout.textContent = "invalid: " + resp.status; return; }
+    data = await resp.json();
+  }
   readout.textContent = JSON.stringify(data, null, 2);
   // Tolerate a stale server that still returns {content:{video}} instead of the
   // {render:{video:{shown}}} (visual/audio-split) shape, so video works either way.
@@ -1129,6 +1146,7 @@ async function reroll() {
 // from the live API and masks it otherwise). Reloads on my edits AND on a server
 // restart. Dev-only convenience; harmless if the endpoint is absent.
 function devLiveReload() {
+  if (window.HEF_CONFIG && window.HEF_CONFIG.static) return;   // no dev server in the static build
   let seen = null;
   setInterval(async () => {
     try {
@@ -1237,7 +1255,10 @@ function scaleAudioUrl(index) {
   if (!ring || !ring.scales.length) return null;
   const s = ring.scales[HEFScrub.wrapIndex(index, ring.scales.length)];
   const a = s.audio || SCALE_AUDIO_FALLBACK[s.id];
-  return a ? "/media/audio/" + a : null;
+  // Route through mediaBase() so audio loads from R2 in the static build (and the
+  // local /media mount in dev) — NOT a hardcoded /media path, which 404s on the
+  // static site. mediaUrl() then passes this absolute url straight through.
+  return a ? mediaBase() + "audio/" + a : null;
 }
 // The current resting altitude's soundtrack url (kept for the status readout).
 function soundtrackUrl() { return scaleAudioUrl(ringIndex); }
@@ -1320,6 +1341,23 @@ function hideLoading() {
 
 let videoEverOn = false;      // has Video ever been switched on this session?
 
+// The gentle audio level the experience starts at — coupled in on the first
+// Video-on (via the Run simulation button or the Video toggle directly).
+const START_AUDIO_LEVEL = "2";
+
+// Begin the experience: Video on, audio snapped to the gentle start level, and
+// the "Run simulation" prompt dismissed. Audio is set + played in THIS gesture so
+// it unlocks on Safari (which blocks play() outside a user gesture). One flip = the
+// full experience at a gentle level. Idempotent across re-toggles via videoEverOn.
+function beginExperience() {
+  videoEverOn = true;
+  const btn = $("run-sim");
+  if (btn) btn.classList.add("hidden");
+  $("audio").value = START_AUDIO_LEVEL;
+  updateAudioLevelLabel();
+  applyAudio();
+}
+
 async function main() {
   devLiveReload();
   try { initPaint(); } catch (e) { paintOK = false; paint.style.display = "none"; showError("WebGL init: " + e.message); }
@@ -1336,14 +1374,17 @@ async function main() {
   // play() outside a user gesture).
   $("audio").addEventListener("input", () => { updateAudioLevelLabel(); applyAudio(); debounced(); });
   updateAudioLevelLabel();
-  // Video toggle: the FIRST time video turns on, bring audio up to 3/10 with it (one
-  // flip = the full experience at a gentle level). If audio is already raised, leave it.
-  // Set + played in THIS gesture so it unlocks on Safari.
+  // "Run simulation" button: the obvious starting point. Turns Video on, snaps
+  // audio to the start level, and dismisses itself — all in this click gesture.
+  $("run-sim").addEventListener("click", () => {
+    $("visual").checked = true;   // setting .checked does NOT fire "change", so we drive the rest here
+    beginExperience();
+    debounced();
+  });
+  // Video toggle: the FIRST time video turns on (without the Run simulation button),
+  // begin the experience too — couple audio in and dismiss the prompt.
   $("visual").addEventListener("change", () => {
-    if ($("visual").checked && !videoEverOn) {
-      videoEverOn = true;
-      if (audioLevel() === 0) { $("audio").value = "3"; updateAudioLevelLabel(); applyAudio(); }
-    }
+    if ($("visual").checked && !videoEverOn) beginExperience();
     debounced();
   });
   // Altitude knob: drag to turn (commit detents on release), scroll to step, tap a label to jump.
@@ -1353,13 +1394,18 @@ async function main() {
   dial.addEventListener("wheel", onWheel, { passive: false });
   $("stage").addEventListener("wheel", onWheel, { passive: false });
   update();                   // render the initial state (both toggles off → black, silent)
-  await preloadAllMedia();    // download all media, updating the loading bar
+  // Preload BEFORE interaction: a base for every altitude + all related morphs, so
+  // turning the knob is always smooth (no on-demand stall, no blank next scene). The
+  // "Loading Universe…" bar tracks this; the universe stays gated until it's ready.
+  await preloadAllMedia();
   hideLoading();              // experience is ready — boots SILENT (video off, audio 0)
+  $("run-sim").classList.remove("hidden");   // reveal the obvious starting point over the black stage
   // No un-gestured auto-start: a browser autoplay policy blocks an audio play() made
   // outside a user gesture (muted video survives, sound does not), so an auto-start
   // would show video but stay silent. Instead the experience waits for the operator to
-  // turn Video on — that click IS the gesture, and its handler (above) lifts audio to
-  // 3/10 and starts the soundtrack in-gesture, so sound reliably comes up with video.
+  // press "Run simulation" (or turn Video on directly) — that click IS the gesture, and
+  // beginExperience() lifts audio to the start level and plays the soundtrack in-gesture,
+  // so sound reliably comes up with video.
 }
 
 // Populate the language dropdown from the registry and wire live switching.
@@ -1396,3 +1442,31 @@ function setLanguage(lang) {
 }
 
 main();
+
+// Temporary ?debug overlay: an on-screen readout of media/render state, for
+// diagnosing real-browser playback that headless can't reproduce. Add ?debug to the
+// URL to show it. Harmless/no-op without the flag; safe to remove once resolved.
+(function debugOverlay() {
+  if (!/[?&]debug\b/.test(location.search)) return;
+  const box = document.createElement("div");
+  box.style.cssText = "position:fixed;left:6px;bottom:6px;z-index:99999;max-width:96vw;" +
+    "background:rgba(0,0,0,.82);color:#0f0;font:11px/1.35 monospace;padding:8px 10px;" +
+    "white-space:pre-wrap;border:1px solid #0a0;border-radius:4px;";
+  document.body.appendChild(box);
+  let webgl = "?";
+  try { const c = document.createElement("canvas"); webgl = c.getContext("webgl2") ? "webgl2" : (c.getContext("webgl") ? "webgl1" : "NONE"); }
+  catch (e) { webgl = "throw:" + e.message; }
+  const errs = [];
+  window.addEventListener("error", (e) => { errs.push((e.message || e.error || "err").toString().slice(0, 80)); });
+  const m = (el) => el ? `rs=${el.readyState} ${el.paused ? "PAUSED" : "play"} t=${(el.currentTime || 0).toFixed(1)} err=${el.error ? el.error.code : "-"} ${(el.currentSrc || el.src || "(no src)").slice(0, 46)}` : "absent";
+  setInterval(() => {
+    const cfg = window.HEF_CONFIG || {};
+    box.textContent =
+      `cfg: static=${cfg.static} base=${cfg.mediaBase}\n` +
+      `webgl=${webgl}  visual=${(document.getElementById("visual") || {}).checked}\n` +
+      `loop : ${m(document.getElementById("vid-loop"))}\n` +
+      `morph: ${m(document.getElementById("vid"))}\n` +
+      `aud  : ${m(document.getElementById("aud"))}\n` +
+      `errs : ${errs.slice(-3).join(" | ") || "none"}`;
+  }, 400);
+})();

simulator/static/config.js

@@ -0,0 +1,4 @@
+// Runtime config. This dev default serves media from the local FastAPI /media
+// mount and uses the live API. The static build (tools/build_static.py) OVERWRITES
+// this file in dist/ with { mediaBase: "https://static.benstull.art/", static: true }.
+window.HEF_CONFIG = { mediaBase: "/media/", static: false };

simulator/static/credits.html

@@ -0,0 +1,65 @@
+<!doctype html>
+<html lang="en">
+<head>
+  <meta charset="utf-8" />
+  <meta name="viewport" content="width=device-width, initial-scale=1" />
+  <title>Credits — Human Experience Filter</title>
+  <link rel="stylesheet" href="style.css" />
+</head>
+<body class="credits-page">
+  <main class="credits-wrap">
+    <header>
+      <h1>Credits &amp; licenses</h1>
+      <p><a href="index.html" class="back-link">← Back to the experience</a></p>
+    </header>
+
+    <!-- Option D1: the altered work's own license + the "modified" statement that
+         CC BY / CC BY-SA attribution requires. Heading deliberately NOT "About" — the
+         separate About page covers the project's intent. -->
+    <section class="declaration">
+      <h2>License &amp; reuse</h2>
+      <p>
+        The <em>Human Experience Filter</em> alters its source footage in real time
+        (overlays, an emotion/affect channel, and a WebGL “dream” shader), so every
+        frame you see is a <strong>derivative</strong> of the original clip.
+      </p>
+      <p>
+        This altered work is offered under
+        <a href="https://creativecommons.org/licenses/by-sa/4.0/" rel="license">Creative
+        Commons Attribution-ShareAlike 4.0 (CC BY-SA 4.0)</a>. The original sources it
+        builds on are credited below. This is a non-commercial art installation.
+      </p>
+    </section>
+
+    <section>
+      <h2>Footage</h2>
+      <p class="note">
+        Original video sources and their licenses. Public-domain (US-government) and
+        CC0 clips need no attribution; the names below for CC BY / CC BY-SA clips are
+        required credit. All footage is altered as described above.
+      </p>
+      <div id="video-credits" class="credits-list">
+        <p class="loading">Loading credits…</p>
+      </div>
+    </section>
+
+    <!-- Audio is all public-domain / CC0, so attribution is courtesy, not required;
+         it isn't tracked per-clip in the API, so it's acknowledged here as a block. -->
+    <section>
+      <h2>Sound</h2>
+      <p class="note">
+        Soundtracks are public domain or CC0 — credit is courtesy, not required.
+      </p>
+      <ul class="audio-credits">
+        <li><strong>NASA / Chandra X-ray Observatory (CXC/SAO)</strong> — cosmos sonification (public domain).</li>
+        <li><strong>NOAA</strong> SanctSound &amp; PMEL hydrophone recordings — reef/abyss biological layers (public domain).</li>
+        <li><strong>freesound.org</strong> contributors — Sonicfreak (station room-tone) and DCSFX (underwater bed) (CC0).</li>
+        <li><strong>BigSoundBank</strong> — sea waves &amp; gull calls (CC0).</li>
+      </ul>
+    </section>
+  </main>
+
+  <script src="config.js"></script>
+  <script src="credits.js"></script>
+</body>
+</html>

simulator/static/credits.js

@@ -0,0 +1,75 @@
+// Credits/colophon data + render — no framework. UMD so the browser gets a
+// `HEFCredits` global and `node --test` can require() the pure functions.
+//
+// The legally load-bearing attribution is per VIDEO clip (CC BY / CC BY-SA need
+// the author + license shown to the viewer, and the footage is altered → a
+// derivative). That data already ships in clips.json (baked from /api/clips):
+// each clip carries free-text `license` + `source`. This module turns that into
+// the credits list the public colophon (credits.html) renders. Audio is all
+// PD/CC0 and credited as a static courtesy block in the page itself.
+(function (root, factory) {
+  const api = factory();
+  if (typeof module !== "undefined" && module.exports) module.exports = api;
+  else root.HEFCredits = api;
+})(typeof self !== "undefined" ? self : this, function () {
+  "use strict";
+
+  function escapeHtml(s) {
+    return String(s == null ? "" : s)
+      .replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;")
+      .replace(/"/g, "&quot;");
+  }
+
+  // One attribution entry per clip, sorted by id (deterministic). A clip is
+  // NEVER silently dropped — even one with an empty license appears, so a
+  // missing credit is visible rather than hidden. License/source are the
+  // free-text strings authored in the manifest.
+  function creditEntries(clips) {
+    return (clips || [])
+      .map((c) => ({
+        id: c.id,
+        title: c.title || c.id,
+        license: c.license || "",
+        source: c.source || "",
+      }))
+      .sort((a, b) => String(a.id).localeCompare(String(b.id)));
+  }
+
+  function creditHtml(e) {
+    const lic = e.license
+      ? `<span class="lic">${escapeHtml(e.license)}</span>`
+      : `<span class="lic missing">license not recorded</span>`;
+    const src = e.source ? `<div class="src">${escapeHtml(e.source)}</div>` : "";
+    return (
+      `<div class="credit">` +
+      `<div class="title">${escapeHtml(e.title)}</div>` +
+      lic + src +
+      `</div>`
+    );
+  }
+
+  function creditsListHtml(clips) {
+    return creditEntries(clips).map(creditHtml).join("");
+  }
+
+  // Browser bootstrap: fetch the same clips the experience uses (baked
+  // clips.json in the static build, the live API otherwise — the config.js
+  // flag, loaded before this script, decides) and fill the container.
+  function init(doc, cfg) {
+    const fetchUrl = cfg && cfg.static ? "clips.json" : "/api/clips";
+    const box = doc.getElementById("video-credits");
+    if (!box) return;
+    return fetch(fetchUrl)
+      .then((r) => r.json())
+      .then((d) => { box.innerHTML = creditsListHtml(d.clips || []); })
+      .catch((err) => { box.innerHTML = `<p class="err">Could not load credits: ${escapeHtml(err.message)}</p>`; });
+  }
+
+  if (typeof document !== "undefined") {
+    document.addEventListener("DOMContentLoaded", () => {
+      init(document, (typeof window !== "undefined" && window.HEF_CONFIG) || {});
+    });
+  }
+
+  return { escapeHtml, creditEntries, creditHtml, creditsListHtml, init };
+});

simulator/static/i18n.js

@@ -19,6 +19,8 @@
   const UI_STRINGS = {
     "app.title":      { en: "Human Experience Filter — Alteration Preview", es: "Filtro de Experiencia Humana — Vista previa de alteración", fr: "Filtre d’Expérience Humaine — Aperçu d’altération", ja: "ヒューマン・エクスペリエンス・フィルター — 変容プレビュー" },
     "loading.title":  { en: "Loading Universe", es: "Cargando el universo", fr: "Chargement de l’univers", ja: "宇宙を読み込み中" },
+    "run.button":     { en: "Run simulation", es: "Iniciar simulación", fr: "Lancer la simulation", ja: "シミュレーションを開始" },
+    "credits.link":   { en: "ⓘ Credits & licenses", es: "ⓘ Créditos y licencias", fr: "ⓘ Crédits et licences", ja: "ⓘ クレジットとライセンス" },
     "output.legend":  { en: "Output", es: "Salida", fr: "Sortie", ja: "出力" },
     "output.video":   { en: "Video", es: "Vídeo", fr: "Vidéo", ja: "映像" },
     "output.audio":   { en: "Audio", es: "Audio", fr: "Audio", ja: "音声" },

simulator/static/index.html

@@ -4,7 +4,7 @@
   <meta charset="utf-8" />
   <meta name="viewport" content="width=device-width, initial-scale=1" />
   <title>HEF — Alteration Simulator</title>
-  <link rel="stylesheet" href="/style.css" />
+  <link rel="stylesheet" href="style.css" />
 </head>
 <body>
   <div id="loading">
@@ -13,19 +13,23 @@
       <div class="loading-bar"><div id="loading-fill"></div></div>
     </div>
   </div>
-  <header><h1 data-i18n="app.title">Human Experience Filter — Alteration Preview</h1></header>
+  <header>
+    <h1 data-i18n="app.title">Human Experience Filter — Alteration Preview</h1>
+    <a href="credits.html" class="credits-link" data-i18n="credits.link">ⓘ Credits &amp; licenses</a>
+  </header>
   <main>
     <section class="stage" id="stage">
       <div class="screen">
-        <video id="vid" loop muted playsinline></video>
-        <video id="vid-loop" loop muted playsinline></video>
-        <audio id="aud" loop preload="auto"></audio>
-        <audio id="aud-b" loop preload="auto"></audio>
+        <video id="vid" loop muted playsinline crossorigin="anonymous"></video>
+        <video id="vid-loop" loop muted playsinline crossorigin="anonymous"></video>
+        <audio id="aud" loop preload="auto" crossorigin="anonymous"></audio>
+        <audio id="aud-b" loop preload="auto" crossorigin="anonymous"></audio>
         <canvas id="paint"></canvas>
         <div id="tint"></div>
         <svg id="overlay" viewBox="0 0 100 100" preserveAspectRatio="none"></svg>
         <svg id="affect" viewBox="0 0 100 100" preserveAspectRatio="none"></svg>
         <div id="black" class="black hidden"></div>
+        <button type="button" id="run-sim" class="run-sim hidden" data-i18n="run.button">Run simulation</button>
       </div>
     </section>
 
@@ -107,8 +111,10 @@
       </div>
     </section>
   </main>
-  <script src="/scrub.js"></script>
-  <script src="/i18n.js"></script>
-  <script src="/app.js"></script>
+  <script src="config.js"></script>
+  <script src="scrub.js"></script>
+  <script src="alteration.js"></script>
+  <script src="i18n.js"></script>
+  <script src="app.js"></script>
 </body>
 </html>

simulator/static/style.css

@@ -1,7 +1,32 @@
 * { box-sizing: border-box; }
 body { margin: 0; font: 14px/1.4 system-ui, sans-serif; background: #111; color: #eee; }
-header { padding: 0.6rem 1rem; background: #000; }
+header { padding: 0.6rem 1rem; background: #000; display: flex; align-items: baseline;
+         justify-content: space-between; gap: 1rem; }
 h1 { font-size: 1rem; margin: 0; font-weight: 600; }
+/* Always-visible link to the credits/colophon — reachable from the work, which is
+   what CC BY / BY-SA attribution "reasonable to the medium" calls for. */
+.credits-link { color: #9af; text-decoration: none; font-size: 12px; white-space: nowrap; flex: none; }
+.credits-link:hover { text-decoration: underline; }
+
+/* --- Credits / colophon page (credits.html) --- */
+.credits-page { background: #0c0f14; }
+.credits-wrap { max-width: 760px; margin: 0 auto; padding: 2rem 1.25rem 4rem; }
+.credits-wrap h1 { font-size: 1.6rem; }
+.credits-wrap h2 { font-size: 1.05rem; color: #9af; margin: 1.8rem 0 0.5rem; }
+.credits-wrap a { color: #9af; }
+.credits-wrap .back-link { font-size: 13px; }
+.credits-wrap .note { color: #9ab; font-size: 13px; }
+.declaration { background: #131a24; border: 1px solid #233; border-radius: 6px;
+               padding: 0.8rem 1rem; margin-top: 1rem; }
+.credits-list { display: grid; gap: 0.7rem; margin-top: 0.8rem; }
+.credit { background: #131820; border: 1px solid #1f2a3a; border-radius: 5px; padding: 0.6rem 0.8rem; }
+.credit .title { font-weight: 600; color: #dfe7f2; }
+.credit .lic { display: inline-block; margin-top: 0.2rem; font-size: 12px; color: #cbd; }
+.credit .lic.missing { color: #f97; }
+.credit .src { margin-top: 0.3rem; font-size: 12px; color: #8aa; line-height: 1.5; }
+.audio-credits { color: #b9c4d2; font-size: 13px; line-height: 1.6; padding-left: 1.2rem; }
+.credits-list .loading, .credits-list .err { color: #9ab; }
+.credits-list .err { color: #f97; }
 main { display: flex; gap: 1rem; padding: 1rem; flex-wrap: wrap; align-items: flex-start; }
 /* Stage stays pinned in view while the right pane scrolls on its own. */
 .stage { flex: 1 1 640px; position: sticky; top: 1rem; }
@@ -51,6 +76,20 @@ main { display: flex; gap: 1rem; padding: 1rem; flex-wrap: wrap; align-items: fl
 .black { position: absolute; inset: 0; background: #000; opacity: 1;
          z-index: 50; transform: translateZ(0); transition: opacity 200ms ease; }
 .hidden { display: none; }
+/* "Run simulation" — the obvious starting point, shown over the (black) stage once
+   media is preloaded. Sits above the black cover (z-index 50). Dismissed when the
+   experience begins (the button, or turning Video on directly). */
+.run-sim {
+  position: absolute; top: 50%; left: 50%; transform: translate(-50%, -50%);
+  z-index: 60; cursor: pointer; user-select: none;
+  padding: 0.85rem 2rem; border: 0; border-radius: 999px;
+  font: 600 18px/1 system-ui, sans-serif; letter-spacing: 0.03em;
+  color: #04101f; background: linear-gradient(90deg, #4e9cff, #9af);
+  box-shadow: 0 4px 24px rgba(78, 156, 255, 0.45);
+  transition: transform 0.12s ease, box-shadow 0.12s ease;
+}
+.run-sim:hover { transform: translate(-50%, -50%) scale(1.04); box-shadow: 0 6px 30px rgba(78, 156, 255, 0.6); }
+.run-sim:active { transform: translate(-50%, -50%) scale(0.98); }
 /* Stack the two Output toggles (Video / Audio) with a little breathing room. */
 .dev-switch + .dev-switch { margin-top: 0.45rem; }
 /* Live audio status readout (diagnostic) — turns green when actually playing. */

simulator/unit/alteration.test.js

@@ -0,0 +1,51 @@
+"use strict";
+const test = require("node:test");
+const assert = require("node:assert/strict");
+const A = require("../static/alteration.js");
+
+const c = (o) => ({ visual: "on", audio: "off", left: 0, right: 0, dark: 0, light: 0, ...o });
+
+test("identity at zero knobs", () => {
+  const p = A.plan(c({}));
+  assert.equal(p.grade.tone, 0);
+  assert.equal(p.overlay.level, 0);
+  assert.equal(p.dream.strength, 0);
+  assert.equal(p.is_identity, true);
+});
+
+test("mood tone is signed (light - dark)/KNOB_MAX, clamped", () => {
+  assert.equal(A.plan(c({ light: 4 })).grade.tone, 1);     // full light
+  assert.equal(A.plan(c({ dark: 4 })).grade.tone, -1);     // full dark
+  assert.equal(A.plan(c({ light: 2 })).grade.tone, 0.5);
+});
+
+test("left drives overlay level + intensity; right drives dream + affect", () => {
+  const p = A.plan(c({ left: 2, right: 4 }));
+  assert.equal(p.overlay.level, 2);
+  assert.equal(p.overlay.intensity, 0.5);
+  assert.equal(p.dream.strength, 4);
+  assert.equal(p.dream.intensity, 1);
+  assert.equal(p.affect.strength, 4);
+  assert.equal(p.affect.intensity, 1);
+  assert.equal(p.is_identity, false);
+});
+
+test("renderAudio: off → null, no coupling", () => {
+  assert.deepEqual(A.renderAudio("off", "cosmos.mp3", "https://x/"),
+    { source: "off", url: null, altitude_coupled: false });
+});
+
+test("renderAudio: soundtrack → mediaBase audio url, coupled", () => {
+  assert.deepEqual(A.renderAudio("soundtrack", "cosmos.mp3", "https://x/"),
+    { source: "soundtrack", url: "https://x/audio/cosmos.mp3", altitude_coupled: true });
+  // no scale audio → null url but still coupled
+  assert.deepEqual(A.renderAudio("soundtrack", "", "https://x/"),
+    { source: "soundtrack", url: null, altitude_coupled: true });
+});
+
+test("alteration() composes plan + render with video.shown from visual", () => {
+  const r = A.alteration(c({ visual: "off", audio: "soundtrack", left: 1 }), "reef.mp3", "https://x/");
+  assert.equal(r.render.video.shown, false);
+  assert.equal(r.render.audio.url, "https://x/audio/reef.mp3");
+  assert.equal(r.plan.overlay.level, 1);
+});

simulator/unit/credits.test.js

@@ -0,0 +1,66 @@
+"use strict";
+const test = require("node:test");
+const assert = require("node:assert/strict");
+const fs = require("node:fs");
+const path = require("node:path");
+const C = require("../static/credits.js");
+
+const CLIPS = [
+  { id: "reef_x", title: "Reef X", license: "CC-BY-SA 4.0 — credit Joe Mabel", source: "Wikimedia <reef>" },
+  { id: "cosmos", title: "Cosmic Cliffs", license: "CC-BY-class — credit NASA, ESA, CSA, STScI", source: "NASA SVS 31348" },
+  { id: "pd_only", title: "PD clip", license: "public-domain (US Gov, 17 U.S.C. §105)", source: "NASA" },
+];
+
+test("creditEntries returns one entry per clip, preserving license/source", () => {
+  const out = C.creditEntries(CLIPS);
+  assert.equal(out.length, CLIPS.length, "no clip is silently dropped from the credits");
+  const reef = out.find((e) => e.id === "reef_x");
+  assert.equal(reef.license, "CC-BY-SA 4.0 — credit Joe Mabel");
+  assert.equal(reef.source, "Wikimedia <reef>");
+  assert.equal(reef.title, "Reef X");
+});
+
+test("creditEntries is sorted by id for deterministic output", () => {
+  const ids = C.creditEntries(CLIPS).map((e) => e.id);
+  assert.deepEqual(ids, ["cosmos", "pd_only", "reef_x"]);
+});
+
+test("creditEntries falls back title->id and tolerates missing fields", () => {
+  const out = C.creditEntries([{ id: "bare" }]);
+  assert.deepEqual(out, [{ id: "bare", title: "bare", license: "", source: "" }]);
+});
+
+test("creditEntries handles null/empty input", () => {
+  assert.deepEqual(C.creditEntries(null), []);
+  assert.deepEqual(C.creditEntries([]), []);
+});
+
+test("creditsListHtml renders every clip's attribution and escapes HTML", () => {
+  const html = C.creditsListHtml(CLIPS);
+  assert.match(html, /Cosmic Cliffs/);
+  assert.match(html, /Joe Mabel/);
+  // free-text source "Wikimedia <reef>" must be escaped, not injected as a tag
+  assert.match(html, /Wikimedia &lt;reef&gt;/);
+  assert.doesNotMatch(html, /<reef>/);
+  // one block per clip
+  const blocks = html.match(/class="credit"/g) || [];
+  assert.equal(blocks.length, CLIPS.length);
+});
+
+test("credits.html wires config.js + credits.js, the attributions container, and a back link", () => {
+  const html = fs.readFileSync(path.join(__dirname, "../static/credits.html"), "utf8");
+  assert.match(html, /<script src="config\.js">/);   // static/live media-base + flag
+  assert.match(html, /<script src="credits\.js">/);
+  assert.match(html, /id="video-credits"/);           // JS fills this
+  assert.match(html, /href="index\.html"/);           // back into the experience
+});
+
+test("credits.html carries the CC BY-SA derivative declaration (Option D1)", () => {
+  const html = fs.readFileSync(path.join(__dirname, "../static/credits.html"), "utf8");
+  assert.match(html, /CC BY-SA 4\.0/);                 // the altered work's own license
+  assert.match(html, /altered/i);                      // states the footage is modified
+  // The section is NOT titled "About this work" — that name belongs to the separate
+  // About page; here the declaration lives under "License & reuse".
+  assert.doesNotMatch(html, /About this work/i);
+  assert.match(html, /License &amp; reuse/);
+});

simulator/unit/index-i18n.test.js

@@ -8,7 +8,7 @@ const I = require("../static/i18n.js");
 const html = fs.readFileSync(path.join(__dirname, "../static/index.html"), "utf8");
 
 test("index.html includes the i18n script and a language select", () => {
-  assert.match(html, /<script src="\/i18n\.js">/);
+  assert.match(html, /<script src="i18n\.js">/);   // relative: works at dev-root and under the deploy path prefix
   assert.match(html, /id="lang-select"/);
 });