@miragon/mcp-toolkit-ui 2.7.0 → 2.8.0

package/src/app/use-view-actions.ts

@@ -0,0 +1,89 @@
+import { useCallback, useState } from "react"
+import type { QueryClient } from "@tanstack/react-query"
+import { useDisplayMode } from "mcp-use/react"
+import { useToast } from "../components/Toast.js"
+import type { ViewMessages } from "../locale/toolkit-messages.js"
+import { fullscreenAvailable, isCompleteViewData, type ViewData } from "./mcp-app-view-chrome.js"
+import { decodeViewResult } from "./view-lifecycle.js"
+
+/**
+ * The toolbar actions of `McpAppView`: refresh and the fullscreen toggle.
+ * Their failures raise a toast in catalog words; the raw reason goes to the
+ * console, never to the user.
+ */
+
+/**
+ * Refresh via the refresh tool. A failure keeps the data and says so in a
+ * toast. A refresh that went through invalidates the queries of `client`,
+ * the one the view's widgets fetch through.
+ */
+export function useViewRefresh(options: {
+  viewData: ViewData | null
+  setViewData: (next: ViewData) => void
+  callTool: (name: string, args: Record<string, unknown>) => Promise<unknown>
+  refreshToolName: string
+  labels: Pick<ViewMessages, "refreshFailed" | "refreshFailedHint">
+  client: QueryClient
+}) {
+  const { viewData, setViewData, callTool, refreshToolName, labels, client } = options
+  const toast = useToast()
+  const [isRefreshing, setIsRefreshing] = useState(false)
+  const refreshView = useCallback(async () => {
+    if (!viewData?._refreshParams) return
+    setIsRefreshing(true)
+    let failure: unknown = null
+    try {
+      const result = await callTool(
+        refreshToolName,
+        viewData._refreshParams as unknown as Record<string, unknown>,
+      )
+      // One decoding convention with `useToolQuery` (structured-first), with a
+      // typed outcome: an unusable payload is a failure, never exception text.
+      const outcome = decodeViewResult(result, isCompleteViewData)
+      if (outcome.ok) setViewData(outcome.data)
+      else failure = outcome.reason ?? "the refresh tool returned no view"
+      // The call went through, so self-fetching widgets refresh as well;
+      // a tool error refreshes nothing.
+      if (outcome.ok || !outcome.isError) void client.invalidateQueries()
+    } catch (e) {
+      failure = e
+    } finally {
+      setIsRefreshing(false)
+    }
+    if (failure === null) return
+    console.warn("[mcp-toolkit] refresh failed:", failure)
+    toast.show({
+      tone: "danger",
+      title: labels.refreshFailed,
+      description: labels.refreshFailedHint,
+    })
+  }, [callTool, client, labels, refreshToolName, setViewData, toast, viewData])
+  return { isRefreshing, refreshView }
+}
+
+/** The fullscreen toggle, gated on the host's offer; a rejected request raises a toast. */
+export function useFullscreenToggle(
+  labels: Pick<ViewMessages, "fullscreenFailed" | "fullscreenFailedHint">,
+) {
+  const { displayMode, availableDisplayModes, requestDisplayMode } = useDisplayMode()
+  const toast = useToast()
+  const toggle = useCallback(async () => {
+    const mode = displayMode === "fullscreen" ? "inline" : "fullscreen"
+    try {
+      // Advisory since 2.x: `displayMode` updates when the host applies it.
+      await requestDisplayMode({ mode })
+    } catch (e) {
+      console.warn("[mcp-toolkit] display-mode request failed:", e)
+      toast.show({
+        tone: "danger",
+        title: labels.fullscreenFailed,
+        description: labels.fullscreenFailedHint,
+      })
+    }
+  }, [displayMode, labels, requestDisplayMode, toast])
+  return {
+    isFullscreen: displayMode === "fullscreen",
+    canFullscreen: fullscreenAvailable(displayMode, availableDisplayModes),
+    toggle,
+  }
+}

