@unoverse-platform/studio 0.1.102 → 0.1.104

package/vendor/base/src/manifests/runtime/tools/toolloop.ts

@@ -47,12 +47,6 @@ export interface ToolBridge {
   ): Promise<{ content: string; minted: any[]; skills?: Array<{ name: string; title?: string; instructions: string; regionId?: string; regionName?: string | null; ms?: number }> }>;
   /** Does this exchange end the turn? Depends on which tools were WIRED. */
   endsTurn(calls: { name: string; resultContent: string }[]): boolean;
-  /**
-   * WHAT SORT OF STEP a call to this tool is on the timeline. The bridge minted the tool,
-   * so the bridge knows whether it came from a task row; the loop only relays the answer
-   * to the trace. Optional, because a core-tools-only bridge has nothing but tools.
-   */
-  kindOf?(toolName: string): "tool" | "task";
 }
 
 /**
@@ -100,8 +94,27 @@ export function recordToolTrace(
    */
   kind: "tool" | "skill" | "task" = "tool",
 ): void {
-  const executionId = (ctx as any)?.scope?.executionId;
-  const parentNodeId = (ctx as any)?.scope?.nodeId;
+  recordCall({ executionId: (ctx as any)?.scope?.executionId, parentNodeId: (ctx as any)?.scope?.nodeId, toolName, args, result, startTime, success, kind, who: node.type });
+}
+
+/**
+ * ONE CALL ON THE TIMELINE, by whoever ran it (packages/docs/nodes/mcp-services.md, "Who
+ * records a call"): a tool records its own call, nested under the node that called it. The
+ * service channel (executor.ts) records a node's methods; the harness records only its own
+ * steps through `recordToolTrace`.
+ */
+export function recordCall(call: {
+  executionId?: string;
+  parentNodeId?: string;
+  toolName: string;
+  args: unknown;
+  result: unknown;
+  startTime: number;
+  success: boolean;
+  kind?: "tool" | "skill" | "task";
+  who: string;
+}): void {
+  const { executionId, parentNodeId, toolName, args, result, startTime, success, kind = "tool" } = call;
   if (!executionId || !parentNodeId) return;
 
   /**
@@ -134,7 +147,7 @@ export function recordToolTrace(
     duration: endTime - startTime,
     success,
     kind,
-  }).catch((err: any) => console.warn(`[manifests] ${node.type}: could not save MCP trace: ${err?.message ?? err}`));
+  }).catch((err: any) => console.warn(`[manifests] ${call.who}: could not save MCP trace: ${err?.message ?? err}`));
 }
 
 export async function runToolLoop(
@@ -339,29 +352,19 @@ export async function runToolLoop(
 
       let content: string;
       /**
-       * THE TIMELINE BAR, and it is the AGENT's job to record it, not the tool's.
-       *
-       * Every legacy agent did this — OpenAIAgent, Grok, Realtime — and the manifest loop
-       * that replaced them did not, so the nested `findIntent MCP (1 of 5 tools) 1.51s` row
-       * vanished the day `openai` migrated. It looked like a fault in whichever node was
-       * being called, which is where I went looking, twice.
-       *
-       * `success` is the part that matters most. A tool that fails still returns a string to
-       * the model (see the catch below), so from the outside a broken tool and an empty
-       * result are identical: the workflow completes, four green bars, and the model answers
-       * from its own knowledge. That happened three times in one session before anyone could
-       * see it. This flag is what turns it red.
+       * THE TIMELINE BAR is the TOOL's to record, never the loop's (owner, 2026-10-01;
+       * packages/docs/nodes/mcp-services.md, "Who records a call"). Every tool records its
+       * own call wherever it runs (a node's method, a row's function, a platform tool), with
+       * `success` false on a failure, so a call reads the same from an Agent, a voice session
+       * or an outside host. The bar once vanished the day `openai` migrated, because it lived
+       * in each Agent family; it lives with the tool now.
        */
-      const startedAt = Date.now();
-      let ok = true;
       try {
         content = await bridge.call(call.name, args);
       } catch (err: any) {
         // A failed tool is information for the model, not a crash: it can try another.
-        ok = false;
         content = JSON.stringify({ error: err?.message ?? String(err) });
       }
-      recordToolTrace(node, ctx, call.name, args, content, startedAt, ok, bridge.kindOf?.(call.name) ?? "tool");
       exchanges.push({ name: call.name, resultContent: content });
       // The RESULT, and only now that it exists. It is never in the HTTP stream: our loop
       // produced it, which is why it cannot be a `from: response` row. PARSED for the

package/vendor/base/src/platform/serviceCalls.ts

@@ -153,6 +153,19 @@ export async function saveMCPTraceToWorkflow(trace: any): Promise<string> {
   }
 }
 
