@guuey/chat 0.5.0 → 0.6.1

package/src/corpus/drive.ts

@@ -7,7 +7,7 @@
  */
 import { Reducer, type AgEvent } from "@silverprotocol/core";
 import type { InvokeTurnEvent } from "@guuey/agent-client";
-import type { PromptItemInput, TranscriptInputs, TranscriptMessage } from "../types.js";
+import type { ProfilePromptInput, TranscriptInputs, TranscriptMessage } from "../types.js";
 
 export interface DriveOptions {
   userText?: string;
@@ -22,7 +22,7 @@ export interface DriveOptions {
   historyCards?: TranscriptInputs["historyCards"];
   historyState?: TranscriptInputs["historyState"];
   /** Resolve accumulated prompts to this state (fixture 4's answered leg). */
-  promptState?: PromptItemInput["state"];
+  promptState?: ProfilePromptInput["state"];
 }
 
 export function driveTurn(events: InvokeTurnEvent[], opts: DriveOptions = {}): TranscriptInputs {
@@ -32,7 +32,7 @@ export function driveTurn(events: InvokeTurnEvent[], opts: DriveOptions = {}): T
   let assistantText = "";
   let activeTool: string | null = null;
   let error: TranscriptInputs["error"] = null;
-  const prompts: PromptItemInput[] = [];
+  const prompts: ProfilePromptInput[] = [];
   let done = false;
 
   for (const ev of events) {

package/src/corpus/fixtures.ts

@@ -8,7 +8,7 @@
  * THE STANDING RULE (see README.md): a new weird transcript found in
  * production becomes a fixture BEFORE its fix lands. The corpus only grows.
  */
-import type { AgEvent } from "@silverprotocol/core";
+import { Reducer, type AgEvent } from "@silverprotocol/core";
 import type { InvokeTurnEvent } from "@guuey/agent-client";
 import type { TranscriptInputs } from "../types.js";
 import {
@@ -320,6 +320,99 @@ export function userSendFailure(): TranscriptInputs {
   });
 }
 
+/**
+ * 19. persisted-plus-live — the turn-scoped fold composition (portal's
+ * persisted-overlay data model): a persisted prefix the session's Reducer
+ * never saw + a session fold covering the trailing turns, one settled (its
+ * card ALSO persisted — the dedupe case) and one live with a running tool.
+ */
+export function persistedPlusLive(): TranscriptInputs {
+  const reducer = new Reducer();
+  let seq = 0;
+  const s = (): number => seq++;
+  const push = (events: AgEvent[]): void => {
+    for (const ev of events) reducer.push(ev);
+  };
+  // Session turn A (settled — turn.done carries the outcome):
+  push([
+    { type: "turn.start", threadId: "thread-corpus", turnId: "turn-a", seq: s() },
+    { type: "message.start", id: "msg-a", role: "assistant", turnId: "turn-a", threadId: "thread-corpus", seq: s() },
+    { type: "text.start", id: "ta", seq: s() },
+    { type: "text.delta", id: "ta", delta: "Booked the second option.", seq: s() },
+    { type: "text.end", id: "ta", seq: s() },
+    { type: "tool.start", toolCallId: "tA", name: "ggui_render", seq: s() },
+    {
+      type: "tool.done",
+      toolCallId: "tA",
+      content: [],
+      outcome: "ok",
+      uiData: { sessionId: GGUI_SLICE.sessionId, resourceUri: GGUI_RESOURCE_URI, action: "create" },
+      _meta: { [GGUI_META_KEY]: GGUI_SLICE },
+      seq: s(),
+    },
+    { type: "turn.done", turnId: "turn-a", outcome: { type: "success" }, seq: s() },
+  ]);
+  // Session turn B (live — no turn.done yet): one completed tool already in
+  // the fold, a second still active (the fold materializes a tool-call at
+  // `tool.done`; the ACTIVE call is the status line's job, not a row).
+  push([
+    { type: "turn.start", threadId: "thread-corpus", turnId: "turn-b", seq: s() },
+    { type: "message.start", id: "msg-b", role: "assistant", turnId: "turn-b", threadId: "thread-corpus", seq: s() },
+    { type: "tool.start", toolCallId: "tB", name: "load_booking", turnId: "turn-b", seq: s() },
+    { type: "tool.args.assembled", toolCallId: "tB", input: { id: "second" }, turnId: "turn-b", seq: s() },
+    {
+      type: "tool.done",
+      toolCallId: "tB",
+      content: [{ type: "text", text: "loaded" }],
+      outcome: "ok",
+      turnId: "turn-b",
+      seq: s(),
+    },
+  ]);
+  return {
+    result: reducer.result(),
+    assistantText: "",
+    status: "using-tool",
+    statusElapsedMs: 0,
+    activeTool: "check_calendar",
+    error: null,
+    prompts: [],
+    // The flat transcript: one PERSISTED turn the fold never saw, then the
+    // session turns (turn A's settled text row is present — the thread
+    // viewer's liveTail/refetch carries it; turn B is in flight, no row).
+    messages: [
+      { role: "user", text: "plan my trip" },
+      { role: "assistant", text: "Here are some options." },
+      { role: "user", text: "book the second one" },
+      { role: "assistant", text: "Booked the second option." },
+      { role: "user", text: "now move it to Thursday" },
+    ],
+    historyCards: [
+      // An OLD persisted card (pre-session) — must render.
+      {
+        seq: 1,
+        at: "2026-08-15T00:00:00Z",
+        cardSnapshot: {
+          parts: [
+            { type: "tool-result", toolCallId: "old1", content: [], uiData: { resourceUri: "ui://ggui/render/old/1" } },
+          ],
+        },
+      },
+      // Turn A's card, ALSO persisted by the read plane — the live fold's
+      // mount owns this identity; the snapshot must dedupe away.
+      {
+        seq: 5,
+        at: "2026-08-15T00:05:00Z",
+        cardSnapshot: {
+          parts: [
+            { type: "tool-result", toolCallId: "tA", content: [], uiData: { resourceUri: GGUI_RESOURCE_URI } },
+          ],
+        },
+      },
+    ],
+  };
+}
+
 /** 17. stalled-then-adopted — #192: calm identical, debug carries the marker. */
 export function stalledThenAdopted(): { adopted: TranscriptInputs; streamed: TranscriptInputs } {
   const build = (): InvokeTurnEvent[] => {
@@ -336,3 +429,158 @@ export function stalledThenAdopted(): { adopted: TranscriptInputs; streamed: Tra
     streamed: driveTurn(build(), { userText: "move my booking" }),
   };
 }
+
+/**
+ * 20. hitl-grant-modes (spec draft.2, silverprotocol#16) — a paused turn's
+ * PERSISTED ask declares three asker-scoped accept variants. Driven through
+ * the real Reducer: the declaration the card renders from is
+ * `turn.done.outcome:"paused".asks[]`, exactly what a late-joining client
+ * sees. Ids are deliberately arbitrary strings — display must key off
+ * label/description, never id semantics.
+ */
+export function hitlGrantModes(): TranscriptInputs {
+  const reducer = new Reducer();
+  let seq = 0;
+  const s = (): number => seq++;
+  const events: AgEvent[] = [
+    { type: "turn.start", threadId: "thread-hitl", turnId: "turn-h", seq: s() },
+    { type: "message.start", id: "msg-h", role: "assistant", turnId: "turn-h", threadId: "thread-hitl", seq: s() },
+    { type: "text.start", id: "th", seq: s() },
+    { type: "text.delta", id: "th", delta: "I can remember this preference.", seq: s() },
+    { type: "text.end", id: "th", seq: s() },
+    {
+      type: "turn.done",
+      turnId: "turn-h",
+      outcome: {
+        type: "paused",
+        asks: [
+          {
+            askId: "ask-remember-1",
+            kind: "approval",
+            message: "Remember your seating preference?",
+            grantModes: [
+              { id: "m.durable", label: "Always", description: "Keep it for every future chat" },
+              { id: "m.scoped", label: "Just this chat" },
+            ],
+            requestState: "rs-bytes-1",
+          },
+        ],
+      },
+      seq: s(),
+    },
+  ];
+  for (const ev of events) reducer.push(ev);
+  return {
+    result: reducer.result(),
+    assistantText: "",
+    status: "ready",
+    statusElapsedMs: 0,
+    activeTool: null,
+    error: null,
+    prompts: [], // the test composes these via hitlPromptsFromFold + the answer ledger
+    messages: [{ role: "user", text: "book my usual seat" }],
+  };
+}
+
+/**
+ * 21. notice-rows (spec draft.2) — both arrival paths: a flat adapter
+ * notice (the portal self-hosted mapping) and a fold-borne framework
+ * notice (the claude informational promotion). Labeled, non-conversational,
+ * never agent-voiced; provenance shows only under debug.
+ */
+export function noticeRows(): TranscriptInputs {
+  const reducer = new Reducer();
+  let seq = 0;
+  const s = (): number => seq++;
+  const events: AgEvent[] = [
+    { type: "turn.start", threadId: "thread-n", turnId: "turn-n", seq: s() },
+    {
+      type: "message.start",
+      id: "msg-n0",
+      role: "notice",
+      noticeSource: "framework",
+      turnId: "turn-n",
+      threadId: "thread-n",
+      seq: s(),
+    },
+    // The notice's text lands while it is the sole open message, so block
+    // routing is unambiguous; the assistant message opens after.
+    { type: "text.start", id: "tn0", seq: s() },
+    { type: "text.delta", id: "tn0", delta: "Model fell back to concise mode", seq: s() },
+    { type: "text.end", id: "tn0", seq: s() },
+    { type: "message.end", id: "msg-n0", turnId: "turn-n", seq: s() },
+    { type: "message.start", id: "msg-n1", role: "assistant", turnId: "turn-n", threadId: "thread-n", seq: s() },
+    { type: "text.start", id: "tn", seq: s() },
+    { type: "text.delta", id: "tn", delta: "Done.", seq: s() },
+    { type: "text.end", id: "tn", seq: s() },
+    { type: "turn.done", turnId: "turn-n", outcome: { type: "success" }, seq: s() },
+  ];
+  for (const ev of events) reducer.push(ev);
+  return {
+    result: reducer.result(),
+    assistantText: "",
+    status: "ready",
+    statusElapsedMs: 0,
+    activeTool: null,
+    error: null,
+    prompts: [],
+    messages: [
+      { role: "notice", text: "Session resumed on a new device", noticeSource: "adapter" },
+      { role: "user", text: "hi" },
+      { role: "assistant", text: "Done." },
+    ],
+  };
+}
+
+/**
+ * 22. promoted-view — guuey#204 "promote and reference": the mount a host
+ * stage shows chips in the transcript; every other mount stays full; no
+ * key (or a stale one) is byte-identical to today.
+ */
+export function promotedView(): { inputs: TranscriptInputs; promotedKey: string } {
+  const s = seqSource();
+  const events: InvokeTurnEvent[] = [session, frame(boot(s), { status: "thinking" })];
+  for (const id of ["t1", "t2"] as const) {
+    events.push(
+      frame(
+        toolPart(s, id, "ggui_render", {
+          uiData: { uri: `ui://cards/${id}`, mimeType: "text/html", text: `<div>${id}</div>` },
+          content: [],
+        }),
+        { status: "using-tool", activeTool: "ggui_render" },
+      ),
+    );
+  }
+  events.push(doneEvent);
+  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" });
+}

package/src/hitl.ts

@@ -0,0 +1,103 @@
+/**
+ * R10's AgJSON HITL half (spec draft.2, silverprotocol/typescript-sdk#16):
+ * lifting persisted asks out of the fold, and constructing validated
+ * answers.
+ *
+ * Two contract points are load-bearing here:
+ *
+ *  - **Asks render from the PERSISTED declaration** — `AgPausedAsk` in
+ *    `turn.done.outcome:"paused".asks[]`. The live `hitl.ask` event is
+ *    live-only by spec (§1.3); a client that joins a thread late renders
+ *    the paused record, so this module reads ONLY that record and both
+ *    paths converge.
+ *  - **Every answer is validated BEFORE dispatch** — `validateHitlAnswer`
+ *    from core enforces required-iff-declared, echo-must-be-declared, and
+ *    the `requestState` byte-echo MUST. `buildHitlAnswer` constructs
+ *    answers that pass by construction and THROWS if they don't: a failed
+ *    validation here is a kit bug, never a user-visible state.
+ *
+ * Answer states encode guuey's ratified dismissal ruling (#16): dismissal
+ * maps to `cancelled` (still-pending, re-askable — the card stays
+ * answerable), `declined` is the durable explicit deny.
+ */
+import {
+  validateHitlAnswer,
+  type AgGrantMode,
+  type AgHitlAnswer,
+  type AgPausedAsk,
+  type AgReduceResult,
+} from "@silverprotocol/core";
+import type { HitlPromptInput } from "./types.js";
+
+/** A host-side record of how an ask was answered (the assembler's ledger value). */
+export interface HitlAnswerRecord {
+  status: "resolved" | "declined" | "cancelled";
+  /** Present iff `status === "resolved"` and the ask declared modes. */
+  grantModeId?: string;
+}
+
+/** A user action on a HITL card: pick a declared mode, decline, or dismiss. */
+export type HitlPromptAction = { grantModeId: string } | "accept" | "decline" | "dismiss";
+
+/**
+ * Display text for a grant mode: the asker's `label`, else the id as
+ * LITERAL text. Mode semantics are asker-scoped (normative, spec §7):
+ * falling back to the id displays identity, never interpreted meaning —
+ * a renderer must not special-case id strings.
+ */
+export function grantModeDisplay(mode: AgGrantMode): string {
+  return mode.label ?? mode.id;
+}
+
+/**
+ * Lift every persisted ask in the fold into an R10 prompt input, merged
+ * with the host's answer ledger (keyed by askId). Pure; input order is the
+ * fold's turn order.
+ */
+export function hitlPromptsFromFold(
+  result: AgReduceResult | null,
+  answers: Readonly<Record<string, HitlAnswerRecord>> = {},
+): HitlPromptInput[] {
+  if (result === null) return [];
+  const prompts: HitlPromptInput[] = [];
+  for (const turn of result.turns) {
+    if (turn.outcome?.type !== "paused") continue;
+    for (const ask of turn.outcome.asks) {
+      const answer = answers[ask.askId];
+      prompts.push({
+        id: ask.askId,
+        kind: "hitl",
+        ask,
+        state: answer?.status ?? "pending",
+        ...(answer?.grantModeId !== undefined ? { grantModeId: answer.grantModeId } : {}),
+      });
+    }
+  }
+  return prompts;
+}
+
+/**
+ * Construct the wire answer for a card action and validate it against the
+ * ask's own persisted record before anything dispatches it.
+ *
+ * `"accept"` is the plain-ask affirmative (valid only when the ask
+ * declared no modes — with a declaration, accepting IS picking a mode).
+ * A validation failure throws: the inputs came from the declaration
+ * itself, so a mismatch is a construction bug, not a user error.
+ */
+export function buildHitlAnswer(ask: AgPausedAsk, action: HitlPromptAction): AgHitlAnswer {
+  const answer: AgHitlAnswer = {
+    askId: ask.askId,
+    status:
+      action === "decline" ? "declined" : action === "dismiss" ? "cancelled" : "resolved",
+    ...(typeof action === "object" ? { grantModeId: action.grantModeId } : {}),
+    // The pre-existing byte-echo MUST (spec §7): the answer carries the
+    // ask's requestState verbatim when one exists.
+    ...(ask.requestState !== undefined ? { requestState: ask.requestState } : {}),
+  };
+  const verdict = validateHitlAnswer(ask, answer);
+  if (!verdict.ok) {
+    throw new Error(`buildHitlAnswer constructed an invalid answer (${verdict.code}): ${verdict.message}`);
+  }
+  return answer;
+}

package/src/index.ts

@@ -11,6 +11,7 @@
  * rendering, tests, and RN bundlers consume the view-model directly.
  */
 export {
+  newestViewKey,
   planTranscript,
 } from "./plan.js";
 export {
@@ -24,6 +25,13 @@ export {
   type ChatStrings,
 } from "./strings.js";
 export { transcriptInputsFromHistory } from "./history-inputs.js";
+export {
+  buildHitlAnswer,
+  grantModeDisplay,
+  hitlPromptsFromFold,
+  type HitlAnswerRecord,
+  type HitlPromptAction,
+} from "./hitl.js";
 export {
   DEFAULT_CHAT_THEME,
   GUUEY_CHAT_THEME,
@@ -32,6 +40,7 @@ export {
   resolveTheme,
 } from "./theme.js";
 export type {
+  ChatDebugEvent,
   CitationsItem,
   CodeItem,
   CompactionItem,
@@ -40,7 +49,12 @@ export type {
   ErrorItem,
   HistoryBoundaryItem,
   ItemKey,
+  HitlPromptInput,
+  HitlPromptItem,
   MediaItem,
+  NoticeItem,
+  ProfilePromptInput,
+  ProfilePromptItem,
   PromptItem,
   PromptItemInput,
   ReasoningItem,
@@ -55,4 +69,5 @@ export type {
   UnknownItem,
   UserMessageItem,
   ViewMountItem,
+  ViewRefItem,
 } from "./types.js";

package/src/native/components.tsx

@@ -39,6 +39,7 @@ import type {
   HistoryBoundaryItem,
   ItemKey,
   MediaItem,
+  NoticeItem,
   PromptItem,
   ReasoningItem,
   StatusLineItem,
@@ -48,6 +49,7 @@ import type {
   UserMessageItem,
   TextItem,
   ViewMountItem,
+  ViewRefItem,
 } from "../types.js";
 import { Linking } from "react-native";
 import { NativeMarkdown } from "./markdown.js";
@@ -63,13 +65,21 @@ export interface NativeTranscriptItemContext {
   /** 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;
+  onPromptAction?: (
+    item: PromptItem,
+    action: "accept" | "decline" | "dismiss" | { grantModeId: string },
+  ) => void;
   /** R11 action slots (sign-in / 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;
+  /**
+   * guuey#204: a promoted-view reference chip was activated — the host
+   * focuses/reveals its stage. Absent ⇒ the chip renders as a label.
+   */
+  onViewRef?: (item: ViewRefItem) => void;
 }
 
 interface ItemProps<T> {
@@ -347,6 +357,39 @@ export function NativeView({ item, ctx }: ItemProps<ViewMountItem>): ReactNode {
   );
 }
 
+/**
+ * guuey#204: the "promote and reference" chip — a Pressable when the host
+ * wires `onViewRef`, a plain labeled row otherwise. Never a second mount.
+ */
+export function NativeViewRef({ item, ctx }: ItemProps<ViewRefItem>): ReactNode {
+  const { tokens } = ctx;
+  const chipStyle = {
+    alignSelf: "flex-start" as const,
+    backgroundColor: tokens.palette.surface,
+    borderRadius: 999,
+    paddingHorizontal: tokens.pad,
+    paddingVertical: 6,
+  };
+  if (ctx.onViewRef === undefined) {
+    return (
+      <View accessibilityRole="text" style={chipStyle}>
+        <MutedText ctx={ctx}>{item.label}</MutedText>
+      </View>
+    );
+  }
+  const onViewRef = ctx.onViewRef;
+  return (
+    <Pressable
+      accessibilityRole="button"
+      accessibilityLabel={item.label}
+      onPress={() => onViewRef(item)}
+      style={chipStyle}
+    >
+      <MutedText ctx={ctx}>{item.label}</MutedText>
+    </Pressable>
+  );
+}
+
 // ─── R7 ────────────────────────────────────────────────────────────────────
 
 /** Inline images allow https URLs and image/* base64 data — nothing else. */
@@ -442,6 +485,70 @@ export function NativeCitations({ item, ctx }: ItemProps<CitationsItem>): ReactN
 
 export function NativePrompt({ item, ctx }: ItemProps<PromptItem>): ReactNode {
   const { tokens } = ctx;
+  if (item.promptKind === "hitl") {
+    const s = ctx.strings;
+    if (item.state === "resolved" || item.state === "declined") {
+      return (
+        <MutedText ctx={ctx}>
+          {item.state === "resolved"
+            ? item.chosenModeLabel !== null
+              ? s.promptAnsweredWith(item.chosenModeLabel)
+              : s.promptAccept
+            : s.promptDeclinedRecord}
+        </MutedText>
+      );
+    }
+    // `cancelled` = guuey's re-askable dismissal: a record row that reopens
+    // to the actions on toggle (silverprotocol#16 ruling).
+    const answerable = item.state === "pending" || (item.state === "cancelled" && item.expanded);
+    return (
+      <View
+        accessibilityLiveRegion="polite"
+        accessible
+        style={{ backgroundColor: tokens.palette.surface, borderRadius: tokens.radius, padding: tokens.pad, gap: 8 }}
+      >
+        {item.state === "cancelled" && (
+          <Pressable accessibilityRole="button" accessibilityState={{ expanded: item.expanded }} onPress={() => ctx.onToggle(item.key)}>
+            <Text style={{ color: tokens.palette.inkMuted, fontSize: tokens.fontSize }}>{s.promptDismissed}</Text>
+          </Pressable>
+        )}
+        {answerable && (
+          <>
+            {item.message !== null && (
+              <Text style={{ color: tokens.palette.ink, fontSize: tokens.fontSize, fontFamily: tokens.fontFamily }}>
+                {item.message}
+              </Text>
+            )}
+            <View style={{ flexDirection: "row", flexWrap: "wrap", gap: 12 }}>
+              {item.grantModes.length === 0 ? (
+                <Pressable accessibilityRole="button" onPress={() => ctx.onPromptAction?.(item, "accept")}>
+                  <Text style={{ color: tokens.palette.accent, fontWeight: "700", fontSize: tokens.fontSize }}>
+                    {s.promptAccept}
+                  </Text>
+                </Pressable>
+              ) : (
+                item.grantModes.map((mode) => (
+                  <Pressable
+                    key={mode.id}
+                    accessibilityRole="button"
+                    accessibilityHint={mode.description}
+                    onPress={() => ctx.onPromptAction?.(item, { grantModeId: mode.id })}
+                  >
+                    <Text style={{ color: tokens.palette.accent, fontWeight: "700", fontSize: tokens.fontSize }}>
+                      {mode.label ?? mode.id}
+                    </Text>
+                  </Pressable>
+                ))
+              )}
+              <Pressable accessibilityRole="button" onPress={() => ctx.onPromptAction?.(item, "decline")}>
+                <Text style={{ color: tokens.palette.inkMuted, fontSize: tokens.fontSize }}>{s.promptDecline}</Text>
+              </Pressable>
+            </View>
+          </>
+        )}
+      </View>
+    );
+  }
   if (item.state !== "pending") {
     return (
       <MutedText ctx={ctx}>
@@ -474,6 +581,22 @@ export function NativePrompt({ item, ctx }: ItemProps<PromptItem>): ReactNode {
   );
 }
 
+// ─── R16 ──────────────────────────────────────────────────────────────────
+
+/** The notice row (spec draft.2) — labeled, non-conversational, never agent-voiced. */
+export function NativeNotice({ item, ctx }: ItemProps<NoticeItem>): ReactNode {
+  const { tokens } = ctx;
+  return (
+    <View accessible accessibilityRole="text" style={{ paddingVertical: 4 }}>
+      <Text style={{ color: tokens.palette.inkMuted, fontSize: tokens.fontSize - 2 }}>
+        {ctx.strings.noticeLabel}
+        {item.sourceLabel !== null ? ` · ${item.sourceLabel}` : ""}
+        {item.text !== "" ? ` — ${item.text}` : ""}
+      </Text>
+    </View>
+  );
+}
+
 // ─── R11 ───────────────────────────────────────────────────────────────────
 
 export function NativeError({ item, ctx }: ItemProps<ErrorItem>): ReactNode {
@@ -576,10 +699,12 @@ export interface NativeTranscriptComponents {
   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>>;
@@ -595,10 +720,12 @@ export const nativeTranscriptComponents: NativeTranscriptComponents = {
   toolGroup: NativeToolGroup,
   dataResult: NativeDataResult,
   view: NativeView,
+  viewRef: NativeViewRef,
   media: NativeMedia,
   code: NativeCode,
   citations: NativeCitations,
   prompt: NativePrompt,
+  notice: NativeNotice,
   error: NativeError,
   history: NativeHistoryBoundary,
   compaction: NativeCompaction,
@@ -641,6 +768,10 @@ export function renderNativeItem(
       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} />;
@@ -657,6 +788,10 @@ export function renderNativeItem(
       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} />;

package/src/native/transcript.tsx

@@ -66,7 +66,7 @@ export type NativeTranscriptListProps = Pick<
 export interface NativeTranscriptProps
   extends Pick<
     NativeTranscriptItemContext,
-    "onToggle" | "onRetry" | "onPromptAction" | "onErrorAction" | "resolvedMounts" | "onViewPhase"
+    "onToggle" | "onRetry" | "onPromptAction" | "onErrorAction" | "resolvedMounts" | "onViewPhase" | "onViewRef"
   > {
   plan: TranscriptPlan;
   /** Per-slot component overrides (spec §3's override column). */
@@ -93,6 +93,7 @@ export function NativeTranscript(props: NativeTranscriptProps): ReactNode {
     onErrorAction,
     resolvedMounts,
     onViewPhase,
+    onViewRef,
   } = props;
 
   const tokens = useMemo(() => resolveNativeTheme(theme, mode), [theme, mode]);
@@ -101,8 +102,8 @@ export function NativeTranscript(props: NativeTranscriptProps): ReactNode {
     [components],
   );
   const ctx: NativeTranscriptItemContext = useMemo(
-    () => ({ strings, tokens, onToggle, onRetry, onPromptAction, onErrorAction, resolvedMounts, onViewPhase }),
-    [strings, tokens, onToggle, onRetry, onPromptAction, onErrorAction, resolvedMounts, onViewPhase],
+    () => ({ strings, tokens, onToggle, onRetry, onPromptAction, onErrorAction, resolvedMounts, onViewPhase, onViewRef }),
+    [strings, tokens, onToggle, onRetry, onPromptAction, onErrorAction, resolvedMounts, onViewPhase, onViewRef],
   );
 
   // Inverted-list data: reversed plan, newest at index 0 (the visual