docs: plan for game-view chrome polish (controls/drawers/dialogue), Space-verified

docs/superpowers/plans/2026-06-15-game-chrome-polish.md

@@ -0,0 +1,96 @@
+# Game-View Chrome Polish Implementation Plan
+
+> **For agentic workers:** REQUIRED first reads — `CLAUDE.md` (or `AGENTS.md`) and `docs/superpowers/AGENT-EXECUTION-BRIEF.md`. Branch `feat/game-chrome-polish` (already created off the deployed integration branch). Execute phase-by-phase, one commit per phase.
+>
+> **CRITICAL — verification is SPACE-ONLY.** Local rendering differs from the Space (this whole effort proved it: Gradio SSR, fonts, layout). Do NOT judge these visual changes locally and do NOT block on local appearance. The implementer applies the change + keeps tests green; **Pablo verifies on the live mirror Space after each phase's deploy** and we tune from there. Pixel values below are starting points to be tuned on the Space, not final.
+
+**Goal:** Compose the game-view chrome around the (already-good) foggy scene + child. Three approved changes (from the visual-companion mockup): (1) controls become a minimal top-right **icon cluster** with "begin again" de-emphasized; (2) drawers show a **count** and read as tappable; (3) the dialogue anchors in a **consistent lower band**, two voices balanced inside the frame, older lines faded.
+
+**Architecture:** Pure CSS in `styles.css` §26 for the controls + dialogue; `render.py` drawer-head strings for the count (+ a little CSS). No Python logic change → 276 tests stay green (no new unit tests; this is visual chrome). The scene, child, fog, letterbox, palette, and input bar stay as-is.
+
+**Workflow per phase:** implement → `import app` + `pytest -q` green → commit → `git push space HEAD:main` (mirror) → **Pablo verifies on the Space** → tune if needed (extra commit + redeploy) → next phase. Deploy to `hackathon` only after all three are confirmed on the mirror.
+
+**Key seams (read the real text first):** `styles.css` `#game-topbar` (~1463), `.restart-btn` (~858), the mute `.voice-btn`; `#game-dialogue` + `.bot`/`.user` (~218); `.game-drawer` (~1493). `render.py` drawer-head strings (~339 recovered, ~362 treasure). `app.py` restart/voice buttons (`elem_classes="restart-btn"` / `"voice-btn"`).
+
+---
+
+### Phase 1: Controls → a minimal top-right icon cluster (highest impact)
+
+Make `begin again` + mute a small, low-contrast, grouped cluster (icons, labels on hover), with `begin again` de-emphasized to a quiet `↺`. Today they're two mismatched boxes in the hottest corner, and the destructive restart is the most prominent thing on screen.
+
+**Files:** `app.py` (button labels), `styles.css` (`.restart-btn`, `.voice-btn`, `#game-topbar`).
+
+- [ ] **Step 1: Slim the restart button label.** In `app.py`, the restart button currently reads `"↺ begin again"`. Change its label to just `"↺"` and add a `title` for the native hover tooltip (find the `gr.Button(... elem_classes="restart-btn" ...)`; keep `elem_id`/`elem_classes`):
+  - label `"↺ begin again"` → `"↺"`; if Gradio `gr.Button` supports it, this is a label-only change (the JS still wires `.restart-btn`). Do NOT touch the click wiring.
+  - (The mute `.voice-btn` already shows an icon — leave its label.)
+
+- [ ] **Step 2: Restyle the cluster in `styles.css` §26.** Replace the boxy `.restart-btn` look with a small hairline icon, and group it tight with the mute button. Starting point (tune on the Space):
+  - `.restart-btn`: drop the filled background/border box → `background:transparent !important; border:none !important; max-width:none; min-width:0; width:auto !important; font-size:1rem !important; color:#8b83a2 !important; opacity:.7; padding:4px 6px;` and on `:hover` `color:#e0cdb0 !important; opacity:1;` (amber-tinted, in-world).
+  - `.voice-btn`: same minimal treatment (transparent, hairline-on-hover, `color:#b6acd0`, small).
+  - Group them: the topbar's right side already holds both; add a small gap and right-align them as one cluster (e.g. wrap target `#game-topbar` right items or set `.restart-btn, .voice-btn { margin-left:10px; }`). Keep `#game-title` on the left, but consider reducing `#game-title` `font-size` to ~`0.9rem` and `color:#7d7596` so the child stays the hero (tune on the Space).
+  - Optional hover label: a CSS `::after` on `.restart-btn` showing "begin again" on hover is nice-to-have; the `title` tooltip from Step 1 already covers it — skip the CSS label unless Pablo wants it.
+
+- [ ] **Step 3:** `import app` → ok; `pytest -q` → 276 green. Commit:
+```bash
+git add app.py styles.css
+git commit -m "style(game): minimal top-right control cluster, de-emphasized restart"
+```
+- [ ] **Step 4:** `git push space HEAD:main` → Pablo verifies the cluster on the Space; tune values if needed (extra commit + redeploy) before Phase 2.
+
+---
+
+### Phase 2: Drawer counts + tappable affordance
+
+Show how many items each drawer holds and make it read as openable.
+
+**Files:** `render.py` (drawer-head strings), `styles.css` (`.game-drawer`).
+
+- [ ] **Step 1: Add the count to the drawer headers.** In `render.py`:
+  - Treasure head (~line 362): the header uses a `title` var — append the count of shown items, e.g. `f'{title} <span class="drawer-count">· {n}</span>'` where `n` is the number of treasure entries rendered. Pass/compute the count from the items the function already has.
+  - Recovered head (~line 339): `"✦ What it remembers"` → `f'✦ What it remembers <span class="drawer-count">· {n}</span>'` with `n` = recovered/claimed count it already renders.
+  - Keep the `✦` decoration and the `_HEADER` inline style.
+
+- [ ] **Step 2: Style the count + a clearer tappable state in `styles.css`.** Starting point:
+  - `.drawer-count { color: var(--mem-accent, #e0b283); font-weight: 600; }`
+  - Strengthen the chip's "tappable" read: `.game-drawer { opacity: .82; }` and `.game-drawer:hover { opacity: 1; border-color: rgba(180,160,210,.4); }` (it already toggles `.open` on click; just make hover clearer).
+
+- [ ] **Step 3:** `import app` → ok; `pytest -q` → 276 green (if a render test asserts the exact old header string, update it to include the count — check `tests/test_render.py`). Commit:
+```bash
+git add render.py styles.css
+git commit -m "style(game): drawer counts + clearer tappable affordance"
+```
+- [ ] **Step 4:** `git push space HEAD:main` → Pablo verifies on the Space; tune; then Phase 3.
+
+---
+
+### Phase 3: Dialogue → a consistent lower band, balanced two voices, faded history
+
+Anchor the subtitle transcript in a steady lower band with a soft scrim, keep both voices INSIDE the frame (the player's line currently jams to the far-right edge), and fade older lines so only the last ~2 read strongly.
+
+**Files:** `styles.css` (`#game-dialogue`, `.bot`, `.user`, the chatbot message rows).
+
+- [ ] **Step 1: Anchor + scrim.** In §26, give `#game-dialogue` a consistent position in the lower third and a soft bottom scrim behind the text for legibility over the scene (a `::before` gradient `transparent → rgba(5,4,10,.6)`), so text never sits naked on a bright fog patch. Keep it inside the frame vars (`--fw/--band-h`).
+- [ ] **Step 2: Balance the two voices INSIDE the frame.** `.bot` (the child) stays centered/left; `.user` (you) right-aligns but clamps within the frame (`max-width`, `margin-right` off the edge — today it bleeds to the far right / cuts off). Keep the small `YOU` label (`.user`'s `::before` or existing label) and the child/you color split.
+- [ ] **Step 3: Fade older lines.** Make only the last ~2 messages fully opaque; older ones dim (e.g. target all but the last two chatbot rows with reduced opacity, or a top fade-mask on the scroll container). The transcript already auto-scrolls; this just reduces the 5-line pile-up competing with the child. (Verify against the running app — do NOT disable opacity under `prefers-reduced-motion`; per the gotcha, only sway/fog are disabled there.)
+- [ ] **Step 4:** `import app` → ok; `pytest -q` → 276 green. Commit:
+```bash
+git add styles.css
+git commit -m "style(game): anchored lower dialogue band, balanced voices, faded history"
+```
+- [ ] **Step 5:** `git push space HEAD:main` → Pablo verifies on the Space; tune until it reads right.
+
+---
+
+### Phase 4: Ship
+
+- [ ] **Step 1:** Once all three are confirmed good on the mirror, deploy the submission: `git push hackathon HEAD:main`, verify live.
+- [ ] **Step 2:** Merge `feat/game-chrome-polish` back into the integration branch.
+
+---
+
+## Self-Review
+- **Spec coverage:** controls cluster (Phase 1), drawer counts (Phase 2), dialogue band (Phase 3) — the three approved mockup changes ✅. Scene/child/fog/input untouched ✅.
+- **Space-only verification** is the spine: every phase deploys to the mirror and Pablo judges there; pixel values are starting points, tuned live. No local visual judgement.
+- **Risk / gotchas:** these touch Gradio-styled internals (the chatbot rows, the buttons), so behavior can differ on the Space — that's exactly why each phase is verified live before the next. Don't disable opacity under `prefers-reduced-motion` (Phase 3). If a `test_render.py` test pins an old drawer header string, update it (Phase 2). Edits via Edit tool only (UTF-8: `↺`, `✦`, em-dashes).
+- **No tuple/logic hazard:** counts come from data the render functions already have; the restart label change doesn't touch the `.restart-btn` JS wiring (`openingRitual` + server `_reset`).
+```