@ggui-ai/iframe-runtime 0.14.0 → 0.16.0

package/dist/runtime.js

@@ -27,13 +27,13 @@
 // FIRST import on purpose — declares zod jitless before any
 // schema-defining dependency initializes (see zod-jitless.ts).
 import './zod-jitless.js';
-import { connectionStore } from './connection.js';
+import { runtimeConnectionWriter } from './connection.js';
 import { MCP_APP_BOOTSTRAP_FAILED_TYPE, MCP_APP_RENDERER_READY_TYPE, parseMcpAppAiGguiRenderMeta, readGguiShellEnvelope, } from '@ggui-ai/protocol/integrations/mcp-apps';
 import { effectiveThemeId, effectiveThemeMode, } from '@ggui-ai/protocol/integrations/theme-binding';
-import { extractLocatorFromToolResult, parseMetaFromGlobal, parseMetaFromToolResult, validateMeta, } from './meta-parse.js';
-import { projectHostContext } from '@ggui-ai/protocol';
+import { extractLocatorFromToolResult, parseMetaFromGlobal, parseMetaFromToolResult, validateMeta, reportInvalidAppTheme, } from './meta-parse.js';
+import { projectHostContext } from '@ggui-ai/protocol/wire';
 import { App, PostMessageTransport } from '@modelcontextprotocol/ext-apps';
-import { applyHostContextStyling, attachListener as attachHostContextListener, seed as seedHostContext, } from './host-context-emitter.js';
+import { applyHostContextStyling, attachListener as attachHostContextListener, seed as seedHostContext, subscribeThemeChange as subscribeHostThemeChange, } from './host-context-emitter.js';
 import { mapHostPaletteToGguiVars } from './host-palette-bridge.js';
 import { buildRootWireConfig, StreamBus, } from './wire-config.js';
 import { createChannelTransportRouter, } from './channel-transport.js';
