feat(01-03): add both transports, the standalone stage page and the Gradio component

- avatar/avatar.js: inline transport, 145 lines of stagePort plumbing only
- avatar/avatar-iframe.js: postMessage transport, same facade and same turn loop
- both use a deferred event bus so events emitted during mountStage (notably the
no-expressionManager error) survive until installFacade builds the real one
- avatar/stage.html: iframe target and standalone debug harness; ?demo=1 plays a
canned WAV against a hand-authored placeholder timeline
- avatar/assets/demo-konnichiwa.wav: 24000 Hz mono 16-bit, 1.129 s
- avatar_component.py + app.py: AVATAR_TRANSPORT selects the module in one place
- vrm-stage.js: reword the import-map comment so the stage core names no host
- ignore and un-lint Gradio's auto-generated .pyi component stub

.gitignore

@@ -7,3 +7,9 @@ node_modules/
 .env
 voicevox_runtime/
 test-results/
+
+# Gradio rewrites a .pyi type stub next to every module that subclasses a component
+# (gradio/component_meta.py calls create_or_modify_pyi unconditionally at class
+# creation, with no opt-out). It is regenerated on every import and its import order
+# is not ours to fix, so it is build output, not source.
+*.pyi

app.py

@@ -0,0 +1,38 @@
+"""Space entry point: assembly only.
+
+No logic and no module-level mutable state lives here. Gradio shares module globals
+across every visitor session, so the discipline starts now, while there is still
+nothing to share.
+"""
+
+import os
+
+import gradio as gr
+
+from japanese_avatar.ui.avatar_component import VrmStage
+
+# Serves avatar/ straight off disk, bypassing the Gradio cache, which is how the
+# browser reaches avatar.js, stage.html and tutor.vrm. Deliberately one dedicated
+# directory: this call's own docstring warns that ALL files under a listed path
+# become network-reachable.
+gr.set_static_paths(["avatar"])
+
+
+def gpu_disabled() -> bool:
+    """SC-4's kill switch: the whole turn loop must complete with DISABLE_GPU=1.
+
+    Read per call rather than captured at import so a Space restart with the variable
+    flipped takes effect without a code change.
+    """
+    return os.environ.get("DISABLE_GPU", "0").strip().lower() in {"1", "true", "yes"}
+
+
+def build_app() -> gr.Blocks:
+    """Build the Blocks app. Importable and callable from tests without launching."""
+    with gr.Blocks(title="Japanese Learning Avatar", fill_height=True) as demo:
+        VrmStage()
+    return demo
+
+
+if __name__ == "__main__":
+    build_app().launch()

avatar/assets/demo-konnichiwa.wav

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:4297f70e5b9e41c392c6f9f9457dd72b07470283a2bd038e1dd9d8cef4cdbdfa
+size 54236

avatar/avatar-iframe.js

