Spaces:

Pabloler21
/

hollow

Sleeping

App Files Files Community

Pabloler21 Claude Fable 5 commited on Jun 14

Commit

9ce912d

1 Parent(s): 9557331

docs: front-door menu spec + plan (Direction C, modes, how-to-play, menu music)

Browse files

Plan runs on its own branch feat/front-door-menu for isolation.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

Files changed (2) hide show

docs/superpowers/plans/2026-06-14-front-door-menu.md +396 -0
docs/superpowers/specs/2026-06-14-front-door-menu-design.md +52 -0

docs/superpowers/plans/2026-06-14-front-door-menu.md ADDED Viewed

	@@ -0,0 +1,396 @@

+# Front Door — Menu + Modes + How-to-Play + Menu Music — Implementation Plan
+> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development to implement this plan phase-by-phase. Steps use checkbox (`- [ ]`). **Do Phase 0 FIRST: create a dedicated branch `feat/front-door-menu` off `feat/voice-awareness` and do all work there** — if this overhaul goes wrong, `feat/voice-awareness` stays intact. Run the suite with `.venv/Scripts/python -m pytest -q`. Visuals are verified by screenshotting the RUNNING app (headless Chrome per CLAUDE.md), never the static harness. Audio is verified by ear (ask the user). Design doc: `docs/superpowers/specs/2026-06-14-front-door-menu-design.md`.
+>
+> **SUPERSEDES** `docs/superpowers/plans/2026-06-14-opening-chime-ritual.md` — do NOT execute that plan. With a menu, the chime→greeting ritual fires on **mode-select**, not on the first page gesture (the first gesture now lands on the menu). Phase 5 here owns the full audio flow.
+**Goal:** A Fear & Hunger / Termina-**inspired** opening menu (approved Direction C) over the visitor's AI-painted foggy-wood backdrop, with two real modes — **Tester Run** (fast, judge-friendly arc) and **The Full Stay** (a genuinely longer experience) — a **How to Play** panel, a subtle eerie **menu melody** that starts on the first menu gesture, and the **chime → greeting** ritual as the "you're entering the wood" cue on mode-select. Makes the demo one click and lifts the whole thing from "Gradio app" to "a game".
+**Architecture:** Two top-level Gradio views — `menu_view` (visible at start) and `game_view` (the existing game, `visible=False`). Mode-select flips visibility and initializes the game state with the chosen `mode`. `mode ∈ {"tester","full"}` drives a `PACING` config in `memory.py` that `should_recall`/`decide_ending` read (only the numbers change). The `<head>` controller starts the menu loop on first menu gesture and, on a mode button click, stops it and runs the chime→greeting ritual.
+**Tech Stack:** Gradio 6.x (`gr.Column(visible=...)` view switch, buttons), CSS (menu styling + background `data:` URI), numpy audio (`sting.py` menu loop), the existing `<head>` audio-queue controller, pytest. No new deps.
+**Critical caveat (CLAUDE.md):** `visible=False` can UNMOUNT a component. Only the menu (no persistent audio) and the game view toggle visibility; the game's `voice_panel`/`#idle-trigger` mount when `game_view` is shown — which is exactly when game audio is first needed. Safe. Do NOT put anything that must run while hidden behind `visible=False`.
+---
+## PHASE 0 — Isolation branch (do this before anything else)
+**Why:** this overhaul restructures the whole layout, the audio flow, and the pacing engine. Keep it off the verified `feat/voice-awareness` branch so a bad run loses nothing.
+- [ ] **0a.** Confirm a clean tree on `feat/voice-awareness`: `git status` (the spec + plan are already committed there).
+- [ ] **0b.** Create and switch to the work branch:
+  ```bash
+  git switch -c feat/front-door-menu
+  ```
+  (If the orchestrator prefers an isolated worktree, use superpowers:using-git-worktrees instead — same effect.)
+- [ ] **0c.** Every phase below commits on `feat/front-door-menu`. The merge back happens in FINAL, only after the user approves the live playthrough.
+---
+## PHASE 1 — Two views + screen switch (no styling, no audio, no mode differences yet)
+**Files:** `app.py`, `tests/test_app.py`.
+### Step 1 — Wrap the game in `game_view`, add `menu_view`
+- [ ] **1a.** In `app.py`, inside `with gr.Blocks(...) as demo:` and after `state = gr.State(_init_state)`, the current UI is a header `gr.Row` (title/restart/voice) + a body `gr.Row` (3 columns) + the event wiring. Wrap ALL of that existing UI in a hidden column:
+  ```python
+      with gr.Column(visible=False, elem_id="game-view") as game_view:
+          # ... ALL the existing header row + body row + event wiring stays here,
+          # unchanged, just indented one level deeper ...
+  ```
+  (Indent the existing `with gr.Row():` blocks and the `.click`/`.submit`/`idle_trigger` wiring into this column. The `demo.launch(...)` call at the bottom stays at module level, unchanged.)
+- [ ] **1b.** ADD a menu column BEFORE `game_view` (so it renders first):
+  ```python
+      with gr.Column(visible=True, elem_id="menu-view") as menu_view:
+          menu_art = gr.HTML(_menu_html())          # Phase 2 fills this in; "" for now
+          tester_btn = gr.Button("Tester Run", elem_id="btn-tester",
+                                 elem_classes="menu-btn menu-mode-btn")
+          full_btn = gr.Button("The Full Stay", elem_id="btn-full",
+                                elem_classes="menu-btn menu-mode-btn")
+          howto_btn = gr.Button("How to Play", elem_id="btn-howto",
+                                elem_classes="menu-btn")
+  ```
+  For Phase 1 add a placeholder `_menu_html` near the other render helpers:
+  ```python
+  def _menu_html() -> str:
+      return '<div class="menu-art-placeholder">HOLLOW — menu</div>'
+  ```
+### Step 2 — Enter-game handler
+- [ ] **2a.** Add `_enter_game(mode)` near `_pristine_state` / `_init_state`:
+  ```python
+  def _enter_game(mode: str):
+      """Leave the menu, reveal the game, start a fresh run in the chosen mode.
+      Order matches the outputs list below."""
+      state = _init_state()                 # honors HOLLOW_FAST_FINALE for dev
+      state["mode"] = mode                  # "tester" | "full"
+      return (
+          gr.update(visible=False),         # menu_view
+          gr.update(visible=True),          # game_view
+          state,
+          [{"role": "assistant", "content": OPENING_LINE}],   # chatbot
+          _render_bond(state["affinity"], get_tier(state["affinity"])),
+          render_treasure(state["treasure"], claimed=set(state["claimed"]),
+                          wounds=state.get("wounds", [])),
+          render_entity(state["affinity"]),
+      )
+  ```
+  Add `"mode": "tester",` to the three state factories (`_pristine_state`, both `_init_state` branches) so reads are safe.
+- [ ] **2b.** Wire both mode buttons (How to Play wired in Phase 4):
+  ```python
+      _enter_outputs = [menu_view, game_view, state, chatbot, bond_panel,
+                        treasure_panel, entity_panel]
+      tester_btn.click(lambda: _enter_game("tester"), None, _enter_outputs,
+                       show_progress="hidden")
+      full_btn.click(lambda: _enter_game("full"), None, _enter_outputs,
+                     show_progress="hidden")
+  ```
+  (These outputs reference `chatbot`, `bond_panel`, etc., which are defined inside `game_view`. Define `_enter_outputs` and the `.click` wiring AFTER those components exist — i.e., at the end of the Blocks body, alongside the other event wiring.)
+### Step 3 — Tests + verify
+- [ ] **3a.** In `tests/test_app.py` add:
+  ```python
+  class TestEnterGame:
+      def test_enter_sets_mode_and_reveals_game(self):
+          outs = app._enter_game("full")
+          assert outs[0]["visible"] is False        # menu hidden
+          assert outs[1]["visible"] is True          # game shown
+          assert outs[2]["mode"] == "full"           # mode stored on state
+          assert outs[3][0]["content"] == app.OPENING_LINE
+  ```
+- [ ] **3b. Run** `.venv/Scripts/python -m pytest -q` → green.
+- [ ] **3c. Live screenshot:** launch, confirm the menu (placeholder) shows first and the game is hidden; click Tester → menu hides, game appears with the opening line. Kill the port owner.
+- [ ] **3d. Commit:** `feat: front-door — menu view + game view with screen switch`.
+---
+## PHASE 2 — The background asset + Direction C styling
+**Files:** `assets/background.webp` (new), `app.py` (`_menu_html`, `_BACKGROUND_URI`), `styles.css`, `tests/test_app.py`.
+### Step 1 — Process the visitor's image into a committed asset
+- [ ] **1a.** Convert `assets/backroud.png` → `assets/background.webp` (grayscale + darkened to match the portraits, resized for a wide menu). Run once:
+  ```python
+  from PIL import Image, ImageEnhance
+  img = Image.open("assets/backroud.png").convert("L")
+  img = ImageEnhance.Brightness(img).enhance(0.82)
+  img = ImageEnhance.Contrast(img).enhance(1.06)
+  img = img.convert("RGB").resize((1280, 960), Image.LANCZOS)   # keep ~its aspect
+  img.save("assets/background.webp", "WEBP", quality=82, method=6)
+  ```
+  Commit `assets/background.webp`. (HF accepts images; only committed audio binaries are rejected.) Leave `backroud.png` or delete it — your call; the app uses the `.webp`.
+- [ ] **1b.** In `app.py`, near the top (after imports), load it as a base64 data URI the way portraits are embedded:
+  ```python
+  with open("assets/background.webp", "rb") as _bg:
+      _BACKGROUND_URI = "data:image/webp;base64," + base64.b64encode(_bg.read()).decode()
+  ```
+### Step 2 — `_menu_html` (the C composition, visual only)
+- [ ] **2a.** Replace the placeholder `_menu_html` with the real composition. The interactive buttons are separate Gradio components (Phase 1); this HTML draws the backdrop + title block + decorative text. The background lives on `#menu-view` via CSS (Step 3) so it covers the whole column; this HTML provides the centered title/eyebrow/tag + the credit + the "How to Play" corner is the Gradio `#btn-howto` styled in CSS.
+  ```python
+  def _menu_html() -> str:
+      return (
+          '<div class="menu-eyebrow">AN ADVENTURE IN THOUSAND TOKEN WOOD</div>'
+          '<div class="menu-title">Hollow</div>'
+          '<div class="menu-tag">something is here, at the edge of the wood '
+          '&mdash; it remembers what you give it.</div>'
+          '<div class="menu-credit">A LOST CHILD WAITS &middot; TURN YOUR SOUND ON</div>'
+      )
+  ```
+### Step 3 — Menu CSS (§23) — Direction C
+- [ ] **3a.** In `styles.css`, add a `§23 — opening menu` block. Use `_BACKGROUND_URI` by writing the CSS so the background is set inline on the column from Python is NOT possible (CSS file is static); instead set the background via a CSS custom property injected in `_HEAD_JS` OR set it inline on the `menu_art` HTML wrapper. Simplest: put the background on a full-bleed div INSIDE `_menu_html` with an inline `style="background-image:url(...)"` using the URI. Revise `_menu_html` to wrap its content:
+  ```python
+  def _menu_html() -> str:
+      return (
+          f'<div class="menu-bg" style="background-image:url(\'{_BACKGROUND_URI}\')"></div>'
+          '<div class="menu-scrim"></div>'
+          '<div class="menu-grain"></div>'
+          '<div class="menu-vig"></div>'
+          '<div class="menu-content">'
+          '  <div class="menu-eyebrow">AN ADVENTURE IN THOUSAND TOKEN WOOD</div>'
+          '  <div class="menu-title">Hollow</div>'
+          '  <div class="menu-tag">something is here, at the edge of the wood '
+          '&mdash; it remembers what you give it.</div>'
+          '</div>'
+          '<div class="menu-credit">A LOST CHILD WAITS &middot; TURN YOUR SOUND ON</div>'
+      )
+  ```
+  Then in `styles.css §23` style: `#menu-view{position:relative;min-height:560px;...}`, `.menu-bg{position:absolute;inset:0;background-size:cover;background-position:center 38%;}`, `.menu-scrim{...radial dark...}`, `.menu-grain`/`.menu-vig` (reuse the entity grain/vig feTurbulence + inset shadow), `.menu-content{position:relative;z-index:3;text-align:center;padding-top:64px;font-family:Georgia,serif;}`, `.menu-title{font-variant:small-caps;letter-spacing:.16em;font-weight:700;font-size:72px;color:#ece6f4;text-shadow:0 0 30px #000,0 4px 12px #000;}`, `.menu-eyebrow`/`.menu-tag`/`.menu-credit` per the mockup. Style the buttons: `.menu-btn{position:relative;z-index:4;background:transparent!important;border:0!important;box-shadow:none!important;font-family:Georgia,serif;letter-spacing:.16em;color:#c4bede;...}` with a hover that brightens + widens letter-spacing and a `▸` marker; center them under the title. Position `#btn-howto` absolutely top-right as the corner item.
+  - The reference look is the approved mockup `\.superpowers/brainstorm/3158-1781454014/content/c-final-bg.html` — match its scrim/title/spacing.
+- [ ] **3b. Live screenshot REQUIRED (CSS lies in the harness).** Launch, screenshot the menu, Read the PNG. Confirm: background visible + dark enough, title legible over it, the three buttons read as menu items (Tester/Full centered, How to Play in the corner), grain/vignette present. Iterate on the CSS until it matches the mockup. Kill the port owner.
+- [ ] **3c.** Test: `assert "menu-title" in app._menu_html()` and `assert app._BACKGROUND_URI.startswith("data:image/webp")`. Run suite → green.
+- [ ] **3d. Commit:** `feat: Fear & Hunger-inspired opening menu (Direction C) with painted backdrop`.
+---
+## PHASE 3 — Mode mechanics (Tester vs Full pacing)
+**Files:** `memory.py`, `tests/test_memory.py`, `tools/pacing_sim.py`.
+### Step 1 — `PACING` config + mode-aware gates
+- [ ] **1a. Failing tests** (append to `tests/test_memory.py`):
+  ```python
+  def test_full_mode_recall_waits_for_two_memories():
+      from memory import should_recall
+      one = {"affinity": 30, "treasure": ["a"], "claimed": [], "turn": 1,
+             "last_recall_turn": None, "mode": "full"}
+      assert should_recall(one)[0] is False        # full needs >=2 before first recall
+      two = dict(one, treasure=["a", "bb"])
+      assert should_recall(two)[0] is True
+  def test_full_mode_ending_gate_is_higher():
+      from memory import decide_ending
+      mid = {"affinity": 55, "claimed": ["a", "b"], "turn": 8, "tone": 25,
+             "wounds": [], "ended": False, "mode": "full"}
+      assert decide_ending(mid) is None             # 55 < full gate 68
+      hi = dict(mid, affinity=70, claimed=["a", "b", "c"])
+      assert decide_ending(hi) == "good"
+  def test_tester_mode_unchanged():
+      from memory import should_recall, decide_ending
+      s = {"affinity": 24, "treasure": ["x"], "claimed": [], "turn": 1,
+           "last_recall_turn": None, "mode": "tester"}
+      assert should_recall(s)[0] is True            # tester: first memory -> recall
+      e = {"affinity": 52, "claimed": ["a", "b"], "turn": 6, "tone": 25,
+           "wounds": [], "ended": False, "mode": "tester"}
+      assert decide_ending(e) == "good"
+  ```
+- [ ] **1b. Run, verify fail.**
+- [ ] **1c. Implement.** In `memory.py`, add the config and make the two functions mode-aware:
+  ```python
+  PACING = {
+      "tester": {"recall_min_memories": 1, "recall_cooldown": 2,
+                 "end_affinity": 50, "end_claimed": 2, "bad_min_turn": 4},
+      "full":   {"recall_min_memories": 2, "recall_cooldown": 3,
+                 "end_affinity": 68, "end_claimed": 3, "bad_min_turn": 6},
+  }
+  def _cfg(state: dict) -> dict:
+      return PACING.get(state.get("mode", "tester"), PACING["tester"])
+  ```
+  `should_recall`:
+  ```python
+  def should_recall(state: dict) -> tuple[bool, str | None]:
+      cfg = _cfg(state)
+      unclaimed = [m for m in state["treasure"] if m not in state["claimed"]]
+      if len(unclaimed) < cfg["recall_min_memories"]:
+          return False, None
+      richest = max(unclaimed, key=len)
+      last = state.get("last_recall_turn")
+      if last is None:
+          return True, richest
+      if state["turn"] - last >= cfg["recall_cooldown"]:
+          return True, richest
+      return False, None
+  ```
+  `decide_ending` (replace the two numeric gates with `cfg`):
+  ```python
+      cfg = _cfg(state)
+      tone = state.get("tone", 0)
+      if tone <= -30 and state["turn"] >= cfg["bad_min_turn"] and len(state.get("wounds", [])) >= 2:
+          return "bad"
+      if state["affinity"] >= cfg["end_affinity"] and len(state["claimed"]) >= cfg["end_claimed"]:
+          return "good" if tone >= 20 else "loop"
+      return None
+  ```
+- [ ] **1d.** Update existing `decide_ending`/`should_recall` tests that pass states without `mode` — they default to "tester" via `_cfg`, so they should still pass; fix any that hard-coded the old 50/4 expecting a different mode.
+- [ ] **1e.** `tools/pacing_sim.py`: add a `--mode` (or loop both) so it sets `state["mode"]`. Run it for both modes; record the measured arc lengths in the commit message. Confirm Tester ~5-7, Full ~8-12.
+- [ ] **1f. Run** the suite → green. **Commit:** `feat: Tester vs Full pacing modes (config-driven gates)`.
+---
+## PHASE 4 — How to Play overlay
+**Files:** `app.py`, `styles.css`, `tests/test_app.py`.
+- [ ] **1a.** In `app.py`, inside `menu_view` (after the buttons), add a hidden overlay group:
+  ```python
+          with gr.Column(visible=False, elem_id="howto-overlay") as howto_overlay:
+              gr.HTML(_HOWTO_HTML)
+              howto_close = gr.Button("close", elem_id="btn-howto-close",
+                                      elem_classes="menu-btn")
+  ```
+  Add the copy constant near the other text constants:
+  ```python
+  _HOWTO_HTML = (
+      '<div class="howto-panel">'
+      '<h3>How to Play</h3>'
+      '<p>You found a child at the edge of the wood. It has no memories of its own '
+      '&mdash; so it asks for yours.</p>'
+      '<p>Tell it something true: a person, a place, a moment you lived. It keeps each '
+      'one in its treasure.</p>'
+      '<p>Later it speaks your memories back &mdash; in the first person, as if it had '
+      'lived them. That is what it wants.</p>'
+      '<p>But it remembers how you treat it. Be gentle, or be cruel. '
+      '<b>Three endings</b> wait in the fog.</p>'
+      '<p class="howto-controls">type and press enter &middot; 🔊 mute &middot; '
+      '↺ begin again &middot; turn your sound on</p>'
+      '</div>'
+  )
+  ```
+- [ ] **1b.** Wire open/close (visibility toggles — no audio, safe):
+  ```python
+      howto_btn.click(lambda: gr.update(visible=True), None, howto_overlay,
+                      show_progress="hidden")
+      howto_close.click(lambda: gr.update(visible=False), None, howto_overlay,
+                        show_progress="hidden")
+  ```
+- [ ] **1c.** `styles.css §24`: `#howto-overlay{position:absolute;inset:0;z-index:10;display:flex;align-items:center;justify-content:center;background:#04040ae0;}` and `.howto-panel{max-width:560px;border:11px solid transparent;border-image:var(--stone-frame) 30;background:var(--stone-base);padding:26px 30px;font-family:Georgia,serif;color:#c4bede;line-height:1.6;}` (reuse the carved-stone frame vars). Style `h3`, `.howto-controls` (smaller, muted, letter-spaced).
+- [ ] **1d. Tests:** `assert "Three endings" in app._HOWTO_HTML`; open returns `visible True`, close returns `visible False`. Run suite → green.
+- [ ] **1e. Live screenshot:** How to Play opens a readable stone panel over the menu; close returns. **Commit:** `feat: How to Play overlay`.
+---
+## PHASE 5 — Menu music + chime→greeting ritual on mode-select
+**Files:** `sting.py`, `tests/test_sting.py`, `app.py`, `tests/test_app.py`.
+This phase OWNS the audio flow (superseding the standalone chime-ritual plan): the menu loop starts on the first menu gesture; choosing a mode stops it and plays **chime → greeting** as the entrance, then the game (already revealed by Phase 1) takes over with its per-reply voice.
+### Step 1 — Synthesize the menu loop
+- [ ] **1a. Failing test** (`tests/test_sting.py`): `assert len(menu_loop_wav_bytes()) > 2000`.
+- [ ] **1b.** In `sting.py`, add `menu_loop_wav_bytes()`: a slow, low, detuned music-box / drone motif (a few minor-key notes over a soft low drone, light reverb), 1 dB-quiet, built to **loop seamlessly** (start and end at silence/zero-crossing). Reuse the existing `_wav` writer and the chime/sine helpers already in the file. Keep it short (~6-10 s) so the base64 stays small.
+- [ ] **1c. Run** the sting test → green.
+### Step 2 — Embed the loop + chime/greeting constants
+- [ ] **2a.** In `app.py`, build the audio constants (the chime + greeting were previously the `_greeting_html` element; consolidate as `data:` URI constants like the planned chime-ritual):
+  ```python
+  from sting import chime_wav_bytes, menu_loop_wav_bytes
+  _CHIME_B64 = base64.b64encode(chime_wav_bytes(0)).decode()
+  _GREETING_B64 = speak(OPENING_LINE) or ""
+  _MENU_LOOP_B64 = base64.b64encode(menu_loop_wav_bytes()).decode()
+  _CHIME_URI = f"data:audio/wav;base64,{_CHIME_B64}"
+  _GREETING_URI = f"data:audio/wav;base64,{_GREETING_B64}" if _GREETING_B64 else ""
+  _MENU_LOOP_URI = f"data:audio/wav;base64,{_MENU_LOOP_B64}"
+  ```
+  Remove the now-obsolete `_greeting_html` function and its `#hollow-greeting` element in `voice_panel` (set `voice_panel = gr.HTML(value="", elem_classes="voice-channel")`). Remove the `test_greeting_html_*` tests.
+- [ ] **2b.** Put the menu loop element inside `menu_view`: `gr.HTML('<audio id="menu-loop" loop src="' + _MENU_LOOP_URI + '"></audio>')` (no autoplay — the controller starts it on gesture).
+### Step 3 — Rework the `<head>` controller audio flow
+- [ ] **3a.** In `_HEAD_JS`, inject the three URIs via placeholders (build with `.replace`, NOT f-string): `var CHIME_SRC="__CHIME__"; var GREETING_SRC="__GREETING__"; var MENU_SRC="__MENU__";` and after the string: `_HEAD_JS = _HEAD_JS.replace("__CHIME__", _CHIME_URI).replace("__GREETING__", _GREETING_URI).replace("__MENU__", _MENU_LOOP_URI)`.
+- [ ] **3b.** Add to the controller (next to the queue helpers):
+  ```javascript
+    var menuAudio = null;
+    function startMenuMusic() {
+      if (menuAudio || !MENU_SRC) return;
+      menuAudio = document.getElementById('menu-loop') || new Audio(MENU_SRC);
+      menuAudio.loop = true; menuAudio.volume = st.muted ? 0 : 0.5;
+      menuAudio.muted = st.muted;
+      menuAudio.play().catch(function () {});
+    }
+    function stopMenuMusic() {
+      if (menuAudio) { try { menuAudio.pause(); } catch (e) {} menuAudio = null; }
+    }
+    var _lastRitual = 0;
+    function openingRitual() {            // chime, then the child greets
+      var now = Date.now(); if (now - _lastRitual < 800) return; _lastRitual = now;
+      resetQueue();
+      if (CHIME_SRC) enqueue(CHIME_SRC);
+      if (GREETING_SRC) enqueue(GREETING_SRC);
+    }
+  ```
+- [ ] **3c.** REPLACE the current first-gesture greeting handler. The first menu gesture now starts the **menu music** (not the greeting):
+  ```javascript
+    function firstGesture() {
+      startMenuMusic();
+      window.removeEventListener('pointerdown', firstGesture, true);
+      window.removeEventListener('keydown', firstGesture, true);
+    }
+    window.addEventListener('pointerdown', firstGesture, true);
+    window.addEventListener('keydown', firstGesture, true);
+  ```
+- [ ] **3d.** Extend `wire()` (the poller that already wires `.voice-btn`/`.restart-btn`) to also wire the mode buttons: when `.menu-mode-btn` elements exist, add a click listener that does `stopMenuMusic(); openingRitual();` (do NOT stopPropagation — the server `_enter_game` must still run). Restart (`.restart-btn`) keeps calling `openingRitual()` (re-greet on "begin again", which restarts the current game in place).
+- [ ] **3e.** Mute: `applyLive()` already covers queued audio; also have the mute toggle set `menuAudio.muted` if `menuAudio` exists.
+### Step 4 — Tests + verify
+- [ ] **4a.** `tests/test_app.py`: `assert "openingRitual" in app._HEAD_JS`, `assert "startMenuMusic" in app._HEAD_JS`, `assert "menu-loop" in app._menu_html() or "menu-loop" in <the menu audio html>`, `assert app._MENU_LOOP_URI.startswith("data:audio/wav")`. Remove obsolete greeting-html tests. Run suite → green.
+- [ ] **4b. Live (by ear, user):** first menu gesture → eerie loop starts (low); click Tester/Full → loop stops, chime → child greets, game shows and streams replies; 🔊 mutes everything (menu + voice); "begin again" re-greets. Kill the port owner.
+- [ ] **4c. Commit:** `feat: menu melody + chime-greeting ritual on mode select`.
+---
+## FINAL — verification & docs
+- [ ] **1.** `.venv/Scripts/python -m pytest -q` → all green.
+- [ ] **2.** Full live playthrough (`.venv-tts` + Ollama) with the user: menu (Direction C, painted backdrop, melody) → How to Play reads → pick **Tester** → chime→greeting → fast arc (wow ~turn 2, ending ~5-7); restart, pick **Full** → longer arc (~8-12). Mute/idle/streaming all intact. Confirm all three finales still fire with sound.
+- [ ] **3.** Update `CLAUDE.md` + `AGENTS.md`: new front-door menu (Direction C + `assets/background.webp`), `mode` in state + `PACING` config (tester/full), How to Play overlay, menu loop + ritual-on-mode-select; note this superseded the standalone chime-ritual plan; `_greeting_html` removed. Update file structure + state shape + tests count. Keep ≤200 lines.
+- [ ] **4.** **Merge back, with the user's go-ahead** (REQUIRED SUB-SKILL: superpowers:finishing-a-development-branch): once all phases pass and the user approves the live playthrough, merge `feat/front-door-menu` → `feat/voice-awareness` (fast-forward or `--no-ff`, the finishing skill decides). If the user is unhappy with the result, the branch is simply abandoned and `feat/voice-awareness` is untouched. Do NOT merge to `main` here — `main` and the deploy wait until the whole branch (incl. the prior streaming/pacing work) has had a live playthrough.
+- [ ] **5.** Deploy is out of scope — the user runs the mirror-first deploy after the merge, approving the playthrough (and Phase C streaming Space-verification from the prior plan).
+---
+## Self-review notes
+- **Spec coverage:** menu (P1+P2), modes (P3), how-to-play (P4), menu music + chime ritual (P5) — every spec component has a phase; each phase is independently shippable and verified.
+- **Supersession is explicit:** the chime-ritual plan is NOT executed; this plan owns the ritual and re-points it to mode-select (the only place a greeting makes sense once a menu exists).
+- **Unmount caveat respected:** only menu/game/how-to toggle `visible`; none hold audio that must run while hidden — game audio mounts when `game_view` shows.
+- **Modes are config-only:** `PACING` + `_cfg(state)`; `should_recall`/`decide_ending` read `state["mode"]`; no call-path changes, so the streaming/extraction/finale logic is untouched. Tester reproduces the current arc exactly (default).
+- **`.replace`, not f-string** for `_HEAD_JS` (the JS body has literal `{}`); placeholders filled after the string is defined.
+- **Audio = images-are-fine / synth-the-rest:** background is a committed WebP (allowed); the menu loop is synthesized at runtime (`sting.py`), no committed audio binary.
+- **Visuals screenshot-verified, audio by ear** — per the project's hard-won rules; the approved mockup at `.superpowers/brainstorm/3158-1781454014/content/c-final-bg.html` is the visual reference.

