@miragon/mcp-toolkit-ui 2.6.0 → 2.8.0

package/ui-catalog.json

@@ -46,9 +46,9 @@
       "props": [
         {
           "name": "variant",
-          "type": "\"default\" | \"secondary\" | \"destructive\" | \"outline\" | \"ghost\" | \"link\"",
+          "type": "\"default\" | \"secondary\" | \"danger\" | \"success\" | \"warning\" | \"info\" | \"outline\" | \"ghost\" | \"link\" | \"destructive\"",
           "required": false,
-          "description": "Visual style. Default 'default'."
+          "description": "Visual style. Default 'default'. danger/success/warning/info follow the tone model: tint + foreground text, rim in the tone (TONE_SOFT + TONE_BORDER). 'destructive' is the deprecated name of 'danger'."
         },
         {
           "name": "className",
@@ -285,9 +285,9 @@
       "props": [
         {
           "name": "variant",
-          "type": "\"default\" | \"destructive\"",
+          "type": "\"default\" | \"danger\" | \"destructive\"",
           "required": false,
-          "description": "Visual style."
+          "description": "Visual style. 'danger': tint, rim and icon in the danger colour, foreground text. 'destructive' is its deprecated name. For a failed fetch prefer ErrorState (title, next step, Details, retry)."
         }
       ],
       "whenToUse": "Inline notice or error message inside a widget body."
@@ -396,7 +396,13 @@
           "name": "cells",
           "type": "KpiCell[]",
           "required": true,
-          "description": "Metric cells flowed as columns (1–6, clamped). Each: { label, value, fraction?, trend?, trendDirection?, tone?, onClick?, ariaLabel? }. A cell with onClick renders as a button (drill into a detail view)."
+          "description": "Metric cells: { label, value, fraction?, trend?, trendDirection?: 'up'|'down'|'flat', trendTone?, tone?, onClick?, actionHint? }. Flows 1–6 columns (4+ fall back to 2 in narrow frames). A cell with onClick is a button named by its visible label and value; actionHint ('Opens the incidents dashboard') becomes its aria-describedby. ariaLabel is deprecated (it hides the visible label from voice control, WCAG 2.5.3)."
+        },
+        {
+          "name": "variant",
+          "type": "'strip' | 'soft'",
+          "required": false,
+          "description": "'strip' (default): one bordered strip, tone as a dot next to the label. 'soft': a card per cell in its tone's tint and edge (boxed/header don't apply)."
         },
         {
           "name": "boxed",
@@ -408,10 +414,56 @@
           "name": "header",
           "type": "KpiGridHeader",
           "required": false,
-          "description": "Group header shown above the strip when boxed: { label, badge? }."
+          "description": "Group header above the strip: { label, badge? } (13 px semibold, normal case)."
+        },
+        {
+          "name": "ariaLabel",
+          "type": "string",
+          "required": false,
+          "description": "Names the group of metrics (role=group); omit when a heading right above names it."
+        },
+        {
+          "name": "className",
+          "type": "string",
+          "required": false,
+          "description": "Merged onto the root element."
+        }
+      ],
+      "whenToUse": "Show a row of headline metrics in a widget (replaces the old single-metric KPICard). Pre-format values for locale/currency. Figures stay in the foreground at the page-title size; a cell tone shows as a dot next to its label, a trend as a Lucide direction icon (or a dot with trendTone) next to neutral words. Set onClick + actionHint to make a metric a drill target. Pair with KpiGridSkeleton while loading."
+    },
+    {
+      "name": "KpiGridSkeleton",
+      "export": "KpiGridSkeleton",
+      "importPath": "@miragon/mcp-toolkit-ui",
+      "kind": "component",
+      "group": "composed",
+      "props": [
+        {
+          "name": "cells",
+          "type": "number",
+          "required": true,
+          "description": "How many cells the loaded grid will have."
+        },
+        {
+          "name": "variant",
+          "type": "'strip' | 'soft'",
+          "required": false,
+          "description": "The loaded grid's variant. Default 'strip'."
+        },
+        {
+          "name": "boxed",
+          "type": "boolean",
+          "required": false,
+          "description": "The loaded grid's boxed. Default false."
+        },
+        {
+          "name": "className",
+          "type": "string",
+          "required": false,
+          "description": "Merged onto the root element."
         }
       ],
-      "whenToUse": "Show a row of headline metrics in a widget (replaces the old single-metric KPICard). Pre-format values for locale/currency. Set a cell tone for emphasis (e.g. 'danger') and onClick to make a metric a drill target."
+      "whenToUse": "Loading placeholder with KpiGrid's geometry (same wrapper, grid and cell padding), so the layout doesn't jump when the data arrives. Marked aria-busy."
     },
     {
       "name": "LivePill",
@@ -422,15 +474,21 @@
       "props": [
         {
           "name": "tone",
-          "type": "ToneVariant",
+          "type": "ToneName",
           "required": false,
-          "description": "Status tone driving the dot + tint ('neutral'|'info'|'success'|'warning'|'danger'). Default 'info'."
+          "description": "Status tone driving the dot, tint and border ('neutral'|'info'|'success'|'warning'|'danger'): tint + foreground text, rim in the tone (TONE_SOFT + TONE_BORDER). Default 'info'."
         },
         {
           "name": "children",
           "type": "ReactNode",
           "required": false,
           "description": "Pill label. Defaults to 'Live'."
+        },
+        {
+          "name": "className",
+          "type": "string",
+          "required": false,
+          "description": "Merged onto the root element."
         }
       ],
       "whenToUse": "Signal live/real-time data in a widget header — a tinted pill with a pulsing dot."
@@ -444,19 +502,53 @@
       "props": [
         {
           "name": "tone",
-          "type": "ToneVariant",
+          "type": "ToneName",
           "required": false,
-          "description": "Status tone driving the tint. Default 'neutral'."
+          "description": "Status tone driving the tint and border: tint + foreground text, rim in the tone (TONE_SOFT + TONE_BORDER); the number never takes a tone colour, also on the neutral tint. Default 'neutral'."
         },
         {
           "name": "children",
           "type": "ReactNode",
           "required": true,
           "description": "The count/value (rendered with tabular numbers)."
+        },
+        {
+          "name": "className",
+          "type": "string",
+          "required": false,
+          "description": "Merged onto the root element."
         }
       ],
       "whenToUse": "Right-aligned count indicator on a list/group row (e.g. a per-group item count)."
     },
