docs(01-03): complete the avatar stage and transport seam plan

.planning/ROADMAP.md

@@ -35,7 +35,7 @@ Decimal phases appear between their surrounding integers in numeric order.
   - [x] 01-02-PLAN.md — Toolchain, LFS arming, package skeleton, test scaffolding (local-only) [wave 1]
   - [x] 01-01-PLAN.md — Hosting decision + Space creation + VRM sourcing (user-gated) [wave 2]
   - [x] 01-04-PLAN.md — VOICEVOX TTS, requirements.txt, ground-truth AudioQuery fixtures [wave 2]
-  - [ ] 01-03-PLAN.md — Avatar stage, shared facade + turn loop, both transports [wave 3]
+  - [x] 01-03-PLAN.md — Avatar stage, shared facade + turn loop, both transports [wave 3]
   - [ ] 01-05-PLAN.md — Space manifest, deploy the spike, first deployed E2E, verdict (user-gated) [wave 4]
   - [ ] 01-06-PLAN.md — Mora-to-viseme timeline builder, test-first [wave 4]
   - [ ] 01-07-PLAN.md — Push-to-talk mic gate + tiered browser ASR [wave 4]

.planning/STATE.md

@@ -3,13 +3,13 @@ gsd_state_version: 1.0
 milestone: v1.0
 milestone_name: milestone
 status: executing
-stopped_at: 01-03 mid-execution. Tasks 1-2 complete and committed; Tasks 3-4 not started. See the table under "Current Position".
-last_updated: "2026-08-27T11:44:52.247Z"
+stopped_at: Completed 01-03-PLAN.md (Tasks 3-4 executed after crash recovery); nothing pushed to the space remote
+last_updated: "2026-08-27T12:09:36.232Z"
 progress:
   total_phases: 6
   completed_phases: 0
   total_plans: 10
-  completed_plans: 3
+  completed_plans: 4
 ---
 
 # Project State
@@ -24,26 +24,28 @@ See: .planning/PROJECT.md (updated 2026-08-08)
 ## Current Position
 
 Phase: 01 (voice-avatar-loop-skeleton) — EXECUTING
-Plan: 4 of 10 (3 complete, 01-03 in flight at Task 3 of 4)
+Plan: 5 of 10 (4 complete: 01-01, 01-02, 01-03, 01-04)
 
-> **01-03 IS MID-EXECUTION — a session crash interrupted it, not a pause.** No `HANDOFF.json` and no `.continue-here` exist because `/gsd:pause-work` never ran; the state below was reconstructed from the working tree and git log on 2026-08-27.
+> **01-03 IS COMPLETE.** The crash-interrupted plan was resumed at Task 3 on 2026-08-27 and both remaining tasks executed and committed. Full detail in `01-03-SUMMARY.md`; the highlights that change what later plans should assume are below.
 >
-> | Task | Deliverable | State |
-> |------|-------------|-------|
-> | 1 | `vrm-stage.js`, `lipsync.js`, `audio-queue.js` | Complete, committed `94a5b15` |
-> | 2 | `facade.js`, `turn-loop.js` | Complete, committed `7146e75` (recovered from untracked files at resume) |
-> | 3 | `avatar.js`, `avatar-iframe.js`, `stage.html`, `demo-konnichiwa.wav`, `avatar_component.py`, `app.py` | **Not started — none of these files exist** |
-> | 4 | `tests/test_transport_seam.py`, `tests/e2e/test_stage_standalone.py`, `tests/e2e/test_facade_parity.py` | **Not started** |
+> | Task | Deliverable | Commit |
+> |------|-------------|--------|
+> | 1 | `vrm-stage.js`, `lipsync.js`, `audio-queue.js` | `94a5b15` |
+> | 2 | `facade.js`, `turn-loop.js` | `7146e75` |
+> | 3 | `avatar.js`, `avatar-iframe.js`, `stage.html`, `demo-konnichiwa.wav`, `avatar_component.py`, `app.py` | `f822421` |
+> | 4 | `test_transport_seam.py`, `test_stage_standalone.py`, `test_facade_parity.py` | `d6ea280` |
 >
-> **Resume at Task 3. Do NOT re-do Tasks 1-2** — their files exist and are committed. They were spot-checked against their acceptance criteria at resume and pass: the `?deps=three@0.185.1` pin appears exactly once, no import map exists anywhere in `avatar/`, `lipsync.js` has no `setTimeout`, and `facade.js` is the only file matching `window.Avatar =`.
+> **The Gradio spike works locally, which materially de-risks plan 01-05.** three.js + `@pixiv/three-vrm` render inside a real Gradio 6.22.0 `gr.HTML` component with `threeInstanceCount === 1` and `mountCount === 1`, and the iframe fallback boots identically under `AVATAR_TRANSPORT=iframe`. 43 tests green: 36 static seam guards, 4 standalone browser tests, 3 live parity tests. Both transports expose byte-identical method sets and `__debug` keys.
 >