docs/superpowers/specs/2026-06-14-front-door-menu-design.md ADDED Viewed

	@@ -0,0 +1,52 @@

+# Front Door — Menu, Modes, How-to-Play, Menu Music — Design
+**Date:** 2026-06-14 · **Project:** Hollow (Build Small Hackathon)
+## Goal
+Give Hollow a real "front door": a Fear & Hunger / Termina-**inspired** (not copied) opening menu over an AI-generated foggy-wood background, with two play modes — **Tester Run** (fast, judge-friendly) and **The Full Stay** (a genuinely longer experience) — a **How to Play** panel, a subtle eerie **menu melody**, and the existing **chime** as the "you're entering" cue when a mode is chosen. This makes the demo trivial to run (pick Tester) and lifts the whole thing from "homemade Gradio" to "a game".
+## Approved visual direction
+Direction **C** ("Cold Vista", Termina-style): a wide grayscale painted forest backdrop (path → ruined monument in fog), gothic small-caps **HOLLOW** title centered with the track eyebrow above, a tight vertical menu, "How to Play" in a corner, a quiet credit line, all under a radial **scrim** + top/bottom gradients (text legibility over any image) + grain + vignette. The visitor-supplied image (`assets/backroud.png`) is the backdrop, post-processed to grayscale + darkened to match the portraits.
+## Architecture
+- **Two top-level views in the Blocks:** `menu_view` (visible at start) and `game_view` (the existing 3-column game, `visible=False` at start). Selecting a mode flips both visibilities and initializes the game state with the chosen mode.
+  - **Audio-unmount caveat (CLAUDE.md):** `visible=False` can unmount a component, so the game's `voice_panel` / `#idle-trigger` must NOT be needed while hidden. They aren't — game audio only matters once `game_view` is shown, at which point they mount and the `<head>` controller's MutationObserver picks audio up. Safe.
+- **Mode is state.** `state["mode"] ∈ {"tester","full"}`. A `PACING` config dict (in `memory.py`) maps each mode to its thresholds; `should_recall` and `decide_ending` read `state.get("mode","tester")` and look the values up. No engine call paths change — only the numbers.
+- **The opening ritual moves to mode-select.** Today chime→greeting fires on the first page gesture. With a menu, the page's first gesture lands on the MENU; so: menu melody starts on the first menu gesture; choosing a mode **stops the melody, runs the chime→greeting ritual, and reveals the game**. The `<head>` controller gains listeners on the mode buttons (same pattern as the restart button).
+## Components
+1. **Menu screen** — `menu_view` rendered as a single `gr.HTML` (the C composition, fully styled, background embedded) PLUS three real `gr.Button`s (Tester / Full / How to Play) positioned over it via CSS, so clicks hit the server. Visual is CSS; the background is the post-processed WebP as a base64 `data:` URI in a Python constant (same approach as the portraits).
+2. **Mode mechanics** — `PACING` config:
+   | key | tester | full | meaning |
+   |-----|--------|------|---------|
+   | `recall_min_memories` | 1 | 2 | unclaimed memories needed before the first recall |
+   | `recall_cooldown` | 2 | 3 | turns between recalls |
+   | `end_affinity` | 50 | 68 | affinity gate for good/loop |
+   | `end_claimed` | 2 | 3 | claimed memories for good/loop |
+   | `bad_min_turn` | 4 | 6 | min turn for the wound ending |
+   Tester reproduces today's arc (wow ~turn 2, ending ~5-7). Full lands ~turn 8-12. Both branch good/loop at tone 20 and bad at tone ≤ −30 ∧ wounds ≥ 2, unchanged.
+3. **How to Play overlay** — a dismissible panel over the menu. Copy (in the game's voice):
+   > You found a child at the edge of the wood. It has no memories of its own — so it asks for yours.
+   > Tell it something true: a person, a place, a moment you lived. It keeps each in its treasure.
+   > Later it speaks your memories back — in the first person, as if it had lived them. That is what it wants.
+   > But it remembers how you treat it. Be gentle, or be cruel. Three endings wait in the fog.
+   > *type and press enter · 🔊 mute · ↺ begin again · turn your sound on*
+4. **Menu music + chime** — a slow, detuned music-box / drone **loop** synthesized in `sting.py` (`menu_loop_wav_bytes()`), embedded in the menu as a looped `<audio>`; the `<head>` controller starts it on the first menu gesture (autoplay gate), at low volume, and stops it on mode-select. Mode-select then plays the existing chime → greeting ritual and transitions to the game.
+## Testing
+- **Unit:** `PACING` config exists and `should_recall`/`decide_ending` honor `mode` (tester vs full gates); menu state init sets `mode`; mode-select returns the right visibility updates. How-to-play open/close. `menu_loop_wav_bytes()` returns real audio.
+- **Live (screenshot):** the menu renders with the background + scrim + title + buttons legible; the switch to game works.
+- **By ear (user):** menu melody on first gesture; chime→greeting on mode-select; game voice/idle/mute unaffected.
+- **Pacing re-measure:** run `tools/pacing_sim.py` for both modes; confirm Tester ~5-7 and Full ~8-12.
+## Risks / constraints
+- **`visible=False` unmount** — only the menu (no persistent audio) and the game view toggle; game audio mounts on show. Verified pattern.
+- **Autoplay** — menu music can't play before a gesture; it starts on the first menu interaction (consistent with the greeting rule).
+- **Space build** — the background is an **image** (WebP), which HF accepts (only committed audio binaries are rejected); the menu melody is synthesized at runtime like the other stings. No new deps.
+- **Scope** — five phases, each shippable; Phase 3 (modes) is the only engine-touching one and is pure-number config.
+## Out of scope (deliberate)
+- Re-painting the in-game scene (the game already has its stone/fog styling); this is the menu/front-door. A light F&H typography pass in-game can follow later if wanted.
+- Save/continue, multiple save slots, settings screens. YAGNI for a hackathon front door.