Spaces:

Pabloler21
/

hollow

Sleeping

Pabloler21 Claude Fable 5 commited on Jun 14

Commit

8c9619e

1 Parent(s): 9ce912d

feat: front-door menu, Tester/Full modes, How to Play, menu music + ritual

- Two-view Gradio layout: menu_view (Direction C painted backdrop) and game_view.
- mode-driven PACING config in memory.py (tester fast arc, full longer arc).
- How to Play stone overlay.
- Synthesized menu loop + chime->greeting ritual on mode-select/restart.
- Docs (CLAUDE.md, AGENTS.md) and tests updated; 231 passing.

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

Files changed (11) hide show

AGENTS.md +18 -18
CLAUDE.md +18 -18
app.py +248 -146
assets/background.webp +3 -0
memory.py +19 -5
sting.py +54 -1
styles.css +197 -0
tests/test_app.py +45 -2
tests/test_memory.py +28 -0
tests/test_sting.py +7 -1
tools/pacing_sim.py +7 -6

AGENTS.md CHANGED Viewed

@@ -37,7 +37,7 @@ git push space main && git push hackathon main
 No linter, formatter, or typechecker is configured. After changes, run `pytest` as the only verification step.
 ## Stack (decided — do not reopen)
-- **UI:** Gradio 6.x `gr.Blocks` + `gr.Chatbot` (messages format default, no `type` param). Horror visuals are **pure CSS**; a single `<head>` JS controller (`_HEAD_JS`, passed to `launch(head=...)`) handles browser-only concerns — opening-chime-ritual (chime → greeting on first gesture and on restart), mute, idle timing. **JS is allowed** by the hackathon (verified, Field Guide); "no JS" was our own choice, dropped only for these. (README/FIELD_NOTES still boast "no JS" — fix before deploy.)
 - **Model:** `Qwen/Qwen3-8B` via `transformers`+`@spaces.GPU(duration=90)` on Space; `qwen3:8b` via Ollama (`localhost:11434`) locally. Switch: `IS_SPACE = bool(os.environ.get("SPACE_ID"))`.
 - **Voice:** Kokoro-82M TTS (`voice.py`), **CPU** — the child whispers (`af_nicole`, speed 0.88, "28% fog" numpy DSP). Import-guarded → **silent if unavailable** (local 3.13 `.venv` has no kokoro; works in 3.12 `.venv-tts` and on the Space at py3.11). Per-reply/finale audio inlined as autoplay `<audio>` in a mounted-but-CSS-collapsed `voice_panel`. The opening ritual (detuned music-box chime → spoken greeting) is queued from `data:` URI constants in `_HEAD_JS`. Plays on every Hollow reply + all finale lines.
 - **State:** plain dict in `gr.State` per session. **Parsing:** Pydantic v2 + fallback.
@@ -59,11 +59,11 @@ character.py  # build_system_prompt(... tone, wounds, memory_plea, own_fragment,
 memory.py     # get_tier, apply_update (+ sanitize/Hollow-words filter), should_recall, decide_ending, style_signal (B3), pick_aware_memory (B2) — pure
 finale.py     # finale_steps (loop), finale_steps_bad (wound), finale_steps_good (redemption) — pure data; each has a "frenzy" convulse stage
 render.py     # render_entity(affinity, mode, seq) — modes: idle/flash/flash_strong/build/frenzy/convulse_good/convulse_loop/end/end_settle/rage/peace/peace_settle/peace_dissolve; materialization = fog+brightness (no blur); render_treasure(...)
-sting.py      # _wav + sting/chime/heartbeat/sigh/flatline _wav_bytes — numpy audio synth (HF rejects committed .wav)
-styles.css    # horror CSS §15-22 (22 = finale build pulse + soft convulse + restart + .voice-channel; #idle-trigger hidden)
 assets/       # hollow_{base,terror,almost,end,rage,peace}.webp  (rage = almost copy placeholder; peace = real art)
 requirements.txt / packages.txt   # +kokoro/misaki[en]/soundfile/spacy/en_core_web_sm; espeak-ng (apt)
-tests/        # 212 tests: test_{memory,render,finale,schemas,engine,character,app,sting,voice}.py
 docs/superpowers/{specs,plans}/   # approved specs + plans (active: 2026-06-14-pacing-streaming-overhaul)
 tools/pacing_sim.py               # scripted visitors through real Ollama — pacing tuning
 ```
@@ -87,6 +87,7 @@ tools/pacing_sim.py               # scripted visitors through real Ollama — pa
   "last_activity": float,     # vestigial (client owns idle timing now)
   "idle_count": int,          # how many idle nudges fired (tier + bond decay)
   "barren_turns": int,        # consecutive turns with no captured memory
 }
 ```
 Dev seed: `HOLLOW_FAST_FINALE=good|loop|bad` (`1`/`neutral` alias→ good/loop) — each ending fires on the 2nd message.
@@ -100,16 +101,16 @@ Dev seed: `HOLLOW_FAST_FINALE=good|loop|bad` (`1`/`neutral` alias→ good/loop)
 | 76–100| Almost | possessive | `hollow_almost`, no sway |
 ## Ending matrix (`decide_ending`, checked at turn start, fully scripted, no GPU)
-Single gate so no lower threshold can race a warm run:
-- **bad** (Wound Loop): `tone≤−30 ∧ turn≥4 ∧ wounds≥2`. Recites your cruelties (redacted ▮ → un-redacted), header→"Your Words", frenzy convulsion + triple full-screen stab + scream, reveals `hollow_almost`, threatens, ends "see you... soon."
-- **good** (Redemption): `aff≥50 ∧ claimed≥2 ∧ tone≥20`. Genuine sustained warmth surfaced `OWN_FRAGMENTS` of its real past (tortured/orphaned/starved) during play; finale confesses it's the thing that waits, RETURNS the treasure (un-claimed, lit), first smile (`hollow_peace` → `peace_dissolve`), leaves in peace.
-- **loop** (Visitor Loop): `aff≥50 ∧ claimed≥2 ∧ tone<20`. The DEFAULT high-bond ending — fed plenty but treated transactionally, never truly loved → stays a predator, consumes you, ends with YOU speaking its opening line. Redemption is the rare earned ending; ordinary polite play lands here.
-- Single gate (50/2-claimed) branched at tone 20 — no lower threshold can race a warm run.
 - Tone bands in prompt (separate from ending routing): warm ≥15 / wounded −22..−1 / hostile ≤−22 (injects wounds). Mimicry always on.
-- **Pacing after overhaul:** recall fires as soon as there is one unclaimed memory (no affinity floor); ending gate dropped from 70/turn≥5 to 50/turn≥4 so a satisfying arc lands in ~5-7 turns. Re-measure with `tools/pacing_sim.py` after tuning.
 ## Voice + Presence (the child speaks & watches)
-- **Voice:** every Hollow reply + all finale lines are spoken (Kokoro, CPU); the opening line is spoken as part of the **opening ritual** (detuned chime → greeting) on the visitor's **first gesture** and again on every **"begin again"** (browser autoplay blocks it on load). The reply text now streams token-by-token, and each completed sentence is synthesized and handed to a **client-side audio queue** in the `<head>` controller so sentences play in order without cutting each other. Finale `_voice_and_pause` stretches each step's pause to the audio length (+0.15 s) so lines aren't cut. Recall + finale = the wow. **Mute is client-side**: the controller owns global `{muted}` (persisted to `localStorage`), applies it to the currently playing queued audio and future ones, and drives the 🔊/🔇 button (mute only — no volume slider; voice plays at a fixed level). The server always synthesizes; the browser decides audibility. Horror audio in the entity panel stays untouched.
 - **Awareness (B1/B2/B3):** B3 `style_signal` (Hollow notices short/long messages); B2 `pick_aware_memory` (resurfaces an earlier memory unprompted, every 3rd non-recall turn); B1 idle is timed client-side (60 s, reset by any pointer/keyboard/input/scroll) and clicks a hidden `#idle-trigger` to run `_on_idle` — escalating plead→hurt→hostile (`_IDLE_TIERS`) with affinity −3 / tone −2 per nudge. B4 `memory_plea`: consecutive barren turns make Hollow ask more plainly for a real memory.
 - **Materialization:** the child is **sharp, veiled in fog + shadow** (brightness 0.4→1, fog/vig denser at low bond) — NOT blurred (blur read as a broken image).
@@ -131,7 +132,7 @@ Single gate so no lower threshold can race a warm run:
 - **Space streaming caveat:** `TextIteratorStreamer` inside `@spaces.GPU` was the documented way to stream on ZeroGPU, but it must be verified on the mirror Space before trusting it. If it breaks, gate the Space branch to fall back to the non-streaming `run_turn` (yield the whole reply once), leaving the Ollama path streaming.
 - **Hide Gradio progress, animate our own:** `show_progress="hidden"` on the events kills the per-component "processing | Xs" overlay (CSS class-hiding was unreliable); we render our own `_PENDING` typing bubble. The HTML span + class survives Gradio's markdown sanitizer (verified) so §20 CSS animates it.
 - **Idle is client-timed via the `<head>` controller:** a hidden `#idle-trigger` button runs `_on_idle`; the server only guards against pending/ended states. Any interaction resets the 60 s clock.
-- **Browser autoplay blocks audio before the visitor's first gesture** — the opening line can't auto-speak on load; the head controller plays the chime → greeting ritual on the first pointer/keyboard gesture and re-runs it when **"begin again"** is clicked. The controller also applies volume/mute to every remounted `.voice-channel audio` via MutationObserver; horror audio in the entity panel is unaffected.
 - **Mute is client-side, not server-side:** never gate `speak()` on a `voice_on` flag. The server always synthesizes audio; the browser mutes the playing element.
 - **Media mute = control the element, never replay.** Mute must toggle the *playing* audio's `.muted` (client-side); do NOT clear-then-replay-the-last-line on un-mute — that produced an infinite re-play loop (bug we hit). The browser owns playback state, not the server.
 - **Never default a time/clock field to `0.0`.** `time.time() - 0` ≈ 1.7e9 s, so any "elapsed since" gate fires instantly (bug: the idle nudge fired every 4 s, not after 35 s). Stamp at session start, or better, time it client-side.