+    {
+      "name": "StatusBadge",
+      "export": "StatusBadge",
+      "importPath": "@miragon/mcp-toolkit-ui",
+      "kind": "component",
+      "group": "composed",
+      "props": [
+        {
+          "name": "children",
+          "type": "string | number | ReactElement | (string | number | ReactElement)[]",
+          "required": true,
+          "description": "The state in words ('Suspended', '3 open incidents'). Required: colour is never the only signal."
+        },
+        {
+          "name": "tone",
+          "type": "ToneName",
+          "required": true,
+          "description": "The state's tone: tint, edge and a static dot ('danger'|'warning'|'success'|'info'|'neutral'; retired names map through resolveTone)."
+        },
+        {
+          "name": "className",
+          "type": "string",
+          "required": false,
+          "description": "Merged onto the root element."
+        }
+      ],
+      "whenToUse": "Say a state in words, marked in its tone: a detail-page header (WidgetHeader badge) or a table cell. Foreground text on the tint, never coloured words. For live data use LivePill, for a count CountPill."
+    },
     {
       "name": "SectionHeading",
       "export": "SectionHeading",
@@ -499,16 +591,28 @@
           "description": "The widget title."
         },
         {
-          "name": "icon",
+          "name": "as",
+          "type": "'h1' | 'h2' | 'h3' | 'h4' | 'h5' | 'h6'",
+          "required": false,
+          "description": "Heading element. Default 'h1'. Pick the level that keeps one outline per view: below a toolbar title (an h2) use 'h3'. The size follows `size`, not the level."
+        },
+        {
+          "name": "size",
+          "type": "'default' | 'detail'",
+          "required": false,
+          "description": "'default': page title (28 px / 700); 'detail': compact detail-page title (21 px / 600)."
+        },
+        {
+          "name": "badge",
           "type": "ReactNode",
           "required": false,
-          "description": "Icon/glyph rendered in a tinted tile above the title."
+          "description": "Above the title: a StatusBadge that says the state in words."
         },
         {
-          "name": "iconTone",
-          "type": "ToneVariant",
+          "name": "titleSuffix",
+          "type": "ReactNode",
           "required": false,
-          "description": "Tone for the icon tile. Default 'neutral'."
+          "description": "Inline after the title inside the heading (e.g. a version chip)."
         },
         {
           "name": "sub",
@@ -521,9 +625,27 @@
           "type": "ReactNode",
           "required": false,
           "description": "Right-aligned actions slot (buttons, drill controls)."
+        },
+        {
+          "name": "icon",
+          "type": "ReactNode",
+          "required": false,
+          "description": "Deprecated: the icon tile above the title is the anti-slop U2 pattern; use badge. Still rendered (aria-hidden)."
+        },
+        {
+          "name": "iconTone",
+          "type": "ToneName",
+          "required": false,
+          "description": "Deprecated: tone of the icon tile."
+        },
+        {
+          "name": "className",
+          "type": "string",
+          "required": false,
+          "description": "Merged onto the root element."
         }
       ],
-      "whenToUse": "Anchor the top of a dashboard widget surface: tinted icon tile, large title, meta row, and an actions slot. Use once per widget."
+      "whenToUse": "Anchor the top of a widget surface: optional state badge, the title at a configurable heading level, a meta row and an actions slot. Use once per widget; with McpAppView's toolbar title shown, set titleMode='hide' or as='h3' so the view keeps one title and one outline."
     },
     {
       "name": "GroupCard",
@@ -582,7 +704,7 @@
           "name": "chips",
           "type": "FilterChip[]",
           "required": true,
-          "description": "Toggleable filter chips: { id, label, count?, active? }."
+          "description": "Toggle chips: { id, label, count?, active? }. Each is a button with aria-pressed; an active chip is the info tint and edge around foreground text."
         },
         {
           "name": "onChipToggle",
@@ -595,9 +717,27 @@
           "type": "string",
           "required": false,
           "description": "Placeholder for the search input. Default 'Filter…'."
+        },
+        {
+          "name": "searchAriaLabel",
+          "type": "string",
+          "required": false,
+          "description": "Accessible name of the search input. Default: the locale's 'Filter' (a placeholder is no label)."
+        },
+        {
+          "name": "chipsAriaLabel",
+          "type": "string",
+          "required": false,
+          "description": "Names the chip group (role=group). Default: the locale's 'Filters'."
+        },
+        {
+          "name": "className",
+          "type": "string",
+          "required": false,
+          "description": "Merged onto the root element."
         }
       ],
-      "whenToUse": "Filter a list/table of widget items with a search box + chip row. Pair with useDebouncedValue so a server-side filter only re-queries once typing pauses."
+      "whenToUse": "Filter a list/table of widget items with a labelled search box + a row of toggle chips (aria-pressed). Pair with useDebouncedValue so a server-side filter only re-queries once typing pauses."
     },
     {
       "name": "DrillButton",
@@ -622,7 +762,7 @@
           "name": "icon",
           "type": "ReactNode",
           "required": false,
-          "description": "Optional leading glyph; the trailing → is always rendered."
+          "description": "Optional leading Lucide icon (decorative, never a typed glyph); the trailing Lucide arrow is always rendered."
         },
         {
           "name": "size",
@@ -634,7 +774,7 @@
           "name": "ariaLabel",
           "type": "string",
           "required": false,
-          "description": "Accessible label when the visible text is terse."
+          "description": "Accessible label when the visible text is terse; keep the visible text in it (WCAG 2.5.3)."
         }
       ],
       "whenToUse": "The single neutral in-widget navigation control (drill into a detail/sub-view). Use it for every drill so they read identically and stay visually quieter than primary/agentic actions."
@@ -680,10 +820,74 @@
           "name": "noun",
           "type": "string",
           "required": false,
