@guuey/chat 0.9.0 → 0.11.0

package/src/react/guuey-chat.tsx

@@ -48,6 +48,7 @@ import {
   forwardRef,
   useCallback,
   useEffect,
+  useId,
   useImperativeHandle,
   useMemo,
   useRef,
@@ -64,9 +65,17 @@ import type { AgHitlAnswer, AgPausedAsk } from "@silverprotocol/core";
 import { useAgentInvoke } from "@guuey/agent-client/react";
 import type { UiResourceReader } from "@guuey/mcp-apps-host";
 import { calmPolicy, debugPolicy, type TranscriptPolicy } from "../policy.js";
+import { useStructuralIdentity } from "./structural-identity.js";
 import { defaultChatStrings, type ChatStrings } from "../strings.js";
 import { DEFAULT_CHAT_THEME, type GuueyChatTheme } from "../theme.js";
-import type { ChatDebugEvent, ErrorItem, PromptItem, UserMessageItem } from "../types.js";
+import type {
+  ChatDebugEvent,
+  ErrorItem,
+  PlanViewSummary,
+  PromptItem,
+  UserMessageItem,
+  ViewRefItem,
+} from "../types.js";
 import type { ThemeMode } from "./theme-css.js";
 import { Transcript, type TranscriptWindowing } from "./transcript.js";
 import type { TranscriptComponents, TranscriptItemContext } from "./components.js";
@@ -208,6 +217,19 @@ export interface GuueyChatProps {
    * {@link GuueyChatHandle.threadId} for the pull-style read.
    */
   onThread?: (threadId: string) => void;
+  /**
+   * guuey#301's host-stage trio (all optional; absent = today's inline
+   * behavior). `promotedViewKey` = the mount key the host's stage/canvas
+   * currently shows (chips it in the transcript — with
+   * `policy.view.presentation: "chips"` EVERY view chips and this key
+   * marks the selected one). `onViewRef` fires on chip click — set the
+   * key from it for the browser-history mechanic. `onViewsChange`
+   * delivers the plan's view roster (key/title/phase/channel/mount) so
+   * the host can render the selected mount with `<GuueyView>`.
+   */
+  promotedViewKey?: string;
+  onViewRef?: (item: ViewRefItem) => void;
+  onViewsChange?: (views: PlanViewSummary[]) => void;
   className?: string;
   style?: CSSProperties;
 }
@@ -239,6 +261,9 @@ export const GuueyChat = forwardRef<GuueyChatHandle, GuueyChatProps>(function Gu
     reader,
     onDebugEvent,
     viewProps,
+    promotedViewKey,
+    onViewRef,
+    onViewsChange,
     onPromptAction,
     onHitlAnswer,
     oauthReturnTo,
@@ -250,15 +275,37 @@ export const GuueyChat = forwardRef<GuueyChatHandle, GuueyChatProps>(function Gu
     style,
   } = props;
 
+  // Identity stabilization (guuey#303 QA — the template's own chat-rail
+  // shipped the failure): hosts pass inline literals and arrows, so prop
+  // IDENTITY is noise. The getter props route through refs (presence, not
+  // identity, is the re-mint trigger — flipping guest↔bearer is a real
+  // change; a fresh arrow per render is not), and the policy/strings
+  // overrides stabilize structurally below. Without this, every host
+  // re-render re-minted the plan, whose views-emission effect calls the
+  // host back → setState → re-render → "Maximum update depth exceeded".
+  const getAccessTokenRef = useRef(getAccessToken);
+  getAccessTokenRef.current = getAccessToken;
+  const getGuestSecretRef = useRef(getGuestSecret);
+  getGuestSecretRef.current = getGuestSecret;
+  const hasAccessToken = getAccessToken !== undefined;
+  const hasGuestSecret = getGuestSecret !== undefined;
+
   const adapters = useMemo(
     () =>
       adaptersProp ??
       createWebAdapters({
         ...(apiBaseUrl !== undefined ? { apiBaseUrl } : {}),
-        ...(getAccessToken !== undefined ? { getAccessToken } : {}),
-        ...(getGuestSecret !== undefined ? { getGuestSecret } : {}),
+        ...(hasAccessToken
+          ? {
+              getAccessToken: (opts?: { forceRefresh?: boolean }) =>
+                getAccessTokenRef.current?.(opts) ?? Promise.resolve(null),
+            }
+          : {}),
+        ...(hasGuestSecret
+          ? { getGuestSecret: () => getGuestSecretRef.current?.() ?? null }
+          : {}),
       }),
-    [adaptersProp, apiBaseUrl, getAccessToken, getGuestSecret],
+    [adaptersProp, apiBaseUrl, hasAccessToken, hasGuestSecret],
   );
   const invoke = useAgentInvoke({ endpointUrl, ...(appId !== undefined ? { appId } : {}), adapters, preserveBlocks: true });
 
@@ -282,39 +329,80 @@ export const GuueyChat = forwardRef<GuueyChatHandle, GuueyChatProps>(function Gu
       // 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.
+      // Getters read through the refs at CALL time — the reader's identity
+      // survives a host re-render handing in fresh arrows, and a rotated
+      // getter takes effect on the next read (the same per-request property
+      // `createWebAdapters` documents).
+      const getToken = getAccessTokenRef.current;
+      const getGuest = getGuestSecretRef.current;
       const read = createUiResourceReader({
         apiBaseUrl,
         threadId,
         endpointUrl,
-        ...(getAccessToken !== undefined ? { getAccessToken } : {}),
-        guestSecret: getGuestSecret ? getGuestSecret() : null,
+        ...(getToken !== undefined ? { getAccessToken: getToken } : {}),
+        guestSecret: getGuest !== undefined ? getGuest() : null,
       });
       return read(resourceUri);
     };
-  }, [apiBaseUrl, endpointUrl, getAccessToken, getGuestSecret]);
+  }, [apiBaseUrl, endpointUrl]);
   const effectiveReader = reader ?? defaultReader;
 
