test(01-03): enforce the transport seam statically and in a real browser

- tests/test_transport_seam.py: 36 static cases; no stage-core or shared module may
name the host framework, no transport may assign window.Avatar or implement turn
behaviour, and AVATAR_SURFACE is parsed from facade.js rather than duplicated
- host-token checks are case-insensitive, so a capitalised mention cannot slip past
- tests/e2e/test_stage_standalone.py: 4 tests against avatar/stage.html on a static
server - one three.mjs instance, idle life, demo lip-sync, no duplicate-instance
console warning. Sampling runs in-page at frame rate: a 250 ms poll would miss a
120 ms blink on most runs and be flaky by construction
- tests/e2e/test_facade_parity.py: boots the real app twice, once per transport, and
compares the live method sets, debug keys and deferred-method errors
- stage.html: mirror the event stream onto window.__stageEvents so the standalone
harness can assert on speech-end with no driver on the other side
- avatar_component.py: js_on_load is compiled into a NON-async Function by gradio
6.22.0, so the documented top-level await is a SyntaxError and the component never
booted; wrap in an async IIFE with its own catch
- avatar_component.py: custom props are **kwargs on gr.HTML, not a props= dict; the
dict form made props.vrmUrl undefined and GLTFLoader threw

avatar/stage.html

@@ -64,7 +64,16 @@
 
       const host = window.parent !== window ? window.parent : null;
       const post = (msg) => host && host.postMessage(msg, '*');
-      const emit = (event, data) => post({ type: 'avatar:event', event, data });
+
+      // Opened standalone there is no parent to post to, so the event stream would
+      // vanish. Mirroring it onto window.__stageEvents is the harness counterpart of
+      // window.__stageDebug: it lets a browser test assert on speech-start /
+      // speech-end / error without a driver on the other side of the boundary.
+      window.__stageEvents = [];
+      const emit = (event, data) => {
+        window.__stageEvents.push({ event, data, at: performance.now() });
+        post({ type: 'avatar:event', event, data });
+      };
 
       const canvas = document.getElementById('vrm-canvas');
       let audioCtx = null;

src/japanese_avatar/ui/avatar_component.py

@@ -15,17 +15,25 @@ VRM_URL = "/gradio_api/file=avatar/assets/tutor.vrm"
 
 # No `head=`: the modules load via dynamic import() inside js_on_load, so there is no
 # ordering constraint and no import map to be injected too late.