-          "description": "Plural noun for the count, e.g. 'instances'. Default 'rows'."
+          "description": "Plural noun for the count, e.g. 'instances'. Default: the locale's word for rows."
+        },
+        {
+          "name": "refreshing",
+          "type": "boolean",
+          "required": false,
+          "description": "A first page is in flight while these rows stay on screen: the status line adds a visible 'Updating…'."
+        },
+        {
+          "name": "stale",
+          "type": "boolean",
+          "required": false,
+          "description": "The rows on screen are the previous result: count and Load more hide, so the old count never reads as the new search's answer."
+        },
+        {
+          "name": "labels",
+          "type": "Partial<ListFooterMessages>",
+          "required": false,
+          "description": "Override strings of the active catalog's listFooter section."
+        },
+        {
+          "name": "announce",
+          "type": "boolean",
+          "required": false,
+          "description": "Make the count line a polite live region (role=status). Default true; false only where the caller announces the count in a live region of its own."
+        },
+        {
+          "name": "className",
+          "type": "string",
+          "required": false,
+          "description": "Merged onto the root element."
+        }
+      ],
+      "whenToUse": "Footer for a paginated list: an honest 'Showing X of Y' total + an explicit 'Load more' (not infinite scroll). The count is a polite live region (role=status), so the new total is announced after Load more or a filter change. At zero rows it shows nothing but keeps the region mounted (visually hidden) with 'No entries', so a search that finds nothing is announced too. Text and number format follow the active locale. For a paged query with failures use PagedListFooter."
+    },
+    {
+      "name": "PagedListFooter",
+      "export": "PagedListFooter",
+      "importPath": "@miragon/mcp-toolkit-ui",
+      "kind": "component",
+      "group": "composed",
+      "props": [
+        {
+          "name": "paged",
+          "type": "PagedListState",
+          "required": true,
+          "description": "{ items, total, hasMore, loadMore, loadingMore?, refreshing?, stale?, firstPage?, error?, retry?, loadMoreError? } — a paged-query hook's result passes as is."
+        },
+        {
+          "name": "noun",
+          "type": "string",
+          "required": false,
+          "description": "Plural noun for the count. Default: the locale's word for rows."
+        },
+        {
+          "name": "labels",
+          "type": "Partial<ListFooterMessages>",
+          "required": false,
+          "description": "Override strings of the active catalog's listFooter section."
+        },
+        {
+          "name": "retryLabel",
+          "type": "string",
+          "required": false,
+          "description": "Retry button label of both error lines. Default: the locale's 'Try again'."
         }
       ],
-      "whenToUse": "Footer for a paginated list: an honest 'Showing X of Y' total + an explicit 'Load more' (not infinite scroll)."
+      "whenToUse": "The tail of a paged list: a failed first page over the previous rows (warning alert, retry re-runs page 0) and a failed load-more (danger alert, retry fetches the next offset) stay apart, each with the raw reason under Details; then the ListFooter with 'Updating…' while page 0 is in flight and no count while the rows are stale."
     },
     {
       "name": "Tone tokens",
@@ -691,9 +895,187 @@
       "importPath": "@miragon/mcp-toolkit-ui",
       "kind": "object",
       "group": "composed",
-      "parts": ["TONE_SOFT", "TONE_DOT", "TONE_TEXT"],
+      "parts": [
+        "TONE_SOFT",
+        "TONE_TINT",
+        "TONE_DOT",
+        "TONE_INK",
+        "TONE_TEXT",
+        "TONE_BORDER",
+        "TONE_ICON"
+      ],
+      "props": [],
+      "whenToUse": "Record<ToneVariant, string> maps from a status tone ('neutral'|'info'|'success'|'warning'|'danger') to Tailwind class strings, three roles per tone (Miragon CI): the colour for fills, dots, borders and icons (TONE_DOT, TONE_BORDER, TONE_ICON), the tint (TONE_SOFT = tint + foreground text, rim in the tone via TONE_BORDER; TONE_TINT = the tint alone; never put TONE_INK on a tint) and the TEXT colour for a tone's words on a plain surface (TONE_INK = the tone's -ink role; TONE_TEXT is its deprecated name). Status is never text in its own colour: success and warning ink is the foreground, so show the tone as a dot, icon or border next to the text; figures (counts, KPI values) stay in the foreground. TONE_ICON is for SVG icons only. Use to colour a custom element by status without a tone === 'x' ? ... ternary; the tone-aware components (KpiGrid, LivePill, CountPill, StatusBadge, Badge) consume these internally."
+    },
+    {
+      "name": "Tone vocabulary",
+      "export": "resolveTone",
+      "importPath": "@miragon/mcp-toolkit-ui",
+      "kind": "function",
+      "group": "composed",
+      "parts": ["resolveTone", "isToneVariant", "TONE_VARIANTS", "TONE_ALIASES"],
+      "props": [
+        {
+          "name": "name",
+          "type": "unknown",
+          "required": true,
+          "description": "A tone name, possibly from data: a ToneVariant or a retired alias ('critical', 'error', 'destructive', 'warn', 'ok', …)."
+        },
+        {
+          "name": "fallback",
+          "type": "ToneVariant",
+          "required": false,
+          "description": "The tone for anything unknown. Default 'neutral'."
+        }
+      ],
+      "whenToUse": "ONE tone vocabulary: success | warning | danger | info | neutral (TONE_VARIANTS). resolveTone maps a retired or foreign name onto it (critical/error/destructive → danger; one red, one amber) and anything unknown onto the fallback, so a tone that arrives as data never renders colourless; isToneVariant is the type guard. The props typed ToneName resolve it this way (KpiCell tone/trendTone, LivePill, StatusBadge, CountPill, WidgetHeader iconTone). Toast, ErrorState and EmptyState keep their own tone subset in the types; an untyped name still resolves at runtime and anything outside the subset gets their default. Badge/Alert variants are cva keys: pass a resolved tone."
+    },
+    {
+      "name": "ToastProvider",
+      "export": "ToastProvider",
+      "importPath": "@miragon/mcp-toolkit-ui",
+      "kind": "component",
+      "group": "feedback",
+      "props": [
+        {
+          "name": "children",
+          "type": "ReactNode",
+          "required": true,
+          "description": "Subtree that raises toasts via useToast."
+        }
+      ],
+      "whenToUse": "Provide toasts to a subtree and render their stack: bottom centre, status colour as left edge + icon next to plain text, ONE persistent live region (aria-live=polite, fixed attributes: no role or name, so the first toast is announced; tests find it by data-slot=toast-viewport), toast text at 16 px, auto-dismiss after 2.8 s (errors 5 s), held while hovered or focused. Idempotent when nested. McpAppView mounts one, so widgets inside a view only call useToast. Toast icons follow the LucideProvider around the outermost ToastProvider (stroke 2.5 inside McpAppView)."
+    },
+    {
+      "name": "useToast",
+      "export": "useToast",
+      "importPath": "@miragon/mcp-toolkit-ui",
+      "kind": "hook",
+      "group": "feedback",
       "props": [],
-      "whenToUse": "Record<ToneVariant, string> maps from a status tone ('neutral'|'info'|'success'|'warning'|'danger') to Tailwind class strings (TONE_SOFT = soft tint, TONE_DOT = dot colour, TONE_TEXT = text colour), backed by the semantic status tokens in globals.css and re-skinned by the theme. Use to colour a custom element by status without a tone === 'x' ? ... ternary; the tone-aware components (KpiGrid, LivePill, CountPill, WidgetHeader) consume these internally."
+      "whenToUse": "Raise feedback after a user action instead of logging to the console: useToast().show({ tone: 'success' | 'warning' | 'danger' | 'info', title, description?, duration? }) returns an id; dismiss(id) removes it early. Name the object in the title ('Job retried.'); the description says what to do next. Both come from your catalog: never put a raw error (e.message) in a toast, log it or show it under an ErrorState's Details. Outside a ToastProvider it is a safe no-op."
+    },
+    {
+      "name": "EmptyState",
+      "export": "EmptyState",
+      "importPath": "@miragon/mcp-toolkit-ui",
+      "kind": "component",
+      "group": "feedback",
+      "props": [
+        {
+          "name": "title",
+          "type": "ReactNode",
+          "required": true,
+          "description": "What is empty, in plain words."
+        },
+        {
+          "name": "description",
+          "type": "ReactNode",
+          "required": false,
+          "description": "One help line: why it is empty or what to do next."
+        },
+        {
+          "name": "icon",
+          "type": "ReactNode",
+          "required": false,
+          "description": "Decorative icon or brand mark (aria-hidden): a Lucide icon for the situation (24 px), or a logo; an SVG with its own size-* class keeps that size."
+        },
+        {
+          "name": "tone",
+          "type": "'neutral' | 'success'",
+          "required": false,
+          "description": "Icon colour; 'success' for an 'all done' state. Default 'neutral'."
+        },
+        {
+          "name": "action",
+          "type": "ReactNode",
+          "required": false,
+          "description": "The primary next step (a Button)."
+        },
+        {
+          "name": "secondaryAction",
+          "type": "ReactNode",
+          "required": false,
+          "description": "An optional second, quieter step (at most two actions)."
+        },
+        {
+          "name": "titleAs",
+          "type": "'h2' | 'h3' | 'h4' | 'p'",
+          "required": false,
+          "description": "Title element. Default 'h3'."
+        }
+      ],
+      "whenToUse": "The one empty-state pattern for a list, table or view with nothing to show: icon or mark, a 600-weight title, one help line, up to two actions. Static (no live region). Use instead of a grey one-liner; for 'all done' pass <CircleCheck /> with tone 'success'."
+    },
+    {
+      "name": "ErrorState",
+      "export": "ErrorState",
+      "importPath": "@miragon/mcp-toolkit-ui",
+      "kind": "component",
+      "group": "feedback",
+      "props": [
+        {
+          "name": "title",
+          "type": "ReactNode",
+          "required": true,
+          "description": "What happened, in plain words."
+        },
+        {
+          "name": "description",
+          "type": "ReactNode",
+          "required": false,
+          "description": "What you can do next (or the human reason)."
+        },
+        {
+          "name": "details",
+          "type": "ReactNode",
+          "required": false,
+          "description": "The raw technical reason, shown collapsed under a 'Details' disclosure."
+        },
+        {
+          "name": "onRetry",
+          "type": "() => void",
+          "required": false,
+          "description": "Renders a retry button (label from the locale) when set."
+        },
+        {
+          "name": "actions",
+          "type": "ReactNode",
+          "required": false,
+          "description": "Further actions after the retry button."
+        },
+        {
+          "name": "tone",
+          "type": "'danger' | 'warning' | 'info'",
+          "required": false,
+          "description": "Default 'danger'."
+        },
+        {
+          "name": "variant",
+          "type": "'block' | 'inline'",
+          "required": false,
+          "description": "'block' replaces a view or widget body; 'inline' is an alert above content that still renders. Default 'block'."
+        },
+        {
+          "name": "role",
+          "type": "'alert' | 'status' | 'none'",
+          "required": false,
+          "description": "Live-region role. Default 'alert'."
+        },
+        {
+          "name": "icon",
+          "type": "LucideIcon",
+          "required": false,
+          "description": "Replace the tone's default Lucide icon."
+        },
+        {
+          "name": "titleAs",
+          "type": "'h2' | 'h3' | 'h4' | 'p'",
+          "required": false,
+          "description": "Title element. Default 'h2' (block) / 'p' (inline)."
+        }
+      ],
+      "whenToUse": "The one error pattern: icon, a title that says what happened, a line that says what you can do, the raw error under 'Details', and a retry. Never print a raw exception as the only text, never leave a failed fetch on an endless skeleton."
     },
     {
       "name": "useDebouncedValue",
@@ -726,9 +1108,9 @@
       "props": [
         {
           "name": "queryKey",
-          "type": "unknown[]",
+          "type": "readonly unknown[]",
           "required": true,
-          "description": "Cache key. args is appended automatically so callers with different args get separate cache entries."
+          "description": "Cache key prefix. The effective key is [...queryKey, args] (toolQueryKey): different args get separate entries. Two tools must not share a key and args (the hook warns when they do), unless AppQueryProvider / McpAppView toolNameInQueryKey puts the tool name into the key ([...queryKey, toolName, args])."
         },
         {
           "name": "toolName",
@@ -744,12 +1126,12 @@
         },
         {
           "name": "opts",
-          "type": "{ enabled?: boolean; select?: (data) => selected }",
+          "type": "UseToolQueryOptions<TData, TSelected>",
           "required": false,
-          "description": "Gate the query / transform data on read."
+          "description": "TanStack query options (retry, retryDelay, staleTime, placeholderData / keepPreviousData, initialData + initialDataUpdatedAt, enabled, select, gcTime, …) — everything but queryKey/queryFn. retry defaults to the client's; retry: shouldRetryToolCall stops retrying a tool's own isError answer."
         }
       ],
-      "whenToUse": "Self-fetch arbitrary data from a tool inside a cockpit-embedded widget. Result is decoded with parseToolResult (structured-first). Returns a TanStack UseQueryResult."
+      "whenToUse": "Self-fetch arbitrary data from a tool inside a cockpit-embedded widget. Result is decoded with parseToolResult (structured-first). Returns a TanStack UseQueryResult (data, error, refetch, failureCount, failureReason, isFetching, isPlaceholderData, …). The tool goes through AppQueryProvider's callTool, else the nearest HostBridgeProvider; with neither the query fails with a 'no tool transport' error instead of idling, and fetches once a transport arrives. Keep a list on screen while a new search loads: { placeholderData: keepPreviousData }."
     },
     {
       "name": "useToolMutation",
@@ -766,12 +1148,105 @@
         },
         {
           "name": "opts",
-          "type": "{ invalidateKeys?: unknown[][] }",
+          "type": "UseToolMutationOptions<TData>",
+          "required": false,
+          "description": "TanStack mutation options (onSuccess, onError, onSettled, retry, meta, mutationKey, …) plus invalidateKeys: query-key prefixes to invalidate after each successful call (active queries refetch, inactive ones turn stale)."
+        }
+      ],
+      "whenToUse": "Run a write/action tool (e.g. retry-incident) and invalidate dependent queries. Returns a TanStack UseMutationResult; call .mutate(args, { onSuccess, onError, onSettled }). Unlike TanStack's own mutate, the per-call callbacks fire for EVERY call while the widget is mounted, so two quick calls each get their confirmation."
+    },
+    {
+      "name": "toolQueryKey",
+      "export": "toolQueryKey",
+      "importPath": "@miragon/mcp-toolkit-ui",
+      "kind": "function",
+      "group": "data-hooks",
+      "props": [
+        {
+          "name": "queryKey",
+          "type": "readonly unknown[]",
+          "required": true,
+          "description": "The caller's key prefix."
+        },
+        {
+          "name": "toolName",
+          "type": "string",
+          "required": true,
+          "description": "The tool the query calls."
+        },
+        {
+          "name": "args",
+          "type": "object",
+          "required": true,
+          "description": "The tool arguments."
+        },
+        {
+          "name": "toolNameInKey",
+          "type": "boolean",
           "required": false,
-          "description": "Query keys to refetch on success."
+          "description": "Put the tool name between the key and the args ([...queryKey, toolName, args]). Default false (the 2.x key); the default from the next major."
+        }
+      ],
+      "whenToUse": "Build the exact cache key useToolQuery / useViewToolQuery / useViewData use for getQueryData, setQueryData or cancelQueries with exact: true, never by hand. Pass toolNameInKey when the provider sets toolNameInQueryKey, or use useToolQueryKey, which reads it. Prefix invalidation needs only your queryKey."
+    },
+    {
+      "name": "useToolQueryKey",
+      "export": "useToolQueryKey",
+      "importPath": "@miragon/mcp-toolkit-ui",
+      "kind": "hook",
+      "group": "data-hooks",
+      "props": [
+        {
+          "name": "queryKey",
+          "type": "readonly unknown[]",
+          "required": true,
+          "description": "The caller's key prefix, as passed to useToolQuery."
+        },
+        {
+          "name": "toolName",
+          "type": "string",
+          "required": true,
+          "description": "The tool the query calls."
+        },
+        {
+          "name": "args",
+          "type": "object",
+          "required": true,
+          "description": "The tool arguments."
         }
       ],
-      "whenToUse": "Run a write/action tool (e.g. retry-incident) and refetch dependent queries. Returns a TanStack UseMutationResult; call .mutate(args)."
+      "whenToUse": "The exact cache key the data hooks use for this tool and args under the nearest AppQueryProvider (toolQueryKey with its toolNameInQueryKey setting), for getQueryData, setQueryData or cancelQueries with exact: true, e.g. for an optimistic update in a mutation's onMutate. Stays right when the next major puts the tool name into every key."
+    },
+    {
+      "name": "shouldRetryToolCall",
+      "export": "shouldRetryToolCall",
+      "importPath": "@miragon/mcp-toolkit-ui",
+      "kind": "function",
+      "group": "data-hooks",
+      "props": [
+        {
+          "name": "failureCount",
+          "type": "number",
+          "required": true,
+          "description": "Failed attempts so far."
+        },
+        {
+          "name": "error",
+          "type": "unknown",
+          "required": true,
+          "description": "The last failure."
+        }
+      ],
+      "whenToUse": "An opt-in retry policy for tool queries: no retry for a tool's own isError answer (isToolError) or a missing transport, up to 3 retries for a failed transport, so a deterministic tool error shows at once instead of after ~7 s. Pass retry: shouldRetryToolCall to a hook, or set it as the client's default. The hooks keep the client's retry by default."
+    },
+    {
+      "name": "keepPreviousData",
+      "export": "keepPreviousData",
+      "importPath": "@miragon/mcp-toolkit-ui",
+      "kind": "function",
+      "group": "data-hooks",
+      "props": [],
+      "whenToUse": "TanStack's placeholder helper, re-exported so no direct @tanstack/react-query import is needed: { placeholderData: keepPreviousData } keeps the previous args' answer on screen (isPlaceholderData: true) while a changed search or filter loads — a list never unmounts mid-typing."
     },
     {
       "name": "useViewToolQuery",
@@ -784,7 +1259,7 @@
           "name": "queryKey",
           "type": "unknown[]",
           "required": true,
-          "description": "Cache key; args appended automatically (sibling widgets dedupe)."
+          "description": "Cache key prefix; the effective key is [...queryKey, args] (sibling widgets with equal args dedupe)."
         },
         {
           "name": "toolName",
@@ -800,9 +1275,9 @@
         },
         {
           "name": "opts",
-          "type": "{ enabled?: boolean }",
+          "type": "UseViewToolQueryOptions<T>",
           "required": false,
-          "description": "Gate the query."
+          "description": "TanStack query options (retry, retryDelay, staleTime, placeholderData / keepPreviousData, initialData + initialDataUpdatedAt, enabled, select, gcTime, …) — everything but queryKey/queryFn, as useToolQuery."
         }
       ],
       "whenToUse": "Self-fetch from a *_show_* widget tool. Unwraps the McpAppView view envelope via parseViewToolResult (single-step → flat data, multi-step → keyed by step id) — the envelope-aware sibling of useToolQuery."
