@miragon/mcp-toolkit-ui 2.7.0 → 2.8.1

package/src/app/mcp-app-view-chrome.test.tsx

@@ -14,7 +14,8 @@ import {
   type ViewData,
   type ViewToolbarProps,
 } from "./mcp-app-view-chrome.js"
-import { ViewPlaceholder } from "./mcp-app-view-states.js"
+import { ViewPlaceholder, type DescribeViewError } from "./mcp-app-view-states.js"
+import { VIEW_FOCUS_TARGET } from "./use-build-mode-focus.js"
 import { resolveViewLifecycle, RETRY_IDLE, type ViewLifecycleInput } from "./view-lifecycle.js"
 
 const en = TOOLKIT_MESSAGES.en.view
@@ -102,6 +103,90 @@ describe("ViewPlaceholder — one rendering per lifecycle phase (toolkit#176)",
     expect(html).toContain("HTTP 503")
   })
 
+  it("blocked, writing tool: a notice that the action ran, no button that would run it again (CI §9)", () => {
+    // The exact input McpAppView feeds when the policy keeps a stripped
+    // result of a tool reported as writing from being re-run.
+    const lifecycle = resolveViewLifecycle({
+      hasViewData: false,
+      callStatus: "pending",
+      cancelled: false,
+      callErrorReason: undefined,
+      recoveryFailed: false,
+      recoveryBlocked: true,
+      toolWrites: true,
+      retryState: RETRY_IDLE,
+      slow: false,
+      canRetry: true,
+    } satisfies ViewLifecycleInput)
+    expect(lifecycle).toEqual({
+      phase: "error",
+      reason: undefined,
+      canRetry: false,
+      kind: "blocked",
+    })
+    const html = decodeEntities(placeholder(lifecycle))
+    // Nothing failed: the info tone and a polite status, not a danger alert.
+    expect(html).toContain('data-tone="info"')
+    expect(html).toContain('role="status"')
+    expect(html).not.toContain('role="alert"')
+    expect(html).toContain("lucide-info")
+    expect(html).toContain(en.blockedTitle)
+    expect(html).toContain(en.blockedHintNoRetry)
+    expect(html).not.toContain(en.errorTitle)
+    expect(html).not.toContain(en.errorHint)
+    expect(html).not.toContain("<button")
+    expect(html).not.toContain("<details")
+    const german = decodeEntities(placeholder(lifecycle, de))
+    expect(german).toContain(de.blockedTitle)
+    expect(german).toContain(de.blockedHintNoRetry)
+    expect(german).not.toContain("<button")
+  })
+
+  it("blocked, tool not reported as writing: the notice offers to load the view, in its own words", () => {
+    const lifecycle = {
+      phase: "error",
+      reason: undefined,
+      canRetry: true,
+      kind: "blocked",
+    } as const
+    const html = decodeEntities(placeholder(lifecycle))
+    expect(html).toContain(en.blockedTitle)
+    expect(html).toContain(en.blockedHint)
+    expect(html).not.toContain(en.blockedHintNoRetry)
+    expect(html).toContain(`${en.blockedRetry}</button>`)
+    expect(html).not.toContain(`${en.retry}</button>`)
+    expect(decodeEntities(placeholder(lifecycle, de))).toContain(`${de.blockedRetry}</button>`)
+  })
+
+  it("describeError tells a failure from a block, and can word either", () => {
+    const seen: unknown[] = []
+    const describeError: DescribeViewError = (reason, info) => {
+      seen.push([reason, info])
+      return info?.kind === "blocked" ? { description: "Ask the operator." } : undefined
+    }
+    const render = (lifecycle: Parameters<typeof ViewPlaceholder>[0]["lifecycle"]) =>
+      decodeEntities(
+        renderToStaticMarkup(
+          <ViewPlaceholder
+            lifecycle={lifecycle}
+            labels={en}
+            onRetry={noop}
+            describeError={describeError}
+          />,
+        ),
+      )
+    const blocked = render({ phase: "error", reason: undefined, canRetry: false, kind: "blocked" })
+    expect(blocked).toContain(en.blockedTitle)
+    expect(blocked).toContain("Ask the operator.")
+    expect(blocked).not.toContain(en.blockedHintNoRetry)
+    const failed = render({ phase: "error", reason: "HTTP 503", canRetry: true })
+    expect(failed).toContain(en.errorHint)
+    expect(seen).toEqual([
+      [undefined, { kind: "blocked" }],
+      ["HTTP 503", { kind: "failed" }],
+    ])
+  })
+
   it("cancelled: the cancellation notice, no skeleton, no retry", () => {
     const html = placeholder({ phase: "cancelled" })
     expect(html).toContain(en.cancelled)
@@ -208,6 +293,8 @@ describe("ViewToolbar", () => {
     expect(html).toContain("lucide-pencil")
     const edit = openingTags(html, "button")[0] ?? ""
     expectChromeButton(edit)
+    // The focus target the builder hands the focus back to when it closes.
+    expect(VIEW_FOCUS_TARGET).toBe(`[data-slot="${attribute(edit, "data-slot")}"]`)
   })
 
   it("titles the view once: show (configurable level), hide, or slot", () => {
@@ -238,6 +325,59 @@ describe("ViewToolbar", () => {
     expect(html).toContain(`aria-label="${de.refresh}"`)
     expect(html).toContain(`aria-label="${de.enterFullscreen}"`)
   })
+
+  it("stamps the time of data the view re-loaded itself, in words that carry its meaning (toolkit#176 N23)", () => {
+    expect(toolbar()).not.toContain('data-slot="view-data-as-of"')
+    const html = toolbar({ dataAsOf: "2:32 PM" })
+    const stamp = openingTags(html, "p").find(
+      (t) => attribute(t, "data-slot") === "view-data-as-of",
+    )
+    expect(stamp).toBeDefined()
+    expect(attribute(stamp ?? "", "class")).toContain("text-muted-foreground")
+    // Visible text only: no hover-only tooltip, no screen-reader-only extra
+    // (touch and keyboard users read exactly what everyone reads, once).
+    expect(attribute(stamp ?? "", "title")).toBeUndefined()
+    expect(html).not.toContain("sr-only")
+    expect(html).toContain(`>${en.dataAsOf("2:32 PM")}</p>`)
+    expect(en.dataAsOf("2:32 PM")).toBe("Reloaded at 2:32 PM")
+    expect(toolbar({ dataAsOf: "14:32", labels: de })).toContain(`>${de.dataAsOf("14:32")}</p>`)
+  })
+
+  it("puts the stamp under the title, never beside the controls, and the controls never shrink", () => {
+    const html = toolbar({ dataAsOf: "14:32", builderAvailable: true })
+    const bar = openingTags(html, "div")
+    // [toolbar, heading column, controls]: the stamp is the column's second line.
+    expect(bar.map((t) => attribute(t, "data-slot") ?? "")).toEqual([
+      "view-toolbar",
+      "view-heading",
+      "",
+    ])
+    expect(attribute(bar[1] ?? "", "class")).toBe("min-w-0 flex-1")
+    expect(html).toMatch(
+      /data-slot="view-heading"[^>]*><h2[^>]*>Process definitions<\/h2><p data-slot="view-data-as-of"/,
+    )
+    expect((attribute(bar[2] ?? "", "class") ?? "").split(" ")).toEqual(
+      expect.arrayContaining(["ml-auto", "shrink-0"]),
+    )
+    expect(attribute(bar[2] ?? "", "class")).not.toContain("min-w-0")
+    // Without a stamp the title sits straight in the row, as before.
+    const plain = toolbar({ builderAvailable: true })
+    expect(plain).not.toContain('data-slot="view-heading"')
+    expect(plain).toMatch(/data-slot="view-toolbar"[^>]*><h2/)
+    // The slot title takes the stamp under it as well.
+    const slot = toolbar({ titleMode: "slot", renderTitle: (t) => t, dataAsOf: "14:32" })
+    expect(slot).toMatch(/data-slot="view-heading"[^>]*><div[^>]*>Process definitions<\/div><p/)
+  })
+
+  it("keeps the bar for the stamp alone", () => {
+    const bare = {
+      canFullscreen: false,
+      titleMode: "hide" as const,
+      viewData: { ...view, _refreshParams: undefined },
+    }
+    expect(toolbar(bare)).toBe("")
+    expect(toolbar({ ...bare, dataAsOf: "14:32" })).toContain('data-slot="view-data-as-of"')
+  })
 })
 
 describe("toolbarControls / fullscreenAvailable", () => {

package/src/app/mcp-app-view-chrome.tsx

@@ -79,7 +79,7 @@ export function isCompleteViewData(value: unknown): value is ViewData {
   return Boolean(v?.context && v?.layout)
 }
 
-/** What the LayoutBuilder hands back on Done. */
+/** What the LayoutBuilder hands back on Apply. */
 export interface BuilderCommit {
   layout: LayoutConfig
   keys?: Record<string, unknown>
@@ -135,6 +135,13 @@ export interface ViewToolbarProps {
   onRefresh: () => Promise<void>
   onEnterBuildMode: () => void
   onToggleFullscreen: () => Promise<void>
+  /**
+   * The pre-formatted time of a view that loaded its data again on its own
+   * (toolkit#176 N23): the toolbar stamps it in a quiet line under the title,
+   * so the figures read as live data of that time, not the result the chat
+   * answered from.
+   */
+  dataAsOf?: string
 }
 
 /** The toolbar title per {@link ViewTitleMode}: a heading, the consumer's slot, or nothing. */
@@ -158,6 +165,39 @@ function ToolbarTitle({
   )
 }
 
+/**
+ * The title, and under it the stamp of data the view re-loaded itself. The
+ * stamp is a second line of the title column, never an item beside the
+ * controls: the title keeps the row's width (it is the user's orientation),
+ * and the stamp truncates only against its own column. Its words carry its
+ * meaning, so it needs no tooltip that touch and keyboard users never reach.
+ * Without a stamp the title renders as before, straight in the row.
+ */
+function ToolbarHeading({
+  title,
+  mode,
+  level,
+  renderTitle,
+  stamp,
+}: {
+  title: string | undefined
+  mode: ViewTitleMode
+  level: ViewTitleLevel
+  renderTitle?: (title: string | undefined) => ReactNode
+  stamp: string | undefined
+}) {
+  const heading = <ToolbarTitle title={title} mode={mode} level={level} renderTitle={renderTitle} />
+  if (!stamp) return heading
+  return (
+    <div data-slot="view-heading" className="min-w-0 flex-1">
+      {heading}
+      <p data-slot="view-data-as-of" className="text-muted-foreground truncate text-sm">
+        {stamp}
+      </p>
+    </div>
+  )
+}
+
 /** Which toolbar controls render — pure, so the gates are unit-testable. */
 export function toolbarControls(input: {
   viewData: Pick<ViewData, "_refreshParams" | "layout" | "title">
@@ -250,7 +290,9 @@ function FullscreenButton({
  * `aria-label`; Fullscreen renders only when the host offers it. All three are
  * chrome buttons in the CI pattern (CI §8: surface, border, shadow-1, blue
  * hover; {@link CHROME_BUTTON}). A 16 px inset keeps the bar off the frame
- * edge, also in fullscreen.
+ * edge, also in fullscreen. The controls never shrink; the stamp of re-loaded
+ * data sits under the title ({@link ToolbarHeading}), so neither the title
+ * nor the stamp competes with the controls for width.
  */
 export function ViewToolbar({
   hidden,
@@ -266,21 +308,29 @@ export function ViewToolbar({
   onRefresh,
   onEnterBuildMode,
   onToggleFullscreen,
+  dataAsOf,
 }: ViewToolbarProps) {
   const show = toolbarControls({ viewData, builderAvailable, canFullscreen, titleMode })
-  if (hidden || !show.any) return null
+  if (hidden || (!show.any && !dataAsOf)) return null
   return (
     <LucideProvider strokeWidth={DENSE_ICON_STROKE}>
       <div data-slot="view-toolbar" className="flex min-h-12 items-center gap-2 px-4 py-2">
-        <ToolbarTitle
+        <ToolbarHeading
           title={viewData.title}
           mode={titleMode}
           level={titleLevel}
           renderTitle={renderTitle}
+          stamp={dataAsOf ? labels.dataAsOf(dataAsOf) : undefined}
         />
         <div className="ml-auto flex shrink-0 items-center gap-1">
           {show.edit && (
-            <Button type="button" {...CHROME_BUTTON} size="sm" onClick={onEnterBuildMode}>
+            <Button
+              type="button"
+              {...CHROME_BUTTON}
+              size="sm"
+              data-slot="view-edit"
+              onClick={onEnterBuildMode}
+            >
               <Pencil aria-hidden="true" />
               {labels.build}
             </Button>
@@ -354,7 +404,7 @@ export function StepErrors({
                   {human ? (
                     <span className="font-medium">{human}</span>
                   ) : (
-                    <span className="font-mono text-xs">{ref.step ?? ref.id}</span>
+                    <span className="text-small font-mono">{ref.step ?? ref.id}</span>
                   )}
                 </li>
               ))}

package/src/app/mcp-app-view-states.tsx

@@ -2,17 +2,27 @@
  * The pre-payload states of `McpAppView`, one per lifecycle phase
  * (`view-lifecycle.ts`): waiting (skeleton + status line + slow hint),
  * cancelled, and error (icon, title, what to do, raw reason under "Details",
- * retry when the originating tool is known). Hook-free and SSR-renderable, so
- * each phase is pinned by a test.
+ * retry when the originating tool is known). A `blocked` error is a notice in
+ * the info tone, not a failure: the tool ran, but the chat did not pass its
+ * result to the view. Hook-free and SSR-renderable, so each phase is pinned
+ * by a test.
  */
-import { ErrorState } from "../components/ErrorState.js"
+import { ErrorState, type ErrorStateTone } from "../components/ErrorState.js"
 import { Skeleton } from "../primitives/skeleton.js"
 import type { McpAppViewLabels } from "./mcp-app-view-chrome.js"
-import type { ViewLifecycle } from "./view-lifecycle.js"
+import type { ViewErrorKind, ViewLifecycle } from "./view-lifecycle.js"
 
-/** Human text for a raw error reason (e.g. map "503" to "the engine is down"). */
+export type { ViewErrorKind } from "./view-lifecycle.js"
+
+/**
+ * Human text for a raw error reason (e.g. map "503" to "the engine is down").
+ * `info.kind` tells a failure (`"failed"`) from a result the chat did not pass
+ * to the view (`"blocked"`, no reason); return `undefined` to keep the
+ * toolkit's words for that state.
+ */
 export type DescribeViewError = (
   reason: string | undefined,
+  info?: { kind: ViewErrorKind },
 ) => { title?: string; description?: string } | undefined
 
 export function ViewPlaceholder({
@@ -41,6 +51,7 @@ export function ViewPlaceholder({
     case "error":
       return (
         <ViewErrorState
+          kind={lifecycle.kind}
           reason={lifecycle.reason}
           canRetry={lifecycle.canRetry}
           labels={labels}
@@ -69,30 +80,59 @@ function ViewWaiting({ slow, labels }: { slow: boolean; labels: Required<McpAppV
   )
 }
 
+/** The words and tone of an error phase; the hint never promises a retry the state does not offer. */
+function errorStateCopy(
+  kind: ViewErrorKind,
+  canRetry: boolean,
+  labels: Required<McpAppViewLabels>,
+): { tone: ErrorStateTone; role: "alert" | "status"; title: string; hint: string; retry: string } {
+  if (kind === "blocked") {
+    // Nothing failed: a quiet notice that says what happened and what to do.
+    return {
+      tone: "info",
+      role: "status",
+      title: labels.blockedTitle,
+      hint: canRetry ? labels.blockedHint : labels.blockedHintNoRetry,
+      retry: labels.blockedRetry,
+    }
+  }
+  return {
+    tone: "danger",
+    role: "alert",
+    title: labels.errorTitle,
+    hint: canRetry ? labels.errorHint : labels.errorHintNoRetry,
+    retry: labels.retry,
+  }
+}
+
 function ViewErrorState({
+  kind = "failed",
   reason,
   canRetry,
   labels,
   onRetry,
   describeError,
 }: {
+  /** Absent for a failure (see `ViewLifecycle`). */
+  kind: ViewErrorKind | undefined
   reason: string | undefined
   canRetry: boolean
   labels: Required<McpAppViewLabels>
   onRetry: () => void
   describeError?: DescribeViewError
 }) {
-  const human = describeError?.(reason)
-  // The hint never promises a retry the state does not offer.
-  const hint = canRetry ? labels.errorHint : labels.errorHintNoRetry
+  const human = describeError?.(reason, { kind })
+  const copy = errorStateCopy(kind, canRetry, labels)
   return (
     <div className="px-4 py-4">
       <ErrorState
-        title={human?.title ?? labels.errorTitle}
-        description={human?.description ?? hint}
+        tone={copy.tone}
+        role={copy.role}
+        title={human?.title ?? copy.title}
+        description={human?.description ?? copy.hint}
         details={reason}
         detailsLabel={labels.errorDetails}
-        retryLabel={labels.retry}
+        retryLabel={copy.retry}
         onRetry={canRetry ? onRetry : undefined}
       />
     </div>

package/src/app/mcp-app-view.effects.test.tsx

@@ -0,0 +1,292 @@
+// @vitest-environment happy-dom
+import { ToolError } from "mcp-use/react"
+import { afterEach, beforeEach, describe, expect, it, vi, type Mock } from "vitest"
+import { createToolResultObserver, type ToolResultObserver } from "../lib/tool-result-observer.js"
+import { TOOLKIT_MESSAGES } from "../locale/toolkit-messages.js"
+import { advanceTimers, inAct, renderWithEffects, type EffectRender } from "../render-effects.js"
+import { createStandaloneHostBridge, HostBridgeProvider } from "./host-bridge.js"
+import { McpAppView } from "./mcp-app-view.js"
+import type { BuilderCommit, ViewData } from "./mcp-app-view-chrome.js"
+
+/**
+ * McpAppView's lifecycle with its effects running (toolkit#176 K13, N23): the
+ * view takes the document's tool-result observer by default, so a slow tool
+ * on a compliant host is never re-run and a stripped result re-runs from the
+ * observer's notification alone; and a payload the view re-loaded itself (a
+ * recovery, a retry after a result the chat got, a refresh, an Apply from
+ * the view builder) carries the data-as-of stamp and its model-context line.
+ * The SSR suite
+ * (`mcp-app-view.test.tsx`) pins every state's markup.
+ */
+
+const host = vi.hoisted(
+  (): { tool: Record<string, unknown>; observer: ToolResultObserver | null } => ({
+    tool: {},
+    observer: null,
+  }),
+)
+
+/** The commit the stubbed builder hands back on Apply (`toExitCommit` in the real one). */
+const builder = vi.hoisted((): { commit: BuilderCommit | undefined } => ({ commit: undefined }))
+
+// The builder's own UI is not this suite's subject: a stub hands McpAppView
+// the commit Apply would, so the test drives only the view's wiring of it.
+vi.mock(import("./layout-builder.js"), async (importOriginal) => {
+  const actual = await importOriginal()
+  const { createElement } = await import("react")
+  const LayoutBuilder: typeof actual.LayoutBuilder = ({ onExit }) =>
+    createElement("button", { type: "button", onClick: () => onExit?.(builder.commit) }, "Apply")
+  return { ...actual, LayoutBuilder }
+})
+
+vi.mock(import("../lib/tool-result-observer.js"), async (importOriginal) => {
+  const actual = await importOriginal()
+  return { ...actual, installToolResultObserver: () => host.observer }
+})
+
+vi.mock(import("mcp-use/react"), async (importOriginal) => {
+  const actual = await importOriginal()
+  const context = {
+    locale: "en-US",
+    timeZone: "UTC",
+    safeArea: { top: 0, right: 0, bottom: 0, left: 0 },
+    hostContext: { toolInfo: { tool: { name: "render-view" } } },
+  }
+  const displayMode = {
+    displayMode: "inline",
+    availableDisplayModes: ["inline"],
+    requestDisplayMode: () => Promise.resolve(),
+  }
+  return {
+    ...actual,
+    useToolContext: (() => host.tool) as unknown as typeof actual.useToolContext,
+    useHostContext: (() => context) as unknown as typeof actual.useHostContext,
+    useDisplayMode: (() => displayMode) as unknown as typeof actual.useDisplayMode,
+  }
+})
+
+const en = TOOLKIT_MESSAGES.en.view
+const NOW = Date.UTC(2026, 9, 11, 14, 32)
+
+const VIEW: ViewData = {
+  title: "Process definitions",
+  context: { keys: {}, stepIds: ["kpi"], stepData: {}, errors: [] },
+  layout: { rows: [{ row: [{ widget: "demo:probe" }] }] },
+  _refreshParams: { layout: { rows: [] }, steps: [{ id: "kpi", step: "demo:kpis" }] },
+}
+
+/** A host channel the observer listens on, with the SEP-1865 messages a host sends. */
+function fakeHost() {
+  const channel = new EventTarget()
+  host.observer = createToolResultObserver(channel)
+  const send = (data: unknown) =>
+    inAct(() => channel.dispatchEvent(new MessageEvent("message", { data })))
+  const notify = (method: string, params: Record<string, unknown>) =>
+    send({ jsonrpc: "2.0", method, params })
+  return {
+    handshake: () =>
+      send({
+        jsonrpc: "2.0",
+        id: 1,
+        result: { protocolVersion: "2026-01-26", hostCapabilities: {} },
+      }),
+    toolInput: (args: Record<string, unknown>) =>
+      notify("ui/notifications/tool-input", { arguments: args }),
+    strippedResult: () =>
+      notify("ui/notifications/tool-result", { content: [{ type: "text", text: "Rendered." }] }),
+    structuredResult: (structuredContent: unknown) =>
+      notify("ui/notifications/tool-result", { content: [], structuredContent }),
+  }
+}
+
+type CallTool = (name: string, args: Record<string, unknown>) => Promise<unknown>
+
+let callTool: Mock<CallTool>
+let modelContext: string[]
+let mounted: EffectRender | null = null
+
+async function render() {
+  const bridge = createStandaloneHostBridge({
+    callTool: (name, args) => callTool(name, args),
+    onModelContext: (text) => modelContext.push(text),
+  })
+  mounted = await renderWithEffects(
+    <HostBridgeProvider bridge={bridge}>
+      <McpAppView widgets={{ "demo:probe": () => <span>probe</span> }} />
+    </HostBridgeProvider>,
+  )
+  return mounted
+}
+
+const stamp = (view: EffectRender) =>
+  view.container.querySelector('[data-slot="view-data-as-of"]')?.textContent ?? null
+
+const button = (view: EffectRender, name: string): HTMLElement => {
+  const found = [...view.container.querySelectorAll("button")].find(
+    (b) => b.textContent === name || b.getAttribute("aria-label") === name,
+  )
+  if (!found) throw new Error(`no button "${name}"`)
+  return found
+}
+
+const click = (target: HTMLElement) => inAct(() => target.click())
+
+const toolCalls = (name: string) => callTool.mock.calls.filter(([called]) => called === name)
+
+beforeEach(() => {
+  builder.commit = undefined
+  vi.useFakeTimers()
+  vi.setSystemTime(NOW)
+  host.tool = { status: "pending", toolInput: { id: 7 }, toolOutput: undefined }
+  host.observer = null
+  modelContext = []
+  callTool = vi.fn<CallTool>(() => Promise.resolve({ structuredContent: VIEW }))
+})
+
+afterEach(async () => {
+  await mounted?.unmount()
+  mounted = null
+  vi.useRealTimers()
+})
+
+describe("McpAppView recovery with its effects (K13)", () => {
+  it("keep: a delivered view is never re-run", async () => {
+    const channel = fakeHost()
+    await channel.handshake()
+    await channel.toolInput({ id: 7 })
+    await channel.structuredResult(VIEW)
+    host.tool = { status: "ready", toolInput: { id: 7 }, toolOutput: VIEW }
+    const view = await render()
+    await advanceTimers(vi.advanceTimersByTime, 10_000)
+    expect(callTool).not.toHaveBeenCalled()
+    expect(view.container.querySelector('[data-slot="view-toolbar"]')).not.toBeNull()
+    expect(stamp(view), "the host's own payload").toBeNull()
+  })
+
+  it("slow: a compliant host still answering keeps the view waiting, never re-run", async () => {
+    const channel = fakeHost()
+    await channel.handshake()
+    await channel.toolInput({ id: 7 })
+    const view = await render()
+    await advanceTimers(vi.advanceTimersByTime, 2_501)
+    await advanceTimers(vi.advanceTimersByTime, 10_000)
+    expect(callTool).not.toHaveBeenCalled()
+    expect(view.container.querySelector('[data-slot="skeleton"]')).not.toBeNull()
+  })
+
+  it("strip: the observer's notification alone re-runs the call once, with its complete input, and stamps it", async () => {
+    const channel = fakeHost()
+    await channel.handshake()
+    const view = await render()
+    await channel.toolInput({ id: 7, page: 2 })
+    await channel.strippedResult()
+    expect(callTool).toHaveBeenCalledTimes(1)
+    expect(callTool).toHaveBeenCalledWith("render-view", { id: 7, page: 2 })
+    expect(stamp(view)).toBe("Reloaded at 2:32 PM")
+    expect(modelContext.at(-1)).toMatch(
+      /^The view of render-view re-ran the tool at 2026-10-11T14:32:00\.000Z because the host did not pass/,
+    )
+  })
+})
+
+describe("McpAppView data-as-of stamp on a user's re-run (N23)", () => {
+  it("a retry after a failed recovery is stamped: the chat answered from the original call", async () => {
+    const channel = fakeHost()
+    await channel.handshake()
+    callTool.mockRejectedValueOnce(new Error("503"))
+    const view = await render()
+    await channel.toolInput({ id: 7 })
+    await channel.strippedResult()
+    expect(view.container.querySelector('[role="alert"]')).not.toBeNull()
+    vi.setSystemTime(NOW + 60_000)
+    await click(button(view, en.retry))
+    expect(toolCalls("render-view")).toHaveLength(2)
+    expect(stamp(view)).toBe("Reloaded at 2:33 PM")
+    expect(modelContext.at(-1)).toMatch(/re-ran the tool at 2026-10-11T14:33:00\.000Z/)
+  })
+
+  it("a retry after a failed call is not: the model never had figures", async () => {
+    host.tool = {
+      status: "error",
+      error: new ToolError({ isError: true, content: [{ type: "text", text: "[503] down" }] }),
+      toolInput: { id: 7 },
+    }
+    const view = await render()
+    await click(button(view, en.retry))
+    expect(toolCalls("render-view")).toHaveLength(1)
+    expect(view.container.querySelector('[data-slot="view-toolbar"]')).not.toBeNull()
+    expect(stamp(view)).toBeNull()
+    expect(modelContext.some((line) => line.includes("re-ran the tool"))).toBe(false)
+  })
+
+  it("a refresh is stamped and told to the model as the user's refresh", async () => {
+    host.tool = { status: "ready", toolInput: { id: 7 }, toolOutput: VIEW }
+    const view = await render()
+    expect(stamp(view)).toBeNull()
+    vi.setSystemTime(NOW + 38 * 60_000)
+    await click(button(view, en.refresh))
+    expect(toolCalls("refresh-view")).toEqual([["refresh-view", VIEW._refreshParams]])
+    expect(stamp(view)).toBe("Reloaded at 3:10 PM")
+    expect(modelContext.at(-1)).toBe(
+      "The view of render-view was refreshed by the user at 2026-10-11T15:10:00.000Z; its figures " +
+        "are live as of then and can differ from the original result.",
+    )
+  })
+})
+
+describe("McpAppView data-as-of stamp on a builder Apply (N23)", () => {
+  /** The view as a builder-enabled server delivers it. */
+  const EDITABLE: ViewData = { ...VIEW, builderAvailable: true }
+  /** The builder's live context: its catalogue call ran the steps again. */
+  const LIVE: ViewData["context"] = {
+    keys: { region: "north" },
+    stepIds: ["kpi"],
+    stepData: {
+      kpi: { data: { open: 12 }, keys: {}, _app: "demo", _dataType: "demo:kpis" },
+    },
+    errors: [],
+  }
+  const edit = async (view: EffectRender, commit: BuilderCommit) => {
+    builder.commit = commit
+    await click(button(view, en.build))
+    await click(button(view, "Apply"))
+  }
+
+  it("an Apply with the builder's live figures is stamped and told to the model as the user's edit", async () => {
+    host.tool = { status: "ready", toolInput: { id: 7 }, toolOutput: EDITABLE }
+    const view = await render()
+    expect(stamp(view), "the host's own payload").toBeNull()
+    vi.setSystemTime(NOW + 5 * 60_000)
+    await edit(view, { layout: EDITABLE.layout!, context: LIVE })
+    expect(stamp(view)).toBe("Reloaded at 2:37 PM")
+    expect(modelContext.at(-1)).toBe(
+      "The view of render-view was edited by the user in the view builder, which loaded its data " +
+        "again at 2026-10-11T14:37:00.000Z; its figures are live as of then and can differ from " +
+        "the original result.",
+    )
+  })
+
+  it("an Apply after a refresh moves the stamp to the builder's figures", async () => {
+    host.tool = { status: "ready", toolInput: { id: 7 }, toolOutput: EDITABLE }
+    callTool.mockResolvedValue({ structuredContent: EDITABLE })
+    const view = await render()
+    vi.setSystemTime(NOW + 60_000)
+    await click(button(view, en.refresh))
+    expect(stamp(view)).toBe("Reloaded at 2:33 PM")
+    vi.setSystemTime(NOW + 5 * 60_000)
+    await edit(view, { layout: EDITABLE.layout!, context: LIVE })
+    expect(stamp(view), "the stamp of the refresh above the builder's figures").toBe(
+      "Reloaded at 2:37 PM",
+    )
+  })
+
+  it("an Apply without a context keeps the shown figures, and with them their stamp", async () => {
+    host.tool = { status: "ready", toolInput: { id: 7 }, toolOutput: EDITABLE }
+    const view = await render()
+    vi.setSystemTime(NOW + 5 * 60_000)
+    await edit(view, { layout: EDITABLE.layout!, title: "Renamed" })
+    expect(view.container.textContent).toContain("Renamed")
+    expect(stamp(view)).toBeNull()
+    expect(modelContext.some((line) => line.includes("view builder"))).toBe(false)
+  })
+})