feat(02-06): analyze/translate/languageInfo on the shared turn loop; tokens on the turn event

- turn-loop.js: three host round trips implemented once so both transports get
them; requireBridge()/checkResult() share the missing-bridge, undefined and
{error} checks with dispatchTurn (whose setThinking-before-first-await order
is unchanged); the turn event carries tokens and the debug slice gains the
language keys, initialised at construction
- facade.js: AVATAR_SURFACE += analyze, translate, languageInfo
- tests/test_transport_seam.py: language surface declared once, lives only in
the shared module, debug keys present, tokens inside the turn event, every
bridge call packs one payload

avatar/facade.js

@@ -33,6 +33,9 @@
  * unlockAudio     () -> state string, SYNCHRONOUS: resumes the AudioContext inside the
  *                 caller's user gesture. Resolved from the stagePort so a host can
  *                 pre-unlock on any tap; the turn loop also calls it itself - plan 01-11
+ * analyze         (text) -> {tokens}      - learner lines are tokenised through the bridge (plan 02-06)
+ * translate       (text, lineId) -> {text} - CPU MT on the host; cached per line by the host page (D-17)
+ * languageInfo    () -> the host's language-asset facts (sizes, warm-up, container env)
  */
 export const AVATAR_SURFACE = [
   'mount',
@@ -47,6 +50,9 @@ export const AVATAR_SURFACE = [
   'dispatchTurn',
   'requestSlower',
   'unlockAudio',
+  'analyze',
+  'translate',
+  'languageInfo',
 ];
 
 /**

avatar/turn-loop.js

@@ -29,6 +29,13 @@
 // gate audio behind a gesture (iOS Safari; Chromium in a cross-origin embed) refuse a
 // resume() issued after the server round trip, which is exactly where the only other
 // resume() lives (audio-queue.js), and the owner's phone was silent for that reason.
+//
+// Plan 02-06: analyze / translate / languageInfo are host round trips implemented HERE so
+// both transports get them; the host page renders tokens and caches translations (D-17);
+// this module holds no per-line cache. Every bridge call packs ONE payload object (the
+// host's bridge would turn two arguments into a list), and every result goes through the
+// same two checks dispatchTurn applies: `undefined` (the host's client swallowed an HTTP
+// error) and `{error}` (the far side refused the request without raising).
 
 import { createAsr } from './asr.js';
 import { createMic, isHallucination, REJECT } from './mic.js';
@@ -81,6 +88,18 @@ export function createTurnLoop({
     lastTranscript: null,
     micRejectedCount: 0,
     micLastRejectReason: null,
+    // Plan 02-06: the language bridge. Tokens ride on every directive; the learner's own
+    // lines are tokenised through analyze(); translations are counted and timed here and
+    // cached by the host page, never by this module (D-17).
+    analyzeCount: 0,
+    lastAnalyzeMs: null,
+    lastTokenCount: null,
+    lastTokens: null,
+    translateCount: 0,
+    lastTranslateMs: null,
+    lastTranslation: null,
+    lastTranslateError: null,
+    languageInfo: null,
   };
 
   // Set when a turn or a replay has been dispatched and its speech-start has not yet
@@ -176,6 +195,33 @@ export function createTurnLoop({
     return err instanceof Error ? err : new Error(message);
   }
 
+  /**
+   * The host bridge, or a throw that names the missing function. The standalone stage
+   * (asr-harness.html, stage.html) has no bridge at all; a host that forgot to register
+   * a server function has a bridge without the method. Both are the same failure to a
+   * caller.
+   */
+  function requireBridge(name, without) {
+    const bridge = getServer();
+    if (!bridge || typeof bridge[name] !== 'function') {
+      throw new Error(`no host bridge: the standalone stage has ${without}`);
+    }
+    return bridge;
+  }
+
+  /**
+   * The two checks every bridge result needs. The host's client swallows an HTTP error
+   * into `undefined`, and the far side answers a bad request with {error} rather than
+   * raising, so both are checked before a result is trusted.
+   */
+  function checkResult(result, what) {
+    if (result === undefined || result === null) {
+      throw new Error(`the host returned nothing for ${what} - see its log`);
+    }
+    if (result.error) throw new Error(result.error);
+    return result;
+  }
+
   /**
    * One turn: text in, speech out. Resolves at speech-end with a summary of the turn.
    *
@@ -193,12 +239,11 @@ export function createTurnLoop({
     const busy = busyReason();
     if (busy) throw fail('dispatchTurn', new Error(busy));
 
-    const bridge = getServer();
-    if (!bridge || typeof bridge.turn !== 'function') {
-      throw fail(
-        'dispatchTurn',
-        new Error('no host bridge: the standalone stage has nothing to synthesise with')
-      );
+    let bridge;
+    try {
+      bridge = requireBridge(greeting ? 'greeting' : 'turn', 'nothing to synthesise with');
+    } catch (err) {
+      throw fail('dispatchTurn', err);
     }
 
     performance.mark('turn:dispatch');
@@ -208,18 +253,13 @@ export function createTurnLoop({
     emit('turn-start', { text: greeting ? null : text, speed, greeting });
 
     try {
-      const directive = greeting
-        ? await bridge.greeting()
-        : await bridge.turn({ text: String(text ?? ''), speed });
+      const directive = checkResult(
+        greeting ? await bridge.greeting() : await bridge.turn({ text: String(text ?? ''), speed }),
+        'this turn'
+      );
       performance.mark('turn:response');
       const responseMs = Math.round(now() - dispatchedAt);
 
-      // The host's client swallows an HTTP error into `undefined`, and the far side
-      // answers a bad request with {error} rather than raising, so both are checked.
-      if (directive === undefined || directive === null) {
-        throw new Error('the host returned nothing for this turn - see its log');
-      }
-      if (directive.error) throw new Error(directive.error);
       if (!directive.audio_url || !Array.isArray(directive.timeline)) {
         throw new Error('the host returned a directive with no audio or no timeline');
       }
@@ -229,12 +269,17 @@ export function createTurnLoop({
       state.lastSubtitle = directive.subtitle ?? null;
       state.lastSpeed = directive.speed ?? speed;
       state.lastStageTimings = directive.timings ?? null;
+      // Tokens are optional on the wire (an older host, or an analysis that failed and
+      // yielded []): the turn still speaks, the host page just has nothing to make tappable.
+      state.lastTokens = Array.isArray(directive.tokens) ? directive.tokens : [];
+      state.lastTokenCount = state.lastTokens.length;
       state.lastError = null;
       emit('turn', {
         turnId: state.lastTurnId,
         subtitle: state.lastSubtitle,
         speed: state.lastSpeed,
         timings: state.lastStageTimings,
+        tokens: state.lastTokens,
         responseMs,
         greeting,
       });
@@ -311,6 +356,83 @@ export function createTurnLoop({
       return dispatchTurn(state.lastSubtitle, { speed: SLOWER_SPEED });
     },
 
+    /**
+     * Tokenise a learner line through the host's language core (plan 02-06). No audio is
+     * involved, so no unlockAudio() and no busy check: the host page calls this for the
+     * text the learner typed or the transcript ASR produced, then renders the tokens.
+     *
+     * @param {string} text
+     * @returns {Promise<{tokens: object[], timings: object|null}>}
+     */
+    async analyze(text) {
+      if (typeof text !== 'string' || !text.trim()) {
+        throw fail('analyze', new Error('analyze: text is required'));
+      }
+      const t0 = now();
+      try {
+        const bridge = requireBridge('analyze', 'no language core to analyze with');
+        const result = checkResult(await bridge.analyze({ text }), 'analyze');
+        state.analyzeCount += 1;
+        state.lastAnalyzeMs = Math.round(now() - t0);
+        return {
+          tokens: Array.isArray(result.tokens) ? result.tokens : [],
+          timings: result.timings ?? null,
+        };
+      } catch (err) {
+        throw fail('analyze', err);
+      }
+    },
+
+    /**
+     * Translate one line to English on the host's CPU (D-15). The host page caches the
+     * answer per line for the session (D-17) - this module deliberately does not, so the
+     * cache has exactly one owner. `lineId` is echoed back so the page can file it.
+     *
+     * @param {string} text
+     * @param {string|null} [lineId]
+     * @returns {Promise<{text: string, lineId: string|null, timings: object|null, ms: number}>}
+     */
+    async translate(text, lineId = null) {
+      if (typeof text !== 'string' || !text.trim()) {
+        throw fail('translate', new Error('translate: text is required'));
+      }
+      const t0 = now();
+      try {
+        const bridge = requireBridge('translate', 'no translator to translate with');
+        const result = checkResult(await bridge.translate({ text, line_id: lineId }), 'translate');
+        const ms = Math.round(now() - t0);
+        state.translateCount += 1;
+        state.lastTranslateMs = ms;
+        state.lastTranslation = result.text ?? null;
+        state.lastTranslateError = null;
+        return {
+          text: result.text,
+          lineId: result.line_id ?? lineId,
+          timings: result.timings ?? null,
+          ms,
+        };
+      } catch (err) {
+        state.lastTranslateError = String(err?.message ?? err);
+        throw fail('translate', err);
+      }
+    },
+
+    /**
+     * The host's language-asset facts (sizes, warm-up measurement, container env), read
+     * once through the bridge and kept on the debug slice so a deployed probe can assert
+     * on them after the fact.
+     */
+    async languageInfo() {
+      try {
+        const bridge = requireBridge('language_info', 'no language core to describe');
+        const info = checkResult(await bridge.language_info(), 'languageInfo');
+        state.languageInfo = info;
+        return info;
+      } catch (err) {
+        throw fail('languageInfo', err);
+      }
+    },
+
     /**
      * pointerdown on the push-to-talk control. The host binds the control; the behaviour
      * is here so both transports get it from one implementation.

tests/test_transport_seam.py

@@ -20,6 +20,16 @@ TRANSPORTS = ["avatar.js", "avatar-iframe.js"]
 GRADIO_TOKENS = ["gradio", "gradio_api", "server.", "trigger("]
 AMPLITUDE_TOKENS = ["AnalyserNode", "getByteFrequencyData", "getFloatTimeDomainData"]
 TURN_SURFACE = ["startListening", "stopListening", "dispatchTurn", "requestSlower"]
+# Plan 02-06. The language bridge: tokens for learner lines, CPU translation, asset facts.
+# Host round trips implemented once in turn-loop.js so both transports get them.
+LANGUAGE_SURFACE = ["analyze", "translate", "languageInfo"]
+LANGUAGE_DEBUG_KEYS = [
+    "analyzeCount",
+    "lastTokens",
+    "translateCount",
+    "lastTranslateMs",
+    "languageInfo",
+]
 # Plan 01-07. Mic capture and ASR run in the PARENT document under both transports -
 # only rendering and audio playback live inside the iframe - so these modules must hang
 # off the shared turn loop, never off a transport.
@@ -126,6 +136,9 @@ def test_transports_only_do_plumbing(name):
         "dispatchTurn",
         "requestSlower",
         "unlockAudio",
+        "analyze",
+        "translate",
+        "languageInfo",
     ],
 )
 def test_surface_member_is_declared_once(member):
@@ -467,3 +480,55 @@ def test_audio_state_is_published(name):
     """audioState is a published field on getDebug() from both transports and the
     standalone harness, so the strict-policy tests assert a number, not a silence."""
     assert "audioState" in src(name), f"{name} does not publish audioState"
+
+
+# --------------------------------------------------------------- plan 02-06: the language bridge
+#
+# Three new host round trips. Same seam, same rule: declared once in AVATAR_SURFACE,
+# implemented once in turn-loop.js, absent from both transports, and every bridge call
+# packs ONE payload object because the host's bridge would turn two arguments into a list.
+
+
+@pytest.mark.parametrize("member", LANGUAGE_SURFACE)
+def test_language_surface_declared_once(member):
+    assert avatar_surface().count(member) == 1, (
+        f"{member} must appear exactly once in AVATAR_SURFACE"
+    )
+
+
+@pytest.mark.parametrize("member", LANGUAGE_SURFACE)
+def test_language_surface_lives_in_the_shared_module(member):
+    assert f"async {member}(" in src("turn-loop.js"), (
+        f"{member} must be implemented in avatar/turn-loop.js so BOTH transports get it"
+    )
+    for transport in TRANSPORTS:
+        assert member not in src(transport), (
+            f"{transport} mentions {member!r}; the language bridge belongs in avatar/turn-loop.js"
+        )
+
+
+@pytest.mark.parametrize("key", LANGUAGE_DEBUG_KEYS)
+def test_language_debug_keys_present(key):
+    """Initialised at construction, not on first use: the parity suite compares key sets."""
+    assert f"{key}:" in src("turn-loop.js"), (
+        f"__debug.{key} is not initialised in avatar/turn-loop.js"
+    )
+
+
+def test_turn_event_carries_tokens():
+    """`tokens:` is inside the emit('turn', {...}) object literal, so the host page renders
+    the avatar's line from the same event it always used - no second round trip."""
+    s = src("turn-loop.js")
+    start = s.index("emit('turn', {")
+    end = s.index("});", start)
+    assert "tokens:" in s[start:end], "the turn event does not carry tokens"
+
+
+def test_bridge_calls_take_one_payload():
+    """01-08's bridge trap: server.fn(a, b) arrives as fn([a, b]). One object per call."""
+    s = src("turn-loop.js")
+    assert "bridge.analyze({" in s
+    assert "bridge.translate({" in s
+    assert "bridge.language_info(" in s
+    assert "bridge.analyze(text" not in s, "analyze must pack its arguments into one object"
+    assert "bridge.translate(text" not in s, "translate must pack its arguments into one object"