-_INLINE_JS = """
-    const m = await import('/gradio_api/file=avatar/avatar.js');
-    await m.boot(element, props, trigger, server);
-    watch('value', () => m.onDirective(props.value));
+#
+# The async IIFE is NOT decoration. Gradio 6.22.0 compiles this string with
+# `Function('element','trigger','props','server','upload','watch', js_on_load)` - a
+# plain, non-async function - so a top-level `await` here is a SyntaxError and the
+# component silently never boots. The published docs snippet uses top-level await and
+# does not work on this version. Verified against gradio/templates/frontend/assets.
+#
+# The IIFE also escapes Gradio's own try/catch, so it carries its own .catch: a boot
+# failure must reach the console, because that console line is plan 01-05's verdict.
+_BOOT_JS = """
+    (async () => {{
+        const m = await import('/gradio_api/file=avatar/{module}');
+        await m.boot(element, props, trigger, server);
+        watch('value', () => m.onDirective(props.value));
+    }})().catch((err) => console.error('avatar boot failed:', err));
 """
 
-_IFRAME_JS = """
-    const m = await import('/gradio_api/file=avatar/avatar-iframe.js');
-    await m.boot(element, props, trigger, server);
-    watch('value', () => m.onDirective(props.value));
-"""
+_INLINE_JS = _BOOT_JS.format(module="avatar.js")
+_IFRAME_JS = _BOOT_JS.format(module="avatar-iframe.js")
 
 
 class VrmStage(gr.HTML):
@@ -45,7 +53,12 @@ class VrmStage(gr.HTML):
                 ".vrm-stage iframe{width:100%;height:100%;border:0;display:block}"
             ),
             js_on_load=_IFRAME_JS if AVATAR_TRANSPORT == "iframe" else _INLINE_JS,
-            props={"vrmUrl": VRM_URL, "transport": AVATAR_TRANSPORT},
+            # Custom props are **kwargs on gr.HTML, NOT a props= dict. Passing
+            # props={"vrmUrl": ...} creates a single prop literally named "props"
+            # and js_on_load then reads props.vrmUrl as undefined - the VRM URL
+            # reaches GLTFLoader as undefined and the avatar never mounts.
+            vrmUrl=VRM_URL,
+            transport=AVATAR_TRANSPORT,
             container=False,
             padding=False,
             min_height=480,

tests/e2e/conftest.py

@@ -0,0 +1,125 @@
+"""Browser-suite plumbing: a static server for the standalone harness and a real
+Gradio app subprocess per transport for the parity proof.
+
+Both suites run entirely locally. They must be green BEFORE plan 01-05 deploys
+anything, because that is what makes 01-05's verdict interpretable: if standalone
+passes and deployed fails, the problem is the host, not three.js.
+"""
+
+from __future__ import annotations
+
+import functools
+import http.server
+import os
+import socket
+import subprocess
+import sys
+import threading
+import time
+import urllib.error
+import urllib.request
+from pathlib import Path
+
+import pytest
+
+REPO_ROOT = Path(__file__).resolve().parent.parent.parent
+APP_BOOT_TIMEOUT_S = 180
+
+
+def _free_port() -> int:
+    with socket.socket() as s:
+        s.bind(("127.0.0.1", 0))
+        return s.getsockname()[1]
+
+
+@pytest.fixture(scope="session")
+def browser_type_launch_args(browser_type_launch_args):
+    """Chromium's autoplay policy leaves an ungestured AudioContext suspended forever.
+
+    A suspended context never advances currentTime, so the viseme player would never
+    tick and 'speech-end' would never fire - the test would be measuring the autoplay
+    policy rather than the lip-sync. The flag is the standard way to opt out.
+    """
+    return {
+        **browser_type_launch_args,
+        "args": [
+            *browser_type_launch_args.get("args", []),
+            "--autoplay-policy=no-user-gesture-required",
+        ],
+    }
+
+
+@pytest.fixture(scope="session")
+def static_server() -> str:
+    """Serve the repo root so /avatar/stage.html and /avatar/assets/tutor.vrm resolve."""
+    handler = functools.partial(http.server.SimpleHTTPRequestHandler, directory=str(REPO_ROOT))
+    server = http.server.ThreadingHTTPServer(("127.0.0.1", _free_port()), handler)
+    server.daemon_threads = True
+    threading.Thread(target=server.serve_forever, daemon=True).start()
+    try:
+        yield f"http://127.0.0.1:{server.server_port}"
+    finally:
+        server.shutdown()
+        server.server_close()
+
+
+def _wait_for_http(url: str, proc: subprocess.Popen, timeout_s: int) -> None:
+    deadline = time.time() + timeout_s
+    while time.time() < deadline:
+        if proc.poll() is not None:
+            out = proc.stdout.read() if proc.stdout else ""
+            raise RuntimeError(f"app.py exited with {proc.returncode}:\n{out}")
+        try:
+            with urllib.request.urlopen(url, timeout=2) as response:
+                if response.status == 200:
+                    return
+        except (urllib.error.URLError, TimeoutError, ConnectionError, OSError):
+            time.sleep(0.5)
+    raise RuntimeError(f"app.py did not answer {url} within {timeout_s}s")
+
+
+@pytest.fixture(scope="session")
+def gradio_apps():
+    """Start app.py once per AVATAR_TRANSPORT value and return its base URL.
+
+    One env var is the entire difference between the two deployments, which is the
+    property the parity suite exists to prove.
+    """
+    started: dict[str, tuple[str, subprocess.Popen]] = {}
+
+    def start(transport: str) -> str:
+        if transport not in started:
+            port = _free_port()
+            env = {
+                **os.environ,
+                "AVATAR_TRANSPORT": transport,
+                "GRADIO_SERVER_NAME": "127.0.0.1",
+                "GRADIO_SERVER_PORT": str(port),
+                "GRADIO_ANALYTICS_ENABLED": "False",
+            }
+            proc = subprocess.Popen(  # noqa: S603
+                [sys.executable, "app.py"],
+                cwd=str(REPO_ROOT),
+                env=env,
+                stdout=subprocess.PIPE,
+                stderr=subprocess.STDOUT,
+                text=True,
+            )
+            url = f"http://127.0.0.1:{port}/"
+            try:
+                _wait_for_http(url, proc, APP_BOOT_TIMEOUT_S)
+            except Exception:
+                proc.kill()
+                raise
+            started[transport] = (url, proc)
+        return started[transport][0]
+
+    try:
+        yield start
+    finally:
+        for _url, proc in started.values():
+            proc.terminate()
+            try:
+                proc.wait(timeout=15)
+            except subprocess.TimeoutExpired:
+                proc.kill()

tests/e2e/test_facade_parity.py

@@ -0,0 +1,106 @@
+"""Mechanical proof that the two transports expose the same object.
+
+The static tests in tests/test_transport_seam.py can only prove that no transport
+*writes* window.Avatar. These boot the real Gradio app twice - once per
+AVATAR_TRANSPORT value - and compare the LIVE objects, which is the only way to catch
+a method that resolves in one transport and silently does not in the other.
+
+Marked slow but NOT deployed: they run entirely locally and must be green before
+plan 01-05 deploys anything.
+"""
+
+from __future__ import annotations
+
+import pytest
+
+from tests.test_transport_seam import avatar_surface
+
+pytestmark = pytest.mark.slow
+
+TRANSPORTS = ("inline", "iframe")
+AVATAR_READY = "() => !!window.Avatar && !!window.Avatar.__debug && window.Avatar.__debug.ready"
+BOOT_TIMEOUT_MS = 120_000
+
+# Deliberately double-quoted and built from data: the surface list must come from
+# facade.js, never from a literal in this file.
+DEFERRED_PLAN = "01-08"
+DEFERRED_METHODS = ("dispatchTurn", "requestSlower")
+
+CALL_DEFERRED = """
+async (name) => {
+  try {
+    await window.Avatar[name]('x');
+    return { threw: false, message: '' };
+  } catch (err) {
+    return { threw: true, message: String((err && err.message) || err) };
+  }
+}
+"""
+
+
+@pytest.fixture(scope="session")
+def live_avatars(browser, gradio_apps):
+    """Boot each transport once and capture everything the three tests compare."""
+    captured = {}
+    for transport in TRANSPORTS:
+        url = gradio_apps(transport)
+        page = browser.new_page()
+        try:
+            page.goto(url)
+            page.wait_for_function(AVATAR_READY, timeout=BOOT_TIMEOUT_MS)
+            captured[transport] = {
+                "surface": page.evaluate(
+                    "() => Object.keys(window.Avatar).filter(k => k !== '__debug').sort()"
+                ),
+                "debug_keys": page.evaluate(
+                    "async () => Object.keys(await window.Avatar.getDebug()).sort()"
+                ),
+                "reported_transport": page.evaluate("() => window.Avatar.__debug.transport"),
+                "deferred": {name: page.evaluate(CALL_DEFERRED, name) for name in DEFERRED_METHODS},
+            }
+        finally:
+            page.close()
+    return captured
+
+
+def test_transports_expose_identical_surfaces(live_avatars):
+    inline = live_avatars["inline"]["surface"]
+    iframe = live_avatars["iframe"]["surface"]
+    expected = sorted(avatar_surface())
+
+    assert live_avatars["inline"]["reported_transport"] == "inline"
+    assert live_avatars["iframe"]["reported_transport"] == "iframe"
+    assert inline == iframe, (
+        "the transports have drifted; symmetric difference "
+        f"(inline ^ iframe) = {sorted(set(inline) ^ set(iframe))}"
+    )
+    assert inline == expected, (
+        "the live object does not match AVATAR_SURFACE parsed from avatar/facade.js; "
+        f"symmetric difference = {sorted(set(inline) ^ set(expected))}"
+    )
+
+
+def test_transports_expose_identical_debug_keys(live_avatars):
+    inline = live_avatars["inline"]["debug_keys"]
+    iframe = live_avatars["iframe"]["debug_keys"]
+    assert inline == iframe, (
+        "__debug has drifted between transports; symmetric difference "
+        f"(inline ^ iframe) = {sorted(set(inline) ^ set(iframe))}"
+    )
+
+
+def test_deferred_methods_fail_loudly_not_silently(live_avatars):
+    """The stubs are placeholders, not accidental no-ops.
+
+    Plan 01-08 deletes this test when it implements the methods for real.
+    """
+    for transport in TRANSPORTS:
+        for name, outcome in live_avatars[transport]["deferred"].items():
+            assert outcome["threw"], (
+                f"{transport}: Avatar.{name}() returned instead of throwing; a silent "
+                "no-op is exactly what the deferred stubs exist to prevent"
+            )
+            assert DEFERRED_PLAN in outcome["message"], (
+                f"{transport}: Avatar.{name}() threw {outcome['message']!r}, which does "
+                f"not name plan {DEFERRED_PLAN}"
+            )

tests/e2e/test_stage_standalone.py

@@ -0,0 +1,132 @@
+"""The stage core, proven in a real browser with no Python and no host framework.
+
+avatar/stage.html is opened directly off a static server. If these four tests pass and
+the deployed component later fails, the fault is provably in the host, not in three.js,
+the VRM or the viseme player. That is the whole point of running them before 01-05.
+
+Marked slow but NOT deployed: they need no Space and must be green before one exists.
+"""
+
+from __future__ import annotations
+
+import pytest
+
+pytestmark = pytest.mark.slow
+
+# The VRM is 10.3 MiB and the module graph another ~1.4 MiB. This is a real download.
+READY_TIMEOUT_MS = 30_000
+STAGE_READY = "() => !!window.__stageDebug && window.__stageDebug.ready === true"
+
+# Sampling happens INSIDE the page at animation-frame rate rather than by polling from
+# Python. A blink is a 120 ms ramp on a 1.8-5.8 s schedule, so its peak occupies well
+# under 2% of the wall clock: a 250 ms poll would miss it on most runs and the test
+# would be flaky by construction. Same sampler, ~60x the rate, no flakiness.
+IDLE_SAMPLER = """
+async (ms) => {
+  const blink = [], breath = [];
+  const t0 = performance.now();
+  return await new Promise((resolve) => {
+    const step = () => {
+      const d = window.__stageDebug;
+      if (d) { blink.push(d.blinkValue); breath.push(d.breathValue); }
+      if (performance.now() - t0 >= ms) resolve({ blink, breath });
+      else requestAnimationFrame(step);
+    };
+    requestAnimationFrame(step);
+  });
+}
+"""
+
+# Peak-hold per viseme until the utterance ends, then the settled values afterwards.
+VISEME_SAMPLER = """
+async (ms) => {
+  const names = ['aa', 'ih', 'ou', 'ee', 'oh'];
+  const peak = {}; for (const n of names) peak[n] = 0;
+  const t0 = performance.now();
+  const ended = () => (window.__stageEvents || []).some((e) => e.event === 'speech-end');
+  return await new Promise((resolve) => {
+    const step = () => {
+      const d = window.__stageDebug;
+      if (d && d.currentVisemes) {
+        for (const n of names) peak[n] = Math.max(peak[n], d.currentVisemes[n]);
+      }
+      if ((ended() && d && names.every((n) => d.currentVisemes[n] === 0))
+          || performance.now() - t0 >= ms) {
+        resolve({ peak, settled: d ? d.currentVisemes : null, ended: ended() });
+      } else {
+        requestAnimationFrame(step);
+      }
+    };
+    requestAnimationFrame(step);
+  });
+}
+"""
+
+
+def _open_stage(page, static_server, query: str = ""):
+    page.goto(f"{static_server}/avatar/stage.html{query}")
+    page.wait_for_function(STAGE_READY, timeout=READY_TIMEOUT_MS)
+    return page.evaluate("() => window.__stageDebug")
+
+
+def test_stage_boots_with_one_three_instance(page, static_server):
+    """The single structural fact the whole renderer depends on."""
+    debug = _open_stage(page, static_server, "?demo=1")
+
+    assert debug["threeInstanceCount"] == 1, (
+        f"expected exactly one three.mjs resource entry, got {debug['threeInstanceCount']}; "
+        "the ?deps=three@0.185.1 pin has stopped converging and the VRM is a T-posed glTF"
+    )
+    assert isinstance(debug["vrmMetaTitle"], str) and debug["vrmMetaTitle"], (
+        "vrmMetaTitle is empty; the VRM loaded without its VRMC_vrm.meta block"
+    )
+
+
+def test_idle_life_values_change(page, static_server):
+    """AVTR-01's substance: the avatar is alive before any audio exists.
+
+    12 s spans at least one blink on the 1.8-5.8 s schedule and three 4 s breath cycles.
+    Never a pixel diff - the canvas is opaque, the numbers are not.
+    """
+    _open_stage(page, static_server)
+    samples = page.evaluate(IDLE_SAMPLER, 12_000)
+
+    breath = samples["breath"]
+    blink = samples["blink"]
+    assert len({round(b, 4) for b in breath}) > 5, (
+        f"breathValue took only {len(set(breath))} distinct values over 12 s; it is not breathing"
+    )
+    assert max(blink) > 0.5, (
+        f"blinkValue peaked at {max(blink)} over 12 s; no blink completed its 0 -> 1 -> 0 ramp"
+    )
+
+
+def test_demo_timeline_drives_visemes(page, static_server):
+    """A hardcoded timeline against a canned WAV, clocked off the AudioContext."""
+    _open_stage(page, static_server, "?demo=1")
+    result = page.evaluate(VISEME_SAMPLER, 20_000)
+
+    peak = result["peak"]
+    assert result["ended"], f"no speech-end was emitted; peaks were {peak}"
+
+    opened = [name for name in ("aa", "ih", "oh") if peak[name] > 0.5]
+    assert len(opened) >= 3, (
+        f"only {opened} exceeded 0.5; こんにちは drives o, i, i and a, so aa/ih/oh "
+        f"must all open. Peaks: {peak}"
+    )
+    assert all(value == 0 for value in result["settled"].values()), (
+        f"the mouth did not shut after speech-end: {result['settled']}"
+    )
+
+
+def test_console_has_no_multiple_three_warning(page, static_server):
+    """The console message that means the ?deps= pin silently stopped working."""
+    messages: list[str] = []
+    page.on("console", lambda m: messages.append(m.text))
+    page.on("pageerror", lambda e: messages.append(str(e)))
+
+    _open_stage(page, static_server, "?demo=1")
+    page.wait_for_timeout(3_000)
+
+    offenders = [m for m in messages if "Multiple instances of Three.js" in m]
+    assert not offenders, f"three.js reported duplicate instances: {offenders}"

tests/test_transport_seam.py

@@ -0,0 +1,139 @@
+"""The transport seam. If the gr.HTML spike fails, only the stagePort changes.
+
+These tests exist so that stays true as the phase progresses. Plans 01-07 and 01-08
+add turn behaviour; these tests fail if it lands in a transport file instead of in
+the shared turn-loop module.
+"""
+
+import re
+from pathlib import Path
+
+import pytest
+
+# Resolved from this file rather than the process cwd: the quick loop is documented as
+# running from the repo root, but a relative Path() would make that a silent
+# precondition of every assertion below.
+AVATAR = Path(__file__).resolve().parent.parent / "avatar"
+CORE = ["vrm-stage.js", "lipsync.js", "audio-queue.js"]
+SHARED = ["facade.js", "turn-loop.js"]
+TRANSPORTS = ["avatar.js", "avatar-iframe.js"]
+GRADIO_TOKENS = ["gradio", "gradio_api", "server.", "trigger("]
+AMPLITUDE_TOKENS = ["AnalyserNode", "getByteFrequencyData", "getFloatTimeDomainData"]
+TURN_SURFACE = ["startListening", "stopListening", "dispatchTurn", "requestSlower"]
+
+
+def src(name: str) -> str:
+    return (AVATAR / name).read_text(encoding="utf-8")
+
+
+def avatar_surface() -> list[str]:
+    """Parse AVATAR_SURFACE out of facade.js. Never duplicate the list in the test."""
+    m = re.search(r"AVATAR_SURFACE\s*=\s*\[(.*?)\]", src("facade.js"), re.S)
+    assert m, "AVATAR_SURFACE not found in avatar/facade.js"
+    return re.findall(r"'([a-zA-Z]+)'", m.group(1))
+
+
+@pytest.mark.parametrize("name", CORE)
+def test_stage_core_is_gradio_free(name):
+    lowered = src(name).lower()
+    for tok in GRADIO_TOKENS:
+        assert tok.lower() not in lowered, (
+            f"{name} references {tok!r}; the stage core must stay transport-agnostic"
+        )
+
+
+@pytest.mark.parametrize("name", CORE)
+def test_no_amplitude_lipsync(name):
+    for tok in AMPLITUDE_TOKENS:
+        assert tok not in src(name), f"{name} uses {tok!r}; AVTR-02 disqualifies amplitude lip-sync"
+
+
+@pytest.mark.parametrize("name", SHARED)
+def test_shared_modules_are_gradio_free(name):
+    lowered = src(name).lower()
+    for tok in GRADIO_TOKENS:
+        assert tok.lower() not in lowered, f"{name} must not know about Gradio"
+
+
+def test_lipsync_uses_audiocontext_clock():
+    s = src("lipsync.js")
+    assert "currentTime" in s
+    assert "setTimeout" not in s
+    assert "requestAnimationFrame" not in s  # the stage owns the loop; the player is a tick fn
+
+
+def test_module_urls_are_deps_pinned():
+    s = src("vrm-stage.js")
+    assert "https://esm.sh/three@0.185.1" in s
+    assert "https://esm.sh/@pixiv/three-vrm@3.5.5?deps=three@0.185.1" in s
+    assert "importmap" not in s
+
+
+def test_only_facade_assigns_window_avatar():
+    """One facade builder. Two transports cannot drift if only one of them writes the object."""
+    for p in AVATAR.glob("*.js"):
+        assigns = re.search(r"window\.Avatar\s*=", p.read_text(encoding="utf-8"))
+        if p.name == "facade.js":
+            assert assigns, "facade.js must be the one that installs window.Avatar"
+        else:
+            assert not assigns, f"{p.name} assigns window.Avatar; only facade.js may"
+
+
+@pytest.mark.parametrize("name", TRANSPORTS)
+def test_transports_only_do_plumbing(name):
+    """A transport builds a stagePort and delegates. It never implements turn behaviour."""
+    s = src(name)
+    assert "installFacade" in s and "createTurnLoop" in s, (
+        f"{name} must use the shared facade/turn loop"
+    )
+    for member in TURN_SURFACE:
+        assert f"function {member}" not in s and f"{member}(text" not in s, (
+            f"{name} implements {member}; turn behaviour belongs in avatar/turn-loop.js "
+            "or the iframe fallback silently loses it"
+        )
+
+
+@pytest.mark.parametrize(
+    "member",
+    [
+        "mount",
+        "speak",
+        "replay",
+        "setListening",
+        "setThinking",
+        "on",
+        "getDebug",
+        "startListening",
+        "stopListening",
+        "dispatchTurn",
+        "requestSlower",
+    ],
+)
+def test_surface_member_is_declared_once(member):
+    """Every promised method must resolve in facade.js's surface list."""
+    assert member in avatar_surface()
+
+
+@pytest.mark.parametrize("member", TURN_SURFACE)
+def test_turn_surface_lives_in_the_shared_module(member):
+    assert member in src("turn-loop.js"), (
+        f"{member} must be defined in avatar/turn-loop.js so BOTH transports get it"
+    )
+
+
+@pytest.mark.parametrize(
+    "key",
+    [
+        "ready",
+        "mountCount",
+        "vrmMetaTitle",
+        "threeInstanceCount",
+        "currentVisemes",
+        "blinkValue",
+        "clockOffset",
+        "transport",
+    ],
+)
+def test_debug_contract_keys_present(key):
+    joined = src("facade.js") + src("turn-loop.js") + src("vrm-stage.js")
+    assert key in joined, f"__debug.{key} is required by 01-VALIDATION.md Observable Signals"