@@ -0,0 +1,155 @@
+// avatar/avatar-iframe.js
+//
+// THE IFRAME TRANSPORT: the renderer lives inside avatar/stage.html, reachable only
+// by postMessage. This is the documented escape hatch for the inline spike.
+//
+// It is deliberately the same shape as avatar.js: build a six-method stagePort, then
+// call the SAME createTurnLoop and the SAME installFacade. Every method below is
+// message plumbing. There is no turn behaviour in this file, and there must never be
+// - it belongs in avatar/turn-loop.js so both transports get it at once.
+//
+// Note for later waves: microphone capture and ASR run in the PARENT document under
+// both transports, so nothing about them crosses this boundary. Only rendering and
+// audio playback live inside the frame.
+
+import { installFacade } from './facade.js';
+import { createTurnLoop } from './turn-loop.js';
+
+const STAGE_PATH = '/gradio_api/file=avatar/stage.html';
+// speak() resolves at speech-end, so a reply can legitimately take an utterance's
+// worth of time. This bound only exists so a dead frame fails loudly.
+const REPLY_TIMEOUT_MS = 60000;
+
+/**
+ * A bus that exists before the real one does. Identical in purpose to the one in
+ * avatar.js: the frame can report an error before installFacade() has built the event
+ * bus, and those events must not be lost. Buffers until connect(), then replays.
+ */
+function deferredBus() {
+  let sink = null;
+  const queued = [];
+  const emit = (name, data) => {
+    if (sink) sink(name, data);
+    else queued.push([name, data]);
+  };
+  emit.connect = (real) => {
+    sink = real;
+    while (queued.length > 0) {
+      const [name, data] = queued.shift();
+      sink(name, data);
+    }
+  };
+  return emit;
+}
+
+/**
+ * @param {HTMLElement} element the host-provided mount point
+ * @param {object}      props   at minimum { vrmUrl }; optional { stageUrl }
+ * @param {Function}    [trigger] host event sink
+ * @param {object}      [server]  host bridge, handed to the turn loop as a getter
+ */
+export async function boot(element, props = {}, trigger = null, server = null) {
+  if (window.Avatar && window.Avatar.__debug && window.Avatar.__debug.ready) {
+    return window.Avatar;
+  }
+
+  const emit = deferredBus();
+
+  const frame = document.createElement('iframe');
+  frame.title = 'avatar stage';
+  frame.allow = 'microphone; autoplay';
+  const stageUrl = props.stageUrl || STAGE_PATH;
+  frame.src = `${stageUrl}?vrm=${encodeURIComponent(props.vrmUrl || '')}`;
+  element.appendChild(frame);
+
+  const pending = new Map();
+  let seq = 0;
+
+  let announceReady = null;
+  const frameReady = new Promise((resolve) => {
+    announceReady = resolve;
+  });
+
+  window.addEventListener('message', (ev) => {
+    if (ev.source !== frame.contentWindow) return;
+    const msg = ev.data;
+    if (!msg || typeof msg.type !== 'string' || !msg.type.startsWith('avatar:')) return;
+
+    if (msg.type === 'avatar:frame-ready') {
+      announceReady();
+      return;
+    }
+    if (msg.type === 'avatar:event') {
+      emit(msg.event, msg.data);
+      return;
+    }
+    if (msg.type !== 'avatar:reply') return;
+
+    const slot = pending.get(msg.id);
+    if (!slot) return;
+    pending.delete(msg.id);
+    clearTimeout(slot.timer);
+    if (msg.ok) slot.resolve(msg.value);
+    else slot.reject(new Error(msg.error || `stage frame failed: ${msg.id}`));
+  });
+
+  /** One request, one reply, correlated by id. This is the whole transport. */
+  async function call(type, extra) {
+    await frameReady;
+    seq += 1;
+    const id = `m${seq}`;
+    return new Promise((resolve, reject) => {
+      const timer = setTimeout(() => {
+        pending.delete(id);
+        reject(new Error(`stage frame did not answer ${type} within ${REPLY_TIMEOUT_MS} ms`));
+      }, REPLY_TIMEOUT_MS);
+      pending.set(id, { resolve, reject, timer });
+      frame.contentWindow.postMessage({ ...extra, type, id }, '*');
+    });
+  }
+
+  // Byte-for-byte the same six names as the inline transport's stagePort. Only the
+  // bodies differ, and every body is one round trip.
+  const stagePort = {
+    mount: (vrmUrl) => call('avatar:mount', { vrmUrl: vrmUrl || props.vrmUrl }),
+    speak: (payload) => call('avatar:speak', { payload }),
+    replayCached: () => call('avatar:replay', {}),
+    setThinking: (value) => call('avatar:setThinking', { value }),
+    setListening: (value) => call('avatar:setListening', { value }),
+    getDebug: () => call('avatar:debug', {}),
+  };
+
+  const turnLoop = createTurnLoop({ stagePort, emit, getServer: () => server });
+
+  const installed = installFacade({
+    transport: 'iframe',
+    stagePort,
+    turnLoop,
+    onEmit: (name, data) => {
+      if (typeof trigger === 'function') trigger(name, data);
+    },
+  });
+
+  emit.connect(installed.emit);
+  await installed.avatar.mount(props.vrmUrl);
+  return installed.avatar;
+}
+
+/**
+ * What the host's watch('value', ...) calls. Identical to the inline transport's:
+ * routing a directive is not turn behaviour, it is one line of delegation.
+ */
+export function onDirective(value) {
+  if (value === null || value === undefined || value === '') return null;
+  let directive = value;
+  if (typeof value === 'string') {
+    try {
+      directive = JSON.parse(value);
+    } catch {
+      return null;
+    }
+  }
+  if (!directive || typeof directive !== 'object') return null;
+  if (!window.Avatar) throw new Error('onDirective called before boot()');
+  return window.Avatar.speak(directive);
+}