+  // Structurally-stable overrides: `policy={{ view: { … } }}` inline
+  // literals keep ONE identity while their contents hold still, so the
+  // policy (and through it the plan) does not re-mint per host render.
+  const stablePolicyOverrides = useStructuralIdentity(policyOverrides);
+  const stableStringOverrides = useStructuralIdentity(stringOverrides);
   const policy = useMemo(() => {
     const factory = preset === "debug" ? debugPolicy : calmPolicy;
     const strings: ChatStrings = {
       ...defaultChatStrings,
-      ...policyOverrides?.strings,
-      ...stringOverrides,
+      ...stablePolicyOverrides?.strings,
+      ...stableStringOverrides,
     };
-    return factory({ ...policyOverrides, strings });
-  }, [preset, policyOverrides, stringOverrides]);
+    return factory({ ...stablePolicyOverrides, strings });
+  }, [preset, stablePolicyOverrides, stableStringOverrides]);
 
   const { inputs, resolvePrompt, answerHitlPrompt } = useTranscriptInputs(invoke);
+  // Memoized: once a chip is selected (`promotedViewKey` set) this object
+  // is on the plan's identity path — a per-render fresh spread here was the
+  // second leg of the render loop the template surfaced.
+  const transcriptInputs = useMemo(
+    () => (promotedViewKey !== undefined ? { ...inputs, promotedViewKey } : inputs),
+    [inputs, promotedViewKey],
+  );
   const { plan, toggle, resolvedMounts, onViewPhase, onViewDiagnosis } = useTranscript({
-    inputs,
+    inputs: transcriptInputs,
     policy,
     ...(effectiveReader !== undefined ? { reader: effectiveReader } : {}),
     ...(onDebugEvent !== undefined ? { onDebugEvent } : {}),
   });
 
+  // guuey#301: hand the host the plan's view roster whenever it changes —
+  // the stage renders the selected mount from it. Locator entries carry
+  // the RESOLUTION overlay (a stage mounts material, not identities):
+  // resolved material replaces the locator mount, a failed read surfaces
+  // as the expired phase. Ref'd callback so a host passing a fresh
+  // closure each render doesn't loop the effect.
+  const onViewsChangeRef = useRef(onViewsChange);
+  onViewsChangeRef.current = onViewsChange;
+  useEffect(() => {
+    if (onViewsChangeRef.current === undefined) return;
+    const overlaid = plan.views.map((view) => {
+      const resolved = resolvedMounts.get(view.key);
+      if (resolved === undefined) return view;
+      if (resolved === "expired") return { ...view, phase: "expired" as const };
+      return { ...view, mount: resolved };
+    });
+    onViewsChangeRef.current(overlaid);
+  }, [plan.views, resolvedMounts]);
+
   // ── Composer ─────────────────────────────────────────────────────────
   const [input, setInput] = useState("");
   const inputRef = useRef<HTMLTextAreaElement | null>(null);
+  // Browser form-field heuristics (a11y/autofill lints) flag a field with
+  // neither id nor name on every embedding site. useId keeps the id unique
+  // when several chats mount on one page — a static id would collide.
+  const composerId = useId();
   const busy = invoke.status !== "ready";
   const available = endpointUrl !== null;
   const canSend = available && !busy && input.trim() !== "";
