@guuey/chat 0.4.0 → 0.6.0

package/src/plan.ts

@@ -9,11 +9,14 @@
  * Source-ownership rules (spec §9 Change-1 — one unified plan owns both):
  *
  *  - USER rows always come from the flat `inputs.messages`.
- *  - ASSISTANT content comes from the fold (`inputs.result`) when present;
- *    otherwise from the flat assistant entries plus the in-flight
- *    `assistantText`. Both paths normalize to the same block walk, so a
- *    silver stream carrying only text plans byte-identically to a bypass
- *    stream (fixture 5).
+ *  - ASSISTANT content comes from the fold (`inputs.result`) for the
+ *    TRAILING turns the fold covers; earlier flat assistant entries (a
+ *    rehydrated/persisted prefix the session's Reducer never saw) render as
+ *    text slots in front (the turn-scoped refinement — see
+ *    `TranscriptInputs.result`). Without a fold, flat entries plus the
+ *    in-flight `assistantText` own everything. Both paths normalize to the
+ *    same block walk, so a silver stream carrying only text plans
+ *    byte-identically to a bypass stream (fixture 5).
  *  - Interleaving is conversational alternation (user[i] then assistant[i]) —
  *    the transcript invariant of a request/reply chat. Finer-grained
  *    interleaving (true seq-ordering of history cards inside turns) needs
@@ -31,11 +34,13 @@
 import type { AgBlock, AgReduceResult, JsonValue } from "@silverprotocol/core";
 import { snapshotViewMount, toolResultViewMount, uiLocator, type ViewMount } from "@guuey/mcp-apps-host";
 import type { TranscriptPolicy } from "./policy.js";
+import { grantModeDisplay } from "./hitl.js";
 import type {
   CitationsItem,
   DataResultItem,
   DisplayItem,
   ItemKey,
+  NoticeItem,
   StatusLineItem,
   ToolGroupItem,
   ToolItem,
@@ -44,6 +49,7 @@ import type {
   TranscriptPlan,
   UnknownItem,
   ViewMountItem,
+  ViewRefItem,
 } from "./types.js";
 
 /** R5's giant threshold: above this byte count the state is `giant`. */
@@ -91,27 +97,77 @@ interface AssistantSource {
   stopped: boolean;
 }
 
-function foldAssistantSources(result: AgReduceResult, inFlight: boolean, aborted: boolean): AssistantSource[] {
+/** A fold-borne `role:"notice"` row, anchored to the source it followed. */
+interface FoldNotice {
+  text: string;
+  source: NoticeItem["source"];
+  /** Index into the returned sources of the message this notice followed; -1 = before any. */
+  afterSourceIndex: number;
+}
+
+/** R16 notice text: the message's text blocks, joined (non-text blocks carry no notice prose). */
+function noticeText(content: readonly AgBlock[]): string {
+  return content
+    .filter((b): b is Extract<AgBlock, { type: "text" }> => b.type === "text")
+    .map((b) => b.text)
+    .join("\n");
+}
+
+function foldAssistantSources(
+  result: AgReduceResult,
+  inFlight: boolean,
+  aborted: boolean,
+): { sources: AssistantSource[]; notices: FoldNotice[] } {
   // Real pod folds carry `tool-result` blocks in separate `role: "tool"`
   // messages between assistant turns (the production ggui-render capture is
   // the receipt — guuey#135 3b widget convergence found this): an
   // assistant-only filter orphans every call and drops every mount. A tool
   // message's blocks belong to the PRECEDING assistant slot's walk, exactly
   // the whole-fold message order the retired first-party renderers used.
+  //
+  // LIVE detection is turn-identity-based where the fold carries it: while
+  // a turn is in flight, an assistant message whose `turnId` maps to a turn
+  // record WITHOUT an `outcome` belongs to the open turn — settled earlier
+  // turns stay settled even mid-session (what makes the tail alignment
+  // below count them correctly). Nothing is live once the status is back to
+  // `ready`, whatever the records say (a fold that missed `turn.done` must
+  // not pin a settled turn open forever). Folds without turn identity (a
+  // hand-driven fold that never saw `turn.*` lifecycle) fall back to the
+  // last-source-is-live-iff-in-flight heuristic — the pre-refinement
+  // behaviour, kept so identity-less folds plan exactly as before.
+  const openTurns = new Set(
+    result.turns.filter((t) => t.outcome === undefined).map((t) => t.turnId),
+  );
+  const hasTurnIdentity = result.messages.some(
+    (m) => m.role === "assistant" && m.turnId !== undefined,
+  );
   const sources: AssistantSource[] = [];
+  const notices: FoldNotice[] = [];
   for (const m of result.messages) {
     if (m.role === "assistant") {
-      sources.push({ blocks: [...m.content], live: false, stopped: false });
+      sources.push({
+        blocks: [...m.content],
+        live: inFlight && hasTurnIdentity && m.turnId !== undefined && openTurns.has(m.turnId),
+        stopped: false,
+      });
     } else if (m.role === "tool" && sources.length > 0) {
       sources[sources.length - 1]!.blocks.push(...m.content);
+    } else if (m.role === "notice") {
+      // R16 (spec draft.2): a session annotation — a PEER row, never folded
+      // into assistant content; it anchors after the source it followed.
+      notices.push({
+        text: noticeText(m.content),
+        source: m.noticeSource ?? null,
+        afterSourceIndex: sources.length - 1,
+      });
     }
   }
   const last = sources[sources.length - 1];
   if (last) {
-    last.live = inFlight;
+    if (!hasTurnIdentity) last.live = inFlight;
     last.stopped = aborted;
   }
-  return sources;
+  return { sources, notices };
 }
 
 function flatAssistantSources(inputs: TranscriptInputs, inFlight: boolean): AssistantSource[] {
@@ -621,12 +677,73 @@ export function planTranscript(
 
   const inFlight = inputs.status !== "ready";
   const users = inputs.messages.filter((m) => m.role === "user");
-  const assistants = inputs.result
-    ? foldAssistantSources(inputs.result, inFlight, inputs.aborted === true)
-    : flatAssistantSources(inputs, inFlight);
+  // R16 — notice rows are session annotations anchored between turns: a
+  // flat notice renders after the conversation slot of the user turn it
+  // followed (usersSeen-1; -1 = before the conversation). They are PEER
+  // rows — excluded from both the user pairing and the assistant seam
+  // count, so the fold alignment below never sees them.
+  const notices: Array<{ key: string; text: string; source: NoticeItem["source"]; afterSlot: number }> = [];
+  if (policy.notice.show) {
+    let usersSeen = 0;
+    inputs.messages.forEach((m, i) => {
+      if (m.role === "user") usersSeen += 1;
+      else if (m.role === "notice") {
+        notices.push({ key: `n${i}`, text: m.text, source: m.noticeSource ?? null, afterSlot: usersSeen - 1 });
+      }
+    });
+  }
+  // Turn-scoped fold composition (guuey#135 kit refinement): the fold owns
+  // the TRAILING assistant turns it actually covers — its settled sources
+  // replace that many trailing flat assistant entries; any EARLIER flat
+  // entries (a rehydrated/persisted prefix the session's Reducer never saw)
+  // keep rendering as flat text slots in front. When the fold spans the
+  // whole conversation (a pure-live session — the corpus's world), the kept
+  // prefix is empty and the plan is byte-identical to the old wholesale
+  // replace. Alignment is by COUNT (trailing flat entries ↔ settled fold
+  // sources): flat rows carry no turn identity, so a persisted CARD-ONLY
+  // turn inside the fold's span (an empty-text assistant row the assembler
+  // dropped) can offset the seam by one — a documented approximation, same
+  // class as the header's read-plane-seq note, resolved for the visible
+  // cards by the actionScope dedupe below.
+  let assistants: AssistantSource[];
+  if (inputs.result) {
+    const fold = foldAssistantSources(inputs.result, inFlight, inputs.aborted === true);
+    const foldSources = fold.sources;
+    const settledFoldCount = foldSources.filter((s) => !s.live).length;
+    const flatSettled = inputs.messages.filter((m) => m.role === "assistant");
+    const keep = Math.max(0, flatSettled.length - settledFoldCount);
+    assistants = [
+      ...flatSettled.slice(0, keep).map(
+        (m): AssistantSource => ({
+          blocks: [{ type: "text", text: m.text }],
+          live: false,
+          stopped: false,
+        }),
+      ),
+      ...foldSources,
+    ];
+    if (policy.notice.show) {
+      // Fold-borne notices anchor to the fold source they followed, which
+      // sits at global slot `keep + afterSourceIndex` after the seam.
+      fold.notices.forEach((n, i) => {
+        notices.push({ key: `nf${i}`, text: n.text, source: n.source, afterSlot: keep + n.afterSourceIndex });
+      });
+    }
+  } else {
+    assistants = flatAssistantSources(inputs, inFlight);
+  }
 
   const slots = Math.max(users.length, assistants.length);
   const conversation: DisplayItem[] = [];
+  const noticeItem = (n: (typeof notices)[number]): NoticeItem => ({
+    kind: "notice",
+    key: n.key,
+    expanded: true,
+    text: n.text,
+    source: n.source,
+    sourceLabel: policy.debugDetail && n.source !== null ? n.source : null,
+  });
+  for (const n of notices) if (n.afterSlot < 0) conversation.push(noticeItem(n));
   for (let slot = 0; slot < slots; slot++) {
     const user = users[slot];
     if (user) {
@@ -648,16 +765,35 @@ export function planTranscript(
     if (assistant) {
       conversation.push(...planAssistantSource(assistant, slot, inputs, policy, overrides));
     }
+    for (const n of notices) if (n.afterSlot === slot) conversation.push(noticeItem(n));
   }
   items.push(...groupTools(conversation, policy, overrides));
 
   // R13 — persisted cards, seq order. (Position: after the settled
   // conversation; true in-turn interleave needs read-plane seqs the flat
   // surface lacks — the 3b assemblers own that refinement.)
+  //
+  // Dedupe against LIVE mounts by actionScope (the persisted `ui://`
+  // identity both sides carry): a session whose fold still holds a turn the
+  // read plane has ALSO persisted — the #192 adopted turn, a thread view's
+  // post-handoff refetch — would otherwise render the same card twice. The
+  // fold's view row owns it (richer phase state); the history snapshot
+  // renders only when no live mount claims its identity.
+  const liveViewScopes = new Set<string>();
+  for (const item of items) {
+    if (item.kind === "view" && item.actionScope !== null) liveViewScopes.add(item.actionScope);
+  }
   const cards = [...(inputs.historyCards ?? [])].sort((a, b) => a.seq - b.seq);
   for (const card of cards) {
     const key = `card.${card.seq}`;
     const mount = snapshotViewMount(card.cardSnapshot);
+    const scope =
+      mount === undefined
+        ? null
+        : mount.channel === "locator"
+          ? mount.resourceUri
+          : mount.resource.uri;
+    if (scope !== null && liveViewScopes.has(scope)) continue; // live mount owns it
     const view: ViewMountItem = {
       kind: "view",
       key,
@@ -668,20 +804,42 @@ export function planTranscript(
       label: null,
       attribution: null,
       toolTitle: null,
-      actionScope:
-        mount === undefined
-          ? null
-          : mount.channel === "locator"
-            ? mount.resourceUri
-            : mount.resource.uri,
+      actionScope: scope,
     };
     view.label = viewLabel(view, policy);
     items.push(view);
   }
 
-  // R10 — prompts, in input order.
+  // R10 — prompts, in input order (narrow on `kind`: the guuey-wire
+  // profile arm vs the AgJSON hitl arm, spec draft.2).
   for (const prompt of inputs.prompts) {
     const key = `p.${prompt.id}`;
+    if (prompt.kind === "hitl") {
+      const chosen =
+        prompt.grantModeId !== undefined
+          ? (prompt.ask.grantModes ?? []).find((m) => m.id === prompt.grantModeId)
+          : undefined;
+      items.push({
+        kind: "prompt",
+        key,
+        promptId: prompt.id,
+        // `cancelled` collapses to a dismissed record but stays expandable —
+        // guuey's re-askable ruling (silverprotocol#16); pending opens.
+        expanded: resolveExpanded(key, prompt.state === "pending", overrides),
+        promptKind: "hitl",
+        ask: prompt.ask,
+        message: prompt.ask.message ?? null,
+        askKind: prompt.ask.kind,
+        grantModes: prompt.ask.grantModes ?? [],
+        state: prompt.state,
+        chosenModeId: prompt.grantModeId ?? null,
+        chosenModeLabel: chosen !== undefined ? grantModeDisplay(chosen) : null,
+        raw: policy.prompt.rawPayload
+          ? { askId: prompt.ask.askId, kind: prompt.ask.kind, state: prompt.state, grantModeId: prompt.grantModeId ?? null }
+          : null,
+      });
+      continue;
+    }
     items.push({
       kind: "prompt",
       key,
@@ -731,10 +889,65 @@ export function planTranscript(
     });
   }
 
+  // guuey#204 "promote and reference": the ONE mount a host-owned stage
+  // shows (`inputs.promotedViewKey`) renders as a compact reference chip
+  // instead of a second live app instance. A key matching nothing (stale
+  // host state) or an expired mount promotes nothing — the honest no-op;
+  // the next render's key corrects it. The chip keeps the mount's key, so
+  // overrides and phase reports survive a swap back to the full mount.
+  const promoted = inputs.promotedViewKey;
+  const finalItems =
+    promoted === undefined
+      ? items
+      : items.map((item): DisplayItem => {
+          if (item.kind !== "view" || item.key !== promoted) return item;
+          if (item.phase === "expired" || item.mount === null) return item;
+          const title = item.toolTitle ?? policy.strings.viewRefFallbackTitle;
+          const ref: ViewRefItem = {
+            kind: "viewRef",
+            key: item.key,
+            expanded: false,
+            title,
+            label: policy.strings.viewPromoted(title),
+          };
+          return ref;
+        });
+
   return {
-    items,
+    items: finalItems,
     status: deriveStatus(inputs, policy),
     recovery:
       inputs.adopted === true && policy.debugDetail ? policy.strings.recoveredFromHistory : null,
   };
 }
+
+/**
+ * The plan key of the NEWEST mountable view — what a "most recent card"
+ * stage (the widget's CanvasPane) will show, derived in the same family
+ * the plan's own emission uses: live fold mounts (transcript order, last
+ * wins) outrank history cards (ascending `seq`). `undefined` when nothing
+ * narrows to a mountable resource. Hosts pass the key back as
+ * `TranscriptInputs.promotedViewKey`; `channel` lets a host decline to
+ * promote a bare locator when no reader is wired (the stage would show
+ * nothing, and a chip must never point at an empty canvas).
+ */
+export function newestViewKey(
+  inputs: Pick<TranscriptInputs, "result" | "historyCards">,
+): { key: string; channel: ViewMount["channel"] } | undefined {
+  let newest: { key: string; channel: ViewMount["channel"] } | undefined;
+  const cards = [...(inputs.historyCards ?? [])].sort((a, b) => a.seq - b.seq);
+  for (const card of cards) {
+    const mount = snapshotViewMount(card.cardSnapshot);
+    if (mount === undefined) continue;
+    newest = { key: `card.${card.seq}`, channel: mount.channel };
+  }
+  for (const message of inputs.result?.messages ?? []) {
+    for (const block of message.content) {
+      if (block.type !== "tool-result") continue;
+      const mount = toolResultViewMount(block);
+      if (mount === undefined) continue;
+      newest = { key: `view.${block.toolCallId}`, channel: mount.channel };
+    }
+  }
+  return newest;
+}

package/src/policy.ts

@@ -69,6 +69,8 @@ export interface TranscriptPolicy {
   };
   /** R12 — thresholds are chosen-not-measured (§10-F6; 3b validates vs #188 data). */
   status: { wakingMs: number; longStartMs: number };
+  /** R16 (spec draft.2) — notice rows; provenance facet shows under debug. */
+  notice: { show: boolean };
   /** R14. */
   compaction: { show: boolean };
   /** R15. */
@@ -95,6 +97,7 @@ function withOverrides(base: TranscriptPolicy, overrides?: Partial<TranscriptPol
     prompt: { ...base.prompt, ...(overrides.prompt ?? {}) },
     error: { ...base.error, ...(overrides.error ?? {}) },
     status: { ...base.status, ...(overrides.status ?? {}) },
+    notice: { ...base.notice, ...(overrides.notice ?? {}) },
     compaction: { ...base.compaction, ...(overrides.compaction ?? {}) },
     unknown: { ...base.unknown, ...(overrides.unknown ?? {}) },
   };
@@ -115,6 +118,7 @@ function calmBase(): TranscriptPolicy {
     media: { inlineImageCapRem: 20, chipOnly: false },
     code: { capRem: 16, wrap: false },
     citations: { style: "chips" },
+    notice: { show: true },
     prompt: { placement: "inline", rawPayload: false },
     error: { verbatim: false, copyByCode: {}, verbatimCodes: [] },
     status: { wakingMs: 2500, longStartMs: 15_000 },

package/src/react/components.tsx

@@ -38,6 +38,7 @@ import type {
   HistoryBoundaryItem,
   ItemKey,
   MediaItem,
+  NoticeItem,
   PromptItem,
   ReasoningItem,
   StatusLineItem,
@@ -47,6 +48,7 @@ import type {
   UserMessageItem,
   TextItem,
   ViewMountItem,
+  ViewRefItem,
 } from "../types.js";
 import { Markdown } from "./markdown.js";
 
@@ -57,21 +59,56 @@ export interface TranscriptItemContext {
   onToggle: (key: ItemKey) => void;
   /** R0 failed-send retry. */
   onRetry?: (item: UserMessageItem) => void;
-  /** R10 prompt actions — the host owns what accept/decline DO. */
-  onPromptAction?: (item: PromptItem, action: "accept" | "decline" | "dismiss") => void;
+  /**
+   * R10 prompt actions — the host owns what accept/decline DO. A hitl card
+   * with declared grant modes reports the pick as `{ grantModeId }` (spec
+   * draft.2); plain accepts stay the `"accept"` string.
+   */
+  onPromptAction?: (
+    item: PromptItem,
+    action: "accept" | "decline" | "dismiss" | { grantModeId: string },
+  ) => void;
   /** R11 action slots (sign-in / upgrade / retry affordances). */
   onErrorAction?: (item: ErrorItem) => void;
   /** R6: locator mounts resolved by `useTranscript` ("expired" = failed). */
   resolvedMounts: ReadonlyMap<ItemKey, ResolvedViewMount | "expired">;
   /** R6: live phase reports wired back into the next plan. */
   onViewPhase: (key: ItemKey, phase: ViewHostPhase) => void;
-  /** R6 pass-through (sandbox overrides etc. — policy-gated by the host). */
-  viewProps?: Pick<
-    GuueyViewProps,
-    "hostCapabilities" | "hostInfo" | "hostContext" | "onCallTool" | "negotiationTimeoutMs" | "dangerouslyAddSandboxFlags" | "allow"
-  >;
+  /**
+   * guuey#204: a promoted-view reference chip was activated — the host
+   * focuses/reveals its stage (canvas). Absent ⇒ the chip renders as a
+   * non-interactive label.
+   */
+  onViewRef?: (item: ViewRefItem) => void;
+  /**
+   * R6 pass-through (sandbox overrides, the two-origin mount, relay hooks
+   * — policy-gated by the host). Static, or a FUNCTION of the mount being
+   * rendered: view configuration legitimately varies per mount — the
+   * relay-page URL picks a per-channel egress grant (`?channel=`), and a
+   * `tools/call` hook scopes to the item's persisted locator (guuey#158) —
+   * so the function form receives the item and its resolved mount and is
+   * called only when something actually mounts. Static keeps working
+   * unchanged.
+   */
+  viewProps?: ViewSlotProps | ((item: ViewMountItem, mount: ResolvedViewMount) => ViewSlotProps);
 }
 
+/** The per-view slice of `GuueyViewProps` a transcript may configure. */
+export type ViewSlotProps = Pick<
+  GuueyViewProps,
+  | "hostCapabilities"
+  | "hostInfo"
+  | "hostContext"
+  | "onCallTool"
+  | "onReadResource"
+  | "onSizeChanged"
+  | "negotiationTimeoutMs"
+  | "dangerouslyAddSandboxFlags"
+  | "allow"
+  | "sandboxPageUrl"
+  | "autoResize"
+>;
+
 interface ItemProps<T> {
   item: T;
   ctx: TranscriptItemContext;
@@ -318,11 +355,15 @@ export function DefaultView({ item, ctx }: ItemProps<ViewMountItem>): ReactNode
       </div>
     );
   }
+  // The function form resolves against the ACTUAL mount (per-channel relay
+  // URLs, per-locator action scoping); it runs only when something mounts.
+  const viewProps =
+    typeof ctx.viewProps === "function" ? ctx.viewProps(item, mount) : (ctx.viewProps ?? {});
   return (
     <div className="guuey-chat-view">
       <GuueyView
         mount={mount}
-        {...(ctx.viewProps ?? {})}
+        {...viewProps}
         onPhaseChange={(phase) => ctx.onViewPhase(item.key, phase)}
       />
       {item.attribution !== null ? (
@@ -332,6 +373,31 @@ export function DefaultView({ item, ctx }: ItemProps<ViewMountItem>): ReactNode
   );
 }
 
+/**
+ * guuey#204: the "promote and reference" chip — stands in for the one
+ * mount the host's stage shows. A real button when the host wires
+ * `onViewRef` (keyboard-accessible for free); a plain label otherwise.
+ */
+export function DefaultViewRef({ item, ctx }: ItemProps<ViewRefItem>): ReactNode {
+  if (ctx.onViewRef === undefined) {
+    return (
+      <p className="guuey-chat-view-ref" role="note">
+        {item.label}
+      </p>
+    );
+  }
+  const onViewRef = ctx.onViewRef;
+  return (
+    <button
+      type="button"
+      className="guuey-chat-view-ref guuey-chat-view-ref-button"
+      onClick={() => onViewRef(item)}
+    >
+      {item.label}
+    </button>
+  );
+}
+
 // ─── R7 ────────────────────────────────────────────────────────────────────
 
 /** Inline images allow https URLs and image/* base64 data — nothing else. */
@@ -439,6 +505,72 @@ export function DefaultPrompt({ item, ctx }: ItemProps<PromptItem>): ReactNode {
     wasPending.current = item.state === "pending";
   }, [item.state]);
 
+  if (item.promptKind === "hitl") {
+    const s = ctx.strings;
+    // Settled records: resolved shows the CHOSEN MODE'S LABEL (ids are
+    // echo-only identity — asker-scoped semantics, spec §7); declined is
+    // the durable deny. `cancelled` is guuey's re-askable dismissal: it
+    // collapses to a record but stays answerable when expanded.
+    if (item.state === "resolved" || item.state === "declined") {
+      return (
+        <p className={`guuey-chat-prompt-record guuey-chat-prompt-${item.state}`}>
+          {item.state === "resolved"
+            ? item.chosenModeLabel !== null
+              ? s.promptAnsweredWith(item.chosenModeLabel)
+              : s.promptAccept
+            : s.promptDeclinedRecord}
+        </p>
+      );
+    }
+    const answerable = item.state === "pending" || (item.state === "cancelled" && item.expanded);
+    return (
+      <div className="guuey-chat-prompt" role="group">
+        {item.state === "cancelled" && (
+          <button
+            type="button"
+            className="guuey-chat-prompt-record guuey-chat-prompt-cancelled"
+            aria-expanded={item.expanded}
+            onClick={() => ctx.onToggle(item.key)}
+          >
+            {s.promptDismissed}
+          </button>
+        )}
+        {answerable && (
+          <>
+            {item.message !== null && <p className="guuey-chat-prompt-ask">{item.message}</p>}
+            <div className="guuey-chat-prompt-actions">
+              {item.grantModes.length === 0 ? (
+                <button
+                  ref={firstAction}
+                  type="button"
+                  className="guuey-chat-prompt-accept"
+                  onClick={() => ctx.onPromptAction?.(item, "accept")}
+                >
+                  {s.promptAccept}
+                </button>
+              ) : (
+                item.grantModes.map((mode, i) => (
+                  <button
+                    key={mode.id}
+                    ref={i === 0 ? firstAction : undefined}
+                    type="button"
+                    className="guuey-chat-prompt-accept"
+                    title={mode.description}
+                    onClick={() => ctx.onPromptAction?.(item, { grantModeId: mode.id })}
+                  >
+                    {mode.label ?? mode.id}
+                  </button>
+                ))
+              )}
+              <button type="button" onClick={() => ctx.onPromptAction?.(item, "decline")}>
+                {s.promptDecline}
+              </button>
+            </div>
+          </>
+        )}
+      </div>
+    );
+  }
   if (item.state !== "pending") {
     return (
       <p className={`guuey-chat-prompt-record guuey-chat-prompt-${item.state}`}>
@@ -473,6 +605,25 @@ export function DefaultPrompt({ item, ctx }: ItemProps<PromptItem>): ReactNode {
   );
 }
 
+// ─── R16 ──────────────────────────────────────────────────────────────────
+
+/**
+ * A `role:"notice"` session annotation (spec draft.2) — a labeled,
+ * non-conversational row that must never read as agent-authored. Calm
+ * shows the quiet label; debug appends the provenance facet verbatim.
+ */
+export function DefaultNotice({ item, ctx }: ItemProps<NoticeItem>): ReactNode {
+  return (
+    <div className="guuey-chat-notice" role="note">
+      <span className="guuey-chat-notice-label">
+        {ctx.strings.noticeLabel}
+        {item.sourceLabel !== null ? ` · ${item.sourceLabel}` : ""}
+      </span>
+      {item.text !== "" && <span className="guuey-chat-notice-text">{item.text}</span>}
+    </div>
+  );
+}
+
 // ─── R11 ───────────────────────────────────────────────────────────────────
 
 export function DefaultError({ item, ctx }: ItemProps<ErrorItem>): ReactNode {
@@ -554,10 +705,12 @@ export interface TranscriptComponents {
   toolGroup: ComponentType<ItemProps<ToolGroupItem>>;
   dataResult: ComponentType<ItemProps<DataResultItem>>;
   view: ComponentType<ItemProps<ViewMountItem>>;
+  viewRef: ComponentType<ItemProps<ViewRefItem>>;
   media: ComponentType<ItemProps<MediaItem>>;
   code: ComponentType<ItemProps<CodeItem>>;
   citations: ComponentType<ItemProps<CitationsItem>>;
   prompt: ComponentType<ItemProps<PromptItem>>;
+  notice: ComponentType<ItemProps<NoticeItem>>;
   error: ComponentType<ItemProps<ErrorItem>>;
   history: ComponentType<ItemProps<HistoryBoundaryItem>>;
   compaction: ComponentType<ItemProps<CompactionItem>>;
@@ -573,10 +726,12 @@ export const defaultTranscriptComponents: TranscriptComponents = {
   toolGroup: DefaultToolGroup,
   dataResult: DefaultDataResult,
   view: DefaultView,
+  viewRef: DefaultViewRef,
   media: DefaultMedia,
   code: DefaultCode,
   citations: DefaultCitations,
   prompt: DefaultPrompt,
+  notice: DefaultNotice,
   error: DefaultError,
   history: DefaultHistoryBoundary,
   compaction: DefaultCompaction,
@@ -619,6 +774,10 @@ export function renderItem(
       const C = components.view;
       return <C key={item.key} item={item} ctx={ctx} />;
     }
+    case "viewRef": {
+      const C = components.viewRef;
+      return <C key={item.key} item={item} ctx={ctx} />;
+    }
     case "media": {
       const C = components.media;
       return <C key={item.key} item={item} ctx={ctx} />;
@@ -635,6 +794,10 @@ export function renderItem(
       const C = components.prompt;
       return <C key={item.key} item={item} ctx={ctx} />;
     }
+    case "notice": {
+      const C = components.notice;
+      return <C key={item.key} item={item} ctx={ctx} />;
+    }
     case "error": {
       const C = components.error;
       return <C key={item.key} item={item} ctx={ctx} />;