@miragon/mcp-toolkit-ui 2.7.0 → 2.8.0

package/dist/hooks/use-view-tool-query.d.ts

@@ -1,7 +1,11 @@
 import { type UseQueryResult } from "@tanstack/react-query";
-export interface UseViewToolQueryOptions {
-    enabled?: boolean;
-}
+import { type UseToolQueryOptions } from "../lib/tool-query.js";
+/**
+ * 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
  * of {@link useToolQuery}. A widget tool's text channel carries only a model
@@ -10,9 +14,10 @@ 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 declare function useViewToolQuery<T = unknown>(queryKey: unknown[], toolName: string, args: object, opts?: UseViewToolQueryOptions): UseQueryResult<T, Error>;
+export declare function useViewToolQuery<T = unknown>(queryKey: readonly unknown[], toolName: string, args: object, opts?: UseViewToolQueryOptions<T>): UseQueryResult<T, Error>;
 //# sourceMappingURL=use-view-tool-query.d.ts.map

package/dist/hooks/use-view-tool-query.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"use-view-tool-query.d.ts","sourceRoot":"","sources":["../../src/hooks/use-view-tool-query.ts"],"names":[],"mappings":"AAAA,OAAO,EAAY,KAAK,cAAc,EAAE,MAAM,uBAAuB,CAAA;AAIrE,MAAM,WAAW,uBAAuB;IACtC,OAAO,CAAC,EAAE,OAAO,CAAA;CAClB;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,gBAAgB,CAAC,CAAC,GAAG,OAAO,EAC1C,QAAQ,EAAE,OAAO,EAAE,EACnB,QAAQ,EAAE,MAAM,EAChB,IAAI,EAAE,MAAM,EACZ,IAAI,CAAC,EAAE,uBAAuB,GAC7B,cAAc,CAAC,CAAC,EAAE,KAAK,CAAC,CAY1B"}
+{"version":3,"file":"use-view-tool-query.d.ts","sourceRoot":"","sources":["../../src/hooks/use-view-tool-query.ts"],"names":[],"mappings":"AAAA,OAAO,EAAY,KAAK,cAAc,EAAE,MAAM,uBAAuB,CAAA;AAGrE,OAAO,EAAoB,KAAK,mBAAmB,EAAE,MAAM,sBAAsB,CAAA;AAGjF;;;;GAIG;AACH,MAAM,MAAM,uBAAuB,CAAC,CAAC,GAAG,OAAO,IAAI,mBAAmB,CAAC,CAAC,CAAC,CAAA;AAEzE;;;;;;;;;;;;GAYG;AACH,wBAAgB,gBAAgB,CAAC,CAAC,GAAG,OAAO,EAC1C,QAAQ,EAAE,SAAS,OAAO,EAAE,EAC5B,QAAQ,EAAE,MAAM,EAChB,IAAI,EAAE,MAAM,EACZ,IAAI,CAAC,EAAE,uBAAuB,CAAC,CAAC,CAAC,GAChC,cAAc,CAAC,CAAC,EAAE,KAAK,CAAC,CAY1B"}

package/dist/hooks/use-view-tool-query.js

@@ -1,6 +1,8 @@
 import { useQuery } 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 } from "../lib/tool-query.js";
+import { useRefetchOnTransport, useToolKeyGuard } from "./use-tool-query.js";
 /**
  * Self-fetch hook for `*_show_*` widget tools — the envelope-unwrapping sibling
  * of {@link useToolQuery}. A widget tool's text channel carries only a model
@@ -9,21 +11,20 @@ import { parseViewToolResult } from "../lib/parse-tool-result.js";
  * 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(queryKey, toolName, args, opts) {
     const callTool = useCallTool();
-    return useQuery({
-        queryKey: [...queryKey, args],
-        queryFn: async () => {
-            if (!callTool)
-                throw new Error("callTool not available");
-            const result = await callTool(toolName, args);
-            return parseViewToolResult(result);
-        },
-        enabled: !!callTool && (opts?.enabled ?? true),
-    });
+    const toolNameInKey = useToolNameInQueryKey();
+    useToolKeyGuard(queryKey, toolName, args);
+    const query = useQuery(toolQueryOptions(queryKey, toolName, args, callTool, opts, {
+        decode: parseViewToolResult,
+        toolNameInKey,
+    }));
+    useRefetchOnTransport(callTool, query);
+    return query;
 }
 //# sourceMappingURL=use-view-tool-query.js.map

package/dist/hooks/use-view-tool-query.js.map

@@ -1 +1 @@
-{"version":3,"file":"use-view-tool-query.js","sourceRoot":"","sources":["../../src/hooks/use-view-tool-query.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAuB,MAAM,uBAAuB,CAAA;AACrE,OAAO,EAAE,WAAW,EAAE,MAAM,gCAAgC,CAAA;AAC5D,OAAO,EAAE,mBAAmB,EAAE,MAAM,6BAA6B,CAAA;AAMjE;;;;;;;;;;;GAWG;AACH,MAAM,UAAU,gBAAgB,CAC9B,QAAmB,EACnB,QAAgB,EAChB,IAAY,EACZ,IAA8B;IAE9B,MAAM,QAAQ,GAAG,WAAW,EAAE,CAAA;IAE9B,OAAO,QAAQ,CAAW;QACxB,QAAQ,EAAE,CAAC,GAAG,QAAQ,EAAE,IAAI,CAAC;QAC7B,OAAO,EAAE,KAAK,IAAI,EAAE;YAClB,IAAI,CAAC,QAAQ;gBAAE,MAAM,IAAI,KAAK,CAAC,wBAAwB,CAAC,CAAA;YACxD,MAAM,MAAM,GAAG,MAAM,QAAQ,CAAC,QAAQ,EAAE,IAAI,CAAC,CAAA;YAC7C,OAAO,mBAAmB,CAAI,MAAM,CAAC,CAAA;QACvC,CAAC;QACD,OAAO,EAAE,CAAC,CAAC,QAAQ,IAAI,CAAC,IAAI,EAAE,OAAO,IAAI,IAAI,CAAC;KAC/C,CAAC,CAAA;AACJ,CAAC"}
+{"version":3,"file":"use-view-tool-query.js","sourceRoot":"","sources":["../../src/hooks/use-view-tool-query.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAuB,MAAM,uBAAuB,CAAA;AACrE,OAAO,EAAE,WAAW,EAAE,qBAAqB,EAAE,MAAM,gCAAgC,CAAA;AACnF,OAAO,EAAE,mBAAmB,EAAE,MAAM,6BAA6B,CAAA;AACjE,OAAO,EAAE,gBAAgB,EAA4B,MAAM,sBAAsB,CAAA;AACjF,OAAO,EAAE,qBAAqB,EAAE,eAAe,EAAE,MAAM,qBAAqB,CAAA;AAS5E;;;;;;;;;;;;GAYG;AACH,MAAM,UAAU,gBAAgB,CAC9B,QAA4B,EAC5B,QAAgB,EAChB,IAAY,EACZ,IAAiC;IAEjC,MAAM,QAAQ,GAAG,WAAW,EAAE,CAAA;IAC9B,MAAM,aAAa,GAAG,qBAAqB,EAAE,CAAA;IAC7C,eAAe,CAAC,QAAQ,EAAE,QAAQ,EAAE,IAAI,CAAC,CAAA;IACzC,MAAM,KAAK,GAAG,QAAQ,CACpB,gBAAgB,CAAI,QAAQ,EAAE,QAAQ,EAAE,IAAI,EAAE,QAAQ,EAAE,IAAI,EAAE;QAC5D,MAAM,EAAE,mBAAmB;QAC3B,aAAa;KACd,CAAC,CACH,CAAA;IACD,qBAAqB,CAAC,QAAQ,EAAE,KAAK,CAAC,CAAA;IACtC,OAAO,KAAK,CAAA;AACd,CAAC"}

package/dist/index.d.ts

@@ -13,22 +13,27 @@ export { Switch } from "./primitives/switch.js";
 export { ScrollArea, ScrollBar } from "./primitives/scroll-area.js";
 export { Sheet, SheetClose, SheetContent, SheetDescription, SheetFooter, SheetHeader, SheetTitle, SheetTrigger, } from "./primitives/sheet.js";
 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";
+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";
-export { TONE_SOFT, TONE_DOT, TONE_TEXT, TONE_BORDER, TONE_ICON } from "./lib/tone-utils.js";
-export type { ToneVariant } from "./lib/tone-utils.js";
+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";
+export { TYPE_SCALE, TYPE_STEPS, TYPE_FLOOR_PX, MICRO_LABEL } from "./lib/typography.js";
+export type { TypeStep } from "./lib/typography.js";
 export { FOCUS_RING, FOCUS_RING_INSET } from "./lib/focus-ring.js";
 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";
@@ -37,6 +42,8 @@ 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";
 export { ToastProvider, useToast } from "./components/Toast.js";
 export type { ToastApi, ToastOptions, ToastTone } from "./components/Toast.js";
 export { EmptyState } from "./components/EmptyState.js";
@@ -47,7 +54,7 @@ export { AppQueryProvider, useCallTool, queryClient } from "./providers/query-pr
 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, ThemeVars, CreateThemeOptions, ThemeMode, ThemeContextValue, ThemeProviderProps, ThemePresetId, CdTokenName, FontFacesOptions, InlineStyleTarget, } from "./theme/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";
+export type { LocaleContextValue, LocaleProviderProps, BoundTranslate, BuilderMessages, CommonMessages, FilterBarMessages, ListFooterMessages, PropsSheetMessages, RendererMessages, ToolkitLocale, ToolkitMessages, ToolkitMessagesOverride, ViewMessages, } from "./locale/index.js";
 export { cn } from "./lib/utils.js";
 export { parseToolResult, parseViewToolResult } from "./lib/parse-tool-result.js";
 export type { ParseToolResultOptions } from "./lib/parse-tool-result.js";

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}

package/dist/index.js

@@ -17,26 +17,38 @@ export { Sheet, SheetClose, SheetContent, SheetDescription, SheetFooter, SheetHe
 // 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 { useToolQuery, useToolQueryKey, useToolMutation } 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. Three
+// 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), 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";
+// 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";
+// 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";
 // 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 { KpiGrid } from "./components/KpiGrid.js";
-export { LivePill, CountPill } from "./components/Pills.js";
+export { KpiGrid, KpiGridSkeleton } from "./components/KpiGrid.js";
+export { LivePill, CountPill, StatusBadge } from "./components/Pills.js";
 export { SectionHeading } from "./components/SectionHeading.js";
 export { WidgetHeader } from "./components/WidgetHeader.js";
 export { GroupCard } from "./components/GroupCard.js";
 export { FilterBar } from "./components/FilterBar.js";
 export { DrillButton } from "./components/DrillButton.js";
 export { ListFooter } from "./components/ListFooter.js";
+export { PagedListFooter } from "./components/PagedListFooter.js";
 // Feedback and states — one pattern each for toasts, empty and error states.
 export { ToastProvider, useToast } from "./components/Toast.js";
 export { EmptyState } from "./components/EmptyState.js";

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,yBAAyB;AACzB,OAAO,EACL,IAAI,EACJ,UAAU,EACV,UAAU,EACV,SAAS,EACT,UAAU,EACV,eAAe,EACf,WAAW,GACZ,MAAM,sBAAsB,CAAA;AAC7B,OAAO,EAAE,KAAK,EAAE,aAAa,EAAE,MAAM,uBAAuB,CAAA;AAC5D,OAAO,EACL,KAAK,EACL,WAAW,EACX,SAAS,EACT,WAAW,EACX,QAAQ,EACR,SAAS,EACT,SAAS,EACT,YAAY,GACb,MAAM,uBAAuB,CAAA;AAC9B,OAAO,EAAE,SAAS,EAAE,MAAM,2BAA2B,CAAA;AACrD,OAAO,EAAE,QAAQ,EAAE,MAAM,0BAA0B,CAAA;AACnD,OAAO,EAAE,IAAI,EAAE,QAAQ,EAAE,WAAW,EAAE,WAAW,EAAE,MAAM,sBAAsB,CAAA;AAC/E,OAAO,EAAE,MAAM,EAAE,cAAc,EAAE,MAAM,wBAAwB,CAAA;AAC/D,OAAO,EAAE,KAAK,EAAE,MAAM,uBAAuB,CAAA;AAC7C,OAAO,EACL,MAAM,EACN,aAAa,EACb,WAAW,EACX,UAAU,EACV,WAAW,EACX,sBAAsB,EACtB,oBAAoB,EACpB,eAAe,EACf,aAAa,EACb,WAAW,GACZ,MAAM,wBAAwB,CAAA;AAC/B,OAAO,EACL,MAAM,EACN,WAAW,EACX,aAAa,EACb,iBAAiB,EACjB,YAAY,EACZ,YAAY,EACZ,aAAa,EACb,YAAY,EACZ,WAAW,EACX,aAAa,GACd,MAAM,wBAAwB,CAAA;AAC/B,OAAO,EAAE,KAAK,EAAE,gBAAgB,EAAE,UAAU,EAAE,MAAM,uBAAuB,CAAA;AAC3E,OAAO,EAAE,MAAM,EAAE,MAAM,wBAAwB,CAAA;AAC/C,OAAO,EAAE,UAAU,EAAE,SAAS,EAAE,MAAM,6BAA6B,CAAA;AACnE,OAAO,EACL,KAAK,EACL,UAAU,EACV,YAAY,EACZ,gBAAgB,EAChB,WAAW,EACX,WAAW,EACX,UAAU,EACV,YAAY,GACb,MAAM,uBAAuB,CAAA;AAE9B,QAAQ;AACR,6EAA6E;AAC7E,0EAA0E;AAC1E,OAAO,EAAE,WAAW,EAAE,MAAM,uBAAuB,CAAA;AACnD,OAAO,EAAE,YAAY,EAAE,eAAe,EAAE,eAAe,EAAE,MAAM,2BAA2B,CAAA;AAE1F,wEAAwE;AACxE,mEAAmE;AACnE,wEAAwE;AACxE,uDAAuD;AACvD,OAAO,EAAE,YAAY,EAAE,mBAAmB,EAAE,MAAM,qBAAqB,CAAA;AACvE,OAAO,EAAE,eAAe,EAAE,WAAW,EAAE,MAAM,4BAA4B,CAAA;AACzE,OAAO,EAAE,gBAAgB,EAAE,MAAM,uBAAuB,CAAA;AACxD,OAAO,EAAE,iBAAiB,EAAE,MAAM,gCAAgC,CAAA;AAElE,4EAA4E;AAC5E,yEAAyE;AACzE,2EAA2E;AAC3E,4EAA4E;AAC5E,8EAA8E;AAC9E,oDAAoD;AACpD,OAAO,EACL,aAAa,EACb,YAAY,EACZ,WAAW,EACX,aAAa,EACb,SAAS,EACT,SAAS,EACT,QAAQ,EACR,QAAQ,EACR,SAAS,EACT,WAAW,EACX,SAAS,GACV,MAAM,qBAAqB,CAAA;AAE5B,sFAAsF;AACtF,OAAO,EAAE,UAAU,EAAE,UAAU,EAAE,aAAa,EAAE,WAAW,EAAE,MAAM,qBAAqB,CAAA;AAExF,qEAAqE;AACrE,OAAO,EAAE,UAAU,EAAE,gBAAgB,EAAE,MAAM,qBAAqB,CAAA;AAElE,0EAA0E;AAC1E,+EAA+E;AAC/E,OAAO,EAAE,UAAU,EAAE,QAAQ,EAAE,MAAM,4BAA4B,CAAA;AAEjE,OAAO,EAAE,OAAO,EAAE,eAAe,EAAE,MAAM,yBAAyB,CAAA;AAOlE,OAAO,EAAE,QAAQ,EAAE,SAAS,EAAE,WAAW,EAAE,MAAM,uBAAuB,CAAA;AAOxE,OAAO,EAAE,cAAc,EAAE,MAAM,gCAAgC,CAAA;AAE/D,OAAO,EAAE,YAAY,EAAE,MAAM,8BAA8B,CAAA;AAE3D,OAAO,EAAE,SAAS,EAAE,MAAM,2BAA2B,CAAA;AAErD,OAAO,EAAE,SAAS,EAAE,MAAM,2BAA2B,CAAA;AAErD,OAAO,EAAE,WAAW,EAAE,MAAM,6BAA6B,CAAA;AAEzD,OAAO,EAAE,UAAU,EAAE,MAAM,4BAA4B,CAAA;AAEvD,OAAO,EAAE,eAAe,EAAE,MAAM,iCAAiC,CAAA;AAGjE,6EAA6E;AAC7E,OAAO,EAAE,aAAa,EAAE,QAAQ,EAAE,MAAM,uBAAuB,CAAA;AAE/D,OAAO,EAAE,UAAU,EAAE,MAAM,4BAA4B,CAAA;AAEvD,OAAO,EAAE,UAAU,EAAE,MAAM,4BAA4B,CAAA;AAGvD,YAAY;AACZ,OAAO,EAAE,gBAAgB,EAAE,WAAW,EAAE,WAAW,EAAE,MAAM,+BAA+B,CAAA;AAE1F,yEAAyE;AACzE,8EAA8E;AAC9E,4EAA4E;AAC5E,yEAAyE;AACzE,yEAAyE;AACzE,oEAAoE;AACpE,OAAO,EACL,WAAW,EACX,gBAAgB,EAChB,WAAW,EACX,aAAa,EACb,QAAQ,EACR,kBAAkB,EAClB,YAAY,EACZ,SAAS,EACT,iBAAiB,EACjB,SAAS,EACT,gBAAgB,EAChB,sBAAsB,EACtB,mBAAmB,GACpB,MAAM,kBAAkB,CAAA;AAezB,4EAA4E;AAC5E,mEAAmE;AACnE,0EAA0E;AAC1E,6DAA6D;AAC7D,4DAA4D;AAC5D,OAAO,EACL,cAAc,EACd,SAAS,EACT,YAAY,EACZ,kBAAkB,EAClB,gBAAgB,EAChB,WAAW,EACX,sBAAsB,GACvB,MAAM,mBAAmB,CAAA;AAiB1B,wEAAwE;AACxE,6EAA6E;AAC7E,gFAAgF;AAChF,+EAA+E;AAE/E,QAAQ;AACR,OAAO,EAAE,EAAE,EAAE,MAAM,gBAAgB,CAAA;AACnC,OAAO,EAAE,eAAe,EAAE,mBAAmB,EAAE,MAAM,4BAA4B,CAAA"}

package/dist/lib/focus-return.d.ts

@@ -0,0 +1,61 @@
+/**
+ * Focus return for the kit's dialogs and sheets (CI §12: focus goes back to
+ * where it came from).
+ *
+ * A Radix dialog returns the focus only to its `Trigger`. The kit's overlays
+ * mostly open from React state, without one (the builder's Save, Discard and
+ * Catalogue, a cell's props sheet), and Radix then cancels its focus scope's
+ * own restore and focuses nothing: closing them by keyboard left the focus on
+ * the document body. `DialogContent` and `SheetContent` therefore note the
+ * element that has the focus as they open and hand the focus back to it when
+ * they close and the focus went with them, while that element is still in the
+ * document. A consumer's own `onCloseAutoFocus` that calls `preventDefault()`
+ * keeps full control.
+ */
+/** The part of an element the hand-back needs (structural, so it tests without a DOM). */
+export interface FocusReturnTarget {
+    readonly isConnected: boolean;
+    focus: () => void;
+}
+/** The part of Radix's auto-focus events the hand-back reads. */
+export interface AutoFocusEventLike {
+    readonly defaultPrevented: boolean;
+    preventDefault: () => void;
+}
+/** One overlay's hand-back, from {@link createFocusReturn}. */
+export interface FocusReturn {
+    /**
+     * Notes the element that has the focus as the overlay opens. The document
+     * body is no target: a pointer that opened it without focusing anything
+     * (Safari does not focus a clicked button) leaves Radix's default in place.
+     */
+    capture: (active: FocusReturnTarget | null, body: unknown) => void;
+    /**
+     * Hands the focus back to the noted element when the overlay closes and the
+     * focus went with it (`focusLost`: it sits on the body). It leaves the focus
+     * where it is when a handler before it prevented that, when the focus
+     * already sits elsewhere (a click outside a non-modal overlay, a hand-off
+     * that moved it) or when the element left the document (an Apply or
+     * Discard that unmounted the builder). Forgets the element either way.
+     */
+    restore: (event: AutoFocusEventLike, focusLost: boolean) => void;
+}
+/** A {@link FocusReturn} with nothing noted yet. */
+export declare function createFocusReturn(): FocusReturn;
+/**
+ * The `onOpenAutoFocus` / `onCloseAutoFocus` pair of a Radix dialog content
+ * with the focus hand-back of {@link createFocusReturn} composed in: it notes
+ * the opener BEFORE the consumer's open handler runs (that one may move the
+ * focus) and hands it back AFTER the consumer's close handler (whose
+ * `preventDefault()` keeps it out). Radix fires the open event only when the
+ * focus is outside the content as it mounts, so an element inside it must not
+ * take the focus itself (`autoFocus`): Radix focuses the first one anyway.
+ */
+export declare function useFocusReturn<E extends AutoFocusEventLike>(handlers: {
+    onOpenAutoFocus?: (event: E) => void;
+    onCloseAutoFocus?: (event: E) => void;
+}): {
+    onOpenAutoFocus: (event: E) => void;
+    onCloseAutoFocus: (event: E) => void;
+};
+//# sourceMappingURL=focus-return.d.ts.map