@@ -463,6 +551,7 @@ export const GuueyChat = forwardRef<GuueyChatHandle, GuueyChatProps>(function Gu
         resolvedMounts={resolvedMounts}
         onViewPhase={onViewPhase}
         onViewDiagnosis={onViewDiagnosis}
+        {...(onViewRef !== undefined ? { onViewRef } : {})}
         {...(viewProps !== undefined ? { viewProps } : {})}
       />
       {oauthReturn.notice !== null && (
@@ -487,6 +576,8 @@ export const GuueyChat = forwardRef<GuueyChatHandle, GuueyChatProps>(function Gu
       >
         <textarea
           ref={inputRef}
+          id={composerId}
+          name="message"
           className="guuey-chat-composer-input"
           rows={1}
           value={input}

package/src/react/structural-identity.ts

@@ -0,0 +1,47 @@
+/**
+ * Identity stabilization for host-supplied prop OBJECTS (guuey#303 QA).
+ *
+ * Hosts write `<GuueyChat policy={{ view: { presentation: "chips" } }}>` —
+ * a fresh object identity every render. Anything memo-keyed on that
+ * identity would re-mint per render, and anything the re-mint feeds into a
+ * `useEffect` → host `setState` edge becomes an infinite render loop (the
+ * template's chat-rail shipped exactly that). Identity is not a contract
+ * hosts signed up for; structure is.
+ *
+ * `useStructuralIdentity` returns the PREVIOUS reference while the new
+ * value is structurally equal, so downstream memos see one identity per
+ * structural value. Functions (and anything else non-plain) compare by
+ * reference — a policy override carrying an inline closure (for example
+ * `strings.humanizeTitle`) still churns; hoist such overrides.
+ */
+import { useRef } from "react";
+
+function isPlainObject(value: unknown): value is Record<string, unknown> {
+  if (typeof value !== "object" || value === null) return false;
+  const proto: unknown = Object.getPrototypeOf(value);
+  return proto === Object.prototype || proto === null;
+}
+
+export function structurallyEqual(a: unknown, b: unknown): boolean {
+  if (Object.is(a, b)) return true;
+  if (Array.isArray(a) && Array.isArray(b)) {
+    return a.length === b.length && a.every((item, i) => structurallyEqual(item, b[i]));
+  }
+  if (isPlainObject(a) && isPlainObject(b)) {
+    const aKeys = Object.keys(a);
+    const bKeys = Object.keys(b);
+    return (
+      aKeys.length === bKeys.length &&
+      aKeys.every((key) => Object.hasOwn(b, key) && structurallyEqual(a[key], b[key]))
+    );
+  }
+  // Functions, class instances, Maps, … — reference identity only (already
+  // handled by Object.is above).
+  return false;
+}
+
+export function useStructuralIdentity<T>(value: T): T {
+  const ref = useRef(value);
+  if (!structurallyEqual(ref.current, value)) ref.current = value;
+  return ref.current;
+}

package/src/react/use-transcript.ts

@@ -174,12 +174,15 @@ export function useTranscript({
   }, [plan]);
 
   // Locator resolution — one read per locator key, misses become "expired".
+  // Walks the plan's VIEWS roster, not the display items: under the chips
+  // presentation (guuey#301) no inline mount renders, but the host's canvas
+  // still needs every locator resolved — the roster is presentation-
+  // independent, so resolution is too.
   const readerRef = useRef(reader);
   readerRef.current = reader;
   const inFlight = useRef(new Set<ItemKey>());
   useEffect(() => {
-    for (const item of plan.items) {
-      if (item.kind !== "view") continue;
+    for (const item of plan.views) {
       if (item.mount === null || item.mount.channel !== "locator") continue;
       if (resolvedMounts.has(item.key) || inFlight.current.has(item.key)) continue;
       const read = readerRef.current;

package/src/strings.ts

@@ -68,6 +68,10 @@ export interface ChatStrings {
   }) => string;
   /** guuey#204: the chip text for a mount promoted to a host stage/canvas. */
   viewPromoted: (title: string) => string;
+  /** guuey#301 chips presentation: an unselected, mountable view's chip text. */
+  viewChip: (title: string) => string;
+  /** guuey#301 chips presentation: an expired/dead view's chip text (honest state). */
+  viewChipExpired: (title: string) => string;
   /** Chip title when the mount has no producing-call title (history cards). */
   viewRefFallbackTitle: string;
 
@@ -160,6 +164,8 @@ export const defaultChatStrings: ChatStrings = {
   viewCspBlocked: (d) =>
     `This page's Content-Security-Policy blocks ${d.blockedUri} — add "${d.violatedDirective} ${d.suggestedEntry}" to the policy so the view can start`,
   viewPromoted: (title) => `${title} — on canvas`,
+  viewChip: (title) => title,
+  viewChipExpired: (title) => `${title} — expired`,
   viewRefFallbackTitle: "Card",
 
   recoveredFromHistory: "recovered from history",

package/src/types.ts

@@ -152,9 +152,11 @@ export interface TranscriptInputs {
    * {@link ViewMountItem}, so an interactive surface exists exactly ONCE.
    * Absent (or matching nothing / an expired mount) = today's behavior —
    * every mount renders inline. Hosts derive the key with
-   * {@link newestViewKey} rather than hand-building it; the issue's
-   * phase-2 (every card a chip, click-to-swap) is this same field set per
-   * host click, no further plan changes.
+   * {@link newestViewKey} rather than hand-building it. Set per host
+   * click (via `onViewRef`) this is the SELECTION half of guuey#301's
+   * browser-history mechanic; the collapse-ALL-views half is the policy
+   * knob `view.presentation: "chips"` — the two compose, this field alone
+   * never chips more than the one promoted view.
    */
   promotedViewKey?: string;
   /** The last turn ended by user abort (R1 aborted-partial + "Stopped."). */
@@ -294,8 +296,23 @@ export interface ViewRefItem extends BaseItem {
   kind: "viewRef";
   /** The display title (the producing call's, or the strings fallback). */
   title: string;
-  /** The full resolved chip text (`strings.viewPromoted(title)`). */
+  /**
+   * The full resolved chip text — `strings.viewPromoted(title)` for the
+   * selected chip, `strings.viewChip(title)` / `viewChipExpired(title)`
+   * for the rest under chips presentation (guuey#301).
+   */
   label: string;
+  /**
+   * True when this chip's mount is the one the host's stage currently
+   * shows (`key === promotedViewKey` and mountable). Renderers style it
+   * as the active history entry (guuey#301).
+   */
+  selected: boolean;
+  /**
+   * The underlying mount's phase — chips presentation keeps expired /
+   * unresolved views honest instead of hiding their state (guuey#301).
+   */
+  phase: ViewHostPhase | "expired";
 }
 
 /** R7 — media blocks. */
@@ -488,6 +505,32 @@ export type ChatDebugEvent =
   | { type: "unknown-block"; key: ItemKey; typeName: string; byteSize: number }
   | { type: "turn-recovered"; marker: string };
 
+/**
+ * One renderable view the plan saw, BEFORE any chips/promotion pass —
+ * the host-canvas contract (guuey#301): everything a stage needs to
+ * render the selected mount and label a history rail, in transcript
+ * order (history cards first, live mounts after — the same order the
+ * items carry).
+ */
+export interface PlanViewSummary {
+  key: ItemKey;
+  /** The display title (the producing call's, or the strings fallback). */
+  title: string;
+  phase: ViewHostPhase | "expired";
+  channel: ViewMountChannel | null;
+  /** Null when the locator is dead (the R13 expired path). */
+  mount: ViewMount | null;
+  /** The persisted `ui://` locator actions bind to (guuey#158), or null. */
+  actionScope: string | null;
+  /**
+   * Provenance: a LIVE fold mount vs a persisted HISTORY card. The roster
+   * is in transcript order (history cards sit with the settled prefix), so
+   * "newest" recency needs this — live outranks history, exactly
+   * {@link newestViewKey}'s walk.
+   */
+  origin: "live" | "history";
+}
+
 export interface TranscriptPlan {
   /** Ordered, stable keys (spec §7's determinism contract). */
   items: DisplayItem[];
@@ -499,4 +542,10 @@ export interface TranscriptPlan {
    * byte-identical to a streamed turn's (fixture 17).
    */
   recovery: string | null;
+  /**
+   * Every view the plan saw (guuey#301's host-canvas contract) — present
+   * regardless of `view.presentation`, so a stage can render the selected
+   * mount even when the transcript shows only chips.
+   */
+  views: PlanViewSummary[];
 }

package/styles.css

@@ -262,6 +262,16 @@
   color: var(--guuey-chat-ink);
   border-color: color-mix(in srgb, var(--guuey-chat-ink) 24%, transparent);
 }
+/* guuey#301 chips presentation: the selected (on-stage) chip + honest expired state. */
+.guuey-chat-view-ref-selected {
+  border-color: var(--guuey-chat-accent);
+  color: var(--guuey-chat-ink);
+  background: color-mix(in srgb, var(--guuey-chat-accent) 12%, var(--guuey-chat-surface));
+}
+.guuey-chat-view-ref-expired {
+  opacity: 0.6;
+  text-decoration: line-through;
+}
 
 /* ── R7 media ── */
 .guuey-chat-media-image img {