@@ -151,9 +152,8 @@ Single gate so no lower threshold can race a warm run:
 - **Voice:** Kokoro TTS (`af_nicole` voice, 28% fog filter, speed 0.80). CPU only. Import-guarded — app runs silent if kokoro unavailable.
 ## What's next / pending
-- **Current work is on branch `feat/voice-awareness`, NOT deployed.** Both Spaces are frozen at the pre-voice commit (`4deeed5`) — the submission stays safe while we iterate. Done on the branch (212 tests green): voice + awareness, presence-polish, client-side mute, opening-chime-ritual, dash strip, client-timed idle (60 s), memory coaching. Deploy is **mirror-first**: merge → push `space` → verify build+voice live → push `hackathon`.
-- **DONE:** `docs/superpowers/plans/2026-06-14-pacing-streaming-overhaul.md` — recall now fires as soon as a memory exists (no affinity floor), ending gate lowered to 50/turn≥4 (~5-7 turn arc), replies are short/varied with an explicit anti-template directive, extraction consolidates to one rich memory per turn, token budgets shrunk to 150/80, and the reply now streams token-by-token with per-sentence voice via a client-side audio queue.
-- **Before deploy:** mirror-first deploy to verify `TextIteratorStreamer` under ZeroGPU; update README/FIELD_NOTES "no JS" boast (now false — we added the `<head>` controller; JS is allowed, frame it as "horror is CSS; the only JS satisfies the browser's autoplay-gesture + audio/idle").
-- **`FIELD_NOTES.md`** lives in the repo (📓 badge content). Field Notes done; the demo video + LinkedIn post are Pablo's, link both from the README when ready.
-- **Optional art:** `hollow_rage.webp` is still a copy of `hollow_almost` (works fine). Swap a PNG: `Image.open(png).convert("RGB").resize((512,512),LANCZOS).save(webp,"WEBP",quality=80,method=6)`.
-- **Deliverables (Pablo):** demo video (horror-trailer), social post. **Mon June 15:** submit early + community vote.

 No linter, formatter, or typechecker is configured. After changes, run `pytest` as the only verification step.
 ## Stack (decided — do not reopen)
+- **UI:** Gradio 6.x `gr.Blocks` + `gr.Chatbot`. A Fear & Hunger-inspired **front-door menu** (`menu_view`) with painted foggy-wood backdrop (`assets/background.webp`), two modes (`Tester Run` / `The Full Stay`), and a `How to Play` overlay switches to the hidden `game_view` on mode-select. Horror visuals are pure CSS; the `<head>` JS controller handles menu music, the chime→greeting ritual on mode-select/restart, mute, and idle timing.
 - **Model:** `Qwen/Qwen3-8B` via `transformers`+`@spaces.GPU(duration=90)` on Space; `qwen3:8b` via Ollama (`localhost:11434`) locally. Switch: `IS_SPACE = bool(os.environ.get("SPACE_ID"))`.
 - **Voice:** Kokoro-82M TTS (`voice.py`), **CPU** — the child whispers (`af_nicole`, speed 0.88, "28% fog" numpy DSP). Import-guarded → **silent if unavailable** (local 3.13 `.venv` has no kokoro; works in 3.12 `.venv-tts` and on the Space at py3.11). Per-reply/finale audio inlined as autoplay `<audio>` in a mounted-but-CSS-collapsed `voice_panel`. The opening ritual (detuned music-box chime → spoken greeting) is queued from `data:` URI constants in `_HEAD_JS`. Plays on every Hollow reply + all finale lines.
 - **State:** plain dict in `gr.State` per session. **Parsing:** Pydantic v2 + fallback.
 memory.py     # get_tier, apply_update (+ sanitize/Hollow-words filter), should_recall, decide_ending, style_signal (B3), pick_aware_memory (B2) — pure
 finale.py     # finale_steps (loop), finale_steps_bad (wound), finale_steps_good (redemption) — pure data; each has a "frenzy" convulse stage
 render.py     # render_entity(affinity, mode, seq) — modes: idle/flash/flash_strong/build/frenzy/convulse_good/convulse_loop/end/end_settle/rage/peace/peace_settle/peace_dissolve; materialization = fog+brightness (no blur); render_treasure(...)
+sting.py      # _wav + sting/chime/heartbeat/sigh/flatline/menu_loop _wav_bytes — numpy audio synth (HF rejects committed .wav)
+styles.css    # horror CSS §15-24 (23 = opening menu, 24 = How to Play overlay; 22 = finale/restart/voice-channel)
 assets/       # hollow_{base,terror,almost,end,rage,peace}.webp  (rage = almost copy placeholder; peace = real art)
 requirements.txt / packages.txt   # +kokoro/misaki[en]/soundfile/spacy/en_core_web_sm; espeak-ng (apt)
+tests/        # 231 tests: test_{memory,render,finale,schemas,engine,character,app,sting,voice}.py
 docs/superpowers/{specs,plans}/   # approved specs + plans (active: 2026-06-14-pacing-streaming-overhaul)
 tools/pacing_sim.py               # scripted visitors through real Ollama — pacing tuning
 ```
   "last_activity": float,     # vestigial (client owns idle timing now)
   "idle_count": int,          # how many idle nudges fired (tier + bond decay)
   "barren_turns": int,        # consecutive turns with no captured memory
+  "mode": str,                # "tester" | "full" — pacing profile
 }
 ```
 Dev seed: `HOLLOW_FAST_FINALE=good|loop|bad` (`1`/`neutral` alias→ good/loop) — each ending fires on the 2nd message.
 | 76–100| Almost | possessive | `hollow_almost`, no sway |
 ## Ending matrix (`decide_ending`, checked at turn start, fully scripted, no GPU)
+Mode-driven `PACING` config in `memory.py` (tester = fast/judge-friendly, full = longer experience). Single gate so no lower threshold can race a warm run:
+- **tester:** `bad` at `tone≤−30 ∧ turn≥4 ∧ wounds≥2`; `good/loop` at `aff≥50 ∧ claimed≥2` branched by `tone≥20`.
+- **full:** `bad` at `tone≤−30 ∧ turn≥6 ∧ wounds≥2`; `good/loop` at `aff≥68 ∧ claimed≥3` branched by `tone≥20`.
+- **bad** (Wound Loop): recites your cruelties (redacted ▮ → un-redacted), header→"Your Words", frenzy convulsion + triple full-screen stab + scream, reveals `hollow_almost`, threatens, ends "see you... soon."
+- **good** (Redemption): genuine sustained warmth surfaced `OWN_FRAGMENTS` of its real past; finale confesses it's the thing that waits, RETURNS the treasure (un-claimed, lit), first smile (`hollow_peace` → `peace_dissolve`), leaves in peace.
+- **loop** (Visitor Loop): fed plenty but treated transactionally, never truly loved → stays a predator, consumes you, ends with YOU speaking its opening line.
 - Tone bands in prompt (separate from ending routing): warm ≥15 / wounded −22..−1 / hostile ≤−22 (injects wounds). Mimicry always on.
 ## Voice + Presence (the child speaks & watches)
+- **Voice:** every Hollow reply + all finale lines are spoken (Kokoro, CPU). The front-door menu plays a synthesized eerie **menu loop** on the first gesture; choosing a mode stops it and plays the **chime → greeting** ritual. "Begin again" re-triggers the ritual. The reply text streams token-by-token, and each completed sentence is synthesized and handed to a **client-side audio queue** in the `<head>` controller so sentences play in order without cutting each other. Finale `_voice_and_pause` stretches each step's pause to the audio length (+0.15 s). **Mute is client-side**: the controller owns global `{muted}` (persisted to `localStorage`), applies it to queued audio, menu music, and future audio, driving the 🔊/🔇 button. The server always synthesizes; the browser decides audibility.
 - **Awareness (B1/B2/B3):** B3 `style_signal` (Hollow notices short/long messages); B2 `pick_aware_memory` (resurfaces an earlier memory unprompted, every 3rd non-recall turn); B1 idle is timed client-side (60 s, reset by any pointer/keyboard/input/scroll) and clicks a hidden `#idle-trigger` to run `_on_idle` — escalating plead→hurt→hostile (`_IDLE_TIERS`) with affinity −3 / tone −2 per nudge. B4 `memory_plea`: consecutive barren turns make Hollow ask more plainly for a real memory.
 - **Materialization:** the child is **sharp, veiled in fog + shadow** (brightness 0.4→1, fog/vig denser at low bond) — NOT blurred (blur read as a broken image).
 - **Space streaming caveat:** `TextIteratorStreamer` inside `@spaces.GPU` was the documented way to stream on ZeroGPU, but it must be verified on the mirror Space before trusting it. If it breaks, gate the Space branch to fall back to the non-streaming `run_turn` (yield the whole reply once), leaving the Ollama path streaming.
 - **Hide Gradio progress, animate our own:** `show_progress="hidden"` on the events kills the per-component "processing | Xs" overlay (CSS class-hiding was unreliable); we render our own `_PENDING` typing bubble. The HTML span + class survives Gradio's markdown sanitizer (verified) so §20 CSS animates it.
 - **Idle is client-timed via the `<head>` controller:** a hidden `#idle-trigger` button runs `_on_idle`; the server only guards against pending/ended states. Any interaction resets the 60 s clock.
+- **Browser autoplay blocks audio before the visitor's first gesture** — the head controller starts the menu loop on the first menu gesture, then plays the chime → greeting ritual when a mode is selected or "begin again" is clicked. The controller applies volume/mute to queued voice audio and the menu bed via MutationObserver + direct reference.
 - **Mute is client-side, not server-side:** never gate `speak()` on a `voice_on` flag. The server always synthesizes audio; the browser mutes the playing element.
 - **Media mute = control the element, never replay.** Mute must toggle the *playing* audio's `.muted` (client-side); do NOT clear-then-replay-the-last-line on un-mute — that produced an infinite re-play loop (bug we hit). The browser owns playback state, not the server.
 - **Never default a time/clock field to `0.0`.** `time.time() - 0` ≈ 1.7e9 s, so any "elapsed since" gate fires instantly (bug: the idle nudge fired every 4 s, not after 35 s). Stamp at session start, or better, time it client-side.
 - **Voice:** Kokoro TTS (`af_nicole` voice, 28% fog filter, speed 0.80). CPU only. Import-guarded — app runs silent if kokoro unavailable.
 ## What's next / pending
