@miragon/mcp-toolkit-ui 2.7.0 → 2.8.0

package/dist/lib/toast-model.js.map

@@ -1 +1 @@
-{"version":3,"file":"toast-model.js","sourceRoot":"","sources":["../../src/lib/toast-model.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AA0BH,wDAAwD;AACxD,MAAM,CAAC,MAAM,iBAAiB,GAAG,IAAI,CAAA;AACrC,sFAAsF;AACtF,MAAM,CAAC,MAAM,uBAAuB,GAAG,IAAI,CAAA;AAC3C,+DAA+D;AAC/D,MAAM,CAAC,MAAM,kBAAkB,GAAG,CAAC,CAAA;AAEnC,uFAAuF;AACvF,MAAM,UAAU,aAAa,CAAC,IAAe,EAAE,QAAiB;IAC9D,IAAI,QAAQ,KAAK,SAAS,IAAI,MAAM,CAAC,QAAQ,CAAC,QAAQ,CAAC,IAAI,QAAQ,GAAG,CAAC;QAAE,OAAO,QAAQ,CAAA;IACxF,OAAO,IAAI,KAAK,QAAQ,CAAC,CAAC,CAAC,uBAAuB,CAAC,CAAC,CAAC,iBAAiB,CAAA;AACxE,CAAC;AAED,iDAAiD;AACjD,MAAM,UAAU,WAAW,CAAC,EAAU,EAAE,OAAqB;IAC3D,MAAM,IAAI,GAAG,OAAO,CAAC,IAAI,IAAI,MAAM,CAAA;IACnC,OAAO;QACL,EAAE;QACF,IAAI;QACJ,KAAK,EAAE,OAAO,CAAC,KAAK;QACpB,GAAG,CAAC,OAAO,CAAC,WAAW,CAAC,CAAC,CAAC,EAAE,WAAW,EAAE,OAAO,CAAC,WAAW,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QACpE,QAAQ,EAAE,aAAa,CAAC,IAAI,EAAE,OAAO,CAAC,QAAQ,CAAC;KAChD,CAAA;AACH,CAAC;AAID,kGAAkG;AAClG,MAAM,UAAU,YAAY,CAAC,KAA2B,EAAE,MAAmB;IAC3E,IAAI,MAAM,CAAC,IAAI,KAAK,KAAK;QAAE,OAAO,CAAC,GAAG,KAAK,EAAE,MAAM,CAAC,KAAK,CAAC,CAAC,KAAK,CAAC,CAAC,kBAAkB,CAAC,CAAA;IACrF,MAAM,IAAI,GAAG,KAAK,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,EAAE,KAAK,MAAM,CAAC,EAAE,CAAC,CAAA;IACpD,OAAO,IAAI,CAAC,MAAM,KAAK,KAAK,CAAC,MAAM,CAAC,CAAC,CAAE,KAAqB,CAAC,CAAC,CAAC,IAAI,CAAA;AACrE,CAAC"}
+{"version":3,"file":"toast-model.js","sourceRoot":"","sources":["../../src/lib/toast-model.ts"],"names":[],"mappings":"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"}

package/dist/lib/tone-utils.d.ts

@@ -1,6 +1,11 @@
 /**
  * Single source of truth for the semantic "tones" used across the tone-aware
- * components (`Pills`, `KpiGrid`, `WidgetHeader`, `Badge`, …).
+ * components (`Pills`, `StatusBadge`, `KpiGrid`, `Badge`, …).
+ *
+ * ONE vocabulary: `success | warning | danger | info | neutral`
+ * ({@link TONE_VARIANTS}). Retired or foreign names (`critical`, `error`,
+ * `destructive`, …) map onto it through {@link resolveTone}, so a tone that
+ * arrives as data (a server-built KPI cell) never renders without a colour.
  *
  * Every status tone has THREE roles (Miragon CI §3.3), each its own token in
  * `theme.css` with light and dark values:
@@ -8,14 +13,14 @@
  * | Role                         | Token           | Map            |
  * | ---------------------------- | --------------- | -------------- |
  * | fill, dot, border, icon      | `--<tone>`      | `TONE_DOT`, `TONE_BORDER`, `TONE_ICON` |
- * | tint (badge/banner surface)  | `--<tone>-soft` | `TONE_SOFT` (text on it: the foreground) |
- * | text on a plain surface      | `--<tone>-ink`  | `TONE_TEXT`    |
+ * | tint (badge/banner surface)  | `--<tone>-soft` | `TONE_SOFT`, `TONE_TINT` (text on it: the foreground) |
+ * | text on a plain surface      | `--<tone>-ink`  | `TONE_INK`     |
  *
  * Status is never text in its own colour: success and warning reach only
  * 1.67:1 / 1.83:1 on white, so their ink is the foreground and the tone shows
  * as a dot, icon or border NEXT to the text. On a tint the text is always the
  * foreground (CI §3.3: "-soft: Text darauf --cd-schwarz, Rand in der
- * Statusfarbe"), so pair `TONE_SOFT` with `TONE_BORDER`. `TONE_TEXT` is for
+ * Statusfarbe"), so pair `TONE_SOFT` with `TONE_BORDER`. `TONE_INK` is for
  * a tone's words on a plain surface (a field error); figures — counts, KPI
  * values, trends — never take it: they stay in the foreground next to a
  * `TONE_DOT`. In dark mode the colours are the `-hell` values and the tints
@@ -26,13 +31,55 @@
  * `tone === "x" ? "…" : "…"` ternaries at every call site.
  */
 export type ToneVariant = "neutral" | "info" | "success" | "warning" | "danger";
+/** Every tone, in severity order (for loops, pickers and validation). */
+export declare const TONE_VARIANTS: readonly ToneVariant[];
+/**
+ * Retired or foreign tone names and the tone each one means. One red and one
+ * amber (CI §3.3): `critical`, `error` and `destructive` are `danger`; there
+ * is no separate severity above it. The names on the left are deprecated:
+ * write the {@link ToneVariant} on the right. The map stays so data written
+ * against an older vocabulary (a widget-shell `critical`, a shadcn
+ * `destructive`) keeps its colour.
+ */
+export declare const TONE_ALIASES: {
+    readonly critical: "danger";
+    readonly error: "danger";
+    readonly destructive: "danger";
+    readonly failure: "danger";
+    readonly warn: "warning";
+    readonly ok: "success";
+    readonly positive: "success";
+    readonly notice: "info";
+    readonly default: "neutral";
+    readonly muted: "neutral";
+    readonly secondary: "neutral";
+};
+/** A name {@link resolveTone} maps onto a tone (see {@link TONE_ALIASES}). */
+export type ToneAlias = keyof typeof TONE_ALIASES;
+/**
+ * What a tone-aware component accepts: a {@link ToneVariant}, or a retired
+ * name that {@link resolveTone} maps onto one.
+ */
+export type ToneName = ToneVariant | ToneAlias;
+/** Whether `value` is one of the five tones (a type guard for data from the wire). */
+export declare function isToneVariant(value: unknown): value is ToneVariant;
+/**
+ * Map any tone name onto the vocabulary: a {@link ToneVariant} as is, a
+ * retired name ({@link TONE_ALIASES}, case-insensitive) onto its tone, and
+ * anything else — unknown, empty, not a string — onto `fallback` (default
+ * `"neutral"`, the tone without a state).
+ */
+export declare function resolveTone(name: unknown, fallback?: ToneVariant): ToneVariant;
 /**
  * Tinted surface + its text (the foreground: CI §3.3) — badges, pills,
  * banners. Pair it with {@link TONE_BORDER}: the rim carries the tone, and in
- * dark mode (no tints) it is all that does.
+ * dark mode (no tints) it is all that does. The neutral tint is the muted
+ * surface, its text the foreground too (a count on it is a figure).
  */
 export declare const TONE_SOFT: Record<ToneVariant, string>;
-/** Solid dot colour — a status dot next to a label. */
+/** The tint alone, for a surface that sets its text itself (a soft KPI card). */
+export declare const TONE_TINT: Record<ToneVariant, string>;
+/** Solid dot colour — a status dot next to a label, a bar, a meter fill. */
 export declare const TONE_DOT: Record<ToneVariant, string>;
 /**
  * The tone's TEXT colour (its `-ink` role) for words on a plain surface — a
@@ -41,6 +88,11 @@ export declare const TONE_DOT: Record<ToneVariant, string>;
  * {@link TONE_ICON} to show the tone. Never on a tint (use {@link TONE_SOFT})
  * and never for figures (they stay in the foreground next to a dot).
  */
+export declare const TONE_INK: Record<ToneVariant, string>;
+/**
+ * @deprecated Renamed to {@link TONE_INK} after the role it maps onto
+ * (`--<tone>-ink`); the same object, kept for existing imports.
+ */
 export declare const TONE_TEXT: Record<ToneVariant, string>;
 /** Border colour in the tone — the rim of a tinted badge, banner or toast. */
 export declare const TONE_BORDER: Record<ToneVariant, string>;

package/dist/lib/tone-utils.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"tone-utils.d.ts","sourceRoot":"","sources":["../../src/lib/tone-utils.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,MAAM,MAAM,WAAW,GAAG,SAAS,GAAG,MAAM,GAAG,SAAS,GAAG,SAAS,GAAG,QAAQ,CAAA;AAE/E;;;;GAIG;AACH,eAAO,MAAM,SAAS,EAAE,MAAM,CAAC,WAAW,EAAE,MAAM,CAMjD,CAAA;AAED,uDAAuD;AACvD,eAAO,MAAM,QAAQ,EAAE,MAAM,CAAC,WAAW,EAAE,MAAM,CAMhD,CAAA;AAED;;;;;;GAMG;AACH,eAAO,MAAM,SAAS,EAAE,MAAM,CAAC,WAAW,EAAE,MAAM,CAMjD,CAAA;AAED,8EAA8E;AAC9E,eAAO,MAAM,WAAW,EAAE,MAAM,CAAC,WAAW,EAAE,MAAM,CAMnD,CAAA;AAED;;;GAGG;AACH,eAAO,MAAM,SAAS,EAAE,MAAM,CAAC,WAAW,EAAE,MAAM,CAMjD,CAAA"}
+{"version":3,"file":"tone-utils.d.ts","sourceRoot":"","sources":["../../src/lib/tone-utils.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AACH,MAAM,MAAM,WAAW,GAAG,SAAS,GAAG,MAAM,GAAG,SAAS,GAAG,SAAS,GAAG,QAAQ,CAAA;AAE/E,yEAAyE;AACzE,eAAO,MAAM,aAAa,EAAE,SAAS,WAAW,EAM/C,CAAA;AAED;;;;;;;GAOG;AACH,eAAO,MAAM,YAAY;;;;;;;;;;;;CAYuB,CAAA;AAEhD,8EAA8E;AAC9E,MAAM,MAAM,SAAS,GAAG,MAAM,OAAO,YAAY,CAAA;AAEjD;;;GAGG;AACH,MAAM,MAAM,QAAQ,GAAG,WAAW,GAAG,SAAS,CAAA;AAI9C,sFAAsF;AACtF,wBAAgB,aAAa,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,WAAW,CAElE;AAED;;;;;GAKG;AACH,wBAAgB,WAAW,CAAC,IAAI,EAAE,OAAO,EAAE,QAAQ,GAAE,WAAuB,GAAG,WAAW,CAKzF;AAED;;;;;GAKG;AACH,eAAO,MAAM,SAAS,EAAE,MAAM,CAAC,WAAW,EAAE,MAAM,CAMjD,CAAA;AAED,iFAAiF;AACjF,eAAO,MAAM,SAAS,EAAE,MAAM,CAAC,WAAW,EAAE,MAAM,CAMjD,CAAA;AAED,4EAA4E;AAC5E,eAAO,MAAM,QAAQ,EAAE,MAAM,CAAC,WAAW,EAAE,MAAM,CAMhD,CAAA;AAED;;;;;;GAMG;AACH,eAAO,MAAM,QAAQ,EAAE,MAAM,CAAC,WAAW,EAAE,MAAM,CAMhD,CAAA;AAED;;;GAGG;AACH,eAAO,MAAM,SAAS,EAAE,MAAM,CAAC,WAAW,EAAE,MAAM,CAAY,CAAA;AAE9D,8EAA8E;AAC9E,eAAO,MAAM,WAAW,EAAE,MAAM,CAAC,WAAW,EAAE,MAAM,CAMnD,CAAA;AAED;;;GAGG;AACH,eAAO,MAAM,SAAS,EAAE,MAAM,CAAC,WAAW,EAAE,MAAM,CAMjD,CAAA"}

package/dist/lib/tone-utils.js

@@ -1,16 +1,73 @@
+/** Every tone, in severity order (for loops, pickers and validation). */
+export const TONE_VARIANTS = [
+    "danger",
+    "warning",
+    "success",
+    "info",
+    "neutral",
+];
+/**
+ * Retired or foreign tone names and the tone each one means. One red and one
+ * amber (CI §3.3): `critical`, `error` and `destructive` are `danger`; there
+ * is no separate severity above it. The names on the left are deprecated:
+ * write the {@link ToneVariant} on the right. The map stays so data written
+ * against an older vocabulary (a widget-shell `critical`, a shadcn
+ * `destructive`) keeps its colour.
+ */
+export const TONE_ALIASES = {
+    critical: "danger",
+    error: "danger",
+    destructive: "danger",
+    failure: "danger",
+    warn: "warning",
+    ok: "success",
+    positive: "success",
+    notice: "info",
+    default: "neutral",
+    muted: "neutral",
+    secondary: "neutral",
+};
+const TONE_SET = new Set(TONE_VARIANTS);
+/** Whether `value` is one of the five tones (a type guard for data from the wire). */
+export function isToneVariant(value) {
+    return typeof value === "string" && TONE_SET.has(value);
+}
+/**
+ * Map any tone name onto the vocabulary: a {@link ToneVariant} as is, a
+ * retired name ({@link TONE_ALIASES}, case-insensitive) onto its tone, and
+ * anything else — unknown, empty, not a string — onto `fallback` (default
+ * `"neutral"`, the tone without a state).
+ */
+export function resolveTone(name, fallback = "neutral") {
+    if (typeof name !== "string")
+        return fallback;
+    const key = name.trim().toLowerCase();
+    if (TONE_SET.has(key))
+        return key;
+    return Object.hasOwn(TONE_ALIASES, key) ? TONE_ALIASES[key] : fallback;
+}
 /**
  * Tinted surface + its text (the foreground: CI §3.3) — badges, pills,
  * banners. Pair it with {@link TONE_BORDER}: the rim carries the tone, and in
- * dark mode (no tints) it is all that does.
+ * dark mode (no tints) it is all that does. The neutral tint is the muted
+ * surface, its text the foreground too (a count on it is a figure).
  */
 export const TONE_SOFT = {
-    neutral: "bg-muted text-muted-foreground",
+    neutral: "bg-muted text-foreground",
     info: "bg-info-soft text-foreground",
     success: "bg-success-soft text-foreground",
     warning: "bg-warning-soft text-foreground",
     danger: "bg-danger-soft text-foreground",
 };
-/** Solid dot colour — a status dot next to a label. */
+/** The tint alone, for a surface that sets its text itself (a soft KPI card). */
+export const TONE_TINT = {
+    neutral: "bg-muted",
+    info: "bg-info-soft",
+    success: "bg-success-soft",
+    warning: "bg-warning-soft",
+    danger: "bg-danger-soft",
+};
+/** Solid dot colour — a status dot next to a label, a bar, a meter fill. */
 export const TONE_DOT = {
     neutral: "bg-muted-foreground",
     info: "bg-info",
@@ -25,13 +82,18 @@ export const TONE_DOT = {
  * {@link TONE_ICON} to show the tone. Never on a tint (use {@link TONE_SOFT})
  * and never for figures (they stay in the foreground next to a dot).
  */
-export const TONE_TEXT = {
+export const TONE_INK = {
     neutral: "text-foreground",
     info: "text-info-ink",
     success: "text-success-ink",
     warning: "text-warning-ink",
     danger: "text-danger-ink",
 };
+/**
+ * @deprecated Renamed to {@link TONE_INK} after the role it maps onto
+ * (`--<tone>-ink`); the same object, kept for existing imports.
+ */
+export const TONE_TEXT = TONE_INK;
 /** Border colour in the tone — the rim of a tinted badge, banner or toast. */
 export const TONE_BORDER = {
     neutral: "border-border",

package/dist/lib/tone-utils.js.map

@@ -1 +1 @@
-{"version":3,"file":"tone-utils.js","sourceRoot":"","sources":["../../src/lib/tone-utils.ts"],"names":[],"mappings":"AA6BA;;;;GAIG;AACH,MAAM,CAAC,MAAM,SAAS,GAAgC;IACpD,OAAO,EAAE,gCAAgC;IACzC,IAAI,EAAE,8BAA8B;IACpC,OAAO,EAAE,iCAAiC;IAC1C,OAAO,EAAE,iCAAiC;IAC1C,MAAM,EAAE,gCAAgC;CACzC,CAAA;AAED,uDAAuD;AACvD,MAAM,CAAC,MAAM,QAAQ,GAAgC;IACnD,OAAO,EAAE,qBAAqB;IAC9B,IAAI,EAAE,SAAS;IACf,OAAO,EAAE,YAAY;IACrB,OAAO,EAAE,YAAY;IACrB,MAAM,EAAE,WAAW;CACpB,CAAA;AAED;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,SAAS,GAAgC;IACpD,OAAO,EAAE,iBAAiB;IAC1B,IAAI,EAAE,eAAe;IACrB,OAAO,EAAE,kBAAkB;IAC3B,OAAO,EAAE,kBAAkB;IAC3B,MAAM,EAAE,iBAAiB;CAC1B,CAAA;AAED,8EAA8E;AAC9E,MAAM,CAAC,MAAM,WAAW,GAAgC;IACtD,OAAO,EAAE,eAAe;IACxB,IAAI,EAAE,aAAa;IACnB,OAAO,EAAE,gBAAgB;IACzB,OAAO,EAAE,gBAAgB;IACzB,MAAM,EAAE,eAAe;CACxB,CAAA;AAED;;;GAGG;AACH,MAAM,CAAC,MAAM,SAAS,GAAgC;IACpD,OAAO,EAAE,uBAAuB;IAChC,IAAI,EAAE,WAAW;IACjB,OAAO,EAAE,cAAc;IACvB,OAAO,EAAE,cAAc;IACvB,MAAM,EAAE,aAAa;CACtB,CAAA"}
+{"version":3,"file":"tone-utils.js","sourceRoot":"","sources":["../../src/lib/tone-utils.ts"],"names":[],"mappings":"AAkCA,yEAAyE;AACzE,MAAM,CAAC,MAAM,aAAa,GAA2B;IACnD,QAAQ;IACR,SAAS;IACT,SAAS;IACT,MAAM;IACN,SAAS;CACV,CAAA;AAED;;;;;;;GAOG;AACH,MAAM,CAAC,MAAM,YAAY,GAAG;IAC1B,QAAQ,EAAE,QAAQ;IAClB,KAAK,EAAE,QAAQ;IACf,WAAW,EAAE,QAAQ;IACrB,OAAO,EAAE,QAAQ;IACjB,IAAI,EAAE,SAAS;IACf,EAAE,EAAE,SAAS;IACb,QAAQ,EAAE,SAAS;IACnB,MAAM,EAAE,MAAM;IACd,OAAO,EAAE,SAAS;IAClB,KAAK,EAAE,SAAS;IAChB,SAAS,EAAE,SAAS;CAC0B,CAAA;AAWhD,MAAM,QAAQ,GAAwB,IAAI,GAAG,CAAC,aAAa,CAAC,CAAA;AAE5D,sFAAsF;AACtF,MAAM,UAAU,aAAa,CAAC,KAAc;IAC1C,OAAO,OAAO,KAAK,KAAK,QAAQ,IAAI,QAAQ,CAAC,GAAG,CAAC,KAAK,CAAC,CAAA;AACzD,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,WAAW,CAAC,IAAa,EAAE,WAAwB,SAAS;IAC1E,IAAI,OAAO,IAAI,KAAK,QAAQ;QAAE,OAAO,QAAQ,CAAA;IAC7C,MAAM,GAAG,GAAG,IAAI,CAAC,IAAI,EAAE,CAAC,WAAW,EAAE,CAAA;IACrC,IAAI,QAAQ,CAAC,GAAG,CAAC,GAAG,CAAC;QAAE,OAAO,GAAkB,CAAA;IAChD,OAAO,MAAM,CAAC,MAAM,CAAC,YAAY,EAAE,GAAG,CAAC,CAAC,CAAC,CAAC,YAAY,CAAC,GAAgB,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAA;AACrF,CAAC;AAED;;;;;GAKG;AACH,MAAM,CAAC,MAAM,SAAS,GAAgC;IACpD,OAAO,EAAE,0BAA0B;IACnC,IAAI,EAAE,8BAA8B;IACpC,OAAO,EAAE,iCAAiC;IAC1C,OAAO,EAAE,iCAAiC;IAC1C,MAAM,EAAE,gCAAgC;CACzC,CAAA;AAED,iFAAiF;AACjF,MAAM,CAAC,MAAM,SAAS,GAAgC;IACpD,OAAO,EAAE,UAAU;IACnB,IAAI,EAAE,cAAc;IACpB,OAAO,EAAE,iBAAiB;IAC1B,OAAO,EAAE,iBAAiB;IAC1B,MAAM,EAAE,gBAAgB;CACzB,CAAA;AAED,4EAA4E;AAC5E,MAAM,CAAC,MAAM,QAAQ,GAAgC;IACnD,OAAO,EAAE,qBAAqB;IAC9B,IAAI,EAAE,SAAS;IACf,OAAO,EAAE,YAAY;IACrB,OAAO,EAAE,YAAY;IACrB,MAAM,EAAE,WAAW;CACpB,CAAA;AAED;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,QAAQ,GAAgC;IACnD,OAAO,EAAE,iBAAiB;IAC1B,IAAI,EAAE,eAAe;IACrB,OAAO,EAAE,kBAAkB;IAC3B,OAAO,EAAE,kBAAkB;IAC3B,MAAM,EAAE,iBAAiB;CAC1B,CAAA;AAED;;;GAGG;AACH,MAAM,CAAC,MAAM,SAAS,GAAgC,QAAQ,CAAA;AAE9D,8EAA8E;AAC9E,MAAM,CAAC,MAAM,WAAW,GAAgC;IACtD,OAAO,EAAE,eAAe;IACxB,IAAI,EAAE,aAAa;IACnB,OAAO,EAAE,gBAAgB;IACzB,OAAO,EAAE,gBAAgB;IACzB,MAAM,EAAE,eAAe;CACxB,CAAA;AAED;;;GAGG;AACH,MAAM,CAAC,MAAM,SAAS,GAAgC;IACpD,OAAO,EAAE,uBAAuB;IAChC,IAAI,EAAE,WAAW;IACjB,OAAO,EAAE,cAAc;IACvB,OAAO,EAAE,cAAc;IACvB,MAAM,EAAE,aAAa;CACtB,CAAA"}

package/dist/lib/tool-query.d.ts

@@ -0,0 +1,107 @@
+/**
+ * The plain logic behind `useToolQuery`, `useViewToolQuery`, `useViewData`
+ * and `useToolMutation` (toolkit#176 K18): the effective cache key and its
+ * collision guard, the opt-in retry policy for tool errors, the TanStack
+ * options a tool query runs with, and per-call mutation callbacks that fire
+ * for EVERY call. No React, no `mcp-use/react`, so it is unit-tested without
+ * a renderer.
+ */
+import { type MutateOptions, type MutationFunctionContext, type QueryClient, type UseQueryOptions } from "@tanstack/react-query";
+/** A `(name, args)` tool caller — the shape of `useCallTool()` and `HostBridge.callTool`. */
+export type ToolCaller = (name: string, args: object) => Promise<unknown>;
+/**
+ * TanStack query options a tool query passes through: everything except the
+ * key and the fetcher, which the hooks build from the tool and its args
+ * (`retry`, `retryDelay`, `staleTime`, `placeholderData` / `keepPreviousData`,
+ * `initialData` + `initialDataUpdatedAt`, `enabled`, `select`, …).
+ */
+export type UseToolQueryOptions<TData = unknown, TSelected = TData> = Omit<UseQueryOptions<TData, Error, TSelected>, "queryKey" | "queryFn">;
+/**
+ * Neither an `AppQueryProvider` `callTool` nor a `HostBridgeProvider` is in
+ * reach, so the query cannot call any tool. Never retried: nothing changes
+ * until the mount does.
+ */
+export declare class NoToolTransportError extends Error {
+    constructor(toolName: string);
+}
+/** Retries {@link shouldRetryToolCall} grants a failed transport (TanStack's own default count). */
+export declare const TOOL_QUERY_RETRIES = 3;
+/**
+ * A retry policy for tool queries: up to {@link TOOL_QUERY_RETRIES} retries
+ * for a failed transport, none for a tool's own `isError` answer
+ * (`isToolError`) or a missing transport — repeating a deterministic answer
+ * only repeats it and holds the error back about 7 s.
+ *
+ * Opt-in in 2.x (the hooks keep the client's `retry`, TanStack's 3 by
+ * default, because a tool may also answer a transient failure with
+ * `isError`): pass `retry: shouldRetryToolCall` to a hook, or set it as the
+ * client's default (`queryClient.setDefaultOptions`, or an `AppQueryProvider`
+ * `client` of your own).
+ */
+export declare function shouldRetryToolCall(failureCount: number, error: unknown): boolean;
+/**
+ * The effective cache key of a tool query (toolkit#176 K18).
+ *
+ * - 2.x default: the caller's key, then the args (`[...queryKey, args]`), so
+ *   two callers sharing a key with different args get separate entries.
+ * - `toolNameInKey`: the caller's key, the tool name, then the args
+ *   (`[...queryKey, toolName, args]`), so two tools never share an entry,
+ *   whatever key their callers pass. Opt-in in 2.x (`AppQueryProvider` /
+ *   `McpAppView` `toolNameInQueryKey`), the default from the next major.
+ *
+ * Build exact keys (`getQueryData`, `setQueryData`, `cancelQueries` with
+ * `exact: true`) with this helper, or with `useToolQueryKey`, which reads the
+ * provider's setting, rather than by hand: code that goes through them keeps
+ * working when the default changes. Prefix invalidation by `queryKey`
+ * matches either way.
+ */
+export declare function toolQueryKey(queryKey: readonly unknown[], toolName: string, args: object, toolNameInKey?: boolean): unknown[];
+/**
+ * Claim the cache key `keyId` (`hashKey` of a {@link toolQueryKey}) for
+ * `toolName` on `client`. Returns the tool that held it
+ * before when that is ANOTHER tool — a collision the hooks report — else
+ * `null`. The latest claim wins, so each collision is reported once per
+ * switch.
+ */
+export declare function claimToolQueryKey(client: QueryClient, keyId: string, toolName: string): string | null;
+/** The console line for a {@link claimToolQueryKey} collision. */
+export declare function toolKeyCollisionMessage(keyId: string, toolName: string, previous: string): string;
+/** How {@link toolQueryOptions} decodes a result and builds the key. */
+export interface ToolQueryBuild<TData> {
+    /** Decodes the tool result. Default: `parseToolResult` (structured-first). */
+    decode?: (result: unknown) => TData;
+    /** Put the tool name into the key (see {@link toolQueryKey}). Default `false`. */
+    toolNameInKey?: boolean;
+}
+/**
+ * The TanStack options of a tool query: the caller's options, the
+ * {@link toolQueryKey} and a fetcher that calls `toolName` and decodes the
+ * result. `retry` stays the caller's, else the client's default; only a
+ * missing transport is never retried. Without a transport the fetcher fails
+ * with {@link NoToolTransportError} instead of leaving the query idle.
+ */
+export declare function toolQueryOptions<TData, TSelected = TData>(queryKey: readonly unknown[], toolName: string, args: object, callTool: ToolCaller | undefined, opts?: UseToolQueryOptions<TData, TSelected>, build?: ToolQueryBuild<TData>): UseQueryOptions<TData, Error, TSelected>;
+/**
+ * Seed `queryKey` with host-delivered `seed`: written when the entry is
+ * empty, or when the seed is a payload this client has not seeded for the
+ * key before (a new delivery). Returns whether the cache was written.
+ */
+export declare function seedToolQuery(client: QueryClient, queryKey: readonly unknown[], seed: unknown, updatedAt?: number): boolean;
+/** Callbacks of one `mutate` call, typed as TanStack's per-call options. */
+export type PerCallCallbacks<TData, TVariables> = MutateOptions<TData, Error, TVariables, unknown>;
+/**
+ * Fire one call's per-call `onSuccess` / `onError` / `onSettled` once `call`
+ * settles — for EVERY call. TanStack's own `mutate` keeps only the latest
+ * call's callbacks, so two quick calls (retrying two incidents in a row)
+ * would confirm only the second. `context()` is read when the call settles:
+ * `null` (the component unmounted) skips the callbacks, as TanStack does.
+ * A rejected `call` is handled here, never left unhandled.
+ */
+export declare function settleEachCall<TData, TVariables>(call: Promise<TData>, variables: TVariables, callbacks: PerCallCallbacks<TData, TVariables> | undefined, context: () => MutationFunctionContext | null): void;
+/**
+ * Invalidate the query keys (prefixes) a mutation names: matching ACTIVE
+ * queries refetch now, inactive ones are only marked stale and refetch when
+ * they are next used — never a refetch of every inactive cached page.
+ */
+export declare function invalidateToolQueries(client: QueryClient, keys: readonly (readonly unknown[])[] | undefined): Promise<void>;
+//# sourceMappingURL=tool-query.d.ts.map

package/dist/lib/tool-query.d.ts.map

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

package/dist/lib/tool-query.js

@@ -0,0 +1,182 @@
+/**
+ * The plain logic behind `useToolQuery`, `useViewToolQuery`, `useViewData`
+ * and `useToolMutation` (toolkit#176 K18): the effective cache key and its
+ * collision guard, the opt-in retry policy for tool errors, the TanStack
+ * options a tool query runs with, and per-call mutation callbacks that fire
+ * for EVERY call. No React, no `mcp-use/react`, so it is unit-tested without
+ * a renderer.
+ */
+import { hashKey, } from "@tanstack/react-query";
+import { isToolError, parseToolResult } from "./parse-tool-result.js";
+/**
+ * Neither an `AppQueryProvider` `callTool` nor a `HostBridgeProvider` is in
+ * reach, so the query cannot call any tool. Never retried: nothing changes
+ * until the mount does.
+ */
+export class NoToolTransportError extends Error {
+    constructor(toolName) {
+        super(`[mcp-toolkit] cannot call "${toolName}": no tool transport. Mount the widget under ` +
+            "AppQueryProvider with callTool, or a HostBridgeProvider.");
+        this.name = "NoToolTransportError";
+    }
+}
+/** Retries {@link shouldRetryToolCall} grants a failed transport (TanStack's own default count). */
+export const TOOL_QUERY_RETRIES = 3;
+/**
+ * A retry policy for tool queries: up to {@link TOOL_QUERY_RETRIES} retries
+ * for a failed transport, none for a tool's own `isError` answer
+ * (`isToolError`) or a missing transport — repeating a deterministic answer
+ * only repeats it and holds the error back about 7 s.
+ *
+ * Opt-in in 2.x (the hooks keep the client's `retry`, TanStack's 3 by
+ * default, because a tool may also answer a transient failure with
+ * `isError`): pass `retry: shouldRetryToolCall` to a hook, or set it as the
+ * client's default (`queryClient.setDefaultOptions`, or an `AppQueryProvider`
+ * `client` of your own).
+ */
+export function shouldRetryToolCall(failureCount, error) {
+    if (isToolError(error) || error instanceof NoToolTransportError)
+        return false;
+    return failureCount < TOOL_QUERY_RETRIES;
+}
+/**
+ * The effective cache key of a tool query (toolkit#176 K18).
+ *
+ * - 2.x default: the caller's key, then the args (`[...queryKey, args]`), so
+ *   two callers sharing a key with different args get separate entries.
+ * - `toolNameInKey`: the caller's key, the tool name, then the args
+ *   (`[...queryKey, toolName, args]`), so two tools never share an entry,
+ *   whatever key their callers pass. Opt-in in 2.x (`AppQueryProvider` /
+ *   `McpAppView` `toolNameInQueryKey`), the default from the next major.
+ *
+ * Build exact keys (`getQueryData`, `setQueryData`, `cancelQueries` with
+ * `exact: true`) with this helper, or with `useToolQueryKey`, which reads the
+ * provider's setting, rather than by hand: code that goes through them keeps
+ * working when the default changes. Prefix invalidation by `queryKey`
+ * matches either way.
+ */
+export function toolQueryKey(queryKey, toolName, args, toolNameInKey = false) {
+    return toolNameInKey ? [...queryKey, toolName, args] : [...queryKey, args];
+}
+/**
+ * The tool that last claimed each cache key, per client — the guard against
+ * two tools sharing one entry (their answers would overwrite each other).
+ */
+const keyOwners = new WeakMap();
+/**
+ * Claim the cache key `keyId` (`hashKey` of a {@link toolQueryKey}) for
+ * `toolName` on `client`. Returns the tool that held it
+ * before when that is ANOTHER tool — a collision the hooks report — else
+ * `null`. The latest claim wins, so each collision is reported once per
+ * switch.
+ */
+export function claimToolQueryKey(client, keyId, toolName) {
+    const owners = keyOwners.get(client) ?? new Map();
+    keyOwners.set(client, owners);
+    const previous = owners.get(keyId);
+    owners.set(keyId, toolName);
+    return previous !== undefined && previous !== toolName ? previous : null;
+}
+/** The console line for a {@link claimToolQueryKey} collision. */
+export function toolKeyCollisionMessage(keyId, toolName, previous) {
+    return (`[mcp-toolkit] the query key ${keyId} is used by "${previous}" and "${toolName}": ` +
+        "both share one cache entry and overwrite each other's answer. Give each tool its own queryKey.");
+}
+/**
+ * The TanStack options of a tool query: the caller's options, the
+ * {@link toolQueryKey} and a fetcher that calls `toolName` and decodes the
+ * result. `retry` stays the caller's, else the client's default; only a
+ * missing transport is never retried. Without a transport the fetcher fails
+ * with {@link NoToolTransportError} instead of leaving the query idle.
+ */
+export function toolQueryOptions(queryKey, toolName, args, callTool, opts, build = {}) {
+    const decode = build.decode ?? ((result) => parseToolResult(result));
+    return {
+        ...opts,
+        // An omitted `retry` must stay omitted: an explicit `undefined` would
+        // shadow the client's default.
+        ...(callTool ? null : { retry: false }),
+        queryKey: toolQueryKey(queryKey, toolName, args, build.toolNameInKey),
+        queryFn: async () => {
+            if (!callTool)
+                throw new NoToolTransportError(toolName);
+            return decode(await callTool(toolName, args));
+        },
+    };
+}
+/**
+ * The content of the payload last seeded per query key, per client: a
+ * remounted or re-rendered OLD payload must not roll a refetched answer
+ * back, while a payload not seeded before is a new delivery and wins.
+ */
+const lastSeeded = new WeakMap();
+function contentOf(value) {
+    try {
+        return JSON.stringify(value);
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * Seed `queryKey` with host-delivered `seed`: written when the entry is
+ * empty, or when the seed is a payload this client has not seeded for the
+ * key before (a new delivery). Returns whether the cache was written.
+ */
+export function seedToolQuery(client, queryKey, seed, updatedAt) {
+    const keyId = hashKey(queryKey);
+    const seeded = lastSeeded.get(client) ?? new Map();
+    lastSeeded.set(client, seeded);
+    const content = contentOf(seed);
+    const delivered = content === undefined || seeded.get(keyId) !== content;
+    if (content !== undefined)
+        seeded.set(keyId, content);
+    if (!delivered && client.getQueryData(queryKey) !== undefined)
+        return false;
+    client.setQueryData(queryKey, seed, updatedAt === undefined ? undefined : { updatedAt });
+    return true;
+}
+function settle(run) {
+    try {
+        run();
+    }
+    catch (err) {
+        // Surface a throwing callback as an unhandled rejection, as TanStack
+        // does, without skipping the callbacks after it.
+        void Promise.reject(err instanceof Error ? err : new Error(String(err)));
+    }
+}
+/**
+ * Fire one call's per-call `onSuccess` / `onError` / `onSettled` once `call`
+ * settles — for EVERY call. TanStack's own `mutate` keeps only the latest
+ * call's callbacks, so two quick calls (retrying two incidents in a row)
+ * would confirm only the second. `context()` is read when the call settles:
+ * `null` (the component unmounted) skips the callbacks, as TanStack does.
+ * A rejected `call` is handled here, never left unhandled.
+ */
+export function settleEachCall(call, variables, callbacks, context) {
+    call.then((data) => {
+        const ctx = callbacks ? context() : null;
+        if (!callbacks || !ctx)
+            return;
+        settle(() => callbacks.onSuccess?.(data, variables, undefined, ctx));
+        settle(() => callbacks.onSettled?.(data, null, variables, undefined, ctx));
+    }, (error) => {
+        const ctx = callbacks ? context() : null;
+        if (!callbacks || !ctx)
+            return;
+        settle(() => callbacks.onError?.(error, variables, undefined, ctx));
+        settle(() => callbacks.onSettled?.(undefined, error, variables, undefined, ctx));
+    });
+}
+/**
+ * Invalidate the query keys (prefixes) a mutation names: matching ACTIVE
+ * queries refetch now, inactive ones are only marked stale and refetch when
+ * they are next used — never a refetch of every inactive cached page.
+ */
+export async function invalidateToolQueries(client, keys) {
+    if (!keys)
+        return;
+    await Promise.all(keys.map((queryKey) => client.invalidateQueries({ queryKey })));
+}
+//# sourceMappingURL=tool-query.js.map

package/dist/lib/tool-query.js.map

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

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

@@ -0,0 +1,108 @@
+/**
+ * A passive observer of the MCP Apps (SEP-1865) host → view lifecycle
+ * notifications, read straight off the postMessage channel the view runtime
+ * itself listens on (toolkit#176 K13, N21).
+ *
+ * mcp-use 2.x latches only a result WITH `structuredContent` (or an
+ * `isError`); a content-only result, which claude.ai and Claude Desktop send,
+ * leaves its status `"pending"` forever, and its tool input merges partial and
+ * complete arguments into one field. Watching the notifications themselves
+ * tells the three cases apart that the latch cannot:
+ *
+ * - the host delivered a STRIPPED result (re-run the tool now, with the
+ *   complete arguments it was called with),
+ * - the host delivered a structured result (the latch follows; never re-run),
+ * - nothing arrived yet (a slow tool on a compliant host: keep waiting).
+ *
+ * The last case is only certain when the observer was listening before the
+ * host answered `ui/initialize` ({@link ToolObservation.sawHandshake}): hosts
+ * send the lifecycle notifications after the handshake, so an observer that
+ * saw it has seen everything sent so far. `mountMcpToolkitApp` installs it
+ * ahead of `bootstrapView` for exactly that reason.
+ *
+ * Read-only: it never sends, never answers and never stops a message.
+ */
+/** What the host's `ui/notifications/tool-result` carried. */
+export type ObservedToolResult = "none" | "structured" | "stripped" | "error";
+/** Everything the observer learned about the rendering call so far. */
+export interface ToolObservation {
+    /**
+     * The observer saw the host answer `ui/initialize`, so it was listening
+     * before any lifecycle notification could be sent: a result it has not
+     * seen has not been delivered yet.
+     */
+    sawHandshake: boolean;
+    /**
+     * The arguments of the complete `ui/notifications/tool-input` — never a
+     * partial stream (`tool-input-partial` is ignored). `undefined` until it
+     * arrived.
+     */
+    completeInput: Record<string, unknown> | undefined;
+    /** What the first `ui/notifications/tool-result` carried. */
+    result: ObservedToolResult;
+    /** The host sent `ui/notifications/tool-cancelled`. */
+    cancelled: boolean;
+}
+export declare const EMPTY_TOOL_OBSERVATION: ToolObservation;
+/** A host → view message the observer acts on. */
+export type HostLifecycleMessage = {
+    kind: "handshake";
+} | {
+    kind: "tool-input";
+    arguments: Record<string, unknown>;
+} | {
+    kind: "tool-result";
+    result: Exclude<ObservedToolResult, "none">;
+} | {
+    kind: "tool-cancelled";
+};
+/**
+ * Classify a tool-result notification the way mcp-use 2.x's latch does: an
+ * `isError` result is an error, a result with `structuredContent` (even
+ * `null`) latches as ready, and anything else is the stripped, content-only
+ * result the latch ignores.
+ */
+export declare function classifyToolResult(params: Record<string, unknown>): Exclude<ObservedToolResult, "none">;
+/**
+ * Decode one postMessage payload into the lifecycle message it is, or `null`
+ * for anything else (other methods, requests, responses, foreign traffic).
+ */
+export declare function classifyHostMessage(data: unknown): HostLifecycleMessage | null;
+/**
+ * Fold one message into the observation. Like the mcp-use latch, the call
+ * settles once: after its result or cancellation, later inputs, results and
+ * cancellations change nothing.
+ */
+export declare function reduceToolObservation(state: ToolObservation, message: HostLifecycleMessage): ToolObservation;
+/** The `window` slice the observer listens on (any `EventTarget`, e.g. in tests). */
+export interface MessageEventSource {
+    addEventListener(type: "message", listener: (event: Event) => void): void;
+    removeEventListener(type: "message", listener: (event: Event) => void): void;
+}
+/** A subscribable observation, shaped for `useSyncExternalStore`. */
+export interface ToolResultObserver {
+    subscribe: (listener: () => void) => () => void;
+    getSnapshot: () => ToolObservation;
+    /** Stop listening; the last observation stays readable. */
+    dispose: () => void;
+}
+/**
+ * Observe the lifecycle notifications arriving on `source`. `accept` filters
+ * the events (the view accepts only its host: `event.source === window.parent`,
+ * the same check the ext-apps transport makes).
+ */
+export declare function createToolResultObserver(source: MessageEventSource, accept?: (event: MessageEvent) => boolean): ToolResultObserver;
+/**
+ * The view document's observer: installed once and kept for the document's
+ * lifetime (one document renders one view). `null` outside a browser and in
+ * a top-level window, where no host frames the view.
+ *
+ * It must listen before the view runtime connects, so it sees the
+ * handshake. This module therefore installs it as the bundle evaluates
+ * (below), ahead of any `bootstrapView` call in the entry module, whatever
+ * the mount; `mountMcpToolkitApp` calls it again (idempotent). Installed any
+ * later, it still sees what arrives afterwards, and the recovery falls back
+ * to its grace timer for the rest.
+ */
+export declare function installToolResultObserver(): ToolResultObserver | null;
+//# sourceMappingURL=tool-result-observer.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"tool-result-observer.d.ts","sourceRoot":"","sources":["../../src/lib/tool-result-observer.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAEH,8DAA8D;AAC9D,MAAM,MAAM,kBAAkB,GAAG,MAAM,GAAG,YAAY,GAAG,UAAU,GAAG,OAAO,CAAA;AAE7E,uEAAuE;AACvE,MAAM,WAAW,eAAe;IAC9B;;;;OAIG;IACH,YAAY,EAAE,OAAO,CAAA;IACrB;;;;OAIG;IACH,aAAa,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,SAAS,CAAA;IAClD,6DAA6D;IAC7D,MAAM,EAAE,kBAAkB,CAAA;IAC1B,uDAAuD;IACvD,SAAS,EAAE,OAAO,CAAA;CACnB;AAED,eAAO,MAAM,sBAAsB,EAAE,eAKnC,CAAA;AAEF,kDAAkD;AAClD,MAAM,MAAM,oBAAoB,GAC5B;IAAE,IAAI,EAAE,WAAW,CAAA;CAAE,GACrB;IAAE,IAAI,EAAE,YAAY,CAAC;IAAC,SAAS,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;CAAE,GAC1D;IAAE,IAAI,EAAE,aAAa,CAAC;IAAC,MAAM,EAAE,OAAO,CAAC,kBAAkB,EAAE,MAAM,CAAC,CAAA;CAAE,GACpE;IAAE,IAAI,EAAE,gBAAgB,CAAA;CAAE,CAAA;AAM9B;;;;;GAKG;AACH,wBAAgB,kBAAkB,CAChC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAC9B,OAAO,CAAC,kBAAkB,EAAE,MAAM,CAAC,CAGrC;AAUD;;;GAGG;AACH,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,OAAO,GAAG,oBAAoB,GAAG,IAAI,CAmB9E;AAED;;;;GAIG;AACH,wBAAgB,qBAAqB,CACnC,KAAK,EAAE,eAAe,EACtB,OAAO,EAAE,oBAAoB,GAC5B,eAAe,CAajB;AAED,qFAAqF;AACrF,MAAM,WAAW,kBAAkB;IACjC,gBAAgB,CAAC,IAAI,EAAE,SAAS,EAAE,QAAQ,EAAE,CAAC,KAAK,EAAE,KAAK,KAAK,IAAI,GAAG,IAAI,CAAA;IACzE,mBAAmB,CAAC,IAAI,EAAE,SAAS,EAAE,QAAQ,EAAE,CAAC,KAAK,EAAE,KAAK,KAAK,IAAI,GAAG,IAAI,CAAA;CAC7E;AAED,qEAAqE;AACrE,MAAM,WAAW,kBAAkB;IACjC,SAAS,EAAE,CAAC,QAAQ,EAAE,MAAM,IAAI,KAAK,MAAM,IAAI,CAAA;IAC/C,WAAW,EAAE,MAAM,eAAe,CAAA;IAClC,2DAA2D;IAC3D,OAAO,EAAE,MAAM,IAAI,CAAA;CACpB;AAED;;;;GAIG;AACH,wBAAgB,wBAAwB,CACtC,MAAM,EAAE,kBAAkB,EAC1B,MAAM,GAAE,CAAC,KAAK,EAAE,YAAY,KAAK,OAAoB,GACpD,kBAAkB,CA2BpB;AAID;;;;;;;;;;;GAWG;AACH,wBAAgB,yBAAyB,IAAI,kBAAkB,GAAG,IAAI,CAMrE"}