Merge pull request 'perf(sim): preload all clips into memory for instant altitude swaps' (#19) from feature/preload-media-cache into main

Each altitude change reset the single <video> element's src and re-fetched
the scale's footage over the network, compounded by the dev no-store policy
applying to /media too — so every scale change paid a full fetch+decode.

- simulator/app.py: split the cache middleware — app shell/JS/CSS stay
  no-store (by-eye dev iteration), but /media is now cacheable
  (public, max-age, immutable) since the clips are static.
- simulator/static/app.js: preload every ring clip (19 base + 5 transition,
  ~350 MB) into in-memory blob object URLs at startup — non-blocking, the
  first scale plays immediately while the rest stream in, ordered current
  scale outward. mediaUrl() serves the cached blob when ready, else falls
  back to the network. A small progress chip self-removes when done.
- tests: assert app assets stay no-store and /media is cacheable.

269 passed, 2 skipped. Frontend verified by-eye by the operator (no headless
browser in repo yet).

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

sessions/0016/SESSION-0016.0-TRANSCRIPT-2026-06-24T17-48--2026-06-24T21-46.md

@@ -0,0 +1,117 @@
+# Session 0016.0 — Transcript
+
+> App: human-experience-filter-art
+> Start: 2026-06-24T17-48 (PST)
+> Type: planning-and-executing
+> Posture: yolo
+> Claude-Session: 0fde1d36-7c64-414f-8f49-8669b5dd2263
+> Status: **FINALIZED**
+
+## Launch prompt
+
+`/goal` Content pipeline Increment 2 (expanded) — rotating clip pools + time-windowed
+TRACKED labels + progressive left-brain detail + progressive right-brain emotions.
+Short design pass first (schema changes), then build.
+
+> Anchor: design `docs/superpowers/specs/2026-06-24-content-pipeline-design.md`
+> (graduated, R2a-eligible). Repo is roadmap-anchored, no Gitea issue tracker (R1
+> deviation, as all prior sessions). Increment 2 of that design.
+
+## Pre-state
+
+`main` at `b28f930` (PR #15 — operator-curated rotating-pool doc merged). All 19
+vetted pool clips on disk (gitignored) plus the leftovers to drop. The ring was the
+Increment-1 one-base-per-scale model (cosmos/orbit/forest/reef/abyss), flat
+`min_level` label gating, static or simple-track boxes, scene-level affect gated by
+`min(left,right)`. `tools/pipeline/` had stages 1–4 + 6 (no `track.py`). 246 tests.
+
+## Arc
+
+1. **Session gate + init.** Classified the `/goal` as planning-and-executing,
+   claimed session **0016** (peeked an ENDED-UNFINALIZED 0015 — its PR #15 work was
+   already merged, not live — and proceeded; no worktree needed, solo session).
+   Verified clean `main`, read the pool doc + spec + sub-project-3 memory + the live
+   code (ring, clips, app, app.js, alteration, pipeline).
+2. **Design pass (operator asked for it — schema changes).** Appended **§11** to the
+   content-pipeline spec pinning the concrete shapes: rotating pool, time-windowed
+   tracks, progressive Left detail tiers (salience + tiered strings), progressive
+   Right emotion tiers, and the `track.py` + author-mode tooling. Key call: tiers
+   need **no engine change** — the client reads `overlay.level` (Left) and
+   `dream.strength` (Right) already in the `RenderPlan`.
+3. **PR #16 — the experience.** `Scale.pool` + pure `pick_clip_id` (injected
+   randomness); server-side random pick at the API boundary (delta=0 = initial pick).
+   `forest`→`coast` rename + ring reorder + orphan-media cleanup. Time-windowed
+   tracked labels (`appear`/`disappear`, seam-wrapping). Salience-gated +
+   tier-escalating Left labels; tier-escalating Right emotions; tiered-or-static
+   strings (back-compat). New `build_pool_manifest.py` emits the 19-clip pool
+   manifest (abyss+reef authored as tracked/windowed showcase). Merged via Gitea API.
+4. **PR #17 — the tooling.** `tools/pipeline/track.py`: classical LK optical-flow box
+   tracker (this opencv build has no CSRT) → sparse keyframed track + window; optional
+   lazy ML path. Simulator AUTHOR MODE (`/author.html` + `/api/author/{track,clip}`):
+   scrub, drag a seed box, run tracker, author tiers/affect, save to manifest
+   (idempotent upsert, keeps provenance). Repointed the pipeline integration test off
+   the retired forest base; USER_GUIDE sim section brought current. Merged.
+
+## Cut state
+
+`main` at `c445239` (PR #17 merge). **267 passed / 2 skipped.** Clean tree, fully
+pushed, no open PRs. Both feature branches deleted. All 5 goal items delivered.
+
+Verification was API/logic-level + JS syntax + live-server probes (5 scales with
+pools, rotating picks, new edges, 19 clips served, tracker returns keyframes on real
+abyss_wow footage, committed manifest untouched by the read-only probe). **The
+VISUAL look was not screenshot-verified — no Chrome on this box** — so operator
+by-eye review is the next step (matches the established deferred-review pattern).
+
+## Follow-up (post-finalize, same conversation) — PR #18
+
+Operator asked to replace the scale-ring `⊖ out / in ⊕` buttons with a **circular
+"Altitude" knob** that turns all the way around (including abyss→cosmos). Built a
+turnable SVG dial in `simulator/static/app.js` (`buildDial` / `renderDial` / drag +
+wheel handlers) + `style.css`: cosmos (highest) at top, clockwise descends
+cosmos→orbit→coast→reef→abyss and **wraps** back up. Dragging accumulates rotation
+and commits whole detents on release (a big spin → one fast blended pass, reusing
+the proven wheel/detent path); scroll the knob to step; tap a label to jump the
+shortest way around. **Pure frontend** — the endless ring + wrap already existed
+server-side, so no engine/API change. JS syntax-checked; 23 sim-API tests green;
+live probe confirmed the dial replaced the buttons and the abyss→cosmos wrap is
+intact. Merged as **PR #18** (`main` at `7a32ff1`). Visual look still operator-by-eye
+(no Chrome on this box).
+
+## Deployment pipeline (§9)
+
+No stage run: the HEF simulator is a **local dev tool** (simulator-first directive),
+not a deployed app — it has no PPE/prod infra. Nothing shippable through the §9
+pipeline this session; the session output is the merged code on `main`.
+
+## Plan archival
+
+No separate `superpowers:writing-plans` artifact was produced — the design pass was a
+spec §11 edit (merged in PR #16) and execution was direct TDD tracked by the
+transcript `## Plan` block + the task list. Nothing to `submit-plan.sh`; this app has
+no content repo anyway (roadmap-anchored).
+
+## Deferred decisions
+
+- **Adopting/finalizing the ENDED-UNFINALIZED session 0015 placeholder** was skipped
+  — its PR #15 work is already on `main` and its outcomes are fully recorded in
+  memory; finalizing a prior dead session was judged an unnecessary detour. Low
+  confidence; flagging for the operator.
+- **By-eye visual review deferred** to the operator (no Chrome here) — consistent with
+  the prior-session pattern, but the look of the tiers/windows/pool rotation AND the
+  new Altitude knob is unconfirmed visually.
+- **Light-vs-rich label authoring:** only abyss + reef + the scale primaries are
+  richly authored; the other pool members carry lighter labels. Finishing them is the
+  author-mode follow-up (next goal).
+
+## Next-session prompt
+
+`/goal` Operator by-eye review of Increment 2 + the Altitude knob in the sim
+(`make sim-local`, :8000): turn the Altitude knob (drag/scroll, wraps abyss→cosmos;
+pools rotate per landing), sweep Left (progressive label tiers
+general→scientific+fact), sweep Right with Left up (progressive emotions
+basic→compound), watch abyss/reef time-windowed tracked labels enter/leave + track,
+and exercise `/author.html`. Then author real labels for the remaining pool members
+via author mode. After the content is liked, the next build frontier is the deferred
+i2v ring transitions (generative-video model + adjacent real bases) and/or the Pi
+renderer + serial/firmware (per [[simulator-first-before-hardware]]), per ROADMAP.md.

sessions/0017/SESSION-0017.0-TRANSCRIPT-2026-06-25T07-41--INPROGRESS.md

@@ -1,15 +1,15 @@
-# Session 0016.0 — Transcript
+# Session 0017.0 — Transcript
 
 > App: human-experience-filter-art
-> Start: 2026-06-24T17-48 (PST)
+> Start: 2026-06-25T07-41 (PST)
 > Type: planning-and-executing
 > Posture: yolo
-> Claude-Session: 0fde1d36-7c64-414f-8f49-8669b5dd2263
+> Claude-Session: bcb069f2-0fba-4a66-ae8e-f40b7917a48c
 > Status: **PLACEHOLDER — claimed at session start; finalized at session end.**
 >
-> This file reserves session ID 0016 for human-experience-filter-art. The driver replaces this
+> This file reserves session ID 0017 for human-experience-filter-art. The driver replaces this
 > body with the full transcript and renames the file to its final
-> SESSION-0016.0-TRANSCRIPT-2026-06-24T17-48--<end>.md form at session end.
+> SESSION-0017.0-TRANSCRIPT-2026-06-25T07-41--<end>.md form at session end.
 
 ## Launch prompt
 

sessions/sessions.json

@@ -46,5 +46,8 @@
   },
   "0016": {
     "title": ""
+  },
+  "0017": {
+    "title": ""
   }
 }

simulator/app.py

@@ -234,12 +234,18 @@ def create_app(manifest_path: Optional[Path] = None) -> FastAPI:
         return {"ok": True, "clip": merged}
 
     @app.middleware("http")
-    async def _no_cache(request, call_next):
-        # Dev preview server: never let a browser serve a stale app.js/style.css.
-        # The whole point is by-eye iteration, so a plain refresh must always get
-        # the latest assets (the heuristic cache otherwise hides JS/CSS edits).
+    async def _cache_policy(request, call_next):
+        # Dev preview server: never let a browser serve a stale app.js/style.css —
+        # by-eye iteration needs a plain refresh to always get the latest assets.
+        # Media is the exception: the clips are static and large, so they must be
+        # browser-cacheable. The renderer also preloads them into in-memory blob
+        # URLs (static/app.js), but a cacheable header keeps the preload fetch and
+        # any fallback off the network on repeat loads — instant altitude swaps.
         response = await call_next(request)
-        response.headers["Cache-Control"] = "no-cache, no-store, must-revalidate"
+        if request.url.path.startswith("/media/"):
+            response.headers["Cache-Control"] = "public, max-age=31536000, immutable"
+        else:
+            response.headers["Cache-Control"] = "no-cache, no-store, must-revalidate"
         return response
 
     if MEDIA_DIR.exists():

simulator/static/app.js

@@ -75,7 +75,79 @@ function activeClip() {
   return clipsById[activeClipId] || null;
 }
 
-function mediaUrl(file) { return "/media/" + file; }
+// In-memory preload cache: media file path -> blob object URL. Once a clip's bytes
+// are cached, mediaUrl() hands the <video> an in-memory blob instead of a network
+// path, so swapping the altitude scale loads near-instantly (no fetch round-trip).
+// Falls back to the network path for anything not yet (or never) cached.
+const mediaBlobs = {};
+function mediaUrl(file) { return mediaBlobs[file] || ("/media/" + file); }
+
+// Every media file the ring can show: each scale-pool clip's base footage plus the
+// per-edge transition clips. This is the full preload set (~two dozen files).
+function preloadList() {
+  const files = new Set();
+  for (const c of Object.values(clipsById)) if (c && c.base_file) files.add(c.base_file);
+  if (ring && ring.transitions) for (const t of ring.transitions) if (t && t.file) files.add(t.file);
+  return [...files];
+}
+
+// Order the preload so the clips most likely to be shown next come first: the
+// current scale's pool, then outward to neighboring scales, then transitions.
+function preloadOrder() {
+  if (!ring || !ring.scales) return preloadList();
+  const n = ring.scales.length, seen = new Set(), ordered = [];
+  const add = (f) => { if (f && !seen.has(f)) { seen.add(f); ordered.push(f); } };
+  for (let d = 0; d < n; d++) {
+    for (const sign of d === 0 ? [0] : [1, -1]) {
+      const s = ring.scales[((ringIndex + sign * d) % n + n) % n];
+      if (s && s.pool) for (const m of s.pool) add((clipsById[m.clip_id] || {}).base_file);
+      else if (s) add((clipsById[s.clip_id] || {}).base_file);
+    }
+  }
+  if (ring.transitions) for (const t of ring.transitions) add(t.file);
+  for (const f of preloadList()) add(f);   // sweep up anything not on the ring
+  return ordered;
+}
+
+// Fetch every clip into the blob cache in the background — non-blocking, so the
+// first scale plays immediately while the rest stream in. Bounded concurrency keeps
+// the ~350 MB fetch from stampeding. A tiny progress chip self-removes when done.
+async function preloadAllMedia(concurrency = 4) {
+  const files = preloadOrder();
+  if (!files.length) return;
+  let done = 0;
+  const total = files.length;
+  const chip = preloadChip();
+  const tick = () => { if (chip) chip.textContent = `⬇ caching clips ${done}/${total}`; };
+  tick();
+  let i = 0;
+  async function worker() {
+    while (i < files.length) {
+      const file = files[i++];
+      if (!mediaBlobs[file]) {
+        try {
+          const blob = await (await fetch(mediaUrl(file))).blob();
+          mediaBlobs[file] = URL.createObjectURL(blob);
+        } catch (_) { /* leave it to the network path on demand */ }
+      }
+      done++; tick();
+    }
+  }
+  await Promise.all(Array.from({ length: Math.min(concurrency, files.length) }, worker));
+  if (chip) chip.remove();
+}
+
+function preloadChip() {
+  let c = document.getElementById("preload-chip");
+  if (!c) {
+    c = document.createElement("div");
+    c.id = "preload-chip";
+    c.style.cssText = "position:fixed;bottom:8px;right:10px;z-index:9998;background:rgba(0,0,0,.55);" +
+      "color:#9fe;font:11px/1.4 monospace;padding:4px 8px;border-radius:4px;pointer-events:none;";
+    document.body.appendChild(c);
+  }
+  return c;
+}
 
 // Load the active scale's BASE footage into the video (the painterly canvas reads
 // its frames live). The Right knob no longer swaps the source — it only drives the
@@ -633,6 +705,7 @@ async function main() {
   try { initPaint(); } catch (e) { paintOK = false; paint.style.display = "none"; showError("WebGL init: " + e.message); }
   await loadData();
   await landScale();          // pick the initial scale's pool member before first render
+  preloadAllMedia();          // background: cache every clip in memory for instant altitude swaps
   buildDial();                // draw the altitude knob from the ring's scales
   renderScaleReadout();
   for (const id of ["content", "left", "right", "mood"]) {

tests/test_simulator_api.py

@@ -91,6 +91,32 @@ def test_index_is_served():
     assert "Alteration" in resp.text
 
 
+def test_app_assets_are_not_cached(client):
+    # Dev iteration relies on the browser never serving stale renderer code.
+    resp = client.get("/")
+    assert "no-store" in resp.headers.get("cache-control", "")
+
+
+def test_media_is_cacheable(tmp_path, monkeypatch):
+    # Media is static: it must be browser-cacheable so the preloader's fetch (and
+    # any fallback) doesn't re-hit the network on every altitude change.
+    import simulator.app as appmod
+
+    media = tmp_path / "media"
+    (media / "cosmos").mkdir(parents=True)
+    (media / "cosmos" / "base.mp4").write_bytes(b"\x00\x00\x00\x18ftyp")
+    monkeypatch.setattr(appmod, "MEDIA_DIR", media)
+    manifest = tmp_path / "manifest.json"
+    manifest.write_text(json.dumps({"clips": []}))
+
+    client = TestClient(create_app(manifest_path=manifest))
+    resp = client.get("/media/cosmos/base.mp4")
+    assert resp.status_code == 200
+    cc = resp.headers.get("cache-control", "")
+    assert "no-store" not in cc
+    assert "max-age" in cc
+
+
 @pytest.fixture
 def ring_manifest_path(tmp_path):
     p = tmp_path / "manifest.json"