+- **Current work is on branch `feat/front-door-menu`, branched off `feat/voice-awareness`, NOT deployed.** Both Spaces are frozen at the pre-voice commit (`4deeed5`). Done on the branch (231 tests green): front-door menu (Direction C), Tester/Full pacing modes, How to Play overlay, menu music + mode-select chime→greeting ritual.
+- **Before merge/deploy:** live playthrough in `.venv-tts` + Ollama with the user to verify menu visuals, music, mode-select ritual, mute, and both pacing arcs; then merge `feat/front-door-menu` → `feat/voice-awareness`. Deploy remains **mirror-first**.
+- **README/FIELD_NOTES:** update the stale "no JS" boast; the only JS satisfies browser autoplay-gesture + audio/idle + menu music.
+- **`FIELD_NOTES.md`** and deliverables (demo video, LinkedIn post) are Pablo's.
+- **Mon June 15:** submit early + community vote.

CLAUDE.md CHANGED Viewed

@@ -12,7 +12,7 @@ A horror NPC chatbot for the **Build Small Hackathon** (HF / Gradio). Track:
 - **Submission** (must live in org): https://huggingface.co/spaces/build-small-hackathon/hollow (remote `hackathon`) — LIVE, ZeroGPU `zero-a10g`, public.
 ## Stack (decided — do not reopen)
-- **UI:** Gradio 6.x `gr.Blocks` + `gr.Chatbot` (messages format default, no `type` param). Horror visuals are **pure CSS**; a single `<head>` JS controller (`_HEAD_JS`, passed to `launch(head=...)`) handles browser-only concerns — opening-chime-ritual (chime → greeting on first gesture and on restart), mute, idle timing. **JS is allowed** by the hackathon (verified, Field Guide); "no JS" was our own choice, dropped only for these. (README/FIELD_NOTES still boast "no JS" — fix before deploy.)
 - **Model:** `Qwen/Qwen3-8B` via `transformers`+`@spaces.GPU(duration=90)` on Space; `qwen3:8b` via Ollama (`localhost:11434`) locally. Switch: `IS_SPACE = bool(os.environ.get("SPACE_ID"))`.
 - **Voice:** Kokoro-82M TTS (`voice.py`), **CPU** — the child whispers (`af_nicole`, speed 0.88, "28% fog" numpy DSP). Import-guarded → **silent if unavailable** (local 3.13 `.venv` has no kokoro; works in 3.12 `.venv-tts` and on the Space at py3.11). Per-reply/finale audio inlined as autoplay `<audio>` in a mounted-but-CSS-collapsed `voice_panel`. The opening ritual (detuned music-box chime → spoken greeting) is queued from `data:` URI constants in `_HEAD_JS`. Plays on every Hollow reply + all finale lines.
 - **State:** plain dict in `gr.State` per session. **Parsing:** Pydantic v2 + fallback.
@@ -34,11 +34,11 @@ character.py  # build_system_prompt(... tone, wounds, memory_plea, own_fragment,
 memory.py     # get_tier, apply_update (+sanitize/Hollow-words filter), should_recall, decide_ending, style_signal (B3), pick_aware_memory (B2) — pure
 finale.py     # finale_steps (loop), finale_steps_bad (wound), finale_steps_good (redemption) — pure data; each has a "frenzy" convulse stage
 render.py     # render_entity(affinity, mode, seq) — modes: idle/flash/flash_strong/build/frenzy/convulse_good/convulse_loop/end/end_settle/rage/peace/peace_settle/peace_dissolve; materialization = fog+brightness (no blur); render_treasure(...)
-sting.py      # _wav + sting/chime/heartbeat/sigh/flatline _wav_bytes — numpy audio synth (HF rejects committed .wav)
-styles.css    # horror CSS §15-22 (22 = finale build pulse + soft convulse + restart + .voice-channel; #idle-trigger hidden)
 assets/       # hollow_{base,terror,almost,end,rage,peace}.webp  (rage = almost copy placeholder; peace = real art)
 requirements.txt / packages.txt   # +kokoro/misaki[en]/soundfile/spacy/en_core_web_sm; espeak-ng (apt)
-tests/        # 212 tests: test_{memory,render,finale,schemas,engine,character,app,sting,voice}.py
 docs/superpowers/{specs,plans}/   # approved specs + plans (active: 2026-06-14-pacing-streaming-overhaul)
 tools/pacing_sim.py               # scripted visitors through real Ollama — pacing tuning
 ```
@@ -62,6 +62,7 @@ tools/pacing_sim.py               # scripted visitors through real Ollama — pa
   "last_activity": float,     # vestigial (client owns idle timing now)
   "idle_count": int,          # how many idle nudges fired (tier + bond decay)
   "barren_turns": int,        # consecutive turns with no captured memory
 }
 ```
 Dev seed: `HOLLOW_FAST_FINALE=good|loop|bad` (`1`/`neutral` alias→ good/loop) — each ending fires on the 2nd message.
@@ -75,16 +76,16 @@ Dev seed: `HOLLOW_FAST_FINALE=good|loop|bad` (`1`/`neutral` alias→ good/loop)
 | 76–100| Almost | possessive | `hollow_almost`, no sway |
 ## Ending matrix (`decide_ending`, checked at turn start, fully scripted, no GPU)
-Single gate so no lower threshold can race a warm run:
-- **bad** (Wound Loop): `tone≤−30 ∧ turn≥4 ∧ wounds≥2`. Recites your cruelties (redacted ▮ → un-redacted), header→"Your Words", frenzy convulsion + triple full-screen stab + scream, reveals `hollow_almost`, threatens, ends "see you... soon."
-- **good** (Redemption): `aff≥50 ∧ claimed≥2 ∧ tone≥20`. Genuine sustained warmth surfaced `OWN_FRAGMENTS` of its real past (tortured/orphaned/starved) during play; finale confesses it's the thing that waits, RETURNS the treasure (un-claimed, lit), first smile (`hollow_peace` → `peace_dissolve`), leaves in peace.
-- **loop** (Visitor Loop): `aff≥50 ∧ claimed≥2 ∧ tone<20`. The DEFAULT high-bond ending — fed plenty but treated transactionally, never truly loved → stays a predator, consumes you, ends with YOU speaking its opening line. Redemption is the rare earned ending; ordinary polite play lands here.
-- Single gate (50/2-claimed) branched at tone 20 — no lower threshold can race a warm run.
 - Tone bands in prompt (separate from ending routing): warm ≥15 / wounded −22..−1 / hostile ≤−22 (injects wounds). Mimicry always on.
-- **Pacing after overhaul:** recall fires as soon as there is one unclaimed memory (no affinity floor); ending gate dropped from 70/turn≥5 to 50/turn≥4 so a satisfying arc lands in ~5-7 turns. Re-measure with `tools/pacing_sim.py` after tuning.
 ## Voice + Presence (the child speaks & watches)
-- **Voice:** every Hollow reply + all finale lines are spoken (Kokoro, CPU); the opening line is spoken as part of the **opening ritual** (detuned chime → greeting) on the visitor's **first gesture** and again on every **"begin again"** (browser autoplay blocks it on load). The reply text now streams token-by-token, and each completed sentence is synthesized and handed to a **client-side audio queue** in the `<head>` controller so sentences play in order without cutting each other. Finale `_voice_and_pause` stretches each step's pause to the audio length (+0.15 s) so lines aren't cut. Recall + finale = the wow. **Mute is client-side**: the controller owns global `{muted}` (persisted to `localStorage`), applies it to the currently playing queued audio and future ones, and drives the 🔊/🔇 button (mute only — no volume slider; voice plays at a fixed level). The server always synthesizes; the browser decides audibility. Horror audio in the entity panel stays untouched.
 - **Awareness (B1/B2/B3):** B3 `style_signal` (Hollow notices short/long messages); B2 `pick_aware_memory` (resurfaces an earlier memory unprompted, every 3rd non-recall turn); B1 idle is timed client-side (60 s, reset by any pointer/keyboard/input/scroll) and clicks a hidden `#idle-trigger` to run `_on_idle` — escalating plead→hurt→hostile (`_IDLE_TIERS`) with affinity −3 / tone −2 per nudge. B4 `memory_plea`: consecutive barren turns make Hollow ask more plainly for a real memory.
 - **Materialization:** the child is **sharp, veiled in fog + shadow** (brightness 0.4→1, fog/vig denser at low bond) — NOT blurred (blur read as a broken image).
