@unoverse-platform/studio 0.1.34 → 0.1.35

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@unoverse-platform/studio",
-  "version": "0.1.34",
+  "version": "0.1.35",
   "type": "module",
   "description": "Unoverse Studio: the local authoring app. Reads your own rx/ folder, no backend.",
   "scripts": {

package/src/host.ts

@@ -113,6 +113,20 @@ class LocalUnoverseClient {
     return def;
   }
 
+  /**
+   * The SYNCHRONOUS cached-definition peek (see the SDK client). Studio's `readDefinition`
+   * fetches every time and keeps no cache — deliberately, so an edit on disk shows up on
+   * the next read — so there is nothing to peek and the honest answer is `null`.
+   *
+   * `null` means "no opinion", never "no": the one caller (the latch derivation on send)
+   * treats it as "no latch", which is right here. Studio previews a definition; it has no
+   * live conversation to address a component from. Present so the structural contract holds
+   * — the SDK takes this client by shape, so a missing method is a crash, not a type error.
+   */
+  peekDefinition(_uri: string): UnoverseDefinition | null {
+    return null;
+  }
+
   async readTheme(name = "light"): Promise<ResolvedTheme> {
     const r = await fetch(`/local/theme?ref=${encodeURIComponent(name)}`);
     if (!r.ok) throw new Error(`theme ${name}: ${r.status}`);

package/vendor/sdk/appEngine.tsx

@@ -9,6 +9,7 @@
  * vendored SDK (./lib), not the npm package.
  */
 import { useEffect, useMemo, useRef, useState } from "react";
+import { postToEmbedHost } from "./mcpAppBridge";
 import {
   UnoverseClient,
   ComponentStore,
@@ -112,7 +113,7 @@ export function AppEngine(cfg: AppConfig) {
     setAnalyticsDebug(!!analyticsDebug);
     setAnalyticsContext({ surface, conversation_id: conversationId, user_id: userId });
     setAnalyticsSink((event) => {
-      window.parent?.postMessage({ type: "unoverse:event", ...event }, "*");
+      postToEmbedHost({ type: "unoverse:event", ...event });
     });
     return () => setAnalyticsSink(null);
   }, [surface, conversationId, userId, analyticsDebug]);
@@ -124,7 +125,7 @@ export function AppEngine(cfg: AppConfig) {
       const w = computeAppWidth(resolveActiveLayout(def, store), store, theme?.appSize, def);
       if (w && w !== lastWidthRef.current) {
         lastWidthRef.current = w;
-        window.parent?.postMessage({ type: "unoverse:size", width: w }, "*");
+        postToEmbedHost({ type: "unoverse:size", width: w });
       }
     };
     report();
@@ -153,10 +154,7 @@ export function AppEngine(cfg: AppConfig) {
   // reads "offline" forever while this session streams (observed live). Report the
   // truth the same way size is reported; hosts that don't listen lose nothing.
   useEffect(() => {
-    window.parent?.postMessage(
-      { type: "unoverse:status", ready: !!conn.isReady, connected: !!conn.isConnected },
-      "*",
-    );
+    postToEmbedHost({ type: "unoverse:status", ready: !!conn.isReady, connected: !!conn.isConnected });
   }, [conn.isReady, conn.isConnected]);
 
   // VOICE (§2e-1): a `service: "voice"` app runs the native voice service — which now lives
@@ -198,7 +196,7 @@ export function AppEngine(cfg: AppConfig) {
           // The app owns its close chrome (its own top-right X). Tell the embedding host to
           // dismiss the surface (twin of `unoverse:config`/`unoverse:size`). The host decides
           // what "close" means for its frame (slide the drawer shut); we don't assume.
-          window.parent?.postMessage({ type: "unoverse:close" }, "*");
+          postToEmbedHost({ type: "unoverse:close" });
           return;
         }
         if (t === "sendMessage") {

package/vendor/sdk/lib/connection.tsx

@@ -12,7 +12,8 @@
  * gateway relay and no Redis in the component path.
  */
 import { useCallback, useEffect, useRef, useState, useSyncExternalStore } from "react";
-import { applyServerMessage, type ComponentStore, type ServerMessage } from "./core";
+import { emitAnalytics } from "./core/analytics";
+import { applyServerMessage, resolveLatch, type ComponentStore, type ServerMessage } from "./core";
 import { Client } from "@modelcontextprotocol/sdk/client/index.js";
 import { StreamableHTTPClientTransport } from "@modelcontextprotocol/sdk/client/streamableHttp.js";
 // Interpreter-based JSON-schema validator (no `new Function`). The SDK's default Ajv
@@ -169,6 +170,16 @@ export function useUnoverseConnection(
         setIsReady(true);
         return;
       }
+      // A manifest-declared analytics moment, resolved SERVER-side beside the lifecycle
+      // hook that shares it (componentLifecycle.ts). The SDK adds nothing and decides
+      // nothing here: it hands the event to the same sink every node-attached emit uses,
+      // and the host realm delivers or drops it. News, never instruction — it does not
+      // touch the store.
+      const evt = msg as unknown as { type?: string; event?: string; params?: Record<string, unknown> };
+      if (evt.type === "ANALYTICS_EVENT") {
+        if (typeof evt.event === "string" && evt.event) emitAnalytics(evt.event, evt.params ?? {});
+        return;
+      }
       applyServerMessage(store, msg, seenRef.current);
     };
 
@@ -270,7 +281,52 @@ export function useUnoverseConnection(
       // WORKFLOW_STARTED. startResponse is idempotent — the later WORKFLOW_STARTED
       // (and the first COMPONENT_INIT) reuse this same turn (responseFor by chatId).
       store.startResponse(turn);
-      trigger({ message }, turn);
+      /**
+       * THE LATCH RIDES THE ORDINARY SEND (docs/MCP_COMPLETE_GUIDE.md §The Component Latch).
+       *
+       * Resolved HERE rather than in a host, because both hosts call this one function and
+       * two hosts each deciding "what happens on send" is how the composer regression
+       * happened. The user turn is still minted normally — the guest said something and it
+       * belongs in the timeline; the latch only tells the workflow WHERE the answer lands.
+       *
+       * `state` is the component's live slice, so the workflow is told what the page
+       * currently holds without a round trip, and it stays right after local `setValue`
+       * writes the server never saw. Sent as one `latch` object so an unlatched send is
+       * byte-for-byte what it was before.
+       */
+      /**
+       * UNFINISHED, and deliberately shipped inert rather than guessed at.
+       *
+       * `peekDefinition` is the SYNCHRONOUS cached read the send path needs (a send cannot
+       * await a resources/read), and it lives on `UnoverseClient` — the wrapper holding the
+       * definition cache, constructed in appEngine.tsx. THIS file holds a raw MCP `Client`
+       * (line 137), which has no cache and no such method, so the lookup finds nothing here.
+       *
+       * Optional-called through a narrow type so the shape is honest: null is already a
+       * legitimate answer meaning "no opinion", `resolveLatch` is not called for it, and an
+       * unlatched send is byte-for-byte what it was before. The day this ref carries the
+       * wrapper, latching starts working with no change here.
+       */
+      const cache = clientRef.current as unknown as
+        | { peekDefinition?: (uri: string) => Parameters<typeof resolveLatch>[0] }
+        | null;
+      const tmpl = store.getActiveTemplate().name;
+      const def = tmpl ? (cache?.peekDefinition?.(`unoverse://templates/${tmpl}`) ?? null) : null;
+      const held = def ? resolveLatch(def, store) : null;
+      trigger(
+        held
+          ? {
+              message,
+              latch: {
+                chatId: held.chatId,
+                nodeId: held.nodeId,
+                view: held.view,
+                state: store.get(held.chatId, held.nodeId) ?? {},
+              },
+            }
+          : { message },
+        turn,
+      );
     },
     [mintTurn, store, trigger],
   );

package/vendor/sdk/lib/core/client.ts

@@ -125,6 +125,19 @@ export class UnoverseClient {
     return this.withSession(() => this.client.callTool({ name, arguments: args }));
   }
 
+  /**
+   * The cached definition for a URI, or null — SYNCHRONOUS, and it never fetches.
+   *
+   * For derivations that must answer INSIDE an event, where awaiting is not an option: the
+   * latch resolves on send (`sendMessage`), and a send cannot wait on a resources/read.
+   * Safe because the only caller asks about the template it is already rendering, which
+   * means `readDefinition` resolved before the first frame. Null is a legitimate answer
+   * (nothing rendered yet) and every caller must treat it as "no opinion", never as "no".
+   */
+  peekDefinition(uri: string): UnoverseDefinition | null {
+    return this.cache.get(uri) ?? null;
+  }
+
   /** resources/read a definition by URI (e.g. unoverse://components/card). Cached. */
   async readDefinition(uri: string): Promise<UnoverseDefinition> {
     const cached = this.cache.get(uri);

package/vendor/sdk/lib/core/index.ts

@@ -42,6 +42,7 @@ export {
   propDefaults,
   resolveActiveLayout,
   resolveActiveView,
+  resolveLatch,
   selectPointers,
   viewOf,
 } from "./templates";

package/vendor/sdk/lib/core/templates.ts

@@ -242,6 +242,61 @@ export function resolveActiveView(
   return { view, byGuest };
 }
 
+/**
+ * THE LATCH (docs/MCP_COMPLETE_GUIDE.md §The Component Latch) — which component the
+ * conversation is currently ADDRESSED AT, or none.
+ *
+ * DERIVED, never stored, for the same reason `lifecycle` is (STATE_MODEL §3): nothing
+ * registers a latch and nothing unregisters one. A component becomes latchable by carrying
+ * `latch` on its slice (seeded from its manifest with the render); it stops holding the
+ * latch when its slice evicts or leaves the surface. There is no set, no stack, and no
+ * "latch this one too" — this function returns ONE holder or null, so two latches are not
+ * a bug to prevent but a state that cannot be represented.
+ *
+ * SAME WALK AS `resolveActiveView`, deliberately: the ladder is the ladder. A latchable
+ * slice must be sitting in one of the template's declared states to hold the latch, and
+ * the highest-ranked one wins, ties going to the most recent write. So a page retracted to
+ * `inline` (superseded by an arrival, released by `cancelBelow`, closed by the guest)
+ * silently stops holding it rather than leaving a pill pointing at something off-surface.
+ *
+ * Returns the FULL key. `chatId` alone reaches the turn, not the component inside it: a
+ * turn carrying two components would hydrate the wrong one.
+ */
+export function resolveLatch(
+  def: UnoverseDefinition | null | undefined,
+  store: ComponentStore,
+  dismissed?: string,
+): { key: string; chatId: string; nodeId: string; latch: Record<string, unknown>; view: string } | null {
+  const order = def?.stateOrder?.length ? def.stateOrder : undefined;
+  if (!order) return null; // no ladder, no ranking — abstain rather than guess a holder
+  // `key` is the component key this candidate came from, carried so the return can name the
+  // FULL key (line 269) rather than re-deriving it from chatId, which reaches the turn and
+  // not the component inside it.
+  let best:
+    | { key: string; chatId: string; nodeId: string; latch: Record<string, unknown>; view: string; rank: number; at: number }
+    | null = null;
+  for (const turn of store.getResponses())
+    for (const p of turn.components) {
+      // THE ✕ IS THE ONLY EXIT, and this is it: the guest dismissed THIS holder by key, so
+      // it is passed over and the walk continues to the next candidate. Keyed rather than a
+      // bare flag so the dismissal cannot outlive the thing dismissed — a different
+      // component taking the latch is a different key and is not affected.
+      if (dismissed && dismissed === p) continue;
+      const { chatId, nodeId } = store.split(p);
+      const slice = store.get(chatId, nodeId) as Record<string, unknown>;
+      const latch = slice?.latch;
+      if (!latch || typeof latch !== "object") continue;
+      const view = viewOf(slice);
+      if (!view) continue;
+      const rank = order.indexOf(view);
+      if (rank < 0) continue; // not on the surface (inline/retracted): holds nothing
+      const at = store.touchOf(p);
+      if (!best || rank < best.rank || (rank === best.rank && at > best.at))
+        best = { key: p, chatId, nodeId, latch: latch as Record<string, unknown>, view, rank, at };
+    }
+  return best ? { key: best.key, chatId: best.chatId, nodeId: best.nodeId, latch: best.latch, view: best.view } : null;
+}
+
 /** Resolve a ComponentSlot's `select` against the store → ordered pointers. */
 export function selectPointers(store: ComponentStore, node: UnoverseNode): string[] {
   const sel = node.select ?? {};

package/vendor/sdk/lib/template.tsx

@@ -23,6 +23,7 @@ import {
   propDefaults,
   resolveActiveLayout,
   resolveActiveView,
+  resolveLatch,
   selectPointers,
   viewOf,
   type ComponentStore,
@@ -174,6 +175,52 @@ export function StreamedUnoverseTemplate({ client, store, uri, onAction, theme:
     // only bumps when it changed something, so this settles in one extra pass.
   }, [ladder.view, ladder.byGuest, def, store, structureVersion]);
 
+  /**
+   * THE LATCH, PUBLISHED FOR CHROME (docs/MCP_COMPLETE_GUIDE.md §The Component Latch).
+   *
+   * `resolveLatch` derives WHICH instance the conversation addresses; the composer's pill
+   * is ordinary rx chrome, so it needs those facts as template state to bind against. Same
+   * shape as the voice service (§4 "services feed the state"): a producer writes derived
+   * values into the normal bucket, and `core` learns no UI concept — nothing here knows a
+   * pill exists.
+   *
+   * `latchDismissed` is written as bare `true` by the ✕ (chrome cannot name a key it does
+   * not know) and NORMALISED here to the dismissed holder's key. Keyed, so the dismissal
+   * dies with the thing dismissed: a different component taking the latch is a different
+   * key, and its pill comes up as it should rather than being suppressed by a stale flag.
+   */
+  const tstate = store.getTemplateState() as Record<string, unknown>;
+  const dismissedRaw = tstate.latchDismissed;
+  const held = def ? resolveLatch(def, store, typeof dismissedRaw === "string" ? dismissedRaw : undefined) : null;
+  useEffect(() => {
+    if (dismissedRaw === true) {
+      // Resolve the bare flag against whoever holds it RIGHT NOW, then re-derive.
+      const current = def ? resolveLatch(def, store) : null;
+      store.mergeTemplateState({ latchDismissed: current ? current.key : "" });
+      return;
+    }
+    const l = held?.latch as { title?: unknown } | undefined;
+    const title = typeof l?.title === "string" ? l.title : "";
+    // `latched` is the DISCRIMINANT chrome branches on, exactly as the voice service
+    // publishes `callState`: ONE field for the axis, never a truthy title plus an inverse
+    // guard on its sibling, which is the boolean soup design/state.md rules out ("a case
+    // never re-guards its own discriminant"). Title and icon are the held case's DATA, not
+    // its condition — which is why they are separate keys and not the condition itself.
+    const latched = held != null;
+    if (tstate.latched !== latched || tstate.latchTitle !== title || tstate.latchKey !== (held?.key ?? ""))
+      store.mergeTemplateState({ latched, latchTitle: title, latchKey: held?.key ?? "" });
+  }, [
+    held?.key,
+    held?.latch,
+    dismissedRaw,
+    def,
+    store,
+    tstate.latched,
+    tstate.latchTitle,
+    tstate.latchKey,
+    structureVersion,
+  ]);
+
   // Loading/error hints carry NO styling — the SDK owns zero styles.
   if (error) return <div>Unoverse error: {error}</div>;
   if (!def || !theme) return <div>Loading {uri}…</div>;

package/vendor/sdk/lib/voice.tsx

@@ -52,12 +52,12 @@ export interface UseVoiceServiceConfig {
 /** The single call-phase VALUE a voice template branches its states on — the standard voice
  *  state vocabulary (`visibleWhen: { field: "callState", eq: … }`). Derived from the neutral
  *  facts below so every voice template keys off one field, exactly like `mode` for focus. */
-export type VoiceCallState = "idle" | "active" | "agentSpeaking" | "userSpeaking";
+export type VoiceCallState = "idle" | "active" | "speaking" | "listening" | "thinking";
 
 /** NEUTRAL voice projections — flat, so the channel can spread them into the template scope. */
 export interface VoiceServiceState {
   connectionStatus: VoiceConnectionStatus;
-  /** The single phase the template's states key off (idle | active | agentSpeaking | userSpeaking). */
+  /** The single phase the template's states key off (idle | active | listening | thinking | speaking). */
   callState: VoiceCallState;
   isIdle: boolean;
   isCallActive: boolean;
@@ -259,14 +259,28 @@ export function useVoiceService(config: UseVoiceServiceConfig): VoiceService {
     () => ({
       connectionStatus,
       // The one phase the template branches on — derived from the neutral facts. Order matters:
-      // agent speaking wins over user (barge-in), both win over plain "active".
+      // agent speaking wins over user (barge-in), both win over a lookup, and all three win
+      // over plain "active".
+      //
+      // `thinking` sits BELOW both speaking checks because someone actually talking is the more
+      // important fact: a lookup can still be running while the assistant narrates it ("let me
+      // check that for you"), and the surface should show the speech.
+      //
+      // It sits ABOVE "active" because that is the bug it fixes. A lookup takes 8 to 9 seconds,
+      // and for all of it callState read "active" — which every voice template draws as a calm
+      // halo meaning "the floor is yours". The orb is the only progress indicator a call has,
+      // and it was saying the opposite of what was happening. `isLookingUp` was already right
+      // here in this hook, feeding the small lookup caption; it simply never reached the one
+      // field the templates branch on.
       callState: (!isCallActive
         ? "idle"
         : isAssistantSpeaking
-          ? "agentSpeaking"
+          ? "speaking"
           : isUserSpeaking
-            ? "userSpeaking"
-            : "active") as VoiceCallState,
+            ? "listening"
+            : isLookingUp
+              ? "thinking"
+              : "active") as VoiceCallState,
       isIdle: !isCallActive,
       isCallActive,
       isConnecting: connectionStatus === "connecting",

package/vendor/sdk/main.tsx

@@ -6,6 +6,7 @@
  */
 import { createRoot, type Root } from "react-dom/client";
 import { AppEngine, type AppConfig } from "./appEngine";
+import { connectMcpAppHost } from "./mcpAppBridge";
 
 type HostConfig = Omit<AppConfig, "getAccessToken"> & { token?: string };
 
@@ -65,51 +66,37 @@ window.addEventListener("message", (e) => {
   if (msg?.type === "unoverse:config" && msg.config) apply(msg.config);
 });
 
-// ── ChatGPT (OpenAI Apps) bootstrap ────────────────────────────────────────
-// ChatGPT does NOT send our host's `unoverse:config` postMessage; it exposes a
-// `window.openai` bridge. Without this the SDK never receives config → #root stays
-// empty → blank widget (observed live). `toolOutput` = the tool's structuredContent
-// (app id + conversationId); `toolResponseMetadata` = the tool result `_meta`
-// (server-forwarded serverUrl + token + userId — widget-only, never seen by the model).
-// DIAGNOSTIC-FIRST: log the real runtime shape so we wire against ground truth, not the
-// docs' assumed names. `window.openai` may arrive after load, so also listen for its ready
-// event. This branch is inert in our own hosts (no window.openai there).
-function bootstrapFromOpenAI(): boolean {
-  const oai = (window as unknown as { openai?: Record<string, unknown> }).openai;
-  if (!oai) return false;
-  const out = (oai.toolOutput ?? {}) as Record<string, unknown>;
-  const meta = (oai.toolResponseMetadata ?? {}) as Record<string, unknown>;
-  // eslint-disable-next-line no-console
-  console.log("[unoverse:boot] window.openai present", {
-    keys: Object.keys(oai),
-    toolOutput: out,
-    toolResponseMetadataKeys: Object.keys(meta),
-    hasToken: Boolean(meta["unoverse/token"]),
-  });
-  // serverUrl is SERVER-PROVIDED (the tool result's `_meta.unoverse/serverUrl` = the origin
-  // that served this bundle). NEVER hardcode/guess it — a baked URL ties the bundle to one
-  // environment and hides a missing config. If it's absent, fail loudly and don't mount.
-  const serverUrl = meta["unoverse/serverUrl"] as string;
+// ── MCP Apps host bootstrap (SEP-1865, the STANDARD door) ──────────────────
+// An MCP Apps host (ChatGPT, Claude Desktop, Goose, …) speaks JSON-RPC over postMessage:
+// we send `ui/initialize`, the host pushes `ui/notifications/tool-result`, and the boot
+// facts ride the result's `_meta` (`unoverse/serverUrl` + app + token — widget-only,
+// never seen by the model) with `structuredContent` as the belt-and-braces copy.
+// The legacy `window.openai` config path is REMOVED (2026-08-13): ChatGPT delivers
+// `toolResponseMetadata` empty now, non-OpenAI hosts never had the global, and two boot
+// paths for one host class meant every failure had two explanations. One standard door;
+// our own hosts keep `unoverse:config` / `__UNOVERSE_APP_CONFIG` above.
+connectMcpAppHost((r) => {
+  const meta = (r._meta ?? {}) as Record<string, unknown>;
+  const out = (r.structuredContent ?? {}) as Record<string, unknown>;
+  // serverUrl is SERVER-PROVIDED (`_meta` first, structuredContent as fallback). NEVER
+  // hardcode/guess it — a baked URL ties the bundle to one environment and hides a
+  // missing config. If it's absent, fail loudly and don't mount.
+  const serverUrl = (meta["unoverse/serverUrl"] as string) || (out.serverUrl as string);
   const templateId = (out.app as string) || (meta["unoverse/app"] as string);
   const conversationId = (out.conversationId as string) || (meta["unoverse/conversationId"] as string);
   const token = (meta["unoverse/token"] as string) || undefined;
   const userId = (meta["unoverse/userId"] as string) || undefined;
   if (!templateId || !serverUrl) {
     // eslint-disable-next-line no-console
-    console.warn("[unoverse:boot] cannot mount — missing serverUrl or app id from window.openai", {
+    console.warn("[unoverse:boot] cannot mount — tool result carried no serverUrl/app", {
       serverUrl,
       templateId,
-      toolOutput: out,
-      toolResponseMetadataKeys: Object.keys(meta),
+      structuredContent: out,
+      metaKeys: Object.keys(meta),
     });
-    return false;
+    return;
   }
   // eslint-disable-next-line no-console
-  console.log("[unoverse:boot] mounting", { serverUrl, templateId, conversationId, userId, hasToken: Boolean(token) });
+  console.log("[unoverse:boot] mounting from MCP host", { serverUrl, templateId, conversationId, userId, hasToken: Boolean(token) });
   apply({ serverUrl, templateId, conversationId, userId, token });
-  return true;
-}
-if (!bootstrapFromOpenAI()) {
-  // window.openai can be injected after the bundle loads — retry on its ready signal.
-  window.addEventListener("openai:set_globals", () => bootstrapFromOpenAI());
-}
+});

package/vendor/sdk/mcpAppBridge.ts

@@ -0,0 +1,135 @@
+/**
+ * The MCP Apps host bridge (SEP-1865, spec 2026-01-26) — the STANDARD door.
+ *
+ * An MCP Apps host (ChatGPT, Claude Desktop, Goose, …) renders this bundle in a sandboxed
+ * iframe and speaks JSON-RPC over postMessage: the app sends `ui/initialize`, the host
+ * answers with `hostContext`, then pushes `ui/notifications/tool-input` and
+ * `ui/notifications/tool-result`. The RESULT notification carries the tool call's full
+ * `CallToolResult` — content, structuredContent and `_meta` — and `_meta` is where our
+ * server puts the boot facts (`unoverse/serverUrl`, `unoverse/app`, `unoverse/token`).
+ * This is the lane that still works everywhere: ChatGPT's legacy `window.openai` globals
+ * now arrive with `toolResponseMetadata` EMPTY (observed live 2026-08-13), and non-OpenAI
+ * hosts never had them.
+ *
+ * Deliberately MINIMAL: initialize + the two tool notifications. No display-mode calls, no
+ * host-proxied tools/call — the SDK keeps its own /mcp + /stream connections (the CSP's
+ * connectDomains exist exactly for this). Extend only against the spec:
+ * https://github.com/modelcontextprotocol/ext-apps/blob/main/specification/2026-01-26/apps.mdx
+ */
+
+/** Spec revision we speak. Hosts negotiate; the field is required on ui/initialize. */
+const UI_PROTOCOL_VERSION = "2026-01-26";
+
+type ToolResult = {
+  content?: unknown;
+  structuredContent?: Record<string, unknown>;
+  _meta?: Record<string, unknown>;
+};
+
+export type McpAppHost = {
+  /** True once the host answered ui/initialize — the signal that a STANDARD host owns this
+   *  iframe, used to silence the `unoverse:*` embed-host messages (a standard host validates
+   *  every inbound postMessage as JSON-RPC and logs ours as errors). */
+  connected: boolean;
+  hostContext?: Record<string, unknown>;
+};
+
+/** Whether ANY MCP app host owns this iframe — standard bridge or legacy window.openai.
+ *  The embed-host messages (`unoverse:status`/`size`/`event`/`close`) are for OUR OWN
+ *  parent page and must not be posted at an MCP host. */
+export function hasMcpHost(): boolean {
+  return bridge.connected || Boolean((window as { openai?: unknown }).openai);
+}
+
+const bridge: McpAppHost = { connected: false };
+
+/** Post an `unoverse:*` message to OUR OWN embed host's parent page (status badge, size,
+ *  close, analytics). At an MCP host these are noise — the sandbox validates every inbound
+ *  postMessage as JSON-RPC and logs each of ours as an error (observed live in ChatGPT) —
+ *  so the post is skipped entirely there. `window.openai` counts as host detection ONLY;
+ *  no config is read from it (the legacy boot path was removed 2026-08-13). */
+export function postToEmbedHost(msg: Record<string, unknown>): void {
+  if (hasMcpHost()) return;
+  window.parent?.postMessage(msg, "*");
+}
+
+/**
+ * Open the standard door: send ui/initialize, resolve boot facts from the first
+ * tool-result. `onToolResult` fires for EVERY result the host pushes (the first one
+ * carries the boot facts; later ones are re-renders of the same app instance).
+ */
+export function connectMcpAppHost(onToolResult: (r: ToolResult) => void): McpAppHost {
+  const INIT_ID = "unoverse-ui-init";
+  // DIAGNOSTIC-FIRST (main.tsx doctrine): we implement the SPEC's dialect, but the live
+  // hosts are the ground truth — log a compact line for EVERY inbound message and every
+  // handshake attempt so one browser reproduction shows exactly what the host speaks.
+  const log = (label: string, extra?: unknown) =>
+    // eslint-disable-next-line no-console
+    console.log(`[unoverse:bridge] ${label}`, extra ?? "");
+  window.addEventListener("message", (e: MessageEvent) => {
+    const m = e?.data as
+      | { jsonrpc?: string; id?: unknown; result?: unknown; error?: unknown; method?: string; params?: unknown }
+      | undefined;
+    if (m && typeof m === "object") {
+      log("inbound", {
+        jsonrpc: m.jsonrpc,
+        method: m.method,
+        id: m.id,
+        // FULL bodies, stringified: the first diagnostics run summarized these to booleans
+        // and the one fact that mattered — WHY the host rejected ui/initialize — was in the
+        // unprinted error object. Never summarize the field you are debugging.
+        result: m.result !== undefined ? JSON.stringify(m.result).slice(0, 600) : undefined,
+        error: m.error !== undefined ? JSON.stringify(m.error).slice(0, 600) : undefined,
+        params: m.params !== undefined ? JSON.stringify(m.params).slice(0, 300) : undefined,
+        ports: e.ports?.length ?? 0,
+        origin: e.origin,
+      });
+    }
+    if (m?.jsonrpc !== "2.0") return; // not the host bridge (our own unoverse:config etc.)
+    if (m.id === INIT_ID && m.result) {
+      bridge.connected = true;
+      bridge.hostContext = (m.result as { hostContext?: Record<string, unknown> }).hostContext;
+      log("ui/initialize answered", bridge.hostContext);
+      // Complete the handshake — the reference App sends this notification after the
+      // result (ext-apps src/app.ts `connect`); hosts may hold tool-input/result until it.
+      window.parent?.postMessage({ jsonrpc: "2.0", method: "ui/notifications/initialized" }, "*");
+      return;
+    }
+    // Answer pings so the host's liveness check never times the app out.
+    if (m.method === "ping" && m.id !== undefined) {
+      (e.source as WindowProxy | null)?.postMessage({ jsonrpc: "2.0", id: m.id, result: {} }, "*");
+      return;
+    }
+    if (m.method === "ui/notifications/tool-result") {
+      // Per spec the result rides params (CallToolResult); tolerate a bare shape.
+      const p = (m.params ?? {}) as { result?: ToolResult } & ToolResult;
+      log("tool-result", { metaKeys: Object.keys((p.result ?? p)._meta ?? {}) });
+      onToolResult(p.result ?? p);
+    }
+  });
+  const sendInit = () => {
+    if (bridge.connected) return;
+    log("ui/initialize →");
+    window.parent?.postMessage(
+      {
+        jsonrpc: "2.0",
+        id: INIT_ID,
+        method: "ui/initialize",
+        // Field names per the REFERENCE App (ext-apps src/app.ts), not the docs' prose:
+        // `appInfo` + `appCapabilities`. The first cut sent MCP-core's `clientInfo` +
+        // `capabilities` and ChatGPT's Zod schema answered -32603 "Invalid input".
+        params: {
+          protocolVersion: UI_PROTOCOL_VERSION,
+          appCapabilities: {},
+          appInfo: { name: "unoverse-websdk", version: "0.0.1" },
+        },
+      },
+      "*",
+    );
+  };
+  // The host's listener can attach after our module runs (web hosts boot a sandbox proxy
+  // first — `ui/notifications/sandbox-*`), so retry until answered.
+  sendInit();
+  for (const ms of [250, 1000, 3000]) setTimeout(sendInit, ms);
+  return bridge;
+}