Spaces:

Pabloler21
/

hollow

Running on Zero

App Files Files Community

Pabloler21 Claude Fable 5 commited on 24 days ago

Commit

9557331

1 Parent(s): 454c898

docs: add detailed execution report for opening chime ritual

Browse files

Files changed (1) hide show

docs/superpowers/specs/2026-06-14-execution-report-opening-chime-ritual.md +301 -0

docs/superpowers/specs/2026-06-14-execution-report-opening-chime-ritual.md ADDED Viewed

	@@ -0,0 +1,301 @@

+# Execution Report — Opening Chime Ritual
+**Date:** 2026-06-14
+**Branch:** `feat/voice-awareness`
+**Plan:** `docs/superpowers/plans/2026-06-14-opening-chime-ritual.md`
+**Executor:** OpenCode agent (kimi-k2.7-code)
+**Final verification:** `.venv/Scripts/python -m pytest -q` → **221 passed**
+---
+## Executive Summary
+This report documents the exact execution of the approved `2026-06-14-opening-chime-ritual.md` plan. The goal was to reintroduce the detuned music-box chime as the child's **arrival ritual** (chime → spoken greeting) instead of the previous per-reply chime spam. The ritual now fires on the visitor's first gesture and is re-queued on every "begin again" restart. The greeting no longer lives in `voice_panel` as a DOM element; instead, both chime and greeting are injected into the `<head>` controller as `data:` URI constants so the ritual can survive the server-side `_reset` that wipes `voice_panel`.
+All plan steps were implemented and the full test suite remains green. `CLAUDE.md` and `AGENTS.md` were updated to reflect the new behavior.
+---
+## Files Modified
+| File | What changed |
+|------|--------------|
+| `app.py` | Added `chime_wav_bytes` import; replaced `_greeting_html()` with module-level `_CHIME_*` / `_GREETING_*` constants; emptied `voice_panel` initial value; reworked `_HEAD_JS` to queue the ritual from constants; wired `.restart-btn` to re-trigger the ritual. |
+| `tests/test_app.py` | Removed obsolete `_greeting_html` tests; added `TestOpeningRitual` with markup + chime-data tests. |
+| `CLAUDE.md` | Updated UI, Voice, File structure, Gotchas, and "What's next" sections to describe the chime ritual. |
+| `AGENTS.md` | Same updates as `CLAUDE.md` so agent instructions stay mirrored. |
+---
+## Step 1 — Chime + Greeting Constants and Data URIs
+### 1a. Import
+Added the chime synth import next to the existing voice import in `app.py`:
+```python
+from sting import chime_wav_bytes
+```
+This function exists in `sting.py` and returns a raw WAV `bytes` object.
+### 1b. Module-level constants
+Removed the lazy global `_GREETING_B64: str | None = None` and the entire `_greeting_html()` function. Replaced them with eager constants computed once at import time:
+```python
+_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 ""
+```
+**Why eager:** The chime is pure numpy and always available, so it can be base64-encoded at import. The greeting depends on Kokoro; on the silent dev venv `_GREETING_B64` becomes `""`, so the ritual gracefully degrades to "chime only" during local development. On `.venv-tts` and the Space both sounds are present.
+### 1c. Empty `voice_panel`
+Changed:
+```python
+voice_panel = gr.HTML(value=_greeting_html(), elem_classes="voice-channel")
+```
+to:
+```python
+voice_panel = gr.HTML(value="", elem_classes="voice-channel")
+```
+**Why:** The greeting element used to live inside `voice_panel`, but the restart button's `_reset` function rewrites `voice_panel` to empty HTML, which would destroy the greeting `<audio>` before the controller could re-read it. Moving the greeting into JS constants makes the restart ritual deterministic.
+### Orchestrator verification checklist
+- [ ] `app.py` imports `chime_wav_bytes` from `sting`.
+- [ ] `_greeting_html()` no longer exists in `app.py`.
+- [ ] `_CHIME_URI` starts with `data:audio/wav;base64,` and `_CHIME_B64` is non-empty.
+- [ ] `voice_panel` initial value is `value=""`.
+---
+## Step 2 — Rework `_HEAD_JS`: Ritual + Restart Wiring
+### 2a. Inject constants
+Inside the IIFE, immediately after `persist()`:
+```javascript
+var CHIME_SRC = "__CHIME_SRC__";
+var GREETING_SRC = "__GREETING_SRC__";
+```
+### 2b. Queue control helpers
+Added `resetQueue()` and `openingRitual()` next to the existing queue helpers:
+```javascript
+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);
+}
+```
+**Why `resetQueue()` first:** If the visitor clicks restart while a reply or idle line is speaking, the old voice line is stopped and cleared before the ritual begins, so the arrival moment is clean.
+**Why debounce:** The visitor's first gesture could *be* the restart click, which would trigger both the `firstGesture` listener and the restart listener. The 800 ms guard prevents a doubled chime.
+### 2c. First gesture handler
+Replaced the old `playGreeting()` listener with `firstGesture()`:
+```javascript
+function firstGesture() {
+  openingRitual();
+  window.removeEventListener('pointerdown', firstGesture, true);
+  window.removeEventListener('keydown', firstGesture, true);
+}
+window.addEventListener('pointerdown', firstGesture, true);
+window.addEventListener('keydown', firstGesture, true);
+```
+### 2d. MutationObserver simplification
+Removed the `#hollow-greeting` skip in the observer:
+```javascript
+nodes.forEach(function (a) { enqueue(a.currentSrc || a.src); a.remove(); });
+```
+**Why:** There is no longer a `#hollow-greeting` element; per-reply, idle, and finale audio still arrive through `voice_panel` and are enqueued by the observer exactly as before.
+### 2e. Restart button wiring
+Extended `wire()` to attach a click listener to `.restart-btn`:
+```javascript
+function wire() {
+  var btn = document.querySelector('.voice-btn');
+  var rb = document.querySelector('.restart-btn');
+  if (btn && !btn.dataset.hollowWired) {
+    btn.dataset.hollowWired = '1';
+    btn.textContent = icon();
+    btn.addEventListener('click', function (e) {
+      e.preventDefault(); e.stopPropagation();
+      st.muted = !st.muted;
+      applyLive(); persist(); btn.textContent = icon();
+    });
+  }
+  if (rb && !rb.dataset.hollowWired) {
+    rb.dataset.hollowWired = '1';
+    // do NOT stop propagation — Gradio's server-side _reset must still run;
+    // 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);
+}
+```
+**Critical detail:** The restart listener does **not** call `preventDefault()` or `stopPropagation()` because Gradio's server-side `_reset` is bound to the same click and must still execute. The audio is allowed because the click is a user gesture.
+The interval poller now stops only once both buttons are wired.
+### 2f. Build `_HEAD_JS` with real URIs
+Immediately after the `"""` assignment:
+```python
+_HEAD_JS = _HEAD_JS.replace("__CHIME_SRC__", _CHIME_URI).replace("__GREETING_SRC__", _GREETING_URI)
+```
+**Why `.replace` instead of f-string:** The JS body contains literal `{}` characters (object literals, function bodies). Using an f-string would interpret them as Python format placeholders and break the script.
+Updated the `_HEAD_JS` doc-comment to mention the chime ritual.
+### Orchestrator verification checklist
+- [ ] `_HEAD_JS` contains `openingRitual`, `CHIME_SRC`, `GREETING_SRC`, `resetQueue`, `firstGesture`, and `restart-btn`.
+- [ ] The placeholder `__CHIME_SRC__` is NOT present in the final `_HEAD_JS` (test asserts this).
+- [ ] `openingRitual()` calls `resetQueue()` before enqueuing chime/greeting.
+- [ ] The restart click listener does NOT call `stopPropagation()`.
+- [ ] `_HEAD_JS` is built with `.replace("__CHIME_SRC__", _CHIME_URI).replace("__GREETING_SRC__", _GREETING_URI)`.
+---
+## Step 3 — Tests
+### 3a. Removed obsolete tests
+Deleted from `tests/test_app.py`:
+- `test_greeting_html_has_id_and_no_autoplay`
+- `test_greeting_html_empty_when_voice_unavailable`
+Also updated the comment inside `test_first_turn_speaks_its_own_reply` to reference the new ritual instead of `_greeting_html`.
+### 3b. Added ritual tests
+```python
+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
+        assert "__CHIME_SRC__" 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
+```
+These tests only assert the chime and markup because `_GREETING_B64` is empty on the silent dev venv.
+### 3c. Test result
+```bash
+.venv/Scripts/python -m pytest -q
+# 221 passed in 6.03s
+```
+### Orchestrator verification checklist
+- [ ] `tests/test_app.py` no longer references `_greeting_html`.
+- [ ] `TestOpeningRitual` exists and passes.
+---
+## Step 5 — Documentation Updates
+Updated both `CLAUDE.md` and `AGENTS.md` to reflect:
+- The `<head>` controller now handles the **opening-chime-ritual** (chime → greeting) on first gesture and on restart.
+- Per-reply/finale audio still lives in `voice_panel`; the ritual is queued from `data:` URI constants in `_HEAD_JS`.
+- The `_greeting_html` function is gone.
+- The opening line is spoken as part of the ritual, both on first gesture and on "begin again".
+- File structure descriptions no longer list `_greeting_html`.
+### Orchestrator verification checklist
+- [ ] Neither `CLAUDE.md` nor `AGENTS.md` mentions `_greeting_html`.
+- [ ] Both mention the chime ritual and the restart re-greeting.
+---
+## Practices Followed
+1. **Plan-driven execution.** Every checkbox in the plan was implemented in order.
+2. **No new dependencies.** Only existing `sting.py`, `voice.py`, `base64`, and vanilla JS were used.
+3. **Minimal changes.** `_greeting_html` was removed, but all other voice/finale/idle paths were left untouched.
+4. **Test-driven verification.** Obsolete tests were removed and new markup/data tests were added before final verification.
+5. **Edit tool for Python files.** No PowerShell string manipulation was used on `.py` files.
+6. **Atomic commit.** All changes were committed together with the required `Co-Authored-By` trailer.
+7. **Mirrored docs.** `CLAUDE.md` and `AGENTS.md` were updated in parallel.
+---
+## Verification Evidence
+```bash
+.venv/Scripts/python -m pytest -q
+```
+Result:
+```
+........................................................................ [ 32%]
+........................................................................ [ 65%]
+........................................................................ [ 97%]
+.....                                                                    [100%]
+221 passed in 6.03s
+```
+---
+## Risks / Notes for the Orchestrator
+1. **Live audio verification is still pending.** The plan explicitly requires a human ear check:
+   - First gesture → chime, then greeting.
+   - "Begin again" → chime, then greeting again.
+   - Muted restart → silent ritual.
+   - Normal replies still stream + speak per sentence with no per-reply chime.
+2. **Silent dev venv.** On the 3.13 `.venv` without Kokoro, `_GREETING_URI` is empty, so the local ritual is "chime only". This is expected; full chime + greeting requires `.venv-tts` (py3.12) or the Space.
+3. **Restart wiring race condition.** The `wire()` interval polls for `.restart-btn` for up to 15 seconds. If the button is never rendered, the ritual will still fire via `firstGesture` on the click (because the click is a gesture), but the explicit re-greet on restart will not. This matches the fallback behavior described in the plan.
+4. **Debouncing.** If the first gesture and restart click happen within 800 ms, only one ritual fires. This is intentional.
+5. **Server-side `_reset` must still run.** The restart listener intentionally does not stop propagation; it only adds audio on top of Gradio's existing handler.
+---
+## Git Log
+```
+f375204 feat: chime-then-greeting opening ritual on start and 'begin again'
+```
+All work is on branch `feat/voice-awareness`. Spaces remain frozen at `4deeed5` until the user approves live verification and mirror-first deploy.