-> **Two corrections the Task 3/4 executor needs:**
-> 1. **`avatar/vrm-stage.js:64` contains the word "Gradio" in a comment.** Task 4's `test_stage_core_is_gradio_free` greps the lowercase token `gradio`, so the capitalised word passes today — but it violates the rule's intent and breaks the moment that check is made case-insensitive. Reword it while writing Task 4.
-> 2. **`boot()` has an emit-ordering problem the plan does not call out.** Task 3 step 2 calls `mountStage(canvas, props.vrmUrl, emit)`, but `emit` does not exist until `installFacade` returns it at step 5. The transport needs a deferred emit — a local function that buffers events (or forwards through a mutable reference) until the real bus is installed. This applies to **both** transports.
+> **Two Gradio 6 API traps were found the hard way — `01-RESEARCH.md`'s `gr.HTML` section is NOT reliable on these two points. Copy from `src/japanese_avatar/ui/avatar_component.py`, not from research:**
+> 1. **`js_on_load` cannot use top-level `await`.** Gradio 6.22.0 compiles it with a plain, non-async `Function('element','trigger','props','server','upload','watch', body)`. The documented snippet throws `SyntaxError` and the component silently never boots. Wrap the body in an async IIFE with its own `.catch`.
+> 2. **Custom props are `**kwargs`, not a `props=` dict.** `gr.HTML(props={"vrmUrl": ...})` creates one prop literally named `props`, so `props.vrmUrl` is `undefined` in the browser and `GLTFLoader` throws inside `extractUrlBase`. Pass `vrmUrl=...` directly.
 >
-> Also note Task 2's acceptance criterion `grep -ci "gradio\|element\|props\|THREE" avatar/facade.js avatar/turn-loop.js` returns 0 is **unsatisfiable as literally written**: `threeInstanceCount` is a mandated `__debug` key and contains the substring `three`. The actual enforced test (`test_shared_modules_are_gradio_free`) checks only `gradio`, `gradio_api`, `server.` and `trigger(`, all of which genuinely are absent. Trust the test, not the prose.
+> **Recorded for plan 01-09:** observed `vrmMetaTitle` is `VRM1_Constraint_Twist_Sample`, VRM spec version `1` (so no facing rotation is applied and licence fields live under `meta.name`), `threeInstanceCount` is `1`. Standalone VRM load: 607 ms cold context / ~335 ms warm on loopback.
 >
-> **Do not push to the `space` remote during this phase.** It is the only remote this repo has and pushing triggers a Space rebuild; deployment is plan 01-05's job.
+> **AVTR-01 was deliberately NOT marked complete** even though it is in 01-03's `requirements:` frontmatter. Its acceptance tests (`tests/e2e/test_avatar_loop.py::test_vrm_ready` / `::test_idle_life` / `::test_no_remount`) belong to plan 01-09 and run against the deployed Space; they do not exist yet. This follows the standing warning below about over-claiming plan frontmatter.
+>
+> **Still do not push to the `space` remote.** It is the only remote this repo has and pushing triggers a Space rebuild. `app.py` now exists, but deployment (and the Space README front-matter) is plan 01-05's job.
 
 ## Performance Metrics
 
@@ -73,6 +75,7 @@ Plan: 4 of 10 (3 complete, 01-03 in flight at Task 3 of 4)
 - Trend: 01-01 was fast because its two expensive tasks were human checkpoints answered outside the executor; the executor's own work was verification and recording
 
 *Updated after each plan completion*
+| Phase 01 P03 | 62 | 4 tasks | 20 files |
 
 ## Accumulated Context
 
@@ -95,6 +98,10 @@ Recent decisions affecting current work:
 - [Phase 01]: 1 of 2 free ZeroGPU slots consumed by WolfDavid/japanese-learning-avatar; the remaining slot is the last free Gradio Space this account can create without PRO.
 - [Phase 01]: tutor.vrm is VRM1_Constraint_Twist_Sample (pixiv Inc., VRM 1.0) adopted as a TEMPORARY dev asset; embedded VRMC_vrm.meta grants redistribution/avatar-use/modification with creditNotation unnecessary. Plan 01-10 must re-raise the sourcing gate.
 - [Phase 01]: Audit Space hardware via runtime.hardware.requested, not .current — .current is null for every SLEEPING Space, which made six of eight look unallocated.