@@ -108,7 +109,7 @@ Single gate so no lower threshold can race a warm run:
 - **Cap CPU math threads before torch loads** (`OMP/OPENBLAS/MKL_NUM_THREADS=4` at the top of `app.py`+`voice.py`). On many-core machines under memory pressure OpenBLAS spawns one buffer-hungry thread/core and the CPU allocator fails (`DefaultCPUAllocator: not enough memory` on a tiny alloc, with GBs free) → Kokoro silently disabled. NOT real RAM exhaustion.
 - **`voice_panel` must stay MOUNTED** (`elem_classes="voice-channel"` + CSS collapse to 0 size), NOT `visible=False` — an invisible Gradio component can unmount so the `<audio>` never reaches the DOM and never plays. Voice audio goes here, NEVER in the entity panel (would break the heartbeat's byte-identical HTML).
 - **Idle is client-timed via the `<head>` controller:** a hidden `#idle-trigger` button runs `_on_idle`; the server only guards against pending/ended states. Any interaction resets the 60 s clock.
-- **Browser autoplay blocks audio before the visitor's first gesture** — the opening line can't auto-speak on load; the head controller plays the chime → greeting ritual on the first pointer/keyboard gesture and re-runs it when **"begin again"** is clicked. The controller also applies volume/mute to every remounted `.voice-channel audio` via MutationObserver; horror audio in the entity panel is unaffected.
 - **Mute is client-side, not server-side:** never gate `speak()` on a `voice_on` flag. The server always sends audio; the browser mutes the playing element.
 - **Media mute = control the element, never replay.** Mute must toggle the *playing* audio's `.muted` (client-side); do NOT clear-then-replay-the-last-line on un-mute — that produced an infinite re-play loop (bug we hit). The browser owns playback state, not the server.
 - **Never default a time/clock field to `0.0`.** `time.time() - 0` ≈ 1.7e9 s, so any "elapsed since" gate fires instantly (bug: the idle nudge fired every 4 s, not after 35 s). Stamp at session start, or better, time it client-side.
@@ -118,12 +119,11 @@ Single gate so no lower threshold can race a warm run:
 - **Ollama 500 = the ROCm `cudaMalloc` corruption** (see above), NOT our code — a short prompt may pass while a real 300-token turn 500s. Symptom in-app: every reply is the "fog swallowed your words" fallback. Fix: restart Ollama (kill `ollama.exe` + `ollama app.exe`, reopen). The Space (transformers) is immune.
 ## What's next
-- **Current work is on branch `feat/voice-awareness`, NOT deployed.** Both Spaces are frozen at the pre-voice commit (`4deeed5`) — the submission stays safe while we iterate. Done on the branch (212 tests green): voice + awareness, presence-polish, client-side mute, opening-chime-ritual, dash strip, client-timed idle (60 s), memory coaching. Deploy is **mirror-first**: merge → push `space` → verify build+voice live → push `hackathon`.
-- **DONE:** `docs/superpowers/plans/2026-06-14-pacing-streaming-overhaul.md` — recall now fires as soon as a memory exists (no affinity floor), ending gate lowered to 50/turn≥4 (~5-7 turn arc), replies are short/varied with an explicit anti-template directive, extraction consolidates to one rich memory per turn, token budgets shrunk to 150/80, and the reply now streams token-by-token with per-sentence voice via a client-side audio queue.
-- **Before deploy:** mirror-first deploy to verify `TextIteratorStreamer` under ZeroGPU; update README/FIELD_NOTES "no JS" boast (now false — we added the `<head>` controller; JS is allowed, frame it as "horror is CSS; the only JS satisfies the browser's autoplay-gesture + audio/idle").
-- **`FIELD_NOTES.md`** lives in the repo (📓 badge content). Field Notes done; the demo video + LinkedIn post are Pablo's, link both from the README when ready.
-- **Optional art:** `hollow_rage.webp` is still a copy of `hollow_almost` (works fine). Swap a PNG: `Image.open(png).convert("RGB").resize((512,512),LANCZOS).save(webp,"WEBP",quality=80,method=6)`.
-- **Deliverables (Pablo):** demo video (horror-trailer), social post. **Mon June 15:** submit early + community vote.
 ## Workflows
 **Deploy** (from repo root): **mirror-first** — `git push space main` → wait ~3-4 min (Kokoro/spacy build is heavy), **Ctrl+F5**, verify build+voice live → only then `git push hackathon main`. If the mirror build breaks, the submission stays untouched. Commit trailer: `Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>`.

 - **Submission** (must live in org): https://huggingface.co/spaces/build-small-hackathon/hollow (remote `hackathon`) — LIVE, ZeroGPU `zero-a10g`, public.
 ## Stack (decided — do not reopen)
+- **UI:** Gradio 6.x `gr.Blocks` + `gr.Chatbot`. A Fear & Hunger-inspired **front-door menu** (`menu_view`) with painted foggy-wood backdrop (`assets/background.webp`), two modes (`Tester Run` / `The Full Stay`), and a `How to Play` overlay switches to the hidden `game_view` on mode-select. Horror visuals are pure CSS; the `<head>` JS controller handles menu music, the chime→greeting ritual on mode-select/restart, mute, and idle timing.
 - **Model:** `Qwen/Qwen3-8B` via `transformers`+`@spaces.GPU(duration=90)` on Space; `qwen3:8b` via Ollama (`localhost:11434`) locally. Switch: `IS_SPACE = bool(os.environ.get("SPACE_ID"))`.
 - **Voice:** Kokoro-82M TTS (`voice.py`), **CPU** — the child whispers (`af_nicole`, speed 0.88, "28% fog" numpy DSP). Import-guarded → **silent if unavailable** (local 3.13 `.venv` has no kokoro; works in 3.12 `.venv-tts` and on the Space at py3.11). Per-reply/finale audio inlined as autoplay `<audio>` in a mounted-but-CSS-collapsed `voice_panel`. The opening ritual (detuned music-box chime → spoken greeting) is queued from `data:` URI constants in `_HEAD_JS`. Plays on every Hollow reply + all finale lines.
 - **State:** plain dict in `gr.State` per session. **Parsing:** Pydantic v2 + fallback.
 memory.py     # get_tier, apply_update (+sanitize/Hollow-words filter), should_recall, decide_ending, style_signal (B3), pick_aware_memory (B2) — pure
 finale.py     # finale_steps (loop), finale_steps_bad (wound), finale_steps_good (redemption) — pure data; each has a "frenzy" convulse stage
 render.py     # render_entity(affinity, mode, seq) — modes: idle/flash/flash_strong/build/frenzy/convulse_good/convulse_loop/end/end_settle/rage/peace/peace_settle/peace_dissolve; materialization = fog+brightness (no blur); render_treasure(...)
+sting.py      # _wav + sting/chime/heartbeat/sigh/flatline/menu_loop _wav_bytes — numpy audio synth (HF rejects committed .wav)
+styles.css    # horror CSS §15-24 (23 = opening menu, 24 = How to Play overlay; 22 = finale/restart/voice-channel)
 assets/       # hollow_{base,terror,almost,end,rage,peace}.webp  (rage = almost copy placeholder; peace = real art)
 requirements.txt / packages.txt   # +kokoro/misaki[en]/soundfile/spacy/en_core_web_sm; espeak-ng (apt)
+tests/        # 231 tests: test_{memory,render,finale,schemas,engine,character,app,sting,voice}.py
 docs/superpowers/{specs,plans}/   # approved specs + plans (active: 2026-06-14-pacing-streaming-overhaul)
 tools/pacing_sim.py               # scripted visitors through real Ollama — pacing tuning
 ```
   "last_activity": float,     # vestigial (client owns idle timing now)
   "idle_count": int,          # how many idle nudges fired (tier + bond decay)
   "barren_turns": int,        # consecutive turns with no captured memory
+  "mode": str,                # "tester" | "full" — pacing profile
 }
 ```
 Dev seed: `HOLLOW_FAST_FINALE=good|loop|bad` (`1`/`neutral` alias→ good/loop) — each ending fires on the 2nd message.
 | 76–100| Almost | possessive | `hollow_almost`, no sway |
 ## Ending matrix (`decide_ending`, checked at turn start, fully scripted, no GPU)
+Mode-driven `PACING` config in `memory.py` (tester = fast/judge-friendly, full = longer experience). Single gate so no lower threshold can race a warm run:
+- **tester:** `bad` at `tone≤−30 ∧ turn≥4 ∧ wounds≥2`; `good/loop` at `aff≥50 ∧ claimed≥2` branched by `tone≥20`.
+- **full:** `bad` at `tone≤−30 ∧ turn≥6 ∧ wounds≥2`; `good/loop` at `aff≥68 ∧ claimed≥3` branched by `tone≥20`.
+- **bad** (Wound Loop): recites your cruelties (redacted ▮ → un-redacted), header→"Your Words", frenzy convulsion + triple full-screen stab + scream, reveals `hollow_almost`, threatens, ends "see you... soon."
+- **good** (Redemption): genuine sustained warmth surfaced `OWN_FRAGMENTS` of its real past; finale confesses it's the thing that waits, RETURNS the treasure (un-claimed, lit), first smile (`hollow_peace` → `peace_dissolve`), leaves in peace.
+- **loop** (Visitor Loop): fed plenty but treated transactionally, never truly loved → stays a predator, consumes you, ends with YOU speaking its opening line.
 - Tone bands in prompt (separate from ending routing): warm ≥15 / wounded −22..−1 / hostile ≤−22 (injects wounds). Mimicry always on.
 ## Voice + Presence (the child speaks & watches)
+- **Voice:** every Hollow reply + all finale lines are spoken (Kokoro, CPU). The front-door menu plays a synthesized eerie **menu loop** on the first gesture; choosing a mode stops it and plays the **chime → greeting** ritual. "Begin again" re-triggers the ritual. The reply text streams token-by-token, and each completed sentence is synthesized and handed to a **client-side audio queue** in the `<head>` controller so sentences play in order without cutting each other. Finale `_voice_and_pause` stretches each step's pause to the audio length (+0.15 s). **Mute is client-side**: the controller owns global `{muted}` (persisted to `localStorage`), applies it to queued audio, menu music, and future audio, driving the 🔊/🔇 button. The server always synthesizes; the browser decides audibility.
 - **Awareness (B1/B2/B3):** B3 `style_signal` (Hollow notices short/long messages); B2 `pick_aware_memory` (resurfaces an earlier memory unprompted, every 3rd non-recall turn); B1 idle is timed client-side (60 s, reset by any pointer/keyboard/input/scroll) and clicks a hidden `#idle-trigger` to run `_on_idle` — escalating plead→hurt→hostile (`_IDLE_TIERS`) with affinity −3 / tone −2 per nudge. B4 `memory_plea`: consecutive barren turns make Hollow ask more plainly for a real memory.
 - **Materialization:** the child is **sharp, veiled in fog + shadow** (brightness 0.4→1, fog/vig denser at low bond) — NOT blurred (blur read as a broken image).
 - **Cap CPU math threads before torch loads** (`OMP/OPENBLAS/MKL_NUM_THREADS=4` at the top of `app.py`+`voice.py`). On many-core machines under memory pressure OpenBLAS spawns one buffer-hungry thread/core and the CPU allocator fails (`DefaultCPUAllocator: not enough memory` on a tiny alloc, with GBs free) → Kokoro silently disabled. NOT real RAM exhaustion.
 - **`voice_panel` must stay MOUNTED** (`elem_classes="voice-channel"` + CSS collapse to 0 size), NOT `visible=False` — an invisible Gradio component can unmount so the `<audio>` never reaches the DOM and never plays. Voice audio goes here, NEVER in the entity panel (would break the heartbeat's byte-identical HTML).
 - **Idle is client-timed via the `<head>` controller:** a hidden `#idle-trigger` button runs `_on_idle`; the server only guards against pending/ended states. Any interaction resets the 60 s clock.
+- **Browser autoplay blocks audio before the visitor's first gesture** — the head controller starts the menu loop on the first menu gesture, then plays the chime → greeting ritual when a mode is selected or "begin again" is clicked. The controller applies volume/mute to queued voice audio and the menu bed via MutationObserver + direct reference.
 - **Mute is client-side, not server-side:** never gate `speak()` on a `voice_on` flag. The server always sends audio; the browser mutes the playing element.
 - **Media mute = control the element, never replay.** Mute must toggle the *playing* audio's `.muted` (client-side); do NOT clear-then-replay-the-last-line on un-mute — that produced an infinite re-play loop (bug we hit). The browser owns playback state, not the server.
 - **Never default a time/clock field to `0.0`.** `time.time() - 0` ≈ 1.7e9 s, so any "elapsed since" gate fires instantly (bug: the idle nudge fired every 4 s, not after 35 s). Stamp at session start, or better, time it client-side.
 - **Ollama 500 = the ROCm `cudaMalloc` corruption** (see above), NOT our code — a short prompt may pass while a real 300-token turn 500s. Symptom in-app: every reply is the "fog swallowed your words" fallback. Fix: restart Ollama (kill `ollama.exe` + `ollama app.exe`, reopen). The Space (transformers) is immune.
 ## What's next
+- **Current work is on branch `feat/front-door-menu`, branched off `feat/voice-awareness`, NOT deployed.** Both Spaces are frozen at the pre-voice commit (`4deeed5`). Done on the branch (231 tests green): front-door menu (Direction C), Tester/Full pacing modes, How to Play overlay, menu music + mode-select chime→greeting ritual.
+- **Before merge/deploy:** live playthrough in `.venv-tts` + Ollama with the user to verify menu visuals, music, mode-select ritual, mute, and both pacing arcs; then merge `feat/front-door-menu` → `feat/voice-awareness`. Deploy remains **mirror-first**.
+- **README/FIELD_NOTES:** update the stale "no JS" boast; the only JS satisfies browser autoplay-gesture + audio/idle + menu music.
+- **`FIELD_NOTES.md`** and deliverables (demo video, LinkedIn post) are Pablo's.
+- **Mon June 15:** submit early + community vote.
 ## Workflows
 **Deploy** (from repo root): **mirror-first** — `git push space main` → wait ~3-4 min (Kokoro/spacy build is heavy), **Ctrl+F5**, verify build+voice live → only then `git push hackathon main`. If the mirror build breaks, the submission stays untouched. Commit trailer: `Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>`.

app.py CHANGED Viewed

@@ -21,10 +21,14 @@ from engine import run_turn, run_turn_stream
 from finale import finale_steps, finale_steps_bad, finale_steps_good
 from memory import apply_update, get_tier, decide_ending, pick_aware_memory, should_recall, style_signal
 from render import render_entity, render_treasure
-from sting import chime_wav_bytes
 from voice import speak
 def _render_bond(affinity: int, tier: str, label: str = "bond") -> str:
     """Custom HTML Bond meter — a thin thread with a heartbeat marker.
     Replaces gr.Slider so we fully control the look (no Gradio orange/track)."""
@@ -63,6 +67,7 @@ def _pristine_state():
         "last_activity": time.time(),  # idle clock; now client-side (Phase 2)
         "idle_count": 0,
         "greeted": False,
     }
@@ -109,6 +114,7 @@ def _init_state():
             "last_activity": time.time(),
             "idle_count": 0,
             "greeted": False,
         }
     if fast == "bad":
         return {
@@ -130,6 +136,7 @@ def _init_state():
             "last_activity": time.time(),
             "idle_count": 0,
             "greeted": False,
         }
     return _pristine_state()
