@miragon/mcp-toolkit-ui 2.6.0 → 2.7.0

package/src/components/feedback-states.test.tsx

@@ -0,0 +1,225 @@
+import type { ReactNode } from "react"
+import { renderToStaticMarkup } from "react-dom/server"
+import { CircleCheck } from "lucide-react"
+import { describe, expect, it } from "vitest"
+import { LocaleProvider } from "../locale/locale-provider.js"
+import { TOOLKIT_MESSAGES } from "../locale/toolkit-messages.js"
+import { FOCUS_RING } from "../lib/focus-ring.js"
+import { createToast } from "../lib/toast-model.js"
+import { TONE_BORDER, TONE_ICON, TONE_SOFT } from "../lib/tone-utils.js"
+import { attribute, openingTags } from "../render-scan.js"
+import { EmptyState } from "./EmptyState.js"
+import { ErrorState } from "./ErrorState.js"
+import { ToastProvider, ToastViewport, useToast, type ToastApi } from "./Toast.js"
+
+/**
+ * Accessibility contract of the feedback primitives, pinned on their SSR
+ * markup (the house render path — no jsdom): roles, live regions, accessible
+ * names in the active locale, native focusable controls, nothing that steals
+ * focus.
+ */
+
+const de = TOOLKIT_MESSAGES.de
+const inGerman = (node: ReactNode) =>
+  renderToStaticMarkup(<LocaleProvider locale="de-DE">{node}</LocaleProvider>)
+const noop = (): void => {}
+
+/** No positive tabindex and no autofocus anywhere — feedback never steals focus. */
+function expectNoFocusTheft(html: string) {
+  expect(html).not.toMatch(/autofocus/i)
+  for (const value of html.match(/tabindex="(-?\d+)"/gi) ?? []) {
+    expect(Number(/"(-?\d+)"/.exec(value)?.[1])).toBeLessThanOrEqual(0)
+  }
+}
+
+describe("Toast", () => {
+  const toasts = [
+    createToast(1, { tone: "success", title: "Job retried." }),
+    createToast(2, { tone: "danger", title: "Retry failed.", description: "Engine down (503)" }),
+  ]
+
+  it("renders ONE persistent live region: role=status, aria-live=polite, a localized name", () => {
+    const html = inGerman(<ToastViewport toasts={toasts} onDismiss={noop} />)
+    const [region, ...others] = openingTags(html, "div").filter((t) => /role="status"/.test(t))
+    expect(others).toHaveLength(0)
+    expect(attribute(region ?? "", "aria-live")).toBe("polite")
+    expect(attribute(region ?? "", "aria-label")).toBe(de.common.notifications)
+    // An empty stack keeps the region mounted, so the first toast is announced.
+    const empty = inGerman(<ToastViewport toasts={[]} onDismiss={noop} />)
+    expect(empty).toContain('role="status"')
+    expect(empty).toContain('aria-live="polite"')
+  })
+
+  it("shows the status as edge + icon next to plain text, never as coloured text", () => {
+    const html = inGerman(<ToastViewport toasts={toasts} onDismiss={noop} />)
+    const cards = openingTags(html, "div").filter((t) => /data-slot="toast"/.test(t))
+    expect(cards.map((t) => attribute(t, "data-tone"))).toEqual(["success", "danger"])
+    expect(cards[0]).toMatch(/border-l-success/)
+    expect(cards[1]).toMatch(/border-l-danger/)
+    for (const card of cards) expect(card).not.toMatch(/\btext-(success|danger|warning|info)\b/)
+    // The edge survives the dark 3:1 rim (a later dark: rule would paint over it).
+    expect(cards[0]).toMatch(/dark:border-input/)
+    expect(cards[0]).toMatch(/dark:border-l-success/)
+    // Icons are decorative and drawn in the tone colour; the text carries the message.
+    const svgs = openingTags(html, "svg")
+    for (const svg of svgs) expect(attribute(svg, "aria-hidden")).toBe("true")
+    expect(attribute(svgs[0] ?? "", "class")).toContain(TONE_ICON.success)
+    expect(attribute(svgs[2] ?? "", "class")).toContain(TONE_ICON.danger)
+    expect(html).toContain("Job retried.")
+    expect(html).toContain("Engine down (503)")
+  })
+
+  it("gives every toast a native close button named in the locale, and steals no focus", () => {
+    const html = inGerman(<ToastViewport toasts={toasts} onDismiss={noop} />)
+    const buttons = openingTags(html, "button")
+    expect(buttons).toHaveLength(2)
+    for (const b of buttons) {
+      expect(attribute(b, "type")).toBe("button")
+      expect(attribute(b, "aria-label")).toBe(de.common.dismiss)
+      expect(attribute(b, "class")).toContain(FOCUS_RING)
+    }
+    expectNoFocusTheft(html)
+  })
+
+  it("nests idempotently: one provider, one viewport", () => {
+    const html = renderToStaticMarkup(
+      <ToastProvider>
+        <ToastProvider>
+          <p>body</p>
+        </ToastProvider>
+      </ToastProvider>,
+    )
+    expect(html.match(/data-slot="toast-viewport"/g)).toHaveLength(1)
+    expect(html).toContain("<p>body</p>")
+  })
+
+  it("useToast outside a provider is a safe no-op", () => {
+    let api: ToastApi | undefined
+    function Probe() {
+      api = useToast()
+      return null
+    }
+    renderToStaticMarkup(<Probe />)
+    expect(api?.show({ title: "x" })).toBe(-1)
+    expect(() => api?.dismiss(1)).not.toThrow()
+  })
+})
+
+describe("EmptyState", () => {
+  it("is static (no live region), titles with h3 by default, hides its icon from AT", () => {
+    const html = inGerman(
+      <EmptyState
+        icon={<CircleCheck />}
+        tone="success"
+        title="Keine offenen Incidents"
+        description="Alles erledigt."
+      />,
+    )
+    expect(html).not.toMatch(/role="(status|alert)"|aria-live/)
+    expect(html).toMatch(/<h3[^>]*>Keine offenen Incidents<\/h3>/)
+    const iconSlot = openingTags(html, "div").find((t) => /aria-hidden="true"/.test(t))
+    // The success tone on the icon (TONE_ICON), never on the words.
+    expect(iconSlot).toContain(TONE_ICON.success)
+    expect(html).not.toMatch(/text-success-ink/)
+    expect(html).toContain("Alles erledigt.")
+  })
+
+  it("sizes an icon to 24 px but lets a mark keep its own size-* class (the Komet needs room)", () => {
+    const html = renderToStaticMarkup(
+      <EmptyState icon={<svg className="size-12" aria-label="mark" />} title="Willkommen" />,
+    )
+    const slot = openingTags(html, "div").find((t) => /aria-hidden="true"/.test(t)) ?? ""
+    const slotClass = attribute(slot, "class") ?? ""
+    // The default applies only to an SVG without its own size class…
+    expect(slotClass).toContain("[&_svg:not([class*='size-'])]:size-6")
+    // …and never as a clamp that outranks the mark's class (0,1,1 beats 0,1,0).
+    expect(slotClass).not.toMatch(/\[&_svg\]:size-/)
+    expect(html).toContain('<svg class="size-12"')
+  })
+
+  it("takes the heading level of its surface and at most two actions", () => {
+    const html = renderToStaticMarkup(
+      <EmptyState
+        titleAs="h2"
+        title="Nothing here"
+        action={<button type="button">First</button>}
+        secondaryAction={<button type="button">Second</button>}
+      />,
+    )
+    expect(html).toMatch(/<h2[^>]*>Nothing here<\/h2>/)
+    expect(openingTags(html, "button")).toHaveLength(2)
+    expect(renderToStaticMarkup(<EmptyState title="Bare" />)).not.toContain("<button")
+  })
+})
+
+describe("ErrorState", () => {
+  it("announces itself (role=alert) with a heading, the hint, details and a retry in the locale", () => {
+    const html = inGerman(
+      <ErrorState
+        title="Die Ansicht konnte nicht geladen werden"
+        description="Versuch es noch mal."
+        details="[503 ProcessEngineException] Engine is shutting down"
+        onRetry={noop}
+      />,
+    )
+    const root = openingTags(html, "div")[0] ?? ""
+    expect(attribute(root, "role")).toBe("alert")
+    expect(attribute(root, "data-variant")).toBe("block")
+    expect(html).toMatch(/<h2[^>]*>Die Ansicht konnte nicht geladen werden<\/h2>/)
+    // The raw reason sits collapsed in a native disclosure (keyboard-ready).
+    expect(html).toMatch(/<details[^>]*><summary[^>]*>Details<\/summary>/)
+    expect(html).not.toMatch(/<details[^>]*\sopen/)
+    const [retry] = openingTags(html, "button")
+    expect(attribute(retry ?? "", "type")).toBe("button")
+    expect(html).toContain(`${de.common.retry}</button>`)
+    expectNoFocusTheft(html)
+  })
+
+  it("supports a quieter status role, no role at all, and the inline alert form", () => {
+    const status = renderToStaticMarkup(<ErrorState title="Notice" role="status" tone="info" />)
+    expect(attribute(openingTags(status, "div")[0] ?? "", "role")).toBe("status")
+    const none = renderToStaticMarkup(<ErrorState title="Static" role="none" />)
+    expect(attribute(openingTags(none, "div")[0] ?? "", "role")).toBeUndefined()
+    const inline = renderToStaticMarkup(
+      <ErrorState variant="inline" title="Partial" tone="warning" />,
+    )
+    expect(inline).toMatch(/<p[^>]*>Partial<\/p>/)
+    expect(attribute(openingTags(inline, "div")[0] ?? "", "data-tone")).toBe("warning")
+  })
+
+  it.each(["danger", "warning", "info"] as const)(
+    "shows the %s tone as rim, tint and icon; every word on the tint is the foreground (CI §3.3)",
+    (tone) => {
+      const html = renderToStaticMarkup(
+        <ErrorState title="x" description="what to do" details="raw" tone={tone} onRetry={noop} />,
+      )
+      const rootClass = attribute(openingTags(html, "div")[0] ?? "", "class") ?? ""
+      expect(rootClass).toContain(TONE_SOFT[tone])
+      expect(rootClass).toContain(TONE_BORDER[tone])
+      expect(attribute(openingTags(html, "svg")[0] ?? "", "class")).toContain(TONE_ICON[tone])
+      // No quiet text, no ink and no status colour as text anywhere on the tint
+      // (the icons, which carry the tone colour, set aside).
+      const words = html.replace(/<svg[\s\S]*?<\/svg>/g, "")
+      expect(words).not.toMatch(/text-muted-foreground|text-\w+-ink|text-(danger|warning|info)\b/)
+      // The disclosure is a kit control: the kit's opaque focus ring.
+      expect(attribute(openingTags(html, "summary")[0] ?? "", "class")).toContain(FOCUS_RING)
+    },
+  )
+
+  it("has no retry without onRetry, and takes custom labels", () => {
+    expect(renderToStaticMarkup(<ErrorState title="x" />)).not.toContain("<button")
+    const html = renderToStaticMarkup(
+      <ErrorState
+        title="x"
+        details="raw"
+        detailsLabel="Technical"
+        onRetry={noop}
+        retryLabel="Reload"
+        actions={<a href="#help">Help</a>}
+      />,
+    )
+    expect(html).toContain("Technical</summary>")
+    expect(html).toContain("Reload</button>")
+    expect(html).toContain('<a href="#help">Help</a>')
+  })
+})