+- [Phase 01]: gr.HTML js_on_load must be wrapped in an async IIFE: Gradio 6.22.0 compiles it with a plain non-async Function(), so the documented top-level await is a SyntaxError and the component silently never boots
+- [Phase 01]: Custom gr.HTML props are **kwargs, not a props= dict; the dict form creates one prop literally named 'props' and props.vrmUrl arrives undefined in the browser
+- [Phase 01]: Gradio's auto-generated .pyi component stub is build output: gitignored and ruff-excluded, because create_or_modify_pyi runs unconditionally with no opt-out
+- [Phase 01]: Browser assertions sample in-page at animation-frame rate; a 250 ms Python poll cannot reliably observe a 120 ms blink and would be flaky by construction
 
 ### Pending Todos
 
@@ -113,8 +120,8 @@ None yet.
 
 ## Session Continuity
 
-Last session: 2026-08-27 — session resumed via /gsd:resume-work after a crash; Task 2's recovered files committed, proceeding to execute 01-03 from Task 3.
-Stopped at: 01-03 mid-execution. Tasks 1-2 complete and committed; Tasks 3-4 not started. See the table under "Current Position".
-Resume file: None (crash, not a pause — no HANDOFF.json was written)
+Last session: 2026-08-27T12:09:28.441Z
+Stopped at: Completed 01-03-PLAN.md (Tasks 3-4 executed after crash recovery); nothing pushed to the space remote
+Resume file: None
 
-**Do not push to the `space` remote yet.** It is the only remote this repo has, and pushing triggers a Space rebuild. `app.py` does not exist until Task 3, and the Space README front-matter fixes are owned by plan 01-05. The Space correctly serves 503 (`NO_APP_FILE`) until then.
+**Do not push to the `space` remote yet.** It is the only remote this repo has, and pushing triggers a Space rebuild. `app.py` now exists (01-03), but the Space README front-matter and the deploy itself are owned by plan 01-05. The Space correctly serves 503 (`NO_APP_FILE`) until then. Nothing from 01-03 was pushed.

.planning/phases/01-voice-avatar-loop-skeleton/01-03-SUMMARY.md