package/dist/lib/focus-return.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"focus-return.d.ts","sourceRoot":"","sources":["../../src/lib/focus-return.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;GAaG;AAEH,0FAA0F;AAC1F,MAAM,WAAW,iBAAiB;IAChC,QAAQ,CAAC,WAAW,EAAE,OAAO,CAAA;IAC7B,KAAK,EAAE,MAAM,IAAI,CAAA;CAClB;AAED,iEAAiE;AACjE,MAAM,WAAW,kBAAkB;IACjC,QAAQ,CAAC,gBAAgB,EAAE,OAAO,CAAA;IAClC,cAAc,EAAE,MAAM,IAAI,CAAA;CAC3B;AAED,+DAA+D;AAC/D,MAAM,WAAW,WAAW;IAC1B;;;;OAIG;IACH,OAAO,EAAE,CAAC,MAAM,EAAE,iBAAiB,GAAG,IAAI,EAAE,IAAI,EAAE,OAAO,KAAK,IAAI,CAAA;IAClE;;;;;;;OAOG;IACH,OAAO,EAAE,CAAC,KAAK,EAAE,kBAAkB,EAAE,SAAS,EAAE,OAAO,KAAK,IAAI,CAAA;CACjE;AAED,oDAAoD;AACpD,wBAAgB,iBAAiB,IAAI,WAAW,CAc/C;AAED;;;;;;;;GAQG;AACH,wBAAgB,cAAc,CAAC,CAAC,SAAS,kBAAkB,EAAE,QAAQ,EAAE;IACrE,eAAe,CAAC,EAAE,CAAC,KAAK,EAAE,CAAC,KAAK,IAAI,CAAA;IACpC,gBAAgB,CAAC,EAAE,CAAC,KAAK,EAAE,CAAC,KAAK,IAAI,CAAA;CACtC,GAAG;IAAE,eAAe,EAAE,CAAC,KAAK,EAAE,CAAC,KAAK,IAAI,CAAC;IAAC,gBAAgB,EAAE,CAAC,KAAK,EAAE,CAAC,KAAK,IAAI,CAAA;CAAE,CAahF"}