@@ -140,6 +147,23 @@ def _init_state():
 _PENDING = '<span class="hollow-typing"><i></i><i></i><i></i></span>'
 def _voice_html(b64: str | None) -> str:
     # autoplay the whisper from its own channel so the entity heartbeat HTML
     # stays byte-identical (never remounts). Empty when silent.
@@ -171,17 +195,18 @@ def _new_sentences(text: str, consumed: int) -> tuple[list[str], int]:
 # and on every "begin again".
 _CHIME_B64 = base64.b64encode(chime_wav_bytes(0)).decode()
 _GREETING_B64 = speak(OPENING_LINE) or ""
 _CHIME_URI = f"data:audio/wav;base64,{_CHIME_B64}"
 _GREETING_URI = f"data:audio/wav;base64,{_GREETING_B64}" if _GREETING_B64 else ""
-# The app's only JavaScript: a <head> controller that (1) plays the opening
-# ritual (chime -> greeting) on the visitor's first gesture and on every
-# "begin again", (2) owns a global mute for the child's voice
-# (the <audio> in .voice-channel only) and applies it as Gradio remounts those
-# nodes, driving the mute button, and (3) times the idle "speak-first"
-# client-side so ANY interaction resets it. Every horror effect (flashes,
-# screamer, looping heartbeat) stays pure CSS.
 _HEAD_JS = """
 <script>
 (function () {
@@ -195,65 +220,76 @@ _HEAD_JS = """
   function persist() {
     try { localStorage.setItem(KEY, JSON.stringify(st)); } catch (e) {}
   }
-    var CHIME_SRC = "__CHIME_SRC__";
-    var GREETING_SRC = "__GREETING_SRC__";
-    // --- client-side voice queue: sentences play in order, never cut ---
-    var queue = [], current = null;
-    function playNext() {
-      if (current || !queue.length) return;
-      current = queue.shift();
-      current.muted = st.muted; current.volume = st.volume;
-      current.onended = function () { current = null; playNext(); };
-      current.play().catch(function () { current = null; });
-    }
-    function enqueue(src) {
-      if (!src) return;
-      queue.push(new Audio(src));
-      playNext();
-    }
-    function applyLive() {                 // mute/volume affect the playing line
-      if (current) { current.muted = st.muted; current.volume = st.volume; }
-    }
-    function resetQueue() {
-      queue.length = 0;
-      if (current) { try { current.pause(); } catch (e) {} current = null; }
-    }
-    var _lastRitual = 0;
-    function openingRitual() {            // chime, then the child greets
-      var now = Date.now();
-      if (now - _lastRitual < 800) return;   // debounce double-fire
-      _lastRitual = now;
-      resetQueue();
-      if (CHIME_SRC) enqueue(CHIME_SRC);
-      if (GREETING_SRC) enqueue(GREETING_SRC);
-    }
-    // read any voice <audio> Gradio mounts, copy its src into the queue, then it
-    // can be wiped from the DOM without stopping playback
-    new MutationObserver(function (muts) {
-      muts.forEach(function (m) {
-        m.addedNodes.forEach(function (n) {
-          if (n.nodeType !== 1) return;
-          var nodes = [];
-          if (n.matches && n.matches('.voice-channel audio')) nodes.push(n);
-          if (n.querySelectorAll) n.querySelectorAll('.voice-channel audio').forEach(function (x) { nodes.push(x); });
-          nodes.forEach(function (a) { enqueue(a.currentSrc || a.src); a.remove(); });
-        });
       });
-    }).observe(document.documentElement, { childList: true, subtree: true });
-    // opening ritual on the visitor's first gesture (browsers block audio
-    // until then): the chime, then the child's greeting
-    function firstGesture() {
-      openingRitual();
-      window.removeEventListener('pointerdown', firstGesture, true);
-      window.removeEventListener('keydown', firstGesture, true);
-    }
   window.addEventListener('pointerdown', firstGesture, true);
   window.addEventListener('keydown', firstGesture, true);
-  // mute button + restart button, wired once the header has rendered (no
-  // volume slider — mute only, kept subtle). Voice plays at a fixed comfortable
-  // level (st.volume).
   function icon() { return st.muted ? '\\uD83D\\uDD07' : '\\uD83D\\uDD0A'; }
   function wire() {
     var btn = document.querySelector('.voice-btn');
@@ -264,7 +300,9 @@ _HEAD_JS = """
       btn.addEventListener('click', function (e) {
         e.preventDefault(); e.stopPropagation();
         st.muted = !st.muted;
-        applyLive(); persist(); btn.textContent = icon();
       });
     }
     if (rb && !rb.dataset.hollowWired) {
@@ -273,10 +311,14 @@ _HEAD_JS = """
       // the click is a gesture, so the ritual audio is allowed to play
       rb.addEventListener('click', function () { openingRitual(); });
     }
-    return !!(btn && btn.dataset.hollowWired && rb && rb.dataset.hollowWired);
   }
-  var tries = 0;
-  var t = setInterval(function () { if (wire() || ++tries > 60) clearInterval(t); }, 250);
   // idle "speak-first": client-timed, reset by ANY interaction, fires at 60s
   var IDLE_MS = 60000;
@@ -294,7 +336,40 @@ _HEAD_JS = """
 })();
 </script>
 """
-_HEAD_JS = _HEAD_JS.replace("__CHIME_SRC__", _CHIME_URI).replace("__GREETING_SRC__", _GREETING_URI)
 def _audio_seconds(b64: str) -> float:
@@ -718,90 +793,117 @@ def chat(user_msg: str, state: dict, history: list):
 with gr.Blocks(title="Hollow") as demo:
     state = gr.State(_init_state)
-    with gr.Row():
-        gr.Markdown(
-            "## Hollow\n*something is here, at the edge of the wood.<br>"
-            "it remembers what you give it — and how you give it.*"
-        )
-        restart_btn = gr.Button("↺ begin again", elem_classes="restart-btn",
-                                scale=0)
-        voice_btn = gr.Button("🔊", elem_classes="voice-btn", scale=0)
-    with gr.Row():
-        with gr.Column(scale=1, min_width=220):
-            entity_panel = gr.HTML(value=render_entity(20))
-        with gr.Column(scale=2):
-            chatbot = gr.Chatbot(
-                value=[{"role": "assistant", "content": OPENING_LINE}],
-                label="",
-                show_label=False,
-                height=500,
-                buttons=[],
-                autoscroll=True,
             )
