@guuey/chat 0.6.0 → 0.7.0

package/dist/plan.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"plan.d.ts","sourceRoot":"","sources":["../src/plan.ts"],"names":[],"mappings":"AAkCA,OAAO,EAAqD,KAAK,SAAS,EAAE,MAAM,sBAAsB,CAAC;AACzG,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAC;AAEpD,OAAO,KAAK,EASV,gBAAgB,EAChB,mBAAmB,EACnB,cAAc,EAIf,MAAM,YAAY,CAAC;AAslBpB,uCAAuC;AACvC,wBAAgB,cAAc,CAC5B,MAAM,EAAE,gBAAgB,EACxB,MAAM,EAAE,gBAAgB,EACxB,SAAS,GAAE,mBAAwB,GAClC,cAAc,CA0QhB;AAED;;;;;;;;;GASG;AACH,wBAAgB,aAAa,CAC3B,MAAM,EAAE,IAAI,CAAC,gBAAgB,EAAE,QAAQ,GAAG,cAAc,CAAC,GACxD;IAAE,GAAG,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,SAAS,CAAC,SAAS,CAAC,CAAA;CAAE,GAAG,SAAS,CAiB5D"}
+{"version":3,"file":"plan.d.ts","sourceRoot":"","sources":["../src/plan.ts"],"names":[],"mappings":"AAkCA,OAAO,EAKL,KAAK,SAAS,EACf,MAAM,sBAAsB,CAAC;AAC9B,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAC;AAEpD,OAAO,KAAK,EASV,gBAAgB,EAChB,mBAAmB,EACnB,cAAc,EAIf,MAAM,YAAY,CAAC;AAqmBpB,uCAAuC;AACvC,wBAAgB,cAAc,CAC5B,MAAM,EAAE,gBAAgB,EACxB,MAAM,EAAE,gBAAgB,EACxB,SAAS,GAAE,mBAAwB,GAClC,cAAc,CA0QhB;AAED;;;;;;;;;GASG;AACH,wBAAgB,aAAa,CAC3B,MAAM,EAAE,IAAI,CAAC,gBAAgB,EAAE,QAAQ,GAAG,cAAc,CAAC,GACxD;IAAE,GAAG,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,SAAS,CAAC,SAAS,CAAC,CAAA;CAAE,GAAG,SAAS,CAiB5D"}

package/dist/plan.js

@@ -1,4 +1,4 @@
-import { snapshotViewMount, toolResultViewMount, uiLocator } from "@guuey/mcp-apps-host";
+import { snapshotViewMount, toolResultLocator, toolResultViewMount, uiResourceChannel, } from "@guuey/mcp-apps-host";
 import { grantModeDisplay } from "./hitl.js";
 /** R5's giant threshold: above this byte count the state is `giant`. */
 const GIANT_RESULT_BYTES = 16_384;
@@ -164,6 +164,19 @@ function toolFailed(result) {
         return result.errorText !== undefined && result.errorText !== "";
     return false;
 }
