@unoverse-platform/studio 0.1.22 → 0.1.24

package/package.json

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

package/screens/ComponentsView.tsx

@@ -8,7 +8,7 @@ import { ComponentStore } from "@unoverse/sdk";
 import { UnoverseComponent, type ResolvedTheme } from "@unoverse/sdk";
 import { client, authedFetch, hasSourceAccess } from "studio-host";
 import { SourceView } from "./SourceView";
-import { stateActivation } from "./states";
+import { stateActivation, faceOf, switchLayers } from "./states";
 import { usePersistentState, useRegistryToggles, ToggleSwitch } from "studio-host";
 
 const CHAT_ID = "demo";
@@ -198,28 +198,11 @@ export function ComponentsView({ theme, org = "all" }: { theme: ResolvedTheme; o
   // keys it declares in `state` — that is what the toolbar is allowed to write.
   const subStatesOf = (faceName: string): { on: string; name: string }[] => {
     if (!current?.root || !hasFaces || faceName === "inline") return [];
-    let face: unknown;
-    const findFace = (n: any): void => {
-      if (face || !n || typeof n !== "object") return;
-      if (Array.isArray(n)) { n.forEach(findFace); return; }
-      if (n.type === "Switch" && n.on === "defaultState" && n.cases?.[faceName]) { face = n.cases[faceName]; return; }
-      Object.values(n).forEach(findFace);
-    };
-    findFace(current.root);
     // The component's OWN state keys — everything else in the subtree belongs to an
-    // inlined atom or shared component, or is plain data.
+    // inlined atom or shared component, or is plain data. The derivation itself is
+    // the SHARED layer resolver (states.ts, UNOVERSE_LAYERS.md §3c).
     const ownKeys = new Set(Object.keys((current.state ?? {}) as Record<string, unknown>));
-    const out: { on: string; name: string }[] = [];
-    const walk = (n: any): void => {
-      if (!n || typeof n !== "object") return;
-      if (Array.isArray(n)) { n.forEach(walk); return; }
-      if (n.type === "Switch" && typeof n.on === "string" && n.on !== "defaultState" && ownKeys.has(n.on) && n.cases && typeof n.cases === "object") {
-        for (const k of Object.keys(n.cases)) if (k !== "default" && !out.some((s) => s.name === k)) out.push({ on: n.on, name: k });
-      }
-      Object.values(n).forEach(walk);
-    };
-    walk(face);
-    return out;
+    return switchLayers(faceOf(current.root, faceName), ownKeys);
   };
   const subStates = subStatesOf(masterState);
 

package/screens/TemplatesView.tsx

@@ -1,4 +1,16 @@
 /**
+ * ============================================================================
+ * ⛔ THIS FILE IS NOT TO BE EDITED. ⛔
+ *
+ * Every single change in this file — and any change made on behalf of a
+ * component or template that seems to need one here — MUST be confirmed by
+ * Gavin first. No exceptions: not bug fixes, not one-liners, not reverts.
+ * State the intended diff and wait for an explicit yes.
+ *
+ * Components and templates are DATA (rx/). If a template seems to need code
+ * here, the answer is almost always to express it as data — or to ask.
+ * ============================================================================
+ *
  * Templates view — renders a TEMPLATE definition (layout) and fills its
  * ComponentSlots from a mock conversation seeded into the store.
  *
@@ -11,8 +23,9 @@ import { useCallback, useEffect, useMemo, useState, useSyncExternalStore } from
 import { useAuth } from "react-oidc-context";
 import { usePersistentState, useRegistryToggles, ToggleSwitch } from "studio-host";
 import { ComponentStore } from "@unoverse/sdk";
-import { StreamedUnoverseTemplate, useUnoverseConnection, computeAppWidth, resolveActiveLayout, type ResolvedTheme, type UseVoiceServiceConfig } from "@unoverse/sdk";
+import { StreamedUnoverseTemplate, useUnoverseConnection, computeAppWidth, resolveActiveLayout, visible, type ResolvedTheme, type UseVoiceServiceConfig } from "@unoverse/sdk";
 import { NativeAppHost } from "./NativeAppHost";
+import { inArrangement } from "./states";
 import { client, authedFetch, hasAuth, UNOVERSE_BASE } from "studio-host";
 
 // Per-APP test conversation: each app chats in its own conversation id, so testing
@@ -28,16 +41,18 @@ const chatIdFor = (app: string) => `demo-${app.toLowerCase()}-${SESSION_NONCE}`;
 // it opens the Gravity data plane (WS component stream + REST execute) against the
 // configured server/workflow/node; in MOCK mode it seeds a fake conversation.
 // These are editable in the toolbar (LIVE mode) and persisted across refreshes.
-// Dev workbench serves /api + /ws/gravity + /stream on the merged uWS at :4205
-// (the retired gateway was :4100). Prod uses the page origin.
-const CONN_DEFAULTS = { server: "localhost:4205", workflowId: "wf-r4jzo7", triggerNode: "inputtrigger1", token: "" };
+// The dev universe serves /mcp + /api + /ws/gravity + /stream on the merged uWS at
+// :4105 — since the workbench retired, uWS binds the public port DIRECTLY in dev, same
+// as prod (the retired workbench was :4205, the retired gateway :4100). Prod uses the
+// page origin.
+const CONN_DEFAULTS = { server: "localhost:4105", workflowId: "wf-r4jzo7", triggerNode: "inputtrigger1", token: "" };
 const CONN_KEY = "unoverse.workbench.conn";
 
 function loadConn(): typeof CONN_DEFAULTS {
   try {
     const saved = JSON.parse(localStorage.getItem(CONN_KEY) ?? "{}");
-    // Migration: drop the retired gateway port so the new default applies.
-    if (saved.server === "localhost:4100") delete saved.server;
+    // Migration: drop retired ports (gateway :4100, workbench :4205) so the new default applies.
+    if (saved.server === "localhost:4100" || saved.server === "localhost:4205") delete saved.server;
     return { ...CONN_DEFAULTS, ...saved };
   } catch {
     return { ...CONN_DEFAULTS };
@@ -46,6 +61,10 @@ function loadConn(): typeof CONN_DEFAULTS {
 
 interface PropDef {
   default?: unknown;
+  // Briefed pages declare their Studio mock as `preview` (ComponentsView reads the
+  // same pair) — the mock is `preview ?? default`, per the authoring contract.
+  preview?: unknown;
+  type?: string;
 }
 interface Def {
   name: string;
@@ -96,7 +115,9 @@ interface Def {
     // Per-STATE mock seeding: `{ "<state>": ["coursecard", "coursecard"] }` — the
     // author decides what each state's preview shows (a repeated name = several
     // instances). Supersedes the legacy flat `previewComponents`.
-    preview?: Record<string, string[]>;
+    // Per-state mock: an ARRAY seeds components; an OBJECT is authored template-state
+    // data (what the workflow would have echoed) merged verbatim on pick.
+    preview?: Record<string, string[] | Record<string, unknown>>;
     previewComponents?: string[];
     fluidHeight?: boolean;
     // The app's named default state on load (the single authored field, OPEN name):
@@ -147,6 +168,13 @@ export function TemplatesView({
   // null = the default layout. Independent of the local-state axis — any layout can
   // combine with any local state (a voice List layout while agent-speaking).
   const [activeLayout, setActiveLayout] = useState<string | null>(null);
+  // A STATE BELONGS TO THE LAYOUTS THAT DRAW IT (UNOVERSE_LAYERS.md §3c) — same shared
+  // layer resolver ComponentsView uses for a face's steps (states.ts): a state is in
+  // scope when the ACTIVE layout's tree carries its selector. States shared by all
+  // layouts (a chat core's welcome) match everywhere; a rail-only state matches only
+  // its own arrangement, like Detail under Course.
+  const stateInLayout = (s: { when?: unknown; where?: unknown }, t: { layouts?: Record<string, unknown>; defaultLayout?: string; root?: unknown }): boolean =>
+    !t.layouts || inArrangement(t.layouts[activeLayout ?? t.defaultLayout ?? "main"] ?? t.root, s);
   useEffect(() => {
     const t = templates.find((x) => x.name === selected);
     setActiveState(t?.states?.filter((s) => !(t.layouts && s.name in t.layouts!))[0] ?? null);
@@ -229,8 +257,13 @@ export function TemplatesView({
   const liveStateName = useMemo(() => {
     void storeVersion; // recompute on every store write
     const states = selectedDef?.states ?? [];
+    // This name lights the LOCAL-state rail, so layouts (which have their own pill row
+    // and their own `activeLayout` highlight) are not candidates: a claimed `review`
+    // view must not blank the rail while a local discriminant is active beside it —
+    // the two axes compose (a review arrangement in its gathering state).
     const claims = new Map<string, string>(); // view -> state name
     for (const s of states) {
+      if (selectedDef?.layouts && s.name in selectedDef.layouts) continue;
       const eq = (s.where as { eq?: unknown } | undefined)?.eq;
       if (typeof eq === "string") claims.set(eq, s.name);
     }
@@ -246,6 +279,13 @@ export function TemplatesView({
         }
       }
     if (view) return claims.get(view) ?? null;
+    // LOCAL states carry their own selector (`when`, a condition on template state —
+    // railState/callState-style discriminants). Evaluate it with the RENDERER'S OWN
+    // predicate (`visible`, one condition semantics), against the template-state bag —
+    // so a pill pick, a component's write, or a live workflow echo all light the same.
+    const ts = store.getTemplateState() as Record<string, unknown>;
+    const local = states.find((s) => s.when && typeof s.when === "object" && visible(s.when as Parameters<typeof visible>[0], ts));
+    if (local) return local.name;
     const base = store.getTimeline().length === 0 ? "isEmpty" : "hasMessages";
     return states.find((s) => s.when === base)?.name ?? null;
   }, [storeVersion, store, selectedDef]);
@@ -413,7 +453,9 @@ export function TemplatesView({
   }, [store, live]);
 
   const defaultsOf = (d: Def) =>
-    Object.fromEntries(Object.entries(d.props ?? {}).map(([k, v]) => [k, v.default]));
+    Object.fromEntries(
+      Object.entries(d.props ?? {}).map(([k, v]) => [k, v.preview ?? v.default ?? (v.type === "array" ? [] : v.type === "object" ? {} : "")]),
+    );
 
   // Seed the given components into the latest response, so any slot that matches fills;
   // unmatched slots skeleton. The SET is chosen by the caller — scoped to the selected
@@ -500,7 +542,13 @@ export function TemplatesView({
     //  • { field, eq } (template-state selector, e.g. defaultState="focus") → set it after seeding
     // An explicit preview entry for the state OVERRIDES all of it — the author decided.
     const previewMap = selectedDef?.app?.preview;
-    const entry = activeLayout ? previewMap?.[activeLayout] : activeState ? previewMap?.[activeState.name] : undefined;
+    // An OBJECT preview entry is authored TEMPLATE-STATE mock data — what the workflow
+    // would have echoed (comments, railState, an anchor) — merged as-is so a state's
+    // pill previews with real content. Arrays keep the existing meaning: component seeds.
+    const stateEntry = activeState ? previewMap?.[activeState.name] : undefined;
+    const stateData = stateEntry && !Array.isArray(stateEntry) ? (stateEntry as Record<string, unknown>) : undefined;
+    const layoutEntry = activeLayout ? previewMap?.[activeLayout] : stateEntry;
+    const entry = Array.isArray(layoutEntry) ? layoutEntry : undefined;
     const wantEmpty = !entry && !activeLayout && typeof when === "string" && when === "isEmpty";
     // A COMPONENT is only seeded for a reaction-contract state (select.where) — the
     // surface needs one to grab (Focus). Plain template states (welcome, conversation)
@@ -516,7 +564,11 @@ export function TemplatesView({
           : [];
       // Seed when there's preview content OR a picked state that needs a live conversation.
       if (set.length || activeState) {
-        store.addUserMessage(chatIdFor(selected ?? "app"), "Show me this app");
+        // An autoTrigger app launches by RAW trigger — nothing prints to the
+        // conversation (protocol §launch-from-UI). The mock mirrors it: components
+        // seed without the synthetic user turn, so a template that renders user turns
+        // outside a chat (a review pile) never shows "Show me this app" as content.
+        if (!selectedDef?.app?.autoTrigger) store.addUserMessage(chatIdFor(selected ?? "app"), "Show me this app");
         // Component states need a body to grab; app declares no previewComponents →
         // fall back to the SAMPLE ANSWER (the Markdown component's own default content)
         // so the conversation still previews a real assistant turn.
@@ -534,6 +586,9 @@ export function TemplatesView({
     } else if (typeof when === "string" && when !== "isEmpty" && when !== "hasMessages") {
       store.mergeTemplateState({ [when]: true });
     }
+    // Authored template-state mock (object preview entry) — merged AFTER the selector so
+    // the author's data wins (it may refine the same keys, e.g. railState + comments).
+    if (stateData) store.mergeTemplateState(stateData);
     // Reaction-contract activation (STATE_MODEL §5b): the surface (or the layout pill —
     // same selector) reacts to COMPONENT state, so activate it the way the runtime
     // does — put a seeded component INTO that view. Same write the component's own
@@ -578,7 +633,7 @@ export function TemplatesView({
                 the rail keeps only the template's LOCAL states. */}
             {!live && selected === t.name && (t.states?.length ?? 0) > 0 && (
               <div className="my-0.5 ml-2 flex flex-col gap-px border-l border-gray-700 pl-2">
-                {t.states!.filter((s) => !(t.layouts && s.name in t.layouts!)).map((s) => (
+                {t.states!.filter((s) => !(t.layouts && s.name in t.layouts!)).filter((s) => stateInLayout(s, t)).map((s) => (
                   <button
                     key={s.name}
                     onClick={() => {

package/screens/states.ts

@@ -1,32 +1,75 @@
 /**
- * Component-state activation — shared by the Templates and Components views.
+ * Layer resolution + state activation — shared by the Templates and Components views.
  *
  * A component's `states/` files are its Switch-case layers: the state NAME is the
  * case key, and the Switch's `on` field is the discriminant that selects it
  * (UNOVERSE_LAYERS.md §7). To show a state, write `{ [discriminant]: name }` into
  * the component's own slice — exactly what the component's own buttons do.
+ *
+ * SCOPE lives here too (UNOVERSE_LAYERS.md §3c): a layer belongs to the arrangement
+ * that DRAWS it — a face's steps are the Switches on the component's own keys inside
+ * that face; a template state belongs to the layouts whose trees carry its selector.
+ * The structure is the declaration; both views derive, neither lists.
+ */
+
+/** Walk every object node of a definition tree until `visit` says stop (returns true). */
+function walkTree(n: unknown, visit: (node: Record<string, unknown>) => boolean | void): boolean {
+  if (!n || typeof n !== "object") return false;
+  if (Array.isArray(n)) return n.some((c) => walkTree(c, visit));
+  const o = n as Record<string, unknown>;
+  if (visit(o)) return true;
+  return Object.values(o).some((v) => walkTree(v, visit));
+}
+
+/** The subtree a face draws: the root's `Switch on defaultState` case of that name. */
+export function faceOf(root: unknown, face: string): unknown {
+  let found: unknown;
+  walkTree(root, (o) => {
+    if (o.type === "Switch" && o.on === "defaultState" && o.cases && typeof o.cases === "object" && (o.cases as Record<string, unknown>)[face]) {
+      found = (o.cases as Record<string, unknown>)[face];
+      return true;
+    }
+  });
+  return found;
+}
+
+/**
+ * The STEPS a subtree owns: every case of a `Switch` that turns on one of the thing's
+ * OWN state keys (`defaultState` excluded — that Switch picks faces, not steps).
+ * Switches on data fields (`kind`, a nested component's key) are content selection,
+ * not layers — which is why the caller passes the declared keys.
+ */
+export function switchLayers(tree: unknown, ownKeys: ReadonlySet<string>): { on: string; name: string }[] {
+  const out: { on: string; name: string }[] = [];
+  walkTree(tree, (o) => {
+    if (o.type === "Switch" && typeof o.on === "string" && o.on !== "defaultState" && ownKeys.has(o.on) && o.cases && typeof o.cases === "object") {
+      for (const k of Object.keys(o.cases)) if (k !== "default" && !out.some((s) => s.name === k)) out.push({ on: o.on, name: k });
+    }
+  });
+  return out;
+}
+
+/**
+ * Does an arrangement DRAW this state? Includes are inlined at serve time, so the
+ * selector authored on a state file (`visibleWhen` for a local layer, `select.where`
+ * for a reaction surface) appears verbatim inside every layout that `$include`s it.
+ * A state with no selector has nothing to scope by — always in.
  */
+export function inArrangement(tree: unknown, state: { when?: unknown; where?: unknown }): boolean {
+  const sel = JSON.stringify(state.when ?? state.where ?? null);
+  if (sel === "null") return true;
+  return walkTree(tree, (o) => JSON.stringify(o.visibleWhen ?? null) === sel || JSON.stringify((o.select as { where?: unknown } | undefined)?.where ?? null) === sel);
+}
 
 /** Find the discriminant field whose Switch has a case named `stateName`. */
 export function discriminantFor(root: unknown, stateName: string): string | null {
   let found: string | null = null;
-  const walk = (n: unknown): void => {
-    if (found || !n || typeof n !== "object") return;
-    if (Array.isArray(n)) return n.forEach(walk);
-    const o = n as Record<string, unknown>;
-    if (
-      o.type === "Switch" &&
-      typeof o.on === "string" &&
-      o.cases &&
-      typeof o.cases === "object" &&
-      Object.prototype.hasOwnProperty.call(o.cases, stateName)
-    ) {
+  walkTree(root, (o) => {
+    if (o.type === "Switch" && typeof o.on === "string" && o.cases && typeof o.cases === "object" && Object.prototype.hasOwnProperty.call(o.cases, stateName)) {
       found = o.on;
-      return;
+      return true;
     }
-    Object.values(o).forEach(walk);
-  };
-  walk(root);
+  });
   return found;
 }
 

package/vendor/sdk/lib/primitives.tsx

@@ -130,18 +130,96 @@ const inspectId = (node: UnoverseNode): string | undefined => {
   return typeof id === "string" ? id : undefined;
 };
 
-export function BoxView({ node, data, theme, children }: { node: UnoverseNode; data: Record<string, unknown>; theme: ResolvedTheme; children?: ReactNode }): ReactNode {
+export function BoxView({ node, data, theme, children, onAction }: { node: UnoverseNode; data: Record<string, unknown>; theme: ResolvedTheme; children?: ReactNode; onAction?: ActionHandler }): ReactNode {
   const { className, styleEls, style } = nodeChrome(node, data, theme);
   const scrollRef = useAutoScrollToEnd(node.autoScroll === true);
   const revealRef = useRevealWhenStuck(node.revealOnStick === true);
+  const sel = (node as { selection?: { label?: string; action?: unknown } }).selection;
+  const { selRef, pick, clearPick } = useTextSelection(!!sel);
+  // A selection host must anchor its floating affordance; default to relative only when
+  // the definition declared no position of its own (sticky/absolute roots keep theirs).
+  const hostStyle = sel && !(style as CSSProperties).position ? ({ ...style, position: "relative" } as CSSProperties) : style;
   return (
-    <div ref={scrollRef ?? revealRef} className={className} style={style} data-unoverse-id={inspectId(node)}>
+    <div ref={scrollRef ?? revealRef ?? selRef} className={className} style={hostStyle} data-unoverse-id={inspectId(node)}>
       {styleEls}
       {children}
+      {sel && pick && (
+        <button
+          style={{
+            position: "absolute",
+            top: pick.top,
+            left: pick.left,
+            transform: "translate(-50%, -100%)",
+            zIndex: 40,
+            whiteSpace: "nowrap",
+            ...styleToCss(((theme as { selection?: { chip?: Record<string, unknown> } }).selection?.chip ?? SELECTION_CHIP_BUILTIN) as Record<string, unknown>, theme),
+          }}
+          onMouseDown={(e) => e.preventDefault() /* keep the selection alive through the click */}
+          onClick={() => {
+            onAction?.((sel.action as Parameters<ActionHandler>[0]) ?? "select", { ...data, selection: pick.text });
+            clearPick();
+          }}
+        >
+          {sel.label ?? "Comment"}
+        </button>
+      )}
     </div>
   );
 }
 
+// The selection chip's look: a SERVED recipe (`theme.selection.chip`) when the org styles
+// one; else this neutral fallback of token NAMES resolved against the same theme — the
+// skeleton-shimmer pattern. The SDK still authors no values, only names.
+const SELECTION_CHIP_BUILTIN: Record<string, unknown> = {
+  background: "action.primary",
+  color: "text.inverse",
+  font: "body.sm",
+  radius: "full",
+  padding: ["1", "3"],
+  shadow: "lg",
+  border: "none",
+  cursor: "pointer",
+};
+
+/**
+ * Generic "text was selected here" behavior (opt-in via `node.selection`). The renderer is
+ * the ONLY layer that can know a reader selected text — definitions cannot express it —
+ * so, like `skeleton` and `autoScroll`, capture is SDK behavior while every consequence
+ * stays authored: the node declares the ACTION (fired with the selected text in scope as
+ * `{{selection}}`) and the chip's look is served (`theme.selection.chip`). Selection is
+ * read from the node's own root (shadow-DOM aware); collapsing it dismisses the chip.
+ */
+function useTextSelection(enabled: boolean) {
+  const selRef = useRef<HTMLDivElement | null>(null);
+  const [pick, setPick] = useState<{ text: string; top: number; left: number } | null>(null);
+  useEffect(() => {
+    if (!enabled) return;
+    const el = selRef.current;
+    if (!el) return;
+    const read = () => {
+      const root = el.getRootNode() as Document | ShadowRoot;
+      const s = (root as unknown as { getSelection?: () => Selection | null }).getSelection?.() ?? window.getSelection();
+      if (!s || s.isCollapsed || s.rangeCount === 0) return setPick(null);
+      const range = s.getRangeAt(0);
+      if (!el.contains(range.commonAncestorContainer)) return setPick(null);
+      const text = s.toString().trim();
+      if (!text) return setPick(null);
+      const r = range.getBoundingClientRect();
+      const host = el.getBoundingClientRect();
+      setPick({ text, top: r.top - host.top, left: Math.min(Math.max(0, r.left - host.left + r.width / 2), host.width) });
+    };
+    const up = () => window.setTimeout(read, 0); // after the browser settles the selection
+    // Listen on the DOCUMENT, not the host: a drag-select routinely ends with the mouse
+    // released outside the host (over a rail, past the edge), and mouse events are
+    // composed, so they cross the shadow boundary to reach it. `read` still guards with
+    // `el.contains(...)`, so only selections inside this host raise the chip.
+    const doc = el.ownerDocument;
+    doc.addEventListener("mouseup", up);
+    return () => doc.removeEventListener("mouseup", up);
+  }, [enabled]);
+  return { selRef: enabled ? selRef : undefined, pick, clearPick: () => setPick(null) };
+}
+
 /**
  * Generic "stick to the newest content" behavior for a scroll container (opt-in via
  * `node.autoScroll`). Smooth-scrolls to the bottom whenever content grows — a new turn
@@ -364,6 +442,27 @@ export function InputView({ node, data, theme, onAction }: { node: UnoverseNode;
     if (field == null) setLocal("");
   };
   const { style, disabled } = nodeChrome(node, data, theme);
+  // `multiline: true` — the same irreducible input as a `<textarea>` (critique, notes —
+  // anything longer than one line). Enter inserts a newline; Cmd/Ctrl+Enter submits.
+  // Same element class, no chrome, no new primitive.
+  if ((node as { multiline?: boolean }).multiline === true) {
+    return (
+      <textarea
+        style={style}
+        disabled={disabled}
+        value={value}
+        placeholder={node.placeholder}
+        rows={(node as { rows?: number }).rows ?? 3}
+        onChange={(e) => setValue(e.target.value)}
+        onKeyDown={(e) => {
+          if (e.key === "Enter" && (e.metaKey || e.ctrlKey)) {
+            e.preventDefault();
+            submit();
+          }
+        }}
+      />
+    );
+  }
   return (
     <input
       style={style}

package/vendor/sdk/lib/render.tsx

@@ -173,7 +173,7 @@ export function renderNode(
     case "Row":
     case "Column":
       return (
-        <BoxView key={key} node={node} data={data} theme={theme}>
+        <BoxView key={key} node={node} data={data} theme={theme} onAction={onAction}>
           {kids}
         </BoxView>
       );

package/vendor/sdk/main.tsx

@@ -12,6 +12,12 @@ type HostConfig = Omit<AppConfig, "getAccessToken"> & { token?: string };
 let root: Root | null = null;
 let current: HostConfig | null = null;
 
+// Stable identity, module-level: the connection hook keys its lifecycle on the
+// `getAccessToken` reference (connection.tsx effect deps), and the host re-posts
+// config on every iframe load — an inline closure here would recycle the live
+// /stream session on each repost.
+const readToken = () => current?.token ?? null;
+
 function render() {
   if (!current) return;
   const el = document.getElementById("root")!;
@@ -23,15 +29,21 @@ function render() {
       templateId={current.templateId}
       userId={current.userId}
       conversationId={current.conversationId}
-      getAccessToken={() => current?.token ?? null}
+      // Only claim auth when the host actually sent a token. A fabricated accessor on a
+      // tokenless boot made the SDK skip its guest-id substitution (connection.tsx), so
+      // the session registered a non-guest id and the public-entry gate refused it.
+      // No token ⇒ no accessor ⇒ the SDK mints/persists `guest-<uuid>` per the contract
+      // (UNOVERSE_MCP_TEMPLATE_PROTOCOL §5, AUTH_TOKEN_FLOW Run Authorization).
+      getAccessToken={current.token ? readToken : undefined}
     />,
   );
 }
 
 function apply(cfg: HostConfig) {
-  const first = !current;
   current = { ...current, ...cfg };
-  if (first) render(); // mount once; token refresh just updates `current` (getAccessToken reads it)
+  // Re-render on every apply so a token appearing/disappearing takes effect; a same-token
+  // refresh changes nothing (readToken is stable, values equal), so no connection churn.
+  render();
 }
 
 declare global {