@miragon/mcp-toolkit-ui 2.5.0 → 2.7.0

package/src/i18n-coverage.test.tsx

@@ -0,0 +1,323 @@
+import { isValidElement, type ReactElement } from "react"
+import { renderToStaticMarkup } from "react-dom/server"
+import { describe, expect, it } from "vitest"
+import type { WidgetProps } from "@miragon/mcp-toolkit-core"
+import { EmptyState } from "./components/EmptyState.js"
+import { ErrorState } from "./components/ErrorState.js"
+import { ToastViewport } from "./components/Toast.js"
+import { LocaleProvider } from "./locale/locale-provider.js"
+import { TOOLKIT_MESSAGES, type ToolkitMessages } from "./locale/toolkit-messages.js"
+import { createToast } from "./lib/toast-model.js"
+import { RENDER_CASES } from "./render-cases.js"
+import { userFacingTexts } from "./render-scan.js"
+import { StepErrors, ViewToolbar, type ViewData } from "./app/mcp-app-view-chrome.js"
+import { ViewPlaceholder } from "./app/mcp-app-view-states.js"
+import { LayoutBuilder } from "./app/layout-builder.js"
+import { BuilderBanners } from "./app/builder/BuilderBanners.js"
+import { PipelineStrip } from "./app/builder/PipelineStrip.js"
+import { StatusChip } from "./app/builder/status-chip.js"
+import { Toolbar } from "./app/builder/Toolbar.js"
+import { WidgetCrashFallback, WidgetRenderer } from "./app/widget-renderer.js"
+
+/**
+ * Render half of the i18n guard (the static half is `no-hardcoded-copy.test.ts`):
+ * render every component under the German locale with a MARKED catalog —
+ * each catalog string wrapped in ⟦…⟧ — and scan every text node and text
+ * attribute. Whatever is neither marked (it came from the catalog) nor a
+ * fixture value the case passed in (it came from props) is a hard-coded
+ * string that a German user would read in English.
+ */
+
+const OPEN = "⟦"
+const CLOSE = "⟧"
+
+function marked(messages: ToolkitMessages): ToolkitMessages {
+  const mark = (value: unknown): unknown =>
+    typeof value === "function"
+      ? (...args: unknown[]) => `${OPEN}${(value as (...a: unknown[]) => string)(...args)}${CLOSE}`
+      : `${OPEN}${String(value)}${CLOSE}`
+  return Object.fromEntries(
+    Object.entries(messages).map(([section, entries]) => [
+      section,
+      Object.fromEntries(
+        Object.entries(entries as Record<string, unknown>).map(([k, v]) => [k, mark(v)]),
+      ),
+    ]),
+  ) as unknown as ToolkitMessages
+}
+
+const PSEUDO = marked(TOOLKIT_MESSAGES.de)
+
+/** Every string/number a case hands to the tree through props (its fixtures). */
+function fixtureStrings(node: unknown, out = new Set<string>(), seen = new Set<unknown>()) {
+  if (typeof node === "string" || typeof node === "number") {
+    const text = String(node).trim()
+    if (text.length >= 2) out.add(text)
+    return out
+  }
+  if (!node || typeof node !== "object" || seen.has(node)) return out
+  seen.add(node)
+  if (node instanceof Error) return fixtureStrings(node.message, out, seen)
+  if (isValidElement(node)) return fixtureStrings(node.props, out, seen)
+  for (const value of Array.isArray(node) ? node : Object.values(node)) {
+    fixtureStrings(value, out, seen)
+  }
+  return out
+}
+
+/** Text a German user would read that came neither from the catalog nor from props. */
+function leaks(element: ReactElement): string[] {
+  const html = renderToStaticMarkup(
+    <LocaleProvider locale="de" toolkitMessages={PSEUDO}>
+      {element}
+    </LocaleProvider>,
+  )
+  const fixtures = [...fixtureStrings(element)].sort((a, b) => b.length - a.length)
+  const found: string[] = []
+  for (const { source, value } of userFacingTexts(html)) {
+    let rest = value
+    const innermost = /⟦[^⟦⟧]*⟧/g
+    while (innermost.test(rest)) rest = rest.replace(innermost, " ")
+    rest = rest.replace(/RC:[\w:-]+/g, " ")
+    for (const fixture of fixtures) rest = rest.split(fixture).join(" ")
+    if (/\p{L}/u.test(rest)) found.push(`${source}: "${value}" → "${rest.trim()}"`)
+  }
+  return found
+}
+
+const noop = (): void => {}
+const asyncNoop = (): Promise<void> => Promise.resolve()
+
+const view: ViewData = {
+  title: "Prozessdefinitionen",
+  context: { keys: {}, stepIds: [], stepData: {}, errors: [] },
+  layout: { rows: [] },
+  _refreshParams: { layout: { rows: [] } },
+}
+
+function Crash(): never {
+  throw new Error("kaputt")
+}
+
+function Fine({ keys }: WidgetProps) {
+  return <span>{typeof keys.label === "string" ? keys.label : ""}</span>
+}
+
+/** The toolkit chrome no catalogued render case reaches. */
+const CHROME_CASES: { name: string; render: () => ReactElement }[] = [
+  {
+    name: "ViewPlaceholder waiting + slow hint",
+    render: () => (
+      <ViewPlaceholder
+        lifecycle={{ phase: "waiting", slow: true }}
+        labels={PSEUDO.view}
+        onRetry={noop}
+      />
+    ),
+  },
+  {
+    name: "ViewPlaceholder error",
+    render: () => (
+      <ViewPlaceholder
+        lifecycle={{ phase: "error", reason: "[503] engine down", canRetry: true }}
+        labels={PSEUDO.view}
+        onRetry={noop}
+      />
+    ),
+  },
+  {
+    name: "ViewPlaceholder error without a retry",
+    render: () => (
+      <ViewPlaceholder
+        lifecycle={{ phase: "error", reason: undefined, canRetry: false }}
+        labels={PSEUDO.view}
+        onRetry={noop}
+      />
+    ),
+  },
+  {
+    name: "StepErrors without a refresh",
+    render: () => (
+      <StepErrors
+        hidden={false}
+        errors={[{ stepId: "inc", reason: "[503] engine down" }]}
+        labels={PSEUDO.view}
+      />
+    ),
+  },
+  {
+    name: "ViewPlaceholder cancelled",
+    render: () => (
+      <ViewPlaceholder lifecycle={{ phase: "cancelled" }} labels={PSEUDO.view} onRetry={noop} />
+    ),
+  },
+  {
+    name: "ViewToolbar",
+    render: () => (
+      <ViewToolbar
+        hidden={false}
+        viewData={view}
+        builderAvailable
+        isFullscreen={false}
+        canFullscreen
+        isRefreshing={false}
+        labels={PSEUDO.view}
+        titleMode="show"
+        titleLevel={2}
+        onRefresh={asyncNoop}
+        onEnterBuildMode={noop}
+        onToggleFullscreen={asyncNoop}
+      />
+    ),
+  },
+  {
+    name: "StepErrors",
+    render: () => (
+      <StepErrors
+        hidden={false}
+        errors={[{ stepId: "inc", reason: "[503] engine down" }]}
+        steps={[{ id: "inc", step: "camunda7:incidents" }]}
+        labels={PSEUDO.view}
+        onRetry={noop}
+      />
+    ),
+  },
+  {
+    name: "WidgetRenderer: unknown widget + crashing widget",
+    render: () => (
+      <WidgetRenderer
+        layout={{ rows: [{ row: [{ widget: "demo:gone" }, { widget: "demo:fine" }] }] }}
+        keys={{ label: "Rechnung 42" }}
+        errors={[]}
+        widgets={{ "demo:fine": Fine }}
+      />
+    ),
+  },
+  {
+    name: "WidgetCrashFallback",
+    render: () => (
+      <WidgetCrashFallback widgetId="demo:crash" error={new Error("kaputt")} onRetry={noop} />
+    ),
+  },
+  {
+    name: "ToastViewport",
+    render: () => (
+      <ToastViewport
+        toasts={[createToast(1, { tone: "success", title: "Job neu eingeplant." })]}
+        onDismiss={noop}
+      />
+    ),
+  },
+  {
+    name: "ErrorState defaults",
+    render: () => <ErrorState title="Fehler" details="raw" onRetry={noop} />,
+  },
+  {
+    name: "EmptyState",
+    render: () => <EmptyState title="Leer" description="Nichts zu tun." />,
+  },
+  {
+    name: "LayoutBuilder (empty: data-sources hint)",
+    render: () => <LayoutBuilder widgets={{}} callTool={() => Promise.resolve({})} />,
+  },
+  {
+    name: "LayoutBuilder (tabs, cells, unknown widget)",
+    render: () => (
+      <LayoutBuilder
+        initialLayout={{
+          tabs: [
+            { label: "Übersicht", rows: [{ row: [{ widget: "demo:gone" }] }, { row: [] }] },
+            { label: "Details-Tab", rows: [] },
+          ],
+        }}
+        widgets={{ "demo:fine": Crash }}
+        callTool={() => Promise.resolve({})}
+      />
+    ),
+  },
+  {
+    name: "Builder toolbar",
+    render: () => (
+      <Toolbar
+        L={PSEUDO.builder}
+        previewMode={false}
+        isBusy={false}
+        status="pending"
+        liveKeys={2}
+        reachableCount={5}
+        unreachableCount={1}
+        onOpenCatalogue={noop}
+        onOpenSave={noop}
+        onDone={noop}
+        hasAnyCell
+      />
+    ),
+  },
+  {
+    name: "Builder data sources",
+    render: () => (
+      <PipelineStrip
+        L={PSEUDO.builder}
+        keyEntries={[
+          { name: "demo:id", rawValue: "42" },
+          { name: "demo:live", rawValue: "" },
+        ]}
+        stepEntries={[{ id: "s1", step: "demo:load" }]}
+        keyCatalog={[]}
+        availableSteps={[
+          { id: "demo:load", app: "demo", dataType: "demo:t", requires: [], produces: [] },
+        ]}
+        stepsByApp={[]}
+        liveKeys={{ "demo:live": 7 }}
+        onAddKey={noop}
+        onUpdateKey={noop}
+        onRemoveKey={noop}
+        onAddStep={noop}
+        onUpdateStep={noop}
+        onRemoveStep={noop}
+        status="refreshing"
+      />
+    ),
+  },
+  {
+    name: "Builder banners + status chips",
+    render: () => (
+      <div>
+        <BuilderBanners
+          L={PSEUDO.builder}
+          catalogueToolName="get-builder-catalogue"
+          refreshError="timeout"
+          validationIssues={["demo:id fehlt"]}
+        />
+        <StatusChip status="idle" L={PSEUDO.builder} />
+        <StatusChip status="pending" L={PSEUDO.builder} />
+        <StatusChip status="refreshing" L={PSEUDO.builder} />
+      </div>
+    ),
+  },
+]
+
+describe("no English leaks into a German view", () => {
+  it("the marked catalog marks every string (the scan can see catalog text)", () => {
+    expect(PSEUDO.view.loading).toBe(`⟦${TOOLKIT_MESSAGES.de.view.loading}⟧`)
+    expect(PSEUDO.builder.saved("x")).toBe(`⟦${TOOLKIT_MESSAGES.de.builder.saved("x")}⟧`)
+  })
+
+  for (const renderCase of [...RENDER_CASES, ...CHROME_CASES]) {
+    it(`${renderCase.name} renders only catalog text and props under de`, () => {
+      expect(leaks(renderCase.render())).toEqual([])
+    })
+  }
+
+  it("catches a hard-coded string (gate self-test)", () => {
+    const Leaky = ({ name }: { name: string }) => (
+      <button type="button" aria-label="Close">
+        {name} Load more
+      </button>
+    )
+    expect(leaks(<Leaky name="Rechnung" />)).toEqual([
+      'text: "Rechnung Load more" → "Load more"',
+      'aria-label: "Close" → "Close"',
+    ])
+  })
+})