package/dist/lib/focus-return.js

@@ -0,0 +1,46 @@
+import { useState } from "react";
+/** A {@link FocusReturn} with nothing noted yet. */
+export function createFocusReturn() {
+    let opener = null;
+    return {
+        capture: (active, body) => {
+            opener = active === body ? null : active;
+        },
+        restore: (event, focusLost) => {
+            const target = opener;
+            opener = null;
+            if (event.defaultPrevented || !focusLost || target === null || !target.isConnected)
+                return;
+            event.preventDefault();
+            target.focus();
+        },
+    };
+}
+/**
+ * The `onOpenAutoFocus` / `onCloseAutoFocus` pair of a Radix dialog content
+ * with the focus hand-back of {@link createFocusReturn} composed in: it notes
+ * the opener BEFORE the consumer's open handler runs (that one may move the
+ * focus) and hands it back AFTER the consumer's close handler (whose
+ * `preventDefault()` keeps it out). Radix fires the open event only when the
+ * focus is outside the content as it mounts, so an element inside it must not
+ * take the focus itself (`autoFocus`): Radix focuses the first one anyway.
+ */
+export function useFocusReturn(handlers) {
+    const [focusReturn] = useState(createFocusReturn);
+    return {
+        onOpenAutoFocus: (event) => {
+            focusReturn.capture(activeElementOf(document), document.body);
+            handlers.onOpenAutoFocus?.(event);
+        },
+        onCloseAutoFocus: (event) => {
+            handlers.onCloseAutoFocus?.(event);
+            const active = document.activeElement;
+            focusReturn.restore(event, active === null || active === document.body);
+        },
+    };
+}
+function activeElementOf(doc) {
+    const active = doc.activeElement;
+    return active && "focus" in active ? active : null;
+}
+//# sourceMappingURL=focus-return.js.map