avatar/avatar.js

@@ -0,0 +1,145 @@
+// avatar/avatar.js
+//
+// THE INLINE TRANSPORT: the renderer lives in the same document as the host component.
+//
+// Its ONLY job is to build a six-method stagePort and hand it to the shared
+// installFacade. It implements no turn behaviour and it never assigns window.Avatar.
+// tests/test_transport_seam.py fails if either rule is broken here.
+
+import { getLastDecoded, playBuffer } from './audio-queue.js';
+import { installFacade } from './facade.js';
+import { makePlayer } from './lipsync.js';
+import { createTurnLoop } from './turn-loop.js';
+import { mountStage } from './vrm-stage.js';
+
+/**
+ * A bus that exists before the real one does.
+ *
+ * mountStage() needs an emit callback, but the facade's event bus is only created
+ * once installFacade() runs - which is after the stage is mounted. Anything emitted
+ * during mount (notably the 'error' raised when a VRM has no expressionManager, the
+ * exact symptom of a double three.js instance) would otherwise be dropped on the
+ * floor. This buffers until connect() and then replays in order.
+ */
+function deferredBus() {
+  let sink = null;
+  const queued = [];
+  const emit = (name, data) => {
+    if (sink) sink(name, data);
+    else queued.push([name, data]);
+  };
+  emit.connect = (real) => {
+    sink = real;
+    while (queued.length > 0) {
+      const [name, data] = queued.shift();
+      sink(name, data);
+    }
+  };
+  return emit;
+}
+
+/**
+ * @param {HTMLElement} element the host-provided mount point
+ * @param {object}      props   at minimum { vrmUrl }
+ * @param {Function}    [trigger] host event sink, so the backend also sees avatar events
+ * @param {object}      [server]  host bridge, handed to the turn loop as a getter
+ */
+export async function boot(element, props = {}, trigger = null, server = null) {
+  // Re-entry guard. key="vrm-stage" should stop the host re-running js_on_load at all,
+  // but if it ever does, returning the live object without remounting is what holds
+  // mountCount at 1 across 20 interactions (AVTR-01).
+  if (window.Avatar && window.Avatar.__debug && window.Avatar.__debug.ready) {
+    return window.Avatar;
+  }
+
+  const canvas = element.querySelector('#vrm-canvas');
+  if (!canvas) throw new Error('boot: no #vrm-canvas inside the mounted element');
+
+  const AudioCtor = window.AudioContext || window.webkitAudioContext;
+  const audioCtx = new AudioCtor();
+  const emit = deferredBus();
+
+  let stage = null;
+  let player = null;
+  let mounting = null;
+  let cached = null;
+
+  // Memoised: the stage is mounted exactly once no matter how many callers ask.
+  function ensureStage(vrmUrl) {
+    if (!mounting) {
+      mounting = (async () => {
+        stage = await mountStage(canvas, vrmUrl || props.vrmUrl, emit);
+        player = makePlayer(stage);
+        stage.setOnTick((dt) => player.tick(dt));
+        return stage;
+      })();
+    }
+    return mounting;
+  }
+
+  await ensureStage(props.vrmUrl);
+
+  // The stagePort is the ONLY thing that differs between transports. Here every
+  // method is a direct call; in the iframe transport every method is a round trip.
+  const stagePort = {
+    mount: (vrmUrl) => ensureStage(vrmUrl),
+
+    async speak(payload = {}) {
+      await ensureStage();
+      cached = payload;
+      return playBuffer(audioCtx, payload.audioUrl, emit, (when) =>
+        player.start(payload.timeline, audioCtx, when)
+      );
+    },
+
+    async replayCached() {
+      // The decoded buffer, not the URL: zero network requests, which is what
+      // plan 01-09's test_replay asserts with a browser request listener.
+      const buffer = getLastDecoded();
+      if (!buffer) throw new Error('nothing cached to re-play');
+      return playBuffer(audioCtx, buffer, emit, (when) =>
+        player.start(cached && cached.timeline, audioCtx, when)
+      );
+    },
+
+    setThinking: (value) => (stage ? stage.setThinking(value) : undefined),
+    setListening: (value) => (stage ? stage.setListening(value) : undefined),
+    getDebug: async () => (stage ? stage.getDebug() : {}),
+  };
+
+  const turnLoop = createTurnLoop({ stagePort, emit, getServer: () => server });
+
+  const installed = installFacade({
+    transport: 'inline',
+    stagePort,
+    turnLoop,
+    // The one host-aware line in the file: mirror avatar events onto the host's own
+    // event system so backend listeners see them too.
+    onEmit: (name, data) => {
+      if (typeof trigger === 'function') trigger(name, data);
+    },
+  });
+
+  emit.connect(installed.emit);
+  await installed.avatar.mount(props.vrmUrl);
+  return installed.avatar;
+}
+
+/**
+ * What the host's watch('value', ...) calls. Tolerates null, '' and already-parsed
+ * objects, because a component's initial value is empty and must not throw.
+ */
+export function onDirective(value) {
+  if (value === null || value === undefined || value === '') return null;
+  let directive = value;
+  if (typeof value === 'string') {
+    try {
+      directive = JSON.parse(value);
+    } catch {
+      return null;
+    }
+  }
+  if (!directive || typeof directive !== 'object') return null;
+  if (!window.Avatar) throw new Error('onDirective called before boot()');
+  return window.Avatar.speak(directive);
+}