package/src/components/tone-figures.test.tsx

@@ -0,0 +1,54 @@
+import { renderToStaticMarkup } from "react-dom/server"
+import { describe, expect, it } from "vitest"
+import type { ToneVariant } from "../lib/tone-utils.js"
+import { KpiGrid } from "./KpiGrid.js"
+import { CountPill, LivePill } from "./Pills.js"
+
+/**
+ * Status model (owner decision 2e-f, CI §3.3): coloured digits are retired.
+ * A figure — a KPI value, a trend, a count — stays in the foreground; the tone
+ * shows as a dot, a border or a tint next to it. These components carry
+ * figures, so no tone colour may reach their text (SSR, the house render path).
+ */
+
+const STATUS = ["info", "success", "warning", "danger"] as const
+const TONES: ToneVariant[] = ["neutral", ...STATUS]
+/** Any tone used as a TEXT colour: the raw status colour or its -ink role. */
+const TONE_AS_TEXT = /\btext-(?:success|warning|danger|info)(?:-ink)?\b/
+
+describe("figures never take a tone colour", () => {
+  it("KpiGrid: trend lines and toned cells keep their text in the foreground", () => {
+    const html = renderToStaticMarkup(
+      <KpiGrid
+        cells={[
+          { label: "Up", value: "12", trend: "+12% vs last week", trendDirection: "up" },
+          { label: "Down", value: "3", trend: "-4% vs last week", trendDirection: "down" },
+          { label: "Flat", value: "7", trend: "±0", trendDirection: "flat" },
+          ...STATUS.map((tone) => ({ label: tone, value: "1", tone })),
+        ]}
+      />,
+    )
+    expect(html).not.toMatch(TONE_AS_TEXT)
+    // The tone is still there — as a dot.
+    expect(html).toMatch(/bg-danger\b/)
+    expect(html).toMatch(/bg-success\b/)
+    // A toned trend reads in the foreground, an untoned one stays quiet.
+    expect(html).toMatch(/text-foreground[^"]*"><span aria-hidden="true"[^>]*bg-danger/)
+    expect(html).toMatch(/text-muted-foreground">±0/)
+  })
+
+  it.each(TONES)(
+    "CountPill and LivePill (%s): number and label in the foreground, tone on the rim",
+    (tone) => {
+      const count = renderToStaticMarkup(<CountPill tone={tone}>42</CountPill>)
+      const live = renderToStaticMarkup(<LivePill tone={tone}>Live</LivePill>)
+      for (const html of [count, live]) {
+        expect(html).not.toMatch(TONE_AS_TEXT)
+        if (tone !== "neutral") {
+          expect(html).toContain("text-foreground")
+          expect(html).toContain(`border-${tone}`)
+        }
+      }
+    },
+  )
+})

package/src/fonts.css

@@ -0,0 +1,19 @@
+/*
+ * @miragon/mcp-toolkit-ui/fonts.css — OPT-IN: Geist and Geist Mono, self-hosted
+ * through your bundler (no CDN). Import it next to globals.css/theme.css:
+ *
+ *   @import "@miragon/mcp-toolkit-ui/globals.css";
+ *   @import "@miragon/mcp-toolkit-ui/fonts.css";
+ *
+ * Cost: a bundler that inlines assets (vite-plugin-singlefile, MCP App views)
+ * embeds the woff2 files as base64 in every view. When a server can serve the
+ * files, prefer `fontFaces({ baseUrl })`, which references them by URL (and
+ * allow that origin in the view's CSP resourceDomains). The token stacks
+ * (--font-sans, --font-mono) name both families first, so either path works.
+ * A host's own font stays the fallback behind them: McpToolkitApp moves it
+ * to --host-font-sans/--host-font-mono (adoptHostFontVariables); an app with
+ * its own host-document layer calls that helper after applying the host's
+ * style variables, or the host's --font-sans replaces the whole stack.
+ */
+@import "@fontsource-variable/geist/wght.css";
+@import "@fontsource-variable/geist-mono/wght.css";

package/src/globals.css

@@ -1,168 +1,12 @@
+/*
+ * @miragon/mcp-toolkit-ui/globals.css — the one-line stylesheet for an app
+ * entry: Tailwind, the toolkit's design tokens (./theme.css, Miragon by
+ * default) and the toolkit's own class sources. Fonts are opt-in: add
+ * `@import "@miragon/mcp-toolkit-ui/fonts.css"` or serve them with
+ * `fontFaces()`. A brand overrides the role variables after this import —
+ * see docs/guides/white-labeling.md.
+ */
 @import "tailwindcss";
-@import "tw-animate-css";
-@import "@fontsource-variable/geist";
+@import "./theme.css";
 
 @source "../**/*.{ts,tsx}";
-
-@custom-variant dark (&:is(.dark *));
-
-@theme inline {
-  --font-heading: var(--font-sans);
-  --font-sans: "Geist Variable", sans-serif;
-  --color-sidebar-ring: var(--sidebar-ring);
-  --color-sidebar-border: var(--sidebar-border);
-  --color-sidebar-accent-foreground: var(--sidebar-accent-foreground);
-  --color-sidebar-accent: var(--sidebar-accent);
-  --color-sidebar-primary-foreground: var(--sidebar-primary-foreground);
-  --color-sidebar-primary: var(--sidebar-primary);
-  --color-sidebar-foreground: var(--sidebar-foreground);
-  --color-sidebar: var(--sidebar);
-  --color-chart-5: var(--chart-5);
-  --color-chart-4: var(--chart-4);
-  --color-chart-3: var(--chart-3);
-  --color-chart-2: var(--chart-2);
-  --color-chart-1: var(--chart-1);
-  --color-ring: var(--ring);
-  --color-input: var(--input);
-  --color-border: var(--border);
-  --color-destructive: var(--destructive);
-  --color-accent-foreground: var(--accent-foreground);
-  --color-accent: var(--accent);
-  --color-muted-foreground: var(--muted-foreground);
-  --color-muted: var(--muted);
-  --color-secondary-foreground: var(--secondary-foreground);
-  --color-secondary: var(--secondary);
-  --color-primary-foreground: var(--primary-foreground);
-  --color-primary: var(--primary);
-  --color-popover-foreground: var(--popover-foreground);
-  --color-popover: var(--popover);
-  --color-card-foreground: var(--card-foreground);
-  --color-card: var(--card);
-  --color-foreground: var(--foreground);
-  --color-background: var(--background);
-  /* Semantic status tones — the token surface behind ToneVariant/TONE_* maps.
-     Each tone exposes a readable foreground (`text-danger`) and a tinted
-     surface (`bg-danger-soft`); both carry light + dark values so tone-based
-     components (Pills, KpiGrid, WidgetHeader, FilterBar) re-theme automatically. */
-  --color-danger: var(--danger);
-  --color-danger-soft: var(--danger-soft);
-  --color-warning: var(--warning);
-  --color-warning-soft: var(--warning-soft);
-  --color-success: var(--success);
-  --color-success-soft: var(--success-soft);
-  --color-info: var(--info);
-  --color-info-soft: var(--info-soft);
-  --radius-sm: calc(var(--radius) * 0.6);
-  --radius-md: calc(var(--radius) * 0.8);
-  --radius-lg: var(--radius);
-  --radius-xl: calc(var(--radius) * 1.4);
-  --radius-2xl: calc(var(--radius) * 1.8);
-  --radius-3xl: calc(var(--radius) * 2.2);
-  --radius-4xl: calc(var(--radius) * 2.6);
-}
-
-:root {
-  --background: oklch(1 0 0);
-  --foreground: oklch(0.145 0 0);
-  --card: oklch(1 0 0);
-  --card-foreground: oklch(0.145 0 0);
-  --popover: oklch(1 0 0);
-  --popover-foreground: oklch(0.145 0 0);
-  --primary: oklch(0.205 0 0);
-  --primary-foreground: oklch(0.985 0 0);
-  --secondary: oklch(0.97 0 0);
-  --secondary-foreground: oklch(0.205 0 0);
-  --muted: oklch(0.97 0 0);
-  --muted-foreground: oklch(0.556 0 0);
-  --accent: oklch(0.97 0 0);
-  --accent-foreground: oklch(0.205 0 0);
-  --destructive: oklch(0.577 0.245 27.325);
-  --border: oklch(0.922 0 0);
-  --input: oklch(0.922 0 0);
-  --ring: oklch(0.708 0 0);
-  --chart-1: oklch(0.87 0 0);
-  --chart-2: oklch(0.556 0 0);
-  --chart-3: oklch(0.439 0 0);
-  --chart-4: oklch(0.371 0 0);
-  --chart-5: oklch(0.269 0 0);
-  --radius: 0.625rem;
-  --sidebar: oklch(0.985 0 0);
-  --sidebar-foreground: oklch(0.145 0 0);
-  --sidebar-primary: oklch(0.205 0 0);
-  --sidebar-primary-foreground: oklch(0.985 0 0);
-  --sidebar-accent: oklch(0.97 0 0);
-  --sidebar-accent-foreground: oklch(0.205 0 0);
-  --sidebar-border: oklch(0.922 0 0);
-  --sidebar-ring: oklch(0.708 0 0);
-  /* Semantic status tones (light). Foreground = readable on a card; *-soft =
-     a tinted surface for badges/dots/icon tiles. Neutral tone reuses the
-     muted ramp and needs no dedicated token. */
-  --danger: oklch(0.55 0.21 27.3);
-  --danger-soft: oklch(0.95 0.04 27.3);
-  --warning: oklch(0.62 0.16 70);
-  --warning-soft: oklch(0.95 0.05 80);
-  --success: oklch(0.58 0.15 152);
-  --success-soft: oklch(0.95 0.05 152);
-  --info: oklch(0.55 0.2 255);
-  --info-soft: oklch(0.95 0.04 255);
-}
-
-.dark {
-  --background: oklch(0.145 0 0);
-  --foreground: oklch(0.985 0 0);
-  --card: oklch(0.205 0 0);
-  --card-foreground: oklch(0.985 0 0);
-  --popover: oklch(0.205 0 0);
-  --popover-foreground: oklch(0.985 0 0);
-  --primary: oklch(0.922 0 0);
-  --primary-foreground: oklch(0.205 0 0);
-  --secondary: oklch(0.269 0 0);
-  --secondary-foreground: oklch(0.985 0 0);
-  --muted: oklch(0.269 0 0);
-  --muted-foreground: oklch(0.708 0 0);
-  --accent: oklch(0.269 0 0);
-  --accent-foreground: oklch(0.985 0 0);
-  --destructive: oklch(0.704 0.191 22.216);
-  --border: oklch(1 0 0 / 10%);
-  --input: oklch(1 0 0 / 15%);
-  --ring: oklch(0.556 0 0);
-  --chart-1: oklch(0.87 0 0);
-  --chart-2: oklch(0.556 0 0);
-  --chart-3: oklch(0.439 0 0);
-  --chart-4: oklch(0.371 0 0);
-  --chart-5: oklch(0.269 0 0);
-  --sidebar: oklch(0.205 0 0);
-  --sidebar-foreground: oklch(0.985 0 0);
-  --sidebar-primary: oklch(0.488 0.243 264.376);
-  --sidebar-primary-foreground: oklch(0.985 0 0);
-  --sidebar-accent: oklch(0.269 0 0);
-  --sidebar-accent-foreground: oklch(0.985 0 0);
-  --sidebar-border: oklch(1 0 0 / 10%);
-  --sidebar-ring: oklch(0.556 0 0);
-  /* Semantic status tones (dark). Brighter foregrounds for contrast on the
-     dark surface; *-soft is a low-alpha tint of the same hue. */
-  --danger: oklch(0.7 0.19 22.2);
-  --danger-soft: oklch(0.7 0.19 22.2 / 18%);
-  --warning: oklch(0.78 0.15 75);
-  --warning-soft: oklch(0.78 0.15 75 / 18%);
-  --success: oklch(0.72 0.17 152);
-  --success-soft: oklch(0.72 0.17 152 / 18%);
-  --info: oklch(0.7 0.16 255);
-  --info-soft: oklch(0.7 0.16 255 / 18%);
-}
-
-* {
-  font-family: "Geist Variable", ui-sans-serif, system-ui, sans-serif !important;
-}
-
-@layer base {
-  *,
-  *::before,
-  *::after {
-    @apply border-border outline-ring/50;
-  }
-  html,
-  body {
-    @apply bg-background text-foreground;
-  }
-}

package/src/hooks/use-tool-result-recovery.test.ts

@@ -1,5 +1,9 @@
 import { describe, expect, it } from "vitest"
-import { decodeRecoveredResult, resolveRecoveryToolName } from "./use-tool-result-recovery.js"
+import {
+  decodeRecoveredResult,
+  isRecoveryReady,
+  resolveRecoveryToolName,
+} from "./use-tool-result-recovery.js"
 
 // The hook's effect wiring (single-flight, StrictMode re-run, host-payload
 // precedence) is exercised end-to-end by the consumer's Playwright host
@@ -63,3 +67,23 @@ describe("decodeRecoveredResult", () => {
     expect(decodeRecoveredResult({ content: [] }, isView)).toBeNull()
   })
 })