package/src/index.ts

@@ -71,9 +71,13 @@ export type { UseToolQueryOptions } from "./hooks/use-tool-query.js"
 export { useDebouncedValue } from "./hooks/use-debounced-value.js"
 
 // Tone token system — the semantic status tones (ToneVariant + TONE_* maps)
-// behind the tone-aware components below. Pure data + class strings.
-export { TONE_SOFT, TONE_DOT, TONE_TEXT } from "./lib/tone-utils.js"
+// behind the tone-aware components below. Pure data + class strings. Three
+// roles per tone: colour (TONE_DOT/TONE_BORDER/TONE_ICON), tint (TONE_SOFT,
+// foreground text on it), text on a plain surface (TONE_TEXT, the -ink role).
+export { TONE_SOFT, TONE_DOT, TONE_TEXT, TONE_BORDER, TONE_ICON } from "./lib/tone-utils.js"
 export type { ToneVariant } from "./lib/tone-utils.js"
+// The kit's opaque focus ring as class strings, for custom controls.
+export { FOCUS_RING, FOCUS_RING_INSET } from "./lib/focus-ring.js"
 
 // Composed components — focused widget building blocks assembled from the
 // primitives. Pure (React + primitives + cn), so they live in the root barrel.
@@ -96,6 +100,14 @@ export type { DrillButtonProps } from "./components/DrillButton.js"
 export { ListFooter } from "./components/ListFooter.js"
 export type { ListFooterProps } from "./components/ListFooter.js"
 