package/dist/lib/focus-return.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"focus-return.js","sourceRoot":"","sources":["../../src/lib/focus-return.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,MAAM,OAAO,CAAA;AAgDhC,oDAAoD;AACpD,MAAM,UAAU,iBAAiB;IAC/B,IAAI,MAAM,GAA6B,IAAI,CAAA;IAC3C,OAAO;QACL,OAAO,EAAE,CAAC,MAAM,EAAE,IAAI,EAAE,EAAE;YACxB,MAAM,GAAG,MAAM,KAAK,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,MAAM,CAAA;QAC1C,CAAC;QACD,OAAO,EAAE,CAAC,KAAK,EAAE,SAAS,EAAE,EAAE;YAC5B,MAAM,MAAM,GAAG,MAAM,CAAA;YACrB,MAAM,GAAG,IAAI,CAAA;YACb,IAAI,KAAK,CAAC,gBAAgB,IAAI,CAAC,SAAS,IAAI,MAAM,KAAK,IAAI,IAAI,CAAC,MAAM,CAAC,WAAW;gBAAE,OAAM;YAC1F,KAAK,CAAC,cAAc,EAAE,CAAA;YACtB,MAAM,CAAC,KAAK,EAAE,CAAA;QAChB,CAAC;KACF,CAAA;AACH,CAAC;AAED;;;;;;;;GAQG;AACH,MAAM,UAAU,cAAc,CAA+B,QAG5D;IACC,MAAM,CAAC,WAAW,CAAC,GAAG,QAAQ,CAAC,iBAAiB,CAAC,CAAA;IACjD,OAAO;QACL,eAAe,EAAE,CAAC,KAAK,EAAE,EAAE;YACzB,WAAW,CAAC,OAAO,CAAC,eAAe,CAAC,QAAQ,CAAC,EAAE,QAAQ,CAAC,IAAI,CAAC,CAAA;YAC7D,QAAQ,CAAC,eAAe,EAAE,CAAC,KAAK,CAAC,CAAA;QACnC,CAAC;QACD,gBAAgB,EAAE,CAAC,KAAK,EAAE,EAAE;YAC1B,QAAQ,CAAC,gBAAgB,EAAE,CAAC,KAAK,CAAC,CAAA;YAClC,MAAM,MAAM,GAAG,QAAQ,CAAC,aAAa,CAAA;YACrC,WAAW,CAAC,OAAO,CAAC,KAAK,EAAE,MAAM,KAAK,IAAI,IAAI,MAAM,KAAK,QAAQ,CAAC,IAAI,CAAC,CAAA;QACzE,CAAC;KACF,CAAA;AACH,CAAC;AAED,SAAS,eAAe,CAAC,GAAa;IACpC,MAAM,MAAM,GAAG,GAAG,CAAC,aAAa,CAAA;IAChC,OAAO,MAAM,IAAI,OAAO,IAAI,MAAM,CAAC,CAAC,CAAE,MAAsB,CAAC,CAAC,CAAC,IAAI,CAAA;AACrE,CAAC"}

