@ggui-ai/iframe-runtime 0.9.0 → 0.11.0

package/dist/runtime.js

@@ -1,8 +1,38 @@
-import { MCP_APP_BOOTSTRAP_FAILED_TYPE, MCP_APP_RENDERER_READY_TYPE, } from '@ggui-ai/protocol/integrations/mcp-apps';
-import { parseMetaFromGlobal, parseMetaFromToolResult, } from './meta-parse.js';
+/**
+ * `@ggui-ai/iframe-runtime` iframe runtime entry.
+ *
+ * This is the file esbuild bundles into `dist/iframe-runtime.js`. The
+ * thin-shell HTML loads it via `<script type="module" src=".../iframe-runtime.js">`;
+ * on import the side-effects below take over: build a status DOM,
+ * postMessage `ui/initialize` to the parent, parse the bootstrap, open
+ * the WebSocket, run the version handshake, and mount the render
+ * placeholder.
+ *
+ * Boot sequence:
+ *   - Boot from the `_meta["ai.ggui/render"]` slice received via
+ *     `ui/initialize`.
+ *   - Open the WebSocket, run the subscribe handshake.
+ *   - Mount the render — either a structural placeholder or, when
+ *     the renderer hooks are wired, a React mount of `componentCode`.
+ *
+ * The runtime advertises its build version via a post-`ui/initialize`
+ * notification (`ggui:renderer-ready`).
+ *
+ * Failure surfacing: every parse / handshake failure goes to two
+ * places — (1) the in-iframe status line (operator-visible) and
+ * (2) a parent-bound `postMessage({type:'ggui:bootstrap-failed', ...})`.
+ * The post-message envelope is consumed by the `<McpAppIframe>` host
+ * wrapper, which routes it to the host's `onError` callback.
+ */
+// FIRST import on purpose — declares zod jitless before any
+// schema-defining dependency initializes (see zod-jitless.ts).
+import './zod-jitless.js';
+import { MCP_APP_BOOTSTRAP_FAILED_TYPE, MCP_APP_RENDERER_READY_TYPE, parseMcpAppAiGguiRenderMeta, readGguiShellEnvelope, } from '@ggui-ai/protocol/integrations/mcp-apps';
+import { extractLocatorFromToolResult, parseMetaFromGlobal, parseMetaFromToolResult, validateMeta, } from './meta-parse.js';
 import { projectHostContext } from '@ggui-ai/protocol';
 import { App, PostMessageTransport } from '@modelcontextprotocol/ext-apps';
 import { applyHostContextStyling, attachListener as attachHostContextListener, seed as seedHostContext, } 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';
 import { RelayIncapableError } from './relay-incapability.js';