+// Feedback and states — one pattern each for toasts, empty and error states.
+export { ToastProvider, useToast } from "./components/Toast.js"
+export type { ToastApi, ToastOptions, ToastTone } from "./components/Toast.js"
+export { EmptyState } from "./components/EmptyState.js"
+export type { EmptyStateProps, StateHeadingLevel } from "./components/EmptyState.js"
+export { ErrorState } from "./components/ErrorState.js"
+export type { ErrorStateProps, ErrorStateTone } from "./components/ErrorState.js"
+
 // Providers
 export { AppQueryProvider, useCallTool, queryClient } from "./providers/query-provider.js"
 
@@ -103,7 +115,23 @@ export { AppQueryProvider, useCallTool, queryClient } from "./providers/query-pr
 // `mcp-use/react`), so it belongs in this root barrel: a consumer can re-skin
 // the toolkit's primitives from a single switch without pulling in the host
 // runtime. See packages/ui/src/theme/ and docs/guides/white-labeling.md.
-export { createTheme, ThemeProvider, useTheme, themePresets } from "./theme/index.js"
+// The defaults are the Miragon theme (theme.css over the vendored --cd-*
+// corporate-design tokens); a brand overrides the ROLE_TOKENS only.
+export {
+  createTheme,
+  resolveThemeVars,
+  ROLE_TOKENS,
+  ThemeProvider,
+  useTheme,
+  usePortalContainer,
+  themePresets,
+  CD_TOKENS,
+  CD_TOKENS_VERSION,
+  fontFaces,
+  GEIST_FONT_FILES,
+  adoptHostFontVariables,
+  HOST_FONT_VARIABLES,
+} from "./theme/index.js"
 export type {
   ThemeTokens,
   ThemeDefinition,
@@ -113,6 +141,9 @@ export type {
   ThemeContextValue,
   ThemeProviderProps,
   ThemePresetId,
+  CdTokenName,
+  FontFacesOptions,
+  InlineStyleTarget,
 } from "./theme/index.js"
 
 // i18n / localization. Browser-safe (React only, no `mcp-use/react`), so it
@@ -120,8 +151,29 @@ export type {
 // <LocaleProvider locale=… translator=…> and reads the active locale with
 // useLocale/useTranslate. Pairs with `createTranslator` from
 // `@miragon/mcp-toolkit-core`. See packages/ui/src/locale/.
-export { LocaleProvider, useLocale, useTranslate } from "./locale/index.js"
-export type { LocaleContextValue, LocaleProviderProps, BoundTranslate } from "./locale/index.js"
+export {
+  LocaleProvider,
+  useLocale,
+  useTranslate,
+  useToolkitMessages,
+  TOOLKIT_MESSAGES,
+  formatCount,
+  resolveToolkitMessages,
+} from "./locale/index.js"
+export type {
+  LocaleContextValue,
+  LocaleProviderProps,
+  BoundTranslate,
+  BuilderMessages,
+  CommonMessages,
+  ListFooterMessages,
+  PropsSheetMessages,
+  RendererMessages,
+  ToolkitLocale,
+  ToolkitMessages,
+  ToolkitMessagesOverride,
+  ViewMessages,
+} from "./locale/index.js"
 
 // NOTE: MCP App shell (McpAppView, WidgetRenderer) is exported from the
 // `./app` subpath only. Keeping it out of the main barrel prevents consumers

package/src/lib/focus-ring.ts

@@ -0,0 +1,20 @@
+/**
+ * The toolkit's focus indicator as Tailwind classes: an opaque 2px ring in the
+ * `--focus` role (blau-link on light, blau-hell on dark — 3:1 or more against
+ * every surface, see `theme/theme-css.test.ts`), offset from the control so it
+ * reads on any fill. Every interactive kit control uses it; spread it into a
+ * custom control's `className` so keyboard focus looks the same everywhere.
+ * (`theme.css` also gives every element without its own ring an opaque
+ * `:focus-visible` outline in the same colour.)
+ *
+ * The ring is a box-shadow, which forced-colors mode (Windows High Contrast)
+ * drops. `outline-hidden` — never `outline-none` — hides the outline only
+ * outside that mode and keeps a transparent 2px outline in it, which the
+ * browser paints in the system colour, so focus stays visible there too.
+ */
+export const FOCUS_RING =
+  "outline-hidden focus-visible:ring-2 focus-visible:ring-focus focus-visible:ring-offset-2 focus-visible:ring-offset-background"
+
+/** {@link FOCUS_RING} drawn inside the element — for cells and rows flush with a container edge. */
+export const FOCUS_RING_INSET =
+  "outline-hidden focus-visible:ring-2 focus-visible:ring-focus focus-visible:ring-inset"

package/src/lib/icon-stroke.test.ts

@@ -0,0 +1,59 @@
+import { describe, expect, it } from "vitest"
+import { DENSE_ICON_STROKE, ICON_STROKE } from "./icon-stroke.js"
+
+/**
+ * ONE mechanism for the Lucide stroke (CI §11): `LucideProvider` with the two
+ * constants of `icon-stroke.ts` — 2.5 for the view (`McpAppView`), 2 in dense
+ * chrome bars. No CSS rule (`svg.lucide { stroke-width }`) in the theme, and no
+ * per-icon `strokeWidth` in kit code, so the two can never disagree.
+ */
+
+declare global {
+  interface ImportMeta {
+    glob(
+      pattern: string | string[],
+      options: { query: "?raw"; import: "default"; eager: true },
+    ): Record<string, string>
+  }
+}
+
+const STYLESHEETS = import.meta.glob(["../*.css", "../theme/*.css"], {
+  query: "?raw",
+  import: "default",
+  eager: true,
+})
+
+const SOURCES = import.meta.glob(["../**/*.tsx", "!../**/*.test.tsx", "!../render-cases*.tsx"], {
+  query: "?raw",
+  import: "default",
+  eager: true,
+})
+
+describe("Lucide stroke: one mechanism", () => {
+  it("is 2.5 for the view and 2 in dense bars (CI §11)", () => {
+    expect(ICON_STROKE).toBe(2.5)
+    expect(DENSE_ICON_STROKE).toBe(2)
+  })
+
+  it("is never set in CSS (theme.css, globals.css, fonts.css, the vendored tokens)", () => {
+    expect(Object.keys(STYLESHEETS)).toEqual(
+      expect.arrayContaining(["../theme.css", "../globals.css"]),
+    )
+    for (const [file, css] of Object.entries(STYLESHEETS)) {
+      expect(css, file).not.toMatch(/stroke-width/)
+    }
+  })
+
+  it("is set only on a LucideProvider, from the icon-stroke constants", () => {
+    const uses: string[] = []
+    for (const [file, source] of Object.entries(SOURCES)) {
+      for (const m of source.matchAll(/<(\w+)[^<>]*\bstrokeWidth=\{?([^}\s>]+)\}?/g)) {
+        uses.push(`${file}: <${m[1]} strokeWidth=${m[2]}>`)
+        expect(m[1], file).toBe("LucideProvider")
+        expect(["ICON_STROKE", "DENSE_ICON_STROKE"], file).toContain(m[2])
+      }
+    }
+    // The view and the three dense bars (view toolbar, builder toolbar, pipeline strip).
+    expect(uses.length).toBeGreaterThanOrEqual(4)
+  })
+})

package/src/lib/icon-stroke.ts

@@ -0,0 +1,13 @@
+/**
+ * Lucide stroke widths of the toolkit's chrome (CI §11, on the 24 px grid).
+ * Set once through `LucideProvider`: `McpAppView` applies {@link ICON_STROKE}
+ * to everything it renders (its toast stack included), dense bars narrow it
+ * to {@link DENSE_ICON_STROKE}. Icons of a consumer's own `lucide-react` follow
+ * the provider only when they resolve to the same module instance (dedupe it).
+ */
+
+/** Default stroke of the toolkit's icons. */
+export const ICON_STROKE = 2.5
+
+/** Stroke in dense chrome bars (the view toolbar, the builder's bars). */
+export const DENSE_ICON_STROKE = 2

package/src/lib/toast-model.test.ts

@@ -0,0 +1,68 @@
+import { describe, expect, it } from "vitest"
+import {
+  createToast,
+  MAX_VISIBLE_TOASTS,
+  TOAST_DURATION_MS,
+  TOAST_ERROR_DURATION_MS,
+  toastDuration,
+  toastReducer,
+  type ToastItem,
+} from "./toast-model.js"
+
+const item = (id: number): ToastItem => createToast(id, { title: `t${id}` })
+
+describe("toastDuration (CI §8: about 2.8 s, errors about 5 s)", () => {
+  it("defaults to 2.8 s and gives errors 5 s", () => {
+    expect(TOAST_DURATION_MS).toBe(2800)
+    expect(TOAST_ERROR_DURATION_MS).toBe(5000)
+    expect(toastDuration("success")).toBe(2800)
+    expect(toastDuration("info")).toBe(2800)
+    expect(toastDuration("warning")).toBe(2800)
+    expect(toastDuration("danger")).toBe(5000)
+  })
+
+  it("honours an explicit positive duration and ignores an unusable one", () => {
+    expect(toastDuration("danger", 1200)).toBe(1200)
+    expect(toastDuration("info", 0)).toBe(2800)
+    expect(toastDuration("info", -5)).toBe(2800)
+    expect(toastDuration("danger", Number.NaN)).toBe(5000)
+    expect(toastDuration("danger", Number.POSITIVE_INFINITY)).toBe(5000)
+  })
+})
+
+describe("createToast", () => {
+  it("defaults to the info tone and drops an empty description", () => {
+    expect(createToast(1, { title: "Saved" })).toEqual({
+      id: 1,
+      tone: "info",
+      title: "Saved",
+      duration: 2800,
+    })
+    expect(createToast(2, { title: "x", description: "" })).not.toHaveProperty("description")
+  })
+
+  it("keeps tone, description and the tone's duration", () => {
+    expect(createToast(3, { tone: "danger", title: "Failed", description: "503" })).toEqual({
+      id: 3,
+      tone: "danger",
+      title: "Failed",
+      description: "503",
+      duration: 5000,
+    })
+  })
+})
+
+describe("toastReducer", () => {
+  it("appends and keeps at most the newest MAX_VISIBLE_TOASTS", () => {
+    expect(MAX_VISIBLE_TOASTS).toBe(3)
+    let state: ToastItem[] = []
+    for (let id = 1; id <= 4; id++) state = toastReducer(state, { type: "add", toast: item(id) })
+    expect(state.map((t) => t.id)).toEqual([2, 3, 4])
+  })
+
+  it("dismisses by id and keeps the list identity when nothing matches", () => {
+    const state = [item(1), item(2)]
+    expect(toastReducer(state, { type: "dismiss", id: 1 }).map((t) => t.id)).toEqual([2])
+    expect(toastReducer(state, { type: "dismiss", id: 9 })).toBe(state)
+  })
+})

package/src/lib/toast-model.ts

@@ -0,0 +1,63 @@
+/**
+ * Pure model behind `ToastProvider` / `useToast`: the toast list as a reducer
+ * plus the timing rules, so both are testable without a DOM (the house path,
+ * FITNESS.md) and the component stays a thin view over them.
+ */
+
+/** Status tone of a toast — the four status roles (`--success` … `--info`). */
+export type ToastTone = "success" | "warning" | "danger" | "info"
+
+/** What a caller passes to `useToast().show(...)`. */
+export interface ToastOptions {
+  /** Status tone; drives the edge, the icon and the default duration. Default `"info"`. */
+  tone?: ToastTone
+  /** The message. Say what happened, in one short sentence ("Job retried."). */
+  title: string
+  /** Optional second line (what you can do next, or the affected object). */
+  description?: string
+  /** Auto-dismiss after this many ms. Defaults per {@link toastDuration}. */
+  duration?: number
+}
+
+/** A toast as it sits in the list. */
+export interface ToastItem {
+  id: number
+  tone: ToastTone
+  title: string
+  description?: string
+  duration: number
+}
+
+/** Default lifetime of a toast (CI §8: about 2.8 s). */
+export const TOAST_DURATION_MS = 2800
+/** Lifetime of an error toast (CI §8: about 5 s) — long enough to read the reason. */
+export const TOAST_ERROR_DURATION_MS = 5000
+/** At most this many toasts stack; the oldest leaves first. */
+export const MAX_VISIBLE_TOASTS = 3
+
+/** The lifetime of a toast: an explicit positive duration, else the tone's default. */
+export function toastDuration(tone: ToastTone, explicit?: number): number {
+  if (explicit !== undefined && Number.isFinite(explicit) && explicit > 0) return explicit
+  return tone === "danger" ? TOAST_ERROR_DURATION_MS : TOAST_DURATION_MS
+}
+
+/** Normalise caller options into a list item. */
+export function createToast(id: number, options: ToastOptions): ToastItem {
+  const tone = options.tone ?? "info"
+  return {
+    id,
+    tone,
+    title: options.title,
+    ...(options.description ? { description: options.description } : {}),
+    duration: toastDuration(tone, options.duration),
+  }
+}
+
+export type ToastAction = { type: "add"; toast: ToastItem } | { type: "dismiss"; id: number }
+
+/** Add appends (dropping the oldest beyond {@link MAX_VISIBLE_TOASTS}); dismiss removes by id. */
+export function toastReducer(state: readonly ToastItem[], action: ToastAction): ToastItem[] {
+  if (action.type === "add") return [...state, action.toast].slice(-MAX_VISIBLE_TOASTS)
+  const next = state.filter((t) => t.id !== action.id)
+  return next.length === state.length ? (state as ToastItem[]) : next
+}