package/dist/lib/parse-tool-result.d.ts

@@ -13,10 +13,32 @@ export interface ParseToolResultOptions {
      */
     prefer?: "structured" | "text";
 }
+/**
+ * A tool answered with an `isError` result: a deterministic failure of the
+ * call itself (a validation error, an engine 404), not of the transport.
+ * Thrown by {@link parseToolResult}. The query hooks retry it like any
+ * failure by default (the client's `retry`); pass `retry: shouldRetryToolCall`
+ * to stop that, since repeating the call repeats the answer. Still an `Error`
+ * with the tool's first text block as its message.
+ */
+export declare class ToolResultError extends Error {
+    /** The `isError` result as the tool returned it. */
+    readonly result: unknown;
+    constructor(message: string, result: unknown);
+}
+/**
+ * Whether `error` is a tool's own `isError` answer: a {@link ToolResultError},
+ * or mcp-use's `ToolError` (how `useDynamicTool` rejects an `isError` result
+ * inside a view), recognised by its name and result so the root barrel never
+ * imports `mcp-use/react`. Transport failures (a lost connection, a JSON-RPC
+ * error such as an unknown tool) are not tool errors.
+ */
+export declare function isToolError(error: unknown): boolean;
 /**
  * Decodes an MCP tool result down to its data payload.
  *
- * Default (`prefer: "structured"`): `isError` → throw the first text block,
+ * Default (`prefer: "structured"`): `isError` → throw a
+ * {@link ToolResultError} with the first text block,
  * then `structuredContent` (if non-null), then JSON-decode the first text
  * block (verbatim string if it isn't JSON), then the raw result.
  *

package/dist/lib/parse-tool-result.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"parse-tool-result.d.ts","sourceRoot":"","sources":["../../src/lib/parse-tool-result.ts"],"names":[],"mappings":"AAEA,MAAM,WAAW,sBAAsB;IACrC;;;;;;;;;;;OAWG;IACH,MAAM,CAAC,EAAE,YAAY,GAAG,MAAM,CAAA;CAC/B;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,eAAe,CAAC,CAAC,GAAG,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,IAAI,CAAC,EAAE,sBAAsB,GAAG,CAAC,CAmC9F;AAKD;;;;;;;GAOG;AACH,wBAAgB,mBAAmB,CAAC,CAAC,GAAG,OAAO,EAAE,MAAM,EAAE,OAAO,GAAG,CAAC,CASnE"}
+{"version":3,"file":"parse-tool-result.d.ts","sourceRoot":"","sources":["../../src/lib/parse-tool-result.ts"],"names":[],"mappings":"AAEA,MAAM,WAAW,sBAAsB;IACrC;;;;;;;;;;;OAWG;IACH,MAAM,CAAC,EAAE,YAAY,GAAG,MAAM,CAAA;CAC/B;AAED;;;;;;;GAOG;AACH,qBAAa,eAAgB,SAAQ,KAAK;IACxC,oDAAoD;IACpD,QAAQ,CAAC,MAAM,EAAE,OAAO,CAAA;gBAEZ,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,OAAO;CAK7C;AAMD;;;;;;GAMG;AACH,wBAAgB,WAAW,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,CAKnD;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,eAAe,CAAC,CAAC,GAAG,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,IAAI,CAAC,EAAE,sBAAsB,GAAG,CAAC,CAmC9F;AAKD;;;;;;;GAOG;AACH,wBAAgB,mBAAmB,CAAC,CAAC,GAAG,OAAO,EAAE,MAAM,EAAE,OAAO,GAAG,CAAC,CASnE"}

package/dist/lib/parse-tool-result.js

@@ -1,7 +1,43 @@
+/**
+ * A tool answered with an `isError` result: a deterministic failure of the
+ * call itself (a validation error, an engine 404), not of the transport.
+ * Thrown by {@link parseToolResult}. The query hooks retry it like any
+ * failure by default (the client's `retry`); pass `retry: shouldRetryToolCall`
+ * to stop that, since repeating the call repeats the answer. Still an `Error`
+ * with the tool's first text block as its message.
+ */
+export class ToolResultError extends Error {
+    /** The `isError` result as the tool returned it. */
+    result;
+    constructor(message, result) {
+        super(message);
+        this.name = "ToolResultError";
+        this.result = result;
+    }
+}
+function isRecord(value) {
+    return typeof value === "object" && value !== null;
+}
+/**
+ * Whether `error` is a tool's own `isError` answer: a {@link ToolResultError},
+ * or mcp-use's `ToolError` (how `useDynamicTool` rejects an `isError` result
+ * inside a view), recognised by its name and result so the root barrel never
+ * imports `mcp-use/react`. Transport failures (a lost connection, a JSON-RPC
+ * error such as an unknown tool) are not tool errors.
+ */
+export function isToolError(error) {
+    if (error instanceof ToolResultError)
+        return true;
+    if (!(error instanceof Error) || error.name !== "ToolError")
+        return false;
+    const result = error.result;
+    return isRecord(result) && result.isError === true;
+}
 /**
  * Decodes an MCP tool result down to its data payload.
  *
- * Default (`prefer: "structured"`): `isError` → throw the first text block,
+ * Default (`prefer: "structured"`): `isError` → throw a
+ * {@link ToolResultError} with the first text block,
  * then `structuredContent` (if non-null), then JSON-decode the first text
  * block (verbatim string if it isn't JSON), then the raw result.
  *
@@ -14,7 +50,7 @@
 export function parseToolResult(result, opts) {
     const r = result;
     if (r?.isError)
-        throw new Error(r.content?.[0]?.text ?? "Tool call failed");
+        throw new ToolResultError(r.content?.[0]?.text ?? "Tool call failed", result);
     const fromStructured = () => r?.structuredContent != null ? r.structuredContent : undefined;
     const fromText = () => {
         const text = r?.content?.[0]?.text;

package/dist/lib/parse-tool-result.js.map

@@ -1 +1 @@
-{"version":3,"file":"parse-tool-result.js","sourceRoot":"","sources":["../../src/lib/parse-tool-result.ts"],"names":[],"mappings":"AAkBA;;;;;;;;;;;;GAYG;AACH,MAAM,UAAU,eAAe,CAAc,MAAe,EAAE,IAA6B;IACzF,MAAM,CAAC,GAAG,MAMG,CAAA;IACb,IAAI,CAAC,EAAE,OAAO;QAAE,MAAM,IAAI,KAAK,CAAC,CAAC,CAAC,OAAO,EAAE,CAAC,CAAC,CAAC,EAAE,IAAI,IAAI,kBAAkB,CAAC,CAAA;IAE3E,MAAM,cAAc,GAAG,GAAkB,EAAE,CACzC,CAAC,EAAE,iBAAiB,IAAI,IAAI,CAAC,CAAC,CAAE,CAAC,CAAC,iBAAuB,CAAC,CAAC,CAAC,SAAS,CAAA;IACvE,MAAM,QAAQ,GAAG,GAAkB,EAAE;QACnC,MAAM,IAAI,GAAG,CAAC,EAAE,OAAO,EAAE,CAAC,CAAC,CAAC,EAAE,IAAI,CAAA;QAClC,IAAI,IAAI,IAAI,IAAI;YAAE,OAAO,SAAS,CAAA;QAClC,IAAI,CAAC;YACH,OAAO,IAAI,CAAC,KAAK,CAAC,IAAI,CAAM,CAAA;QAC9B,CAAC;QAAC,MAAM,CAAC;YACP,OAAO,IAAS,CAAA;QAClB,CAAC;IACH,CAAC,CAAA;IAED,IAAI,IAAI,EAAE,MAAM,KAAK,MAAM,EAAE,CAAC;QAC5B,MAAM,IAAI,GAAG,QAAQ,EAAE,CAAA;QACvB,IAAI,IAAI,KAAK,SAAS;YAAE,OAAO,IAAI,CAAA;QACnC,MAAM,UAAU,GAAG,cAAc,EAAE,CAAA;QACnC,IAAI,UAAU,KAAK,SAAS;YAAE,OAAO,UAAU,CAAA;QAC/C,OAAO,CAAM,CAAA;IACf,CAAC;IAED,MAAM,UAAU,GAAG,cAAc,EAAE,CAAA;IACnC,IAAI,UAAU,KAAK,SAAS;QAAE,OAAO,UAAU,CAAA;IAC/C,MAAM,IAAI,GAAG,QAAQ,EAAE,CAAA;IACvB,IAAI,IAAI,KAAK,SAAS;QAAE,OAAO,IAAI,CAAA;IACnC,OAAO,CAAM,CAAA;AACf,CAAC;AAKD;;;;;;;GAOG;AACH,MAAM,UAAU,mBAAmB,CAAc,MAAe;IAC9D,MAAM,MAAM,GAAG,eAAe,CAAU,MAAM,CAAC,CAAA;IAC/C,MAAM,GAAG,GAAI,MAA8B,EAAE,OAAO,CAAA;IACpD,MAAM,OAAO,GAAG,GAAG,EAAE,OAAO,CAAA;IAC5B,IAAI,GAAG,EAAE,QAAQ,IAAI,KAAK,CAAC,OAAO,CAAC,OAAO,CAAC,IAAI,OAAO,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QAClE,IAAI,OAAO,CAAC,MAAM,KAAK,CAAC;YAAE,OAAO,GAAG,CAAC,QAAQ,CAAC,OAAO,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC,EAAE,IAAS,CAAA;QAC1E,OAAO,MAAM,CAAC,WAAW,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC,EAAE,EAAE,EAAE,CAAC,CAAC,EAAE,EAAE,GAAG,CAAC,QAAQ,CAAC,EAAE,CAAC,EAAE,IAAI,CAAC,CAAC,CAAM,CAAA;IACnF,CAAC;IACD,OAAO,MAAW,CAAA;AACpB,CAAC"}
+{"version":3,"file":"parse-tool-result.js","sourceRoot":"","sources":["../../src/lib/parse-tool-result.ts"],"names":[],"mappings":"AAkBA;;;;;;;GAOG;AACH,MAAM,OAAO,eAAgB,SAAQ,KAAK;IACxC,oDAAoD;IAC3C,MAAM,CAAS;IAExB,YAAY,OAAe,EAAE,MAAe;QAC1C,KAAK,CAAC,OAAO,CAAC,CAAA;QACd,IAAI,CAAC,IAAI,GAAG,iBAAiB,CAAA;QAC7B,IAAI,CAAC,MAAM,GAAG,MAAM,CAAA;IACtB,CAAC;CACF;AAED,SAAS,QAAQ,CAAC,KAAc;IAC9B,OAAO,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,KAAK,IAAI,CAAA;AACpD,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,WAAW,CAAC,KAAc;IACxC,IAAI,KAAK,YAAY,eAAe;QAAE,OAAO,IAAI,CAAA;IACjD,IAAI,CAAC,CAAC,KAAK,YAAY,KAAK,CAAC,IAAI,KAAK,CAAC,IAAI,KAAK,WAAW;QAAE,OAAO,KAAK,CAAA;IACzE,MAAM,MAAM,GAAa,KAAsC,CAAC,MAAM,CAAA;IACtE,OAAO,QAAQ,CAAC,MAAM,CAAC,IAAI,MAAM,CAAC,OAAO,KAAK,IAAI,CAAA;AACpD,CAAC;AAED;;;;;;;;;;;;;GAaG;AACH,MAAM,UAAU,eAAe,CAAc,MAAe,EAAE,IAA6B;IACzF,MAAM,CAAC,GAAG,MAMG,CAAA;IACb,IAAI,CAAC,EAAE,OAAO;QAAE,MAAM,IAAI,eAAe,CAAC,CAAC,CAAC,OAAO,EAAE,CAAC,CAAC,CAAC,EAAE,IAAI,IAAI,kBAAkB,EAAE,MAAM,CAAC,CAAA;IAE7F,MAAM,cAAc,GAAG,GAAkB,EAAE,CACzC,CAAC,EAAE,iBAAiB,IAAI,IAAI,CAAC,CAAC,CAAE,CAAC,CAAC,iBAAuB,CAAC,CAAC,CAAC,SAAS,CAAA;IACvE,MAAM,QAAQ,GAAG,GAAkB,EAAE;QACnC,MAAM,IAAI,GAAG,CAAC,EAAE,OAAO,EAAE,CAAC,CAAC,CAAC,EAAE,IAAI,CAAA;QAClC,IAAI,IAAI,IAAI,IAAI;YAAE,OAAO,SAAS,CAAA;QAClC,IAAI,CAAC;YACH,OAAO,IAAI,CAAC,KAAK,CAAC,IAAI,CAAM,CAAA;QAC9B,CAAC;QAAC,MAAM,CAAC;YACP,OAAO,IAAS,CAAA;QAClB,CAAC;IACH,CAAC,CAAA;IAED,IAAI,IAAI,EAAE,MAAM,KAAK,MAAM,EAAE,CAAC;QAC5B,MAAM,IAAI,GAAG,QAAQ,EAAE,CAAA;QACvB,IAAI,IAAI,KAAK,SAAS;YAAE,OAAO,IAAI,CAAA;QACnC,MAAM,UAAU,GAAG,cAAc,EAAE,CAAA;QACnC,IAAI,UAAU,KAAK,SAAS;YAAE,OAAO,UAAU,CAAA;QAC/C,OAAO,CAAM,CAAA;IACf,CAAC;IAED,MAAM,UAAU,GAAG,cAAc,EAAE,CAAA;IACnC,IAAI,UAAU,KAAK,SAAS;QAAE,OAAO,UAAU,CAAA;IAC/C,MAAM,IAAI,GAAG,QAAQ,EAAE,CAAA;IACvB,IAAI,IAAI,KAAK,SAAS;QAAE,OAAO,IAAI,CAAA;IACnC,OAAO,CAAM,CAAA;AACf,CAAC;AAKD;;;;;;;GAOG;AACH,MAAM,UAAU,mBAAmB,CAAc,MAAe;IAC9D,MAAM,MAAM,GAAG,eAAe,CAAU,MAAM,CAAC,CAAA;IAC/C,MAAM,GAAG,GAAI,MAA8B,EAAE,OAAO,CAAA;IACpD,MAAM,OAAO,GAAG,GAAG,EAAE,OAAO,CAAA;IAC5B,IAAI,GAAG,EAAE,QAAQ,IAAI,KAAK,CAAC,OAAO,CAAC,OAAO,CAAC,IAAI,OAAO,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QAClE,IAAI,OAAO,CAAC,MAAM,KAAK,CAAC;YAAE,OAAO,GAAG,CAAC,QAAQ,CAAC,OAAO,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC,EAAE,IAAS,CAAA;QAC1E,OAAO,MAAM,CAAC,WAAW,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC,EAAE,EAAE,EAAE,CAAC,CAAC,EAAE,EAAE,GAAG,CAAC,QAAQ,CAAC,EAAE,CAAC,EAAE,IAAI,CAAC,CAAC,CAAM,CAAA;IACnF,CAAC;IACD,OAAO,MAAW,CAAA;AACpB,CAAC"}

package/dist/lib/toast-model.d.ts

@@ -5,9 +5,19 @@
  */
 /** Status tone of a toast — the four status roles (`--success` … `--info`). */
 export type ToastTone = "success" | "warning" | "danger" | "info";