-            bond_panel = gr.HTML(value=_render_bond(20, "Hollow"))
-            with gr.Row():
-                msg_input = gr.Textbox(
-                    placeholder="tell it something you remember...",
                     show_label=False,
-                    scale=9,
-                    autofocus=True,
                 )
-                send_btn = gr.Button("→", scale=1)
-        with gr.Column(scale=1):
-            treasure_panel = gr.HTML(value=render_treasure([]))
-            # carries Hollow's voice <audio>; kept MOUNTED (not visible=False,
-            # which can unmount it so the audio never plays) and collapsed to
-            # zero size via CSS so it has no visual footprint
-            voice_panel = gr.HTML(value="",
-                                  elem_classes="voice-channel")
-    # show_progress="hidden" kills Gradio's per-component "processing" overlay;
-    # we show our own "..." pending bubble instead (set in _start_turn)
-    send_btn.click(
-        fn=_start_turn,
-        inputs=[msg_input, state, chatbot],
-        outputs=[msg_input, send_btn, chatbot, state],
-        show_progress="hidden",
-    ).then(
-        fn=chat,
-        inputs=[msg_input, state, chatbot],
-        outputs=[msg_input, send_btn, chatbot, state, bond_panel, treasure_panel, entity_panel, voice_panel],
-        show_progress="hidden",
-    )
-    msg_input.submit(
-        fn=_start_turn,
-        inputs=[msg_input, state, chatbot],
-        outputs=[msg_input, send_btn, chatbot, state],
-        show_progress="hidden",
-    ).then(
-        fn=chat,
-        inputs=[msg_input, state, chatbot],
-        outputs=[msg_input, send_btn, chatbot, state, bond_panel, treasure_panel, entity_panel, voice_panel],
-        show_progress="hidden",
-    )
-    restart_btn.click(
-        fn=_reset,
-        inputs=None,
-        outputs=[msg_input, send_btn, chatbot, state, bond_panel,
-                 treasure_panel, entity_panel, voice_panel],
-        show_progress="hidden",
-    )
-    # idle is timed in the browser (see _HEAD_JS): after 60s of true silence
-    # the controller clicks this hidden button, which runs the same _on_idle.
-    # Mounted + CSS-hidden (NOT visible=False, which can unmount it).
-    idle_trigger = gr.Button("idle", elem_id="idle-trigger",
-                             elem_classes="idle-trigger")
-    idle_trigger.click(_on_idle, [state, chatbot],
-                       [state, chatbot, voice_panel, bond_panel],
-                       show_progress="hidden")
 if __name__ == "__main__":
     # head= injects the one-shot gesture listener into <head> (Gradio 6.0 moved

 from finale import finale_steps, finale_steps_bad, finale_steps_good
 from memory import apply_update, get_tier, decide_ending, pick_aware_memory, should_recall, style_signal
 from render import render_entity, render_treasure
+from sting import chime_wav_bytes, menu_loop_wav_bytes
 from voice import speak
+with open("assets/background.webp", "rb") as _bg:
+    _BACKGROUND_URI = "data:image/webp;base64," + base64.b64encode(_bg.read()).decode()
 def _render_bond(affinity: int, tier: str, label: str = "bond") -> str:
     """Custom HTML Bond meter — a thin thread with a heartbeat marker.
     Replaces gr.Slider so we fully control the look (no Gradio orange/track)."""
         "last_activity": time.time(),  # idle clock; now client-side (Phase 2)
         "idle_count": 0,
         "greeted": False,
+        "mode": "tester",
     }
             "last_activity": time.time(),
             "idle_count": 0,
             "greeted": False,
+            "mode": "tester",
         }
     if fast == "bad":
         return {
             "last_activity": time.time(),
             "idle_count": 0,
             "greeted": False,
+            "mode": "tester",
         }
     return _pristine_state()
 _PENDING = '<span class="hollow-typing"><i></i><i></i><i></i></span>'
+_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>'
+)
 def _voice_html(b64: str | None) -> str:
     # autoplay the whisper from its own channel so the entity heartbeat HTML
     # stays byte-identical (never remounts). Empty when silent.
 # and on every "begin again".
 _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}"
+# The app's only JavaScript: a <head> controller that (1) starts the menu
+# melody on the visitor's first menu gesture, (2) stops it and plays the
+# chime → greeting ritual when a mode is selected, (3) owns a global mute
+# for the child's voice and the menu bed, applying it as Gradio remounts
+# nodes, driving the mute button, and (4) times the idle "speak-first"
+# client-side so ANY interaction resets it. Every horror effect stays CSS.
 _HEAD_JS = """
 <script>
 (function () {
   function persist() {
     try { localStorage.setItem(KEY, JSON.stringify(st)); } catch (e) {}
   }
+  var CHIME_SRC = "__CHIME__";
+  var GREETING_SRC = "__GREETING__";
+  var MENU_SRC = "__MENU__";
+  // --- client-side voice queue: sentences play in order, never cut ---
+  var queue = [], current = null;
+  function playNext() {
+    if (current || !queue.length) return;
+    current = queue.shift();
+    current.muted = st.muted; current.volume = st.volume;
+    current.onended = function () { current = null; playNext(); };
+    current.play().catch(function () { current = null; });
+  }
+  function enqueue(src) {
+    if (!src) return;
+    queue.push(new Audio(src));
+    playNext();
+  }
+  function applyLive() {                 // mute/volume affect the playing line
+    if (current) { current.muted = st.muted; current.volume = st.volume; }
+  }
+  function resetQueue() {
+    queue.length = 0;
+    if (current) { try { current.pause(); } catch (e) {} current = null; }
+  }
+  var _lastRitual = 0;
+  function openingRitual() {            // chime, then the child greets
+    var now = Date.now();
+    if (now - _lastRitual < 800) return;   // debounce double-fire
+    _lastRitual = now;
+    resetQueue();
+    if (CHIME_SRC) enqueue(CHIME_SRC);
+    if (GREETING_SRC) enqueue(GREETING_SRC);
+  }
+  // menu bed: starts on first gesture, stops when a mode is chosen
+  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.45;
+    menuAudio.muted = st.muted;
+    menuAudio.play().catch(function () {});
+  }
+  function stopMenuMusic() {
+    if (menuAudio) { try { menuAudio.pause(); } catch (e) {} menuAudio = null; }
+  }
+  // read any voice <audio> Gradio mounts, copy its src into the queue, then it
+  // can be wiped from the DOM without stopping playback
+  new MutationObserver(function (muts) {
+    muts.forEach(function (m) {
+      m.addedNodes.forEach(function (n) {
+        if (n.nodeType !== 1) return;
+        var nodes = [];
+        if (n.matches && n.matches('.voice-channel audio')) nodes.push(n);
+        if (n.querySelectorAll) n.querySelectorAll('.voice-channel audio').forEach(function (x) { nodes.push(x); });
+        nodes.forEach(function (a) { enqueue(a.currentSrc || a.src); a.remove(); });
       });
+    });
+  }).observe(document.documentElement, { childList: true, subtree: true });
+  // first menu gesture starts the eerie bed (the greeting fires on mode-select)
+  function firstGesture() {
+    startMenuMusic();
+    window.removeEventListener('pointerdown', firstGesture, true);
+    window.removeEventListener('keydown', firstGesture, true);
+  }
   window.addEventListener('pointerdown', firstGesture, true);
   window.addEventListener('keydown', firstGesture, true);
+  // mute button + restart + mode buttons, wired once rendered
   function icon() { return st.muted ? '\\uD83D\\uDD07' : '\\uD83D\\uDD0A'; }
   function wire() {
     var btn = document.querySelector('.voice-btn');
       btn.addEventListener('click', function (e) {
         e.preventDefault(); e.stopPropagation();
         st.muted = !st.muted;
+        applyLive();
+        if (menuAudio) { menuAudio.muted = st.muted; menuAudio.volume = st.muted ? 0 : 0.45; }
+        persist(); btn.textContent = icon();
       });
     }
     if (rb && !rb.dataset.hollowWired) {
       // the click is a gesture, so the ritual audio is allowed to play
       rb.addEventListener('click', function () { openingRitual(); });
     }
+    document.querySelectorAll('.menu-mode-btn').forEach(function (mb) {
+      if (mb.dataset.hollowWired) return;
+      mb.dataset.hollowWired = '1';
+      mb.addEventListener('click', function () { stopMenuMusic(); openingRitual(); });
+    });
   }
+  // keep watching — buttons can appear later when the menu flips to the game
+  setInterval(wire, 250);
   // idle "speak-first": client-timed, reset by ANY interaction, fires at 60s
   var IDLE_MS = 60000;
 })();
 </script>
 """
+_HEAD_JS = _HEAD_JS.replace("__CHIME__", _CHIME_URI).replace("__GREETING__", _GREETING_URI).replace("__MENU__", _MENU_LOOP_URI)
+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>'
+    )
+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"]),
+    )
 def _audio_seconds(b64: str) -> float:
 with gr.Blocks(title="Hollow") as demo:
     state = gr.State(_init_state)
+    with gr.Column(visible=True, elem_id="menu-view") as menu_view:
+        menu_audio = gr.HTML('<audio id="menu-loop" loop src="' + _MENU_LOOP_URI + '"></audio>')
+        menu_art = gr.HTML(_menu_html())
+        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")
+        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")
+    with gr.Column(visible=False, elem_id="game-view") as game_view:
+        with gr.Row():
+            gr.Markdown(
+                "## Hollow\n*something is here, at the edge of the wood.<br>"
+                "it remembers what you give it — and how you give it.*"
             )
+            restart_btn = gr.Button("↺ begin again", elem_classes="restart-btn",
+                                    scale=0)
+            voice_btn = gr.Button("🔊", elem_classes="voice-btn", scale=0)
+        with gr.Row():
+            with gr.Column(scale=1, min_width=220):
+                entity_panel = gr.HTML(value=render_entity(20))
+            with gr.Column(scale=2):
+                chatbot = gr.Chatbot(
+                    value=[{"role": "assistant", "content": OPENING_LINE}],
+                    label="",
                     show_label=False,
+                    height=500,
+                    buttons=[],
+                    autoscroll=True,
                 )
