From b8543906be2bad7b184495f7f185ddcb27672407 Mon Sep 17 00:00:00 2001 From: Ben Stull Date: Sun, 7 Jun 2026 22:58:46 -0700 Subject: [PATCH] docs: point parent design at reconciliation; roadmap + user guide for sim alteration Co-Authored-By: Claude Opus 4.8 (1M context) --- docs/ROADMAP.md | 23 +++++++++- docs/USER_GUIDE.md | 43 ++++++++++++++----- ...06-05-machine-altered-perception-design.md | 14 ++++++ 3 files changed, 69 insertions(+), 11 deletions(-) diff --git a/docs/ROADMAP.md b/docs/ROADMAP.md index 50efbc7..5667f11 100644 --- a/docs/ROADMAP.md +++ b/docs/ROADMAP.md @@ -123,6 +123,22 @@ longer *select* a pre-tagged clip; they drive an **alteration engine** (design Plan: [`2026-06-05-player-alteration-core.md`](./superpowers/plans/2026-06-05-player-alteration-core.md). +**Slice 2 — simulator-first alteration preview ✅ Done.** Merged to `main` +(session 0009). Wires the alteration engine into the web simulator so the look is +tunable by eye before any hardware, and **reconciles** the unmerged session-0007 +design with the merged session-0008 design (the Left-HUD conflict): Left is a +**runtime overlay** (authored annotation track + per-language string tables), +Right is a **discrete pre-baked** flow-stabilized variant, Dark/Light a **live** +grade — superseding 0007's baked-HUD 5×5 grid. Engine: a parameterized +`Calibration` (tuned by eye, baked into `DEFAULT_CALIBRATION`), `Restyle.variant` +(discrete) replacing the continuous blend, and `AnalyticalOverlay.level`. Sim: +`/api/alteration` + `/api/clips` over `simulator/clips.py`, an alteration-preview +UI, and one neutral clip with a real flow-stabilized Right variant from the POC. +Design: +[`2026-06-07-reconciled-simulator-alteration-slice-design.md`](./superpowers/specs/2026-06-07-reconciled-simulator-alteration-slice-design.md); +plan: +[`2026-06-07-reconciled-simulator-alteration-slice.md`](./superpowers/plans/2026-06-07-reconciled-simulator-alteration-slice.md). + **Remaining slices (not started):** - **Runtime renderer** — drive the single panoramic projector via mpv/ffmpeg; @@ -134,7 +150,12 @@ Plan: [`2026-06-05-player-alteration-core.md`](./superpowers/plans/2026-06-05-pl `Controls` stream). - **White-noise generation** — runtime white/pink noise for that content position. - **Offline v2v variant pipeline** — author the pre-baked Right restyle variants - (the only paid AI step, design §9) + the multilingual label/string tables + TTS. + via the local flow-stabilized SD pipeline (now ~free, not a paid API — see the + scales-library/right-axis design §1/§4); a real multi-strength flow-stabilized + re-bake per base clip + the multilingual label/string tables + TTS. +- **Scale-ring navigation** — the endless rotary encoder + short pre-baked AI + zoom/warp transitions between neutral "scales of nature" clips on a closed ring + (scales-library design §3); a new control + offline pipeline element. - **Catalog model changes** — audio *source* + "neutral base" vs "altered variant" flag (sub-project 2 territory, design §13). diff --git a/docs/USER_GUIDE.md b/docs/USER_GUIDE.md index 232e515..ad95237 100644 --- a/docs/USER_GUIDE.md +++ b/docs/USER_GUIDE.md @@ -287,11 +287,23 @@ Records point at files via `file_path`. Those files live on the player's drive, `file_path` values consistent with wherever you mount that drive on the machine that will eventually run the room. -## Playing with the simulator (curator's X-ray) +## Playing with the simulator (alteration preview) The simulator is a web stand-in for the installation's control panel. It runs the -real `hef.selection` code against a synthetic catalog so you can feel whether the -dials surface fitting pieces before any hardware exists. +real `player.alteration` engine and **alters** a neutral base clip toward the knob +state in the browser, so you can tune the *look* of the filter before any hardware +exists. (The earlier selection-era "curator's X-ray" view was retired when the +piece moved from *selecting* clips to *altering* them.) + +**One-time setup — populate the sample footage** (look-tuning only; not shipped +content): + + python simulator/setup_sample_media.py + +This copies the session-0008 POC artifacts (`~/hef-poc/out/`) into +`simulator/sample_media/forest/` — the neutral base clip and the real +flow-stabilized Right restyle — and generates placeholder intermediate Right +strengths. The `.mp4` binaries are gitignored. **Run it (Docker):** @@ -304,11 +316,22 @@ then open http://localhost:8000. pip install -e ".[sim]" make sim-local -**What you see:** the five real dials (mode + Left/Right/Dark/Light), the model -knobs (brain/mood weights, pool size, approved-only), and the X-ray — the picked -piece, the ranked candidate pool with distances, and brain/mood coordinate maps -showing where your knob point and the candidates sit. +**What you see and can do:** -By default it loads a generated fixture catalog. To point it at a real catalog, -set `HEF_SIM_CATALOG=catalog/library.jsonl` (used automatically when that file is -non-empty). +- **Content dial** — picks audio/video channel; "off" and audio-only positions go + to black walls. +- **Four experience knobs (0–4):** + - **Dark / Light** — a live runtime color grade (cool/dark ↔ warm/bright; equal + or zero = the raw footage). + - **Right (dreamlike)** — selects a discrete pre-baked, flow-stabilized restyle + variant and crossfades to it (strength 0 = raw base). + - **Left (analytical)** — a live overlay: labelled boxes from the clip's authored + annotation track, with more annotations appearing at higher levels. Text is + shaped live (the simulator analogue of the Pi's Pango/HarfBuzz path). +- **Calibration sliders** — adjust the grade/overlay gain curves live; once a look + is liked, bake the values into `DEFAULT_CALIBRATION` in `player/alteration.py`. +- **RenderPlan readout** — always shows the exact numbers the engine produced (the + project's honesty "X-ray," now over the alteration model). + +The base clips, Right variants, Left annotation track, and string tables come from +`simulator/sample_media/manifest.json`. diff --git a/docs/superpowers/specs/2026-06-05-machine-altered-perception-design.md b/docs/superpowers/specs/2026-06-05-machine-altered-perception-design.md index c855cdc..7298a4b 100644 --- a/docs/superpowers/specs/2026-06-05-machine-altered-perception-design.md +++ b/docs/superpowers/specs/2026-06-05-machine-altered-perception-design.md @@ -121,6 +121,13 @@ layers. This single rule covers the whole `5×5×5×5` space: ### 4.3 Where each transform runs +> **Reconciled (2026-06-07, session 0009):** the Left HUD is a **runtime overlay** +> driven by an authored annotation track + per-language string tables (text shaped +> live); the Right axis selects a **discrete pre-baked** flow-stabilized variant +> (not a continuous blend). See +> [`2026-06-07-reconciled-simulator-alteration-slice-design.md`](./2026-06-07-reconciled-simulator-alteration-slice-design.md) +> §1, which supersedes the session-0007 baked-HUD / 5×5-grid proposal. + - **Runtime, on the Pi (free, continuous, full-res):** the Dark/Light color grade and the Left analytical overlay. These are cheap (LUT/curves + luma key, and text/graphics compositing) and can move continuously with the knob. @@ -235,6 +242,13 @@ one-time build. ## 10. Accessibility, i18n, and the translation-cost finding +> **Reconciled (2026-06-07, session 0009):** the near-free-i18n path is kept — the +> Left HUD is a runtime overlay (authored annotation track + per-language string +> tables, shaped live via Pango/HarfBuzz on the Pi). The session-0007 baked-HUD +> reversal is **not** adopted. See +> [`2026-06-07-reconciled-simulator-alteration-slice-design.md`](./2026-06-07-reconciled-simulator-alteration-slice-design.md) +> §1. + The piece is operable **blind, in the dark, in your language**, via four redundant channels on the control panel: **touch** (engraved symbol shape), **low-light color** (LEDs), **braille**, and **audio** (a read-aloud button on a small *local*