@miragon/mcp-toolkit-ui 2.6.0 → 2.8.0

package/src/hooks/use-view-tool-query.ts

@@ -1,10 +1,15 @@
 import { useQuery, type UseQueryResult } from "@tanstack/react-query"
-import { useCallTool } from "../providers/query-provider.js"
+import { useCallTool, useToolNameInQueryKey } from "../providers/query-provider.js"
 import { parseViewToolResult } from "../lib/parse-tool-result.js"
+import { toolQueryOptions, type UseToolQueryOptions } from "../lib/tool-query.js"
+import { useRefetchOnTransport, useToolKeyGuard } from "./use-tool-query.js"
 
-export interface UseViewToolQueryOptions {
-  enabled?: boolean
-}
+/**
+ * Options of {@link useViewToolQuery}: TanStack's query options, passed
+ * through like `useToolQuery`'s (`enabled`, `retry`, `staleTime`,
+ * `placeholderData`, `initialData`, …).
+ */
+export type UseViewToolQueryOptions<T = unknown> = UseToolQueryOptions<T>
 
 /**
  * Self-fetch hook for `*_show_*` widget tools — the envelope-unwrapping sibling
@@ -14,25 +19,26 @@ export interface UseViewToolQueryOptions {
  * envelope; this hook decodes via {@link parseViewToolResult} (single-step →
  * flat data, multi-step → keyed by step id) instead.
  *
- * `args` is appended to the effective query key — same queryKey-vs-args
- * contract as {@link useToolQuery}, so sibling widgets sharing a query key
- * collapse to a single deduped tool call.
+ * Same key and options contract as {@link useToolQuery}: the effective key is
+ * `[...queryKey, args]` (`[...queryKey, toolName, args]` under an
+ * `AppQueryProvider` with `toolNameInQueryKey`), so sibling widgets sharing a
+ * query key and args collapse to a single deduped tool call.
  */
 export function useViewToolQuery<T = unknown>(
-  queryKey: unknown[],
+  queryKey: readonly unknown[],
   toolName: string,
   args: object,
-  opts?: UseViewToolQueryOptions,
+  opts?: UseViewToolQueryOptions<T>,
 ): UseQueryResult<T, Error> {
   const callTool = useCallTool()
-
-  return useQuery<T, Error>({
-    queryKey: [...queryKey, args],
-    queryFn: async () => {
-      if (!callTool) throw new Error("callTool not available")
-      const result = await callTool(toolName, args)
-      return parseViewToolResult<T>(result)
-    },
-    enabled: !!callTool && (opts?.enabled ?? true),
-  })
+  const toolNameInKey = useToolNameInQueryKey()
+  useToolKeyGuard(queryKey, toolName, args)
+  const query = useQuery<T, Error>(
+    toolQueryOptions<T>(queryKey, toolName, args, callTool, opts, {
+      decode: parseViewToolResult,
+      toolNameInKey,
+    }),
+  )
+  useRefetchOnTransport(callTool, query)
+  return query
 }

package/src/i18n-coverage.test.tsx