@@ -818,7 +1293,7 @@
           "name": "initialData",
           "type": "T | null | undefined",
           "required": true,
-          "description": "Host-pushed data (e.g. from adaptDataWidget). Returned verbatim when present."
+          "description": "Host-pushed data (e.g. from adaptDataWidget). Returned verbatim by default; with initialDataMode 'seed' it becomes the feed query's cached answer."
         },
         {
           "name": "key",
@@ -842,10 +1317,16 @@
           "name": "ready",
           "type": "boolean",
           "required": true,
-          "description": "Whether the required id/key is present; fetch is disabled until ready and only when no initialData."
+          "description": "Whether the required id/key is present; the feed stays off until ready (and, by default, while initialData is present)."
+        },
+        {
+          "name": "options",
+          "type": "UseViewDataOptions<T>",
+          "required": false,
+          "description": "TanStack query options (retry, retryDelay, staleTime, placeholderData / keepPreviousData, initialDataUpdatedAt, enabled, gcTime, …) — everything but queryKey/queryFn; enabled (a boolean or a function of the query) is an extra gate next to ready, and a closed gate is not loading. initialDataMode: 'static' (default) or 'seed' — seed keeps the feed live over host data, so a write's invalidation, a refetch or a retry re-reads it."
         }
       ],
-      "whenToUse": "The dual-mode seam: write ONE widget that renders host-pushed data when handed it (standalone *_show_* widget) AND self-fetches when embedded in a cockpit. Returns { data, loading, error }."
+      "whenToUse": "The dual-mode seam: write ONE widget that renders host-pushed data when handed it (standalone *_show_* widget) AND self-fetches when embedded in a cockpit. Returns { data, loading, error, refetch, failureCount, failureReason, isFetching, isPlaceholderData }; pass refetch as the error state's retry (<ErrorState onRetry={refetch} />). Pass { initialDataMode: 'seed' } when a standalone view must stay live after writes, { placeholderData: keepPreviousData } to keep rows on screen while new args load."
     },
     {
       "name": "useIsMobile",
@@ -1010,12 +1491,28 @@
         {
           "name": "children",
           "type": "ReactNode",
-          "required": true,
-          "description": "The widget subtree the description belongs to."
+          "required": false,
+          "description": "The widget subtree the description belongs to (nested below it). Omit it to report one line where it renders."
         }
       ],
       "whenToUse": "Report model context from a widget that self-fetches (cockpit views) — the host-portable replacement for mcp-use/react's ModelContext. Inside an mcp-use view it renders the native aggregating ModelContext; in every other mount (widget playground, ChatGPT, standalone) it routes through the HostBridge's setModelContext. NEVER import ModelContext from mcp-use/react in a widget: it throws outside a bootstrapView mount."
     },