@@ -171,6 +171,11 @@ export function setCurrentApp(app) {
 function getCurrentApp() {
     return currentApp;
 }
+/**
+ * The live theme re-injection's subscription (ggui#987 §4), held so a
+ * re-entered boot replaces it instead of stacking a second subscriber.
+ */
+let activeThemeUnsubscribe = null;
 /**
  * The host's announced color mode, read from the connected App's
  * pre-merged hostContext (`ui/initialize` result, kept current by the
@@ -185,10 +190,11 @@ function getCurrentApp() {
  * `color-scheme` via `applyDocumentTheme` — nothing in the token
  * pipeline keys off it, so a dark host painted the light ladder
  * (host-fit 46.0 vs 87.7 with the dark ladder, probe `cc728a8eb`).
- * `buildOpts` consumes this ONLY when the slice stamps no `themeMode`:
- * every operator layer (live provider > per-render override > app
- * default > server default) still wins by being stamped; the host
- * fills the gap where no operator had an opinion.
+ * Under ggui#987 §4 the embedding host OWNS runtime mode: when it
+ * announces one, `buildOpts` paints it over every stamped opinion; the
+ * stamped layers decide only when the host is silent. Read live from
+ * the App's pre-merged hostContext, so a `hostcontextchanged` flip
+ * re-resolves on the next `buildOpts`.
  *
  * @internal — exported for unit tests (`setCurrentApp` injects the
  *   App); production caller is `buildOpts` inside `bootSequence`.
@@ -198,36 +204,30 @@ export function hostAnnouncedThemeMode() {
     return theme === 'light' || theme === 'dark' ? theme : undefined;
 }
 /**
- * Resolve the mount's base-stylesheet color mode from the slice, with
- * the host as the final fallback (ggui#589, completing the ggui#551
- * precedence ruling — "slice wins, host is the fallback, absent ≠
- * light"):
+ * Resolve the mount's color mode (ggui#987 §4 — the embedding host owns
+ * runtime mode; the app theme's `mode` is a DEFAULT, never a pin):
  *
- *   stamped `themeMode`  >  `theme.mode` (the slice theme OBJECT)  >
- *   host-announced theme  >  undefined
+ *   host-announced theme  >  stamped `themeMode`  >  `theme.mode`
+ *   (the app theme's default)  >  undefined
  *
- * The middle leg is the ggui#589 fix: a render envelope carrying a
- * per-app theme (`theme: {mode, cssVariables}`) but no top-level
- * `themeMode` is still a slice-stamped mode opinion — before this,
- * the base token ladder ignored it and painted the LIGHT token set
- * under a dark overlay whenever the host (correctly, per the
- * adapter-boundary doctrine in the native host helpers) announced no
- * `hostContext.theme`: a light skeleton in a dark skin. The theme
- * object's own `mode` already drove `color-scheme`; now it also
- * selects the ladder.
+ * A card that ignored the host's announced mode painted a light
+ * skeleton inside a dark chat — the host's word is what the user
+ * actually sees around the card. The stamped layers (live provider >
+ * per-render override > app default > server default) decide only when
+ * the host is silent, which is the adapter-boundary case (a host
+ * helper that announces no `hostContext.theme`).
  *
  * `undefined` still means "no opinion anywhere" — the renderer's
- * default applies; never coerced to `'light'`.
+ * default applies; never coerced to `'light'` here (ggui#551).
  *
  * @internal — exported for unit tests; production caller is
  *   `buildOpts` inside `bootSequence`.
  */
 export function resolveMountThemeMode(meta) {
     // The CLIENT projection of the protocol's normative theme-binding
-    // total order (@ggui-ai/protocol/integrations/theme-binding,
-    // ggui#598 leg 4) — the server stamps via the sibling projection and
-    // the protocol's composition-law test pins that the two compose
-    // without rank drift.
+    // total order (@ggui-ai/protocol/integrations/theme-binding) — the
+    // server stamps via the sibling projection and the protocol's
+    // composition-law test pins that the two compose without rank drift.
     return effectiveThemeMode({
         stamped: meta.themeMode,
         sessionSidecar: meta.theme?.mode,
@@ -235,20 +235,14 @@ export function resolveMountThemeMode(meta) {
     });
 }
 /**
- * Resolve the mount's base-theme id from the slice (ggui#589 ask 3):
+ * Resolve the mount's compiled-ladder id from the slice (ggui#987 D2):
  *
- *   stamped `themeId`  >  `theme.name` (the slice theme OBJECT's name)
- *   >  undefined (renderer default ladder)
+ *   stamped `themeId`  >  undefined (renderer default ladder)
  *
- * The name leg makes a slice theme whose `name` matches a REGISTERED
- * theme id select that theme as the BASE token ladder — the overlay's
- * cssVariables still apply above it, so the base carries the full
- * brand ramp coverage a sparse overlay cannot (the "only the mapped
- * vars carry brand" store-frame class). An unregistered name is
- * harmless by construction: `getScopedThemeCss` falls back to the
- * default theme, which is byte-identical to the no-themeId path
- * (`getScopedCssTokens` ≡ `getScopedThemeCss(default)`), so a slice
- * naming its theme "My Custom" renders exactly as before.
+ * The app theme's `name` is a LABEL the author's tooling reads back —
+ * it never selects a ladder. An app theme carries its own full
+ * projection (`overlays`, exactly the manifest minus the floor), so
+ * there is no coverage gap for a compiled theme to fill beneath it.
  *
  * @internal — exported for unit tests; production caller is
  *   `buildOpts` inside `bootSequence`.
@@ -256,10 +250,7 @@ export function resolveMountThemeMode(meta) {
 export function resolveMountThemeId(meta) {
     // Client projection of the normative theme-binding order — see
     // resolveMountThemeMode above.
-    return effectiveThemeId({
-        stamped: meta.themeId,
-        sidecarName: meta.theme?.name,
-    });
+    return effectiveThemeId({ stamped: meta.themeId });
 }
 /**
  * The host's announced palette, read from the connected App's
@@ -421,11 +412,35 @@ export async function bootSequence(opts) {
     // covers every boot path; arrivals before a renderer publishes
     // `applyRender` no-op inside the listener.
     installPersistentToolResultListener(app);
+    // Fresh boot ⇒ the relay latch and the connection store start
+    // aligned (ggui#670): a standing latch from a prior mount in a
+    // re-booted document must not outlive the store it was written to.
+    // It runs BEFORE the handshake so that every boot passes the close
+    // edge before it can latch — the boot-failed write below is then
+    // always on-edge (ggui#830 fold): a prior zone ends with its
+    // 'cleared' edge and its summary, never buried under a second
+    // 'latched' with its tally erased.
+    resetRelayLatchForBoot();
     const initResult = await connectApp(app, transport);
     if (!initResult.ok) {
         setStatus(refs, `ui/initialize failed: ${initResult.message}`, 'error');
         retireShellLoadingIndicator(doc);
         emitBootFailure('UI_INITIALIZE_FAILED', initResult.message);
+        // The maximal dead zone (ggui#830): the host refused the handshake
+        // every session begins with, so nothing can be delivered here — the
+        // relay latch sets through its one writer (store false, 'latched'
+        // edge, standing notice) instead of leaving this document with
+        // `isConnected === true`, no explanation and no count. No gesture
+        // is needed for that knowledge, and no gesture is suppressed by it:
+        // every later tap still attempts (attempt-always) and lands as a
+        // counted dead tap. The scope is empty because no bootstrap has
+        // named a session yet; it clears the only way a handshake failure
+        // can — the next boot's close edge, which this boot itself already
+        // passed above, so this write is on-edge by construction. The
+        // gesture gate's pre-capture rule ("never latch before the host has
+        // been asked") does not apply here: the host HAS been asked — this
+        // is its answer to `ui/initialize`, resolved as failure.
+        announceRelayIncapability('boot-failed', {});
         return { ok: false, mountedRender };
     }
     // Record what this host said it can do (ggui#440). Earliest valid
@@ -437,7 +452,7 @@ export async function bootSequence(opts) {
     // `tools/call` (dispatchSubmitAction, channel-transport router)
     // routes through `app.callServerTool` instead of the legacy raw
     // postMessage pump. Idempotent: re-boot with the same App is a
-    // no-op; a different App throws (the iframe is single-tenant).
+    // no-op; a different App throws (the iframe is single-app).
     setCurrentApp(app);
     // Slice-meta resolution — spec-canonical primary, no in-house
     // Reading-B (retired Phase 1.19b.3 with the App-class swap; the
@@ -678,10 +693,6 @@ export async function bootSequence(opts) {
     // Fresh boot ⇒ not superseded (matters only for test re-runs that
     // reuse the module; a real iframe boots once).
     mountSuperseded = false;
-    // Fresh boot ⇒ the relay latch and the connection store start
-    // aligned (ggui#670): a standing latch from a prior mount in a
-    // re-booted document must not outlive the store it was written to.
-    resetRelayLatchForBoot();
     telemetry?.record('boot.path', JSON.stringify({
         hasStaticContent,
         hasLiveTrio,
@@ -1336,7 +1347,7 @@ export async function resolveMetaViaReadDoor(app, locator) {
     const envelope = readGguiShellEnvelope(text);
     if (envelope === undefined)
         return null;
-    const parsed = parseMcpAppAiGguiRenderMeta(envelope);
+    const parsed = parseMcpAppAiGguiRenderMeta(envelope, { onInvalidTheme: reportInvalidAppTheme });
     if (!parsed.ok || parsed.meta === undefined)
         return null;
     const validated = validateMeta(parsed.meta);
@@ -1386,7 +1397,7 @@ function awaitToolResultMeta(timeoutMs) {
  * App instance even across re-mounts (e.g. an agent fires a second
  * `ggui_render` and the listener re-applies through the published
  * `applyRender`). Keyed by App — not a module boolean — so a fresh App
- * (a re-booted document in tests; production is single-tenant per
+ * (a re-booted document in tests; production is single-app per
  * iframe) always gets its own registration, never a stale latch.
  */
 const persistentToolResultListenerApps = new WeakSet();
@@ -1657,7 +1668,11 @@ async function callServerToolSpec(toolName, args) {
  *
  * Unknown codes NEVER confirm — they may be proxy- or server-minted
  * (e.g. `-32603` internal error), and classifying them would misbrand
- * capable mounts. They stay on the per-gesture transient path.
+ * capable mounts. They never CONFIRM (they can latch only through
+ * the advert-silent leg, never on an advertising host); off-latch they
+ * stay on the per-gesture transient path, and inside a standing zone
+ * they count as dead taps like every other undelivered outcome
+ * (ggui#826).
  */
 const CONFIRMED_RELAY_REFUSAL_CODES = new Set([-32601]);
 /**
@@ -1775,6 +1790,20 @@ function classifySubmitActionResponse(resp) {
  * carries a result envelope, so neither is evidence the relay worked.
  */
 function isRelayShapedFailure(resp) {
+    // "Relay-shaped" IS "undelivered" on this leg, by construction — not
+    // by hope (ggui#832, ruled from the hosts' source): every JSON-RPC
+    // error the iframe sees here is host- or transport-minted. The MCP
+    // SDK server turns a tool handler's throw into an `isError` RESULT and
+    // mints JSON-RPC codes only for its own gate; the guuey view-host
+    // answers a rejecting relay with an in-band unavailable RESULT, never
+    // an error; ggui's embed host proxies over HTTP and mints its OWN
+    // codes for a failed proxy. So a server-side outcome always arrives
+    // as a `CallToolResult` (`ok:true` and `ok:false` alike clear the
+    // latch), and an error envelope always means the call did not round
+    // trip. A third-party host that forwarded a server's JSON-RPC error
+    // verbatim would be indistinguishable by code — that is the
+    // host-helper conformance catalog's business (H3 / R1), not this
+    // predicate's.
     // Null-tolerant on `error`, matching `classifySubmitActionResponse`'s
     // own check: an `{error:null, result:{...}}` envelope classifies as
     // success there, so it must also read as NOT relay-shaped-failure
@@ -1845,7 +1874,7 @@ function applyFreezeCue(root) {
         fontFamily: '-apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, sans-serif',
         fontSize: '11px',
         fontWeight: '600',
-        color: 'var(--ggui-color-onSurface, inherit)',
+        color: 'var(--ggui-color-onContainer, inherit)',
         background: 'rgba(128,128,128,0.16)',
         border: '1px solid currentColor',
         opacity: '0.85',
@@ -2282,7 +2311,7 @@ let relayLatchTrigger;
 let relayLatchScope = {};
 function transitionRelayLatch(next, trigger, scope = {}) {
     relayIncapabilityAnnounced = next;
-    connectionStore.set(!next);
+    runtimeConnectionWriter().set(!next);
     if (next && trigger !== undefined) {
         relayLatchedAt = Date.now();
         relayDeadTaps = 0;
@@ -2308,6 +2337,22 @@ function transitionRelayLatch(next, trigger, scope = {}) {
     relayLatchTrigger = undefined;
     relayLatchScope = {};
 }
+/**
+ * Set the latch AND present it — the three steps every latch-set path
+ * takes, in one place: the transition through the ONE writer (store
+ * flip + `'latched'` edge), a fresh dead zone (unspent cue throttles —
+ * the state belongs to THIS notice, so a second latch-set path never
+ * has to know the clear edge already reset it), and the standing
+ * explanation, marked so the per-gesture cue arms on its dismissal.
+ * Callers: the dispatch outcome gate (a gesture's confirmed relay
+ * failure) and the boot sequence (a refused `ui/initialize`, ggui#830).
+ */
+function announceRelayIncapability(trigger, scope) {
+    transitionRelayLatch(true, trigger, scope);
+    resetRelayCueThrottles();
+    showActionToast('This host cannot relay actions to the agent — interactive controls will not work here.', 'action_required');
+    markRelayNotice();
+}
 /**
  * One {@link RelayDeadTapEvent} per gesture attempted inside a standing
  * dead zone that came back UNDELIVERED (ggui#670 Phase 3). Called from
@@ -2381,6 +2426,10 @@ function isRelayNoticeVisible() {
  * @internal — exported for unit tests.
  */
 export function resetRelayLatchForBoot() {
+    // The runtime's claim on the document's connection writer is taken HERE,
+    // eagerly, before any transition (ggui#843): a second runtime in this
+    // document fails at boot naming itself, never continuing unclaimed.
+    runtimeConnectionWriter();
     if (typeof document !== 'undefined') {
         const el = document.getElementById(ACTION_TOAST_ID);
         if (el !== null && el.hasAttribute(RELAY_NOTICE_ATTR))
@@ -2391,14 +2440,14 @@ export function resetRelayLatchForBoot() {
         transitionRelayLatch(false);
     }
     else {
-        connectionStore.set(true);
+        runtimeConnectionWriter().set(true);
     }
 }
 /**
  * Module-level handle to the CURRENT boot's telemetry sink so
  * module-scope paths (the doorbell emitter below) can report without
  * threading the sink through every call chain. Per-iframe
- * single-tenancy makes a single slot correct — same justification as
+ * single-app scope makes a single slot correct — same justification as
  * `getCurrentApp()`.
  */
 let currentTelemetrySink = null;
@@ -2486,7 +2535,7 @@ function resetRelayCueThrottles() {
 /** @internal — exported for unit tests to reset module state. */
 export function __resetRelayNoticeForTest() {
     relayIncapabilityAnnounced = false;
-    connectionStore.set(true);
+    runtimeConnectionWriter().set(true);
     relayLatchedAt = undefined;
     relayDeadTaps = 0;
     relayLatchTrigger = undefined;
@@ -2891,39 +2940,46 @@ export function dispatchSubmitAction(args) {
         // helper-minted refusal code, which outranks any positive
         // advertisement (the advertises-but-refuses host previously got a
         // fresh transient toast per tap, forever). Timeouts and unknown
-        // codes never reach the second leg; the un-classify edge for BOTH
-        // is the same response-arrival clear guard above (attempt-always
-        // preserved — nothing here suppresses dispatch, per the #443
-        // doctrine: the attempt is the self-heal sensor).
+        // codes never reach the second leg — they never CONFIRM (the
+        // advert-silent leg alone can latch on them); inside a standing
+        // zone they are counted like every other undelivered outcome by
+        // the branch below (ggui#826). The un-classify edge for
+        // BOTH legs is the same response-arrival clear guard above
+        // (attempt-always preserved — nothing here suppresses dispatch,
+        // per the #443 doctrine: the attempt is the self-heal sensor).
         const confirmedRefusal = isConfirmedRelayRefusal(resp);
+        if (relayIncapabilityAnnounced && isRelayShapedFailure(resp)) {
+            // A gesture whose undelivered outcome landed inside a standing
+            // dead zone — a dead tap, counted for the host (ggui#670 Phase 3);
+            // an in-flight gesture that raced the latching one counts too.
+            // Counted on the OUTCOME and keyed on the LATCH, never on
+            // advertisement (ggui#826): the advertises-but-refuses host
+            // latches by a confirmed refusal, and its later code-less or
+            // timeout failures are exactly the undelivered gestures the
+            // RelayDeadTapEvent contract promises to count. The eligibility
+            // predicate below is the LATCH-SET rule — a timeout or unknown
+            // code never CONFIRMS; it can latch only through the advert-silent
+            // leg, never on an advertising host — and is the wrong key for
+            // counting. Every outcome that
+            // reaches here while the latch stands is relay-shaped by
+            // construction (the response-arrival guard above cleared on any
+            // well-formed result); the conjunct states the contract instead
+            // of trusting that. The latching gesture is the 'latched' edge
+            // and a gesture that heals the zone is the 'cleared' edge —
+            // neither is a dead tap.
+            emitRelayDeadTap(intent, { sessionId, appId });
+            return;
+        }
         if (hostCapabilitiesCaptured() &&
             ((!hostCanRelayToolCalls() && isRelayShapedFailure(resp)) ||
                 confirmedRefusal)) {
-            if (!relayIncapabilityAnnounced) {
-                // Transition edge — the paired 'cleared' edge lives at the
-                // response-arrival guard above. NEVER emit off-edge (e.g. per
-                // channel poll tick): the router ticks on an interval and
-                // would spam; the two edges carry the full information.
-                transitionRelayLatch(true, confirmedRefusal ? 'confirmed-refusal' : 'advert-silent', { sessionId, appId });
-                // Establish the flag's invariant where the notice it describes
-                // is created: a freshly-shown notice is undismissed, and its
-                // dead zone starts with an unspent throttle. Today every
-                // re-latch already passes through the clear edge above (which
-                // resets both), so this is the same value arriving by a second
-                // route — kept because the state belongs to THIS notice, and a
-                // future second latch-set path shouldn't have to know that.
-                resetRelayCueThrottles();
-                showActionToast('This host cannot relay actions to the agent — interactive controls will not work here.', 'action_required');
-                markRelayNotice();
-            }
-            else {
-                // A gesture attempted inside a standing dead zone came back
-                // undelivered — a dead tap, counted for the host (ggui#670
-                // Phase 3). The latching gesture above is the 'latched' edge,
-                // and a gesture that heals the zone is the 'cleared' edge —
-                // neither is a dead tap.
-                emitRelayDeadTap(intent, { sessionId, appId });
-            }
+            // Transition edge — the paired 'cleared' edge lives at the
+            // response-arrival guard above. NEVER emit off-edge (e.g. per
+            // channel poll tick): the router ticks on an interval and
+            // would spam; the two edges carry the full information. A
+            // standing latch never reaches here: its undelivered outcomes
+            // were counted above, and a delivered one cleared it.
+            announceRelayIncapability(confirmedRefusal ? 'confirmed-refusal' : 'advert-silent', { sessionId, appId });
             return;
         }
         showActionToast(`⚠ ${intent} — could not reach the agent`, 'error');
@@ -2932,19 +2988,22 @@ export function dispatchSubmitAction(args) {
 /**
  * Channel-transport router's `tools/call` invoker (ggui#440) —
  * iframe-polling transport, `tools/call` against the parent MCP host
- * via `app.callServerTool` (spec-canonical) when the App handle is
- * set; falls back to raw postMessage pre-handshake or in tests.
+ * via `app.callServerTool` (spec-canonical); with no App bound the
+ * call answers a code-less error envelope — never a raw postMessage.
  * Direct call (no LLM consent loop). Returns the tool's
  * structuredContent (or `content[0]` if that's where the payload
  * landed) as a `JsonValue`. On RPC error we throw — the router
  * catches and silently retries on the next tick.
  *
- * Once a REAL gesture has confirmed this host can't relay (the latch
- * above — set only after {@link dispatchSubmitAction} actually tried
- * and failed on a host with no `serverTools` advertised, with
- * capabilities already captured, AND the failure was relay-shaped —
- * not a well-formed `{ok:false}` result; see `isRelayShapedFailure`),
- * every subsequent poll will fail identically.
+ * Once this document has confirmed it cannot relay (the latch above —
+ * set through the ONE writer on exactly three paths: a REAL gesture
+ * that failed relay-shaped on a host that never advertised
+ * `serverTools`, with capabilities already captured (`advert-silent`);
+ * a declared refusal code answered under a positive advertisement
+ * (`confirmed-refusal`); or the host's own failure of the mandatory
+ * `ui/initialize` handshake, before any gesture (`boot-failed`,
+ * ggui#830) — never a well-formed `{ok:false}` result; see
+ * `isRelayShapedFailure`), every subsequent poll will fail identically.
  *
  * This guard does NOT stop the router's poll loop, and nothing here
  * should ever be written so that it could (ggui#443). It does two
@@ -2970,10 +3029,13 @@ export function dispatchSubmitAction(args) {
  * (ggui's own embed host pre-Task-2 is exactly this case) — silently
  * killing working channel polls forever. That is "absence of a
  * capability blocks an attempt", which the fail-safe constraint
- * forbids. The latch implies `!hostCanRelayToolCalls()` (it only
- * ever sets inside that guard), so testing it alone is sufficient —
- * a host that never fails a real gesture never latches, and its
- * channels keep working.
+ * forbids. The latch is set only by a CONFIRMED OUTCOME — a failed
+ * real gesture (the advert-silent leg, or a confirmed refusal under a
+ * positive advertisement, ggui#599 cycle-2) or a failed handshake
+ * (ggui#830), never by an advertisement's absence — so testing the
+ * latch alone is sufficient: a host that answers its handshake and
+ * never fails a real gesture never latches, and its channels keep
+ * working.
  *
  * Extracted to a named export (rather than an inline closure inside
  * `bootProduction`) so unit tests can drive it directly through the
@@ -3645,10 +3707,10 @@ async function bootProduction(opts) {
             // DEFAULT-handlers compositions only (a custom `handlers` list
             // drains its own pipe; bridging the channel onto an instance
             // nobody drains would buffer gestures into the void — see the
-            // hoist note in server.ts). The hosted pod IS a custom-handlers
-            // caller: on it, a WS gesture lands on the retained ledger only
+            // hoist note in server.ts). A deployment composing its own `handlers`
+            // IS such a caller: on it, a WS gesture lands on the retained ledger only
             // and never reaches the agent. Any WS action fallback (ggui#599's
-            // open design leg) therefore requires the server/pod bridge
+            // open design leg) therefore requires the server-side bridge
             // FIRST — it is a capability gap on that composition today. The WS pipe otherwise carries
             // streamSpec subscriptions (inbound `ggui_emit` fanout +
             // `props_update` + `render` + `data` + `drain_ack` +
@@ -3797,29 +3859,27 @@ async function bootProduction(opts) {
                         !('createdAt' in render)
                         ? { codeModuleUrl: meta.codeModuleUrl }
                         : {}),
-                    // Base-theme ladder (ggui#589 ask 3 — see `resolveMountThemeId`):
-                    // stamped themeId > the slice theme object's NAME (a
-                    // registered name binds the full brand base; unregistered
-                    // names fall back to the default ladder, byte-identical to
-                    // the no-themeId path).
+                    // Compiled ladder (see `resolveMountThemeId`): the stamped
+                    // themeId alone; absent = the renderer's default ladder.
                     ...(() => {
                         const themeId = resolveMountThemeId(meta);
                         return themeId !== undefined ? { themeId } : {};
                     })(),
-                    // Mode ladder (ggui#551 + #589 — see `resolveMountThemeMode`):
-                    // stamped `themeMode` > the slice theme OBJECT's `mode` >
-                    // host-announced theme. Absent everywhere means "no opinion",
-                    // not "light".
+                    // Mode (ggui#987 §4 — see `resolveMountThemeMode`): host-
+                    // announced theme > stamped `themeMode` > the app theme's
+                    // default `mode`. Absent everywhere means "no opinion", not
+                    // "light". Re-resolved on every buildOpts, so the live
+                    // hostcontextchanged re-injection below picks up a flip.
                     ...(() => {
                         const themeMode = resolveMountThemeMode(meta);
                         return themeMode !== undefined ? { themeMode } : {};
                     })(),
-                    // Per-app theme overlay (St3 M2.2). Threaded straight from the
+                    // Per-app theme (ggui#987 v2). Threaded straight from the
                     // bootstrap's `_meta["ai.ggui/render"].theme` (typed `AppTheme`,
                     // already injection-validated by the wire parser) onto the mount
-                    // options so the renderer applies the `--ggui-*` overrides +
-                    // `color-scheme` at `:root`. THEME IS COMPONENT-ONLY — system
-                    // cards theme via the SystemCardHost/ThemeProvider path.
+                    // options; the renderer injects the effective mode's overlay
+                    // into the scoped block + `:root`. THEME IS COMPONENT-ONLY —
+                    // system cards theme via the SystemCardHost/ThemeProvider path.
                     ...(meta.theme !== undefined ? { appTheme: meta.theme } : {}),
                     // Host palette: always threaded when the host announced one —
                     // unlike mode there is no either/or gate here, because the
@@ -3845,14 +3905,52 @@ async function bootProduction(opts) {
              * layer just calls `applyRender(render)` without owning
              * lifecycle state.
              */
+            // Every in-place update of the mounted slot goes through ONE
+            // chain: the WS render-frame / props_update path and the live
+            // theme re-injection below are independent callers, and the
+            // handle's `update` has no lock of its own — serializing them
+            // here is what keeps a host flip landing mid-render from
+            // interleaving two updates.
+            let updateChain = Promise.resolve();
+            const queueUpdate = (opts) => {
+                const run = updateChain.then(async () => {
+                    if (renderHandle === null)
+                        return;
+                    await renderHandle.update(opts());
+                });
+                updateChain = run.catch(() => undefined);
+                return run;
+            };
             const applyRender = async (render) => {
                 currentRender = render;
                 if (renderHandle === null) {
                     renderHandle = await mountRender(renderInto, buildOpts(render));
                     return;
                 }
-                await renderHandle.update(buildOpts(render));
+                await queueUpdate(() => buildOpts(render));
             };
+            // Live re-injection (ggui#987 §4): the host owns runtime mode and
+            // may flip it mid-session. The trigger is the emitter's THEME
+            // subscription — the raw `theme` / `styles` payload — because the
+            // host-context projection excludes both by design and its
+            // equality gate would never fire for a theme-only flip. The App
+            // pre-merges the new hostContext before the emitter fans out, so
+            // re-running `buildOpts` on the CURRENT render re-resolves mode +
+            // palette and the renderer repaints from the retained other
+            // overlay — no fetch, no remount. A rejection is reported to the
+            // embedding host, never dropped on the floor.
+            activeThemeUnsubscribe?.();
+            activeThemeUnsubscribe = subscribeHostThemeChange(() => {
+                if (renderHandle === null || currentRender === null)
+                    return;
+                const render = currentRender;
+                queueUpdate(() => buildOpts(render)).catch((err) => {
+                    postObservabilityToParent({
+                        kind: 'theme-reinject-failed',
+                        message: err instanceof Error ? err.message : String(err),
+                    });
+                });
+            });
             // Publish `applyRender` module-level. The persistent tool-result
             // listener is ALREADY registered — `bootSequence` installs it
             // pre-connect (ggui#586) — and reads this slot dynamically, so