@@ -0,0 +1,425 @@
+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 { Workspace } from "./app/builder/Workspace.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: "ViewPlaceholder blocked (a writing tool, no retry)",
+    render: () => (
+      <ViewPlaceholder
+        lifecycle={{ phase: "error", reason: undefined, canRetry: false, kind: "blocked" }}
+        labels={PSEUDO.view}
+        onRetry={noop}
+      />
+    ),
+  },
+  {
+    name: "ViewPlaceholder blocked (load the view)",
+    render: () => (
+      <ViewPlaceholder
+        lifecycle={{ phase: "error", reason: undefined, canRetry: true, kind: "blocked" }}
+        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}
+        dataAsOf="14:32"
+      />
+    ),
+  },
+  {
+    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 (advanced, unsaved)",
+    render: () => (
+      <Toolbar
+        L={PSEUDO.builder}
+        previewMode={false}
+        isBusy={false}
+        status="pending"
+        liveKeys={2}
+        reachableCount={5}
+        unreachableCount={1}
+        advanced
+        onToggleAdvanced={noop}
+        unsaved
+        onOpenCatalogue={noop}
+        onOpenSave={noop}
+        onDiscard={noop}
+        onApply={noop}
+        hasAnyCell
+      />
+    ),
+  },
+  {
+    name: "Builder workspace (titled and untitled palette entries, canvas cells)",
+    render: () => (
+      <Workspace
+        L={PSEUDO.builder}
+        paletteByApp={[
+          [
+            "demo",
+            [
+              {
+                id: "demo:orders",
+                app: "demo",
+                requires: ["demo:key"],
+                size: "full",
+                title: { en: "Orders", de: "Bestellungen" },
+                summary: { de: "Alle offenen Bestellungen." },
+              },
+              { id: "demo:raw", app: "demo", requires: [], size: "half" },
+            ],
+          ],
+        ]}
+        appDisplayByName={new Map()}
+        paletteCount={2}
+        paletteLoading={false}
+        onOpenDataSources={noop}
+        activeRows={[{ row: [{ widget: "demo:orders" }] }, { row: [] }]}
+        focusedRowIndex={0}
+        setFocusedRowIndex={noop}
+        dragOverRow={null}
+        setDragOverRow={noop}
+        onAddRow={noop}
+        onRemoveRow={noop}
+        onMoveRow={noop}
+        onSetCellSpan={noop}
+        onRemoveCell={noop}
+        onAddWidget={noop}
+        onConfigureCell={noop}
+        propsSchemaByWidgetId={new Map([["demo:orders", { type: "object" }]])}
+        displayByWidgetId={new Map([["demo:orders", { title: { de: "Bestellungen" } }]])}
+        advanced
+        widgets={{}}
+        widgetProps={{ keys: {}, context: { keys: {}, steps: {}, errors: [] } }}
+        onAddTab={noop}
+      />
+    ),
+  },
+  ...[true, false].map((paletteLoading) => ({
+    name: `Builder workspace (palette ${paletteLoading ? "loading" : "empty"})`,
+    render: () => (
+      <Workspace
+        L={PSEUDO.builder}
+        paletteByApp={[]}
+        appDisplayByName={new Map()}
+        paletteCount={0}
+        paletteLoading={paletteLoading}
+        onOpenDataSources={noop}
+        activeRows={[{ row: [] }]}
+        focusedRowIndex={0}
+        setFocusedRowIndex={noop}
+        dragOverRow={null}
+        setDragOverRow={noop}
+        onAddRow={noop}
+        onRemoveRow={noop}
+        onMoveRow={noop}
+        onSetCellSpan={noop}
+        onRemoveCell={noop}
+        onAddWidget={noop}
+        onConfigureCell={noop}
+        propsSchemaByWidgetId={new Map()}
+        displayByWidgetId={new Map()}
+        advanced={false}
+        widgets={{}}
+        widgetProps={{ keys: {}, context: { keys: {}, steps: {}, errors: [] } }}
+      />
+    ),
+  })),
+  {
+    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

@@ -66,27 +66,65 @@ export {
 // NOTE: the view-tool hooks (`useViewToolQuery`, `useViewData`) are exported
 // from the `./hooks` subpath only — see `packages/ui/src/hooks/index.ts`.
 export { useIsMobile } from "./hooks/use-mobile.js"
-export { useToolQuery, useToolMutation } from "./hooks/use-tool-query.js"
-export type { UseToolQueryOptions } from "./hooks/use-tool-query.js"
+export { useToolQuery, useToolQueryKey, useToolMutation } from "./hooks/use-tool-query.js"
+export type { UseToolQueryOptions, UseToolMutationOptions } from "./hooks/use-tool-query.js"
+// The query layer's contract: the effective cache key, the opt-in retry
+// policy (no retry of a tool's own isError answer), and TanStack's
+// keepPreviousData for `placeholderData`, so a consumer needs no direct
+// @tanstack/react-query import for the common options.
+export { toolQueryKey, shouldRetryToolCall } from "./lib/tool-query.js"
+export { ToolResultError, isToolError } from "./lib/parse-tool-result.js"
+export { keepPreviousData } from "@tanstack/react-query"
 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"
-export type { ToneVariant } from "./lib/tone-utils.js"
+// behind the tone-aware components below. Pure data + class strings. ONE
+// vocabulary (TONE_VARIANTS; retired names map through resolveTone). Three
+// roles per tone: colour (TONE_DOT/TONE_BORDER/TONE_ICON), tint (TONE_SOFT,
+// foreground text on it; TONE_TINT alone), text on a plain surface (TONE_INK,
+// the -ink role; TONE_TEXT is its deprecated name).
+export {
+  TONE_VARIANTS,
+  TONE_ALIASES,
+  resolveTone,
+  isToneVariant,
+  TONE_SOFT,
+  TONE_TINT,
+  TONE_DOT,
+  TONE_INK,
+  TONE_TEXT,
+  TONE_BORDER,
+  TONE_ICON,
+} from "./lib/tone-utils.js"
+export type { ToneVariant, ToneAlias, ToneName } from "./lib/tone-utils.js"
+// The type scale (CI §4): text-title/section/body/dense/small utilities, 13 px floor.
+export { TYPE_SCALE, TYPE_STEPS, TYPE_FLOOR_PX, MICRO_LABEL } from "./lib/typography.js"
+export type { TypeStep } from "./lib/typography.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.
 export { GridLayout, GridItem } from "./components/GridLayout.js"
 export type { GridLayoutProps, GridItemProps } from "./components/GridLayout.js"
-export { KpiGrid } from "./components/KpiGrid.js"
-export type { KpiGridProps, KpiGridHeader, KpiCell } from "./components/KpiGrid.js"
-export { LivePill, CountPill } from "./components/Pills.js"
-export type { LivePillProps, CountPillProps } from "./components/Pills.js"
+export { KpiGrid, KpiGridSkeleton } from "./components/KpiGrid.js"
+export type {
+  KpiGridProps,
+  KpiGridHeader,
+  KpiCell,
+  KpiGridSkeletonProps,
+} from "./components/KpiGrid.js"
+export { LivePill, CountPill, StatusBadge } from "./components/Pills.js"
+export type {
+  LivePillProps,
+  CountPillProps,
+  StatusBadgeProps,
+  StatusBadgeText,
+} from "./components/Pills.js"
 export { SectionHeading } from "./components/SectionHeading.js"
 export type { SectionHeadingProps } from "./components/SectionHeading.js"
 export { WidgetHeader } from "./components/WidgetHeader.js"
-export type { WidgetHeaderProps } from "./components/WidgetHeader.js"
+export type { WidgetHeaderProps, WidgetHeadingLevel } from "./components/WidgetHeader.js"
 export { GroupCard } from "./components/GroupCard.js"
 export type { GroupCardProps } from "./components/GroupCard.js"
 export { FilterBar } from "./components/FilterBar.js"
@@ -95,6 +133,16 @@ export { DrillButton } from "./components/DrillButton.js"
 export type { DrillButtonProps } from "./components/DrillButton.js"
 export { ListFooter } from "./components/ListFooter.js"
 export type { ListFooterProps } from "./components/ListFooter.js"
+export { PagedListFooter } from "./components/PagedListFooter.js"
+export type { PagedListFooterProps, PagedListState } from "./components/PagedListFooter.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 +151,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 +177,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 +187,30 @@ 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,
+  FilterBarMessages,
+  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