+/**
+ * THE TOOLS A CALLER HOLDS NOW, so each call's row on the trace lists the choice the model
+ * really had: the run's starting tools plus every one a search has minted since. Fire and
+ * forget, like the trace itself.
+ */
+export function saveAvailableTools(executionId: string, nodeId: string, tools: string[]): void {
+  void fetch(`${WORKFLOW_SERVICE_URL}/analytics/available-tools`, {
+    method: "POST",
+    headers: { "Content-Type": "application/json" },
+    body: JSON.stringify({ executionId, nodeId, tools }),
+  }).catch(() => {});
+}
+
 /**
  * Persist plugin state to PostgreSQL via workflow-service
  */

package/vendor/sdk/appEngine.ts

@@ -0,0 +1,363 @@
+/**
+ * The native app ENGINE (§6d), plain DOM, surface-agnostic. It:
+ *   - reads its OWN workflow binding from its manifest (§4b: "App supplies workflow, trigger"),
+ *   - opens the SDK's native connection (`/stream` register_session → store),
+ *   - fires the workflow DIRECTLY over that connection with the USER's token (§5a: "direct
+ *     channel → Gravity backend, never brokered").
+ *
+ * The server tool only LOADS this app; it never fires or brokers a token.
+ */
+import { postToEmbedHost, handAnswerToHost } from "./mcpAppBridge";
+import { mountPageInterfaces, type Binding } from "./pageInterfaces";
+import { UnoverseClient } from "./lib/core/client";
+import { ComponentStore } from "./lib/core/store";
+import { computeAppWidth, resolveActiveLayout } from "./lib/core/apps";
+import { setAnalyticsSink, setAnalyticsContext, setAnalyticsDebug } from "./lib/core/analytics";
+import type { ResolvedTheme, UnoverseDefinition } from "./lib/core/types";
+import type { ActionHandler, ActionMeta } from "./lib/actions";
+import { mountApp, type AppMount } from "./lib/dom/app";
+import { openConnection, type UnoverseConnection } from "./lib/dom/connection";
+import { fetchTheme } from "./lib/dom/theme";
+import { createVoiceService, type VoiceService } from "./lib/voiceService";
+
+export interface AppConfig {
+  serverUrl: string;
+  apiUrl?: string;
+  appId: string;
+  getAccessToken?: () => Promise<string | null> | string | null;
+  userId?: string;
+  conversationId: string;
+  /** Where this app runs, reported on every analytics event (UNOVERSE_ANALYTICS.md §surfaces). */
+  surface?: string;
+  /** Log each analytics event as it fires (server-delivered, never a client flag). */
+  analyticsDebug?: boolean;
+}
+
+export interface AppEngine {
+  update(cfg: AppConfig): void;
+  destroy(): void;
+}
+
+type Manifest = { workflow?: string; trigger?: string; service?: string };
+
+/** Mount the named app into `el`. */
+export function mountAppEngine(el: HTMLElement, first: AppConfig): AppEngine {
+  const doc = el.ownerDocument;
+  let cfg = first;
+  // ONE CLIENT PER SERVER, ONE STORE PER CONVERSATION: a conversation swap must not carry the
+  // old timeline into another's shell (seen live 2026-08-08).
+  let client = new UnoverseClient(`${cfg.serverUrl}/mcp`, { getAccessToken: cfg.getAccessToken as never });
+  let storeKey = `${cfg.userId}|${cfg.conversationId}`;
+  let store = new ComponentStore();
+  // WHICH APP IS RUNNING: the host's config names it, and the SERVER may swap it mid
+  // conversation (an app discovered and called IS the surface). A swap resets the binding at
+  // once, so no session opens on the old app's trigger against the new app.
+  let appId = cfg.appId;
+  let binding: Manifest = {};
+  let def: UnoverseDefinition | null = null;
+  let theme: ResolvedTheme | null = null;
+  let inTask = false;
+  let alive = true;
+  let loadToken = 0;
+  let conn: UnoverseConnection | null = null;
+  let connKey = "";
+  let voice: VoiceService = inertVoice();
+  let voiceKey = "";
+  let app: AppMount | null = null;
+  let page: { destroy(): void } | null = null;
+  let lastWidth: string | undefined;
+  let stopStore = () => {};
+  let stopVoice = () => {};
+  let stopConn = () => {};
+
+  function inertVoice(): VoiceService {
+    // No `store`: not a producer, so it writes no callState into ordinary templates.
+    return createVoiceService({ apiUrl: "", session: { userId: "", conversationId: "", workflowId: "", targetTriggerNode: "" } });
+  }
+
+  // ANALYTICS (UNOVERSE_ANALYTICS.md): events cross to the HOST REALM, where the page's own tag
+  // lives with the visitor's consent; with no parent the post is a silent no-op.
+  const analytics = () => {
+    setAnalyticsDebug(!!cfg.analyticsDebug);
+    setAnalyticsContext({ surface: cfg.surface, conversation_id: cfg.conversationId, user_id: cfg.userId });
+    setAnalyticsSink((event) => postToEmbedHost({ type: "unoverse:event", ...event }));
+  };
+
+  // The app's width, reported UP to the embedding host whenever a panel opens or closes; a new
+  // app always re-announces (the host resets its frame on a switch).
+  const reportWidth = () => {
+    const w = computeAppWidth(resolveActiveLayout(def, store), store, theme?.appSize, def);
+    if (w && w !== lastWidth) {
+      lastWidth = w;
+      postToEmbedHost({ type: "unoverse:size", width: w });
+    }
+  };
+
+  // STATUS TO THE HOST: ready, connected, the server's refusal, and the last run's failure.
+  let lastStatus = "";
+  const reportStatus = () => {
+    const s = conn?.status() ?? { isConnected: false, isReady: false, refusal: null };
+    const msg = { type: "unoverse:status", ready: !!s.isReady, connected: !!s.isConnected, refused: s.refusal ?? undefined, failure: store.getLastFailure() ?? undefined };
+    const key = JSON.stringify(msg);
+    if (key === lastStatus) return;
+    lastStatus = key;
+    postToEmbedHost(msg);
+  };
+
+  /** The voice service for this app: real for a `service: "voice"` app, else inert. A call
+   *  names the workflow it runs; the app lends its binding as the default. */
+  const syncVoice = () => {
+    const wanted = binding.service === "voice";
+    const key = wanted ? JSON.stringify([cfg.apiUrl ?? cfg.serverUrl, cfg.userId, cfg.conversationId, binding.workflow, binding.trigger, storeKey]) : "inert";
+    if (key === voiceKey) return;
+    voiceKey = key;
+    stopVoice();
+    voice.destroy();
+    voice = wanted
+      ? createVoiceService({
+          apiUrl: cfg.apiUrl ?? cfg.serverUrl,
+          // The audio lane is derived from the client's own server origin, never the host's.
+          wsUrl: client.serverOrigin.replace(/^http/, "ws"),
+          getAccessToken: cfg.getAccessToken,
+          session: { userId: cfg.userId ?? "", conversationId: cfg.conversationId, chatId: cfg.conversationId, workflowId: binding.workflow ?? "", targetTriggerNode: binding.trigger ?? "" },
+          // Producer: writes callState/isMuted into TEMPLATE STATE so the voice states switch.
+          store,
+        })
+      : inertVoice();
+    stopVoice = voice.subscribe(syncConnection);
+    app?.update({ voice });
+    mountPage();
+  };
+
+  /**
+   * THE CONNECTION, open once the user is known AND there is something to hear from: the app's
+   * own workflow, a call, or a task the page is in. Nothing is held open while a visitor reads.
+   */
+  const syncConnection = () => {
+    const enabled = !!cfg.userId && (!!binding.workflow || voice.state.isCallActive || inTask);
+    const key = enabled ? JSON.stringify([cfg.serverUrl, binding.workflow, binding.trigger, cfg.userId, cfg.conversationId, storeKey, !!cfg.getAccessToken]) : "";
+    if (key === connKey) return;
+    connKey = key;
+    stopConn();
+    conn?.close();
+    conn = null;
+    if (enabled) {
+      conn = openConnection(
+        { apiUrl: cfg.apiUrl ?? cfg.serverUrl, streamUrl: cfg.serverUrl, getAccessToken: cfg.getAccessToken as never },
+        { workflowId: binding.workflow ?? "", targetTriggerNode: binding.trigger ?? "", userId: cfg.userId ?? "", conversationId: cfg.conversationId, chatId: cfg.conversationId, appId },
+        store,
+        {
+          appId: () => appId,
+          onAppSwitch: switchApp,
+          // A voice in the running workflow asks the page in: join its call, never start one.
+          onJoinCall: (workflowId) => void voice.joinCall(workflowId),
+        },
+      );
+      stopConn = conn.subscribe(reportStatus);
+    }
+    reportStatus();
+  };
+
+  const switchApp = (next: string) => {
+    if (next === appId) return;
+    appId = next;
+    load();
+  };
+
+  /** Read the app's manifest (its binding, its service) and its definition (its width). */
+  const load = () => {
+    const token = ++loadToken;
+    binding = {};
+    def = null;
+    lastWidth = undefined;
+    syncConnection();
+    syncVoice();
+    const orgFromId = appId.includes("/") ? appId.split("/")[0] : null;
+    if (orgFromId) loadTheme(`${orgFromId}/light`, token);
+    client
+      .connect()
+      .then(() => (client as unknown as { client: { readResource(a: { uri: string }): Promise<{ contents?: { text?: string }[] }> } }).client.readResource({ uri: `unoverse://apps/${appId.toLowerCase()}` }))
+      .then((res) => {
+        if (!alive || token !== loadToken) return;
+        const parsed = res?.contents?.[0]?.text ? JSON.parse(res.contents[0].text) : null;
+        const m = parsed?.manifest ?? parsed ?? {};
+        const b = m.binding ?? {};
+        binding = { workflow: b.workflow, trigger: b.trigger, service: m.service };
+        syncVoice();
+        syncConnection();
+      })
+      .catch((e) => console.error("[app] manifest read failed:", e));
+    client
+      .connect()
+      .then(() => client.readDefinition(`unoverse://apps/${appId}/definition`))
+      .then((d) => {
+        if (!alive || token !== loadToken) return;
+        def = d ?? null;
+        if (!orgFromId) loadTheme(def?.org ? `${def.org}/light` : "light", token);
+        reportWidth();
+      })
+      .catch((e) => console.error("[app] template read failed:", e));
+    mountAppView();
+  };
+  const loadTheme = (name: string, token: number) =>
+    fetchTheme(client, name)
+      .then((t) => {
+        if (!alive || token !== loadToken) return;
+        theme = t;
+        reportWidth();
+      })
+      .catch(() => {});
+
+  // THE SPEC'S ANSWERS, AND NOTHING ELSE: while the server is ELICITING, a `submit` answers
+  // `accept` with its slice and a `cancel` answers `cancel`. Otherwise a submit inside an outside
+  // host goes to the host's model; everything else is the data-plane `user_action`.
+  const toServer = (t: string, data: Record<string, unknown>, meta?: ActionMeta) => {
+    const state = (meta?.state ?? data) as Record<string, unknown>;
+    if ((t === "submit" || t === "cancel") && conn?.resolveElicitation(state, t === "cancel" ? "cancel" : "accept")) return;
+    if (t === "submit" && handAnswerToHost(state)) return;
+    conn?.sendAction(t, {
+      componentNodeId: meta?.nodeId,
+      componentType: meta?.type,
+      // The component's OWN chatId is the TURN id the waiting node execution is keyed on.
+      componentChatId: meta?.chatId,
+      componentState: state,
+    });
+  };
+
+  // A PAGE TEMPLATE'S TASK, called at its own workflow's trigger with the user's token.
+  // `metadata.task` names the task its Task Runner loads; the submit carries the answers.
+  const startTask = async (b: Binding, task: string, submit?: Record<string, unknown>) => {
+    if (!b.workflow) return;
+    inTask = true;
+    syncConnection();
+    const token = cfg.getAccessToken ? await cfg.getAccessToken() : null;
+    fetch(`${cfg.apiUrl ?? cfg.serverUrl}/api/workflows/${b.workflow}/execute`, {
+      method: "POST",
+      headers: { "Content-Type": "application/json", ...(token ? { Authorization: `Bearer ${token}` } : {}) },
+      body: JSON.stringify({
+        input: {
+          message: submit ? "Submit" : "Start",
+          chatId: cfg.conversationId,
+          conversationId: cfg.conversationId,
+          userId: cfg.userId,
+          providerId: "gravity-ds",
+          metadata: { targetTriggerNode: b.trigger, workflowId: b.workflow, task, ...(submit ? { submit } : {}) },
+        },
+        conversationId: cfg.conversationId,
+      }),
+    }).catch((e) => console.error("[unoverse] task start failed", e));
+  };
+
+  const onAction: ActionHandler = (action, data, meta) => {
+    const t = typeof action === "string" ? action : (action as { type?: string })?.type;
+    const d = (data ?? {}) as Record<string, unknown>;
+    if (t === "close") {
+      // The app owns its close chrome; the embedding host decides what "close" means.
+      postToEmbedHost({ type: "unoverse:close" });
+      return;
+    }
+    if (t === "sendMessage") {
+      // A suggestion that NAMES AN APP launches it: read that app's manifest (the binding lives
+      // there) and fire its trigger on the bound workflow.
+      const launch = typeof d.app === "string" ? d.app : "";
+      if (launch) {
+        (client as unknown as { client: { readResource(a: { uri: string }): Promise<{ contents?: { text?: string }[] }> } }).client
+          .readResource({ uri: `unoverse://apps/${launch.toLowerCase()}` })
+          .then((res) => {
+            const parsed = res?.contents?.[0]?.text ? JSON.parse(res.contents[0].text) : null;
+            const b = parsed?.manifest?.binding ?? parsed?.binding ?? {};
+            if (!b.trigger) return console.error("[app] launch failed: no binding on", launch);
+            if (b.workflow && binding.workflow && b.workflow !== binding.workflow)
+              console.warn("[app] launch:", launch, "binds a different workflow — firing its trigger on the bound workflow");
+            // LOADING STATE: the app's declared defaultState pre-opens its surface.
+            const declared = parsed?.manifest?.defaultState ?? parsed?.manifest?.mode ?? parsed?.defaultState ?? parsed?.mode;
+            if (declared && declared !== "app") store.mergeAppState({ defaultState: declared });
+            conn?.trigger({ app: launch, metadata: { targetTriggerNode: b.trigger, ...(def?.org ? { org: def.org } : {}) } });
+          })
+          .catch((e) => console.error("[app] launch failed:", e));
+        return;
+      }
+      // Composer submit: Enter carries `text`; a send BUTTON carries none, so the shared draft.
+      const text = (typeof d.text === "string" && d.text) || store.getDraft();
+      if (text.trim()) {
+        conn?.sendMessage(text);
+        store.setDraft("");
+      }
+      return;
+    }
+    // Controlled composer: every keystroke is the shared draft (local, never a round trip).
+    if (t === "input") {
+      store.setDraft(typeof d.text === "string" ? d.text : "");
+      return;
+    }
+    if (t) toServer(t, d, meta);
+  };
+
+  const mountAppView = () => {
+    const uri = `unoverse://apps/${appId}/definition`;
+    if (app) return app.update({ uri, voice });
+    app = mountApp({ client, store, uri, voice, onAction, doc });
+    el.append(...app.nodes);
+  };
+  // The page's own templates, drawn into its elements by this one runtime.
+  const mountPage = () => {
+    page?.destroy();
+    page = mountPageInterfaces({ org: appId.split("/")[0], client, voice, appStore: store, toServer, startTask });
+  };
+
+  const watchStore = () => {
+    stopStore();
+    stopStore = store.subscribe(() => {
+      reportWidth();
+      reportStatus();
+    });
+  };
+
+  analytics();
+  watchStore();
+  load();
+
+  return {
+    update(next) {
+      const prev = cfg;
+      cfg = next;
+      analytics();
+      let reset = false;
+      if (next.serverUrl !== prev.serverUrl) {
+        client = new UnoverseClient(`${next.serverUrl}/mcp`, { getAccessToken: next.getAccessToken as never });
+        reset = true;
+      }
+      const key = `${next.userId}|${next.conversationId}`;
+      if (key !== storeKey) {
+        storeKey = key;
+        store = new ComponentStore();
+        watchStore();
+        reset = true;
+      }
+      if (reset) {
+        app?.destroy();
+        app?.nodes.forEach((n) => n.parentNode?.removeChild(n));
+        app = null;
+      }
+      // The host's own switch WINS and resets: a new config is a new intent.
+      if (reset || next.appId !== prev.appId) {
+        appId = next.appId;
+        load();
+      } else {
+        syncVoice();
+        syncConnection();
+      }
+    },
+    destroy() {
+      alive = false;
+      stopStore();
+      stopVoice();
+      stopConn();
+      conn?.close();
+      voice.destroy();
+      page?.destroy();
+      app?.destroy();
+      setAnalyticsSink(null);
+    },
+  };
+}

