@miragon/mcp-toolkit-ui 2.7.0 → 2.8.0

package/dist/components/Toast.d.ts

@@ -17,9 +17,15 @@ export interface ToastApi {
 export declare function useToast(): ToastApi;
 /**
  * The stack of toasts — a presentational view over a list (the provider owns
- * the state). The container is ONE persistent live region (`role="status"`,
- * `aria-live="polite"`), so a newly added toast is announced without stealing
- * focus. Bottom centre, above dialogs (z 60), per CI §5/§8.
+ * the state). The container is ONE persistent live region
+ * (`aria-live="polite"`, mounted before the first toast so that toast is
+ * announced, each new toast on its own: `aria-atomic="false"`), without
+ * stealing focus. Its attributes never change: a role or name that switched
+ * on with the first toast would make the browser rebuild the region in the
+ * same commit that inserts the toast, and a region created with its content
+ * already in it is not announced. So it carries no role (a generic element
+ * takes no name either): an idle stack is no second "status" next to a view's
+ * own loading status. Bottom centre, above dialogs (z 60), per CI §5/§8.
  */
 export declare function ToastViewport({ toasts, onDismiss, }: {
     toasts: readonly ToastItem[];

package/dist/components/Toast.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"Toast.d.ts","sourceRoot":"","sources":["../../src/components/Toast.tsx"],"names":[],"mappings":"AAAA,OAAO,EASL,KAAK,SAAS,EACf,MAAM,OAAO,CAAA;AAMd,OAAO,EAGL,KAAK,SAAS,EACd,KAAK,YAAY,EAElB,MAAM,uBAAuB,CAAA;AAE9B,YAAY,EAAE,YAAY,EAAE,SAAS,EAAE,MAAM,uBAAuB,CAAA;AAEpE,qCAAqC;AACrC,MAAM,WAAW,QAAQ;IACvB,4EAA4E;IAC5E,IAAI,EAAE,CAAC,OAAO,EAAE,YAAY,KAAK,MAAM,CAAA;IACvC,gDAAgD;IAChD,OAAO,EAAE,CAAC,EAAE,EAAE,MAAM,KAAK,IAAI,CAAA;CAC9B;AAOD;;;;;GAKG;AACH,wBAAgB,QAAQ,IAAI,QAAQ,CAEnC;AA0BD;;;;;GAKG;AACH,wBAAgB,aAAa,CAAC,EAC5B,MAAM,EACN,SAAS,GACV,EAAE;IACD,MAAM,EAAE,SAAS,SAAS,EAAE,CAAA;IAC5B,SAAS,EAAE,CAAC,EAAE,EAAE,MAAM,KAAK,IAAI,CAAA;CAChC,+BAoBA;AAyED;;;;;GAKG;AACH,wBAAgB,aAAa,CAAC,EAAE,QAAQ,EAAE,EAAE;IAAE,QAAQ,EAAE,SAAS,CAAA;CAAE,+TAGlE"}
+{"version":3,"file":"Toast.d.ts","sourceRoot":"","sources":["../../src/components/Toast.tsx"],"names":[],"mappings":"AAAA,OAAO,EASL,KAAK,SAAS,EACf,MAAM,OAAO,CAAA;AAMd,OAAO,EAIL,KAAK,SAAS,EACd,KAAK,YAAY,EAGlB,MAAM,uBAAuB,CAAA;AAE9B,YAAY,EAAE,YAAY,EAAE,SAAS,EAAE,MAAM,uBAAuB,CAAA;AAEpE,qCAAqC;AACrC,MAAM,WAAW,QAAQ;IACvB,4EAA4E;IAC5E,IAAI,EAAE,CAAC,OAAO,EAAE,YAAY,KAAK,MAAM,CAAA;IACvC,gDAAgD;IAChD,OAAO,EAAE,CAAC,EAAE,EAAE,MAAM,KAAK,IAAI,CAAA;CAC9B;AAOD;;;;;GAKG;AACH,wBAAgB,QAAQ,IAAI,QAAQ,CAEnC;AA0BD;;;;;;;;;;;GAWG;AACH,wBAAgB,aAAa,CAAC,EAC5B,MAAM,EACN,SAAS,GACV,EAAE;IACD,MAAM,EAAE,SAAS,SAAS,EAAE,CAAA;IAC5B,SAAS,EAAE,CAAC,EAAE,EAAE,MAAM,KAAK,IAAI,CAAA;CAChC,+BAmBA;AAoFD;;;;;GAKG;AACH,wBAAgB,aAAa,CAAC,EAAE,QAAQ,EAAE,EAAE;IAAE,QAAQ,EAAE,SAAS,CAAA;CAAE,+TAGlE"}

package/dist/components/Toast.js

@@ -1,11 +1,11 @@
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
-import { createContext, useCallback, useContext, useEffect, useMemo, useReducer, useRef, useState, } from "react";
+import { createContext, useCallback, useContext, useEffect, useMemo, useReducer, useRef, } from "react";
 import { CircleAlert, CircleCheck, Info, TriangleAlert, X } from "lucide-react";
 import { useToolkitMessages } from "../locale/locale-provider.js";
 import { FOCUS_RING } from "../lib/focus-ring.js";
 import { TONE_ICON } from "../lib/tone-utils.js";
 import { cn } from "../lib/utils.js";
-import { createToast, toastReducer, } from "../lib/toast-model.js";
+import { createToast, createToastTimer, toastReducer, } from "../lib/toast-model.js";
 const ToastContext = createContext(null);
 /** Outside a provider `useToast()` degrades to a no-op instead of throwing. */
 const NOOP_TOASTS = { show: () => -1, dismiss: () => { } };
@@ -42,28 +42,43 @@ const TOAST_ICON = {
 };
 /**
  * The stack of toasts — a presentational view over a list (the provider owns
- * the state). The container is ONE persistent live region (`role="status"`,
- * `aria-live="polite"`), so a newly added toast is announced without stealing
- * focus. Bottom centre, above dialogs (z 60), per CI §5/§8.
+ * the state). The container is ONE persistent live region
+ * (`aria-live="polite"`, mounted before the first toast so that toast is
+ * announced, each new toast on its own: `aria-atomic="false"`), without
+ * stealing focus. Its attributes never change: a role or name that switched
+ * on with the first toast would make the browser rebuild the region in the
+ * same commit that inserts the toast, and a region created with its content
+ * already in it is not announced. So it carries no role (a generic element
+ * takes no name either): an idle stack is no second "status" next to a view's
+ * own loading status. Bottom centre, above dialogs (z 60), per CI §5/§8.
  */
 export function ToastViewport({ toasts, onDismiss, }) {
     const messages = useToolkitMessages();
-    return (_jsx("div", { "data-slot": "toast-viewport", role: "status", "aria-live": "polite", "aria-label": messages.common.notifications, className: "pointer-events-none fixed inset-x-0 bottom-4 z-60 flex flex-col items-center gap-2 px-4", children: toasts.map((toast) => (_jsx(ToastCard, { toast: toast, dismissLabel: messages.common.dismiss, onDismiss: onDismiss }, toast.id))) }));
+    return (_jsx("div", { "data-slot": "toast-viewport", "aria-live": "polite", "aria-atomic": "false", className: "pointer-events-none fixed inset-x-0 bottom-4 z-60 flex flex-col items-center gap-2 px-4", children: toasts.map((toast) => (_jsx(ToastCard, { toast: toast, dismissLabel: messages.common.dismiss, onDismiss: onDismiss }, toast.id))) }));
 }
 function ToastCard({ toast, dismissLabel, onDismiss, }) {
-    // Hover or keyboard focus holds the toast: the timer restarts on leave.
-    const [held, setHeld] = useState(false);
+    // Hover or keyboard focus holds the toast; on leave it resumes with the
+    // time that was LEFT (createToastTimer), never a fresh full duration.
+    const timer = useRef(null);
     useEffect(() => {
-        if (held)
-            return;
-        const timer = setTimeout(() => onDismiss(toast.id), toast.duration);
-        return () => clearTimeout(timer);
-    }, [held, onDismiss, toast.id, toast.duration]);
+        const countdown = createToastTimer(toast.duration, () => onDismiss(toast.id));
+        timer.current = countdown;
+        return () => {
+            countdown.cancel();
+            timer.current = null;
+        };
+    }, [onDismiss, toast.id, toast.duration]);
+    const releaseFocus = (event) => {
+        // Focus moving inside the toast (card → close button) keeps the hold.
+        if (!event.currentTarget.contains(event.relatedTarget)) {
+            timer.current?.release("focus");
+        }
+    };
     const Icon = TOAST_ICON[toast.tone];
-    return (_jsxs("div", { "data-slot": "toast", "data-tone": toast.tone, onMouseEnter: () => setHeld(true), onMouseLeave: () => setHeld(false), onFocus: () => setHeld(true), onBlur: () => setHeld(false), className: cn(
+    return (_jsxs("div", { "data-slot": "toast", "data-tone": toast.tone, onMouseEnter: () => timer.current?.hold("pointer"), onMouseLeave: () => timer.current?.release("pointer"), onFocus: () => timer.current?.hold("focus"), onBlur: releaseFocus, className: cn(
         // An overlay like Dialog/Sheet: shadow-2 on light, the 3:1 input rim on
-        // dark (shadows vanish on the ground).
-        "bg-popover text-popover-foreground dark:border-input shadow-2 pointer-events-auto flex w-full max-w-sm items-start gap-3 rounded-md border border-l-4 px-4 py-3 text-sm", "motion-safe:animate-in motion-safe:fade-in-0 motion-safe:slide-in-from-bottom-2 motion-safe:duration-(--motion-base) motion-safe:ease-(--ease)", TONE_EDGE[toast.tone]), children: [_jsx(Icon, { "aria-hidden": "true", className: cn("mt-0.5 size-4 shrink-0", TONE_ICON[toast.tone]) }), _jsxs("div", { className: "min-w-0 flex-1", children: [_jsx("p", { className: "font-medium break-words", children: toast.title }), toast.description && (_jsx("p", { className: "text-muted-foreground mt-0.5 break-words", children: toast.description }))] }), _jsx("button", { type: "button", "aria-label": dismissLabel, onClick: () => onDismiss(toast.id), className: `text-muted-foreground hover:text-foreground -mr-1 inline-flex size-6 shrink-0 items-center justify-center rounded-sm ${FOCUS_RING}`, children: _jsx(X, { "aria-hidden": "true", className: "size-4" }) })] }));
+        // dark (shadows vanish on the ground). Its words are running text (16 px).
+        "bg-popover text-popover-foreground dark:border-input shadow-2 text-body pointer-events-auto flex w-full max-w-sm items-start gap-3 rounded-md border border-l-4 px-4 py-3", "motion-safe:animate-in motion-safe:fade-in-0 motion-safe:slide-in-from-bottom-2 motion-safe:duration-(--motion-base) motion-safe:ease-(--ease)", TONE_EDGE[toast.tone]), children: [_jsx(Icon, { "aria-hidden": "true", className: cn("mt-1 size-4 shrink-0", TONE_ICON[toast.tone]) }), _jsxs("div", { className: "min-w-0 flex-1", children: [_jsx("p", { className: "font-medium break-words", children: toast.title }), toast.description && (_jsx("p", { className: "text-muted-foreground mt-0.5 break-words", children: toast.description }))] }), _jsx("button", { type: "button", "aria-label": dismissLabel, onClick: () => onDismiss(toast.id), className: `text-muted-foreground hover:text-foreground -mr-1 inline-flex size-6 shrink-0 items-center justify-center rounded-sm ${FOCUS_RING}`, children: _jsx(X, { "aria-hidden": "true", className: "size-4" }) })] }));
 }
 function ToastRoot({ children }) {
     const [toasts, dispatch] = useReducer(toastReducer, []);

package/dist/components/Toast.js.map

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

package/dist/components/WidgetHeader.d.ts

@@ -1,21 +1,45 @@
 import type { ReactNode } from "react";
-import { type ToneVariant } from "../lib/tone-utils.js";
+import { type ToneName } from "../lib/tone-utils.js";
+/** Heading element of a {@link WidgetHeader} title. */
+export type WidgetHeadingLevel = "h1" | "h2" | "h3" | "h4" | "h5" | "h6";
 export interface WidgetHeaderProps {
-    /** Optional icon/glyph rendered in a tinted tile above the title. */
-    icon?: ReactNode;
-    /** Tone for the icon tile. Default `"neutral"`. */
-    iconTone?: ToneVariant;
     /** The widget title. */
     title: ReactNode;
-    /** Subtitle/meta row under the title (e.g. a live pill + counts). */
+    /**
+     * Heading element of the title. Default `"h1"`: the widget is the page.
+     * Pick the level that keeps ONE outline per view — below a toolbar title
+     * (`McpAppView` `titleMode="show"`, an h2 by default) use `"h3"`, inside a
+     * composed view under its own heading one level below it. The size follows
+     * `size`, not the level.
+     */
+    as?: WidgetHeadingLevel;
+    /**
+     * `"default"`: the page title (28 px / 700, the CI h2 style). `"detail"`:
+     * the compact detail-page title (21 px / 600, the CI h3 style).
+     */
+    size?: "default" | "detail";
+    /** Inline after the title inside the heading (e.g. a version chip). */
+    titleSuffix?: ReactNode;
+    /** Above the title — a `StatusBadge` that says the state in words. */
+    badge?: ReactNode;
+    /** Subtitle/meta row under the title (e.g. a live pill + counts), a 13 px caption row. */
     sub?: ReactNode;
     /** Right-aligned actions slot (buttons, drill controls). */
     actions?: ReactNode;
+    /**
+     * @deprecated A glyph in a tinted tile above every title is the icon-tile
+     * pattern the CI rules out (anti-slop U2). Say a state in words with a
+     * `StatusBadge` in {@link WidgetHeaderProps.badge}. Still rendered when set.
+     */
+    icon?: ReactNode;
+    /** @deprecated Tone of the deprecated {@link WidgetHeaderProps.icon} tile. */
+    iconTone?: ToneName;
+    className?: string;
 }
 /**
- * Page-level header for the top of a dashboard widget: an optional tinted icon
- * tile, a large title, a subtitle/meta row, and a right-aligned actions slot.
- * Use once per widget surface to anchor it.
+ * Page-level header at the top of a widget: an optional state badge, the
+ * title (heading level per `as`, size per `size`), a subtitle/meta row and a
+ * right-aligned actions slot. Use once per widget surface to anchor it.
  */
-export declare function WidgetHeader({ icon, iconTone, title, sub, actions, }: WidgetHeaderProps): import("react").JSX.Element;
+export declare function WidgetHeader({ title, as: Heading, size, titleSuffix, badge, sub, actions, icon, iconTone, className, }: WidgetHeaderProps): import("react").JSX.Element;
 //# sourceMappingURL=WidgetHeader.d.ts.map

package/dist/components/WidgetHeader.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"WidgetHeader.d.ts","sourceRoot":"","sources":["../../src/components/WidgetHeader.tsx"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,OAAO,CAAA;AACtC,OAAO,EAAa,KAAK,WAAW,EAAE,MAAM,sBAAsB,CAAA;AAElE,MAAM,WAAW,iBAAiB;IAChC,qEAAqE;IACrE,IAAI,CAAC,EAAE,SAAS,CAAA;IAChB,mDAAmD;IACnD,QAAQ,CAAC,EAAE,WAAW,CAAA;IACtB,wBAAwB;IACxB,KAAK,EAAE,SAAS,CAAA;IAChB,qEAAqE;IACrE,GAAG,CAAC,EAAE,SAAS,CAAA;IACf,4DAA4D;IAC5D,OAAO,CAAC,EAAE,SAAS,CAAA;CACpB;AAED;;;;GAIG;AACH,wBAAgB,YAAY,CAAC,EAC3B,IAAI,EACJ,QAAoB,EACpB,KAAK,EACL,GAAG,EACH,OAAO,GACR,EAAE,iBAAiB,+BAuBnB"}
+{"version":3,"file":"WidgetHeader.d.ts","sourceRoot":"","sources":["../../src/components/WidgetHeader.tsx"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,OAAO,CAAA;AACtC,OAAO,EAA0B,KAAK,QAAQ,EAAE,MAAM,sBAAsB,CAAA;AAG5E,uDAAuD;AACvD,MAAM,MAAM,kBAAkB,GAAG,IAAI,GAAG,IAAI,GAAG,IAAI,GAAG,IAAI,GAAG,IAAI,GAAG,IAAI,CAAA;AAExE,MAAM,WAAW,iBAAiB;IAChC,wBAAwB;IACxB,KAAK,EAAE,SAAS,CAAA;IAChB;;;;;;OAMG;IACH,EAAE,CAAC,EAAE,kBAAkB,CAAA;IACvB;;;OAGG;IACH,IAAI,CAAC,EAAE,SAAS,GAAG,QAAQ,CAAA;IAC3B,uEAAuE;IACvE,WAAW,CAAC,EAAE,SAAS,CAAA;IACvB,sEAAsE;IACtE,KAAK,CAAC,EAAE,SAAS,CAAA;IACjB,0FAA0F;IAC1F,GAAG,CAAC,EAAE,SAAS,CAAA;IACf,4DAA4D;IAC5D,OAAO,CAAC,EAAE,SAAS,CAAA;IACnB;;;;OAIG;IACH,IAAI,CAAC,EAAE,SAAS,CAAA;IAChB,8EAA8E;IAC9E,QAAQ,CAAC,EAAE,QAAQ,CAAA;IACnB,SAAS,CAAC,EAAE,MAAM,CAAA;CACnB;AAOD;;;;GAIG;AACH,wBAAgB,YAAY,CAAC,EAC3B,KAAK,EACL,EAAE,EAAE,OAAc,EAClB,IAAgB,EAChB,WAAW,EACX,KAAK,EACL,GAAG,EACH,OAAO,EACP,IAAI,EACJ,QAAoB,EACpB,SAAS,GACV,EAAE,iBAAiB,+BAkCnB"}

package/dist/components/WidgetHeader.js

@@ -1,11 +1,16 @@
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
-import { TONE_SOFT } from "../lib/tone-utils.js";
+import { resolveTone, TONE_SOFT } from "../lib/tone-utils.js";
+import { cn } from "../lib/utils.js";
+const TITLE_SIZE = {
+    default: "text-title",
+    detail: "text-section",
+};
 /**
- * Page-level header for the top of a dashboard widget: an optional tinted icon
- * tile, a large title, a subtitle/meta row, and a right-aligned actions slot.
- * Use once per widget surface to anchor it.
+ * Page-level header at the top of a widget: an optional state badge, the
+ * title (heading level per `as`, size per `size`), a subtitle/meta row and a
+ * right-aligned actions slot. Use once per widget surface to anchor it.
  */
-export function WidgetHeader({ icon, iconTone = "neutral", title, sub, actions, }) {
-    return (_jsxs("header", { className: "flex flex-wrap items-start justify-between gap-4", children: [_jsxs("div", { className: "min-w-0", children: [icon && (_jsx("div", { className: `mb-3.5 grid size-11 place-items-center rounded-md text-xl ${TONE_SOFT[iconTone]}`, children: icon })), _jsx("h1", { className: "text-foreground mb-1.5 text-3xl leading-tight font-bold tracking-tight", children: title }), sub && (_jsx("div", { className: "text-muted-foreground flex flex-wrap items-center gap-2 text-sm", children: sub }))] }), actions && _jsx("div", { className: "flex flex-wrap items-center gap-2", children: actions })] }));
+export function WidgetHeader({ title, as: Heading = "h1", size = "default", titleSuffix, badge, sub, actions, icon, iconTone = "neutral", className, }) {
+    return (_jsxs("header", { "data-slot": "widget-header", className: cn("flex flex-wrap items-start justify-between gap-4", className), children: [_jsxs("div", { className: "min-w-0", children: [icon && (_jsx("div", { "aria-hidden": "true", className: cn("text-section mb-3.5 grid size-11 place-items-center rounded-md", TONE_SOFT[resolveTone(iconTone)]), children: icon })), badge && _jsx("div", { className: "mb-3", children: badge }), _jsxs(Heading, { className: cn("text-foreground mb-1.5 tracking-tight break-words", TITLE_SIZE[size]), children: [title, titleSuffix] }), sub && (_jsx("div", { className: "text-muted-foreground text-small flex flex-wrap items-center gap-2", children: sub }))] }), actions && _jsx("div", { className: "flex flex-wrap items-center gap-2", children: actions })] }));
 }
 //# sourceMappingURL=WidgetHeader.js.map

package/dist/components/WidgetHeader.js.map

@@ -1 +1 @@
-{"version":3,"file":"WidgetHeader.js","sourceRoot":"","sources":["../../src/components/WidgetHeader.tsx"],"names":[],"mappings":";AACA,OAAO,EAAE,SAAS,EAAoB,MAAM,sBAAsB,CAAA;AAelE;;;;GAIG;AACH,MAAM,UAAU,YAAY,CAAC,EAC3B,IAAI,EACJ,QAAQ,GAAG,SAAS,EACpB,KAAK,EACL,GAAG,EACH,OAAO,GACW;IAClB,OAAO,CACL,kBAAQ,SAAS,EAAC,kDAAkD,aAClE,eAAK,SAAS,EAAC,SAAS,aACrB,IAAI,IAAI,CACP,cACE,SAAS,EAAE,6DAA6D,SAAS,CAAC,QAAQ,CAAC,EAAE,YAE5F,IAAI,GACD,CACP,EACD,aAAI,SAAS,EAAC,wEAAwE,YACnF,KAAK,GACH,EACJ,GAAG,IAAI,CACN,cAAK,SAAS,EAAC,iEAAiE,YAC7E,GAAG,GACA,CACP,IACG,EACL,OAAO,IAAI,cAAK,SAAS,EAAC,mCAAmC,YAAE,OAAO,GAAO,IACvE,CACV,CAAA;AACH,CAAC"}
+{"version":3,"file":"WidgetHeader.js","sourceRoot":"","sources":["../../src/components/WidgetHeader.tsx"],"names":[],"mappings":";AACA,OAAO,EAAE,WAAW,EAAE,SAAS,EAAiB,MAAM,sBAAsB,CAAA;AAC5E,OAAO,EAAE,EAAE,EAAE,MAAM,iBAAiB,CAAA;AAwCpC,MAAM,UAAU,GAA2D;IACzE,OAAO,EAAE,YAAY;IACrB,MAAM,EAAE,cAAc;CACvB,CAAA;AAED;;;;GAIG;AACH,MAAM,UAAU,YAAY,CAAC,EAC3B,KAAK,EACL,EAAE,EAAE,OAAO,GAAG,IAAI,EAClB,IAAI,GAAG,SAAS,EAChB,WAAW,EACX,KAAK,EACL,GAAG,EACH,OAAO,EACP,IAAI,EACJ,QAAQ,GAAG,SAAS,EACpB,SAAS,GACS;IAClB,OAAO,CACL,+BACY,eAAe,EACzB,SAAS,EAAE,EAAE,CAAC,kDAAkD,EAAE,SAAS,CAAC,aAE5E,eAAK,SAAS,EAAC,SAAS,aACrB,IAAI,IAAI,CACP,6BACc,MAAM,EAClB,SAAS,EAAE,EAAE,CACX,gEAAgE,EAChE,SAAS,CAAC,WAAW,CAAC,QAAQ,CAAC,CAAC,CACjC,YAEA,IAAI,GACD,CACP,EACA,KAAK,IAAI,cAAK,SAAS,EAAC,MAAM,YAAE,KAAK,GAAO,EAC7C,MAAC,OAAO,IACN,SAAS,EAAE,EAAE,CAAC,mDAAmD,EAAE,UAAU,CAAC,IAAI,CAAC,CAAC,aAEnF,KAAK,EACL,WAAW,IACJ,EACT,GAAG,IAAI,CACN,cAAK,SAAS,EAAC,oEAAoE,YAChF,GAAG,GACA,CACP,IACG,EACL,OAAO,IAAI,cAAK,SAAS,EAAC,mCAAmC,YAAE,OAAO,GAAO,IACvE,CACV,CAAA;AACH,CAAC"}

package/dist/hooks/index.d.ts

@@ -1,11 +1,11 @@
 export { useIsMobile } from "./use-mobile.js";
 export { useDebouncedValue } from "./use-debounced-value.js";
-export { useToolQuery, useToolMutation } from "./use-tool-query.js";
-export type { UseToolQueryOptions } from "./use-tool-query.js";
+export { useToolQuery, useToolQueryKey, useToolMutation } from "./use-tool-query.js";
+export type { UseToolQueryOptions, UseToolMutationOptions } from "./use-tool-query.js";
 export { useViewToolQuery } from "./use-view-tool-query.js";
 export type { UseViewToolQueryOptions } from "./use-view-tool-query.js";
 export { useViewData } from "./use-view-data.js";
-export type { ViewDataResult } from "./use-view-data.js";
+export type { ViewDataResult, UseViewDataOptions, ViewDataMode } from "./use-view-data.js";
 export { useToolResultRecovery, resolveRecoveryToolName, decodeRecoveredResult, } from "./use-tool-result-recovery.js";
-export type { ToolResultRecoveryOptions, ToolResultRecoveryState, } from "./use-tool-result-recovery.js";
+export type { RecoveryBlockReason, RecoveryPolicy, ToolResultRecoveryOptions, ToolResultRecoveryState, ToolSafety, } from "./use-tool-result-recovery.js";
 //# sourceMappingURL=index.d.ts.map

package/dist/hooks/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/hooks/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,MAAM,iBAAiB,CAAA;AAC7C,OAAO,EAAE,iBAAiB,EAAE,MAAM,0BAA0B,CAAA;AAC5D,OAAO,EAAE,YAAY,EAAE,eAAe,EAAE,MAAM,qBAAqB,CAAA;AACnE,YAAY,EAAE,mBAAmB,EAAE,MAAM,qBAAqB,CAAA;AAC9D,OAAO,EAAE,gBAAgB,EAAE,MAAM,0BAA0B,CAAA;AAC3D,YAAY,EAAE,uBAAuB,EAAE,MAAM,0BAA0B,CAAA;AACvE,OAAO,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAA;AAChD,YAAY,EAAE,cAAc,EAAE,MAAM,oBAAoB,CAAA;AACxD,OAAO,EACL,qBAAqB,EACrB,uBAAuB,EACvB,qBAAqB,GACtB,MAAM,+BAA+B,CAAA;AACtC,YAAY,EACV,yBAAyB,EACzB,uBAAuB,GACxB,MAAM,+BAA+B,CAAA"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/hooks/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,MAAM,iBAAiB,CAAA;AAC7C,OAAO,EAAE,iBAAiB,EAAE,MAAM,0BAA0B,CAAA;AAC5D,OAAO,EAAE,YAAY,EAAE,eAAe,EAAE,eAAe,EAAE,MAAM,qBAAqB,CAAA;AACpF,YAAY,EAAE,mBAAmB,EAAE,sBAAsB,EAAE,MAAM,qBAAqB,CAAA;AACtF,OAAO,EAAE,gBAAgB,EAAE,MAAM,0BAA0B,CAAA;AAC3D,YAAY,EAAE,uBAAuB,EAAE,MAAM,0BAA0B,CAAA;AACvE,OAAO,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAA;AAChD,YAAY,EAAE,cAAc,EAAE,kBAAkB,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAA;AAC1F,OAAO,EACL,qBAAqB,EACrB,uBAAuB,EACvB,qBAAqB,GACtB,MAAM,+BAA+B,CAAA;AACtC,YAAY,EACV,mBAAmB,EACnB,cAAc,EACd,yBAAyB,EACzB,uBAAuB,EACvB,UAAU,GACX,MAAM,+BAA+B,CAAA"}

package/dist/hooks/index.js

@@ -1,6 +1,6 @@
 export { useIsMobile } from "./use-mobile.js";
 export { useDebouncedValue } from "./use-debounced-value.js";
-export { useToolQuery, useToolMutation } from "./use-tool-query.js";
+export { useToolQuery, useToolQueryKey, useToolMutation } from "./use-tool-query.js";
 export { useViewToolQuery } from "./use-view-tool-query.js";
 export { useViewData } from "./use-view-data.js";
 export { useToolResultRecovery, resolveRecoveryToolName, decodeRecoveredResult, } from "./use-tool-result-recovery.js";

package/dist/hooks/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/hooks/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,MAAM,iBAAiB,CAAA;AAC7C,OAAO,EAAE,iBAAiB,EAAE,MAAM,0BAA0B,CAAA;AAC5D,OAAO,EAAE,YAAY,EAAE,eAAe,EAAE,MAAM,qBAAqB,CAAA;AAEnE,OAAO,EAAE,gBAAgB,EAAE,MAAM,0BAA0B,CAAA;AAE3D,OAAO,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAA;AAEhD,OAAO,EACL,qBAAqB,EACrB,uBAAuB,EACvB,qBAAqB,GACtB,MAAM,+BAA+B,CAAA"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/hooks/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,MAAM,iBAAiB,CAAA;AAC7C,OAAO,EAAE,iBAAiB,EAAE,MAAM,0BAA0B,CAAA;AAC5D,OAAO,EAAE,YAAY,EAAE,eAAe,EAAE,eAAe,EAAE,MAAM,qBAAqB,CAAA;AAEpF,OAAO,EAAE,gBAAgB,EAAE,MAAM,0BAA0B,CAAA;AAE3D,OAAO,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAA;AAEhD,OAAO,EACL,qBAAqB,EACrB,uBAAuB,EACvB,qBAAqB,GACtB,MAAM,+BAA+B,CAAA"}

package/dist/hooks/tool-result-recovery-model.d.ts

@@ -0,0 +1,155 @@
+import type { ToolObservation, ToolResultObserver } from "../lib/tool-result-observer.js";
+/**
+ * What the host's tool annotations say about re-running the originating
+ * tool: `readOnlyHint: true` is `"read-only"`, `readOnlyHint: false` or
+ * `destructiveHint: true` is `"writes"`, anything else (no tool definition,
+ * no annotations, no read-only hint) is `"unknown"`.
+ */
+export type ToolSafety = "read-only" | "writes" | "unknown";
+/**
+ * Which tools the view may re-execute on its own to recover a stripped result.
+ *
+ * - `"auto"` (default): any tool the host does not report as writing — a
+ *   view tool is a read by the toolkit's render contract, so a missing hint
+ *   counts as one.
+ * - `"read-only"`: only a tool the host reports with `readOnlyHint: true`.
+ * - `"never"`: never; a stripped result shows the error state, whose retry
+ *   runs the tool on the user's click.
+ */
+export type RecoveryPolicy = "auto" | "read-only" | "never";
+/** Why a needed recovery did not run: the policy forbids it, or the host names no tool. */
+export type RecoveryBlockReason = "policy" | "no-tool";
+/** Read {@link ToolSafety} from `hostContext.toolInfo.tool.annotations` (SEP-1865). */
+export declare function resolveToolSafety(hostContext: unknown): ToolSafety;
+/** Whether `policy` lets the view re-execute a tool of this `safety` on its own. */
+export declare function policyAllows(policy: RecoveryPolicy, safety: ToolSafety): boolean;
+export interface RecoveryDecisionInput {
+    /** The latch fired (`useToolContext().status !== "pending"`). */
+    resultReady: boolean;
+    /** The latched payload is renderable (a conforming host delivered it). */
+    payloadValid: boolean;
+    /** The host cancelled the call. */
+    cancelled: boolean;
+    /** The call latched a tool error (an `isError` result or a failed call). */
+    errored: boolean;
+    /** What the transport observer saw; `null` when none listens. */
+    observation: ToolObservation | null;
+    /** The call's arguments arrived (any tool-input, partial or complete). */
+    hasInput: boolean;
+    /** The originating tool (`hostContext.toolInfo`), when the host names it. */
+    toolName: string | undefined;
+    safety: ToolSafety;
+    policy: RecoveryPolicy;
+    /** The fallback grace period passed for the current arguments. */
+    graceElapsed: boolean;
+}
+export type RecoveryDecision = 
+/** Delivered, failed or cancelled: nothing to recover. */
+{
+    action: "none";
+}
+/** The result is not in yet; `armGrace` starts the fallback timer (observer cannot vouch). */
+ | {
+    action: "wait";
+    armGrace: boolean;
+}
+/** Re-execute the originating tool now. */
+ | {
+    action: "recover";
+}
+/** A recovery is needed but must not run. */
+ | {
+    action: "blocked";
+    reason: RecoveryBlockReason;
+};
+/** The recovery rule (see the module comment). Pure: every input is explicit. */
+export declare function decideRecovery(input: RecoveryDecisionInput): RecoveryDecision;
+/**
+ * The arguments a re-execution runs with: the complete tool-input the
+ * observer saw, else the view runtime's latest input, else none.
+ */
+export declare function recoveryArgs(observation: ToolObservation | null, toolInput: Record<string, unknown> | null | undefined): Record<string, unknown>;
+/**
+ * Content identity of a JSON value, independent of key order and object
+ * identity: a re-delivered equal input is the same input (N21).
+ */
+export declare function stableKey(value: unknown): string;
+/**
+ * Decodes a re-executed tool result and validates it: the payload, or `null`
+ * for an error result, an empty one or one the validator refuses.
+ */
+export declare function decodeRecoveredResult<T>(result: unknown, isValid: (value: unknown) => boolean): T | null;
+export interface ToolResultRecoveryState<T> {
+    /** The recovered payload, `null` until the re-execution resolved (or when it failed). */
+    data: T | null;
+    /** The single recovery attempt failed — the view shows its error state, no retry loop. */
+    failed: boolean;
+    /**
+     * A recovery was needed but did not run: the policy forbids re-executing
+     * this tool, or the host names no tool. `null` otherwise.
+     */
+    blocked: RecoveryBlockReason | null;
+    /** When the recovered payload arrived (epoch ms) — its data is live as of then (N23). */
+    recoveredAt: number | null;
+    /** The arguments the recovered payload was computed for. */
+    args: Record<string, unknown> | null;
+}
+export declare const RECOVERY_IDLE: ToolResultRecoveryState<never>;
+/** What the view knows about the rendering call on each render. */
+export interface RecoveryInputs {
+    resultReady: boolean;
+    cancelled: boolean;
+    errored: boolean;
+    /** The payload the host delivered (`useToolContext().toolOutput`). */
+    props: unknown;
+    isValid: (value: unknown) => boolean;
+    toolInput: Record<string, unknown> | null | undefined;
+    /** Raw host context; `toolInfo` names the originating tool and its annotations. */
+    hostContext: Record<string, unknown> | null | undefined;
+    callTool: (name: string, args: Record<string, unknown>) => Promise<unknown>;
+    policy: RecoveryPolicy;
+    /** The fallback grace period (observer cannot vouch). */
+    graceMs: number;
+    /** Resolves the originating tool name from the host context. */
+    resolveToolName: (hostContext: unknown) => string | undefined;
+}
+export interface RecoveryController<T> {
+    subscribe: (listener: () => void) => () => void;
+    getState: () => ToolResultRecoveryState<T>;
+    /** Feed the latest inputs (every commit) and act on the decision. */
+    update: (inputs: RecoveryInputs) => void;
+    /** Listen to the observer (mount). */
+    start: () => void;
+    /** Stop listening and drop the grace timer; an in-flight call still lands (StrictMode re-runs). */
+    stop: () => void;
+}
+export interface RecoveryControllerOptions {
+    /** The transport observer; `null` when none listens (the grace timer decides alone). */
+    observer: ToolResultObserver | null;
+    /** Clock for {@link ToolResultRecoveryState.recoveredAt}. Default `Date.now`. */
+    now?: () => number;
+}
+/** One evaluation of the inputs: the decision plus the run it concerns. */
+interface Evaluation {
+    decision: RecoveryDecision;
+    toolName: string | undefined;
+    args: Record<string, unknown>;
+    /** Content identity of `args` (the grace timer's key). */
+    argsKey: string;
+    /** Identity of the run: the tool and its arguments (the single flight's key). */
+    runKey: string;
+}
+/** Run {@link decideRecovery} on the controller's current knowledge. */
+export declare function evaluateRecovery(inputs: RecoveryInputs, observation: ToolObservation | null, grace: {
+    key: string | null;
+    elapsed: boolean;
+}): Evaluation;
+/**
+ * Runs {@link decideRecovery} for the view: re-evaluates on every input
+ * update and observer change, arms the fallback grace timer per argument set,
+ * and makes at most one call per run (single flight, keyed by the tool and
+ * its arguments; a newer run drops an older call's outcome).
+ */
+export declare function createRecoveryController<T>(options: RecoveryControllerOptions): RecoveryController<T>;
+export {};
+//# sourceMappingURL=tool-result-recovery-model.d.ts.map

package/dist/hooks/tool-result-recovery-model.d.ts.map

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