+    {
+      "name": "useHostModelContext",
+      "export": "useHostModelContext",
+      "importPath": "@miragon/mcp-toolkit-ui/app",
+      "kind": "hook",
+      "group": "widget-authoring",
+      "props": [
+        {
+          "name": "content",
+          "type": "string | null | undefined",
+          "required": true,
+          "description": "One line for the model; blank or null reports nothing."
+        }
+      ],
+      "whenToUse": "Report one line of model context from a component with nothing to wrap (a selection, a filter, an error the user sees) for as long as it is mounted. Inside an mcp-use view the line joins the view's one model-context tree with every HostModelContext and leaves it on unmount; elsewhere it goes through the HostBridge's setModelContext."
+    },
     {
       "name": "DescribeForModel",
       "export": "DescribeForModel",
@@ -1054,6 +1551,44 @@
       ],
       "whenToUse": "Decode a raw callTool result to its data payload. Structured-first: isError → throw, then structuredContent, then JSON-decoded text, then raw. useToolQuery decodes through this for you."
     },
+    {
+      "name": "ToolResultError",
+      "export": "ToolResultError",
+      "importPath": "@miragon/mcp-toolkit-ui",
+      "kind": "function",
+      "group": "widget-authoring",
+      "props": [
+        {
+          "name": "message",
+          "type": "string",
+          "required": true,
+          "description": "The tool's first text block."
+        },
+        {
+          "name": "result",
+          "type": "unknown",
+          "required": true,
+          "description": "The isError result as the tool returned it."
+        }
+      ],
+      "whenToUse": "The Error class parseToolResult throws for an isError result — a deterministic answer of the tool (validation error, engine 404), not a transport failure. The query hooks retry it like any failure by default (the client's retry); pass retry: shouldRetryToolCall to stop that. Check with isToolError (also matches mcp-use's ToolError)."
+    },
+    {
+      "name": "isToolError",
+      "export": "isToolError",
+      "importPath": "@miragon/mcp-toolkit-ui",
+      "kind": "function",
+      "group": "widget-authoring",
+      "props": [
+        {
+          "name": "error",
+          "type": "unknown",
+          "required": true,
+          "description": "Anything a tool call rejected with."
+        }
+      ],
+      "whenToUse": "Tell a tool's own isError answer (ToolResultError, or mcp-use's ToolError inside a view) from a transport failure — e.g. in a custom retry policy or to word an error state."
+    },
     {
       "name": "parseViewToolResult",
       "export": "parseViewToolResult",
@@ -1097,16 +1632,16 @@
           "name": "tokens",
           "type": "ThemeTokens",
           "required": true,
-          "description": "Curated brand tokens (all optional): primary, primaryForeground, accent, accentForeground, background, foreground, card, cardForeground, border, ring, radius, fontSans, fontHeading. Colors are any CSS color string (oklch/hex/hsl)."
+          "description": "Brand tokens (all optional), one field per role of the role-token contract (ROLE_TOKENS): primary, primaryForeground, primaryHover, link, focus, ring, background, foreground, card, popover, muted, mutedForeground, secondary, accent, border, input, destructive, success/warning/danger/info with *Soft and *Ink, radiusSm/Md/Lg/Pill, shadow1-3, scrim, motionFast/Base/Slow, ease, fontSans, fontMono, plus the legacy accentForeground, cardForeground, radius, fontHeading. Colors are any CSS color string."
         },
         {
           "name": "opts",
           "type": "{ dark?: ThemeTokens }",
           "required": false,
-          "description": "Dark-mode token overrides, applied on top of the .dark defaults when the active mode is dark."
+          "description": "Dark-mode token overrides. In dark mode a theme scope gets the toolkit's dark defaults, the theme's mode-invariant light tokens (brand button colour, radii, fonts) and these — never the other light values."
         }
       ],
