@guuey/chat 0.10.0 → 0.12.0

package/src/react/components.tsx

@@ -106,6 +106,7 @@ export type ViewSlotProps = Pick<
   | "hostInfo"
   | "hostContext"
   | "onCallTool"
+  | "onUpdateModelContext"
   | "onReadResource"
   | "onSizeChanged"
   | "negotiationTimeoutMs"
@@ -387,9 +388,12 @@ export function DefaultView({ item, ctx }: ItemProps<ViewMountItem>): ReactNode
  * `onViewRef` (keyboard-accessible for free); a plain label otherwise.
  */
 export function DefaultViewRef({ item, ctx }: ItemProps<ViewRefItem>): ReactNode {
+  const stateClasses = `${item.selected ? " guuey-chat-view-ref-selected" : ""}${
+    item.phase === "expired" ? " guuey-chat-view-ref-expired" : ""
+  }`;
   if (ctx.onViewRef === undefined) {
     return (
-      <p className="guuey-chat-view-ref" role="note">
+      <p className={`guuey-chat-view-ref${stateClasses}`} role="note">
         {item.label}
       </p>
     );
@@ -398,7 +402,8 @@ export function DefaultViewRef({ item, ctx }: ItemProps<ViewRefItem>): ReactNode
   return (
     <button
       type="button"
-      className="guuey-chat-view-ref guuey-chat-view-ref-button"
+      className={`guuey-chat-view-ref guuey-chat-view-ref-button${stateClasses}`}
+      aria-pressed={item.selected}
       onClick={() => onViewRef(item)}
     >
       {item.label}

package/src/react/guuey-chat.tsx

@@ -48,6 +48,7 @@ import {
   forwardRef,
   useCallback,
   useEffect,
+  useId,
   useImperativeHandle,
   useMemo,
   useRef,
@@ -56,23 +57,61 @@ import {
   type ReactNode,
 } from "react";
 import {
+  createUiActionRelay,
   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";
+import { unavailableToolCallResult } from "@guuey/mcp-apps-host";
+import type { McpToolCallResult, UiActionRequest, 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";
+import type { TranscriptComponents, TranscriptItemContext, ViewSlotProps } from "./components.js";
 import { useTranscript, useTranscriptInputs } from "./use-transcript.js";
 import { oauthPromptAction, useOAuthReturn } from "./oauth-return.js";
 
+/**
+ * The kit-tier theme announce (guuey#302): default `hostContext.theme`
+ * from the transcript mode onto every view slot. A caller-declared
+ * `hostContext` key wins field-by-field; `theme` is only filled in.
+ * Exported for tests; not part of the package surface.
+ */
+export function viewPropsWithThemeAnnounce(
+  viewProps: TranscriptItemContext["viewProps"],
+  mode: ThemeMode,
+  defaults: Pick<ViewSlotProps, "onCallTool" | "onUpdateModelContext"> = {},
+): TranscriptItemContext["viewProps"] {
+  const themed = (base: ViewSlotProps | undefined): ViewSlotProps => ({
+    // Kit-default host wires (guuey#335): the ACTION RELAY (Confirm inside
+    // a rendered card is a tools/call — without a relay the initialize-only
+    // host -32601s and the interaction visibly fails) and the
+    // model-context sink (a COMPLEMENT channel — producers mirror the
+    // snapshot server-side, so a recording sink is honest). A caller-
+    // declared slot prop always wins.
+    ...defaults,
+    ...base,
+    hostContext: { theme: mode, ...base?.hostContext },
+  });
+  if (typeof viewProps === "function") {
+    return (item, mount) => themed(viewProps(item, mount));
+  }
+  return themed(viewProps);
+}
+
 /**
  * The imperative seam (guuey#210): programmatic send/prefill/focus for
  * hosts that stay on the batteries-included path (suggested-prompt chips
@@ -107,6 +146,16 @@ export interface GuueyChatHandle {
    * {@link GuueyChatProps.onThread}.
    */
   readonly threadId: string | null;
+  /**
+   * The slot props the kit's OWN inline mounts run with — theme announce,
+   * default action relay, model-context sink (guuey#335). A host mounting
+   * a roster view on its own canvas (`<GuueyView {...handle.viewSlotProps()}`>)
+   * gets the identical wiring, so a rendered card's Confirm works there
+   * too. Live values (read on demand); when the host passed a FUNCTION-form
+   * `viewProps`, this returns the kit defaults (per-item resolution belongs
+   * to the transcript).
+   */
+  viewSlotProps(): ViewSlotProps;
 }
 
 export interface GuueyChatProps {
@@ -208,6 +257,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 +301,9 @@ export const GuueyChat = forwardRef<GuueyChatHandle, GuueyChatProps>(function Gu
     reader,
     onDebugEvent,
     viewProps,
+    promotedViewKey,
+    onViewRef,
+    onViewsChange,
     onPromptAction,
     onHitlAnswer,
     oauthReturnTo,
@@ -250,15 +315,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 +369,149 @@ 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]);
+
+  // The theme announce, completed at the kit tier (guuey#302): every
+  // inline mount carries `hostContext.theme` from the transcript's `mode`
+  // — render bundles read it at ui/initialize (ggui precedence: slice
+  // wins, host falls back — their #551/#573). A caller's explicit
+  // `viewProps.hostContext` keys win; `theme` is only defaulted. Hosts
+  // mounting views DIRECTLY (a canvas over the roster) announce on their
+  // own <GuueyView hostContext> — this covers the kit's own mounts.
+  // The DEFAULT ACTION RELAY (guuey#335 — the founder-hit Confirm bug):
+  // pod-then-persisted, built over the SAME identity as the reader, thread
+  // read through the ref at CALL time. Without it, a kit-mounted render's
+  // tools/call hits an initialize-only host and the card's interaction
+  // visibly fails — the #221 batteries-included treatment, applied to the
+  // ACTION half. No thread yet ⇒ the in-band unavailable result (a card
+  // cannot exist before its thread, but a race answers honestly).
+  const defaultOnCallTool = useMemo<((request: UiActionRequest) => Promise<McpToolCallResult>) | undefined>(() => {
+    if (apiBaseUrl === undefined) return undefined;
+    return async (request) => {
+      const threadId = threadIdRef.current;
+      if (threadId === null) return unavailableToolCallResult();
+      const getToken = getAccessTokenRef.current;
+      const getGuest = getGuestSecretRef.current;
+      const relay = createUiActionRelay({
+        apiBaseUrl,
+        threadId,
+        endpointUrl,
+        ...(getToken !== undefined ? { getAccessToken: getToken } : {}),
+        guestSecret: getGuest !== undefined ? getGuest() : null,
+      });
+      return relay(request);
+    };
+  }, [apiBaseUrl, endpointUrl]);
+
+  // Model-context sink (guuey#335): the snapshot is a complement (producers
+  // mirror it server-side), so recording to the debug surface is the honest
+  // kit default — and answering the method keeps strict producers green.
+  const onDebugEventRef = useRef(onDebugEvent);
+  onDebugEventRef.current = onDebugEvent;
+  const defaultOnUpdateModelContext = useCallback((params: { [key: string]: unknown }) => {
+    onDebugEventRef.current?.({
+      type: "model-context-update",
+      byteSize: JSON.stringify(params)?.length ?? 0,
+    });
+  }, []);
+
+  const effectiveViewProps = useMemo<TranscriptItemContext["viewProps"]>(
+    () =>
+      viewPropsWithThemeAnnounce(viewProps, mode, {
+        ...(defaultOnCallTool !== undefined ? { onCallTool: defaultOnCallTool } : {}),
+        onUpdateModelContext: defaultOnUpdateModelContext,
+      }),
+    [viewProps, mode, defaultOnCallTool, defaultOnUpdateModelContext],
+  );
+
+  // The canvas-host door (guuey#335): a host mounting views DIRECTLY from
+  // the roster (the chat-rail shell) needs the SAME slot wiring the kit's
+  // inline mounts get — theme announce, action relay, context sink. Read
+  // through a ref so the lifetime-stable handle always hands out current
+  // wiring; a caller-passed FUNCTION-form viewProps resolves per transcript
+  // item only, so the handle returns the kit defaults in that case.
+  const staticSlotPropsRef = useRef<ViewSlotProps>({});
+  staticSlotPropsRef.current =
+    typeof effectiveViewProps === "function"
+      ? {
+          ...(defaultOnCallTool !== undefined ? { onCallTool: defaultOnCallTool } : {}),
+          onUpdateModelContext: defaultOnUpdateModelContext,
+          hostContext: { theme: mode },
+        }
+      : (effectiveViewProps ?? {});
+
   // ── 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() !== "";
@@ -357,6 +554,9 @@ export const GuueyChat = forwardRef<GuueyChatHandle, GuueyChatProps>(function Gu
       get threadId(): string | null {
         return threadIdRef.current;
       },
+      // Same live-read discipline as `threadId`: the ref always holds the
+      // CURRENT kit wiring (guuey#335 — the canvas-host door).
+      viewSlotProps: (): ViewSlotProps => staticSlotPropsRef.current,
     }),
     [],
   );
@@ -463,7 +663,8 @@ export const GuueyChat = forwardRef<GuueyChatHandle, GuueyChatProps>(function Gu
         resolvedMounts={resolvedMounts}
         onViewPhase={onViewPhase}
         onViewDiagnosis={onViewDiagnosis}
-        {...(viewProps !== undefined ? { viewProps } : {})}
+        {...(onViewRef !== undefined ? { onViewRef } : {})}
+        viewProps={effectiveViewProps}
       />
       {oauthReturn.notice !== null && (
         <p
@@ -487,6 +688,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. */
@@ -486,7 +503,40 @@ export type ChatDebugEvent =
       diagnosis?: ViewCspDiagnosis;
     }
   | { type: "unknown-block"; key: ItemKey; typeName: string; byteSize: number }
-  | { type: "turn-recovered"; marker: string };
+  | { type: "turn-recovered"; marker: string }
+  /**
+   * A view pushed a `ui/update-model-context` snapshot and the kit's
+   * default sink recorded it (guuey#335). The snapshot itself is a
+   * COMPLEMENT — producers mirror it server-side — so the debug surface
+   * carries the fact and the size, not the payload.
+   */
+  | { type: "model-context-update"; byteSize: number };
+
+/**
+ * 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). */
@@ -499,4 +549,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 {