@unoverse-platform/studio 0.1.102 → 0.1.104

package/vendor/sdk/lib/dom/component.ts

@@ -0,0 +1,333 @@
+/**
+ * ONE COMPONENT, in plain DOM: reads a definition by URI from the server and draws it.
+ *
+ * One component, two data sources. A definition cannot tell which is drawing it:
+ *
+ *   data source          give it                        state lives in
+ *   a plain object       `uri` + `data`                 a local slice, here
+ *   the live stream      `store` + `chatId` + `nodeId`  the store's slice
+ *
+ * It draws inside its own shadow root (./isolate) unless the host owns isolation.
+ */
+import type { ResolvedTheme, UnoverseDefinition, UnoverseNode } from "../core/types";
+import type { ComponentStore } from "../core/store";
+import { dispatchAction } from "../core/actions";
+import { matches } from "../core/conditions";
+import { heldPointer, stateOfUri } from "../core/apps";
+import { keyframesCss } from "../style";
+import type { ActionHandler } from "../actions";
+import { setChildren, setStyle } from "./element";
+import { isolatedRoot } from "./isolate";
+import { mountQueue } from "./mounted";
+import { regionView, type Leaf, type Region } from "./region";
+import { ensureFontStylesheets, fetchTheme, type ThemeSource } from "./theme";
+import type { Data } from "./types";
+
+/** What reads definitions and themes: the MCP client, or anything answering the same calls. */
+export interface DefinitionSource extends ThemeSource {
+  readDefinition(address: string): Promise<UnoverseDefinition>;
+}
+
+export interface ComponentOptions {
+  client: DefinitionSource;
+  /** STATIC source: the definition to draw, e.g. "unoverse://components/card". */
+  uri?: string;
+  /** STATIC source: instance data bound into the definition. */
+  data?: Data;
+  /** LIVE source: the store. With it, the address and data come from the instance. */
+  store?: ComponentStore;
+  chatId?: string;
+  nodeId?: string;
+  /** Neutral turn state merged into the data scope (e.g. `streaming`). Live source only. */
+  extraData?: Data;
+  onAction?: ActionHandler;
+  /** The resolved theme; omitted, it is fetched for the definition's org. */
+  theme?: ResolvedTheme;
+  /** Draw inside a shadow root (default true). False only for a host with its own isolation. */
+  isolate?: boolean;
+  /** A surface's single occupant fills the surface: the wrapper takes the frame's height. */
+  fill?: boolean;
+  /** What a `Place` in this definition draws; only its host knows. Without it, nothing. */
+  place?: (name: string) => Node[] | null;
+  /** The app's state, when it lives in another store (live source only). */
+  appStore?: ComponentStore;
+  doc?: Document;
+  /** False when the host steps the template with the arrow keys itself (a page, which picks
+   *  the one template the keys move), so one press is never two steps. */
+  arrowKeys?: boolean;
+}
+
+export interface ComponentMount extends Leaf {
+  /** Change what the component is given; it draws again. */
+  update(next: Partial<ComponentOptions>): void;
+}
+
+const message = (doc: Document, text: string) => {
+  const d = doc.createElement("div");
+  d.textContent = text;
+  return d;
+};
+
+export function mountComponent(options: ComponentOptions): ComponentMount {
+  let o: ComponentOptions = { ...options };
+  // Isolated unless a host says `false`: a prop left out arrives as `undefined` and keeps the default.
+  const isolated = () => o.isolate !== false;
+  const doc = o.doc ?? document;
+  let def: UnoverseDefinition | null = null;
+  let error: string | null = null;
+  let localSlice: Data = {};
+  let defUri: string | null = null;
+  let fetched: ResolvedTheme | null = null;
+  let themeName: string | null = null;
+  let alive = true;
+  let defaults: Data = {};
+
+  // The page elements: a message while loading, else the drawing (isolated or not).
+  let nodes: Node[] = [];
+  const iso = isolatedRoot(doc);
+  const plain = doc.createElement("div");
+  plain.style.display = "contents";
+  const keyframes = doc.createElement("style");
+  const mounted = mountQueue(() => (isolated() ? iso.host.isConnected : keyframes.isConnected));
+  const tree = regionView(doc, mounted);
+
+  // Snapshots of the store, so a change elsewhere in it does not draw this again.
+  let seen: unknown[] = [];
+  const snapshot = () =>
+    o.store ? [o.store.get(o.chatId ?? "", o.nodeId ?? ""), o.store.getType(o.chatId ?? "", o.nodeId ?? ""), o.store.getComponentUrl(o.chatId ?? "", o.nodeId ?? ""), o.appStore?.getAppState()] : [];
+  const changed = () => {
+    const now = snapshot();
+    const diff = now.some((v, i) => v !== seen[i]);
+    seen = now;
+    return diff;
+  };
+  let unsubscribe = () => {};
+  let unsubscribeApp = () => {};
+  const subscribe = () => {
+    unsubscribe();
+    unsubscribeApp();
+    unsubscribe = o.store ? o.store.subscribe(() => changed() && draw()) : () => {};
+    unsubscribeApp = o.appStore && o.appStore !== o.store ? o.appStore.subscribe(() => changed() && draw()) : () => {};
+  };
+
+  const address = () => {
+    const { store, chatId = "", nodeId = "" } = o;
+    if (!store) return o.uri ?? null;
+    const url = store.getComponentUrl(chatId, nodeId);
+    const type = store.getType(chatId, nodeId);
+    return url ?? (type ? `unoverse://components/${type}` : null);
+  };
+
+  // ONE ACTION RULE, TWO OWNERS OF THE SLICE. `setValue` writes THIS instance's keys.
+  const handleAction: ActionHandler = (action, scope, meta) => {
+    const { store, chatId = "", nodeId = "", onAction, appStore } = o;
+    if (store) {
+      dispatchAction(action, scope, {
+        store,
+        chatId,
+        nodeId,
+        appStore,
+        // Server actions carry the INSTANCE context (which component, its current slice).
+        sendToServer: onAction ? (t, payload) => onAction(t, payload, { chatId, nodeId, type: store.getType(chatId, nodeId), state: store.get(chatId, nodeId) }) : undefined,
+      });
+      return;
+    }
+    // No store, so the slice is local: a tab works in a preview with no state code around it.
+    if (action && typeof action === "object" && (action as { type?: string }).type === "setValue") {
+      const values = ((action as { values?: { key: string; value: unknown }[] }).values ?? []).filter((v) => v && typeof v.key === "string");
+      if (values.length) {
+        localSlice = { ...localSlice, ...Object.fromEntries(values.map((v) => [v.key, v.value])) };
+        draw();
+      }
+    }
+    o.onAction?.(action, scope, meta);
+  };
+
+  // ARROW KEYS STEP A TEMPLATE while it holds the main place and its state says `arrows: true`,
+  // through the same setValue its own Back and Next make. Typing in a field never steps.
+  const onKey = (e: KeyboardEvent) => {
+    const d = def as (UnoverseDefinition & { kind?: string; stateTree?: { name: string; on?: string; arrows?: boolean; states?: { name: string }[] }[]; statePlaces?: Record<string, string> }) | null;
+    if (o.arrowKeys === false || d?.kind !== "template" || (e.key !== "ArrowRight" && e.key !== "ArrowLeft")) return;
+    const slice = (o.store ? sourceData() : localSlice) as Data | undefined;
+    const face = String(slice?.state ?? d.state?.state ?? "");
+    const branch = (d.stateTree ?? []).find((s) => s.name === face);
+    const steps = branch?.states?.map((s) => s.name) ?? [];
+    if (!branch?.on || !branch.arrows || steps.length < 2 || d.statePlaces?.[face] !== "main") return;
+    const t = e.target as HTMLElement | null;
+    if (t && (t.isContentEditable || /^(INPUT|TEXTAREA|SELECT)$/.test(t.tagName))) return;
+    const on = branch.on;
+    const cur = String(slice?.[on] ?? d.state?.[on] ?? steps[0]);
+    const i = steps.indexOf(cur) + (e.key === "ArrowRight" ? 1 : -1);
+    if (i < 0 || i >= steps.length) return;
+    e.preventDefault();
+    handleAction({ type: "setValue", values: [{ key: on, value: steps[i] }] }, {});
+  };
+  doc.addEventListener("keydown", onKey);
+
+  const sourceData = (): Data | undefined => {
+    const { store, chatId = "", nodeId = "", extraData, data } = o;
+    if (store) {
+      const live = store.get(chatId, nodeId) as Data | undefined;
+      return extraData ? { ...(live ?? {}), ...extraData } : live;
+    }
+    const a = address();
+    const hashState = a ? stateOfUri(a).state : undefined;
+    return hashState && data?.state == null ? { state: hashState, ...(data ?? {}) } : data;
+  };
+
+  const loadDefinition = (uri: string | null) => {
+    if (uri === defUri) return;
+    defUri = uri;
+    def = null;
+    error = null;
+    localSlice = {};
+    if (!uri) return;
+    const asked = uri;
+    o.client
+      .readDefinition(uri)
+      .then((d) => {
+        if (!alive || defUri !== asked) return;
+        def = d;
+        defaults = Object.fromEntries(Object.entries((d.props ?? {}) as Record<string, { default?: unknown }>).map(([k, v]) => [k, v?.default]));
+        draw();
+      })
+      .catch((e) => {
+        if (!alive || defUri !== asked) return;
+        error = String(e?.message ?? e);
+        draw();
+      });
+  };
+
+  const loadTheme = () => {
+    if (o.theme || !def) return;
+    const name = def.org ? `${def.org}/light` : "light";
+    if (name === themeName) return;
+    themeName = name;
+    fetchTheme(o.client, name)
+      .then((t) => {
+        if (!alive || themeName !== name) return;
+        fetched = t;
+        draw();
+      })
+      .catch(() => {});
+  };
+
+  /** What a slot in this definition holds: a template's sections claim instances in the
+   *  SAME store by the face they wear; a Place is filled by the host. TEMPLATES ONLY for
+   *  claims: an ordinary component's flow slot belongs to the app's timeline. */
+  const slotFor = (theme: ResolvedTheme) => {
+    const { store, place } = o;
+    if (!((store && ((def as { sections?: unknown }).sections || (def as { held?: unknown }).held)) || place)) return undefined;
+    return (node: UnoverseNode, data: Data): Region => {
+      if (node.type === "Place") {
+        const name = String((node as { name?: unknown }).name ?? "");
+        const placed = place?.(name);
+        return placed ? { kind: "nodes", key: `place:${name}`, nodes: placed } : { kind: "none" };
+      }
+      if (!store) return { kind: "none" };
+      // WHAT A TEMPLATE HOLDS: this item's own instance, unless its state lifted it elsewhere.
+      if ((node as { hold?: unknown }).hold) {
+        const held = heldPointer(store, node, data ?? {}, { chatId: o.chatId ?? "", nodeId: o.nodeId ?? "" });
+        if (!held) return { kind: "none" };
+        const { chatId: c, nodeId: n } = store.split(held);
+        const opts = { client: o.client, store, chatId: c, nodeId: n, onAction: o.onAction, theme, appStore: o.appStore, doc };
+        return { kind: "list", key: "held", flip: false, items: [{ key: n, make: () => mountComponent(opts), refresh: (leaf: Leaf) => (leaf as ComponentMount).update(opts) }] };
+      }
+      const claim = node.select?.where;
+      const pointers = store
+        .getResponses()
+        .flatMap((r) => r.components)
+        .filter((p) => {
+          const { chatId: c, nodeId: n } = store.split(p);
+          if (n === o.nodeId) return false; // never claim the instance drawing the slot
+          return claim ? matches(claim, (store.get(c, n) ?? {}) as Data) : true;
+        })
+        .slice(0, node.select?.limit ?? undefined);
+      if (!pointers.length)
+        return node.fallback ? { kind: "tree", key: "fallback", node: node.fallback, data: {}, ctx: { theme, onAction: handleAction, defs: def!.defs } } : { kind: "none" };
+      return {
+        kind: "list",
+        key: "claimed",
+        flip: false,
+        items: pointers.map((p) => {
+          const { chatId: c, nodeId: n } = store.split(p);
+          const opts = { client: o.client, store, chatId: c, nodeId: n, onAction: o.onAction, theme, appStore: o.appStore, doc };
+          return { key: n, make: () => mountComponent(opts), refresh: (leaf: Leaf) => (leaf as ComponentMount).update(opts) };
+        }),
+      };
+    };
+  };
+
+  // A component draws again on its own (a definition arriving, a store change), so it puts
+  // its new elements where the old ones stand: the host around it need not draw too.
+  const show = (next: Node[]) => {
+    const at = nodes[0];
+    const parent = at?.parentNode;
+    if (parent && (next.length !== nodes.length || next.some((n, i) => n !== nodes[i]))) {
+      for (const n of next) parent.insertBefore(n, at);
+      for (const n of nodes) if (!next.includes(n)) n.parentNode?.removeChild(n);
+    }
+    nodes = next;
+  };
+
+  const draw = () => {
+    if (!alive) return;
+    seen = snapshot();
+    const a = address();
+    loadDefinition(a ? stateOfUri(a).uri : null);
+    loadTheme();
+    const theme = o.theme ?? fetched;
+    ensureFontStylesheets(theme, doc);
+    const say = (text: string) => {
+      tree.destroy();
+      show([message(doc, text)]);
+    };
+    // Loading and error hints carry NO styling: the SDK owns zero styles.
+    if (error) return say(`Unoverse error: ${error}`);
+    if (o.store && !o.store.getType(o.chatId ?? "", o.nodeId ?? "")) return say("waiting for COMPONENT_INIT…");
+    if (!def || !theme) return say(`Loading ${defUri ?? "component"}…`);
+    // Defaults beneath; the app's state, then the definition's own state, then the
+    // instance's values above; a value the component wrote itself on top (static source).
+    const merged = o.store
+      ? { ...defaults, ...(o.appStore?.getAppState() ?? {}), ...(def.state ?? {}), ...(sourceData() ?? {}) }
+      : { ...defaults, ...(def.state ?? {}), ...(sourceData() ?? {}), ...localSlice };
+    const slot = slotFor(theme);
+    tree.set({ kind: "tree", key: `def:${defUri}`, node: def.root, data: merged, ctx: { theme, onAction: handleAction, defs: def.defs }, slot });
+    keyframes.textContent = keyframesCss(theme);
+    // The container mirrors the root's sizing intent: a root of `height: "full"` needs a
+    // definite chain, so it passes the host's height through; any other fits its content.
+    const fillsHost = o.fill || ((def.root as { style?: Data })?.style?.height ?? null) === "full";
+    const rootStyle = { ...(theme.root as Data), ...(fillsHost ? { height: "100%" } : {}), ...(o.fill ? { flex: "1 1 auto", minHeight: 0 } : {}) } as Record<string, string>;
+    if (isolated()) {
+      setStyle(iso.root, rootStyle);
+      setChildren(iso.root, [keyframes, ...tree.nodes]);
+      show([iso.host]);
+    } else {
+      setStyle(plain, { display: "contents", ...(theme.root as Record<string, string>) });
+      setChildren(plain, tree.nodes);
+      show([keyframes, plain]);
+    }
+  };
+
+  subscribe();
+  draw();
+
+  return {
+    get nodes() {
+      return nodes;
+    },
+    update(next) {
+      const storeChanged = (next.store !== undefined && next.store !== o.store) || (next.appStore !== undefined && next.appStore !== o.appStore);
+      o = { ...o, ...next };
+      if (storeChanged) subscribe();
+      draw();
+    },
+    destroy() {
+      alive = false;
+      unsubscribe();
+      unsubscribeApp();
+      doc.removeEventListener("keydown", onKey);
+      tree.destroy();
+    },
+  };
+}

