@miragon/mcp-toolkit-ui 2.6.0 → 2.8.0

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"}

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

@@ -0,0 +1,158 @@
+/**
+ * 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.
+ */
+export const EMPTY_TOOL_OBSERVATION = Object.freeze({
+    sawHandshake: false,
+    completeInput: undefined,
+    result: "none",
+    cancelled: false,
+});
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+/**
+ * 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 function classifyToolResult(params) {
+    if (params.isError === true)
+        return "error";
+    return params.structuredContent === undefined ? "stripped" : "structured";
+}
+/** The host's answer to `ui/initialize`: a response carrying its capabilities or protocol version. */
+function isHandshakeResponse(message) {
+    if (!("id" in message) || !isRecord(message.result))
+        return false;
+    return (isRecord(message.result.hostCapabilities) || typeof message.result.protocolVersion === "string");
+}
+/**
+ * Decode one postMessage payload into the lifecycle message it is, or `null`
+ * for anything else (other methods, requests, responses, foreign traffic).
+ */
+export function classifyHostMessage(data) {
+    if (!isRecord(data) || data.jsonrpc !== "2.0")
+        return null;
+    if (typeof data.method !== "string") {
+        return isHandshakeResponse(data) ? { kind: "handshake" } : null;
+    }
+    const params = isRecord(data.params) ? data.params : {};
+    switch (data.method) {
+        case "ui/notifications/tool-input":
+            return {
+                kind: "tool-input",
+                arguments: isRecord(params.arguments) ? params.arguments : {},
+            };
+        case "ui/notifications/tool-result":
+            return { kind: "tool-result", result: classifyToolResult(params) };
+        case "ui/notifications/tool-cancelled":
+            return { kind: "tool-cancelled" };
+        default:
+            return 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 function reduceToolObservation(state, message) {
+    if (message.kind === "handshake") {
+        return state.sawHandshake ? state : { ...state, sawHandshake: true };
+    }
+    if (state.result !== "none" || state.cancelled)
+        return state;
+    switch (message.kind) {
+        case "tool-input":
+            return { ...state, completeInput: message.arguments };
+        case "tool-result":
+            return { ...state, result: message.result };
+        case "tool-cancelled":
+            return { ...state, cancelled: true };
+    }
+}
+/**
+ * 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 function createToolResultObserver(source, accept = () => true) {
+    let snapshot = EMPTY_TOOL_OBSERVATION;
+    const listeners = new Set();
+    const onMessage = (received) => {
+        // Only `message` events are subscribed: each one is a MessageEvent.
+        const event = received;
+        if (!accept(event))
+            return;
+        const message = classifyHostMessage(event.data);
+        if (!message)
+            return;
+        const next = reduceToolObservation(snapshot, message);
+        if (next === snapshot)
+            return;
+        snapshot = next;
+        for (const listener of [...listeners])
+            listener();
+    };
+    source.addEventListener("message", onMessage);
+    return {
+        subscribe: (listener) => {
+            listeners.add(listener);
+            return () => {
+                listeners.delete(listener);
+            };
+        },
+        getSnapshot: () => snapshot,
+        dispose: () => {
+            source.removeEventListener("message", onMessage);
+        },
+    };
+}
+let documentObserver = null;
+/**
+ * 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 function installToolResultObserver() {
+    if (documentObserver)
+        return documentObserver;
+    if (typeof window === "undefined" || window.parent === window)
+        return null;
+    const host = window.parent;
+    documentObserver = createToolResultObserver(window, (event) => event.source === host);
+    return documentObserver;
+}
+// Listen from the moment the view bundle evaluates (a passive listener; a
+// no-op outside a framed browser document).
+installToolResultObserver();
+//# sourceMappingURL=tool-result-observer.js.map

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

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

package/dist/lib/typography.d.ts

@@ -0,0 +1,37 @@
+/**
+ * The type scale of the kit (modeler-tool-design §4, adapted for embedded
+ * widgets): five steps, each a role in `theme.css` (`--text-<step>` with its
+ * line height and weight) and a Tailwind utility of the same name.
+ *
+ * | Step      | Utility        | Size / weight / line height | Use                                        |
+ * | --------- | -------------- | --------------------------- | ------------------------------------------ |
+ * | `title`   | `text-title`   | 28 px / 700 / 1.2           | page title (the CI h2; a widget has no h1 40 px) |
+ * | `section` | `text-section` | 21 px / 600 / 1.3           | section title (CI h3)                      |
+ * | `body`    | `text-body`    | 16 px / 400 / 1.6           | running text: state and toast descriptions |
+ * | `dense`   | `text-dense`   | 14 px / 400 / 1.5           | dense tables and controls (inputs, chips, count pills, the inline alert box): the documented product exception, never running text |
+ * | `small`   | `text-small`   | 13 px / 400 / 1.5           | captions, labels, hints, meta rows: the FLOOR |
+ *
+ * Nothing renders below 13 px — no `text-xs` (12 px), no `text-[10px]`
+ * micro-labels (`examples/test/design-system.test.ts` enforces it). A label
+ * that used to be a 10–11 px uppercase caption is {@link MICRO_LABEL}: 13 px,
+ * semibold, normal case.
+ *
+ * Combine the utilities through the kit's `cn`: plain tailwind-merge does not
+ * know these sizes and would drop `text-small` next to a text colour.
+ */
+/** The five steps, smallest last. */
+export declare const TYPE_STEPS: readonly ["title", "section", "body", "dense", "small"];
+/** One step of the type scale. */
+export type TypeStep = (typeof TYPE_STEPS)[number];
+/** The utility class per step (`TYPE_SCALE.small` → `"text-small"`). */
+export declare const TYPE_SCALE: Readonly<Record<TypeStep, `text-${TypeStep}`>>;
+/** The smallest text the kit renders, in CSS px (CI §4 "klein"). */
+export declare const TYPE_FLOOR_PX = 13;
+/**
+ * A caption above a value or a column: table heads, KPI labels, group
+ * labels. 13 px semibold in normal case — the CI floor, where these used to
+ * be 10–11 px uppercase. Typography only: add the colour
+ * (`text-muted-foreground`) at the call site.
+ */
+export declare const MICRO_LABEL = "text-small font-semibold";
+//# sourceMappingURL=typography.d.ts.map

package/dist/lib/typography.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"typography.d.ts","sourceRoot":"","sources":["../../src/lib/typography.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAEH,qCAAqC;AACrC,eAAO,MAAM,UAAU,yDAA0D,CAAA;AAEjF,kCAAkC;AAClC,MAAM,MAAM,QAAQ,GAAG,CAAC,OAAO,UAAU,CAAC,CAAC,MAAM,CAAC,CAAA;AAElD,wEAAwE;AACxE,eAAO,MAAM,UAAU,EAAE,QAAQ,CAAC,MAAM,CAAC,QAAQ,EAAE,QAAQ,QAAQ,EAAE,CAAC,CAMrE,CAAA;AAED,oEAAoE;AACpE,eAAO,MAAM,aAAa,KAAK,CAAA;AAE/B;;;;;GAKG;AACH,eAAO,MAAM,WAAW,6BAA6B,CAAA"}