@@ -58,7 +88,7 @@ function dispatchDrainAck(payload) {
 // App-class plumbing (Phase 1.19b.3). The renderer used to roll its own
 // JSON-RPC pump (a closure-scoped `makeJsonRpcCaller` for the single
 // `ui/initialize` request + a module-level `ensurePostRpcToParentListener`
-// for `tools/call` and a `installPostMountListener` for inbound
+// for `tools/call` and a `installPersistentToolResultListener` for inbound
 // `ui/notifications/tool-result`). Every one of those was a hand-rolled
 // reimplementation of a primitive `@modelcontextprotocol/ext-apps`'s
 // `App` class already ships — drift across them produced the Reading-B
@@ -131,6 +161,106 @@ export function setCurrentApp(app) {
 function getCurrentApp() {
     return currentApp;
 }
+/**
+ * The host's announced color mode, read from the connected App's
+ * pre-merged hostContext (`ui/initialize` result, kept current by the
+ * App across `host-context-changed`). `undefined` when no App is
+ * connected, the host sent no `theme`, or it sent something outside
+ * the spec's `'light' | 'dark'` literals (dropped, never guessed —
+ * the same tolerant posture as `projectHostContext`).
+ *
+ * This is the INPUT leg of host-theme adaptation
+ * (rnd/gen-ui/beauty/experiments/002-host-theme-adaptation.md, ggui#551):
+ * `hostContext.theme` alone reaches only `data-theme` +
+ * `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.
+ *
+ * @internal — exported for unit tests (`setCurrentApp` injects the
+ *   App); production caller is `buildOpts` inside `bootSequence`.
+ */
+export function hostAnnouncedThemeMode() {
+    const theme = currentApp?.getHostContext()?.theme;
+    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"):
+ *
+ *   stamped `themeMode`  >  `theme.mode` (the slice theme OBJECT)  >
+ *   host-announced theme  >  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.
+ *
+ * `undefined` still means "no opinion anywhere" — the renderer's
+ * default applies; never coerced to `'light'`.
+ *
+ * @internal — exported for unit tests; production caller is
+ *   `buildOpts` inside `bootSequence`.
+ */
+export function resolveMountThemeMode(meta) {
+    return meta.themeMode ?? meta.theme?.mode ?? hostAnnouncedThemeMode();
+}
+/**
+ * Resolve the mount's base-theme id from the slice (ggui#589 ask 3):
+ *
+ *   stamped `themeId`  >  `theme.name` (the slice theme OBJECT's name)
+ *   >  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.
+ *
+ * @internal — exported for unit tests; production caller is
+ *   `buildOpts` inside `bootSequence`.
+ */
+export function resolveMountThemeId(meta) {
+    return meta.themeId ?? meta.theme?.name;
+}
+/**
+ * The host's announced palette, read from the connected App's
+ * pre-merged hostContext and translated onto `--ggui-*` tokens by the
+ * host-palette bridge. `undefined` when no App is connected, the host
+ * sent no `styles.variables`, or nothing in it maps/survives
+ * sanitization — callers spread-skip the option, exactly like
+ * {@link hostAnnouncedThemeMode}.
+ *
+ * This is the palette input leg of host-theme adaptation (ggui#572,
+ * the color analog of #551's mode leg above): the spec `--color-*`
+ * variables land as inline custom properties on `<html>` via the
+ * canonical ext-apps helper, but nothing ggui renders consumes that
+ * vocabulary, and the scoped token block shadows root inheritance
+ * anyway — so without this mapping a host palette repaints nothing.
+ * `buildOpts` threads it onto the mount options; the renderer merges
+ * it as the fallback layer BENEATH the slice's own theme (ggui#573
+ * ruling: slice wins, host fallback).
+ *
+ * @internal — exported for unit tests (`setCurrentApp` injects the
+ *   App); production caller is `buildOpts` inside `bootSequence`.
+ */
+export function hostAnnouncedPalette() {
+    return mapHostPaletteToGguiVars(currentApp?.getHostContext()?.styles?.variables);
+}
 /**
  * @internal — exported for unit tests to reset module state between
  * scenarios.
@@ -259,6 +389,14 @@ export async function bootSequence(opts) {
     const toolResultPromise = opts.preResolvedMeta !== undefined
         ? Promise.resolve(null)
         : awaitToolResultMetaFromApp(app, toolResultTimeoutMs);
+    // Persistent re-mount listener — ALSO pre-connect (ggui#586). On a
+    // Tier-1/preResolved boot the one-shot listener above is skipped,
+    // which made the post-mount installation the FIRST toolresult
+    // registration — after the handshake, tripping the ext-apps timing
+    // notice and leaning on SDK replay for correctness. Registering here
+    // covers every boot path; arrivals before a renderer publishes
+    // `applyRender` no-op inside the listener.
+    installPersistentToolResultListener(app);
     const initResult = await connectApp(app, transport);
     if (!initResult.ok) {
         setStatus(refs, `ui/initialize failed: ${initResult.message}`, 'error');
@@ -314,7 +452,16 @@ export async function bootSequence(opts) {
             parsed = inline;
         }
         else {
-            const fromToolResult = await toolResultPromise;
+            // Tier 1.5 — the read-plane door (ggui#537). A pre-boot tool
+            // result named the view but carried no material; now that the
+            // App is connected, resolve the locator through the host's
+            // `resources/read` proxy. One round trip, ahead of the Tier 2
+            // wait; a miss falls through to Tier 2 unchanged (its listener
+            // is already armed and resolves locator-only arrivals too).
+            const viaDoor = opts.preResolvedLocator !== undefined
+                ? await resolveMetaViaReadDoor(app, opts.preResolvedLocator)
+                : null;
+            const fromToolResult = viaDoor ?? (await toolResultPromise);
             if (fromToolResult !== null) {
                 parsed = { ok: true, meta: fromToolResult };
             }
@@ -1052,6 +1199,26 @@ export function readPendingToolResults() {
     }
     return null;
 }
+/**
+ * Sibling of {@link readPendingToolResults} for the read-plane-only
+ * posture (ggui#537): the NEWEST buffered tool result that carries a
+ * `ui://ggui/render/…` locator but no bootstrap material. Consulted only
+ * when the buffer yielded no inline slice; the autostart threads it to
+ * `bootSequence` as `preResolvedLocator`, resolved after the handshake.
+ */
+export function readPendingToolResultLocator() {
+    if (typeof window === 'undefined')
+        return null;
+    const raw = window.__GGUI_PENDING_TOOL_RESULTS__;
+    if (!Array.isArray(raw) || raw.length === 0)
+        return null;
+    for (let i = raw.length - 1; i >= 0; i--) {
+        const locator = extractLocatorFromToolResult(raw[i]);
+        if (locator !== null)
+            return locator;
+    }
+    return null;
+}
 /**
  * Listen for a `ui/notifications/tool-result` notification via the
  * App's spec-canonical event surface and resolve to the extracted
@@ -1067,36 +1234,75 @@ export function readPendingToolResults() {
 function awaitToolResultMetaFromApp(app, timeoutMs) {
     return new Promise((resolve) => {
         let settled = false;
-        const handler = (params) => {
+        const settle = (value) => {
             if (settled)
                 return;
-            const meta = extractMetaFromToolResult(params);
-            if (meta === null)
-                return;
             settled = true;
             app.removeEventListener('toolresult', handler);
             clearTimeout(timer);
-            resolve(meta);
+            resolve(value);
         };
-        app.addEventListener('toolresult', handler);
-        const timer = setTimeout(() => {
+        const handler = (params) => {
             if (settled)
                 return;
-            settled = true;
-            app.removeEventListener('toolresult', handler);
-            resolve(null);
-        }, timeoutMs);
+            const meta = extractMetaFromToolResult(params);
+            if (meta !== null) {
+                settle(meta);
+                return;
+            }
+            // Read-plane door (ggui#537): identity-only result → resolve the
+            // locator through the host's `resources/read` proxy. Async, and
+            // it never settles `null` — a later result carrying the slice
+            // inline (or the timeout) still decides.
+            const locator = extractLocatorFromToolResult(params);
+            if (locator === null)
+                return;
+            void resolveMetaViaReadDoor(app, locator).then((resolved) => {
+                if (resolved !== null)
+                    settle(resolved);
+            });
+        };
+        app.addEventListener('toolresult', handler);
+        const timer = setTimeout(() => settle(null), timeoutMs);
     });
 }
 /**
- * Pre-handshake variant — listens to raw `window.message` for the
- * autostart layer. Used BEFORE the App is constructed, so this can't
- * route through `app.addEventListener`. Pairs with the minimal-shell
- * pattern: the shell buffers any tool-results that arrived BEFORE
- * runtime load (read via {@link readPendingToolResults}); this
- * listener catches the ones that arrive AFTER the bundle parses but
- * BEFORE bootSequence runs.
- */
+ * The read-plane door (ggui#537). A server running the read-plane-only
+ * posture publishes only the view's identity on the tool result — the
+ * `ui://ggui/render/…` locator — and no bootstrap material; the
+ * per-render resource that locator names is the self-contained shell,
+ * whose document inlines the very envelope this runtime boots from.
+ * Ask the HOST to read it (`app.readServerResource` → `resources/read`,
+ * proxied by the host's own MCP client — no fetch from this sandbox, so
+ * a host CSP without `connect-src` to the server is not in the way),
+ * recover the envelope with the protocol's writer/reader pair
+ * ({@link readGguiShellEnvelope}), and validate it exactly as an inline
+ * slice would be. `null` on any miss (host cannot proxy reads, resource
+ * gone, no envelope) — the caller's other tiers still decide.
+ */
+export async function resolveMetaViaReadDoor(app, locator) {
+    let text;
+    try {
+        const res = await app.readServerResource({ uri: locator });
+        const first = res.contents[0];
+        text = first !== undefined && 'text' in first && typeof first.text === 'string' ? first.text : undefined;
+    }
+    catch (err) {
+        // eslint-disable-next-line no-console -- operator-visible: the door is a boot tier, its miss must be legible
+        console.warn(`[ggui-runtime] read-plane door: host could not read ${locator} — ${err instanceof Error ? err.message : String(err)}`);
+        return null;
+    }
+    if (text === undefined)
+        return null;
+    const envelope = readGguiShellEnvelope(text);
+    if (envelope === undefined)
+        return null;
+    const parsed = parseMcpAppAiGguiRenderMeta(envelope);
+    if (!parsed.ok || parsed.meta === undefined)
+        return null;
+    const validated = validateMeta(parsed.meta);
+    return validated.ok ? validated.meta : null;
+}
 function awaitToolResultMeta(timeoutMs) {
     if (typeof window === 'undefined')
         return Promise.resolve(null);
@@ -1119,25 +1325,36 @@ function awaitToolResultMeta(timeoutMs) {
                 return;
             }
             const meta = extractMetaFromToolResult(m.params);
-            if (meta !== null)
-                settle(meta);
+            if (meta !== null) {
+                settle({ kind: 'meta', meta });
+                return;
+            }
+            // Identity-only result (ggui#537): settle NOW with the locator so
+            // boot starts immediately and the door runs after the handshake —
+            // waiting the full timeout for a slice this posture never sends
+            // would cost every spec-host view 30 s for nothing.
+            const locator = extractLocatorFromToolResult(m.params);
+            if (locator !== null)
+                settle({ kind: 'locator', locator });
         };
         window.addEventListener('message', onMessage);
         const timer = setTimeout(() => settle(null), timeoutMs);
     });
 }
 /**
- * Module-level guard for the App-mediated post-mount toolresult
- * re-listener. Ensures exactly one persistent
- * `app.addEventListener('toolresult', …)` registration even across
- * re-mounts (e.g. an agent fires a second `ggui_render` and the
- * listener re-applies through the published `applyRender`).
+ * Per-App guard for the persistent toolresult re-listener. Ensures
+ * exactly one `app.addEventListener('toolresult', …)` registration per
+ * 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
+ * iframe) always gets its own registration, never a stale latch.
  */
-let postMountListenerInstalled = false;
+const persistentToolResultListenerApps = new WeakSet();
 /**
  * Module-level handle to the active renderer's `applyRender`, published
  * by `bootProduction`'s `setup()` once the renderer is built. The
- * module-level {@link installPostMountListener} resolves this to re-mount
+ * module-level {@link installPersistentToolResultListener} resolves this to re-mount
  * on a host-re-emitted tool-result WITHOUT a fresh boot — no second mount,
  * no second WS. This is the no-WS live-re-render channel for
  * spec-compliant MCP-Apps hosts (claude.ai / ChatGPT / Claude Desktop)
@@ -1149,8 +1366,8 @@ let postMountListenerInstalled = false;
 let activeApplyRender = null;
 /**
  * Module-level guard for {@link installAnchorClickInterceptor}. Same
- * rationale as {@link postMountListenerInstalled}: re-mounts are
- * triggered by `installPostMountListener`, and stacking capture-phase
+ * rationale as {@link persistentToolResultListenerApps}: re-mounts are
+ * triggered by `installPersistentToolResultListener`, and stacking capture-phase
  * click listeners across re-mounts would multiply the audit envelopes
  * that fire on a single click.
  */
@@ -2681,7 +2898,7 @@ export function requestDisplayModeInParent(args) {
  * or honor an upstream `defaultPrevented` from a higher-priority
  * handler.
  *
- * Idempotent: re-mounts (via `installPostMountListener`) call this
+ * Idempotent: re-mounts (via `installPersistentToolResultListener`) call this
  * helper again; the {@link anchorClickInterceptInstalled} guard makes
  * subsequent calls a no-op.
  */
@@ -2822,15 +3039,26 @@ export function __resetInterceptorsForTest() {
     fullscreenInterceptInstalled = false;
 }
 /**
- * Install a persistent `app.addEventListener('toolresult', …)` listener
- * that catches `ui/notifications/tool-result` notifications arriving
- * AFTER the initial mount. Each new tool-result that carries a
- * different bootstrap (different sessionId / codeUrl / kind) triggers
- * a re-mount through the published `applyRender`. This closes the boot-only-
+ * Install the persistent `app.addEventListener('toolresult', …)`
+ * listener that catches `ui/notifications/tool-result` notifications
+ * arriving at ANY point in the document's life. Each tool-result that
+ * carries a different bootstrap (different sessionId / codeUrl / kind)
+ * triggers a re-mount through the published `applyRender`; arrivals
+ * before a renderer publishes `applyRender` no-op safely (and do NOT
+ * latch the dedupe key — see below). This closes the boot-only-
  * listener gap that prevented live re-render when an agent issued
  * a second `ggui_render` to the same render-resource.
  *
- * Idempotent: subsequent calls no-op via {@link postMountListenerInstalled}.
+ * REGISTRATION TIMING (ggui#586): called by `bootSequence` BEFORE
+ * `app.connect(transport)` — on a Tier-1/preResolved boot the one-shot
+ * Tier-2 listener never registers, so this used to be the FIRST
+ * `toolresult` registration and landed post-handshake (the ext-apps
+ * `_assertHandlerTiming` notice a guuey production render surfaced).
+ * The SDK's replay made that harmless; pre-registering removes the
+ * dependence on replay entirely.
+ *
+ * Idempotent per App: repeat calls with the same App no-op via
+ * {@link persistentToolResultListenerApps}.
  *
  * Why module-level vs scoped to a single mount: re-mounts re-apply
  * through `applyRender` while the listener stays live, and the
@@ -2840,17 +3068,13 @@ export function __resetInterceptorsForTest() {
  * Spec-canonical (post-Phase-1.19b.3): the previous hand-rolled
  * `window.addEventListener('message', …)` is gone; App handles every
  * inbound `ui/notifications/tool-result` envelope and dispatches via
- * its event system. Per-iframe single-tenancy means the App handle
- * comes from `getCurrentApp()` — set by `bootSequence`'s connect
- * path before this helper runs.
+ * its event system. The App handle is passed by the boot path
+ * directly (pre-connect, so `getCurrentApp()` is not yet set).
  */
-function installPostMountListener() {
-    if (postMountListenerInstalled)
+function installPersistentToolResultListener(app) {
+    if (persistentToolResultListenerApps.has(app))
         return;
-    const app = getCurrentApp();
-    if (app === null)
-        return; // pre-connect; caller bug, swallow safely
-    postMountListenerInstalled = true;
+    persistentToolResultListenerApps.add(app);
     let lastMetaKey = null;
     app.addEventListener('toolresult', (params) => {
         const meta = extractMetaFromToolResult(params);
@@ -2888,15 +3112,21 @@ function installPostMountListener() {
         ].join('|');
         if (key === lastMetaKey)
             return;
-        lastMetaKey = key;
         // Re-mount through the EXISTING renderer's `applyRender` (published
         // module-level by bootProduction's setup) — NOT a fresh boot. One
         // mount surface, one WS; the prior stale-closure / second-WS race
         // (the #290 root cause) is structurally impossible. Project the new
         // tool-result meta into a seed and re-apply it.
+        //
+        // The apply-null check runs BEFORE the dedupe key latches (ggui#586
+        // ordering): now that this listener registers pre-connect, the
+        // BOOT-path tool-result also flows through here while no renderer
+        // is published yet — latching its key then would silently dedupe a
+        // legitimate post-mount re-broadcast of the same envelope.
         const apply = activeApplyRender;
         if (apply === null)
             return; // no renderer published yet — no-op safely
+        lastMetaKey = key;
         void buildGguiSessionSeedInput(meta).then((seed) => {
             if (seed === null)
                 return;
@@ -2969,7 +3199,7 @@ function readLiveBootstrapShape() {
  * re-await the same postMessage or re-parse the same global), saving
  * up to the 30s postMessage timeout for spec-strict hosts.
  */
-function runBootProduction(preResolvedMeta) {
+function runBootProduction(preResolvedMeta, preResolvedLocator) {
     const { app, transport } = createDefaultApp();
     void bootProduction({
         doc: document,
@@ -2985,6 +3215,7 @@ function runBootProduction(preResolvedMeta) {
         onObserve: postObservabilityToParent,
         onLifecycle: postLifecycleToParent,
         ...(preResolvedMeta !== undefined ? { preResolvedMeta } : {}),
+        ...(preResolvedLocator !== undefined ? { preResolvedLocator } : {}),
     });
 }
 if (shouldAutostart() && typeof window !== 'undefined') {
@@ -3015,15 +3246,26 @@ if (shouldAutostart() && typeof window !== 'undefined') {
     }
     else {
         const buffered = readPendingToolResults();
+        const bufferedLocator = buffered === null ? readPendingToolResultLocator() : null;
         if (buffered !== null) {
             runBootProduction(buffered);
         }
+        else if (bufferedLocator !== null) {
+            // Read-plane-only posture (ggui#537): the buffered result named
+            // the view; the door resolves it right after the handshake.
+            runBootProduction(undefined, bufferedLocator);
+        }
         else if (readLiveBootstrapShape()) {
             runBootProduction();
         }
         else {
-            void awaitToolResultMeta(POSTMESSAGE_BOOT_TIMEOUT_MS).then((postMessageMeta) => {
-                runBootProduction(postMessageMeta ?? undefined);
+            void awaitToolResultMeta(POSTMESSAGE_BOOT_TIMEOUT_MS).then((pre) => {
+                if (pre === null)
+                    runBootProduction();
+                else if (pre.kind === 'meta')
+                    runBootProduction(pre.meta);
+                else
+                    runBootProduction(undefined, pre.locator);
             });
         }
     }
@@ -3302,10 +3544,38 @@ async function bootProduction(opts) {
                     ...(meta.gadgets !== undefined
                         ? { gadgetPackages: meta.gadgets.map((g) => g.package) }
                         : {}),
-                    ...(meta.themeId !== undefined ? { themeId: meta.themeId } : {}),
-                    ...(meta.themeMode !== undefined
-                        ? { themeMode: meta.themeMode }
+                    // Strict-CSP module variant (ggui#522 slice 2) — attached to
+                    // the INLINE SEED mount only, detected by the absence of the
+                    // server-assigned ledger fields (`buildGguiSessionSeedInput`
+                    // omits them; every wire-delivered GguiSession carries them).
+                    // The variant URL names the SEEDED bytes: a WS-delivered
+                    // body may differ, and importing a stale variant would paint
+                    // the WRONG component rather than fail. A WS redelivery of
+                    // the SAME bytes loses nothing — same code ⇒ the renderer
+                    // skips re-evaluation entirely.
+                    ...(meta.codeModuleUrl !== undefined &&
+                        render.type !== 'mcpApps' &&
+                        render.type !== 'system' &&
+                        !('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).
+                    ...(() => {
+                        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".
+                    ...(() => {
+                        const themeMode = resolveMountThemeMode(meta);
+                        return themeMode !== undefined ? { themeMode } : {};
+                    })(),
                     // Per-app theme overlay (St3 M2.2). Threaded straight from the
                     // bootstrap's `_meta["ai.ggui/render"].theme` (typed `AppTheme`,
                     // already injection-validated by the wire parser) onto the mount
@@ -3313,6 +3583,15 @@ async function bootProduction(opts) {
                     // `color-scheme` at `: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
+                    // precedence is CSS document order inside the scoped block
+                    // (base < hostPalette < appTheme, ggui#572/#573: slice wins,
+                    // host fallback), not a value-level ?? fallback.
+                    ...(() => {
+                        const hostPalette = hostAnnouncedPalette();
+                        return hostPalette !== undefined ? { hostPalette } : {};
+                    })(),
                     ...(wrapOuter !== undefined ? { wrapOuter } : {}),
                 };
             };
@@ -3336,17 +3615,17 @@ async function bootProduction(opts) {
                 }
                 await renderHandle.update(buildOpts(render));
             };
-            // Publish `applyRender` module-level + install the persistent
-            // post-mount tool-result listener. On a host-re-emitted tool-result
-            // (claude.ai re-broadcast; the Anthropic-SDK-strips-_meta refetch),
-            // the listener re-mounts through THIS `applyRender` — no fresh boot,
-            // no second WS. The no-WS live-re-render channel; for WS hosts the
-            // render-frame handler already covers re-render, so it's a
-            // redundant-safe fallback (guarded by the sessionId pin + liveTrio
-            // dedupe). Runs only on the production renderer path (tests that
-            // drive bootSequence without a renderer never reach setup()).
+            // 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
+            // publishing here is what arms it. On a host-re-emitted
+            // tool-result (claude.ai re-broadcast; the
+            // Anthropic-SDK-strips-_meta refetch), the listener re-mounts
+            // through THIS `applyRender` — no fresh boot, no second WS. The
+            // no-WS live-re-render channel; for WS hosts the render-frame
+            // handler already covers re-render, so it's a redundant-safe
+            // fallback (guarded by the sessionId pin + liveTrio dedupe).
             activeApplyRender = applyRender;
-            installPostMountListener();
             // Validator context — A2UI default for `_ggui:preview`; no
             // bootstrap-supplied overrides today (the
             // `extraReservedValidators` injection slot is reserved for a
@@ -3493,5 +3772,8 @@ async function bootProduction(opts) {
         ...(opts.preResolvedMeta !== undefined
             ? { preResolvedMeta: opts.preResolvedMeta }
             : {}),
+        ...(opts.preResolvedLocator !== undefined
+            ? { preResolvedLocator: opts.preResolvedLocator }
+            : {}),
     });
 }

package/dist/server.d.ts

@@ -34,3 +34,22 @@ export declare const RUNTIME_DIST_DIR: string;
  * `bootstrap.runtimeUrl`, never hardcodes it.
  */
 export declare const RUNTIME_BUNDLE_URL_PATH: "/_ggui/iframe-runtime.js";
+/**
+ * Directory of the static shim modules (`dist/shims/<name>.js`) the
+ * build emits alongside the bundle (ggui#522 slice 2 — `asset-url`
+ * delivery). The mcp-server captures these files at composition and
+ * serves them under `/_ggui/shims/<runtime-hash>/<name>.js` with the
+ * same immutable posture as the hashed bundle route: the shims ship in
+ * the same dist as the bundle, so the bundle's content hash versions
+ * both — a shim-affecting change in the design package also changes
+ * the bundle bytes.
+ */
+export declare const RUNTIME_SHIMS_DIR: string;
+/**
+ * The URL prefix under which the mcp-server publishes the shim
+ * directory family. The full shim directory for a given build is
+ * `<origin>${RUNTIME_SHIMS_URL_PREFIX}/<runtime-hash>` — the server-
+ * side `asset-url` rewrite composes shim URLs on it, and the shim
+ * route parses it back.
+ */
+export declare const RUNTIME_SHIMS_URL_PREFIX: "/_ggui/shims";

package/dist/server.js

@@ -70,3 +70,22 @@ export const RUNTIME_DIST_DIR = path.dirname(RUNTIME_BUNDLE_FILE);
  * `bootstrap.runtimeUrl`, never hardcodes it.
  */
 export const RUNTIME_BUNDLE_URL_PATH = '/_ggui/iframe-runtime.js';
+/**
+ * Directory of the static shim modules (`dist/shims/<name>.js`) the
+ * build emits alongside the bundle (ggui#522 slice 2 — `asset-url`
+ * delivery). The mcp-server captures these files at composition and
+ * serves them under `/_ggui/shims/<runtime-hash>/<name>.js` with the
+ * same immutable posture as the hashed bundle route: the shims ship in
+ * the same dist as the bundle, so the bundle's content hash versions
+ * both — a shim-affecting change in the design package also changes
+ * the bundle bytes.
+ */
+export const RUNTIME_SHIMS_DIR = path.resolve(here, 'shims');
+/**
+ * The URL prefix under which the mcp-server publishes the shim
+ * directory family. The full shim directory for a given build is
+ * `<origin>${RUNTIME_SHIMS_URL_PREFIX}/<runtime-hash>` — the server-
+ * side `asset-url` rewrite composes shim URLs on it, and the shim
+ * route parses it back.
+ */
+export const RUNTIME_SHIMS_URL_PREFIX = '/_ggui/shims';

package/dist/shims/app-components.js

@@ -0,0 +1 @@
+const M = (globalThis.__ggui__&&globalThis.__ggui__["appComponents"]||window["__GGUI_APP_COMPONENTS"]) || {}; const handler = { get(_, key) { return M[key]; } }; export default new Proxy({}, handler);

package/dist/shims/components.js

@@ -0,0 +1 @@
+const M = Object.assign({}, (globalThis.__ggui__&&globalThis.__ggui__["components"]||window["__GGUI_COMPONENTS"]||{}),(globalThis.__ggui__&&globalThis.__ggui__["primitives"]||window["__GGUI_PRIMITIVES"]||{}),(globalThis.__ggui__&&globalThis.__ggui__["compositions"]||window["__GGUI_COMPOSITIONS"]||{}),(globalThis.__ggui__&&globalThis.__ggui__["interact"]||window["__GGUI_INTERACT"]||{})); export const Container = M["Container"]; export const Card = M["Card"]; export const Stack = M["Stack"]; export const Row = M["Row"]; export const Grid = M["Grid"]; export const Box = M["Box"]; export const Divider = M["Divider"]; export const Spacer = M["Spacer"]; export const Text = M["Text"]; export const Heading = M["Heading"]; export const Button = M["Button"]; export const Input = M["Input"]; export const TextArea = M["TextArea"]; export const Select = M["Select"]; export const Checkbox = M["Checkbox"]; export const Toggle = M["Toggle"]; export const RadioGroup = M["RadioGroup"]; export const Slider = M["Slider"]; export const Badge = M["Badge"]; export const Spinner = M["Spinner"]; export const Skeleton = M["Skeleton"]; export const Avatar = M["Avatar"]; export const Alert = M["Alert"]; export const Progress = M["Progress"]; export const Image = M["Image"]; export const Icon = M["Icon"]; export const Link = M["Link"]; export const Tooltip = M["Tooltip"]; export const Table = M["Table"]; export const Tabs = M["Tabs"]; export const Toast = M["Toast"]; export const Accordion = M["Accordion"]; export const MotionKeyframes = M["MotionKeyframes"]; export const useMotion = M["useMotion"]; export const useAnimationKey = M["useAnimationKey"]; export const SearchField = M["SearchField"]; export const FormField = M["FormField"]; export const MenuItem = M["MenuItem"]; export const Tag = M["Tag"]; export const Dropdown = M["Dropdown"]; export const Autocomplete = M["Autocomplete"]; export const Breadcrumb = M["Breadcrumb"]; export const Pagination = M["Pagination"]; export const EmptyState = M["EmptyState"]; export const Stat = M["Stat"]; export const Stepper = M["Stepper"]; export const Markdown = M["Markdown"]; export const MarkdownInline = M["MarkdownInline"]; export const renderRichTextInlines = M["renderRichTextInlines"]; export const Header = M["Header"]; export const Sidebar = M["Sidebar"]; export const CardGrid = M["CardGrid"]; export const CommentThread = M["CommentThread"]; export const DataTable = M["DataTable"]; export const ChatWindow = M["ChatWindow"]; export const NavigationBar = M["NavigationBar"]; export const FileUploader = M["FileUploader"]; export const NotificationCenter = M["NotificationCenter"]; export const Modal = M["Modal"]; export const CommandPalette = M["CommandPalette"]; export const Footer = M["Footer"]; export const Hero = M["Hero"]; export const Clickable = M["Clickable"]; export const Hoverable = M["Hoverable"]; export const Pressable = M["Pressable"]; export default M;