@unoverse-platform/studio 0.1.80 → 0.1.82

package/vendor/sdk/lib/app.tsx

@@ -12,7 +12,7 @@
  * This slice handles ComponentSlot + Skeleton (Tier-1, e.g. KeyService). The
  * chat primitives (Conversation/Input/…) come in later slices.
  */
-import { useCallback, useEffect, useMemo, useState, useSyncExternalStore, type CSSProperties, type ReactNode } from "react";
+import { useCallback, useEffect, useLayoutEffect, useMemo, useRef, useState, useSyncExternalStore, type CSSProperties, type ReactNode } from "react";
 import {
   collectSurfacedViews,
   cssWidth,
@@ -39,6 +39,66 @@ import { renderNode, styleToCss, keyframesCss, type ActionHandler, type SlotReso
 // existing consumers keep their import path.
 export { collectSurfacedViews, computeAppWidth, orderedClaims, resolveActiveLayout, resolveActiveView, selectPointers, viewOf } from "./core";
 import { UnoverseComponent } from "./UnoverseComponent";
+
+/**
+ * FLIP wrapper for a multi-occupant slot: when arrivals reorder the list (a refreshed
+ * card floating to the front, a new card pushing the rest along), the existing cards
+ * SLIDE to their new position instead of jumping. Generic list behavior, no styling
+ * owned: each child sits in an unstyled measuring div; on every commit the previous
+ * rect is compared by key and the delta is played back as a transform that eases to
+ * identity. A key seen for the first time animates nothing (arrivals appear in place).
+ */
+function FlipList({ items }: { items: { key: string; node: ReactNode }[] }) {
+  const positions = useRef(new Map<string, { left: number; top: number }>());
+  const order = useRef("");
+  const els = useRef(new Map<string, HTMLDivElement>());
+  useLayoutEffect(() => {
+    // ANIMATE ONLY A REORDER. The template re-renders for plenty of reasons that are not
+    // this list (typing writes the draft into template state every keystroke), and chrome
+    // above the list growing or the page scrolling shifts every measured position a
+    // little — playing those back made the cards wobble while the guest typed. Order is
+    // the thing this animates, so unchanged order = remeasure silently and do nothing.
+    // Positions are layout-relative (offsetLeft/Top), not viewport-relative, for the
+    // same reason: scroll must not read as movement.
+    const nextOrder = items.map((i) => i.key).join(" ");
+    // The guest's OS-level reduce-motion setting wins outright: reorders land instantly.
+    const reduced = typeof matchMedia === "function" && matchMedia("(prefers-reduced-motion: reduce)").matches;
+    const moved = !reduced && order.current !== "" && order.current !== nextOrder;
+    const next = new Map<string, { left: number; top: number }>();
+    for (const [k, el] of els.current) {
+      const pos = { left: el.offsetLeft, top: el.offsetTop };
+      next.set(k, pos);
+      const prev = positions.current.get(k);
+      const dx = prev && moved ? prev.left - pos.left : 0;
+      const dy = prev && moved ? prev.top - pos.top : 0;
+      if (dx || dy) {
+        el.style.transition = "none";
+        el.style.transform = `translate(${dx}px, ${dy}px)`;
+        requestAnimationFrame(() => {
+          el.style.transition = "transform 240ms ease";
+          el.style.transform = "";
+        });
+      }
+    }
+    positions.current = next;
+    order.current = nextOrder;
+  });
+  return (
+    <>
+      {items.map(({ key, node }) => (
+        <div
+          key={key}
+          ref={(el) => {
+            if (el) els.current.set(key, el);
+            else els.current.delete(key);
+          }}
+        >
+          {node}
+        </div>
+      ))}
+    </>
+  );
+}
 import { useUnoverseTheme, ensureFontStylesheets } from "./theme";
 import { IsolatedRoot } from "./isolate";
 import { useVoiceService, type UseVoiceServiceConfig } from "./voice";
@@ -59,7 +119,7 @@ export interface StreamedUnoverseAppProps {
    *  hook drawn ABOVE a Container's content — Studio uses it for per-container state
    *  tabs. The SDK stays styleless: it hands the facts (name, the container's states,
    *  the held interface's active state, a setter) and draws whatever comes back. */
-  containerChrome?: (info: { name: string; states: string[]; active?: string; set: (state: string) => void }) => ReactNode;
+  templateChrome?: (info: { name: string; states: string[]; active?: string; set: (state: string) => void }) => ReactNode;
   /** The `voice` NATIVE SERVICE config (UNOVERSE_SPEC §2e-1). Present ONLY for a
    *  `service: "voice"` app — the host supplies the connection identity (apiUrl/wsUrl/
    *  token/session) it already holds; the renderer OWNS the service so every host is
@@ -77,9 +137,28 @@ const INERT_VOICE: UseVoiceServiceConfig = {
   session: { userId: "", conversationId: "", workflowId: "", targetTriggerNode: "" },
 };
 
-export function StreamedUnoverseApp({ client, store, uri, onAction, theme: themeProp, props, isolate = true, voice: voiceConfig, containerChrome }: StreamedUnoverseAppProps) {
+/** Every pointer a mounted template layout's slots currently select — its occupancy. */
+function collectSlotPointers(node: unknown, store: ComponentStore, scope?: Set<string>): string[] {
+  const out: string[] = [];
+  const walk = (n: unknown): void => {
+    if (!n || typeof n !== "object") return;
+    const un = n as UnoverseNode & { children?: unknown[]; template?: unknown; frame?: unknown; cases?: Record<string, unknown> };
+    if (un.type === "ComponentSlot") out.push(...selectPointers(store, un, scope));
+    (un.children ?? []).forEach(walk);
+    if (un.template) walk(un.template);
+    if (un.frame) walk(un.frame);
+    if (un.cases) Object.values(un.cases).forEach(walk);
+  };
+  walk(node);
+  return [...new Set(out)];
+}
+
+export function StreamedUnoverseApp({ client, store, uri, onAction, theme: themeProp, props, isolate = true, voice: voiceConfig, templateChrome }: StreamedUnoverseAppProps) {
   const [def, setDef] = useState<UnoverseDefinition | null>(null);
   const [error, setError] = useState<string | null>(null);
+  // MOUNTED TEMPLATES: an app entry with `use:` names a template definition; it is
+  // fetched once per app def and its own machinery runs inside the Template place.
+  const [mounted, setMounted] = useState<Record<string, UnoverseDefinition>>({});
   // The voice native service lives HERE (shared), not in each host. Called every render
   // (rules of hooks); inert until a `startCall` only a voice template has a button for.
   // The audio WS lane travels WITH the SDK: derive it from the client's own server origin
@@ -111,9 +190,27 @@ export function StreamedUnoverseApp({ client, store, uri, onAction, theme: theme
     let alive = true;
     setDef(null);
     setError(null);
+    setMounted({});
     client
       .readDefinition(uri)
-      .then((d) => alive && setDef(d))
+      .then((d) => {
+        if (!alive) return;
+        setDef(d);
+        const entries = ((d as { templates?: Record<string, { template?: string }> }).templates ?? {});
+        for (const entry of Object.values(entries)) {
+          const use = entry?.template;
+          if (!use) continue;
+          // A failed fetch may be a transient (dev-server restart mid-selection):
+          // retry once, and never fail SILENTLY — an empty mount with no console
+          // trace cost a debugging session (2026-08-28).
+          const turi = use.includes("://") ? use : `unoverse://templates/${use}`;
+          client
+            .readDefinition(turi)
+            .catch(() => new Promise((r) => setTimeout(r, 1500)).then(() => client.readDefinition(turi)))
+            .then((t) => alive && t && setMounted((m) => ({ ...m, [use]: t })))
+            .catch((e) => console.warn(`[unoverse] mounted template "${use}" failed to load:`, e));
+        }
+      })
       .catch((e) => alive && setError(String(e?.message ?? e)));
     return () => {
       alive = false;
@@ -159,8 +256,13 @@ export function StreamedUnoverseApp({ client, store, uri, onAction, theme: theme
   const surfacedViews = useMemo(() => {
     const views = new Set<string>(orderedClaims(def));
     if (activeRoot) collectSurfacedViews(activeRoot, views, def?.defs as Record<string, unknown> | undefined);
+    // A MOUNTED template claims every state it declares (base included): instances
+    // it holds must not also render in the flow — one instance, one placeholder.
+    for (const tpl of Object.values(mounted)) {
+      for (const name of Object.keys(tpl.layouts ?? {})) views.add(name);
+    }
     return views;
-  }, [activeRoot, def]);
+  }, [activeRoot, def, mounted]);
 
   // RULE 4: the winner clears the states below it — WHEN A DELIVERY PUT IT THERE.
   // An arrival taking a higher rung means the screen has moved on, so stale claims below
@@ -274,7 +376,11 @@ export function StreamedUnoverseApp({ client, store, uri, onAction, theme: theme
 
   const leaf = (pointer: string, extraData?: Record<string, unknown>, fill?: boolean) => {
     const { chatId, nodeId } = store.split(pointer);
-    return <UnoverseComponent key={pointer} client={client} store={store} chatId={chatId} nodeId={nodeId} onAction={dispatch} theme={theme} extraData={extraData} fill={fill} />;
+    // Keyed by the INSTANCE (nodeId), not the pointer: the same instance re-delivered in
+    // a later turn keeps its React identity, so a refresh reconciles in place instead of
+    // remounting (the remount was the visible flicker). Unique among siblings — a turn's
+    // nodeIds are unique, and selectPointers dedupes cross-turn copies to one.
+    return <UnoverseComponent key={nodeId} client={client} store={store} chatId={chatId} nodeId={nodeId} onAction={dispatch} theme={theme} extraData={extraData} fill={fill} />;
   };
 
   // THE ACTIVE STATE (docs/design/04): a template is in exactly ONE state at a time —
@@ -292,27 +398,69 @@ export function StreamedUnoverseApp({ client, store, uri, onAction, theme: theme
   const surfacedView = resolveActiveView(def, store, surfacedViews).view;
 
   // ComponentSlot — filter the timeline to matching component pointers (KeyService).
-  const resolveSlot = (node: UnoverseNode, key?: React.Key): ReactNode => {
-    // A CONTAINER (UNOVERSE_INTERFACE_MODEL §3): the layout places it by NAME and owns
-    // its width; the manifest's `containers:` block owns its claim. Resolved here into
-    // the slot it is — one authoring word (`state`), translated to the wire key.
-    if (node.type === "Container") {
-      // A CONTAINER (UNOVERSE_INTERFACE_MODEL §3): its states each HOLD AN INTERFACE —
-      // the page state holds the deal, the chat state holds text-chat — and the tabs
-      // switch between them. The container's ACTIVE state is app chrome (`setAppValue`
-      // territory, the one thing an app owns), keyed `container:<name>`; the shorthand
-      // `interface:` is a one-state container and never draws tabs.
+  // A FACTORY: a mounted template's slots select within a SCOPE (the current
+  // delivery — hold: latest, basic form); the app's own slots stay unscoped.
+  const makeResolveSlot = (scope?: Set<string>): SlotResolver => {
+  const resolveSlot: SlotResolver = (node: UnoverseNode, key?: React.Key): ReactNode => {
+    // A TEMPLATE PLACE (the container noun folded into templates, 2026-08-28): the
+    // layout places it by NAME and owns its width; the manifest's `templates:` block
+    // owns what it holds. An entry with `use:` MOUNTS a template definition (its own
+    // states, shapes and slots run here over the shared store); an entry with
+    // states/interface keeps the old holder behavior (a template with one shape).
+    if (node.type === "Template") {
       const cname = (node as { name?: string }).name ?? "";
-      const spec = (def as { containers?: Record<string, { states?: Record<string, { interface?: string; width?: string }>; interface?: string }> } | null)
-        ?.containers?.[cname];
+      const spec = (def as { templates?: Record<string, { template?: string; states?: Record<string, { interface?: string; width?: string }>; interface?: string }> } | null)
+        ?.templates?.[cname];
+      // THE MOUNT: `template:` names a template definition (the holder grammar:
+      // a place names what it holds); its OWN machinery runs —
+      // resolveActiveLayout derives its state from the instances' faces, its slots
+      // claim by face, sub-states stay contained in each instance's slice. EMPTY
+      // COLLAPSES: nothing held → nothing drawn (frame included) — a place with
+      // nothing collapses.
+      if (spec?.template) {
+        const tpl = mounted[spec.template];
+        const active = tpl ? resolveActiveLayout(tpl, store) : undefined;
+        // HOLD: LATEST (basic form, UNOVERSE_TEMPLATE_MODEL §9b): the mount holds
+        // only the CURRENT delivery — the guest's send clears the set.
+        const delivery = store.currentDeliveryPointers();
+        const held = active ? collectSlotPointers(active, store, delivery) : [];
+        if (!tpl) return null;
+        if (!active) return null;
+        if (!held.length) return null;
+        const tree = renderNode(active, store.getAppState() as Record<string, unknown>, dispatch, theme, `${String(key ?? cname)}-tpl`, makeResolveSlot(delivery), tpl.defs);
+        // A PLACE DECLARES ITS WIDTH ONCE (docs/design/05), same law as a slot
+        // panel: `appWidth` resolves via theme.appSize and sizes the frame box —
+        // `flex` is the served "all remaining space" name. Without it the frame's
+        // own styles decide (and a width-less frame beside a fixed-width chat
+        // collapsed to its padding — observed live 2026-08-28).
+        const declaredW = (node as { appWidth?: string }).appWidth;
+        const placeW = cssWidth(typeof declaredW === "string" ? (theme.appSize?.[declaredW] ?? declaredW) : undefined);
+        // THEME-FREE FALLBACK (same law as computeAppWidth's marker): a theme without
+        // an `appSize.flex` token must still mean "fill the remaining host space" —
+        // an unresolved name collapsed the place to its padding (observed live
+        // 2026-08-28, the light theme's missing `flex`).
+        const flexFallback = !placeW && declaredW === "flex";
+        const rawFrame = (node as { frame?: UnoverseNode }).frame;
+        if (rawFrame) {
+          const frame = placeW
+            ? ({ ...rawFrame, style: { ...(rawFrame.style ?? {}), width: placeW, flex: "0 0 auto" } } as UnoverseNode)
+            : flexFallback
+              ? ({ ...rawFrame, style: { ...(rawFrame.style ?? {}), flex: "1 1 0%", minWidth: 0 } } as UnoverseNode)
+              : rawFrame;
+          const innerSlot: SlotResolver = () => tree;
+          return renderNode(frame, store.getAppState() as Record<string, unknown>, dispatch, theme, `${String(key ?? cname)}-frame`, innerSlot, def?.defs);
+        }
+        return <div key={key} style={{ display: "flex", flexDirection: "column", minHeight: 0, ...(placeW ? { width: placeW, flex: "0 0 auto" } : flexFallback ? { flex: "1 1 0%", minWidth: 0 } : {}) }}>{tree}</div>;
+      }
       const stateNames = spec?.states ? Object.keys(spec.states) : [];
       const appState = store.getAppState() as Record<string, unknown>;
-      const active = (appState[`container:${cname}`] as string | undefined) ?? stateNames[0];
+      const active = (appState[`template:${cname}`] as string | undefined) ?? stateNames[0];
       const heldInterface = spec?.states ? spec.states[active ?? ""]?.interface : spec?.interface;
       // AN EMPTY STATE HOLDS NOTHING (`closed: {}` is a collapsed drawer): a declared
       // container whose active state names no interface renders EMPTY — never a bare
       // slot, which would grab every interface in the store and un-collapse the drawer.
       const emptyState = Boolean(spec?.states) && !heldInterface;
+      // (legacy holder path continues below unchanged)
       node = {
         ...node,
         type: "ComponentSlot",
@@ -322,8 +470,8 @@ export function StreamedUnoverseApp({ client, store, uri, onAction, theme: theme
             ? ({ limit: 0 } as never)
             : (node.select ?? {}),
       } as UnoverseNode;
-      if (containerChrome && spec) {
-        const set = (state: string) => store.mergeAppState({ [`container:${cname}`]: state });
+      if (templateChrome && spec) {
+        const set = (state: string) => store.mergeAppState({ [`template:${cname}`]: state });
         const inner = node;
         // THE STATE'S WIDTH: a container state may declare one (a collapsed drawer's slim
         // edge). Resolved like every panel width (app-size name, else raw CSS); absent,
@@ -332,7 +480,7 @@ export function StreamedUnoverseApp({ client, store, uri, onAction, theme: theme
         const stateW = declaredW ? (cssWidth(theme.appSize?.[declaredW] ?? declaredW) ?? declaredW) : undefined;
         return (
           <div key={key} style={{ display: "flex", flexDirection: "column", minHeight: 0, height: "100%", ...(stateW ? { width: stateW, flex: "0 0 auto", overflow: "hidden" } : {}) }}>
-            {containerChrome({ name: cname, states: stateNames, active, set })}
+            {templateChrome({ name: cname, states: stateNames, active, set })}
             <div style={{ flex: 1, minHeight: 0, overflow: "auto" }}>{resolveSlot(inner, `${String(key ?? cname)}-inner`)}</div>
           </div>
         );
@@ -350,7 +498,7 @@ export function StreamedUnoverseApp({ client, store, uri, onAction, theme: theme
     if (isViewField(claim?.field) && typeof claim?.eq === "string" && declaredClaim && claim.eq !== surfacedView) {
       return node.fallback ? renderNode(node.fallback, {}, dispatch, theme, key ?? "fallback", undefined, def?.defs) : null;
     }
-    const pointers = selectPointers(store, node);
+    const pointers = selectPointers(store, node, scope);
     if (pointers.length === 0) {
       return node.fallback ? renderNode(node.fallback, {}, dispatch, theme, key ?? "fallback", undefined, def?.defs) : null;
     }
@@ -364,7 +512,12 @@ export function StreamedUnoverseApp({ client, store, uri, onAction, theme: theme
       // height — the component's `height: "full"` finally has a definite container,
       // with zero per-face styling. Multi-occupant surfaces (a rail) stay content-sized.
       const fill = node.select?.limit === 1;
-      const innerSlot: SlotResolver = () => pointers.map((p) => leaf(p, undefined, fill));
+      // Multi-occupant surfaces (a rail) animate reorders; a single occupant fills its
+      // frame directly — a measuring wrapper there would break the height chain.
+      const innerSlot: SlotResolver = () =>
+        fill
+          ? pointers.map((p) => leaf(p, undefined, fill))
+          : <FlipList items={pointers.map((p) => ({ key: store.split(p).nodeId, node: leaf(p) }))} />;
       // A panel declares its width ONCE (docs/design/05): `appWidth` grows the app
       // (computeAppWidth) AND sizes the frame box here — the two can never disagree.
       // Named sizes resolve via theme.appSize like any token; unresolvable → no width.
@@ -377,8 +530,11 @@ export function StreamedUnoverseApp({ client, store, uri, onAction, theme: theme
         : node.frame;
       return renderNode(frame, store.getAppState() as Record<string, unknown>, dispatch, theme, key ?? "frame", innerSlot, def?.defs);
     }
-    return pointers.map((p) => leaf(p));
+    return <FlipList key={key ?? "slot"} items={pointers.map((p) => ({ key: store.split(p).nodeId, node: leaf(p) }))} />;
+  };
+  return resolveSlot;
   };
+  const resolveSlot = makeResolveSlot();
 
   // Timeline — GENERIC iterator. Walks the timeline and renders the `user` / `assistant`
   // DATA sub-tree per turn. Zero chat UX in the SDK: bubbles, alignment, structure all live

package/vendor/sdk/lib/connection.tsx

@@ -238,18 +238,20 @@ export function useUnoverseConnection(
       };
 
       // Inject the bearer on every underlying request (fresh per call → refresh-safe).
-      const authFetch = getAccessToken
-        ? async (url: string | URL, init?: RequestInit): Promise<Response> => {
-            const token = await getAccessToken();
-            const headers = new Headers(init?.headers);
-            if (token) headers.set("Authorization", `Bearer ${token}`);
-            return fetch(url, { ...init, headers });
-          }
-        : undefined;
+      // ALWAYS wrapped: dev tunnels need the ngrok bypass header, token or not
+      // (ngrok free interstitial = 200 HTML no CORS = dead /stream in sandboxed
+      // hosts; header is 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 {
         const transport = new StreamableHTTPClientTransport(
           new URL(`${streamUrl}${STREAM_ENDPOINT}`),
-          authFetch ? { fetch: authFetch } : undefined,
+          { fetch: authFetch },
         );
         await client.connect(transport);
         if (cancelled || clientRef.current !== client) {

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

@@ -122,6 +122,7 @@ export function computeAppWidth(root: unknown, store: ComponentStore, appSize?:
   const rw = (w: unknown): string | undefined => cssWidth(typeof w === "string" ? (appSize?.[w] ?? w) : undefined);
   const r = root as Record<string, unknown> | null | undefined;
   const widths: string[] = [];
+  let flexOpen = false;
   // Gather the tree's width-bearing nodes: always-open core panels and the reaction
   // SURFACES (view → panel width).
   const surfaces = new Map<string, string | undefined>();
@@ -152,6 +153,12 @@ export function computeAppWidth(root: unknown, store: ComponentStore, appSize?:
       } else if (n.appWidth !== undefined) {
         const w = rw(n.appWidth);
         if (w) widths.push(w); // a plain panel (the core column) is ALWAYS open
+        // The `flex` MARKER on an always-open place (a mounted Template) — same law
+        // as the active flex surface below: the panel completes the viewport, so the
+        // app is the full host width. Without this the marker was silently DROPPED
+        // here and the app box computed to the chat alone, flexing the place to 0px
+        // (measured live 2026-08-28: grid column track 0px, cards 667px tall).
+        else if (n.appWidth === "flex") flexOpen = true;
       }
     }
     for (const v of Object.values(n)) if (v && typeof v === "object") walk(v);
@@ -166,7 +173,7 @@ export function computeAppWidth(root: unknown, store: ComponentStore, appSize?:
   const activePanel = active ? surfaces.get(active) : undefined;
   // An ACTIVE flex surface fills the host viewport (the host caps at its pane); the
   // surface flexes into whatever the fixed panels leave.
-  if (activePanel === "flex") return "100%";
+  if (flexOpen || activePanel === "flex") return "100%";
   if (activePanel) widths.push(activePanel);
   if (!widths.length) return undefined;
   return widths.length === 1 ? widths[0] : `calc(${widths.join(" + ")})`;
@@ -210,16 +217,32 @@ export function resolveActiveView(
 ): { view: string; byGuest: boolean } {
   const order = def?.stateOrder?.length ? def.stateOrder : undefined;
   const valid = order ? new Set(order) : (validViews ?? new Set(orderedClaims(def)));
+  // A STATE THAT MOUNTS A TEMPLATE claims the template's own states (loader-stamped
+  // `claims`, UNOVERSE_TEMPLATE_MODEL §12): an instance arriving in any of them is a
+  // match FOR THE MOUNT STATE — "the grid holds cards" is what enters `courses`, and
+  // the empty grid is what releases it. Same walk, one more spelling of a match.
+  const aliasOf = new Map<string, string>();
+  for (const [sname, entry] of Object.entries((def?.templates ?? {}) as Record<string, { template?: string; claims?: string[] }>)) {
+    if (!entry?.template || !valid.has(sname)) continue;
+    for (const c of entry.claims ?? []) aliasOf.set(c, sname);
+  }
+  // A mount-claim match counts only within THE CURRENT DELIVERY (hold: latest):
+  // released instances must release the state too, or the app would sit in an
+  // arrangement whose template just emptied.
+  const delivery = aliasOf.size ? store.currentDeliveryPointers() : null;
   // One pass over the timeline: the best (latest) match per view.
   const best = new Map<string, { at: number; byGuest: boolean }>();
   for (const turn of store.getResponses())
     for (const p of turn.components) {
       const { chatId, nodeId } = store.split(p);
       const v = viewOf(store.get(chatId, nodeId) as Record<string, unknown>);
-      if (!v || !valid.has(v)) continue;
+      if (!v) continue;
+      const aliasTarget = aliasOf.get(v);
+      const target = valid.has(v) ? v : aliasTarget && delivery?.has(p) ? aliasTarget : undefined;
+      if (!target) continue;
       const t = store.touchOf(p);
-      const b = best.get(v);
-      if (!b || t > b.at) best.set(v, { at: t, byGuest: store.interactionTouchOf(p) >= t });
+      const b = best.get(target);
+      if (!b || t > b.at) best.set(target, { at: t, byGuest: store.interactionTouchOf(p) >= t });
     }
   if (order) {
     // THE LADDER: first declared state with any match wins. No word is special.
@@ -298,12 +321,14 @@ export function resolveLatch(
 }
 
 /** Resolve a ComponentSlot's `select` against the store → ordered pointers. */
-export function selectPointers(store: ComponentStore, node: UnoverseNode): string[] {
+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 };
   let pointers =
     sel.from === "all"
       ? store.getResponses().flatMap((r) => r.components)
       : (store.latestResponse()?.components ?? []);
+  // A SCOPED selection (the mount's hold: latest) sees only the given pointers.
+  if (scope) pointers = pointers.filter((p) => scope.has(p));
 
   // `where` — select by COMPONENT STATE (the reaction contract, STATE_MODEL §5b): any
   // component whose own slice matches, ordered newest state-write first so `limit: 1`
@@ -313,6 +338,18 @@ export function selectPointers(store: ComponentStore, node: UnoverseNode): strin
   // interface holds it whatever state it is in. Placement, not reaction — the one case
   // where selecting by definition name is the point rather than the anti-pattern.
   if (sel.type) pointers = pointers.filter((p) => store.typeOf(p) === sel.type);
+  // ONE INSTANCE, ONE CARD. An instance is its nodeId; the same instance re-delivered in
+  // a later turn (a row card re-surfaced by a later search) is a REFRESH of that card,
+  // never a sibling. `from: "all"` spans turns and would otherwise show both copies, so
+  // keep the most recently written pointer per instance. Per-turn selections are
+  // unaffected — a turn's nodeIds are already unique.
+  const byInstance = new Map<string, string>();
+  for (const p of pointers) {
+    const { nodeId } = store.split(p);
+    const held = byInstance.get(nodeId);
+    if (!held || store.touchOf(p) >= store.touchOf(held)) byInstance.set(nodeId, p);
+  }
+  if (byInstance.size !== pointers.length) pointers = [...byInstance.values()];
   if (sel.where) {
     const { field, eq, ne } = sel.where;
     const within = (sel.where as { in?: unknown[] }).in;

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

@@ -66,18 +66,21 @@ export class UnoverseClient {
       this.connecting = (async () => {
         const getToken = this.options.getAccessToken;
         // Inject the bearer on every underlying request (fresh per call → refresh-safe).
-        const authFetch = getToken
-          ? async (url: string | URL, init?: RequestInit): Promise<Response> => {
-              const token = await getToken();
-              const headers = new Headers(init?.headers);
-              if (token) headers.set("Authorization", `Bearer ${token}`);
-              return fetch(url, { ...init, headers });
-            }
-          : undefined;
-        const transport = new StreamableHTTPClientTransport(
-          new URL(this.url),
-          authFetch ? { fetch: authFetch } : undefined,
-        );
+        // ALWAYS wrapped (not only when a token getter exists): dev tunnels need the
+        // ngrok bypass header below, token or not.
+        const authFetch = async (url: string | URL, init?: RequestInit): Promise<Response> => {
+          const token = getToken ? await getToken() : undefined;
+          const headers = new Headers(init?.headers);
+          if (token) headers.set("Authorization", `Bearer ${token}`);
+          // DEV TUNNEL ONLY: ngrok's free tier answers browser requests with an
+          // interstitial (200 HTML, no CORS) unless this header rides along — which
+          // read as "blocked by CORS" inside ChatGPT's widget sandbox (observed live
+          // 2026-08-28). Hostname-gated so production traffic never grows a
+          // preflight-triggering custom header.
+          if (String(url).includes("ngrok")) headers.set("ngrok-skip-browser-warning", "true");
+          return fetch(url, { ...init, headers });
+        };
+        const transport = new StreamableHTTPClientTransport(new URL(this.url), { fetch: authFetch });
         await this.client.connect(transport);
         this.connected = true;
       })().catch((err) => {

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

@@ -137,6 +137,13 @@ export function applyServerMessage(store: ComponentStore, msg: ServerMessage, se
       else if (m.state === "ERROR" || m.state === "WORKFLOW_ERROR") store.setLifecycle("error");
       return;
     }
+    case "COMPONENTS_CLEAR": {
+      // Rule 5's empty delivery (STATE_MODEL §5, amended 2026-08-26): a turn that ran
+      // with cards enabled and surfaced none owns the screen — earlier-turn components
+      // in public states retract to inline. The sender decided WHEN; this only obeys.
+      store.supersedeAll(typeof msg.chatId === "string" ? msg.chatId : undefined);
+      return;
+    }
     // No AUDIO_STATE case: voice is a NATIVE SERVICE on the WS audio lane (useVoiceService),
     // NOT the structured MCP stream. Audio-state events never arrive here (UNOVERSE_SPEC §2e-1).
     case "APP_DATA": {

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

@@ -27,6 +27,19 @@
 /** A pointer into the data plane — the `${chatId}:${nodeId}` key. */
 export type Pointer = string;
 
+/** Structural equality for wire values: identity first, JSON compare for the rest.
+ *  Wire payloads are plain JSON, so stringify is faithful there; anything it cannot
+ *  serialize (cycles, functions) counts as CHANGED, which errs on re-rendering. */
+function sameValue(a: unknown, b: unknown): boolean {
+  if (Object.is(a, b)) return true;
+  if (typeof a !== "object" || typeof b !== "object" || a === null || b === null) return false;
+  try {
+    return JSON.stringify(a) === JSON.stringify(b);
+  } catch {
+    return false;
+  }
+}
+
 export interface UserTurn {
   role: "user";
   id: string;
@@ -81,6 +94,8 @@ export class ComponentStore {
   //     ComponentSlot.select.where's "most recent state-write wins" ordering (§5b).
   //     Generic bookkeeping: core stamps WHEN a slice changed, never reads WHAT. ---
   private touches = new Map<string, number>();
+  /** The touch sequence at the guest's last send — the CURRENT DELIVERY's floor. */
+  private deliveryWatermark = 0;
   /** Slices whose LATEST write was a guest interaction (`mergeComponentState`) — value is
    *  that write's touch seq. Powers `pinned` layouts: guest writes move them, arrivals don't. */
   private interactionTouches = new Map<string, number>();
@@ -182,6 +197,31 @@ export class ComponentStore {
    * refresh is VISIBLE is the ladder's business alone (rule 4: higher states mask;
    * lower states update silently underneath).
    */
+  /**
+   * RULE 5's EMPTY DELIVERY (STATE_MODEL §5 rule 5, amended 2026-08-26): a discovery
+   * turn that ran with cards enabled and surfaced NONE still owns the screen — the
+   * server says so with COMPONENTS_CLEAR, and every earlier-turn component sitting in
+   * a public state retracts to inline. `supersede` for ALL states at once: same
+   * durable (`lifetime: "conversation"`) opt-out, same same-turn exemption. Rule 7
+   * stands — this rides the answer's delivery, never the guest's typing.
+   */
+  supersedeAll(arrivingChatId?: string): void {
+    let changed = false;
+    for (const [key, slice] of this.data) {
+      if (arrivingChatId && key.startsWith(`${arrivingChatId}:`)) continue;
+      if (slice.lifetime === "conversation") continue;
+      const v = (slice.view ?? slice.defaultState) as unknown;
+      if (typeof v !== "string" || !v || v === "inline") continue;
+      const next: Record<string, unknown> = { ...slice };
+      if ("view" in next || !("defaultState" in next)) next.view = "inline";
+      if ("defaultState" in next) next.defaultState = "inline";
+      this.data.set(key, next);
+      this.touches.set(key, ++this.touchSeq);
+      changed = true;
+    }
+    if (changed) this.bump();
+  }
+
   private supersede(arrivingChatId: string, view: unknown): void {
     if (typeof view !== "string" || !view || view === "inline") return;
     let changed = false;
@@ -330,6 +370,9 @@ export class ComponentStore {
    *  guest's next message; a stale rail is cleared by the cards that replace it,
    *  never by the message that asked for them. */
   addUserMessage(chatId: string, text: string): void {
+    // The guest's send is the delivery boundary (hold: latest, basic form): every
+    // pointer not server-touched after this moment leaves the current set.
+    this.deliveryWatermark = this.touchSeq;
     this.timeline.push({ role: "user", id: `u${this.seq++}`, chatId, text, createdAt: Date.now() });
     this.evict();
     this.bump();
@@ -376,8 +419,12 @@ export class ComponentStore {
       this.timeline.push(resp);
       this.evict();
     }
-    if (!resp.components.includes(key)) resp.components.push(key);
-    this.bump();
+    // A reload of an already-placed pointer changes no structure — bump only when
+    // something actually moved, so re-delivering a card does not re-walk the template.
+    if (!resp.components.includes(key)) {
+      resp.components.push(key);
+      this.bump();
+    }
   }
 
   private responseFor(chatId: string): AssistantTurn | undefined {
@@ -409,7 +456,16 @@ export class ComponentStore {
   private merge(key: string, patch: Record<string, unknown>): void {
     // merge-not-replace. Fresh object identity per merge = the per-slice snapshot
     // React bindings key on (useSyncExternalStore bails out for untouched slices).
-    this.data.set(key, { ...(this.data.get(key) ?? {}), ...patch });
+    //
+    // AN UNCHANGED MERGE IS A TRUE NO-OP: a reload that re-delivers the same props must
+    // not bump recency (which would reorder recency-sorted slots) or mint a new snapshot
+    // (which would re-render the card). Cheap identity check per key first; only keys
+    // that fail it pay for the structural compare — wire payloads are plain JSON, so
+    // JSON.stringify is a faithful equality there, and a non-serializable value simply
+    // counts as changed.
+    const prev = this.data.get(key);
+    if (prev && Object.keys(patch).every((k) => k in prev && sameValue(prev[k], patch[k]))) return;
+    this.data.set(key, { ...(prev ?? {}), ...patch });
     this.touches.set(key, ++this.touchSeq);
     this.bumpData();
   }
@@ -508,6 +564,23 @@ export class ComponentStore {
   getTimeline(): readonly Turn[] {
     return this.timeline;
   }
+  /** THE CURRENT DELIVERY (hold: latest, basic form — UNOVERSE_TEMPLATE_MODEL §9b):
+   *  the pointers placed since the guest's LAST SEND. A mounted template holds only
+   *  these, so the guest's own send clears the set — nothing stale ever survives a
+   *  turn, and the disappearance happens at the guest's action, never a background
+   *  delivery's. */
+  currentDeliveryPointers(): Set<string> {
+    // TOUCH-BASED, not turn-based: durable-keyed instances (conversation-chatId
+    // renders) file into ONE assistant turn across the whole conversation, so turn
+    // position says nothing about freshness. A pointer is current when it was
+    // WRITTEN since the guest's last send — which also makes a re-delivered card
+    // part of the new set, exactly as hold: latest wants.
+    const out = new Set<string>();
+    for (const r of this.getResponses())
+      for (const p of r.components)
+        if ((this.touches.get(p) ?? 0) > this.deliveryWatermark) out.add(p);
+    return out;
+  }
   /** Just the assistant responses, in order. */
   getResponses(): AssistantTurn[] {
     return this.timeline.filter((t): t is AssistantTurn => t.role === "assistant");