@@ -0,0 +1,277 @@
+---
+phase: 01-voice-avatar-loop-skeleton
+plan: 03
+subsystem: ui
+tags: [three.js, three-vrm, vrm, webaudio, gradio, playwright, postmessage, esm]
+
+# Dependency graph
+requires:
+  - phase: 01-01
+    provides: avatar/assets/tutor.vrm (VRM 1.0, Git LFS) and its recorded licence facts
+  - phase: 01-02
+    provides: pyproject pytest/ruff config, tests/conftest.py, marker conventions
+provides:
+  - "avatar/vrm-stage.js — three.js scene, single-instance module load, VRM mount, idle blink/breathe/sway, numeric __debug"
+  - "avatar/lipsync.js — AudioContext-clocked viseme player, no timers, no amplitude analysis"
+  - "avatar/audio-queue.js — WebAudio decode/schedule, speech-start/speech-end off the SCHEDULED start"
+  - "avatar/facade.js — AVATAR_SURFACE + installFacade, the only assignment of window.Avatar"
+  - "avatar/turn-loop.js — the only turn implementation, shared by both transports"
+  - "avatar/avatar.js — inline gr.HTML transport (145 lines, plumbing only)"
+  - "avatar/avatar-iframe.js — postMessage transport (155 lines, plumbing only)"
+  - "avatar/stage.html — iframe target AND standalone debug harness with ?demo=1"
+  - "avatar/assets/demo-konnichiwa.wav — 24000 Hz mono 16-bit, 1.129 s canned utterance"
+  - "src/japanese_avatar/ui/avatar_component.py — VrmStage, AVATAR_TRANSPORT read in one place"
+  - "app.py — Blocks assembly, gr.set_static_paths([\"avatar\"]), DISABLE_GPU switch"
+  - "tests/test_transport_seam.py — 36 static seam guards"
+  - "tests/e2e/test_stage_standalone.py — 4 browser tests against stage.html"
+  - "tests/e2e/test_facade_parity.py — 3 live-object parity tests across both transports"
+affects: [01-05 deployment spike, 01-06 viseme timeline, 01-07 mic and ASR, 01-08 turn loop, 01-09 avatar loop E2E]
+
+# Tech tracking
+tech-stack:
+  added: [three@0.185.1 via esm.sh, "@pixiv/three-vrm@3.5.5 via esm.sh ?deps= pinning", playwright chromium]
+  patterns:
+    - "stagePort: the six-method renderer boundary; the ONLY thing that differs between transports"
+    - "AVATAR_SURFACE as data — the facade is built by iterating it and throws at boot on an unresolved name"
+    - "deferred event bus in each transport so events emitted during mount survive until installFacade runs"
+    - "in-page frame-rate sampling for browser assertions instead of Python-side polling"
+
+key-files:
+  created:
+    - avatar/avatar.js
+    - avatar/avatar-iframe.js
+    - avatar/stage.html
+    - avatar/assets/demo-konnichiwa.wav
+    - src/japanese_avatar/ui/avatar_component.py
+    - app.py
+    - tests/test_transport_seam.py
+    - tests/e2e/conftest.py
+    - tests/e2e/test_stage_standalone.py
+    - tests/e2e/test_facade_parity.py
+  modified:
+    - avatar/vrm-stage.js
+    - .gitignore
+    - pyproject.toml
+
+key-decisions:
+  - "gr.HTML js_on_load must be wrapped in an async IIFE: Gradio 6.22.0 compiles it with a plain non-async Function(), so the documented top-level await is a SyntaxError and the component silently never boots"
+  - "Custom gr.HTML props are **kwargs, not a props= dict; the dict form creates one prop literally named 'props' and props.vrmUrl arrives undefined"
+  - "Gradio's auto-generated .pyi component stub is build output: gitignored and excluded from ruff, because create_or_modify_pyi runs unconditionally with no opt-out"
+  - "Browser assertions sample in-page at animation-frame rate; a 250 ms poll cannot reliably observe a 120 ms blink"
+  - "The host-token seam guards are case-insensitive so a capitalised mention cannot pass by accident"
+
+patterns-established:
+  - "One facade, one turn loop, N transports: a transport is message plumbing, never behaviour"
+  - "Every visual property is published as a number in __debug; the canvas is never screenshotted"
+  - "Deferred methods throw an error naming the plan that implements them, so a premature call fails loudly"
+
+requirements-completed: []
+
+# Metrics
+duration: 62min
+completed: 2026-08-27
+---
+
+# Phase 01 Plan 03: Avatar Stage and Transport Seam Summary
+
+**A VRM 1.0 avatar that blinks, breathes, sways and lip-syncs a canned Japanese utterance off the AudioContext clock, behind a single `window.Avatar` facade that two independently-booting transports are proven — in a running browser — to expose identically.**
+
+## Performance
+
+- **Duration:** ~62 min for Tasks 3-4 (this session); Tasks 1-2 were executed before a session crash
+- **Started:** 2026-08-27T07:45:00Z (resume at Task 3)
+- **Completed:** 2026-08-27T08:47:00Z
+- **Tasks:** 4 of 4 (Tasks 1-2 pre-existing and committed; Tasks 3-4 executed here)
+- **Files modified:** 20 across four task commits
+
+## Required Measurements
+
+| Measurement | Observed value |
+|---|---|
+| `threeInstanceCount` | **1** — in the standalone harness, in the inline Gradio app, and in the iframe Gradio app. `performance.getEntriesByType('resource')` also reports exactly **one** `three.mjs` entry, and no `Multiple instances of Three.js` console warning appeared in any run. |
+| `vrmMetaTitle` | **`VRM1_Constraint_Twist_Sample`** — plan 01-09's `test_vrm_meta_matches_licenses` compares against this string. It matches `docs/ASSETS.md` `meta.name` exactly. |
+| VRM spec version detected | **VRM 1.0** — `vrm.meta.metaVersion === '1'`, surfaced as `__debug.vrmSpecVersion`. Confirms `docs/ASSETS.md` (`extensions.VRMC_vrm.specVersion = 1.0`). Consequence: **no facing rotation is applied** (`vrm.scene.rotation.y = Math.PI` is the VRM 0.0 branch only), and the licence fields live under `meta.name`, not `meta.title`. |
+| VRM load time, standalone harness | Navigation → `__stageDebug.ready === true`: **607 ms** on a cold browser context, **334 ms / 338 ms** on the two following contexts. The 10.28 MiB `tutor.vrm` fetch itself was **33-56 ms** (served from `python -m http.server` on loopback), and the single `three.mjs` fetch **34-37 ms** from esm.sh. Loopback + a warm browser HTTP cache for the CDN modules — the deployed number is 01-05's to measure, and the E2E `READY_TIMEOUT_MS` is set to 30 s to leave room for it. |
+| `avatar/avatar.js` line count | **145** (budget: under 150) |
+| `avatar/avatar-iframe.js` line count | **155** (budget: under 180) |
+| Deliberate seam break | **Confirmed.** Appending `window.Avatar = {};` to `avatar/avatar-iframe.js` made `test_only_facade_assigns_window_avatar` fail with `AssertionError: avatar-iframe.js assigns window.Avatar; only facade.js may` and `assert not <re.Match object; span=(5384, 5399), match='window.Avatar ='>`. The file was reverted with `git checkout --` and the full 36-case suite is green again. |
+
+## Accomplishments
+
+- **The stage core works in a real browser with no Python at all.** `avatar/stage.html?demo=1` loads the VRM, runs blink/breathe/sway, and lip-syncs `こんにちは` against a hand-authored placeholder timeline. Observed viseme peaks: `aa = 1.0`, `ih = 1.0`, `oh = 1.0`, with `ou` and `ee` correctly at `0` (こんにちは contains no `u` or `e` vowel), and all five back to `0` after `speech-end`.
+- **The Wave 0 spike question is now substantially answered locally, and the answer is positive.** three.js + `@pixiv/three-vrm` load and render inside a Gradio 6.22.0 `gr.HTML` component via dynamic `import()` from `/gradio_api/file=avatar/...`, with `threeInstanceCount === 1` and `mountCount === 1`. `01-RESEARCH.md` recorded that nobody had publicly done this; it now works on this machine. Plan 01-05 still owns the deployed verdict.
+- **The iframe fallback is not a plan, it is a running program.** Both transports boot the same app under a single env var and expose byte-identical surfaces, proven mechanically rather than asserted in prose.
+- **Two real Gradio 6 API defects were found and fixed** (see Deviations) — both would have made the deployed spike fail in ways that look like "three.js does not work in Gradio", which is precisely the wrong conclusion.
+
+## Task Commits
+
+1. **Task 1: Gradio-free stage core** — `94a5b15` (feat) *(pre-existing; committed before the crash)*
+2. **Task 2: The single facade and the single turn loop** — `7146e75` (feat) *(pre-existing; recovered and committed at resume)*
+3. **Task 3: Two thin transports, the standalone host page, and the Gradio component** — `f822421` (feat)
+4. **Task 4: Enforce the seam — static guards, standalone proof, mechanical parity** — `d6ea280` (test)
+
+## Files Created/Modified
+
+- `avatar/avatar.js` — inline transport: builds a direct stagePort, memoised single mount, deferred emit, delegates everything else
+- `avatar/avatar-iframe.js` — iframe transport: same shape, six postMessage round trips, id-correlated replies with a 60 s bound
+- `avatar/stage.html` — standalone harness and iframe target; `DEMO_TIMELINE`, `window.__stageDebug`, `window.__stageEvents`, the full postMessage protocol
+- `avatar/assets/demo-konnichiwa.wav` — 24000 Hz mono 16-bit, 27096 frames, 1.129000 s; one 220 Hz raised-cosine burst per voiced mora at the `DEMO_TIMELINE` offsets (Git LFS)
+- `avatar/vrm-stage.js` — reworded the import-map comment so the stage core names no host framework
+- `src/japanese_avatar/ui/avatar_component.py` — `VrmStage`, `AVATAR_TRANSPORT`, one shared `_BOOT_JS` template
+- `app.py` — `gr.set_static_paths(["avatar"])`, `build_app()`, `gpu_disabled()` for SC-4
+- `tests/test_transport_seam.py` — 36 static cases
+- `tests/e2e/conftest.py` — static-file server, per-transport Gradio subprocess, Chromium autoplay flag
+- `tests/e2e/test_stage_standalone.py` — 4 tests
+- `tests/e2e/test_facade_parity.py` — 3 tests
+- `.gitignore`, `pyproject.toml` — exclude Gradio's generated `.pyi` stub from git and from the lint gate
+
+## Decisions Made
+
+- **`js_on_load` bodies are wrapped in an async IIFE with its own `.catch`.** The IIFE escapes Gradio's internal `try/catch`, so a boot failure has to report itself; that console line is what plan 01-05 will read.
+- **The demo WAV is a synthetic tone burst per voiced mora, not synthesised speech.** It only has to be audible and correctly timed; plan 01-06 replaces both the audio and the timeline from a real `AudioQuery`. The generator snippet is recorded below so the asset is reproducible.
+- **`window.__stageEvents` was added alongside `window.__stageDebug`.** Opened standalone, the stage has no parent to post to, so the event stream would be unobservable and `test_demo_timeline_drives_visemes` would have to guess at timing instead of waiting for `speech-end`.
+- **Host-token guards are case-insensitive.** The state file flagged that `vrm-stage.js` passed only because the offending word was capitalised. The comment is reworded *and* the guard is now case-insensitive, so the pass is honest rather than lucky.
+
+## Deviations from Plan
+
+### Auto-fixed Issues
+
+**1. [Rule 1 - Bug] `js_on_load` top-level `await` is a SyntaxError in Gradio 6.22.0**
+
+- **Found during:** Task 4 (writing the parity suite, which boots the real app)
+- **Issue:** The plan's `_INLINE_JS` / `_IFRAME_JS` (taken from `01-RESEARCH.md`, which took them from Gradio's docs) use top-level `await`. Gradio 6.22.0's HTML component compiles the string with `Function('element','trigger','props','server','upload','watch', js_on_load)` — a plain, non-async function. The browser console showed `Error executing js_on_load: SyntaxError: await is only valid in async functions and the top level bodies of modules`, and `window.Avatar` never existed. Verified by reading `gradio/templates/frontend/assets/HTML-DtO81iEW.js`.
+- **Fix:** One shared `_BOOT_JS` template wrapping the body in `(async () => { ... })().catch(err => console.error('avatar boot failed:', err))`.
+- **Files modified:** `src/japanese_avatar/ui/avatar_component.py`
+- **Verification:** `window.Avatar` present and `__debug.ready` true under both transports; `test_facade_parity.py` 3 passed.
+- **Committed in:** `d6ea280`
+
+**2. [Rule 1 - Bug] Custom `gr.HTML` props are `**kwargs`, not a `props=` dict**
+
+- **Found during:** Task 4 (same run, immediately after fix 1)
+- **Issue:** The plan passes `props={"vrmUrl": VRM_URL, "transport": AVATAR_TRANSPORT}`. `gradio/components/html.py` declares `**props: Any`, so that call creates a single prop literally named `props`. In the browser `props.vrmUrl` was `undefined`, which reached `GLTFLoader.load` and threw `TypeError: Cannot read properties of undefined (reading 'lastIndexOf')` inside `extractUrlBase`. `01-RESEARCH.md`'s "verified signature" line `props: Any = {}` is a misreading of `**props`.
+- **Fix:** Pass `vrmUrl=VRM_URL, transport=AVATAR_TRANSPORT` as keyword arguments, with a comment recording the trap.
+- **Files modified:** `src/japanese_avatar/ui/avatar_component.py`
+- **Verification:** VRM fetched (`RESP 200 /gradio_api/file=avatar/assets/tutor.vrm`) and `__debug.ready` true under both transports.
+- **Committed in:** `d6ea280`
+
+**3. [Rule 3 - Blocking] Gradio writes an un-lintable `.pyi` stub next to any component subclass**
+
+- **Found during:** Task 3 (first `ruff check .` after creating `VrmStage`)
+- **Issue:** `gradio/component_meta.py` calls `create_or_modify_pyi()` unconditionally at class creation — no env switch, no opt-out. It generated `src/japanese_avatar/ui/avatar_component.pyi`, which fails `E402`, `F401` and `UP035`. The lint gate is a plan verification command, so this blocked the task, and the file regenerates on every import.
+- **Fix:** `*.pyi` added to `.gitignore` and to ruff's `extend-exclude`, each with a comment explaining why.
+- **Files modified:** `.gitignore`, `pyproject.toml`
+- **Verification:** `uv run ruff check . && uv run ruff format --check .` exits 0; `git status` clean after a test run.
+- **Committed in:** `f822421`
+
+**4. [Rule 1 - Bug] The 250 ms idle-life poll the plan specifies is flaky by construction**
+
+- **Found during:** Task 4 (writing `test_idle_life_values_change`)
+- **Issue:** The plan says sample `{blinkValue, breathValue}` every 250 ms for 12 s and assert `max(blink_samples) > 0.5`. A blink is a 120 ms triangular ramp on a 1.8-5.8 s schedule, so the window where `blinkValue > 0.5` is roughly 60 ms per blink — under 2% of the wall clock. 48 polls over 12 s would land inside it about 0.7 times on average: the test would fail on most runs for a perfectly healthy avatar.
+- **Fix:** The sampler runs *inside the page* on `requestAnimationFrame` for the same 12 s window, returning the full series to Python. Same measurement, same assertions, ~60× the sampling rate, no flakiness. The same technique is used for viseme peaks in `test_demo_timeline_drives_visemes`.
+- **Files modified:** `tests/e2e/test_stage_standalone.py`
+- **Verification:** Suite run repeatedly, 4 passed each time; observed blink peak 0.868, 69 distinct breath values in a 3 s window alone.
+- **Committed in:** `d6ea280`
+
+**5. [Rule 2 - Missing Critical] `window.__stageEvents` added to the standalone harness**
+
+- **Found during:** Task 4
+- **Issue:** `stage.html` emits `speech-start` / `speech-end` / `error` by `postMessage` to its parent. Opened standalone there is no parent, so the entire event stream is unobservable and a browser test can only guess when the utterance ended.
+- **Fix:** `emit()` also appends `{event, data, at}` to `window.__stageEvents`, mirroring the existing `window.__stageDebug` convention.
+- **Files modified:** `avatar/stage.html`
+- **Verification:** `test_demo_timeline_drives_visemes` waits on `speech-end` and asserts the mouth shut afterwards; passes.
+- **Committed in:** `d6ea280`
+
+**6. [Rule 2 - Missing Critical] Deferred event bus in both transports**
+
+- **Found during:** Task 3 (flagged in advance by STATE.md, not rediscovered)
+- **Issue:** The plan's `boot` calls `mountStage(canvas, props.vrmUrl, emit)` at step 2 but `emit` only exists after `installFacade` returns it at step 5. Events emitted during mount — notably the `error` raised when a VRM has no `expressionManager`, the exact symptom of a double three.js instance — would be dropped.
+- **Fix:** A ~12-line `deferredBus()` in each transport buffers `(name, data)` pairs and replays them in order into the real bus at `emit.connect(installed.emit)`. Duplicated rather than shared because the alternative was editing a frozen Task 2 file; it is plumbing, not behaviour, so it is outside what the seam guards protect.
+- **Files modified:** `avatar/avatar.js`, `avatar/avatar-iframe.js`
+- **Verification:** `test_transports_only_do_plumbing` passes for both files; both transports boot green.
+- **Committed in:** `f822421`
+
+**7. [Rule 3 - Blocking] `test_transport_seam.py` resolves `avatar/` from `__file__`, not the cwd**
+
+- **Found during:** Task 4
+- **Issue:** The plan's code block uses `AVATAR = Path("avatar")`, which silently makes every assertion a function of the process working directory.
+- **Fix:** `AVATAR = Path(__file__).resolve().parent.parent / "avatar"`. Every assertion is otherwise verbatim from the plan.
+- **Files modified:** `tests/test_transport_seam.py`
+- **Verification:** 36 passed from the repo root.
+- **Committed in:** `d6ea280`
+
+**8. [Rule 3 - Blocking] `tests/e2e/conftest.py` created (not in `files_modified`)**
+
+- **Found during:** Task 4
+- **Issue:** Both browser suites need a static-file server, a per-transport Gradio subprocess and a Chromium launched with `--autoplay-policy=no-user-gesture-required`. Without the autoplay flag an ungestured `AudioContext` stays suspended, `currentTime` never advances, and the lip-sync test would be measuring Chromium's autoplay policy rather than the player.
+- **Fix:** One `tests/e2e/conftest.py` holding those three fixtures, following plan 01-02's conventions.
+- **Files modified:** `tests/e2e/conftest.py`
+- **Verification:** Both suites green.
+- **Committed in:** `d6ea280`
+
+### Acceptance criteria not satisfiable as literally written
+
+Recorded rather than fixed, because satisfying the literal text would make the code worse:
+
+- **Task 2's `grep -ci "gradio\|element\|props\|THREE" facade.js turn-loop.js` returning 0** is impossible: `threeInstanceCount` is a mandated `__debug` key and contains `three`. The enforced test (`test_shared_modules_are_gradio_free`) checks `gradio`, `gradio_api`, `server.` and `trigger(`, all genuinely absent from both files, and now case-insensitively. This was pre-flagged in STATE.md.
+- **`grep -c "installFacade" avatar/avatar.js` returning exactly 1** — returns 4 here, because the module header and JSDoc name it. The enforced test asserts presence, not count. Same for `grep -c 'key="vrm-stage"'` in `avatar_component.py` returning 2 rather than 1, which the plan's own code block also does (the docstring names it).
+
+---
+
+**Total deviations:** 8 auto-fixed (4 bugs, 2 missing-critical, 2 blocking) + 2 unsatisfiable criteria recorded.
+**Impact on plan:** No scope creep. Deviations 1 and 2 are the substantive ones: without them the component never boots and the spike would have been read as "three.js does not work in Gradio 6". Everything else is test robustness or lint plumbing.
+
+## Issues Encountered
+
+- **The published Gradio `gr.HTML` recipe does not run on 6.22.0.** Both the top-level `await` and the `props=` dict come straight from the docs/research and both are wrong for this version. The fix required reading Gradio's compiled frontend bundle and `components/html.py` directly. Recorded in code comments at both sites so a future editor cannot re-introduce either.
+- **`three-vrm` emits two deprecation warnings on load** — `VRMUtils.removeUnnecessaryJoints is deprecated` (we already call `combineSkeletons` first and the call is guarded with `?.`) and `THREE.Clock: This module has been deprecated. Please use THREE.Timer instead.` Neither is an error and neither affects behaviour. Logged as a cleanup candidate; deliberately not fixed here, as changing the clock source is a stage-core change with no test demanding it.
+- **Playwright + Chromium were already installed** and `uv run playwright install chromium` was a no-op. No environment blockers; both browser suites ran to completion in this environment.
+
+## Known Stubs
+
+Intentional, each named in the plan and each failing loudly rather than silently:
+
+- `avatar/turn-loop.js` — `startListening` / `stopListening` throw `Avatar.<name>() is not wired yet - plan 01-07 implements it`; `dispatchTurn` / `requestSlower` throw the same naming **01-08**. `test_deferred_methods_fail_loudly_not_silently` asserts this in a live browser under both transports and is deleted by 01-08.
+- `avatar/stage.html` `DEMO_TIMELINE` and `avatar/assets/demo-konnichiwa.wav` — hand-authored placeholder, marked `PLACEHOLDER` in source. Plan 01-06 replaces both from a real VOICEVOX `AudioQuery`.
+- `app.py` mounts only `VrmStage()`; there is no chat UI, mic control or credits footer yet. Those belong to 01-07, 01-08 and 01-10.
+
+None of these block the plan's goal: the seam, the renderer and the parity proof are all real.
+
+## Reproducing the demo asset
+
+`avatar/assets/demo-konnichiwa.wav` was generated from `DEMO_TIMELINE`'s voiced-mora offsets — 24000 Hz mono 16-bit, 27096 frames, a 220 Hz carrier under a raised-cosine (Hann) envelope at amplitude 0.35, one burst per voiced mora at `(0.164, 0.128)`, `(0.484, 0.117)`, `(0.676, 0.107)`, `(0.826, 0.203)`.
+
+## Verification Results
+
+| Command | Result |
+|---|---|
+| `uv run pytest tests/test_transport_seam.py -q` | **36 passed** (plan requires ≥30 collected) |
+| `uv run pytest tests/e2e/test_stage_standalone.py -q` | **4 passed** |
+| `uv run pytest tests/e2e/test_facade_parity.py -q` | **3 passed** |
+| `uv run pytest tests/ -x -q --ignore=tests/e2e` | **49 passed in 8.3 s wall clock** (budget: under 15 s) |
+| `uv run ruff check . && uv run ruff format --check .` | **exit 0**, 19 files formatted |
+| `uv run python -c "import app; app.build_app()"` | **exit 0** |
+| `AVATAR_TRANSPORT=iframe uv run python -c "import app; app.build_app()"` | **exit 0** |
+| `grep -rc "screenshot" tests/e2e/` | **0** in every file |
+| `grep -rc "importmap" avatar/` | **0** in every file |
+| Seam break: `window.Avatar = {}` appended to `avatar-iframe.js` | `test_only_facade_assigns_window_avatar` **FAILED** as designed, then reverted and green |
+
+## User Setup Required
+
+None — no external service configuration required. Nothing was pushed to the `space` remote; deployment remains plan 01-05's job and the Space still correctly serves 503 `NO_APP_FILE` until then.
+
+## Next Phase Readiness
+
+- **Plan 01-05 (deploy spike) is materially de-risked.** The inline transport already runs against a real Gradio 6.22.0 server locally with `mountCount === 1` and `threeInstanceCount === 1`. What 01-05 still has to prove is deployment-specific: CDN reachability from `*.hf.space`, `set_static_paths` behaviour behind the Space proxy, cold-start time, and mobile. If it fails, `AVATAR_TRANSPORT=iframe` is a one-variable flip that is already tested green.
+- **Plan 01-06** replaces `DEMO_TIMELINE` and `demo-konnichiwa.wav` with generated output; the player contract (`{t, dur, viseme, weight}`, `'closed'` meaning all five at zero) is fixed and exercised.
+- **Plans 01-07 and 01-08** must add their methods to `avatar/turn-loop.js`. `test_turn_surface_lives_in_the_shared_module` fails if they land in a transport instead, and `test_transports_expose_identical_surfaces` fails if the live objects drift.
+- **Plan 01-09** should read `vrmMetaTitle = 'VRM1_Constraint_Twist_Sample'` and `__debug.vrmMeta` (a structured-clone-safe copy — `thumbnailImage` is deliberately stripped) for `test_vrm_meta_matches_licenses`.
+- **Concern, unchanged:** esm.sh is a volunteer-run CDN and every module load in this plan depends on it. `01-RESEARCH.md`'s recommendation to vendor into `avatar/vendor/` before the phase exits still stands and is not yet owned by any plan.
+- **Concern, new:** the two Gradio 6 API traps above mean `01-RESEARCH.md`'s `gr.HTML` section is not fully reliable. Any later plan copying `js_on_load` or `props` usage from it should copy from `avatar_component.py` instead.
+
+---
+*Phase: 01-voice-avatar-loop-skeleton*
+*Completed: 2026-08-27*
+
+## Self-Check: PASSED
+
+All 11 claimed files exist on disk and all four claimed commits (`94a5b15`, `7146e75`, `f822421`, `d6ea280`) are present in the git history.