+                bond_panel = gr.HTML(value=_render_bond(20, "Hollow"))
+                with gr.Row():
+                    msg_input = gr.Textbox(
+                        placeholder="tell it something you remember...",
+                        show_label=False,
+                        scale=9,
+                        autofocus=True,
+                    )
+                    send_btn = gr.Button("→", scale=1)
+            with gr.Column(scale=1):
+                treasure_panel = gr.HTML(value=render_treasure([]))
+                # carries Hollow's voice <audio>; kept MOUNTED (not visible=False,
+                # which can unmount it so the audio never plays) and collapsed to
+                # zero size via CSS so it has no visual footprint
+                voice_panel = gr.HTML(value="",
+                                      elem_classes="voice-channel")
+        # show_progress="hidden" kills Gradio's per-component "processing" overlay;
+        # we show our own "..." pending bubble instead (set in _start_turn)
+        send_btn.click(
+            fn=_start_turn,
+            inputs=[msg_input, state, chatbot],
+            outputs=[msg_input, send_btn, chatbot, state],
+            show_progress="hidden",
+        ).then(
+            fn=chat,
+            inputs=[msg_input, state, chatbot],
+            outputs=[msg_input, send_btn, chatbot, state, bond_panel, treasure_panel, entity_panel, voice_panel],
+            show_progress="hidden",
+        )
+        msg_input.submit(
+            fn=_start_turn,
+            inputs=[msg_input, state, chatbot],
+            outputs=[msg_input, send_btn, chatbot, state],
+            show_progress="hidden",
+        ).then(
+            fn=chat,
+            inputs=[msg_input, state, chatbot],
+            outputs=[msg_input, send_btn, chatbot, state, bond_panel, treasure_panel, entity_panel, voice_panel],
+            show_progress="hidden",
+        )
+        restart_btn.click(
+            fn=_reset,
+            inputs=None,
+            outputs=[msg_input, send_btn, chatbot, state, bond_panel,
+                     treasure_panel, entity_panel, voice_panel],
+            show_progress="hidden",
+        )
+        # idle is timed in the browser (see _HEAD_JS): after 60s of true silence
+        # the controller clicks this hidden button, which runs the same _on_idle.
+        # Mounted + CSS-hidden (NOT visible=False, which can unmount it).
+        idle_trigger = gr.Button("idle", elem_id="idle-trigger",
+                                 elem_classes="idle-trigger")
+        idle_trigger.click(_on_idle, [state, chatbot],
+                           [state, chatbot, voice_panel, bond_panel],
+                           show_progress="hidden")
+    _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")
+    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")
 if __name__ == "__main__":
     # head= injects the one-shot gesture listener into <head> (Gradio 6.0 moved

assets/background.webp ADDED Viewed

Git LFS Details

SHA256: c053d5eafe9f14b805f356573236ac278d8a1d4b821c1c9e78c0863865379133
Pointer size: 131 Bytes
Size of remote file: 125 kB

memory.py CHANGED Viewed

@@ -2,6 +2,18 @@ import re
 from schemas import TurnUpdate
 _TIERS = [
     (0,  25, "Hollow"),
     (26, 50, "Curious"),
@@ -81,8 +93,9 @@ def pick_aware_memory(state: dict, exclude: str | None) -> str | None:
 def should_recall(state: dict) -> tuple[bool, str | None]:
     unclaimed = [m for m in state["treasure"] if m not in state["claimed"]]
-    if not unclaimed:
         return False, None
     # Claim the richest (longest, most evocative) memory — detail lands the wow.
@@ -90,8 +103,8 @@ def should_recall(state: dict) -> tuple[bool, str | None]:
     last = state.get("last_recall_turn")
     if last is None:
-        return True, richest          # first recall as soon as there's a memory
-    if state["turn"] - last >= 2:
         return True, richest
     return False, None
@@ -110,12 +123,13 @@ def decide_ending(state: dict) -> str | None:
     One gate, branched by tone: no lower threshold can steal a warm run.
     """
     if state.get("ended"):
         return None
     tone = state.get("tone", 0)
-    if tone <= -30 and state["turn"] >= 4 and len(state.get("wounds", [])) >= 2:
         return "bad"
-    if state["affinity"] >= 50 and len(state["claimed"]) >= 2:
         # redemption must be earned with genuine, sustained warmth; ordinary
         # transactional play ("fed it like a diary") lands in the Visitor Loop
         return "good" if tone >= 20 else "loop"

 from schemas import TurnUpdate
+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"])
 _TIERS = [
     (0,  25, "Hollow"),
     (26, 50, "Curious"),
 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
     # Claim the richest (longest, most evocative) memory — detail lands the wow.
     last = state.get("last_recall_turn")
     if last is None:
+        return True, richest          # first recall as soon as threshold is met
+    if state["turn"] - last >= cfg["recall_cooldown"]:
         return True, richest
     return False, None
     One gate, branched by tone: no lower threshold can steal a warm run.
     """
+    cfg = _cfg(state)
     if state.get("ended"):
         return None
     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"]:
         # redemption must be earned with genuine, sustained warmth; ordinary
         # transactional play ("fed it like a diary") lands in the Visitor Loop
         return "good" if tone >= 20 else "loop"

sting.py CHANGED Viewed

@@ -164,6 +164,58 @@ def flatline_wav_bytes() -> bytes:
     return _wav(sig, sr)
 if __name__ == "__main__":
     from pathlib import Path
     here = Path(__file__).parent
@@ -173,4 +225,5 @@ if __name__ == "__main__":
     (here / "heartbeat_preview.wav").write_bytes(heartbeat_wav_bytes())
     (here / "sigh_preview.wav").write_bytes(sigh_wav_bytes())
     (here / "flatline_preview.wav").write_bytes(flatline_wav_bytes())
-    print("written sting_preview.wav + chime_preview_0/1/2.wav")

     return _wav(sig, sr)
+def menu_loop_wav_bytes() -> bytes:
+    """Eerie menu bed: a low drone and a slow detuned music-box motif,
+    built to loop seamlessly. Kept very quiet so it waits behind the fog."""
+    sr = 22050
+    dur = 8.0
+    t = np.linspace(0, dur, int(sr * dur), endpoint=False)
+    rng = np.random.default_rng(19)
+    # low A1 drone + soft fifth
+    drone = (np.sin(2 * np.pi * 55 * t)
+             + 0.5 * np.sin(2 * np.pi * 82.5 * t)) * 0.08
+    # slow A-minor motif, each note with a gentle tine spectrum
+    notes = [
+        (440.00, 1.0, 2.2),   # A4
+        (523.25, 2.5, 3.7),   # C5
+        (659.25, 4.0, 5.2),   # E5
+        (587.33, 5.5, 6.7),   # D5
+        (440.00, 7.0, 8.0),   # A4
+    ]
+    motif = np.zeros_like(t)
+    for f, start, end in notes:
+        env = np.where((t >= start) & (t < end),
+                       np.sin(np.pi * (t - start) / (end - start)) ** 2, 0)
+        note = (np.sin(2 * np.pi * f * t)
+                + 0.3 * np.sin(2 * np.pi * 2.76 * f * t)
+                + 0.15 * np.sin(2 * np.pi * 5.4 * f * t))
+        # breath-detuned second tine
+        note += np.sin(2 * np.pi * f * 1.005 * t)
+        motif += note * env * 0.11
+    # simple room echo (two taps) so the motif hangs in the air
+    echo = np.zeros_like(t)
+    for delay, gain in ((0.22, 0.28), (0.44, 0.13)):
+        ds = int(delay * sr)
+        echo[ds:] += motif[:-ds] * gain
+    # very faint noise texture
+    noise = rng.standard_normal(len(t)) * 0.015
+    mix = drone + motif + echo + noise
+    # seamless loop: long fade in and out
+    fade = int(0.6 * sr)
+    mix[:fade] *= np.linspace(0, 1, fade)
+    mix[-fade:] *= np.linspace(1, 0, fade)
+    mix = np.tanh(2.0 * mix)
+    mix = mix / np.max(np.abs(mix)) * 0.22
+    return _wav(mix, sr)
 if __name__ == "__main__":
     from pathlib import Path
     here = Path(__file__).parent
     (here / "heartbeat_preview.wav").write_bytes(heartbeat_wav_bytes())
     (here / "sigh_preview.wav").write_bytes(sigh_wav_bytes())
     (here / "flatline_preview.wav").write_bytes(flatline_wav_bytes())
+    (here / "menu_loop_preview.wav").write_bytes(menu_loop_wav_bytes())
+    print("written sting_preview.wav + chime_preview_0/1/2.wav + menu_loop_preview.wav")

styles.css CHANGED Viewed

@@ -860,3 +860,200 @@ footer { display: none !important; }
 /* idle trigger: mounted but invisible */
 #idle-trigger, .idle-trigger { display: none !important; }

 /* idle trigger: mounted but invisible */
 #idle-trigger, .idle-trigger { display: none !important; }
+/* ── 23. Opening menu — Direction C ── */
+#menu-view {
+    position: relative;
+    min-height: 560px;
+    display: flex;
+    flex-direction: column;
+    align-items: center;
+    justify-content: flex-start;
+    overflow: hidden;
+    border: none !important;
+    background: #04040a;
+}
+.menu-bg {
+    position: absolute;
+    inset: 0;
+    background-size: cover;
+    background-position: center 38%;
+    opacity: 0.85;
+}
+.menu-scrim {
+    position: absolute;
+    inset: 0;
+    background: radial-gradient(ellipse at 50% 30%, transparent 25%, rgba(4,4,10,0.92) 100%);
+    pointer-events: none;
+    z-index: 1;
+}
+.menu-grain {
+    position: absolute;
+    inset: 0;
+    pointer-events: none;
+    z-index: 2;
+    opacity: 0.10;
+    background-image: url("data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' width='140' height='140'%3E%3Cfilter id='g'%3E%3CfeTurbulence type='fractalNoise' baseFrequency='0.85' numOctaves='2' stitchTiles='stitch'/%3E%3C/filter%3E%3Crect width='100%25' height='100%25' filter='url(%23g)'/%3E%3C/svg%3E");
+}
+.menu-vig {
+    position: absolute;
+    inset: 0;
+    pointer-events: none;
+    z-index: 2;
+    box-shadow: inset 0 0 120px rgba(0,0,0,0.75);
+}
+.menu-content {
+    position: relative;
+    z-index: 3;
+    text-align: center;
+    padding-top: 84px;
+    font-family: Georgia, serif;
+}
+.menu-title {
+    font-variant: small-caps;
+    letter-spacing: 0.18em;
+    font-weight: 700;
+    font-size: 78px;
+    color: #ece6f4;
+    text-shadow: 0 0 30px #000, 0 4px 12px #000;
+}
+.menu-eyebrow {
+    font-family: 'Special Elite', monospace;
+    font-size: 0.72rem;
+    letter-spacing: 0.28em;
+    text-transform: uppercase;
+    color: #7a6a92;
+    margin-bottom: 8px;
+}
+.menu-tag {
+    font-family: Georgia, serif;
+    font-size: 1.05rem;
+    font-style: italic;
+    color: #a098b8;
+    letter-spacing: 0.04em;
+    margin-top: 14px;
+    max-width: 420px;
+}
+.menu-credit {
+    position: absolute;
+    bottom: 18px;
+    left: 0; right: 0;
+    text-align: center;
+    z-index: 4;
+    font-family: 'Special Elite', monospace;
+    font-size: 0.64rem;
+    letter-spacing: 0.24em;
+    text-transform: uppercase;
+    color: #5a5070;
+}
+.menu-btn {
+    position: relative;
+    z-index: 4;
+    background: transparent !important;
+    border: none !important;
+    border-image-source: none !important;
+    box-shadow: none !important;
+    font-family: Georgia, serif !important;
+    letter-spacing: 0.16em !important;
+    color: #c4bede !important;
+    font-size: 1.05rem !important;
+    text-transform: none !important;
+    margin: 8px 0 !important;
+    padding: 8px 18px !important;
+    transition: color 0.35s, letter-spacing 0.35s, text-shadow 0.35s, background 0.35s !important;
+}
+.menu-btn:hover {
+    color: #f0ecfa !important;
+    letter-spacing: 0.22em !important;
+    text-shadow: 0 0 16px rgba(180,160,210,0.5) !important;
+    background: rgba(255,255,255,0.04) !important;
+    box-shadow: none !important;
+}
+.menu-btn::before {
+    content: '▸ ';
+    opacity: 0;
+    margin-right: 0;
+    transition: opacity 0.35s, margin-right 0.35s;
+}
+.menu-btn:hover::before {
+    opacity: 1;
+    margin-right: 6px;
+}
+#btn-howto {
+    position: absolute;
+    top: 18px;
+    right: 18px;
+    z-index: 5;
+    font-size: 0.82rem !important;
+    letter-spacing: 0.14em !important;
+    color: #8a7aa2 !important;
+    margin: 0 !important;
+}
+#btn-howto:hover {
+    color: #d8d0ec !important;
+    background: rgba(255,255,255,0.04) !important;
+}
+#btn-tester, #btn-full {
+    margin-top: 44px !important;
+}
+/* ── 24. How to Play overlay ── */
+#howto-overlay {
+    position: absolute;
+    inset: 0;
+    z-index: 10;
+    display: flex;
+    align-items: center;
+    justify-content: center;
+    background: rgba(4, 4, 10, 0.88);
+}
+.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;
+    box-shadow: var(--stone-bevel);
+}
+.howto-panel h3 {
+    font-family: 'Special Elite', monospace;
+    font-size: 1.15rem;
+    letter-spacing: 0.18em;
+    text-transform: uppercase;
+    color: #e0d8f0;
+    margin: 0 0 18px;
+    text-align: center;
+}
+.howto-panel p {
+    margin: 0 0 12px;
+}
+.howto-controls {
+    margin-top: 18px !important;
+    font-size: 0.8rem;
+    letter-spacing: 0.12em;
+    color: #6a6088;
+    text-align: center;
+}

