add sessions/0021/SESSION-0021.0-TRANSCRIPT-2026-06-26T08-12--2026-06-26T08-20.md + replace placeholder/variant SESSION-0021.0-TRANSCRIPT-2026-06-26T08-12--INPROGRESS.md

Operator-driven revision of the audio feature: Dev-Mode-style Video/Audio toggles,
white-noise deferred (Audio = off/soundtrack), and fixes for two real-browser bugs
(video-off not blanking GPU-composited layers; no soundtrack on Safari/iOS).
Verified in headless Chromium + WebKit. 288 tests + 3 Playwright E2E pass.

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

sessions/0020/SESSION-0020.0-TRANSCRIPT-2026-06-26T06-47--2026-06-26T07-58.md

@@ -0,0 +1,109 @@
+# Session 0020.0 — Transcript
+
+> App: human-experience-filter-art
+> Start: 2026-06-26T06-47 (PST)
+> End: 2026-06-26T07-58 (PST)
+> Type: writing-plans (extended into execution — operator approved "then build it" at the plan gate)
+> Posture: careful (execution proceeded under explicit operator approval)
+> Claude-Session: e0cc053a-41fa-416d-a4f5-493f14984e75
+> Anchor: design docs/superpowers/specs/2026-06-26-audio-video-separated-controls-design.md (R2a)
+> Status: FINALIZED
+
+## Launch prompt
+
+> Write the implementation plan for the "Audio + Video — separated Visual & Audio
+> controls" feature, then build it. (Spec:
+> docs/superpowers/specs/2026-06-26-audio-video-separated-controls-design.md.)
+> Split the bundled 7-way Content selector into orthogonal Visual (on/off) ×
+> Audio (off / soundtrack / white noise). Audio follows the single Altitude dial;
+> white noise synthesized (ffmpeg anoisesrc). Reframe the (unbuilt) networked-
+> control-surface spec §3/§5 as a clean pre-implementation edit. Honor the testing
+> tiers; resolve the three §12 flagged decisions.
+
+## Pre-state
+
+- `main` clean at 99a751c. Two stale `--INPROGRESS` placeholders (0015, 0017) from
+  2026-06-24/25 — prior dead sessions, not live; left untouched.
+- The networked-control-surface architecture (SSE / `/remote` / renderer split) was
+  **unbuilt** — the sim is a single fused page (`simulator/static/index.html`) talking
+  to FastAPI via `POST /api/alteration` (knobs) + `POST /api/ring/advance` (altitude).
+- Audio assets (5 sourced ambiences) sat gitignored under `simulator/sample_media/audio/<scale>/`,
+  unreferenced by the manifest, unserved; no `<audio>` element anywhere; video muted.
+
+## Session arc (turn by turn)
+
+1. **Session gate → writing-plans.** Classified the two-part "write the plan, then
+   build it" prompt as the build track's entry; claimed session **0020** (`--type
+   writing-plans`, careful posture). Baseline clean; created branch `session-0020`.
+2. **Scoping.** Read both specs + the audio candidate pool; dispatched an Explore
+   agent to map the current simulator. Key finding: the control-surface architecture
+   is unbuilt, so the audio spec's §6 server contract had no host. **Resolved by the
+   standing simulator-first directive:** build the audio feature into the current
+   single-page sim (ships sound now); reframe the control-surface spec on paper only;
+   do NOT build the SSE/`/remote`/renderer split (it's "v1 hardware," deferred). This
+   build is the "Content step" the audio spec §11 anticipates.
+3. **Plan.** Wrote `docs/superpowers/plans/2026-06-26-audio-video-separated-controls.md`
+   (10 tasks, all testing tiers). Committed + pushed; presented at the careful-posture
+   plan gate. Operator answered **"Approve — build it."** §12 decisions resolved:
+   audio=live (~0.6 s crossfade), noise=pink, autoplay=tap-to-start overlay; asset
+   params −18 LUFS / mp3 / loop mirrors the proven video crossfade recipe.
+4. **Build (TDD, commit per task):**
+   - T1–2: pure ffmpeg audio builders (`tools/pipeline/audio_ops.py`) + runner
+     (`audio_run.py`) + `simulator/build_audio_media.py`; produced the 5 normalized
+     loops + pink-noise bed (gitignored).
+   - T3: `Scale.audio` manifest field + read/emit/serialize + `SCALE_AUDIO`; manifest
+     regenerated (clean diff — only 5 audio lines).
+   - T4–6: pure `player/audio.py` resolver; retired `player/content.py` (+ test);
+     reframed `player/controls.py` + `player/state.py`; `/api/alteration` validates
+     visual+audio and returns `render.video` + server-resolved `render.audio.url` from
+     `altitude_index`. Full Python suite green.
+   - T7–8: client — Content `<select>` → Visual toggle + Audio selector; A/B `<audio>`
+     gain-crossfade layer; tap-to-start gesture. Smoke-tested page + media (200s).
+   - T9: reframed the networked-control-surface spec §3/§4/§5/§6; recorded §12
+     resolutions; ROADMAP note.
+   - T10: Playwright E2E (`[e2e]` extra). Installed Chromium and ran it for real —
+     surfaced + fixed three client issues (see Cut state). **3 E2E pass**, full suite
+     **288 passed, 2 skipped**.
+5. **Verify + ship.** Screenshotted the running app (cosmos plays, soundtrack audibly
+   playing `cosmos/pillars.loop.mp3`, split controls visible, zero JS errors). Merged
+   `session-0020` → `main` (`--no-ff`) and pushed. (`gh` PR create denied — Gitea host;
+   merged locally with branch→merge discipline.)
+
+## Deferred decisions
+
+_No low-confidence autonomous calls. The scope decision (current-sim vs full control
+surface) was approved at the plan gate; the three §12 resolutions were operator-
+delegated by the launch prompt ("resolve the three flagged decisions"); asset params
+(−18 LUFS, mp3, pink) follow the spec's stated direction._
+
+## Cut state
+
+- `main` @ `aa76cd1` (merge of session-0020), clean, synced with origin.
+- **288 tests + 3 Playwright E2E pass; 2 skipped** (opt-in media integration).
+- Three client robustness fixes the E2E drove out (worth remembering):
+  - `fadeVolume` uses `setInterval`, not `requestAnimationFrame` (rAF stalls when the
+    tab is backgrounded → the gain ramp hung in headless).
+  - The start gesture drops per-element "priming": a single page click grants Chrome
+    autoplay document-wide; priming srcless `<audio>` only hung the handler / polluted
+    the paused-state.
+  - `applyAudio` does not `await` `play()` (awaiting a srcless/buffering play can hang).
+- Plan archival: this app has **no content repo** (`CONTENT_REMOTE` empty), so the plan
+  was not archived to a `plans/` collection — it lives in-repo at
+  `docs/superpowers/plans/` and is already on `main`.
+- §9 pipeline: localhost + E2E stage is **green**; there is no PPE/prod infra for this
+  simulator-first art app (deferred with the Pi renderer), so no further ship stage ran.
+
+## Operator plate (what's true now / next)
+
+- The simulator has **sound**: per-altitude soundtracks that follow the Altitude dial +
+  a pink white-noise bed, behind orthogonal **Visual** × **Audio** controls. The unheard
+  audio wants a by-ear review/tune.
+- Deferred (already roadmap-tracked, not re-parked in memory): the **music** layer
+  (reserved Audio position, no assets), the networked-control-surface SSE/`/remote`
+  build, i2v ring transitions, the Pi renderer.
+
+## Next /goal
+
+```
+/goal review/tune the new audio by ear in the sim (per-altitude soundtracks + pink white-noise + the ~0.6s A/B crossfade; tap-to-start), then source/compose the deferred per-altitude music layer (the reserved Audio position), per docs/audio-candidate-pool.md
+```

sessions/0020/SESSION-0020.0-TRANSCRIPT-2026-06-26T06-47--INPROGRESS.md

@@ -1,22 +0,0 @@
-# Session 0020.0 — Transcript
-
-> App: human-experience-filter-art
-> Start: 2026-06-26T06-47 (PST)
-> Type: writing-plans
-> Posture: careful
-> Claude-Session: e0cc053a-41fa-416d-a4f5-493f14984e75
-> Status: **PLACEHOLDER — claimed at session start; finalized at session end.**
->
-> This file reserves session ID 0020 for human-experience-filter-art. The driver replaces this
-> body with the full transcript and renames the file to its final
-> SESSION-0020.0-TRANSCRIPT-2026-06-26T06-47--<end>.md form at session end.
-
-## Launch prompt
-
-_(launch prompt not captured at claim time)_
-
-## Deferred decisions
-
-_Autonomous-mode low-confidence calls the driver made and would have
-liked operator input on. Appended as the session runs; surfaced at
-finalize. Empty if none._

sessions/0021/SESSION-0021.0-TRANSCRIPT-2026-06-26T08-12--2026-06-26T08-20.md

@@ -0,0 +1,88 @@
+# Session 0021.0 — Transcript
+
+> App: human-experience-filter-art
+> Start: 2026-06-26T08-12 (PST)
+> End: 2026-06-26T08-20 (PST)
+> Type: executing-plans (operator-driven hotfix/revision of session 0020's audio feature)
+> Posture: yolo
+> Claude-Session: e0cc053a-41fa-416d-a4f5-493f14984e75
+> Status: FINALIZED
+
+## Launch prompt
+
+> Show video unchecked doesn't turn off the video. Make "show video" just "Video"
+> and have a toggle like "Dev Mode" has. I can't hear any audio when "soundtrack
+> (follows altitude)" is selected. Let's just have Audio as off/on like Video for
+> now and get rid of white noise.
+
+## Pre-state
+
+- Session 0020 had just merged the audio feature to `main` (Visual×Audio split,
+  per-altitude soundtracks, pink white-noise, A/B crossfade). The operator tested it
+  live and reported three issues.
+
+## Session arc
+
+1. **Diagnosis (the key work).** Both reported bugs were reproduced *only* in the
+   operator's real browser — neither appeared in headless Chromium **or** WebKit
+   (installed `playwright install webkit` to test Safari's engine). Root causes:
+   - **Video-off doesn't blank:** `#vid` (`<video>`) and `#paint` (WebGL `<canvas>`)
+     are GPU-composited layers; the `#black` cover had *auto* z-index, so on a real
+     GPU (Safari/Chrome) the video layer can composite *above* it despite DOM order.
+     Headless software-raster hides this.
+   - **No soundtrack audio:** real Safari/iOS unlocks an `<audio>` element only when
+     `play()` is called *synchronously inside* the user gesture; the 0020 gesture
+     played in an async continuation (after `await fetch`), which Chrome allows but
+     Safari blocks. Headless WebKit relaxes autoplay, so it passed.
+   This is the session's main lesson: **Playwright headless relaxes both GPU
+   compositing and autoplay**, so the 0020 E2E couldn't have caught either — real
+   device / by-eye review is required.
+2. **Fixes (branch `session-0021`):**
+   - **Video** + **Audio** are now Dev-Mode-style on/off toggles (`.dev-switch`),
+     wired on `change`. Audio on → soundtrack; **white-noise deferred** (removed from
+     the live control; `AUDIO_SOURCES={off,soundtrack}`; the pure pink-noise
+     machinery + tests stay for later).
+   - Video-off: `.black` gets `z-index:50` + `translateZ(0)` (own layer) **and** the
+     video layers are set `opacity:0` on video-off (belt-and-suspenders blanking).
+   - Safari audio: the tap-to-start gesture now primes both A/B `<audio>` elements
+     **synchronously in-gesture** (set src, vol 0, `play().then(pause)`), unlocking
+     the later async crossfades.
+   - Server: `player/audio.py` resolver + `controls.py`/`state.py` + `/api/alteration`
+     drop white-noise; `build_audio_media.py` stops emitting the noise bed.
+3. **Verify + ship.** Updated unit/contract/E2E tests; rewrote the 3 E2E for the new
+   toggles (click the visible `.dev-switch-track`; wait for the opacity transition).
+   **288 passed, 2 skipped.** Re-verified in **both Chromium and WebKit**: Audio toggle
+   plays `cosmos/pillars.loop.mp3`, video-off sets vid+paint opacity 0 with `#black`
+   shown, zero JS errors; screenshotted the new toggle UI. Merged `session-0021` →
+   `main` and pushed. (Also untracked a stray `docs/.threads/*.json` editor artifact
+   swept in by `git add -A`, and gitignored `.threads/`.)
+
+## Deferred decisions
+
+_No low-confidence calls. All three changes were explicit operator requests; the
+root-cause fixes (GPU z-index/layer-hide; Safari in-gesture unlock) are the standard
+remedies for these well-known browser behaviors._
+
+## Cut state
+
+- `main` @ `fddb6d6` (merge of session-0021), clean, pushed.
+- **288 tests + 3 Playwright E2E pass** (2 skipped: opt-in media integration).
+- White-noise is deferred, not deleted: `tools/pipeline/audio_ops.white_noise_args` +
+  `audio_run.generate_white_noise` + their tests remain; only the live control + the
+  build-script emission were removed.
+- **Unvalidated by this session:** real-device audio (Safari autoplay) and real-GPU
+  video-off — headless can't exercise either; needs the operator's by-ear/by-eye pass.
+
+## Operator plate
+
+- Video + Audio are simple on/off toggles (Dev-Mode style). Audio on = the current
+  altitude's soundtrack. The two real-browser bugs should now be fixed — but please
+  confirm on a real device (especially iPad/Safari).
+- Deferred: white-noise (easy to re-add as a 3rd Audio position), the per-altitude
+  music layer, the networked-control-surface build, Pi renderer.
+
+## Next /goal
+
+```
+/goal by-ear/by-eye review the audio + Video/Audio toggles on a REAL device (esp. iPad/Safari — headless can't validate Safari autoplay or GPU compositing), then source/compose the deferred per-altitude music layer per docs/audio-candidate-pool.md (or re-enable white-noise as a 3rd Audio position if wanted)
+```

sessions/sessions.json

@@ -58,5 +58,8 @@
   },
   "0020": {
     "title": ""
+  },
+  "0021": {
+    "title": ""
   }
 }