avatar/stage.html

@@ -0,0 +1,188 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="utf-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1" />
+    <title>Avatar stage</title>
+    <style>
+      html,
+      body {
+        margin: 0;
+        height: 100%;
+        overflow: hidden;
+        background: transparent;
+      }
+      #vrm-canvas {
+        width: 100%;
+        height: 100%;
+        display: block;
+      }
+    </style>
+  </head>
+  <body>
+    <canvas id="vrm-canvas"></canvas>
+
+    <!--
+      This page has two jobs and both matter.
+
+      1. It is the IFRAME FALLBACK TARGET. avatar/avatar-iframe.js drives it entirely
+         through the postMessage protocol implemented at the bottom of this file.
+      2. It is the LOCAL DEBUG HARNESS. Open it directly - no Python, no host framework
+         - and the avatar renders, blinks, breathes and sways. With ?demo=1 it also
+         lip-syncs a canned utterance. If this page works and the deployed inline
+         component does not, the problem is the host, not three.js.
+
+      Query parameters: ?vrm=<url> (defaults to ./assets/tutor.vrm), ?demo=1
+    -->
+    <script type="module">
+      import { playBuffer, getLastDecoded } from './audio-queue.js';
+      import { makePlayer } from './lipsync.js';
+      import { mountStage } from './vrm-stage.js';
+
+      // PLACEHOLDER shaped like a real VOICEVOX timeline. These durations are
+      // hand-authored, NOT measured. Plan 01-06 replaces this with a timeline
+      // generated from a real AudioQuery. こんにちは = k o N n i ch i w a, chosen
+      // because the N gives a 'closed' viseme sandwiched between two vowels.
+      const DEMO_TIMELINE = [
+        { t: 0.0, dur: 0.1, viseme: 'closed', weight: 0.0 }, // prePhonemeLength
+        { t: 0.1, dur: 0.064, viseme: 'closed', weight: 0.0 }, // k
+        { t: 0.164, dur: 0.128, viseme: 'oh', weight: 1.0 }, // o
+        { t: 0.292, dur: 0.139, viseme: 'closed', weight: 0.0 }, // N
+        { t: 0.431, dur: 0.053, viseme: 'closed', weight: 0.0 }, // n
+        { t: 0.484, dur: 0.117, viseme: 'ih', weight: 1.0 }, // i
+        { t: 0.601, dur: 0.075, viseme: 'closed', weight: 0.0 }, // ch
+        { t: 0.676, dur: 0.107, viseme: 'ih', weight: 1.0 }, // i
+        { t: 0.783, dur: 0.043, viseme: 'closed', weight: 0.0 }, // w
+        { t: 0.826, dur: 0.203, viseme: 'aa', weight: 1.0 }, // a
+        { t: 1.029, dur: 0.1, viseme: 'closed', weight: 0.0 }, // postPhonemeLength
+      ];
+      const DEMO_AUDIO = './assets/demo-konnichiwa.wav';
+
+      const params = new URLSearchParams(location.search);
+      const vrmUrl = params.get('vrm') || './assets/tutor.vrm';
+      const wantDemo = params.get('demo') === '1';
+
+      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 });
+
+      const canvas = document.getElementById('vrm-canvas');
+      let audioCtx = null;
+      const ctx = () => {
+        if (!audioCtx) audioCtx = new (window.AudioContext || window.webkitAudioContext)();
+        return audioCtx;
+      };
+
+      let stage = null;
+      let player = null;
+      let mounting = null;
+      let cached = null;
+
+      function ensureStage(url) {
+        if (!mounting) {
+          mounting = (async () => {
+            stage = await mountStage(canvas, url || vrmUrl, emit);
+            player = makePlayer(stage);
+            // One tick fn drives the viseme player and mirrors the stage's debug
+            // object onto window.__stageDebug, so a browser test can read numbers
+            // instead of screenshotting a canvas.
+            stage.setOnTick((dt) => {
+              player.tick(dt);
+              window.__stageDebug = stage.getDebug();
+            });
+            window.__stageDebug = stage.getDebug();
+            return stage;
+          })();
+        }
+        return mounting;
+      }
+
+      async function speak(payload) {
+        const directive = payload || {};
+        await ensureStage();
+        cached = directive;
+        return playBuffer(ctx(), directive.audioUrl, emit, (when) =>
+          player.start(directive.timeline, ctx(), when)
+        );
+      }
+
+      async function replayCached() {
+        const buffer = getLastDecoded();
+        if (!buffer) throw new Error('nothing cached to re-play');
+        return playBuffer(ctx(), buffer, emit, (when) =>
+          player.start(cached && cached.timeline, ctx(), when)
+        );
+      }
+
+      async function runDemo() {
+        await ensureStage();
+        const c = ctx();
+        if (c.state === 'suspended') {
+          try {
+            await c.resume();
+          } catch {
+            /* still gesture-gated; the pointerdown handler below retries */
+          }
+        }
+        return speak({ audioUrl: DEMO_AUDIO, timeline: DEMO_TIMELINE, subtitle: 'こんにちは' });
+      }
+
+      // The postMessage protocol. parent -> frame requests, frame -> parent replies.
+      const HANDLERS = {
+        'avatar:mount': async (m) => {
+          await ensureStage(m.vrmUrl);
+          return stage.getDebug();
+        },
+        'avatar:speak': (m) => speak(m.payload),
+        'avatar:replay': () => replayCached(),
+        'avatar:setThinking': async (m) => {
+          await ensureStage();
+          stage.setThinking(m.value);
+          return !!m.value;
+        },
+        'avatar:setListening': async (m) => {
+          await ensureStage();
+          stage.setListening(m.value);
+          return !!m.value;
+        },
+        'avatar:debug': async () => (stage ? stage.getDebug() : {}),
+      };
+
+      window.addEventListener('message', async (ev) => {
+        const m = ev.data;
+        if (!m || typeof m.type !== 'string') return;
+        const handler = HANDLERS[m.type];
+        if (!handler) return;
+        try {
+          const value = await handler(m);
+          post({ type: 'avatar:reply', id: m.id, ok: true, value: value === undefined ? null : value });
+        } catch (err) {
+          post({
+            type: 'avatar:reply',
+            id: m.id,
+            ok: false,
+            error: String((err && err.message) || err),
+          });
+        }
+      });
+
+      // Mount eagerly so the VRM download starts immediately and so opening this file
+      // directly shows a living avatar with no driver at all.
+      ensureStage().catch((err) =>
+        emit('error', { message: String((err && err.message) || err), where: 'mount' })
+      );
+
+      if (wantDemo) {
+        runDemo().catch((err) =>
+          emit('error', { message: String((err && err.message) || err), where: 'demo' })
+        );
+        // Browsers that gate audio behind a gesture: one click and the demo runs.
+        document.addEventListener('pointerdown', () => {
+          if (ctx().state !== 'running') runDemo();
+        });
+      }
+
+      post({ type: 'avatar:frame-ready' });
+    </script>
+  </body>
+</html>