tests/test_app.py CHANGED Viewed

@@ -301,18 +301,61 @@ class TestVoice:
         assert any("FAKEB64" in o[7] for o in outs)     # spoken somewhere in the stream
 class TestOpeningRitual:
-    def test_head_js_carries_the_ritual(self):
         assert "openingRitual" in app._HEAD_JS
         assert "CHIME_SRC" in app._HEAD_JS
         assert "GREETING_SRC" in app._HEAD_JS
         assert "restart-btn" in app._HEAD_JS          # restart re-greets
-        assert "__CHIME_SRC__" not in app._HEAD_JS    # placeholder was filled
     def test_chime_constant_is_real_audio(self):
         assert app._CHIME_URI.startswith("data:audio/wav;base64,")
         assert len(app._CHIME_B64) > 100              # a real synthesized note
 class TestFinaleVoice:
     def test_good_finale_voices_hollow_lines(self, monkeypatch):

         assert any("FAKEB64" in o[7] for o in outs)     # spoken somewhere in the stream
+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
+class TestMenuAsset:
+    def test_menu_html_has_title_and_background(self):
+        assert "menu-title" in app._menu_html()
+        assert app._BACKGROUND_URI.startswith("data:image/webp")
+class TestHowToPlay:
+    def test_howto_copy_present(self):
+        assert "Three endings" in app._HOWTO_HTML
+    def test_open_howto_reveals_overlay(self):
+        out = app.gr.update(visible=True)
+        assert out["visible"] is True
+    def test_close_howto_hides_overlay(self):
+        out = app.gr.update(visible=False)
+        assert out["visible"] is False
+        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
 class TestOpeningRitual:
+    def test_head_js_carries_the_ritual_and_menu_music(self):
         assert "openingRitual" in app._HEAD_JS
+        assert "startMenuMusic" in app._HEAD_JS
+        assert "stopMenuMusic" in app._HEAD_JS
         assert "CHIME_SRC" in app._HEAD_JS
         assert "GREETING_SRC" in app._HEAD_JS
+        assert "MENU_SRC" in app._HEAD_JS
         assert "restart-btn" in app._HEAD_JS          # restart re-greets
+        assert "menu-mode-btn" in app._HEAD_JS        # mode buttons stop music + greet
+        assert "__CHIME__" not in app._HEAD_JS        # placeholders were filled
+        assert "__GREETING__" not in app._HEAD_JS
+        assert "__MENU__" not in app._HEAD_JS
     def test_chime_constant_is_real_audio(self):
         assert app._CHIME_URI.startswith("data:audio/wav;base64,")
         assert len(app._CHIME_B64) > 100              # a real synthesized note
+    def test_menu_loop_constant_is_real_audio(self):
+        assert app._MENU_LOOP_URI.startswith("data:audio/wav;base64,")
+        assert len(app._MENU_LOOP_B64) > 1000
 class TestFinaleVoice:
     def test_good_finale_voices_hollow_lines(self, monkeypatch):

tests/test_memory.py CHANGED Viewed

@@ -414,3 +414,31 @@ def test_bad_ending_fires_by_turn_four():
     s = {"affinity": 12, "claimed": [], "turn": 4, "tone": -32,
          "wounds": ["w1", "w2"], "ended": False}
     assert decide_ending(s) == "bad"

     s = {"affinity": 12, "claimed": [], "turn": 4, "tone": -32,
          "wounds": ["w1", "w2"], "ended": False}
     assert decide_ending(s) == "bad"
+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"

tests/test_sting.py CHANGED Viewed

@@ -3,7 +3,7 @@ import io
 import wave
 from sting import (chime_wav_bytes, flatline_wav_bytes, heartbeat_wav_bytes,
-                   sigh_wav_bytes, sting_wav_bytes)
 def _frames(b: bytes) -> int:
@@ -30,3 +30,9 @@ def test_flatline_is_four_seconds():
 def test_existing_sounds_still_synthesize():
     assert len(sting_wav_bytes()) > 1000
     assert len(chime_wav_bytes(0)) > 500

 import wave
 from sting import (chime_wav_bytes, flatline_wav_bytes, heartbeat_wav_bytes,
+                   menu_loop_wav_bytes, sigh_wav_bytes, sting_wav_bytes)
 def _frames(b: bytes) -> int:
 def test_existing_sounds_still_synthesize():
     assert len(sting_wav_bytes()) > 1000
     assert len(chime_wav_bytes(0)) > 500
+def test_menu_loop_is_valid_wav():
+    b = menu_loop_wav_bytes()
+    assert len(b) > 2000
+    assert _frames(b) > int(22050 * 7)

tools/pacing_sim.py CHANGED Viewed

@@ -49,11 +49,11 @@ NEUTRAL = [  # LOOP: share a lot, factual/transactional, never warm to the child
 ]
-def simulate(name: str, script: list[str]) -> None:
     state = {"affinity": 20, "treasure": [], "claimed": [], "history": [],
              "turn": 0, "last_recall_turn": None, "ended": False,
-             "tone": 0, "wounds": [], "ending": None}
-    print(f"\n=== {name} ===")
     for i, msg in enumerate(script, 1):
         ending = decide_ending(state)
         if ending:
@@ -84,9 +84,10 @@ def simulate(name: str, script: list[str]) -> None:
 if __name__ == "__main__":
     which = sys.argv[1] if len(sys.argv) > 1 else "all"
     if which in ("bad", "all"):
-        simulate("BAD", BAD)
     if which in ("good", "all"):
-        simulate("GOOD", GOOD)
     if which in ("neutral", "all"):
-        simulate("NEUTRAL", NEUTRAL)

 ]
+def simulate(name: str, script: list[str], mode: str = "tester") -> None:
     state = {"affinity": 20, "treasure": [], "claimed": [], "history": [],
              "turn": 0, "last_recall_turn": None, "ended": False,
+             "tone": 0, "wounds": [], "ending": None, "mode": mode}
+    print(f"\n=== {name} ({mode}) ===")
     for i, msg in enumerate(script, 1):
         ending = decide_ending(state)
         if ending:
 if __name__ == "__main__":
     which = sys.argv[1] if len(sys.argv) > 1 else "all"
+    mode = sys.argv[2] if len(sys.argv) > 2 else "tester"
     if which in ("bad", "all"):
+        simulate("BAD", BAD, mode=mode)
     if which in ("good", "all"):
+        simulate("GOOD", GOOD, mode=mode)
     if which in ("neutral", "all"):
+        simulate("NEUTRAL", NEUTRAL, mode=mode)