+/**
+ * The sandbox-trust channel a view item will MOUNT on. For a resolved mount
+ * that is the mount's own channel; for the `"locator"` arm it is what the
+ * reader will assign at resolution — derived from the requested uri
+ * (`uiResourceChannel`), the same rule the reader itself applies. Since the
+ * ggui vendor arm retired (guuey#209) every live ggui card is a locator at
+ * plan time, so the channel-aware label must look through the arm.
+ */
+function trustChannel(item) {
+    if (item.mount === null)
+        return item.channel === "ggui" || item.channel === "inline" ? item.channel : null;
+    return item.mount.channel === "locator" ? uiResourceChannel(item.mount.resourceUri) : item.mount.channel;
+}
 function viewLabel(item, policy) {
     const s = policy.strings;
     switch (item.phase) {
@@ -176,7 +189,9 @@ function viewLabel(item, policy) {
         case "no-handshake":
             // Channel-aware (R6): a ggui shell that never handshakes is a boot
             // failure; inline tenant HTML may legitimately be a non-App document.
-            return item.channel === "ggui" ? s.viewBootFailure : s.viewInlineFallback;
+            // Keyed on the TRUST channel (locators resolve to it by uri), not the
+            // mount arm — a live ggui card is a locator until its read lands.
+            return trustChannel(item) === "ggui" ? s.viewBootFailure : s.viewInlineFallback;
     }
 }
 function unknownFromValue(key, typeName, value, policy, overrides) {
@@ -308,7 +323,7 @@ function planAssistantSource(source, slot, inputs, policy, overrides) {
                         // `result` is narrowed by `mount !== undefined` above; the scope
                         // is the PERSISTED locator (`uiData.resourceUri`), never the
                         // mount payload's own uri (synthetic for a ggui shell).
-                        actionScope: result ? (uiLocator(result.uiData) ?? null) : null,
+                        actionScope: result ? (toolResultLocator(result) ?? null) : null,
                     };
                     view.label = viewLabel(view, policy);
                     items.push(view);

package/dist/react/guuey-chat.d.ts

@@ -83,16 +83,48 @@ export interface GuueyChatHandle {
     }): void;
     /** Focus the composer input. */
     focusComposer(): void;
+    /**
+     * The CURRENT persisted thread id, or `null` before the first turn is
+     * admitted (it hydrates from storage on mount and from the pod's
+     * `session` frame on the first send). Read on demand — a live value, not
+     * a mount-time snapshot — so a host can key its own per-thread state
+     * without wrapping `adapters.storage`. For a push-style notification use
+     * {@link GuueyChatProps.onThread}.
+     */
+    readonly threadId: string | null;
 }
 export interface GuueyChatProps {
     /** Pod base URL (with or without `/agent/invoke`). `null` disables chat. */
     endpointUrl: string | null;
     /** Owning app id — namespaces the persisted threadId. */
     appId?: string;
+    /**
+     * The guuey public API base (`…/v1`). Enables the batteries-included
+     * read paths without hand-wiring: when set and no `adapters` are given,
+     * the default `createWebAdapters` gains transcript history; when set and
+     * no `reader` is given, a `UiResourceReader` is built over the same
+     * identity so generative-UI locators resolve (guuey#221 — a guest kit
+     * user has no bearer to construct one with). Explicit `adapters` /
+     * `reader` always win. Absent → today's behavior (no history, no
+     * default reader; locators render as expired, labeled).
+     */
+    apiBaseUrl?: string;
+    /**
+     * Identity for the default adapters + default reader — the same two
+     * resolvers `createWebAdapters` takes (bearer wins; guest secret next;
+     * neither → cookie identity). Ignored when explicit `adapters` and
+     * `reader` are both supplied.
+     */
+    getAccessToken?: (opts?: {
+        forceRefresh?: boolean;
+    }) => Promise<string | null>;
+    getGuestSecret?: () => string | null;
     /**
      * Host couplings (storage / id / transport / history). Default:
-     * `createWebAdapters()` — localStorage thread persistence + the web SSE
-     * transport (cookie/guest identity, saturation + cold-start retries).
+     * `createWebAdapters({ apiBaseUrl, getAccessToken, getGuestSecret })` —
+     * localStorage thread persistence + the web SSE transport (cookie/guest
+     * identity, saturation + cold-start retries), plus history when
+     * `apiBaseUrl` is set.
      */
     adapters?: AgentInvokeAdapters;
     /** Policy preset (spec §5). Default `"calm"`. */
@@ -107,7 +139,11 @@ export interface GuueyChatProps {
     mode?: ThemeMode;
     /** DOM windowing (§3.2). `false` renders everything. */
     window?: TranscriptWindowing | false;
-    /** R6 locator resolution (history cards). See `useTranscript`. */
+    /**
+     * R6 locator resolution (history cards + meta-less live renders). See
+     * `useTranscript`. Defaults from `apiBaseUrl` (+ `endpointUrl` for the
+     * pod door) when omitted; an explicit reader always wins.
+     */
     reader?: UiResourceReader;
     /** The debug sink (spec §5) — fires only under the debug policy. */
     onDebugEvent?: (event: ChatDebugEvent) => void;
@@ -135,6 +171,14 @@ export interface GuueyChatProps {
      * the same stable handle the ref receives.
      */
     onReady?: (handle: GuueyChatHandle) => void;
+    /**
+     * Fires with the thread id when it first hydrates and again whenever it
+     * changes to a DIFFERENT id (a new chat, a reset that starts a fresh
+     * thread). Never fires for `null`, and never re-fires for the same id
+     * across re-renders or StrictMode's remount cycle. Pair with
+     * {@link GuueyChatHandle.threadId} for the pull-style read.
+     */
+    onThread?: (threadId: string) => void;
     className?: string;
     style?: CSSProperties;
 }

package/dist/react/guuey-chat.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"guuey-chat.d.ts","sourceRoot":"","sources":["../../src/react/guuey-chat.tsx"],"names":[],"mappings":"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"}
+{"version":3,"file":"guuey-chat.d.ts","sourceRoot":"","sources":["../../src/react/guuey-chat.tsx"],"names":[],"mappings":"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"}

package/dist/react/guuey-chat.js

@@ -46,7 +46,7 @@ import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
  * native GuueyChat, so there is no native surface to put a handle on yet.
  */
 import { forwardRef, useCallback, useEffect, useImperativeHandle, useMemo, useRef, useState, } from "react";
-import { createWebAdapters } from "@guuey/agent-client";
+import { createUiResourceReader, createWebAdapters, } from "@guuey/agent-client";
 import { useAgentInvoke } from "@guuey/agent-client/react";
 import { calmPolicy, debugPolicy } from "../policy.js";
 import { defaultChatStrings } from "../strings.js";
@@ -59,9 +59,47 @@ const PROMPT_STATE = {
     dismiss: "dismissed",
 };
 export const GuueyChat = forwardRef(function GuueyChat(props, ref) {
-    const { endpointUrl, appId, adapters: adaptersProp, preset = "calm", policy: policyOverrides, components, strings: stringOverrides, theme = DEFAULT_CHAT_THEME, mode = "light", window: windowing, reader, onDebugEvent, viewProps, onPromptAction, onHitlAnswer, onErrorAction, onReady, className, style, } = props;
-    const adapters = useMemo(() => adaptersProp ?? createWebAdapters(), [adaptersProp]);
+    const { endpointUrl, appId, apiBaseUrl, getAccessToken, getGuestSecret, adapters: adaptersProp, preset = "calm", policy: policyOverrides, components, strings: stringOverrides, theme = DEFAULT_CHAT_THEME, mode = "light", window: windowing, reader, onDebugEvent, viewProps, onPromptAction, onHitlAnswer, onErrorAction, onReady, onThread, className, style, } = props;
+    const adapters = useMemo(() => adaptersProp ??
+        createWebAdapters({
+            ...(apiBaseUrl !== undefined ? { apiBaseUrl } : {}),
+            ...(getAccessToken !== undefined ? { getAccessToken } : {}),
+            ...(getGuestSecret !== undefined ? { getGuestSecret } : {}),
+        }), [adaptersProp, apiBaseUrl, getAccessToken, getGuestSecret]);
     const invoke = useAgentInvoke({ endpointUrl, ...(appId !== undefined ? { appId } : {}), adapters, preserveBlocks: true });
+    // Default reader (guuey#221): built over the SAME identity as the
+    // transport/history, targeting the pod door (live turns) then the
+    // platform door (persisted). The threadId hydrates after mount and can
+    // change on reset, so the reader is a stable function that reads the
+    // CURRENT thread through a ref — `useTranscript` sees one reader for the
+    // component's life and never re-resolves every mount on a thread flip.
+    const threadIdRef = useRef(invoke.threadId);
+    threadIdRef.current = invoke.threadId;
+    const defaultReader = useMemo(() => {
+        if (apiBaseUrl === undefined)
+            return undefined;
+        return async (resourceUri) => {
+            const threadId = threadIdRef.current;
+            // No thread yet ⇒ nothing persisted to scope a read to; a live-turn
+            // locator always arrives with the thread already admitted (the
+            // `session` frame precedes tool results).
+            if (threadId === null)
+                return undefined;
+            // Assembled per read: `createUiResourceReader` is a cheap closure, and
+            // the guest secret is re-resolved each call so a rotation takes
+            // effect immediately — the same per-request property
+            // `createWebAdapters` documents for its own resolvers.
+            const read = createUiResourceReader({
+                apiBaseUrl,
+                threadId,
+                endpointUrl,
+                ...(getAccessToken !== undefined ? { getAccessToken } : {}),
+                guestSecret: getGuestSecret ? getGuestSecret() : null,
+            });
+            return read(resourceUri);
+        };
+    }, [apiBaseUrl, endpointUrl, getAccessToken, getGuestSecret]);
+    const effectiveReader = reader ?? defaultReader;
     const policy = useMemo(() => {
         const factory = preset === "debug" ? debugPolicy : calmPolicy;
         const strings = {
@@ -75,7 +113,7 @@ export const GuueyChat = forwardRef(function GuueyChat(props, ref) {
     const { plan, toggle, resolvedMounts, onViewPhase } = useTranscript({
         inputs,
         policy,
-        ...(reader !== undefined ? { reader } : {}),
+        ...(effectiveReader !== undefined ? { reader: effectiveReader } : {}),
         ...(onDebugEvent !== undefined ? { onDebugEvent } : {}),
     });
     // ── Composer ─────────────────────────────────────────────────────────
@@ -115,8 +153,29 @@ export const GuueyChat = forwardRef(function GuueyChat(props, ref) {
         focusComposer: () => {
             inputRef.current?.focus();
         },
+        // A getter, not a captured value: the handle is created once, but the
+        // thread hydrates after mount and can change — reads go through the
+        // same ref the default reader uses, so it is always the live id.
+        get threadId() {
+            return threadIdRef.current;
+        },
     }), []);
     useImperativeHandle(ref, () => handle, [handle]);
+    // `onThread` fires on the first hydrated id and on each DISTINCT change —
+    // never for null, never twice for the same id (a StrictMode remount
+    // re-runs the effect with the same value; the last-notified ref absorbs
+    // it). Read the callback through the live ref so an inline arrow prop
+    // doesn't churn the effect.
+    const lastNotifiedThreadRef = useRef(null);
+    const onThreadRef = useRef(onThread);
+    onThreadRef.current = onThread;
+    useEffect(() => {
+        const id = invoke.threadId;
+        if (id === null || id === lastNotifiedThreadRef.current)
+            return;
+        lastNotifiedThreadRef.current = id;
+        onThreadRef.current?.(id);
+    }, [invoke.threadId]);
     // `onReady` fires once per instance, on mount, with the stable handle
     // (guarded ref: StrictMode's remount cycle must not double-fire it).
     const readyFiredRef = useRef(false);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@guuey/chat",
-  "version": "0.6.0",
+  "version": "0.7.0",
   "description": "The default end-user transcript UI for guuey agents — the headless view-model (planTranscript), calm/debug presets, the GuueyChatTheme token schema, the ChatStrings i18n seam, and (at ./react) the component kit that renders it: per-category components, <Transcript>, the live + history input assemblers, and stick-to-bottom/windowed/accessible transcript behavior; at ./native, the React Native renderer over the same view-model.",
   "license": "MIT",
   "type": "module",
@@ -39,8 +39,8 @@
     "@silverprotocol/core": "0.5.0",
     "@silverprotocol/richtext": "0.5.0",
     "zod": "^4.3.6",
-    "@guuey/agent-client": "0.6.0",
-    "@guuey/mcp-apps-host": "0.6.0"
+    "@guuey/agent-client": "0.7.0",
+    "@guuey/mcp-apps-host": "0.7.0"
   },
   "peerDependencies": {
     "react": ">=18",

package/src/corpus/README.md

@@ -44,7 +44,19 @@ witness.
   paths, labeled and never agent-voiced, provenance under debug only),
   and family 22 (`promoted-view` — guuey#204 "promote and reference": the
   one mount a host stage shows chips via `promotedViewKey`, every other
-  mount stays full, no/stale key is byte-identical to today).
+  mount stays full, no/stale key is byte-identical to today), and family
+  23 (`meta-less-locator` — guuey#209 route-A: a `_meta`-withholding
+  producer's `ui://` locator rides `structuredContent` (AgJSON §2.1 model-
+  channel routing) and STILL mounts as a locator — before this it rendered
+  nothing at all, the corpus's first "dark, not degraded" shape), and
+  family 24 (`prod-wire-ggui-render` — the vendor arm's retirement,
+  guuey#209: the EXACT shape ggui's read-plane-only PRODUCTION posture
+  emits (no `_meta`, no `uiData`, a `structuredContent` locator), planned as
+  a locator and RESOLVED through the kit's real reader assembly over a
+  C2-shaped read shell (`gguiReadShell`) to the `"ggui"` channel — the
+  whole converged path in plain Node; 24c pins that a bootstrap-carrying
+  result (fixture 7's shape) rides the same arm to the same outcome, and
+  family 18's production capture asserts the same).
 - `capture.ts` / `captures/` — family 18: production-capture replay
   through the real `invokeTurn` (provenance in the module header).
 - `corpus.test.ts` — the runner: per-fixture assertions + snapshots, plain

package/src/corpus/__snapshots__/corpus.test.ts.snap

@@ -1115,23 +1115,14 @@ exports[`corpus > 7. view-never-handshakes — channel-aware labels on both chan
     {
       "actionScope": "ui://ggui/render/render_00000000-0000-4000-8000-300000000001/c0ffee",
       "attribution": "via ggui render",
-      "channel": "ggui",
+      "channel": "locator",
       "expanded": true,
       "key": "view.tGgui",
       "kind": "view",
       "label": "This view couldn't start",
       "mount": {
-        "channel": "ggui",
-        "resource": {
-          "mimeType": "text/html",
-          "text": "<!doctype html>
-<html lang="en" style="background:transparent"><head><meta charset="utf-8"><meta name="viewport" content="width=device-width, initial-scale=1"><meta name="color-scheme" content="light dark"><title>ggui render</title></head>
-<body style="margin:0;background:transparent">
-<script>globalThis.__GGUI_META__ = {"ai.ggui/render":{"sessionId":"render_00000000-0000-4000-8000-300000000001","appId":"APP00000","runtimeUrl":"https://dev.mcp.sandbox.ggui.ai/_ggui/iframe-runtime.js","wsUrl":"wss://dev.mcp.sandbox.ggui.ai/ws","wsToken":"eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.e30.AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA","expiresAt":"2026-07-29T11:07:58.000Z","lastSequence":0,"propsJson":"{}"}};</script>
-<script type="module" crossorigin="anonymous" src="https://dev.mcp.sandbox.ggui.ai/_ggui/iframe-runtime.js"></script>
-</body></html>",
-          "uri": "ui://ggui/render/render_00000000-0000-4000-8000-300000000001/c0ffee",
-        },
+        "channel": "locator",
+        "resourceUri": "ui://ggui/render/render_00000000-0000-4000-8000-300000000001/c0ffee",
       },
       "phase": "no-handshake",
       "toolTitle": "ggui render",
@@ -1641,23 +1632,14 @@ exports[`corpus > 19. persisted-plus-live — the fold owns its trailing turns;
     {
       "actionScope": "ui://ggui/render/render_00000000-0000-4000-8000-300000000001/c0ffee",
       "attribution": "via ggui render",
-      "channel": "ggui",
+      "channel": "locator",
       "expanded": true,
       "key": "view.tA",
       "kind": "view",
       "label": "Loading view…",
       "mount": {
-        "channel": "ggui",
-        "resource": {
-          "mimeType": "text/html",
-          "text": "<!doctype html>
-<html lang="en" style="background:transparent"><head><meta charset="utf-8"><meta name="viewport" content="width=device-width, initial-scale=1"><meta name="color-scheme" content="light dark"><title>ggui render</title></head>
-<body style="margin:0;background:transparent">
-<script>globalThis.__GGUI_META__ = {"ai.ggui/render":{"sessionId":"render_00000000-0000-4000-8000-300000000001","appId":"APP00000","runtimeUrl":"https://dev.mcp.sandbox.ggui.ai/_ggui/iframe-runtime.js","wsUrl":"wss://dev.mcp.sandbox.ggui.ai/ws","wsToken":"eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.e30.AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA","expiresAt":"2026-07-29T11:07:58.000Z","lastSequence":0,"propsJson":"{}"}};</script>
-<script type="module" crossorigin="anonymous" src="https://dev.mcp.sandbox.ggui.ai/_ggui/iframe-runtime.js"></script>
-</body></html>",
-          "uri": "ui://ggui/render/render_00000000-0000-4000-8000-300000000001/c0ffee",
-        },
+        "channel": "locator",
+        "resourceUri": "ui://ggui/render/render_00000000-0000-4000-8000-300000000001/c0ffee",
       },
       "phase": "negotiating",
       "toolTitle": "ggui render",
@@ -1892,3 +1874,100 @@ exports[`corpus > 22. promoted-view — the stage's mount chips (guuey#204); oth
   "status": null,
 }
 `;
+
+exports[`corpus > 23. meta-less-locator — a \`_meta\`-withholding producer's render still mounts (as a locator), never dark (guuey#209) 1`] = `
+{
+  "items": [
+    {
+      "expanded": true,
+      "key": "u0",
+      "kind": "user",
+      "retry": false,
+      "state": "sent",
+      "text": "render a slot picker",
+    },
+    {
+      "argsPreview": null,
+      "attribution": true,
+      "expanded": false,
+      "key": "tool.t1",
+      "kind": "tool",
+      "name": "ggui_render",
+      "result": null,
+      "state": "done",
+      "title": "ggui render",
+      "toolCallId": "t1",
+    },
+    {
+      "actionScope": "ui://ggui/render/render_dark/h1",
+      "attribution": "via ggui render",
+      "channel": "locator",
+      "expanded": true,
+      "key": "view.t1",
+      "kind": "view",
+      "label": "Loading view…",
+      "mount": {
+        "channel": "locator",
+        "resourceUri": "ui://ggui/render/render_dark/h1",
+      },
+      "phase": "negotiating",
+      "toolTitle": "ggui render",
+    },
+  ],
+  "recovery": null,
+  "status": null,
+}
+`;
+
+exports[`corpus > 24. prod-wire-ggui-render — ggui's production posture: no _meta, no uiData, a structuredContent locator → mounts as a locator (guuey#209) 1`] = `
+{
+  "items": [
+    {
+      "expanded": true,
+      "key": "u0",
+      "kind": "user",
+      "retry": false,
+      "state": "sent",
+      "text": "show me the board",
+    },
+    {
+      "argsPreview": null,
+      "attribution": true,
+      "expanded": false,
+      "key": "tool.t1",
+      "kind": "tool",
+      "name": "ggui_render",
+      "result": null,
+      "state": "done",
+      "title": "ggui render",
+      "toolCallId": "t1",
+    },
+    {
+      "actionScope": "ui://ggui/render/render_5d11b1b4-75ba-44e5-81bb-0b420b86bb8e/7328555b44e72bd7",
+      "attribution": "via ggui render",
+      "channel": "locator",
+      "expanded": true,
+      "key": "view.t1",
+      "kind": "view",
+      "label": "Loading view…",
+      "mount": {
+        "channel": "locator",
+        "resourceUri": "ui://ggui/render/render_5d11b1b4-75ba-44e5-81bb-0b420b86bb8e/7328555b44e72bd7",
+      },
+      "phase": "negotiating",
+      "toolTitle": "ggui render",
+    },
+    {
+      "expanded": true,
+      "key": "a0.t0",
+      "kind": "text",
+      "markdown": true,
+      "stopped": false,
+      "streaming": false,
+      "text": "Here is your board.",
+    },
+  ],
+  "recovery": null,
+  "status": null,
+}
+`;

package/src/corpus/fixtures.ts

@@ -24,7 +24,7 @@ import {
 
 // The ggui render shapes below mirror mcp-apps-host's own capture-derived
 // test fixtures (synthetic ids, production shape — ggui-render.test.ts).
-const GGUI_RESOURCE_URI = "ui://ggui/render/render_00000000-0000-4000-8000-300000000001/c0ffee";
+export const GGUI_RESOURCE_URI = "ui://ggui/render/render_00000000-0000-4000-8000-300000000001/c0ffee";
 const GGUI_META_KEY = "ai.ggui/render";
 const GGUI_SLICE = {
   sessionId: "render_00000000-0000-4000-8000-300000000001",
@@ -555,3 +555,99 @@ export function promotedView(): { inputs: TranscriptInputs; promotedKey: string
   const inputs = driveTurn(events, { userText: "show me two cards" });
   return { inputs, promotedKey: "view.t2" };
 }
+
+/**
+ * 23. meta-less-locator — guuey#209 route-A finding: a producer that
+ * withholds tool-result `_meta` (ggui's non-prod posture; any plain-locator
+ * MCP server) yields a fold block with NO uiData and NO _meta — AgJSON §2.1
+ * routes the sibling structuredContent to the MODEL channel — and the
+ * `ui://` locator rides `structuredContent.resourceUri`. Wire keys per the
+ * 2026-08-16 dev dump: type,toolCallId,content,outcome,isError,
+ * structuredContent. Before #209 this rendered NOTHING (dark, not
+ * "expired") and persisted no placeholder row.
+ */
+export function metaLessLocator(): TranscriptInputs {
+  const s = seqSource();
+  const events: InvokeTurnEvent[] = [
+    session,
+    frame(boot(s), { status: "thinking" }),
+    frame(
+      toolPart(s, "t1", "ggui_render", {
+        content: [{ type: "text", text: "rendered" }],
+        outcome: "ok",
+        isError: false,
+        structuredContent: { resourceUri: "ui://ggui/render/render_dark/h1", sessionId: "render_dark" },
+      }),
+      { status: "using-tool", activeTool: "ggui_render" },
+    ),
+    doneEvent,
+  ];
+  return driveTurn(events, { userText: "render a slot picker" });
+}
+
+/**
+ * 24. prod-wire-ggui-render — the EXACT shape ggui's read-plane-only PRODUCTION
+ * posture emits (guuey#209 prod probe, 2026-08-16): a `ggui_render` tool.done
+ * with NO `_meta["ai.ggui/render"]`, NO `uiData`, only
+ * `structuredContent.resourceUri = ui://ggui/render/<renderId>/<hash>`. The
+ * vendor arm is retired: this mounts as a LOCATOR, and the "ggui" trust
+ * channel is assigned at RESOLUTION from the uri — the corpus resolves it
+ * through the kit's real reader assembly over a C2-shaped read shell
+ * ({@link gguiReadShell}) to prove the whole converged path in plain Node.
+ */
+export const PROD_WIRE_RENDER_URI =
+  "ui://ggui/render/render_5d11b1b4-75ba-44e5-81bb-0b420b86bb8e/7328555b44e72bd7";
+export const PROD_WIRE_RUNTIME_URL = "https://mcp.ggui.ai/_ggui/iframe-runtime.js";
+export const PROD_WIRE_WS_URL = "wss://mcp.ggui.ai/ws";
+
+export function prodWireGguiRender(): TranscriptInputs {
+  const s = seqSource();
+  const events: InvokeTurnEvent[] = [
+    session,
+    frame(boot(s), { status: "thinking" }),
+    frame(
+      toolPart(s, "t1", "ggui_render", {
+        content: [{ type: "text", text: PROD_WIRE_RENDER_URI }],
+        outcome: "ok",
+        isError: false,
+        structuredContent: {
+          resourceUri: PROD_WIRE_RENDER_URI,
+          sessionId: "render_5d11b1b4-75ba-44e5-81bb-0b420b86bb8e",
+        },
+      }),
+      { status: "using-tool", activeTool: "ggui_render" },
+    ),
+    frame(textPart(s, "x", "Here is your board."), {
+      status: "responding",
+      activeTool: null,
+      text: "Here is your board.",
+    }),
+    doneEvent,
+  ];
+  return driveTurn(events, { userText: "show me the board" });
+}
+
+/**
+ * What ggui's `resources/read` answers for a render locator (guuey#209 C2):
+ * the shell that boots ggui's runtime with the live-channel material
+ * (`wsUrl`, a `wsToken` minted FRESH at read time, `expiresAt`) inlined as
+ * `__GGUI_META__` — the same envelope the retired bootstrap arm used to get
+ * on the tool result, now younger than any inlined copy could be.
+ */
+export function gguiReadShell(opts: { runtimeUrl: string; wsUrl: string }): string {
+  const meta = {
+    "ai.ggui/render": {
+      runtimeUrl: opts.runtimeUrl,
+      wsUrl: opts.wsUrl,
+      wsToken: "minted-fresh-at-read",
+      expiresAt: "2026-08-16T00:03:00.000Z",
+    },
+  };
+  return (
+    `<!doctype html><html><head><meta charset="utf-8">` +
+    `<script>globalThis.__GGUI_META__ = ${JSON.stringify(meta)};</script>` +
+    `<script type="module" crossorigin="anonymous" src="${opts.runtimeUrl}"></script>` +
+    `</head><body style="margin:0;background:transparent"></body></html>`
+  );
+}
+

package/src/plan.ts

@@ -32,7 +32,13 @@
  * append ordinals, so every existing key survives each re-plan.
  */
 import type { AgBlock, AgReduceResult, JsonValue } from "@silverprotocol/core";
-import { snapshotViewMount, toolResultViewMount, uiLocator, type ViewMount } from "@guuey/mcp-apps-host";
+import {
+  snapshotViewMount,
+  toolResultLocator,
+  toolResultViewMount,
+  uiResourceChannel,
+  type ViewMount,
+} from "@guuey/mcp-apps-host";
 import type { TranscriptPolicy } from "./policy.js";
 import { grantModeDisplay } from "./hitl.js";
 import type {
@@ -252,8 +258,21 @@ function toolFailed(result: ToolResultBlock): boolean {
   return false;
 }
 
+/**
+ * The sandbox-trust channel a view item will MOUNT on. For a resolved mount
+ * that is the mount's own channel; for the `"locator"` arm it is what the
+ * reader will assign at resolution — derived from the requested uri
+ * (`uiResourceChannel`), the same rule the reader itself applies. Since the
+ * ggui vendor arm retired (guuey#209) every live ggui card is a locator at
+ * plan time, so the channel-aware label must look through the arm.
+ */
+function trustChannel(item: Pick<ViewMountItem, "mount" | "channel">): "inline" | "ggui" | null {
+  if (item.mount === null) return item.channel === "ggui" || item.channel === "inline" ? item.channel : null;
+  return item.mount.channel === "locator" ? uiResourceChannel(item.mount.resourceUri) : item.mount.channel;
+}
+
 function viewLabel(
-  item: Pick<ViewMountItem, "phase" | "channel">,
+  item: Pick<ViewMountItem, "phase" | "channel" | "mount">,
   policy: TranscriptPolicy,
 ): string | null {
   const s = policy.strings;
@@ -267,7 +286,9 @@ function viewLabel(
     case "no-handshake":
       // Channel-aware (R6): a ggui shell that never handshakes is a boot
       // failure; inline tenant HTML may legitimately be a non-App document.
-      return item.channel === "ggui" ? s.viewBootFailure : s.viewInlineFallback;
+      // Keyed on the TRUST channel (locators resolve to it by uri), not the
+      // mount arm — a live ggui card is a locator until its read lands.
+      return trustChannel(item) === "ggui" ? s.viewBootFailure : s.viewInlineFallback;
   }
 }
 
@@ -411,7 +432,7 @@ function planAssistantSource(
             // `result` is narrowed by `mount !== undefined` above; the scope
             // is the PERSISTED locator (`uiData.resourceUri`), never the
             // mount payload's own uri (synthetic for a ggui shell).
-            actionScope: result ? (uiLocator(result.uiData) ?? null) : null,
+            actionScope: result ? (toolResultLocator(result) ?? null) : null,
           };
           view.label = viewLabel(view, policy);
           items.push(view);

package/src/react/guuey-chat.tsx

@@ -55,7 +55,11 @@ import {
   type CSSProperties,
   type ReactNode,
 } from "react";
-import { createWebAdapters, type AgentInvokeAdapters } from "@guuey/agent-client";
+import {
+  createUiResourceReader,
+  createWebAdapters,
+  type AgentInvokeAdapters,
+} from "@guuey/agent-client";
 import type { AgHitlAnswer, AgPausedAsk } from "@silverprotocol/core";
 import { useAgentInvoke } from "@guuey/agent-client/react";
 import type { UiResourceReader } from "@guuey/mcp-apps-host";
@@ -93,6 +97,15 @@ export interface GuueyChatHandle {
   prefill(text: string, opts?: { focus?: boolean; append?: boolean }): void;
   /** Focus the composer input. */
   focusComposer(): void;
+  /**
+   * The CURRENT persisted thread id, or `null` before the first turn is
+   * admitted (it hydrates from storage on mount and from the pod's
+   * `session` frame on the first send). Read on demand — a live value, not
+   * a mount-time snapshot — so a host can key its own per-thread state
+   * without wrapping `adapters.storage`. For a push-style notification use
+   * {@link GuueyChatProps.onThread}.
+   */
+  readonly threadId: string | null;
 }
 
 export interface GuueyChatProps {
@@ -100,10 +113,31 @@ export interface GuueyChatProps {
   endpointUrl: string | null;
   /** Owning app id — namespaces the persisted threadId. */
   appId?: string;
+  /**
+   * The guuey public API base (`…/v1`). Enables the batteries-included
+   * read paths without hand-wiring: when set and no `adapters` are given,
+   * the default `createWebAdapters` gains transcript history; when set and
+   * no `reader` is given, a `UiResourceReader` is built over the same
+   * identity so generative-UI locators resolve (guuey#221 — a guest kit
+   * user has no bearer to construct one with). Explicit `adapters` /
+   * `reader` always win. Absent → today's behavior (no history, no
+   * default reader; locators render as expired, labeled).
+   */
+  apiBaseUrl?: string;
+  /**
+   * Identity for the default adapters + default reader — the same two
+   * resolvers `createWebAdapters` takes (bearer wins; guest secret next;
+   * neither → cookie identity). Ignored when explicit `adapters` and
+   * `reader` are both supplied.
+   */
+  getAccessToken?: (opts?: { forceRefresh?: boolean }) => Promise<string | null>;
+  getGuestSecret?: () => string | null;
   /**
    * Host couplings (storage / id / transport / history). Default:
-   * `createWebAdapters()` — localStorage thread persistence + the web SSE
-   * transport (cookie/guest identity, saturation + cold-start retries).
+   * `createWebAdapters({ apiBaseUrl, getAccessToken, getGuestSecret })` —
+   * localStorage thread persistence + the web SSE transport (cookie/guest
+   * identity, saturation + cold-start retries), plus history when
+   * `apiBaseUrl` is set.
    */
   adapters?: AgentInvokeAdapters;
   /** Policy preset (spec §5). Default `"calm"`. */
@@ -118,7 +152,11 @@ export interface GuueyChatProps {
   mode?: ThemeMode;
   /** DOM windowing (§3.2). `false` renders everything. */
   window?: TranscriptWindowing | false;
-  /** R6 locator resolution (history cards). See `useTranscript`. */
+  /**
+   * R6 locator resolution (history cards + meta-less live renders). See
+   * `useTranscript`. Defaults from `apiBaseUrl` (+ `endpointUrl` for the
+   * pod door) when omitted; an explicit reader always wins.
+   */
   reader?: UiResourceReader;
   /** The debug sink (spec §5) — fires only under the debug policy. */
   onDebugEvent?: (event: ChatDebugEvent) => void;
@@ -147,6 +185,14 @@ export interface GuueyChatProps {
    * the same stable handle the ref receives.
    */
   onReady?: (handle: GuueyChatHandle) => void;
+  /**
+   * Fires with the thread id when it first hydrates and again whenever it
+   * changes to a DIFFERENT id (a new chat, a reset that starts a fresh
+   * thread). Never fires for `null`, and never re-fires for the same id
+   * across re-renders or StrictMode's remount cycle. Pair with
+   * {@link GuueyChatHandle.threadId} for the pull-style read.
+   */
+  onThread?: (threadId: string) => void;
   className?: string;
   style?: CSSProperties;
 }
@@ -164,6 +210,9 @@ export const GuueyChat = forwardRef<GuueyChatHandle, GuueyChatProps>(function Gu
   const {
     endpointUrl,
     appId,
+    apiBaseUrl,
+    getAccessToken,
+    getGuestSecret,
     adapters: adaptersProp,
     preset = "calm",
     policy: policyOverrides,
@@ -179,13 +228,55 @@ export const GuueyChat = forwardRef<GuueyChatHandle, GuueyChatProps>(function Gu
     onHitlAnswer,
     onErrorAction,
     onReady,
+    onThread,
     className,
     style,
   } = props;
 
-  const adapters = useMemo(() => adaptersProp ?? createWebAdapters(), [adaptersProp]);
+  const adapters = useMemo(
+    () =>
+      adaptersProp ??
+      createWebAdapters({
+        ...(apiBaseUrl !== undefined ? { apiBaseUrl } : {}),
+        ...(getAccessToken !== undefined ? { getAccessToken } : {}),
+        ...(getGuestSecret !== undefined ? { getGuestSecret } : {}),
+      }),
+    [adaptersProp, apiBaseUrl, getAccessToken, getGuestSecret],
+  );
   const invoke = useAgentInvoke({ endpointUrl, ...(appId !== undefined ? { appId } : {}), adapters, preserveBlocks: true });
 
+  // Default reader (guuey#221): built over the SAME identity as the
+  // transport/history, targeting the pod door (live turns) then the
+  // platform door (persisted). The threadId hydrates after mount and can
+  // change on reset, so the reader is a stable function that reads the
+  // CURRENT thread through a ref — `useTranscript` sees one reader for the
+  // component's life and never re-resolves every mount on a thread flip.
+  const threadIdRef = useRef<string | null>(invoke.threadId);
+  threadIdRef.current = invoke.threadId;
+  const defaultReader = useMemo<UiResourceReader | undefined>(() => {
+    if (apiBaseUrl === undefined) return undefined;
+    return async (resourceUri: string) => {
+      const threadId = threadIdRef.current;
+      // No thread yet ⇒ nothing persisted to scope a read to; a live-turn
+      // locator always arrives with the thread already admitted (the
+      // `session` frame precedes tool results).
+      if (threadId === null) return undefined;
+      // Assembled per read: `createUiResourceReader` is a cheap closure, and
+      // the guest secret is re-resolved each call so a rotation takes
+      // effect immediately — the same per-request property
+      // `createWebAdapters` documents for its own resolvers.
+      const read = createUiResourceReader({
+        apiBaseUrl,
+        threadId,
+        endpointUrl,
+        ...(getAccessToken !== undefined ? { getAccessToken } : {}),
+        guestSecret: getGuestSecret ? getGuestSecret() : null,
+      });
+      return read(resourceUri);
+    };
+  }, [apiBaseUrl, endpointUrl, getAccessToken, getGuestSecret]);
+  const effectiveReader = reader ?? defaultReader;
+
   const policy = useMemo(() => {
     const factory = preset === "debug" ? debugPolicy : calmPolicy;
     const strings: ChatStrings = {
@@ -200,7 +291,7 @@ export const GuueyChat = forwardRef<GuueyChatHandle, GuueyChatProps>(function Gu
   const { plan, toggle, resolvedMounts, onViewPhase } = useTranscript({
     inputs,
     policy,
-    ...(reader !== undefined ? { reader } : {}),
+    ...(effectiveReader !== undefined ? { reader: effectiveReader } : {}),
     ...(onDebugEvent !== undefined ? { onDebugEvent } : {}),
   });
 
@@ -243,12 +334,33 @@ export const GuueyChat = forwardRef<GuueyChatHandle, GuueyChatProps>(function Gu
       focusComposer: (): void => {
         inputRef.current?.focus();
       },
+      // A getter, not a captured value: the handle is created once, but the
+      // thread hydrates after mount and can change — reads go through the
+      // same ref the default reader uses, so it is always the live id.
+      get threadId(): string | null {
+        return threadIdRef.current;
+      },
     }),
     [],
   );
 
   useImperativeHandle(ref, () => handle, [handle]);
 
+  // `onThread` fires on the first hydrated id and on each DISTINCT change —
+  // never for null, never twice for the same id (a StrictMode remount
+  // re-runs the effect with the same value; the last-notified ref absorbs
+  // it). Read the callback through the live ref so an inline arrow prop
+  // doesn't churn the effect.
+  const lastNotifiedThreadRef = useRef<string | null>(null);
+  const onThreadRef = useRef(onThread);
+  onThreadRef.current = onThread;
+  useEffect(() => {
+    const id = invoke.threadId;
+    if (id === null || id === lastNotifiedThreadRef.current) return;
+    lastNotifiedThreadRef.current = id;
+    onThreadRef.current?.(id);
+  }, [invoke.threadId]);
+
   // `onReady` fires once per instance, on mount, with the stable handle
   // (guarded ref: StrictMode's remount cycle must not double-fire it).
   const readyFiredRef = useRef(false);