package/vendor/sdk/lib/actions.ts

@@ -0,0 +1,36 @@
+/**
+ * What a definition's interaction fires, and the handler it reaches. Plain TypeScript: both
+ * renderers (the legacy one in render.tsx and the plain-DOM one in ./dom) use it.
+ */
+import type { ActionSpec, UnoverseNode } from "./core/types";
+
+// An action is a bare string (→ workflow) or a declarative envelope (§2e-3). The
+// binding layer (streamed.tsx) interprets it; primitives just forward node.action.
+/** Instance context riding with a bubbled server action — WHICH component fired and its
+ *  current slice, so the channel can forward the submitted state (e.g. a wizard's answers)
+ *  without reaching into the store. Pure transport metadata; the SDK interprets none of it. */
+export interface ActionMeta {
+  chatId?: string;
+  nodeId?: string;
+  /** Which component this instance is — so the server needs no registry to find out. */
+  type?: string;
+  state?: Record<string, unknown>;
+}
+
+export type ActionHandler = (action: string | ActionSpec, data: Record<string, unknown>, meta?: ActionMeta) => void;
+
+/**
+ * A leaf's action, with the node's declared `analytics` attached (UNOVERSE_ANALYTICS.md).
+ *
+ * Authors write `analytics:` beside `action:` on the node, where the data it reports is
+ * already in scope. The two travel together from here so `dispatchAction` remains the ONE
+ * place an interaction is understood: leaves stay dumb, and no leaf can forget to report.
+ * A node with no `analytics` block passes its action through untouched, unallocated.
+ */
+export function nodeAction(node: UnoverseNode, fallback: string): string | ActionSpec {
+  const action = node.action ?? fallback;
+  if (!node.analytics?.event) return action;
+  return typeof action === "string"
+    ? { type: action, analytics: node.analytics }
+    : { ...action, analytics: node.analytics };
+}