+
+describe("isRecoveryReady (toolkit#176)", () => {
+  const base = { resultReady: false, assumedReady: false, cancelled: false, errored: false }
+
+  it("fires once a result latched or the stripped-result grace period passed", () => {
+    expect(isRecoveryReady(base)).toBe(false)
+    expect(isRecoveryReady({ ...base, resultReady: true })).toBe(true)
+    expect(isRecoveryReady({ ...base, assumedReady: true })).toBe(true)
+  })
+
+  it("never re-executes a call that failed (K14: isError renders the error instead)", () => {
+    expect(isRecoveryReady({ ...base, resultReady: true, errored: true })).toBe(false)
+    expect(isRecoveryReady({ ...base, assumedReady: true, errored: true })).toBe(false)
+  })
+
+  it("never re-executes a call the host cancelled", () => {
+    expect(isRecoveryReady({ ...base, resultReady: true, cancelled: true })).toBe(false)
+    expect(isRecoveryReady({ ...base, assumedReady: true, cancelled: true })).toBe(false)
+  })
+})

package/src/hooks/use-tool-result-recovery.ts

@@ -23,7 +23,10 @@ import { parseToolResult } from "../lib/parse-tool-result.js"
  * A call the host cancelled is never recovered: since mcp-use 2.7.1 the
  * cancellation latches as `status: "error"` (a `ToolCancelledError`), which
  * would otherwise count as a ready-but-invalid result — re-executing it would