-      "whenToUse": "Define a white-label theme from a single set of brand tokens. Maps the curated fields onto the real CSS variables (--primary, --radius, ...) and returns a serializable ThemeDefinition { vars, darkVars?, toStyle() }. Apply it with ThemeProvider so every primitive re-skins to the client's brand."
+      "whenToUse": "Define a white-label theme for a customer brand. The toolkit's default IS the Miragon theme (no theme needed for it). Maps the fields onto the role CSS variables (--primary, --link, --focus, ...) and returns a serializable ThemeDefinition { vars, darkVars?, toStyle() }. Apply it with ThemeProvider so every primitive re-skins; override roles only, never --cd-* tokens or component classes."
     },
     {
       "name": "ThemeProvider",
@@ -1119,7 +1654,7 @@
           "name": "theme",
           "type": "ThemeDefinition",
           "required": false,
-          "description": "The theme from createTheme/themePresets to apply. Omit to manage only the light/dark mode against the toolkit defaults."
+          "description": "The theme from createTheme to apply. Omit to manage only the light/dark mode against the toolkit defaults (the Miragon theme)."
         },
         {
           "name": "mode",
@@ -1146,7 +1681,7 @@
           "description": "Subtree that inherits the theme's CSS variables and dark class."
         }
       ],
-      "whenToUse": "Wrap a widget (or a whole app) to apply a ThemeDefinition. Renders a wrapper carrying the theme's CSS variables inline (overriding :root) and toggles the .dark class on the scope per mode. React + DOM only — no host required."
+      "whenToUse": "Wrap a widget (or a whole app) to apply a ThemeDefinition and/or a light/dark mode to a scope. Light mode applies the theme's vars, dark mode the toolkit's dark roles plus the theme's dark and mode-invariant tokens (resolveThemeVars). A light scope stays light inside a dark document. Dialogs, Sheets and Select menus opened inside portal into the scope, so they keep its theme and mode. React + DOM only — no host required."
     },
     {
       "name": "useTheme",
@@ -1164,7 +1699,129 @@
       "kind": "object",
       "group": "theming",
       "props": [],
-      "whenToUse": "Ready-made white-label themes (themePresets.miragon, .violet, .emerald) — a demonstration of createTheme and a fork-able starting point. Pass one to ThemeProvider's theme prop."
+      "whenToUse": "Ready-made white-label themes — a demonstration of createTheme and a fork-able starting point (themePresets.emerald). themePresets.miragon and .violet are deprecated: the Miragon theme is the toolkit's default, use no theme for it. Pass a preset to ThemeProvider's theme prop."
+    },
+    {
+      "name": "resolveThemeVars",
+      "export": "resolveThemeVars",
+      "importPath": "@miragon/mcp-toolkit-ui",
+      "kind": "function",
+      "group": "theming",
+      "props": [
+        {
+          "name": "theme",
+          "type": "ThemeDefinition | null | undefined",
+          "required": true,
+          "description": "The theme; null/undefined yields {}."
+        },
+        {
+          "name": "mode",
+          "type": "\"light\" | \"dark\"",
+          "required": true,
+          "description": "The resolved mode of the scope."
+        }
+      ],
+      "whenToUse": "The CSS variables a ThemeDefinition applies at its scope in a mode — what ThemeProvider puts on its wrapper. Use it to theme an element without ThemeProvider (spread it into style), e.g. resolveThemeVars(theme, host.theme ?? 'light'). A legacy base radius also derives the sm/md/lg steps."
+    },
+    {
+      "name": "ROLE_TOKENS",
+      "export": "ROLE_TOKENS",
+      "importPath": "@miragon/mcp-toolkit-ui",
+      "kind": "object",
+      "group": "theming",
+      "props": [],
+      "whenToUse": "The role-token contract as a readonly list of CSS variable names (--background … --font-mono). Components style through these roles only; a brand overrides only these. Use it to check a brand stylesheet or a host token map covers / stays within the contract."
+    },
+    {
+      "name": "usePortalContainer",
+      "export": "usePortalContainer",
+      "importPath": "@miragon/mcp-toolkit-ui",
+      "kind": "hook",
+      "group": "theming",
+      "props": [],
+      "whenToUse": "The portal node of the nearest ThemeProvider (or null). Pass it as `container` to a portal of your own so overlays keep the scope's theme and light/dark mode; the toolkit's Dialog, Sheet and Select already do."
+    },
+    {
+      "name": "CD_TOKENS",
+      "export": "CD_TOKENS",
+      "importPath": "@miragon/mcp-toolkit-ui",
+      "kind": "object",
+      "group": "theming",
+      "parts": ["CD_TOKENS", "CD_TOKENS_VERSION"],
+      "props": [],
+      "whenToUse": "The Miragon corporate-design tokens (--cd-*) as plain TypeScript, keys without the prefix (CD_TOKENS.blau, CD_TOKENS['danger-soft']). For code that cannot read CSS variables — SVG/canvas renderers, chart marks, server-side images. Drift-tested against the vendored CSS. UI components style through the role tokens, never through these constants."
+    },
+    {
+      "name": "fontFaces",
+      "export": "fontFaces",
+      "importPath": "@miragon/mcp-toolkit-ui",
+      "kind": "function",
+      "group": "theming",
+      "parts": ["fontFaces", "GEIST_FONT_FILES"],
+      "props": [
+        {
+          "name": "baseUrl",
+          "type": "string",
+          "required": true,
+          "description": "Where the woff2 files (GEIST_FONT_FILES) are served from."
+        },
+        {
+          "name": "files",
+          "type": "{ sans?: string; mono?: string }",
+          "required": false,
+          "description": "File-name overrides."
+        },
+        {
+          "name": "display",
+          "type": "\"auto\" | \"block\" | \"swap\" | \"fallback\" | \"optional\"",
+          "required": false,
+          "description": "Default 'swap'."
+        }
+      ],
+      "whenToUse": "Opt-in Geist delivery by URL: returns the @font-face rules for Geist and Geist Mono (latin, variable weight) served from baseUrl. Inject into the view document, e.g. <style>{fontFaces({ baseUrl })}</style>, and allow that origin in the view CSP. Alternative: import @miragon/mcp-toolkit-ui/fonts.css (bundled). The font tokens name Geist first, so either path works; without either the host's font (see adoptHostFontVariables) or the system stack renders."
+    },
+    {
+      "name": "adoptHostFontVariables",
+      "export": "adoptHostFontVariables",
+      "importPath": "@miragon/mcp-toolkit-ui",
+      "kind": "function",
+      "group": "theming",
+      "parts": ["adoptHostFontVariables", "HOST_FONT_VARIABLES"],
+      "props": [
+        {
+          "name": "style",
+          "type": "InlineStyleTarget",
+          "required": true,
+          "description": "The inline style the host variables were applied to, normally document.documentElement.style."
+        },
+        {
+          "name": "hostVariables",
+          "type": "Record<string, string | undefined> | null | undefined",
+          "required": true,
+          "description": "The host's SEP-1865 style variables (hostContext.styles.variables)."
+        }
+      ],
+      "whenToUse": "Keeps Geist first when a host sends its font. SEP-1865 hosts send --font-sans/--font-mono, the same names as the toolkit's font roles, and would replace the Geist-first stacks whole; this moves them to --host-font-sans/--host-font-mono, the fallback slot right after Geist. McpToolkitApp already calls it; call it yourself only in an app with its own host-document layer, right after applying the host's style variables."
+    },
+    {
+      "name": "FOCUS_RING",
+      "export": "FOCUS_RING",
+      "importPath": "@miragon/mcp-toolkit-ui",
+      "kind": "object",
+      "group": "widget-authoring",
+      "parts": ["FOCUS_RING", "FOCUS_RING_INSET"],
+      "props": [],
+      "whenToUse": "The kit's opaque focus ring as a class string (2px ring in --focus with an offset; FOCUS_RING_INSET draws it inside, for cells flush with a container edge). Spread it into a custom control's className so keyboard focus reads the same everywhere (3:1 or more in both modes)."
+    },
+    {
+      "name": "Type scale",
+      "export": "TYPE_SCALE",
+      "importPath": "@miragon/mcp-toolkit-ui",
+      "kind": "object",
+      "group": "widget-authoring",
+      "parts": ["TYPE_SCALE", "TYPE_STEPS", "TYPE_FLOOR_PX", "MICRO_LABEL"],
+      "props": [],
+      "whenToUse": "The CI type scale as role tokens and utilities: text-title (28/700, page title), text-section (21/600), text-body (16/400/1.6, running text incl. state and toast descriptions), text-dense (14, dense tables and controls such as inputs, chips, count pills and the inline alert box; never running text), text-small (13, the floor: captions, hints, meta rows). Nothing renders below 13 px: no text-xs, no text-[10px]; a former 10–11 px uppercase caption is MICRO_LABEL (13 px semibold, normal case). Combine with the kit's cn (plain tailwind-merge drops text-small next to a text colour). Brands resize via --text-* (ThemeTokens textTitle … textSmall)."
     },
     {
       "name": "LocaleProvider",
@@ -1185,6 +1842,12 @@
           "required": false,
           "description": "A translator from createTranslator(catalogs) (@miragon/mcp-toolkit-core). Omit to provide the locale only (useTranslate echoes keys)."
         },