package/src/app/use-view-lifecycle.ts

@@ -18,6 +18,10 @@ export interface UseViewLifecycleOptions<T> {
   cancelled: boolean
   callError: unknown
   recoveryFailed: boolean
+  /** The recovery policy kept the view from re-running a stripped result's tool. */
+  recoveryBlocked?: boolean
+  /** The host reports the originating tool as writing (no retry after a block). */
+  toolWrites?: boolean
   /** The originating tool (`hostContext.toolInfo`); a retry needs it. */
   toolName: string | undefined
   toolInput: Record<string, unknown> | null | undefined
@@ -47,6 +51,8 @@ export function useViewLifecycle<T>(options: UseViewLifecycleOptions<T>): {
     cancelled: options.cancelled,
     callErrorReason: errorMessage(options.callError),
     recoveryFailed: options.recoveryFailed,
+    recoveryBlocked: options.recoveryBlocked,
+    toolWrites: options.toolWrites,
     retryState,
     slow: false,
     canRetry: toolName !== undefined,

package/src/app/view-lifecycle.test.ts

@@ -2,7 +2,9 @@ import { describe, expect, it } from "vitest"
 import {
   decodeViewResult,
   DEFAULT_SLOW_HINT_MS,
+  describeViewForModel,
   errorMessage,
+  reloadedAtOf,
   resolveViewLifecycle,
   RETRY_IDLE,
   retryFocusTarget,
@@ -51,6 +53,53 @@ describe("resolveViewLifecycle (toolkit#176 state machine)", () => {
     })
   })
 
+  it("a blocked recovery is its own error kind: the tool ran, the view must not re-run it", () => {
+    // A tool the host reports as writing: no retry, one click would write twice.
+    expect(at({ recoveryBlocked: true, toolWrites: true })).toEqual({
+      phase: "error",
+      reason: undefined,
+      canRetry: false,
+      kind: "blocked",
+    })
+    // Any other tool (a stricter policy blocked it): loading it is the user's call.
+    expect(at({ recoveryBlocked: true, toolWrites: false })).toEqual({
+      phase: "error",
+      reason: undefined,
+      canRetry: true,
+      kind: "blocked",
+    })
+    expect(at({ recoveryBlocked: true })).toMatchObject({ canRetry: true, kind: "blocked" })
+    expect(at({ recoveryBlocked: true, canRetry: false })).toMatchObject({ canRetry: false })
+    // toolWrites alone changes nothing: a failure keeps its retry.
+    expect(at({ recoveryFailed: true, toolWrites: true })).toEqual({
+      phase: "error",
+      reason: undefined,
+      canRetry: true,
+    })
+    expect(at({ callStatus: "error", callErrorReason: "x", toolWrites: true })).toMatchObject({
+      canRetry: true,
+    })
+  })
+
+  it("a block yields to a payload, a retry, a cancellation and a call error, and wins over a failure", () => {
+    const blocked = { recoveryBlocked: true, toolWrites: true }
+    expect(at({ ...blocked, hasViewData: true })).toEqual({ phase: "result" })
+    expect(at({ ...blocked, retryState: { status: "running", attempt: 1 } })).toEqual({
+      phase: "waiting",
+      slow: false,
+    })
+    expect(
+      at({ ...blocked, retryState: { status: "failed", attempt: 1, reason: "down" } }),
+    ).toEqual({ phase: "error", reason: "down", canRetry: true })
+    expect(at({ ...blocked, cancelled: true })).toEqual({ phase: "cancelled" })
+    expect(at({ ...blocked, callStatus: "error", callErrorReason: "x" })).toEqual({
+      phase: "error",
+      reason: "x",
+      canRetry: true,
+    })
+    expect(at({ ...blocked, recoveryFailed: true })).toMatchObject({ kind: "blocked" })
+  })
+
   it("offers a retry only when the originating tool is known", () => {
     expect(at({ callStatus: "error", canRetry: false })).toMatchObject({
       phase: "error",
@@ -225,3 +274,170 @@ describe("errorMessage", () => {
     expect(errorMessage(undefined)).toBeUndefined()
   })
 })
+
+describe("describeViewForModel (the view's model context, toolkit#176 K20)", () => {
+  const error = (reason: string | undefined, canRetry = true) =>
+    ({ phase: "error", reason, canRetry }) as const
+
+  it("an error says what failed and that the user sees an error instead of the view", () => {
+    expect(
+      describeViewForModel({ lifecycle: error("[503] engine down"), toolName: "render-view" }),
+    ).toBe(
+      "The view of render-view could not be shown (reason: [503] engine down). " +
+        "The user sees an error message with a retry button instead of the view.",
+    )
+    expect(describeViewForModel({ lifecycle: error(undefined, false), toolName: undefined })).toBe(
+      "The view could not be shown. The user sees an error message instead of the view.",
+    )
+  })
+
+  it("a block says the tool ran, nothing failed, and the model must not re-run it to show the view", () => {
+    const blocked = (canRetry: boolean) =>
+      ({ phase: "error", reason: undefined, canRetry, kind: "blocked" }) as const
+    expect(describeViewForModel({ lifecycle: blocked(false), toolName: "start_and_show" })).toBe(
+      "The view of start_and_show is not shown: start_and_show ran, but the host did not pass its " +
+        "result to the view, and the view did not re-run it. The user sees a note to ask in the chat " +
+        "for the current state instead of the view. Do not re-run start_and_show just to show the view.",
+    )
+    expect(describeViewForModel({ lifecycle: blocked(true), toolName: undefined })).toBe(
+      "The view is not shown: the tool ran, but the host did not pass its result to the view, " +
+        "and the view did not re-run it. The user sees a note with a button that loads the view " +
+        "instead of the view. Do not re-run the tool just to show the view.",
+    )
+  })
+
+  it("a cancellation says so", () => {
+    expect(describeViewForModel({ lifecycle: { phase: "cancelled" }, toolName: "show_x" })).toBe(
+      "The view of show_x was cancelled before it rendered. The user sees a note that the call was cancelled.",
+    )
+  })
+
+  it("nothing while waiting, nor for a plain host-delivered view", () => {
+    expect(
+      describeViewForModel({ lifecycle: { phase: "waiting", slow: true }, toolName: "t" }),
+    ).toBeNull()
+    // A waiting view shows no data, so a stamp or step errors of an older payload say nothing.
+    expect(
+      describeViewForModel({
+        lifecycle: { phase: "waiting", slow: false },
+        toolName: "t",
+        reloadedAt: Date.UTC(2026, 9, 11),
+        stepErrors: [{ stepId: "kpi", reason: "timeout" }],
+      }),
+    ).toBeNull()
+    expect(describeViewForModel({ lifecycle: { phase: "result" }, toolName: "t" })).toBeNull()
+    expect(
+      describeViewForModel({
+        lifecycle: { phase: "result" },
+        toolName: "t",
+        stepErrors: [],
+        reloadedAt: null,
+      }),
+    ).toBeNull()
+  })
+
+  it("failed data steps of a shown view, with or without the alert's retry", () => {
+    const stepErrors = [
+      { stepId: "kpi", reason: "timeout" },
+      { stepId: "list", reason: "[404] gone" },
+    ]
+    expect(
+      describeViewForModel({
+        lifecycle: { phase: "result" },
+        toolName: "render-view",
+        stepErrors,
+        stepsRetryable: true,
+      }),
+    ).toBe(
+      "The view of render-view is shown, but some of its data could not be loaded " +
+        "(kpi: timeout; list: [404] gone). The user sees an alert with a retry button.",
+    )
+    expect(
+      describeViewForModel({ lifecycle: { phase: "result" }, toolName: undefined, stepErrors }),
+    ).toBe(
+      "The view is shown, but some of its data could not be loaded " +
+        "(kpi: timeout; list: [404] gone). The user sees an alert.",
+    )
+  })
+
+  it("a payload the view re-loaded itself is live as of then (N23)", () => {
+    const at = Date.UTC(2026, 9, 11, 14, 32, 5)
+    const recovered =
+      "The view of t re-ran the tool at 2026-10-11T14:32:05.000Z because the host did not pass " +
+      "the original result to the view; its figures are live as of then and can differ from the original result."
+    expect(
+      describeViewForModel({ lifecycle: { phase: "result" }, toolName: "t", reloadedAt: at }),
+    ).toBe(recovered)
+    expect(
+      describeViewForModel({
+        lifecycle: { phase: "result" },
+        toolName: "t",
+        reloadedAt: at,
+        reloadedBy: "recovery",
+      }),
+    ).toBe(recovered)
+    expect(
+      describeViewForModel({
+        lifecycle: { phase: "result" },
+        toolName: "t",
+        reloadedAt: at,
+        stepErrors: [{ stepId: "kpi", reason: "timeout" }],
+      }),
+    ).toMatch(
+      /original result\. Some of its data could not be loaded \(kpi: timeout\)\. The user sees an alert\.$/,
+    )
+  })
+
+  it("a refreshed payload says the user refreshed it, and when", () => {
+    expect(
+      describeViewForModel({
+        lifecycle: { phase: "result" },
+        toolName: "t",
+        reloadedAt: Date.UTC(2026, 9, 11, 15, 10),
+        reloadedBy: "refresh",
+      }),
+    ).toBe(
+      "The view of t 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.",
+    )
+  })
+
+  it("a payload applied from the view builder says the user edited it there, and when it loaded", () => {
+    expect(
+      describeViewForModel({
+        lifecycle: { phase: "result" },
+        toolName: "show_orders_dashboard",
+        reloadedAt: Date.UTC(2026, 9, 11, 10, 5),
+        reloadedBy: "builder",
+      }),
+    ).toBe(
+      "The view of show_orders_dashboard was edited by the user in the view builder, which loaded " +
+        "its data again at 2026-10-11T10:05:00.000Z; its figures are live as of then and can " +
+        "differ from the original result.",
+    )
+  })
+})
+
+describe("reloadedAtOf (which payload carries the data-as-of stamp, N23)", () => {
+  const now = 42_000
+
+  it("a recovery, a refresh and a builder Apply always: the view loaded the figures itself", () => {
+    expect(reloadedAtOf("recovered", now, false)).toBe(now)
+    expect(reloadedAtOf("refresh", now, false)).toBe(now)
+    expect(reloadedAtOf("refresh", now, true)).toBe(now)
+    expect(reloadedAtOf("builder", now, false)).toBe(now)
+    expect(reloadedAtOf("builder", now, true)).toBe(now)
+  })
+
+  it("a retry only when the original result reached the chat", () => {
+    // After a blocked or failed recovery: the host answered, the chat has figures.
+    expect(reloadedAtOf("retry", now, false)).toBe(now)
+    // After a failed or cancelled call: the model never had figures.
+    expect(reloadedAtOf("retry", now, true)).toBeNull()
+  })
+
+  it("never the host's own payload", () => {
+    expect(reloadedAtOf("host", now, false)).toBeNull()
+    expect(reloadedAtOf("host", now, true)).toBeNull()
+  })
+})

package/src/app/view-lifecycle.ts

@@ -6,6 +6,8 @@
  *   waiting ──result──▶ result
  *      │  ╲
  *      │   ╲──tool error / failed recovery / unrecoverable result──▶ error ──retry──▶ waiting
+ *      │    ╲
+ *      │     ╲──stripped result the policy must not re-load──▶ error (blocked)
  *      │
  *      └──host cancelled──▶ cancelled (terminal: the user stopped it)
  *
@@ -14,6 +16,10 @@
  * skeleton, and a retry re-runs the originating tool once on the user's click.
  * A latched result that is no view on a host that names no originating tool
  * is an `error` too: nothing could recover it, so waiting would never end.
+ * A `blocked` error is no failure: the tool ran, the host kept its result
+ * from the view, and the recovery policy forbids re-running it. It offers to
+ * load the view only for a tool the host does not report as writing, so one
+ * click never runs a write a second time (CI §9).
  * Pure functions only: the hook in `use-view-lifecycle.ts` feeds them.
  */
 import { parseToolResult } from "../lib/parse-tool-result.js"
@@ -53,8 +59,23 @@ export interface ViewLifecycleInput {
   cancelled: boolean
   /** Message of the original call's error, when it failed. */
   callErrorReason: string | undefined
-  /** The automatic stripped-result recovery ran and failed. */
+  /**
+   * The automatic stripped-result recovery ran and failed, or was needed but
+   * could not run because the host names no tool.
+   */
   recoveryFailed: boolean
+  /**
+   * The host did not pass the result to the view, and the recovery policy
+   * forbids re-running the tool: it ran, but the view never got its result.
+   * Default `false`.
+   */
+  recoveryBlocked?: boolean
+  /**
+   * The host reports the originating tool as writing (`readOnlyHint: false`
+   * or `destructiveHint: true`). A blocked state then offers no retry: one
+   * click would run the write a second time. Default `false`.
+   */
+  toolWrites?: boolean
   /** The user-triggered retry. */
   retryState: RetryState
   /** Loading has outlasted the slow-hint delay. */
@@ -63,18 +84,32 @@ export interface ViewLifecycleInput {
   canRetry: boolean
 }
 
+/**
+ * What an `error` phase stands for: `"failed"` (the call, the recovery or the
+ * retry failed) or `"blocked"` (the tool ran, but the host did not pass its
+ * result to the view, and the recovery policy keeps the view from re-running it).
+ */
+export type ViewErrorKind = "failed" | "blocked"
+
 export type ViewLifecycle =
   | { phase: "result" }
   | { phase: "waiting"; slow: boolean }
   | { phase: "cancelled" }
-  | { phase: "error"; reason: string | undefined; canRetry: boolean }
+  | {
+      phase: "error"
+      reason: string | undefined
+      canRetry: boolean
+      /** Absent for a failure; `"blocked"` for a result the view must not re-load. */
+      kind?: ViewErrorKind
+    }
 
 /**
  * Resolve the single phase the view is in. Precedence: a payload always wins;
  * a running retry is waiting; a failed retry is an error with ITS reason; a
- * cancellation is terminal; a failed call, a failed recovery or a latched
- * non-view result nothing can recover is an error; everything else is still
- * waiting.
+ * cancellation is terminal; a failed call is an error; a blocked recovery is
+ * a `blocked` error, retryable only for a tool not reported as writing; a
+ * failed recovery or a latched non-view result nothing can recover is an
+ * error; everything else is still waiting.
  */
 export function resolveViewLifecycle(input: ViewLifecycleInput): ViewLifecycle {
   if (input.hasViewData) return { phase: "result" }
@@ -87,6 +122,10 @@ export function resolveViewLifecycle(input: ViewLifecycleInput): ViewLifecycle {
   if (input.callStatus === "error") {
     return { phase: "error", reason: input.callErrorReason, canRetry: input.canRetry }
   }
+  if (input.recoveryBlocked) {
+    const canRetry = input.canRetry && !input.toolWrites
+    return { phase: "error", reason: undefined, canRetry, kind: "blocked" }
+  }
   if (input.recoveryFailed) return { phase: "error", reason: undefined, canRetry: input.canRetry }
   // A latched result without a renderable view: the recovery re-runs the
   // originating tool, so it can only help when the host names that tool.
@@ -166,6 +205,127 @@ export function decodeViewResult<T>(
     : { ok: false, isError: false, reason: undefined }
 }
 
+/** What {@link describeViewForModel} reports on. */
+export interface ViewModelContextInput {
+  lifecycle: ViewLifecycle
+  /** The originating tool, when the host names it. */
+  toolName: string | undefined
+  /** The shown payload's failed data steps (result phase). */
+  stepErrors?: readonly { stepId: string; reason: string }[]
+  /** The step-error alert offers a retry (the view can refresh). */
+  stepsRetryable?: boolean
+  /**
+   * When the view re-loaded the shown payload itself (epoch ms, see
+   * {@link reloadedAtOf}); `null` for a payload the host delivered.
+   */
+  reloadedAt?: number | null
+  /**
+   * How it re-loaded: it re-ran the tool because the host did not pass the
+   * result along (`"recovery"`, the default: its own recovery or the user's
+   * retry), the user refreshed the view (`"refresh"`), or the user applied an
+   * edit from the view builder, which ran the data steps again (`"builder"`).
+   */
+  reloadedBy?: "recovery" | "refresh" | "builder"
+}
+
+/**
+ * Where the shown payload came from: the host's tool result, the view's own
+ * re-execution when the host stripped it, the user's retry, a refresh, or the
+ * user's Apply in the view builder (its figures are the builder's own run of
+ * the data steps).
+ */
+export type ViewSource = "host" | "recovered" | "retry" | "refresh" | "builder"
+
+/**
+ * When a payload counts as re-loaded by the view itself (N23): `at` when its
+ * figures can differ from the result the chat answered from, else `null`. A
+ * recovery, a refresh and a builder Apply always; a retry only after a call
+ * whose result reached the chat (a stripped or unusable one), never after a
+ * failed or cancelled call, of which the model never had figures. The host's
+ * own payload never.
+ */
+export function reloadedAtOf(source: ViewSource, at: number, callFailed: boolean): number | null {
+  if (source === "host") return null
+  if (source === "retry" && callFailed) return null
+  return at
+}
+
+/** How the view says, to the model, that it loaded the shown figures itself. */
+const RELOADED_BY: Record<
+  NonNullable<ViewModelContextInput["reloadedBy"]>,
+  (at: string) => string
+> = {
+  recovery: (at) =>
+    `re-ran the tool at ${at} because the host did not pass the original result to the view`,
+  refresh: (at) => `was refreshed by the user at ${at}`,
+  builder: (at) =>
+    `was edited by the user in the view builder, which loaded its data again at ${at}`,
+}
+
+/**
+ * The view's own line of model context (toolkit#176 K20): what failed and
+ * that the user sees an error instead of the view; a blocked recovery (the
+ * tool ran, its result never reached the view, and the model must not re-run
+ * it just to show the view); failed data steps; a payload the view re-loaded
+ * itself (a recovery, a retry, a refresh, a builder Apply), whose figures can
+ * differ from the tool result the model answered from (N23). `null` while
+ * there is nothing to report (waiting, or a plain host-delivered view).
+ * English: it is read by the model, never shown.
+ */
+export function describeViewForModel(input: ViewModelContextInput): string | null {
+  const subject = input.toolName ? `The view of ${input.toolName}` : "The view"
+  const { lifecycle } = input
+  if (lifecycle.phase === "error") {
+    if (lifecycle.kind === "blocked") {
+      return describeBlockedForModel(subject, input.toolName, lifecycle.canRetry)
+    }
+    const reason = lifecycle.reason ? ` (reason: ${lifecycle.reason})` : ""
+    const offer = lifecycle.canRetry ? "an error message with a retry button" : "an error message"
+    return `${subject} could not be shown${reason}. The user sees ${offer} instead of the view.`
+  }
+  if (lifecycle.phase === "cancelled") {
+    return `${subject} was cancelled before it rendered. The user sees a note that the call was cancelled.`
+  }
+  if (lifecycle.phase === "waiting") return null
+  const lines: string[] = []
+  if (input.reloadedAt != null) {
+    const at = new Date(input.reloadedAt).toISOString()
+    const how = RELOADED_BY[input.reloadedBy ?? "recovery"](at)
+    lines.push(
+      `${subject} ${how}; its figures are live as of then and can differ from the original result.`,
+    )
+  }
+  const failed = input.stepErrors ?? []
+  if (failed.length > 0) {
+    const steps = failed.map((e) => `${e.stepId}: ${e.reason}`).join("; ")
+    const lead = lines.length > 0 ? "Some" : `${subject} is shown, but some`
+    const offer = input.stepsRetryable ? "an alert with a retry button" : "an alert"
+    lines.push(`${lead} of its data could not be loaded (${steps}). The user sees ${offer}.`)
+  }
+  return lines.length > 0 ? lines.join(" ") : null
+}
+
+/**
+ * The model's line for a blocked recovery: the tool ran (nothing failed), the
+ * host kept its result from the view, the view did not re-run it, and the
+ * model must not re-run it just to show the view, a write least of all.
+ */
+function describeBlockedForModel(
+  subject: string,
+  toolName: string | undefined,
+  canRetry: boolean,
+): string {
+  const tool = toolName ?? "the tool"
+  const offer = canRetry
+    ? "a note with a button that loads the view"
+    : "a note to ask in the chat for the current state"
+  return (
+    `${subject} is not shown: ${tool} ran, but the host did not pass its result to the view, ` +
+    `and the view did not re-run it. The user sees ${offer} instead of the view. ` +
+    `Do not re-run ${tool} just to show the view.`
+  )
+}
+
 /** A displayable message for anything thrown. */
 export function errorMessage(err: unknown): string | undefined {
   if (err instanceof Error) return err.message || undefined

package/src/app/widget-fixture.effects.test.tsx

@@ -0,0 +1,51 @@
+// @vitest-environment happy-dom
+import { useEffect } from "react"
+import { afterEach, describe, expect, it } from "vitest"
+import { useToast } from "../components/Toast.js"
+import { TOOLKIT_MESSAGES } from "../locale/toolkit-messages.js"
+import { renderWithEffects, type EffectRender } from "../render-effects.js"
+import { WidgetFixtureHost } from "./widget-fixture.js"
+
+/**
+ * The harness's toast stack inside the host's locale scope, with its effects
+ * running: a toast exists only after a widget's effect shows it, so the SSR
+ * suite (`widget-fixture.render.test.tsx`) never sees its words. Its one
+ * localized word is the dismiss button's name; it follows `globals.locale`
+ * like `McpAppView`'s stack does, which holds only while the `ToastProvider`
+ * sits inside the `ToolkitLocaleFallback`.
+ */
+
+/** A widget that reports a write's outcome as a toast once it mounts. */
+function SavesOnMount() {
+  const toast = useToast()
+  useEffect(() => {
+    toast.show({ tone: "success", title: "Saved" })
+  }, [toast])
+  return <p>widget</p>
+}
+
+let mounted: EffectRender | null = null
+
+afterEach(async () => {
+  await mounted?.unmount()
+  mounted = null
+})
+
+/** The dismiss button's accessible name of the toast the widget raised. */
+async function dismissLabel(globals?: Record<string, unknown>): Promise<string | null> {
+  mounted = await renderWithEffects(<WidgetFixtureHost widget={SavesOnMount} globals={globals} />)
+  const toast = mounted.container.querySelector('[data-slot="toast"]')
+  expect(toast?.textContent, "the widget's toast reached the stack").toContain("Saved")
+  return toast?.querySelector("button")?.getAttribute("aria-label") ?? null
+}
+
+describe("WidgetFixtureHost toast stack (effects)", () => {
+  it("names a toast's dismiss button in globals.locale", async () => {
+    expect(await dismissLabel({ locale: "de" })).toBe(TOOLKIT_MESSAGES.de.common.dismiss)
+  })
+
+  it("names it in English without a host locale", async () => {
+    expect(await dismissLabel()).toBe(TOOLKIT_MESSAGES.en.common.dismiss)
+    expect(TOOLKIT_MESSAGES.en.common.dismiss).not.toBe(TOOLKIT_MESSAGES.de.common.dismiss)
+  })
+})