- * override the user's decision to stop the call.
+ * override the user's decision to stop the call. Neither is a call that
+ * failed (`isError` or a transport error, {@link ToolResultRecoveryOptions.errored}):
+ * re-running it only repeats the failure, so the shell renders the error and
+ * offers an explicit retry instead (toolkit#176).
  *
  * Assumes the originating tool is a read-only render pipeline (true for all
  * toolkit `render-view`/`show_*` tools) — the re-execution must be safe to
@@ -53,6 +56,14 @@ export interface ToolResultRecoveryOptions {
    * attempt already in flight is dropped. Defaults to `false`.
    */
   cancelled?: boolean
+  /**
+   * The originating call latched a tool error (`useToolContext().status ===
+   * "error"` without a cancellation): an `isError` result or a failed call.
+   * Suppresses the recovery exactly like {@link cancelled} — the shell shows
+   * the error instead of silently re-running a call that just failed
+   * (toolkit#176). Defaults to `false`.
+   */
+  errored?: boolean
   /** The payload the host delivered (`useToolContext().toolOutput`). */
   props: unknown
   /**
@@ -124,12 +135,28 @@ export function decodeRecoveredResult<T>(
   return decoded !== null && isValid(decoded) ? (decoded as T) : null
 }
 
+/**
+ * Whether the recovery may fire: the result latched (or is assumed stripped)
+ * and the call was neither cancelled nor failed. Exported for tests — this is
+ * the #176 rule "never recover on an error status".
+ */
+export function isRecoveryReady(state: {
+  resultReady: boolean
+  assumedReady: boolean
+  cancelled: boolean
+  errored: boolean
+}): boolean {
+  if (state.cancelled || state.errored) return false
+  return state.resultReady || state.assumedReady
+}
+
 export function useToolResultRecovery<T>(
   options: ToolResultRecoveryOptions,
 ): ToolResultRecoveryState<T> {
   const {
     resultReady,
     cancelled = false,
+    errored = false,
     props,
     isValid,
     toolInput,
@@ -160,15 +187,16 @@ export function useToolResultRecovery<T>(
     setPrevTimerInput(toolInput)
     if (assumedReady) setAssumedReady(false)
   }
+  const suppressed = cancelled || errored
   useEffect(() => {
-    if (resultReady || cancelled || toolName === undefined) return
+    if (resultReady || suppressed || toolName === undefined) return
     const timer = setTimeout(() => setAssumedReady(true), assumeStrippedAfterMs)
     return () => clearTimeout(timer)
-  }, [resultReady, cancelled, toolName, toolInput, assumeStrippedAfterMs])
+  }, [resultReady, suppressed, toolName, toolInput, assumeStrippedAfterMs])
 
-  // A cancelled call never counts as ready, so the effect below invalidates
-  // any in-flight attempt the same way it does for a superseded run.
-  const ready = !cancelled && (resultReady || assumedReady)
+  // A cancelled or failed call never counts as ready, so the effect below
+  // invalidates any in-flight attempt the same way it does for a superseded run.
+  const ready = isRecoveryReady({ resultReady, assumedReady, cancelled, errored })
 
   useEffect(() => {
     // A new tool run (result no longer ready, or fresh tool-input identity)

package/src/hooks/use-view-data.test.tsx

@@ -0,0 +1,60 @@
+import { renderToStaticMarkup } from "react-dom/server"
+import { describe, expect, it, vi } from "vitest"
+import { AppQueryProvider } from "../providers/query-provider.js"
+import { useViewData, type ViewDataResult } from "./use-view-data.js"
+
+type Demo = { n: number }
+type CallTool = (name: string, args: object) => Promise<unknown>
+
+/** Renders a probe once (SSR, the house path) and hands back the hook's result. */
+function probe(
+  initialData: Demo | null,
+  ready: boolean,
+  callTool: CallTool,
+  key: string,
+): ViewDataResult<Demo> {
+  let result: ViewDataResult<Demo> | undefined
+  function Probe() {
+    result = useViewData<Demo>(
+      initialData,
+      ["use-view-data.test", key],
+      "demo_data",
+      { id: 1 },
+      ready,
+    )
+    return null
+  }
+  renderToStaticMarkup(
+    <AppQueryProvider callTool={callTool}>
+      <Probe />
+    </AppQueryProvider>,
+  )
+  if (!result) throw new Error("probe did not render")
+  return result
+}
+
+describe("useViewData", () => {
+  it("returns host-pushed data verbatim without fetching", () => {
+    const callTool = vi.fn<CallTool>(() => Promise.resolve({}))
+    const result = probe({ n: 1 }, true, callTool, "pushed")
+    expect(result.data).toEqual({ n: 1 })
+    expect(result.loading).toBe(false)
+    expect(result.error).toBeNull()
+    expect(callTool).not.toHaveBeenCalled()
+  })
+
+  it("is not loading before it is ready", () => {
+    const result = probe(null, false, vi.fn<CallTool>(), "not-ready")
+    expect(result).toMatchObject({ data: null, loading: false, error: null })
+  })
+
+  it("refetch calls the tool again: the retry an error state offers", async () => {
+    const callTool = vi.fn<CallTool>(() => Promise.resolve({ structuredContent: { n: 2 } }))
+    const result = probe(null, false, callTool, "refetch")
+    expect(callTool).not.toHaveBeenCalled()
+    result.refetch()
+    await vi.waitFor(() => {
+      expect(callTool).toHaveBeenCalledWith("demo_data", { id: 1 })
+    })
+  })
+})

package/src/hooks/use-view-data.ts

@@ -1,3 +1,4 @@
+import { useCallback } from "react"
 import { useToolQuery } from "./use-tool-query.js"
 
 export interface ViewDataResult<T> {
@@ -5,6 +6,12 @@ export interface ViewDataResult<T> {
   /** True while self-fetching with no data yet — the first paint of a cockpit cell. */
   loading: boolean
   error: Error | null
+  /**
+   * Fetch `tool` again: the retry of an error state
+   * (`<ErrorState onRetry={refetch} … />`). Host-pushed data, when present,
+   * stays what `data` returns.
+   */
+  refetch: () => void
 }
 
 /**
@@ -27,5 +34,9 @@ export function useViewData<T>(
 ): ViewDataResult<T> {
   const query = useToolQuery<T>([...key], tool, args, { enabled: !initialData && ready })
   const data = initialData ?? query.data ?? null
-  return { data, loading: !data && ready && !query.isError, error: query.error ?? null }
+  const { refetch: refetchQuery } = query
+  const refetch = useCallback(() => {
+    void refetchQuery()
+  }, [refetchQuery])
+  return { data, loading: !data && ready && !query.isError, error: query.error ?? null, refetch }
 }