docs: game-view UI polish implementation plan (transcript/voices/color/feedback)

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

@@ -0,0 +1,408 @@
+# Game-View UI Polish Implementation Plan
+
+> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development or superpowers:executing-plans. Steps use checkbox (`- [ ]`).
+
+**Goal:** Polish the in-game UI for playability — a readable fading transcript with a clear two-voice hierarchy, an amber "memory" / red "cruelty" color language, and whispered in-voice feedback for capture/recall/recover.
+
+**Architecture:** Mostly CSS in `styles.css` §26 plus two small seams that ride the **existing per-turn marker pattern** (the `.tone-now` → `applyTone()` mechanism): `render_entity` emits a `.cue-now[data-cue][data-seq]` marker, and a new `applyCue()` in `_HEAD_JS` (polled by the existing `wire()` loop) pulses the right drawer chip, drops a transient whisper, and tags the recall line amber. No chat engine / recall / ending / voice changes.
+
+**Tech Stack:** Gradio 6 (HTML+CSS+`_HEAD_JS`), pure CSS, pytest for the one pure helper (`render_entity` marker).
+
+**Reference spec:** `docs/superpowers/specs/2026-06-15-game-ui-polish-design.md`. **Decisions:** transcript=B, voices=V1, color=B, feedback=B.
+
+**Verification:** visuals by eye (headless unreliable — CLAUDE.md); `import app` + `pytest -q` stay green (262). Gradio chatbot internal class names vary — target `.bot`/`.user` (load-bearing, already used) and verify `.message-row`/`.prose` against the running app.
+
+---
+
+### Task 1: Color var — the amber "memory" accent
+
+**Files:** Modify `styles.css` (§1 `:root`, ~line 12)
+
+- [ ] **Step 1: Add the memory accent var**
+
+In `:root` (after the existing accent vars near line 20), add:
+
+```css
+    /* memory/humanity accent (recall line, recovered items, feedback pulses) —
+       distinct from the dried-blood red reserved for cruelty/bad-ending */
+    --mem-accent: #e0b283;
+    --mem-glow:   rgba(200,130,70,0.55);
+```
+
+- [ ] **Step 2: Verify import**
+
+Run: `./.venv/Scripts/python -c "import app; print('ok')"` → `ok` (CSS isn't parsed by Python; this just confirms nothing else broke).
+
+- [ ] **Step 3: Commit**
+
+```bash
+git add styles.css
+git commit -m "style(game): add --mem-accent amber var (memory/humanity)"
+```
+
+---
+
+### Task 2: Transcript fade + two-voice hierarchy (B + V1)
+
+**Files:** Modify `styles.css` §26 (the `#game-dialogue` chat rules, ~lines 1669-1691)
+
+Make the conversation read as a fading transcript: last lines visible, older ones dimmer; the child italic & unlabeled, the player upright with a `you` typewriter tag, centered (never scattered). Recall lines turn amber.
+
+- [ ] **Step 1: Replace the `#game-dialogue` chat block**
+
+Replace the current rules from `#game-dialogue .chatbot {` through the `.user` rule (the block ending at the line that sets `.user ... color:#b9b2cc`) with:
+
+```css
+#game-dialogue .chatbot {
+    width: 100% !important;
+    max-height: 160px !important;
+    background: transparent !important;
+    border: none !important;
+    border-image: none !important;
+    box-shadow: none !important;
+    backdrop-filter: none !important;
+    padding: 0 !important;
+    overflow: hidden;            /* old lines fade out, no scrollbar */
+}
+/* transparent rows, centered text — kill Gradio's bubble chrome */
+#game-dialogue .message-row,
+#game-dialogue .message,
+#game-dialogue .bubble {
+    background: transparent !important; border: none !important;
+    box-shadow: none !important; text-align: center !important;
+    padding: 2px 0 !important; margin: 0 !important;
+}
+/* fade-by-recency: newest crisp, older dimmer, 4th-back and beyond hidden.
+   (Gradio wraps each message in a .message-row — verify this selector against
+   the running app; if rows are .message instead, swap the selector.) */
+#game-dialogue .message-row { opacity: 0.38; transition: opacity 0.4s ease; }
+#game-dialogue .message-row:nth-last-child(2) { opacity: 0.6; }
+#game-dialogue .message-row:nth-last-child(1) { opacity: 1; }
+#game-dialogue .message-row:nth-last-child(n+4) { display: none; }
+
+/* the child — italic, bright, unlabeled (it owns the scene) */
+#game-dialogue .bot, #game-dialogue .bot .prose, #game-dialogue .bot p {
+    font-style: italic !important; font-size: 1.2rem !important; line-height: 1.55 !important;
+    color: #ece6f4 !important; text-align: center !important;
+    text-shadow: 0 2px 16px #000 !important;
+}
+/* you — upright, muted, with a small typewriter tag */
+#game-dialogue .user, #game-dialogue .user .prose, #game-dialogue .user p {
+    font-style: normal !important; font-size: 1.0rem !important;
+    color: #aaa2be !important; text-align: center !important; background: transparent !important;
+}
+#game-dialogue .user .prose::before {
+    content: 'you ';
+    font-family: 'Special Elite', monospace;
+    font-size: 0.6rem; letter-spacing: 0.18em; text-transform: uppercase;
+    color: #6f6590; margin-right: 7px;
+}
+/* a recall line (it claims your memory) — JS tags the last .bot row .recall-line */
+#game-dialogue .bot.recall-line, #game-dialogue .bot.recall-line .prose,
+#game-dialogue .bot.recall-line p {
+    color: var(--mem-accent) !important;
+    text-shadow: 0 0 20px var(--mem-glow) !important;
+}
+```
+
+- [ ] **Step 2: Live-verify (user, by eye)**
+
+Run `.venv/Scripts/python app.py`, enter the game, send 2-3 messages. Confirm: the child's lines are italic/centered, your lines are upright/centered with a `you` tag (NOT scattered left/right), older lines dim and only ~3 show. If lines don't fade, the row selector is wrong — change `.message-row` to the actual per-message wrapper class (inspect element) and re-verify.
+
+- [ ] **Step 3: Commit**
+
+```bash
+git add styles.css
+git commit -m "style(game): fading transcript + two-voice hierarchy (B + V1)"
+```
+
+---
+
+### Task 3: Recovered items use the amber accent
+
+**Files:** Modify `styles.css` §26 (add a rule near the drawer/recovered styles)
+
+The "What it remembers" items are the child's recovered humanity → amber, per the color decision.
+
+- [ ] **Step 1: Add the recovered-item color rule**
+
+Append in §26 (near the `.game-drawer` rules):
+
+```css
+/* the child's recovered memories read in the warm memory accent */
+.game-drawer .recovered-item {
+    color: var(--mem-accent) !important;
+    border-left-color: rgba(200,130,70,0.5) !important;
+}
+```
+
+- [ ] **Step 2: Commit**
+
+```bash
+git add styles.css
+git commit -m "style(game): recovered items in the amber memory accent"
+```
+
+---
+
+### Task 4: `render_entity` emits a per-turn cue marker
+
+**Files:** Modify `render.py` (`render_entity` signature + return, ~lines 79-313); Test: `tests/test_render.py`
+
+Add an optional `cue` that surfaces a hidden marker (mirroring `.tone-now`) so the head-JS can fire the right feedback once per turn.
+
+- [ ] **Step 1: Write the failing test**
+
+In `tests/test_render.py`:
+
+```python
+def test_entity_cue_marker():
+    from render import render_entity
+    assert 'data-cue="recall"' in render_entity(60, cue="recall", seq=3)
+    assert 'data-seq="3"' in render_entity(60, cue="recall", seq=3)
+    # no cue → no marker
+    assert 'cue-now' not in render_entity(20)
+```
+
+- [ ] **Step 2: Run it (fails)**
+
+Run: `./.venv/Scripts/python -m pytest tests/test_render.py::test_entity_cue_marker -v` → FAIL (unexpected `cue` kwarg).
+
+- [ ] **Step 3: Add the `cue` param**
+
+Change the signature:
+
+```python
+def render_entity(affinity: int, mode: str = "idle", seq: int = 0,
+                  tone: int = 0, cue: str = "") -> str:
+```
+
+- [ ] **Step 4: Emit the marker in the return**
+
+In the final `return` (the block starting with the `tone-now` span), prepend a cue marker when `cue` is set. Replace the return with:
+
+```python
+    tone_token = tone_class.split("-", 1)[1] if "-" in tone_class else "neutral"
+    cue_mark = (f'<span class="cue-now" data-cue="{cue}" data-seq="{seq}" '
+                'style="display:none"></span>') if cue else ""
+    return (
+        cue_mark
+        + f'<span class="tone-now" data-tone="{tone_token}" style="display:none"></span>'
+        f'<div class="entity-scene {tone_class}">'
+        f'{figure}{flash}{tint}'
+        '</div>'
+        f'{ghost}'
+    )
+```
+
+- [ ] **Step 5: Run the test + full render suite**
+
+Run: `./.venv/Scripts/python -m pytest tests/test_render.py -q` → PASS.
+
+- [ ] **Step 6: Commit**
+
+```bash
+git add render.py tests/test_render.py
+git commit -m "feat(entity): optional per-turn cue marker (capture/recall/recover)"
+```
+
+---
+
+### Task 5: `chat()` computes and passes the cue
+
+**Files:** Modify `app.py` (the main turn body + yield, ~lines 923-1034)
+
+Surface which beat happened this turn so render_entity can mark it. Precedence: recall > recover > capture.
+
+- [ ] **Step 1: Capture the fragment count BEFORE it can increment**
+
+Find `do_recall, recall_memory = should_recall(state)` (~line 923). Immediately AFTER it, add:
+
+```python
+    frag_before = state.get("fragments_told", 0)
+```
+
+- [ ] **Step 2: Compute the cue just before the final yield**
+
+Find `just_claimed = recall_memory if (do_recall and recall_memory) else None` (~line 1020). Immediately AFTER it, add:
+
+```python
+    recovered_now = state.get("fragments_told", 0) > frag_before
+    cue = ("recall" if (do_recall and recall_memory)
+           else "recover" if recovered_now
+           else "capture" if captured else "")
+```
+
+- [ ] **Step 3: Pass the cue into the final `render_entity`**
+
+In the final yield, change:
+
+```python
+        render_entity(state["affinity"], mode, seq=state["turn"],
+                      tone=state.get("tone", 0)),
+```
+
+to:
+
+```python
+        render_entity(state["affinity"], mode, seq=state["turn"],
+                      tone=state.get("tone", 0), cue=cue),
+```
+
+- [ ] **Step 4: Verify import + suite**
+
+Run: `./.venv/Scripts/python -c "import app; print('ok')"` → `ok`; then `./.venv/Scripts/python -m pytest -q` → 263 passed (262 + the new render test).
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add app.py
+git commit -m "feat(game): chat() surfaces the per-turn cue (recall/recover/capture)"
+```
+
+---
+
+### Task 6: `applyCue()` — drawer pulse, whisper, recall-line tag
+
+**Files:** Modify `app.py` (`_HEAD_JS`: add `applyCue()` + call it in `wire()`, ~lines 428-442)
+
+Mirror `applyTone()`: read the marker, fire once per `data-seq`, pulse the matching chip, drop a transient whisper, and amber-tag the recall line.
+
+- [ ] **Step 1: Add `applyCue()` after `applyTone()`**
+
+Immediately after the `applyTone()` function (it ends at line ~439, the closing `}` before `function wire()`), insert:
+
+```javascript
+  // once-per-turn feedback: pulse the relevant drawer chip, drop a whisper,
+  // amber-tag the recall line. Rides the same marker pattern as applyTone.
+  var CUE_WHISPER = { capture: '\\u2014 it keeps this \\u2014',
+                      recover: '\\u2014 it remembers \\u2014' };
+  function applyCue() {
+    var gv = document.getElementById('game-view');
+    var mark = document.querySelector('#game-view .cue-now[data-cue]');
+    if (!gv || !mark) return;
+    var seq = mark.getAttribute('data-seq');
+    if (gv.dataset.cueSeq === seq) return;   // already fired this turn
+    gv.dataset.cueSeq = seq;
+    var cue = mark.getAttribute('data-cue');
+    var rightSide = (cue === 'recover');
+    var drawer = document.getElementById(rightSide ? 'drawer-right' : 'drawer-left');
+    if (drawer) {
+      drawer.classList.add('pulse');
+      setTimeout(function () { drawer.classList.remove('pulse'); }, 2500);
+    }
+    if (cue === 'recall') {
+      var bots = document.querySelectorAll('#game-dialogue .bot');
+      if (bots.length) bots[bots.length - 1].classList.add('recall-line');
+    }
+    var text = CUE_WHISPER[cue];
+    if (text && drawer) {
+      var w = document.createElement('div');
+      w.className = 'cue-whisper';
+      w.textContent = text;
+      var r = drawer.getBoundingClientRect();
+      w.style.left = r.left + 'px';
+      w.style.top = (r.bottom + 6) + 'px';
+      document.body.appendChild(w);
+      setTimeout(function () { w.classList.add('out'); }, 60);
+      setTimeout(function () { w.remove(); }, 2800);
+    }
+  }
+```
+
+- [ ] **Step 2: Call it from `wire()`**
+
+In `wire()`, the line `applyTone();` (~line 442) — add `applyCue();` right after it:
+
+```javascript
+  function wire() {
+    applyTone();
+    applyCue();
+```
+
+- [ ] **Step 3: Verify import + that the JS shipped**
+
+Run: `./.venv/Scripts/python -c "import app; print('ok')"` → `ok`. (The `\\u2014` escapes are em-dashes; keep them escaped — this file has hit UTF-8 mangling before, see CLAUDE.md.)
+
+- [ ] **Step 4: Commit**
+
+```bash
+git add app.py
+git commit -m "feat(game): applyCue — chip pulse + in-voice whisper + recall-line tag"
+```
+
+---
+
+### Task 7: CSS — chip pulse + whisper styling
+
+**Files:** Modify `styles.css` §26
+
+- [ ] **Step 1: Add the pulse + whisper rules**
+
+Append in §26:
+
+```css
+/* feedback: the drawer chip breathes amber when its collection changes */
+.game-drawer.pulse {
+    border-color: rgba(200,150,80,0.6) !important;
+    box-shadow: 0 0 18px rgba(200,150,80,0.45) !important;
+    animation: chip-pulse 1.1s ease-in-out 2;
+}
+.game-drawer.pulse .drawer-head { color: var(--mem-accent) !important; }
+@keyframes chip-pulse {
+    0%, 100% { box-shadow: 0 0 10px rgba(200,150,80,0.25); }
+    50%      { box-shadow: 0 0 22px rgba(200,150,80,0.55); }
+}
+
+/* the in-voice whisper that breathes next to the chip, then fades */
+.cue-whisper {
+    position: fixed; z-index: 60; pointer-events: none;
+    font-family: 'Special Elite', monospace;
+    font-size: 0.62rem; letter-spacing: 0.14em;
+    color: var(--mem-accent); text-shadow: 0 0 10px var(--mem-glow);
+    opacity: 0; transform: translateY(-3px);
+    transition: opacity 0.5s ease, transform 0.5s ease;
+}
+.cue-whisper.out { opacity: 0; transform: translateY(-8px); }
+.cue-whisper { animation: whisper-in 0.5s ease forwards; }
+@keyframes whisper-in { from { opacity: 0; } 40% { opacity: 0.9; } to { opacity: 0.9; } }
+```
+
+(The `.out` class drives the fade-away after ~2.5 s; `whisper-in` brings it in.)
+
+- [ ] **Step 2: Reduced-motion safety**
+
+In the existing `@media (prefers-reduced-motion: reduce)` block (near the end of §26), add:
+
+```css
+    .game-drawer.pulse { animation: none !important; }
+    .cue-whisper { animation: none !important; opacity: 0.9 !important; }
+```
+
+- [ ] **Step 3: Commit**
+
+```bash
+git add styles.css
+git commit -m "style(game): chip pulse + in-voice whisper feedback styling"
+```
+
+---
+
+### Task 8: Full suite + live verification
+
+- [ ] **Step 1:** Run `./.venv/Scripts/python -m pytest -q` → all green (263). Fix any breakage.
+- [ ] **Step 2 (user, by eye + ear, `.venv-tts` + Ollama):** play a few turns and confirm:
+  - Conversation reads as a centered fading transcript; child italic, your lines tagged `you`, never scattered; only ~3 lines show.
+  - On a captured memory: the **Treasure** chip pulses amber + "— it keeps this —" breathes and fades.
+  - On a recall: the child's line turns amber + the Treasure item shows claimed.
+  - On a recovered fragment: the **What it remembers** chip pulses + "— it remembers —".
+  - Recovered items render amber; cruelty/bad-ending still red.
+- [ ] **Step 3:** Commit any tuning.
+
+---
+
+## Self-Review
+- **Spec coverage:** transcript B (Task 2) ✅; voices V1 — `you` tag + child italic + recall amber (Tasks 2, 6) ✅; color B — amber memory var + recall + recovered + pulses, red untouched (Tasks 1, 2, 3, 7) ✅; feedback B — thinking unchanged, capture/recover whisper + chip pulse, recall glow (Tasks 4-7) ✅; bond unchanged ✅; no engine changes ✅.
+- **Placeholder scan:** every code step shows full code; no TBDs.
+- **Type/seam consistency:** `cue` kwarg added in Task 4 is passed in Task 5; the `.cue-now[data-cue][data-seq]` marker (Task 4) is read by `applyCue()` (Task 6); `--mem-accent`/`--mem-glow` (Task 1) used in Tasks 2/3/7; `.recall-line` tagged in Task 6, styled in Task 2; `.pulse` added in Task 6, styled in Task 7; `#drawer-left`/`#drawer-right` are existing ids (confirmed).
+- **Fragility flagged:** the `.message-row` fade selector and `.user .prose::before` tag are Gradio-version-dependent — Task 2 Step 2 verifies them live; `.bot`/`.user` are the load-bearing classes already in use.