package/vendor/sdk/lib/dom/connection.ts

@@ -0,0 +1,309 @@
+/**
+ * THE LIVE CONNECTION (the data plane), plain TypeScript: the workflow's MCP stream on the
+ * Unoverse server's `/stream` endpoint (Streamable-HTTP SSE). Inbound
+ * `notifications/unoverse/event` messages feed the one `ComponentStore` through the pure
+ * `applyServerMessage` mapper; outbound sends ride the same session as tool calls.
+ *
+ * Per UNOVERSE_MCP_APP_PROTOCOL.md §5/§5a/§5b: the component stream rides MCP (NOT the
+ * legacy `/ws/gravity` WS, which is reserved for live audio). The node executes in the same
+ * Unoverse process that serves this stream, so there's no gateway relay in the path.
+ */
+import { CfWorkerJsonSchemaValidator } from "@modelcontextprotocol/client/validators/cf-worker";
+import { Client, StreamableHTTPClientTransport } from "@modelcontextprotocol/client";
+import { emitAnalytics } from "../core/analytics";
+import { applyServerMessage, type ServerMessage } from "../core/connection";
+import type { ComponentStore } from "../core/store";
+
+// Interpreter-based JSON-schema validator (no `new Function`): the default Ajv provider
+// compiles with `new Function`, which ChatGPT's widget CSP (no unsafe-eval) blocks.
+
+export interface UnoverseConnectionConfig {
+  /** Gravity API base, e.g. "http://localhost:4100". */
+  apiUrl: string;
+  /** Unoverse server base; the `/stream` MCP data-plane endpoint (§5b) is appended. */
+  streamUrl: string;
+  /** Optional JWT provider: the token rides the MCP transport fetch. */
+  getAccessToken?: () => Promise<string | null>;
+}
+
+export interface UnoverseSessionParams {
+  workflowId: string;
+  targetTriggerNode: string;
+  userId: string;
+  conversationId: string;
+  /** Groups one request→response turn. Defaults to conversationId if omitted. */
+  chatId?: string;
+  /** The app this session shows (`<org>/<name>`). */
+  appId?: string;
+}
+
+/** What a host reads: whether the stream is up, ready, or refused. */
+export interface ConnectionStatus {
+  isConnected: boolean;
+  isReady: boolean;
+  /** The server's refusal text when register_session answered isError, null while
+   *  unrefused. TERMINAL for the attempt: hosts surface it instead of "connecting" forever. */
+  refusal: string | null;
+}
+
+export interface ConnectionOptions {
+  /** An app swap is the host's call: the conversation survives it. */
+  onAppSwitch?: (app: string) => void;
+  /** A voice in the workflow asks the page to join (VOICE_STREAMING_GUIDE.md). */
+  onJoinCall?: (workflowId?: string) => void;
+  /** The app this session names when it (re)registers; read at each registration. */
+  appId?: () => string | undefined;
+}
+
+export interface UnoverseConnection {
+  status(): ConnectionStatus;
+  /** Called on every status change; returns the unsubscribe. */
+  subscribe(listener: () => void): () => void;
+  /** Composer target: optimistic user turn + the workflow trigger. */
+  sendMessage(text: string): void;
+  /** Fire the bound workflow WITHOUT a user turn (the "load → run the workflow" ping). */
+  trigger(input?: Record<string, unknown>, turnId?: string): void;
+  /** Other component actions (button clicks, etc.) → MCP `user_action` tool. */
+  sendAction(action: string, data: Record<string, unknown>): void;
+  /** Answer a pending ELICITATION with the submitted state; false when none is pending. */
+  resolveElicitation(state: Record<string, unknown>, action?: "accept" | "cancel"): boolean;
+  close(): void;
+}
+
+/** The data-plane endpoint on the Unoverse server (§5b). */
+const STREAM_ENDPOINT = "/stream";
+/** Custom notification carrying one ServerMessage as `params` (§5b). */
+const UNOVERSE_EVENT = "notifications/unoverse/event";
+
+/**
+ * Guest identity, CONTAINED HERE so hosts never write guest logic. A token-less session is a
+ * GUEST to the public-entry gate, which only admits `guest-`-prefixed ids. Minted once per
+ * browser and persisted, so the visitor's conversation and memory cohere across reloads.
+ */
+const GUEST_KEY = "unoverse:guestId";
+export function resolveGuestId(): string {
+  let id: string | null = null;
+  try {
+    id = localStorage.getItem(GUEST_KEY);
+  } catch {
+    /* storage blocked → per-load guest below */
+  }
+  if (!id || !/^guest[-:]/.test(id)) {
+    id = `guest-${crypto.randomUUID()}`;
+    try {
+      localStorage.setItem(GUEST_KEY, id);
+    } catch {
+      /* fine: the id just won't survive a reload */
+    }
+  }
+  return id;
+}
+
+/**
+ * THE ONE IDENTITY RULE for every lane the SDK opens: with a token the host's userId passes
+ * through; without one a host-supplied guest id wins and anything else is replaced by the
+ * stored guest id. The data plane and the audio lane both call this.
+ */
+export function sessionUserId(userId: string | undefined, getAccessToken: unknown): string {
+  return getAccessToken || /^guest[-:]/.test(userId ?? "") ? (userId as string) : resolveGuestId();
+}
+
+/** Open the live connection; it reconnects on its own until `close()`. */
+export function openConnection(config: UnoverseConnectionConfig, session: UnoverseSessionParams, store: ComponentStore, options: ConnectionOptions = {}): UnoverseConnection {
+  const { streamUrl, getAccessToken } = config;
+  const { workflowId, targetTriggerNode, conversationId } = session;
+  const userId = sessionUserId(session.userId, getAccessToken);
+  const chatId = session.chatId ?? conversationId;
+
+  let status: ConnectionStatus = { isConnected: false, isReady: false, refusal: null };
+  const listeners = new Set<() => void>();
+  const setStatus = (next: Partial<ConnectionStatus>) => {
+    const merged = { ...status, ...next };
+    if (merged.isConnected === status.isConnected && merged.isReady === status.isReady && merged.refusal === status.refusal) return;
+    status = merged;
+    listeners.forEach((l) => l());
+  };
+
+  let current: Client | null = null;
+  // First-seen component keys, kept ACROSS reconnects: a re-bind may re-push components
+  // this session already placed, and a repeat INIT on a seen key merges props instead.
+  const seen = new Set<string>();
+  // The pending elicitation's resolver (one at a time per session).
+  let pendingElicit: ((state: Record<string, unknown>, action: "accept" | "cancel") => void) | null = null;
+  let cancelled = false;
+  let attempt = 0;
+  let retryTimer: ReturnType<typeof setTimeout> | null = null;
+
+  /**
+   * SESSION-DEATH RECOVERY (the MCP spec's own rule): a session id the server no longer
+   * knows answers 404, and the client MUST start a NEW session. Any client error recycles
+   * the whole client and re-runs the connect sequence with backoff; register_session is
+   * idempotent and a re-bind emits SESSION_READY. Blunt on purpose: a spurious reconnect
+   * costs little, a missed session death is a dead screen.
+   */
+  const recycle = (dead: Client, why: unknown) => {
+    // Only the CURRENT client may trigger recovery: a dying client's teardown fires strays.
+    if (cancelled || current !== dead) return;
+    current = null;
+    void dead.close().catch(() => {});
+    setStatus({ isConnected: false, isReady: false });
+    const delay = Math.min(15_000, 500 * 2 ** Math.min(attempt++, 5));
+    console.warn(`[unoverse] session lost — reconnecting in ${delay}ms (attempt ${attempt})`, why);
+    retryTimer = setTimeout(() => void connect(), delay);
+  };
+
+  const connect = async () => {
+    if (cancelled) return;
+    // The ELICITATION capability (form mode), the native collection path (§3.3): the
+    // interactive component already on screen IS the form; its `submit` answers it.
+    const client = new Client({ name: "unoverse-channel", version: "0.0.1" }, { capabilities: { elicitation: {} }, jsonSchemaValidator: new CfWorkerJsonSchemaValidator() });
+    client.setRequestHandler("elicitation/create", async (req) => {
+      // The accept content MUST match the requestedSchema (flat primitives only): project
+      // the submitted state to the REQUESTED keys.
+      const requested = (req.params as unknown as { requestedSchema?: { properties?: Record<string, unknown> } }).requestedSchema?.properties ?? {};
+      return await new Promise((resolve) => {
+        pendingElicit = (state, action) => {
+          pendingElicit = null;
+          if (action === "cancel") return resolve({ action: "cancel" } as never);
+          const content: Record<string, unknown> = {};
+          for (const k of Object.keys(requested)) if (state[k] !== undefined) content[k] = state[k];
+          resolve({ action: "accept", content } as never);
+        };
+      });
+    });
+    // A failure of the standalone GET SSE lands only here; so does a session dying mid-life.
+    client.onerror = (e) => {
+      // TEARDOWN NOISE when the close was ours: quiet, no recovery.
+      if (cancelled || current !== client) {
+        // eslint-disable-next-line no-console
+        console.debug("[unoverse] client closed:", (e as Error)?.message ?? e);
+        return;
+      }
+      console.error("[unoverse] client error:", e);
+      recycle(client, e);
+    };
+    current = client;
+
+    client.fallbackNotificationHandler = async (notification) => {
+      if (notification.method !== UNOVERSE_EVENT) return;
+      const msg = (notification.params ?? {}) as unknown as ServerMessage;
+      const evt = msg as unknown as { type?: string; event?: string; params?: Record<string, unknown>; app?: unknown; workflowId?: unknown };
+      if (evt.type === "SESSION_READY") return setStatus({ isReady: true });
+      // A manifest-declared analytics moment, resolved server-side: handed to the sink, never the store.
+      if (evt.type === "ANALYTICS_EVENT") {
+        if (typeof evt.event === "string" && evt.event) emitAnalytics(evt.event, evt.params ?? {});
+        return;
+      }
+      // AN APP SWAP IS THE HOST'S CALL: handed straight out, the store untouched.
+      if (evt.type === "APP_SWITCH") {
+        if (typeof evt.app === "string" && evt.app) options.onAppSwitch?.(evt.app);
+        return;
+      }
+      // A VOICE IN THE WORKFLOW ASKS THE PAGE TO JOIN.
+      if (evt.type === "JOIN_CALL") {
+        options.onJoinCall?.(typeof evt.workflowId === "string" ? evt.workflowId : undefined);
+        return;
+      }
+      applyServerMessage(store, msg, seen);
+    };
+
+    // The bearer on every request (fresh per call → refresh-safe), and the ngrok bypass
+    // header for dev tunnels (hostname-gated, so prod requests are untouched).
+    const authFetch = async (url: string | URL, init?: RequestInit): Promise<Response> => {
+      const token = getAccessToken ? await getAccessToken() : undefined;
+      const headers = new Headers(init?.headers);
+      if (token) headers.set("Authorization", `Bearer ${token}`);
+      if (String(url).includes("ngrok")) headers.set("ngrok-skip-browser-warning", "true");
+      return fetch(url, { ...init, headers });
+    };
+    try {
+      await client.connect(new StreamableHTTPClientTransport(new URL(`${streamUrl}${STREAM_ENDPOINT}`), { fetch: authFetch }));
+      if (cancelled || current !== client) {
+        await client.close().catch(() => {});
+        return;
+      }
+      // A fresh attempt owns a fresh verdict.
+      setStatus({ isConnected: true, refusal: null });
+      const appId = options.appId?.();
+      const bind = await client.callTool({
+        name: "register_session",
+        arguments: { userId, conversationId, workflowId, targetTriggerNode, chatId, ...(appId ? { appId } : {}) },
+      });
+      // A refusal is an isError RESULT: surface it and STOP, never retry (the server has answered).
+      if ((bind as { isError?: boolean }).isError) {
+        const c = (bind as { content?: Array<{ type?: string; text?: string }> }).content;
+        const reason = c?.[0]?.text ?? "unauthorized";
+        console.error("[unoverse] session refused:", reason);
+        setStatus({ refusal: reason });
+        return;
+      }
+      // A completed re-bind is health: the next death starts its backoff fresh.
+      attempt = 0;
+    } catch (e) {
+      if (cancelled) return;
+      console.error("[unoverse] stream connect failed", e);
+      recycle(client, e);
+    }
+  };
+
+  // TURN IDENTITY: `conversationId` names the conversation, `chatId` one turn. A fresh turn
+  // id per send; the `<conversationId>:t…` prefix keeps conversation-scoped waiters matching.
+  const mintTurn = () => `${chatId}:t${Date.now().toString(36)}${Math.floor(Math.random() * 1296).toString(36)}`;
+
+  const trigger = (input?: Record<string, unknown>, turnId?: string) => {
+    const turn = turnId ?? mintTurn();
+    void (async () => {
+      // NATIVE MCP: the run fires as a `tools/call` on the live /stream session (§0.3).
+      const client = current;
+      if (!client) {
+        console.error("[unoverse] trigger dropped — MCP stream not connected yet");
+        return;
+      }
+      const inputEnvelope = { chatId: turn, conversationId, userId, providerId: "gravity-ds", metadata: { targetTriggerNode }, ...input };
+      try {
+        await client.callTool({ name: "trigger", arguments: { workflowId, conversationId, input: inputEnvelope } });
+      } catch (e) {
+        console.error("[unoverse] trigger failed", e);
+      }
+    })();
+  };
+
+  if (!userId || !conversationId) console.warn("[unoverse] connection missing userId/conversationId");
+  else void connect();
+
+  return {
+    status: () => status,
+    subscribe(listener) {
+      listeners.add(listener);
+      return () => void listeners.delete(listener);
+    },
+    sendMessage(text) {
+      const message = text.trim();
+      if (!message) return;
+      const turn = mintTurn();
+      store.addUserMessage(turn, message); // optimistic user turn
+      // The assistant turn opens at once, so the thinking state shows on send; the later
+      // WORKFLOW_STARTED and first COMPONENT_INIT reuse this same turn.
+      store.startResponse(turn);
+      trigger({ message }, turn);
+    },
+    trigger,
+    sendAction(action, data) {
+      void current?.callTool({ name: "user_action", arguments: { action, data, userId, conversationId, chatId } }).catch((e) => console.error("[unoverse] user_action failed", e));
+    },
+    resolveElicitation(state, action = "accept") {
+      const pending = pendingElicit;
+      if (!pending) return false;
+      pending(state, action);
+      return true;
+    },
+    close() {
+      cancelled = true;
+      if (retryTimer !== null) clearTimeout(retryTimer);
+      setStatus({ isConnected: false, isReady: false, refusal: null });
+      void current?.close().catch(() => {});
+      current = null;
+      listeners.clear();
+    },
+  };
+}