avatar/vrm-stage.js

@@ -61,8 +61,9 @@ export async function mountStage(canvasEl, vrmUrl, emit = () => {}) {
   // https://esm.sh/three@0.185.1/es2022/three.mjs, so the browser's module map
   // guarantees a single instance. Dropping ?deps= gives two instances and the VRM
   // silently degrades to a T-posed glTF with no humanoid and no expressions.
-  // No import map: Gradio's frontend is an already-booted ES-module app, and a late
-  // import map throws "An import map is added after module script load was triggered."
+  // No import map: the host page is an already-booted ES-module app, so module
+  // resolution has begun long before this file runs and a late import map throws
+  // "An import map is added after module script load was triggered."
   const [THREE, { GLTFLoader }, { VRMLoaderPlugin, VRMUtils }] = await Promise.all([
     import(THREE_URL),
     import(LOADER_URL),

pyproject.toml

@@ -55,7 +55,10 @@ target-version = "py312"
 # ruff 0.16+ lints and formats Python code blocks embedded in Markdown. Planning docs,
 # research notes and design snippets are prose, not source: excluding *.md keeps the lint
 # gate about shipped Python and stops doc snippets from failing `ruff format --check`.
-extend-exclude = ["avatar/vendor", "*.md"]
+# *.pyi: Gradio auto-generates a type stub beside any module that subclasses a
+# component, with no opt-out. It is generated output we cannot edit, so it is not
+# subject to our lint gate.
+extend-exclude = ["avatar/vendor", "*.md", "*.pyi"]
 
 [tool.ruff.lint]
 select = ["E", "F", "I", "UP", "B", "SIM"]

src/japanese_avatar/ui/avatar_component.py

@@ -0,0 +1,56 @@
+"""The single gr.HTML component that owns the WebGL canvas.
+
+One env var, read in one place, chooses which transport module ``js_on_load``
+imports. Everything downstream of that import - the facade, the turn loop, the
+renderer - is identical between the two, which is what makes the fallback a flag
+flip rather than a re-plan.
+"""
+
+import os
+
+import gradio as gr
+
+AVATAR_TRANSPORT = os.environ.get("AVATAR_TRANSPORT", "inline")  # "inline" | "iframe"
+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));
+"""
+
+_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));
+"""
+
+
+class VrmStage(gr.HTML):
+    """The single gr.HTML component that owns the WebGL canvas.
+
+    Mounted with key="vrm-stage" so Gradio never remounts it across re-renders;
+    AVTR-01 requires mountCount to stay at 1 over 20 interactions.
+    """
+
+    def __init__(self, **kwargs):
+        super().__init__(
+            value="",
+            html_template='<div class="vrm-stage"><canvas id="vrm-canvas"></canvas></div>',
+            css_template=(
+                ".vrm-stage{position:relative;width:100%;height:100%;min-height:480px}"
+                "#vrm-canvas{width:100%;height:100%;display:block}"
+                ".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},
+            container=False,
+            padding=False,
+            min_height=480,
+            key="vrm-stage",
+            preserved_by_key="value",
+            elem_id="vrm-stage",
+            **kwargs,
+        )