+        {
+          "name": "toolkitMessages",
+          "type": "ToolkitMessagesOverride",
+          "required": false,
+          "description": "Override individual toolkit strings per catalog section (e.g. { listFooter: { loadMore: 'Show more' } }). Omitted entries keep the shipped en/de catalog of locale."
+        },
         {
           "name": "children",
           "type": "ReactNode",
@@ -1192,7 +1855,7 @@
           "description": "Subtree whose widgets read the locale via useLocale/useTranslate."
         }
       ],
-      "whenToUse": "Wrap a widget (or a whole app) to provide the active locale + an optional translator. Widgets read it with useLocale/useTranslate. Pure React (no host required), mirroring ThemeProvider — pairs with createTranslator from @miragon/mcp-toolkit-core."
+      "whenToUse": "Wrap a widget (or a whole app) to provide the active locale + an optional translator. Widgets read it with useLocale/useTranslate. Pure React (no host required), mirroring ThemeProvider — pairs with createTranslator from @miragon/mcp-toolkit-core. The toolkit's own components read their strings from it too (en/de, English otherwise), so passing the locale localizes the whole toolkit chrome."
     },
     {
       "name": "useLocale",
@@ -1212,6 +1875,68 @@
       "props": [],
       "whenToUse": "Get a locale-bound translate (key, params?) => string from the nearest LocaleProvider. Outside a provider it echoes the key, so a missing wrapper degrades gracefully instead of crashing."
     },