package/vendor/sdk/lib/citations.ts

@@ -0,0 +1,48 @@
+/**
+ * Citations in answers (docs/unoverse/data/objects/citations-in-answers.md): the text rules
+ * and the pop-up placement. Plain TypeScript, shared by both renderers.
+ */
+
+/**
+ * A CITATION STILL ARRIVING is held back (citations-in-answers.md): while an answer streams, the
+ * tail from an open `[1](cite:` to its closing `)` would draw as a long line of raw link and then
+ * collapse into its marker, jolting the text once per citation. Only the tail is touched, and only
+ * a numbered label (a citation's), so finished text and web links draw exactly as written.
+ */
+const OPEN_CITATION = /\[\d{0,3}(?:\](?:\((?:c(?:i(?:t(?:e(?::[^)\n]*)?)?)?)?)?)?)?$/;
+export function holdOpenCitation(text: string): string {
+  return text.replace(OPEN_CITATION, "");
+}
+
+/**
+ * A CITATION'S QUOTE STAYS ONE CELL (citations-in-answers.md, 2026-09-15): a quote of a table row
+ * carried its pipes ("Total | 10") into the link's title, and inside an answer's own table the
+ * pipe split the row and left the marker raw. Before the markdown is parsed, a pipe inside a
+ * `cite:` link's title becomes a broken bar and a line break a space; the words still read.
+ */
+const CITATION_TITLE = /(\]\(cite:[^)\s]*\s+")([^"]*)("\))/g;
+export function keepCitationsWhole(text: string): string {
+  return text.replace(CITATION_TITLE, (_, open: string, quote: string, close: string) => `${open}${quote.replace(/\|/g, "\u00a6").replace(/\s*\n\s*/g, " ")}${close}`);
+}
+
+/**
+ * WHERE A POP-UP FITS (citations-in-answers.md): the horizontal shift that keeps a box of this
+ * width inside the window from an anchor at `left`, and whether it opens above the anchor
+ * because below there is no room and above there is. A margin keeps it off the very edge.
+ */
+export function fitPopover(anchor: { left: number; top: number; bottom: number }, box: { width: number; height: number }, view: { width: number; height: number }, margin = 8) {
+  const over = anchor.left + box.width - (view.width - margin);
+  const shift = Math.max(over > 0 ? -over : 0, margin - anchor.left);
+  const above = anchor.bottom + box.height + margin > view.height && anchor.top - box.height - margin >= 0;
+  return { shift, above };
+}
+
+/** A `cite:` link's parts: `cite:<document>?part=&page=&doc=`, its title the quoted words. */
+export function citationOf(href: string, title?: string) {
+  try {
+    const u = new URL(href);
+    return { document: decodeURIComponent(u.pathname), part: u.searchParams.get("part") ?? "", page: u.searchParams.get("page") ?? "", doc: u.searchParams.get("doc") ?? "", quote: title ?? "" };
+  } catch {
+    return null;
+  }
+}

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

@@ -308,6 +308,24 @@ export function resolveActiveView(
 
 
 /** Resolve a ComponentSlot's `select` against the store → ordered pointers. */
+/**
+ * THE INSTANCE A HELD SLOT DRAWS (docs/design/templates.md "Holding a component"). A template
+ * holds a component inside an `Each`: each item is its own instance, keyed by the item's id
+ * under the template's own node id, the same id the server sent it under
+ * (server runtime/screen/held.ts `heldNodeId`). Nothing when it has not arrived, or when its own
+ * state has lifted it into a place: it is drawn there, not here.
+ */
+export function heldPointer(store: ComponentStore, node: UnoverseNode, item: Record<string, unknown>, host: { chatId: string; nodeId: string }): string | undefined {
+  const type = (node as { hold?: { type?: unknown } }).hold?.type;
+  if (typeof type !== "string") return undefined;
+  const id = item.universal_id ?? item.ref ?? item.id ?? item.index;
+  if (typeof id !== "string" && typeof id !== "number") return undefined;
+  const nodeId = `${host.nodeId}:${type}:${String(id)}`;
+  if (!store.getType(host.chatId, nodeId)) return undefined;
+  const pointer = `${host.chatId}:${nodeId}`;
+  return store.isPlaced(pointer) ? undefined : pointer;
+}
+
 export function selectPointers(store: ComponentStore, node: UnoverseNode, scope?: Set<string>): string[] {
   const sel = (node.select ?? {}) as { from?: string; type?: string; where?: { field?: string; eq?: unknown; ne?: unknown }; limit?: number };
   // A SCOPED selection (the mount's hold: latest) spans ALL turns and the SCOPE is

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

@@ -5,11 +5,11 @@
  * (resources/read), with a per-request bearer for secured servers. Caches both.
  * No UI framework here.
  */
-import { Client } from "@modelcontextprotocol/sdk/client/index.js";
-import { StreamableHTTPClientTransport } from "@modelcontextprotocol/sdk/client/streamableHttp.js";
+import { CfWorkerJsonSchemaValidator } from "@modelcontextprotocol/client/validators/cf-worker";
+import { Client, StreamableHTTPClientTransport } from "@modelcontextprotocol/client";
+
 // CSP-safe (no `new Function`) validator — the default Ajv provider's eval is blocked by
 // ChatGPT's widget CSP. See connection.tsx for the full rationale.
-import { CfWorkerJsonSchemaValidator } from "@modelcontextprotocol/sdk/validation/cfworker";
 import type { UnoverseDefinition, ResolvedTheme } from "./types";
 import { stateOfUri } from "./apps";
 

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

@@ -395,6 +395,12 @@ export class ComponentStore {
   placedState(pointer: Pointer): string | undefined {
     return this.placed.get(pointer);
   }
+  /** Whether the screen has put this interface in any place. A held interface its own state
+   *  lifted into a place is drawn there, never in its template too (one instance, one place). */
+  isPlaced(pointer: Pointer): boolean {
+    for (const items of this.places.values()) if (items.includes(pointer)) return true;
+    return false;
+  }
   /** What one place holds, in the order the screen document gives. */
   placeItems(place: string): readonly Pointer[] {
     return this.places.get(place) ?? EMPTY_POINTERS;