+/**
+ * The toast tone of any tone name: the four status tones as is, a retired
+ * name through `resolveTone` (`error` → `danger`), and `neutral` or anything
+ * unknown as `info`. Keeps a toast whose tone arrives untyped (plain JS, wire
+ * data) on the screen instead of crashing the view on a missing icon.
+ */
+export declare function resolveToastTone(name: unknown): ToastTone;
 /** What a caller passes to `useToast().show(...)`. */
 export interface ToastOptions {
-    /** Status tone; drives the edge, the icon and the default duration. Default `"info"`. */
+    /**
+     * Status tone; drives the edge, the icon and the default duration. Default
+     * `"info"`. An untyped retired name still resolves ({@link resolveToastTone}).
+     */
     tone?: ToastTone;
     /** The message. Say what happened, in one short sentence ("Job retried."). */
     title: string;
@@ -43,4 +53,34 @@ export type ToastAction = {
 };
 /** Add appends (dropping the oldest beyond {@link MAX_VISIBLE_TOASTS}); dismiss removes by id. */
 export declare function toastReducer(state: readonly ToastItem[], action: ToastAction): ToastItem[];
+/**
+ * The clock a {@link createToastTimer} runs on. The default reads the global
+ * timers at call time, so fake timers installed in a test take effect.
+ */
+export interface ToastClock {
+    now: () => number;
+    setTimeout: (callback: () => void, ms: number) => unknown;
+    clearTimeout: (handle: unknown) => void;
+}
+/** The countdown of one toast (see {@link createToastTimer}). */
+export interface ToastTimer {
+    /**
+     * Hold the toast for `reason` (`"pointer"`, `"focus"`): the countdown
+     * pauses and keeps the time that was left.
+     */
+    hold: (reason: string) => void;
+    /** Release `reason`; once nothing holds the toast, it resumes with the time that was left. */
+    release: (reason: string) => void;
+    /** The time left in ms — frozen while held. */
+    remaining: () => number;
+    /** Stop for good (the toast left early or unmounted); `onExpire` never fires afterwards. */
+    cancel: () => void;
+}
+/**
+ * A pausable countdown: starts at once, pauses while anything holds it
+ * (hover, keyboard focus — so a reader can finish), and on release RESUMES
+ * WITH THE REMAINING TIME instead of restarting the full duration. Fires
+ * `onExpire` once.
+ */
+export declare function createToastTimer(duration: number, onExpire: () => void, clock?: ToastClock): ToastTimer;
 //# sourceMappingURL=toast-model.d.ts.map

package/dist/lib/toast-model.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"toast-model.d.ts","sourceRoot":"","sources":["../../src/lib/toast-model.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,+EAA+E;AAC/E,MAAM,MAAM,SAAS,GAAG,SAAS,GAAG,SAAS,GAAG,QAAQ,GAAG,MAAM,CAAA;AAEjE,sDAAsD;AACtD,MAAM,WAAW,YAAY;IAC3B,yFAAyF;IACzF,IAAI,CAAC,EAAE,SAAS,CAAA;IAChB,8EAA8E;IAC9E,KAAK,EAAE,MAAM,CAAA;IACb,2EAA2E;IAC3E,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB,2EAA2E;IAC3E,QAAQ,CAAC,EAAE,MAAM,CAAA;CAClB;AAED,sCAAsC;AACtC,MAAM,WAAW,SAAS;IACxB,EAAE,EAAE,MAAM,CAAA;IACV,IAAI,EAAE,SAAS,CAAA;IACf,KAAK,EAAE,MAAM,CAAA;IACb,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB,QAAQ,EAAE,MAAM,CAAA;CACjB;AAED,wDAAwD;AACxD,eAAO,MAAM,iBAAiB,OAAO,CAAA;AACrC,sFAAsF;AACtF,eAAO,MAAM,uBAAuB,OAAO,CAAA;AAC3C,+DAA+D;AAC/D,eAAO,MAAM,kBAAkB,IAAI,CAAA;AAEnC,uFAAuF;AACvF,wBAAgB,aAAa,CAAC,IAAI,EAAE,SAAS,EAAE,QAAQ,CAAC,EAAE,MAAM,GAAG,MAAM,CAGxE;AAED,iDAAiD;AACjD,wBAAgB,WAAW,CAAC,EAAE,EAAE,MAAM,EAAE,OAAO,EAAE,YAAY,GAAG,SAAS,CASxE;AAED,MAAM,MAAM,WAAW,GAAG;IAAE,IAAI,EAAE,KAAK,CAAC;IAAC,KAAK,EAAE,SAAS,CAAA;CAAE,GAAG;IAAE,IAAI,EAAE,SAAS,CAAC;IAAC,EAAE,EAAE,MAAM,CAAA;CAAE,CAAA;AAE7F,kGAAkG;AAClG,wBAAgB,YAAY,CAAC,KAAK,EAAE,SAAS,SAAS,EAAE,EAAE,MAAM,EAAE,WAAW,GAAG,SAAS,EAAE,CAI1F"}
+{"version":3,"file":"toast-model.d.ts","sourceRoot":"","sources":["../../src/lib/toast-model.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAIH,+EAA+E;AAC/E,MAAM,MAAM,SAAS,GAAG,SAAS,GAAG,SAAS,GAAG,QAAQ,GAAG,MAAM,CAAA;AAEjE;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,OAAO,GAAG,SAAS,CAGzD;AAED,sDAAsD;AACtD,MAAM,WAAW,YAAY;IAC3B;;;OAGG;IACH,IAAI,CAAC,EAAE,SAAS,CAAA;IAChB,8EAA8E;IAC9E,KAAK,EAAE,MAAM,CAAA;IACb,2EAA2E;IAC3E,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB,2EAA2E;IAC3E,QAAQ,CAAC,EAAE,MAAM,CAAA;CAClB;AAED,sCAAsC;AACtC,MAAM,WAAW,SAAS;IACxB,EAAE,EAAE,MAAM,CAAA;IACV,IAAI,EAAE,SAAS,CAAA;IACf,KAAK,EAAE,MAAM,CAAA;IACb,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB,QAAQ,EAAE,MAAM,CAAA;CACjB;AAED,wDAAwD;AACxD,eAAO,MAAM,iBAAiB,OAAO,CAAA;AACrC,sFAAsF;AACtF,eAAO,MAAM,uBAAuB,OAAO,CAAA;AAC3C,+DAA+D;AAC/D,eAAO,MAAM,kBAAkB,IAAI,CAAA;AAEnC,uFAAuF;AACvF,wBAAgB,aAAa,CAAC,IAAI,EAAE,SAAS,EAAE,QAAQ,CAAC,EAAE,MAAM,GAAG,MAAM,CAGxE;AAED,iDAAiD;AACjD,wBAAgB,WAAW,CAAC,EAAE,EAAE,MAAM,EAAE,OAAO,EAAE,YAAY,GAAG,SAAS,CASxE;AAED,MAAM,MAAM,WAAW,GAAG;IAAE,IAAI,EAAE,KAAK,CAAC;IAAC,KAAK,EAAE,SAAS,CAAA;CAAE,GAAG;IAAE,IAAI,EAAE,SAAS,CAAC;IAAC,EAAE,EAAE,MAAM,CAAA;CAAE,CAAA;AAE7F,kGAAkG;AAClG,wBAAgB,YAAY,CAAC,KAAK,EAAE,SAAS,SAAS,EAAE,EAAE,MAAM,EAAE,WAAW,GAAG,SAAS,EAAE,CAI1F;AAED;;;GAGG;AACH,MAAM,WAAW,UAAU;IACzB,GAAG,EAAE,MAAM,MAAM,CAAA;IACjB,UAAU,EAAE,CAAC,QAAQ,EAAE,MAAM,IAAI,EAAE,EAAE,EAAE,MAAM,KAAK,OAAO,CAAA;IACzD,YAAY,EAAE,CAAC,MAAM,EAAE,OAAO,KAAK,IAAI,CAAA;CACxC;AAQD,iEAAiE;AACjE,MAAM,WAAW,UAAU;IACzB;;;OAGG;IACH,IAAI,EAAE,CAAC,MAAM,EAAE,MAAM,KAAK,IAAI,CAAA;IAC9B,8FAA8F;IAC9F,OAAO,EAAE,CAAC,MAAM,EAAE,MAAM,KAAK,IAAI,CAAA;IACjC,+CAA+C;IAC/C,SAAS,EAAE,MAAM,MAAM,CAAA;IACvB,4FAA4F;IAC5F,MAAM,EAAE,MAAM,IAAI,CAAA;CACnB;AAED;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAC9B,QAAQ,EAAE,MAAM,EAChB,QAAQ,EAAE,MAAM,IAAI,EACpB,KAAK,GAAE,UAAyB,GAC/B,UAAU,CA2CZ"}

package/dist/lib/toast-model.js

@@ -3,6 +3,17 @@
  * 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.
  */
+import { resolveTone } from "./tone-utils.js";
+/**
+ * The toast tone of any tone name: the four status tones as is, a retired
+ * name through `resolveTone` (`error` → `danger`), and `neutral` or anything
+ * unknown as `info`. Keeps a toast whose tone arrives untyped (plain JS, wire
+ * data) on the screen instead of crashing the view on a missing icon.
+ */
+export function resolveToastTone(name) {
+    const tone = resolveTone(name, "info");
+    return tone === "neutral" ? "info" : tone;
+}
 /** 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. */
@@ -17,7 +28,7 @@ export function toastDuration(tone, explicit) {
 }
 /** Normalise caller options into a list item. */
 export function createToast(id, options) {
-    const tone = options.tone ?? "info";
+    const tone = resolveToastTone(options.tone);
     return {
         id,
         tone,
@@ -33,4 +44,59 @@ export function toastReducer(state, action) {
     const next = state.filter((t) => t.id !== action.id);
     return next.length === state.length ? state : next;
 }
+const SYSTEM_CLOCK = {
+    now: () => Date.now(),
+    setTimeout: (callback, ms) => globalThis.setTimeout(callback, ms),
+    clearTimeout: (handle) => globalThis.clearTimeout(handle),
+};
+/**
+ * A pausable countdown: starts at once, pauses while anything holds it
+ * (hover, keyboard focus — so a reader can finish), and on release RESUMES
+ * WITH THE REMAINING TIME instead of restarting the full duration. Fires
+ * `onExpire` once.
+ */
+export function createToastTimer(duration, onExpire, clock = SYSTEM_CLOCK) {
+    let left = Math.max(duration, 0);
+    let startedAt = 0;
+    let handle;
+    let running = false;
+    let finished = false;
+    const holds = new Set();
+    const elapsed = () => (running ? clock.now() - startedAt : 0);
+    const start = () => {
+        if (finished || running || holds.size > 0)
+            return;
+        running = true;
+        startedAt = clock.now();
+        handle = clock.setTimeout(() => {
+            running = false;
+            finished = true;
+            left = 0;
+            onExpire();
+        }, left);
+    };
+    const pause = () => {
+        if (!running)
+            return;
+        left = Math.max(left - elapsed(), 0);
+        running = false;
+        clock.clearTimeout(handle);
+    };
+    start();
+    return {
+        hold: (reason) => {
+            holds.add(reason);
+            pause();
+        },
+        release: (reason) => {
+            holds.delete(reason);
+            start();
+        },
+        remaining: () => Math.max(left - elapsed(), 0),
+        cancel: () => {
+            pause();
+            finished = true;
+        },
+    };
+}
 //# sourceMappingURL=toast-model.js.map