+    {
+      "name": "useToolkitMessages",
+      "export": "useToolkitMessages",
+      "importPath": "@miragon/mcp-toolkit-ui",
+      "kind": "hook",
+      "group": "i18n",
+      "props": [],
+      "whenToUse": "Read the toolkit's own UI strings (common, view, listFooter, filterBar, pills, renderer, builder, propsSheet) for the nearest LocaleProvider's locale: the shipped en/de catalog, English for any other locale, with the provider's toolkitMessages override applied. Reuse them in a widget for consistent chrome copy (e.g. common.retry)."
+    },
+    {
+      "name": "TOOLKIT_MESSAGES",
+      "export": "TOOLKIT_MESSAGES",
+      "importPath": "@miragon/mcp-toolkit-ui",
+      "kind": "object",
+      "group": "i18n",
+      "props": [],
+      "whenToUse": "The shipped toolkit catalogs keyed by locale ({ en, de }), typed as ToolkitMessages. Use it to build a LocaleProvider toolkitMessages override or to assert in a consumer test that no toolkit default leaks into a localized bundle."
+    },
+    {
+      "name": "resolveToolkitMessages",
+      "export": "resolveToolkitMessages",
+      "importPath": "@miragon/mcp-toolkit-ui",
+      "kind": "function",
+      "group": "i18n",
+      "props": [
+        {
+          "name": "locale",
+          "type": "string | undefined",
+          "required": true,
+          "description": "Any BCP 47 tag; its primary language picks the catalog (en fallback)."
+        },
+        {
+          "name": "override",
+          "type": "ToolkitMessagesOverride",
+          "required": false,
+          "description": "Per-section partial override merged over the catalog."
+        }
+      ],
+      "whenToUse": "Resolve the toolkit catalog outside React (the pure function behind LocaleProvider/useToolkitMessages)."
+    },
+    {
+      "name": "formatCount",
+      "export": "formatCount",
+      "importPath": "@miragon/mcp-toolkit-ui",
+      "kind": "function",
+      "group": "i18n",
+      "props": [
+        {
+          "name": "value",
+          "type": "number",
+          "required": true,
+          "description": "The count."
+        },
+        {
+          "name": "locale",
+          "type": "string | undefined",
+          "required": true,
+          "description": "The app locale (from useLocale), not the browser's."
+        }
+      ],
+      "whenToUse": "Format a count with the app locale's grouping (1,234 / 1.234); an invalid tag falls back to English instead of throwing in render."
+    },
     {
       "name": "McpToolkitApp",
       "export": "McpToolkitApp",
@@ -1256,6 +1981,15 @@
       ],
       "whenToUse": "The bundle entry point since mcp-use 2.x: mounts McpToolkitApp via bootstrapView (ext-apps handshake, error boundary, auto-resize). Call it once in main.tsx instead of createRoot().render()."
     },
+    {
+      "name": "installToolResultObserver",
+      "export": "installToolResultObserver",
+      "importPath": "@miragon/mcp-toolkit-ui/app",
+      "kind": "function",
+      "group": "app-shell",
+      "props": [],
+      "whenToUse": "Only for a custom shell under its own bootstrapView: call it before bootstrapView so McpAppView can tell a stripped tool result (claude.ai) from a slow tool and never re-runs a call the host is still answering. mountMcpToolkitApp and the bundle's first evaluation install it already; idempotent, null outside a framed browser document."
+    },
     {
       "name": "WidgetFixtureHost",
       "export": "WidgetFixtureHost",
@@ -1291,7 +2025,7 @@
           "name": "globals",
           "type": "Record<string, unknown>",
           "required": false,
-          "description": "Host-context overrides (theme, displayMode, locale...)."
+          "description": "Host context: theme (reported on the HostBridge) and locale (the toolkit's own strings and number format, as under McpAppView). Other keys are accepted for compatibility."
         },
         {
           "name": "onModelContext",