skybridge 0.0.0-dev.bc2c12c → 0.0.0-dev.bc518c9

package/dist/web/bridges/use-host-context.js

@@ -1,5 +1,10 @@
 import { useSyncExternalStore } from "react";
 import { getAdaptor } from "./get-adaptor.js";
+/**
+ * @internal
+ * Subscribe to a single {@link HostContext} key via `useSyncExternalStore`.
+ * Used to build the higher-level hooks; prefer those for app code.
+ */
 export const useHostContext = (key) => {
     const adaptor = getAdaptor();
     const store = adaptor.getHostContextStore(key);

package/dist/web/bridges/use-host-context.js.map

@@ -1 +1 @@
-{"version":3,"file":"use-host-context.js","sourceRoot":"","sources":["../../../src/web/bridges/use-host-context.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,oBAAoB,EAAE,MAAM,OAAO,CAAC;AAC7C,OAAO,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAG9C,MAAM,CAAC,MAAM,cAAc,GAAG,CAC5B,GAAM,EACU,EAAE;IAClB,MAAM,OAAO,GAAG,UAAU,EAAE,CAAC;IAC7B,MAAM,KAAK,GAAG,OAAO,CAAC,mBAAmB,CAAC,GAAG,CAAC,CAAC;IAE/C,OAAO,oBAAoB,CAAC,KAAK,CAAC,SAAS,EAAE,KAAK,CAAC,WAAW,CAAC,CAAC;AAClE,CAAC,CAAC","sourcesContent":["import { useSyncExternalStore } from \"react\";\nimport { getAdaptor } from \"./get-adaptor.js\";\nimport type { HostContext } from \"./types.js\";\n\nexport const useHostContext = <K extends keyof HostContext>(\n  key: K,\n): HostContext[K] => {\n  const adaptor = getAdaptor();\n  const store = adaptor.getHostContextStore(key);\n\n  return useSyncExternalStore(store.subscribe, store.getSnapshot);\n};\n"]}
+{"version":3,"file":"use-host-context.js","sourceRoot":"","sources":["../../../src/web/bridges/use-host-context.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,oBAAoB,EAAE,MAAM,OAAO,CAAC;AAC7C,OAAO,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAG9C;;;;GAIG;AACH,MAAM,CAAC,MAAM,cAAc,GAAG,CAC5B,GAAM,EACU,EAAE;IAClB,MAAM,OAAO,GAAG,UAAU,EAAE,CAAC;IAC7B,MAAM,KAAK,GAAG,OAAO,CAAC,mBAAmB,CAAC,GAAG,CAAC,CAAC;IAE/C,OAAO,oBAAoB,CAAC,KAAK,CAAC,SAAS,EAAE,KAAK,CAAC,WAAW,CAAC,CAAC;AAClE,CAAC,CAAC","sourcesContent":["import { useSyncExternalStore } from \"react\";\nimport { getAdaptor } from \"./get-adaptor.js\";\nimport type { HostContext } from \"./types.js\";\n\n/**\n * @internal\n * Subscribe to a single {@link HostContext} key via `useSyncExternalStore`.\n * Used to build the higher-level hooks; prefer those for app code.\n */\nexport const useHostContext = <K extends keyof HostContext>(\n  key: K,\n): HostContext[K] => {\n  const adaptor = getAdaptor();\n  const store = adaptor.getHostContextStore(key);\n\n  return useSyncExternalStore(store.subscribe, store.getSnapshot);\n};\n"]}

package/dist/web/create-store.d.ts

@@ -1,3 +1,29 @@
 import { type StateCreator } from "zustand";
 import type { UnknownObject } from "./types.js";
+/**
+ * Create a Zustand store that is bidirectionally synced with the host's
+ * `viewState`. Local store updates persist to the host, and external host
+ * updates rehydrate the store — making the store the single source of truth
+ * for state that should survive view remounts.
+ *
+ * Use this when you outgrow {@link useViewState} and want first-class Zustand
+ * ergonomics (selectors, actions, middleware). Otherwise prefer `useViewState`.
+ *
+ * Skybridge-internal context fields (see {@link DataLLM}) are filtered out
+ * automatically before reaching your store.
+ *
+ * @typeParam State - Shape of the store's state. Must be a plain object.
+ *
+ * @example
+ * ```ts
+ * export const useStore = createStore<{ count: number; inc: () => void }>(
+ *   (set) => ({
+ *     count: 0,
+ *     inc: () => set((s) => ({ count: s.count + 1 })),
+ *   }),
+ * );
+ * ```
+ *
+ * @see https://docs.skybridge.tech/api-reference/create-store
+ */
 export declare function createStore<State extends UnknownObject>(storeCreator: StateCreator<State, [], [], State>, defaultState?: State | (() => State)): import("zustand").UseBoundStore<import("zustand").StoreApi<State>>;

package/dist/web/create-store.js

@@ -2,6 +2,32 @@ import { dequal } from "dequal/lite";
 import { create } from "zustand";
 import { getAdaptor } from "./bridges/index.js";
 import { filterViewContext, getInitialState, injectViewContext, serializeState, } from "./helpers/state.js";
+/**
+ * Create a Zustand store that is bidirectionally synced with the host's
+ * `viewState`. Local store updates persist to the host, and external host
+ * updates rehydrate the store — making the store the single source of truth
+ * for state that should survive view remounts.
+ *
+ * Use this when you outgrow {@link useViewState} and want first-class Zustand
+ * ergonomics (selectors, actions, middleware). Otherwise prefer `useViewState`.
+ *
+ * Skybridge-internal context fields (see {@link DataLLM}) are filtered out
+ * automatically before reaching your store.
+ *
+ * @typeParam State - Shape of the store's state. Must be a plain object.
+ *
+ * @example
+ * ```ts
+ * export const useStore = createStore<{ count: number; inc: () => void }>(
+ *   (set) => ({
+ *     count: 0,
+ *     inc: () => set((s) => ({ count: s.count + 1 })),
+ *   }),
+ * );
+ * ```
+ *
+ * @see https://docs.skybridge.tech/api-reference/create-store
+ */
 export function createStore(storeCreator, defaultState) {
     const initialState = getInitialState(defaultState);
     const store = create()((...args) => {

package/dist/web/create-store.js.map

@@ -1 +1 @@
-{"version":3,"file":"create-store.js","sourceRoot":"","sources":["../../src/web/create-store.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AACrC,OAAO,EAAE,MAAM,EAAqB,MAAM,SAAS,CAAC;AACpD,OAAO,EAAE,UAAU,EAAE,MAAM,oBAAoB,CAAC;AAChD,OAAO,EACL,iBAAiB,EACjB,eAAe,EACf,iBAAiB,EACjB,cAAc,GACf,MAAM,oBAAoB,CAAC;AAG5B,MAAM,UAAU,WAAW,CACzB,YAAgD,EAChD,YAAoC;IAEpC,MAAM,YAAY,GAAG,eAAe,CAAC,YAAY,CAAC,CAAC;IAEnD,MAAM,KAAK,GAAG,MAAM,EAAS,CAC3B,CAAC,GAAG,IAAoD,EAAE,EAAE;QAC1D,MAAM,SAAS,GAAG,YAAY,CAAC,GAAG,IAAI,CAAC,CAAC;QAExC,IAAI,YAAY,KAAK,IAAI,EAAE,CAAC;YAC1B,OAAO,EAAE,GAAG,SAAS,EAAE,GAAG,YAAY,EAAE,CAAC;QAC3C,CAAC;QAED,OAAO,SAAS,CAAC;IACnB,CAAC,CACF,CAAC;IAEF,4EAA4E;IAC5E,qFAAqF;IACrF,KAAK,CAAC,SAAS,CAAC,CAAC,KAAY,EAAE,EAAE;QAC/B,MAAM,eAAe,GAAG,cAAc,CAAC,KAAK,CAAC,CAAC;QAC9C,IAAI,eAAe,KAAK,IAAI,IAAI,eAAe,KAAK,SAAS,EAAE,CAAC;YAC9D,MAAM,cAAc,GAAG,iBAAiB,CAAC,eAAwB,CAAC,CAAC;YACnE,IAAI,cAAc,KAAK,IAAI,EAAE,CAAC;gBAC5B,UAAU,EAAE,CAAC,YAAY,CAAC,cAAc,CAAC,CAAC;YAC5C,CAAC;QACH,CAAC;IACH,CAAC,CAAC,CAAC;IAEH,MAAM,cAAc,GAAG,UAAU,EAAE,CAAC,mBAAmB,CAAC,WAAW,CAAC,CAAC;IACrE,cAAc,CAAC,SAAS,CAAC,GAAG,EAAE;QAC5B,MAAM,aAAa,GAAG,cAAc,CAAC,WAAW,EAAE,CAAC;QACnD,IAAI,aAAa,KAAK,IAAI,EAAE,CAAC;YAC3B,MAAM,QAAQ,GAAG,iBAAiB,CAAC,aAAa,CAAU,CAAC;YAC3D,MAAM,OAAO,GAAG,cAAc,CAAC,KAAK,CAAC,QAAQ,EAAE,CAAU,CAAC;YAC1D,IAAI,CAAC,MAAM,CAAC,QAAQ,EAAE,OAAO,CAAC,EAAE,CAAC;gBAC/B,KAAK,CAAC,QAAQ,CAAC,QAAQ,CAAC,CAAC;YAC3B,CAAC;QACH,CAAC;IACH,CAAC,CAAC,CAAC;IAEH,OAAO,KAAK,CAAC;AACf,CAAC","sourcesContent":["import { dequal } from \"dequal/lite\";\nimport { create, type StateCreator } from \"zustand\";\nimport { getAdaptor } from \"./bridges/index.js\";\nimport {\n  filterViewContext,\n  getInitialState,\n  injectViewContext,\n  serializeState,\n} from \"./helpers/state.js\";\nimport type { UnknownObject } from \"./types.js\";\n\nexport function createStore<State extends UnknownObject>(\n  storeCreator: StateCreator<State, [], [], State>,\n  defaultState?: State | (() => State),\n) {\n  const initialState = getInitialState(defaultState);\n\n  const store = create<State>()(\n    (...args: Parameters<StateCreator<State, [], [], State>>) => {\n      const baseStore = storeCreator(...args);\n\n      if (initialState !== null) {\n        return { ...baseStore, ...initialState };\n      }\n\n      return baseStore;\n    },\n  );\n\n  // Bidirectional sync between the Zustand store and the adaptor's viewState.\n  // Store changes persist to the host; external viewState changes rehydrate the store.\n  store.subscribe((state: State) => {\n    const serializedState = serializeState(state);\n    if (serializedState !== null && serializedState !== undefined) {\n      const stateToPersist = injectViewContext(serializedState as State);\n      if (stateToPersist !== null) {\n        getAdaptor().setViewState(stateToPersist);\n      }\n    }\n  });\n\n  const viewStateStore = getAdaptor().getHostContextStore(\"viewState\");\n  viewStateStore.subscribe(() => {\n    const externalState = viewStateStore.getSnapshot();\n    if (externalState !== null) {\n      const filtered = filterViewContext(externalState) as State;\n      const current = serializeState(store.getState()) as State;\n      if (!dequal(filtered, current)) {\n        store.setState(filtered);\n      }\n    }\n  });\n\n  return store;\n}\n"]}
+{"version":3,"file":"create-store.js","sourceRoot":"","sources":["../../src/web/create-store.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AACrC,OAAO,EAAE,MAAM,EAAqB,MAAM,SAAS,CAAC;AACpD,OAAO,EAAE,UAAU,EAAE,MAAM,oBAAoB,CAAC;AAChD,OAAO,EACL,iBAAiB,EACjB,eAAe,EACf,iBAAiB,EACjB,cAAc,GACf,MAAM,oBAAoB,CAAC;AAG5B;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,MAAM,UAAU,WAAW,CACzB,YAAgD,EAChD,YAAoC;IAEpC,MAAM,YAAY,GAAG,eAAe,CAAC,YAAY,CAAC,CAAC;IAEnD,MAAM,KAAK,GAAG,MAAM,EAAS,CAC3B,CAAC,GAAG,IAAoD,EAAE,EAAE;QAC1D,MAAM,SAAS,GAAG,YAAY,CAAC,GAAG,IAAI,CAAC,CAAC;QAExC,IAAI,YAAY,KAAK,IAAI,EAAE,CAAC;YAC1B,OAAO,EAAE,GAAG,SAAS,EAAE,GAAG,YAAY,EAAE,CAAC;QAC3C,CAAC;QAED,OAAO,SAAS,CAAC;IACnB,CAAC,CACF,CAAC;IAEF,4EAA4E;IAC5E,qFAAqF;IACrF,KAAK,CAAC,SAAS,CAAC,CAAC,KAAY,EAAE,EAAE;QAC/B,MAAM,eAAe,GAAG,cAAc,CAAC,KAAK,CAAC,CAAC;QAC9C,IAAI,eAAe,KAAK,IAAI,IAAI,eAAe,KAAK,SAAS,EAAE,CAAC;YAC9D,MAAM,cAAc,GAAG,iBAAiB,CAAC,eAAwB,CAAC,CAAC;YACnE,IAAI,cAAc,KAAK,IAAI,EAAE,CAAC;gBAC5B,UAAU,EAAE,CAAC,YAAY,CAAC,cAAc,CAAC,CAAC;YAC5C,CAAC;QACH,CAAC;IACH,CAAC,CAAC,CAAC;IAEH,MAAM,cAAc,GAAG,UAAU,EAAE,CAAC,mBAAmB,CAAC,WAAW,CAAC,CAAC;IACrE,cAAc,CAAC,SAAS,CAAC,GAAG,EAAE;QAC5B,MAAM,aAAa,GAAG,cAAc,CAAC,WAAW,EAAE,CAAC;QACnD,IAAI,aAAa,KAAK,IAAI,EAAE,CAAC;YAC3B,MAAM,QAAQ,GAAG,iBAAiB,CAAC,aAAa,CAAU,CAAC;YAC3D,MAAM,OAAO,GAAG,cAAc,CAAC,KAAK,CAAC,QAAQ,EAAE,CAAU,CAAC;YAC1D,IAAI,CAAC,MAAM,CAAC,QAAQ,EAAE,OAAO,CAAC,EAAE,CAAC;gBAC/B,KAAK,CAAC,QAAQ,CAAC,QAAQ,CAAC,CAAC;YAC3B,CAAC;QACH,CAAC;IACH,CAAC,CAAC,CAAC;IAEH,OAAO,KAAK,CAAC;AACf,CAAC","sourcesContent":["import { dequal } from \"dequal/lite\";\nimport { create, type StateCreator } from \"zustand\";\nimport { getAdaptor } from \"./bridges/index.js\";\nimport {\n  filterViewContext,\n  getInitialState,\n  injectViewContext,\n  serializeState,\n} from \"./helpers/state.js\";\nimport type { UnknownObject } from \"./types.js\";\n\n/**\n * Create a Zustand store that is bidirectionally synced with the host's\n * `viewState`. Local store updates persist to the host, and external host\n * updates rehydrate the store — making the store the single source of truth\n * for state that should survive view remounts.\n *\n * Use this when you outgrow {@link useViewState} and want first-class Zustand\n * ergonomics (selectors, actions, middleware). Otherwise prefer `useViewState`.\n *\n * Skybridge-internal context fields (see {@link DataLLM}) are filtered out\n * automatically before reaching your store.\n *\n * @typeParam State - Shape of the store's state. Must be a plain object.\n *\n * @example\n * ```ts\n * export const useStore = createStore<{ count: number; inc: () => void }>(\n *   (set) => ({\n *     count: 0,\n *     inc: () => set((s) => ({ count: s.count + 1 })),\n *   }),\n * );\n * ```\n *\n * @see https://docs.skybridge.tech/api-reference/create-store\n */\nexport function createStore<State extends UnknownObject>(\n  storeCreator: StateCreator<State, [], [], State>,\n  defaultState?: State | (() => State),\n) {\n  const initialState = getInitialState(defaultState);\n\n  const store = create<State>()(\n    (...args: Parameters<StateCreator<State, [], [], State>>) => {\n      const baseStore = storeCreator(...args);\n\n      if (initialState !== null) {\n        return { ...baseStore, ...initialState };\n      }\n\n      return baseStore;\n    },\n  );\n\n  // Bidirectional sync between the Zustand store and the adaptor's viewState.\n  // Store changes persist to the host; external viewState changes rehydrate the store.\n  store.subscribe((state: State) => {\n    const serializedState = serializeState(state);\n    if (serializedState !== null && serializedState !== undefined) {\n      const stateToPersist = injectViewContext(serializedState as State);\n      if (stateToPersist !== null) {\n        getAdaptor().setViewState(stateToPersist);\n      }\n    }\n  });\n\n  const viewStateStore = getAdaptor().getHostContextStore(\"viewState\");\n  viewStateStore.subscribe(() => {\n    const externalState = viewStateStore.getSnapshot();\n    if (externalState !== null) {\n      const filtered = filterViewContext(externalState) as State;\n      const current = serializeState(store.getState()) as State;\n      if (!dequal(filtered, current)) {\n        store.setState(filtered);\n      }\n    }\n  });\n\n  return store;\n}\n"]}

package/dist/web/data-llm.d.ts

@@ -1,14 +1,47 @@
 import { type ReactNode } from "react";
+/** Text content surfaced to the model by a {@link DataLLM} component. */
 export type DataLLMContent = string;
+/**
+ * A node in the {@link DataLLM} tree. Nested `<DataLLM>` elements form a
+ * hierarchy that is serialized as an indented bullet list for the model.
+ */
 export interface DataLLMNode {
     id: string;
     parentId: string | null;
     content: string | null;
 }
+/**
+ * Key under which the serialized {@link DataLLM} tree is persisted on the
+ * host's `viewState`. The host exposes the value to the model on subsequent
+ * turns.
+ */
 export declare const VIEW_CONTEXT_KEY: "__view_context";
 interface DataLLMProps {
     content: DataLLMContent | null | undefined;
     children?: ReactNode;
 }
+/**
+ * Surface in-view content to the LLM so it can reason about what the user is
+ * seeing without an extra tool call.
+ *
+ * Each `<DataLLM>` registers `content` as a node in a tree (parented by any
+ * enclosing `<DataLLM>`). The flattened tree is serialized as an indented
+ * bullet list and persisted on the host's `viewState` under
+ * {@link VIEW_CONTEXT_KEY}; the host then surfaces it to the model as part of
+ * the next turn's context.
+ *
+ * Pass `null`/`undefined` for `content` to register only as a structural
+ * parent (useful for grouping).
+ *
+ * @example
+ * ```tsx
+ * <DataLLM content="Active filters">
+ *   <DataLLM content={`Sort: ${sort}`} />
+ *   <DataLLM content={`Page: ${page}`} />
+ * </DataLLM>
+ * ```
+ *
+ * @see https://docs.skybridge.tech/api-reference/data-llm
+ */
 export declare function DataLLM({ content, children }: DataLLMProps): import("react/jsx-runtime").JSX.Element;
 export {};

package/dist/web/data-llm.js

@@ -1,6 +1,11 @@
 import { jsx as _jsx } from "react/jsx-runtime";
 import { createContext, useContext, useEffect, useId, } from "react";
 import { getAdaptor } from "./bridges/index.js";
+/**
+ * Key under which the serialized {@link DataLLM} tree is persisted on the
+ * host's `viewState`. The host exposes the value to the model on subsequent
+ * turns.
+ */
 export const VIEW_CONTEXT_KEY = "__view_context";
 const nodes = new Map();
 function setNode(node) {
@@ -20,6 +25,29 @@ function onChange() {
     }));
 }
 const ParentIdContext = createContext(null);
+/**
+ * Surface in-view content to the LLM so it can reason about what the user is
+ * seeing without an extra tool call.
+ *
+ * Each `<DataLLM>` registers `content` as a node in a tree (parented by any
+ * enclosing `<DataLLM>`). The flattened tree is serialized as an indented
+ * bullet list and persisted on the host's `viewState` under
+ * {@link VIEW_CONTEXT_KEY}; the host then surfaces it to the model as part of
+ * the next turn's context.
+ *
+ * Pass `null`/`undefined` for `content` to register only as a structural
+ * parent (useful for grouping).
+ *
+ * @example
+ * ```tsx
+ * <DataLLM content="Active filters">
+ *   <DataLLM content={`Sort: ${sort}`} />
+ *   <DataLLM content={`Page: ${page}`} />
+ * </DataLLM>
+ * ```
+ *
+ * @see https://docs.skybridge.tech/api-reference/data-llm
+ */
 export function DataLLM({ content, children }) {
     const parentId = useContext(ParentIdContext);
     const id = useId();

package/dist/web/data-llm.js.map

@@ -1 +1 @@
-{"version":3,"file":"data-llm.js","sourceRoot":"","sources":["../../src/web/data-llm.tsx"],"names":[],"mappings":"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","sourcesContent":["import {\n  createContext,\n  type ReactNode,\n  useContext,\n  useEffect,\n  useId,\n} from \"react\";\nimport { getAdaptor } from \"./bridges/index.js\";\n\nexport type DataLLMContent = string;\n\nexport interface DataLLMNode {\n  id: string;\n  parentId: string | null;\n  content: string | null;\n}\n\nexport const VIEW_CONTEXT_KEY = \"__view_context\" as const;\n\nconst nodes = new Map<string, DataLLMNode>();\n\nfunction setNode(node: DataLLMNode) {\n  nodes.set(node.id, node);\n  onChange();\n}\n\nfunction removeNode(id: string) {\n  nodes.delete(id);\n  onChange();\n}\n\nfunction onChange() {\n  const description = getLLMDescriptionString();\n  const adaptor = getAdaptor();\n  adaptor.setViewState((prevState) => ({\n    ...prevState,\n    [VIEW_CONTEXT_KEY]: description,\n  }));\n}\n\nconst ParentIdContext = createContext<string | null>(null);\n\ninterface DataLLMProps {\n  content: DataLLMContent | null | undefined;\n  children?: ReactNode;\n}\n\nexport function DataLLM({ content, children }: DataLLMProps) {\n  const parentId = useContext(ParentIdContext);\n  const id = useId();\n\n  useEffect(() => {\n    if (content) {\n      setNode({\n        id,\n        parentId,\n        content,\n      });\n    } else {\n      removeNode(id);\n    }\n\n    return () => {\n      removeNode(id);\n    };\n  }, [id, parentId, content]);\n\n  return (\n    <ParentIdContext.Provider value={id}>{children}</ParentIdContext.Provider>\n  );\n}\n\nfunction getLLMDescriptionString(): string {\n  const byParent = new Map<string | null, DataLLMNode[]>();\n  for (const node of Array.from(nodes.values())) {\n    const key = node.parentId ?? null;\n    if (!byParent.has(key)) {\n      byParent.set(key, []);\n    }\n    byParent.get(key)?.push(node);\n  }\n\n  for (const list of byParent.values()) {\n    list.sort((a, b) => a.id.localeCompare(b.id));\n  }\n\n  const lines: string[] = [];\n\n  function traverseTree(parentId: string | null, depth: number) {\n    const children = byParent.get(parentId);\n    if (!children) {\n      return;\n    }\n\n    for (const child of children) {\n      if (child.content?.trim()) {\n        const indent = \"  \".repeat(depth);\n        lines.push(`${indent}- ${child.content.trim()}`);\n      }\n      traverseTree(child.id, depth + 1);\n    }\n  }\n\n  traverseTree(null, 0);\n\n  return lines.join(\"\\n\");\n}\n"]}
+{"version":3,"file":"data-llm.js","sourceRoot":"","sources":["../../src/web/data-llm.tsx"],"names":[],"mappings":";AAAA,OAAO,EACL,aAAa,EAEb,UAAU,EACV,SAAS,EACT,KAAK,GACN,MAAM,OAAO,CAAC;AACf,OAAO,EAAE,UAAU,EAAE,MAAM,oBAAoB,CAAC;AAehD;;;;GAIG;AACH,MAAM,CAAC,MAAM,gBAAgB,GAAG,gBAAyB,CAAC;AAE1D,MAAM,KAAK,GAAG,IAAI,GAAG,EAAuB,CAAC;AAE7C,SAAS,OAAO,CAAC,IAAiB;IAChC,KAAK,CAAC,GAAG,CAAC,IAAI,CAAC,EAAE,EAAE,IAAI,CAAC,CAAC;IACzB,QAAQ,EAAE,CAAC;AACb,CAAC;AAED,SAAS,UAAU,CAAC,EAAU;IAC5B,KAAK,CAAC,MAAM,CAAC,EAAE,CAAC,CAAC;IACjB,QAAQ,EAAE,CAAC;AACb,CAAC;AAED,SAAS,QAAQ;IACf,MAAM,WAAW,GAAG,uBAAuB,EAAE,CAAC;IAC9C,MAAM,OAAO,GAAG,UAAU,EAAE,CAAC;IAC7B,OAAO,CAAC,YAAY,CAAC,CAAC,SAAS,EAAE,EAAE,CAAC,CAAC;QACnC,GAAG,SAAS;QACZ,CAAC,gBAAgB,CAAC,EAAE,WAAW;KAChC,CAAC,CAAC,CAAC;AACN,CAAC;AAED,MAAM,eAAe,GAAG,aAAa,CAAgB,IAAI,CAAC,CAAC;AAO3D;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,MAAM,UAAU,OAAO,CAAC,EAAE,OAAO,EAAE,QAAQ,EAAgB;IACzD,MAAM,QAAQ,GAAG,UAAU,CAAC,eAAe,CAAC,CAAC;IAC7C,MAAM,EAAE,GAAG,KAAK,EAAE,CAAC;IAEnB,SAAS,CAAC,GAAG,EAAE;QACb,IAAI,OAAO,EAAE,CAAC;YACZ,OAAO,CAAC;gBACN,EAAE;gBACF,QAAQ;gBACR,OAAO;aACR,CAAC,CAAC;QACL,CAAC;aAAM,CAAC;YACN,UAAU,CAAC,EAAE,CAAC,CAAC;QACjB,CAAC;QAED,OAAO,GAAG,EAAE;YACV,UAAU,CAAC,EAAE,CAAC,CAAC;QACjB,CAAC,CAAC;IACJ,CAAC,EAAE,CAAC,EAAE,EAAE,QAAQ,EAAE,OAAO,CAAC,CAAC,CAAC;IAE5B,OAAO,CACL,KAAC,eAAe,CAAC,QAAQ,IAAC,KAAK,EAAE,EAAE,YAAG,QAAQ,GAA4B,CAC3E,CAAC;AACJ,CAAC;AAED,SAAS,uBAAuB;IAC9B,MAAM,QAAQ,GAAG,IAAI,GAAG,EAAgC,CAAC;IACzD,KAAK,MAAM,IAAI,IAAI,KAAK,CAAC,IAAI,CAAC,KAAK,CAAC,MAAM,EAAE,CAAC,EAAE,CAAC;QAC9C,MAAM,GAAG,GAAG,IAAI,CAAC,QAAQ,IAAI,IAAI,CAAC;QAClC,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,GAAG,CAAC,EAAE,CAAC;YACvB,QAAQ,CAAC,GAAG,CAAC,GAAG,EAAE,EAAE,CAAC,CAAC;QACxB,CAAC;QACD,QAAQ,CAAC,GAAG,CAAC,GAAG,CAAC,EAAE,IAAI,CAAC,IAAI,CAAC,CAAC;IAChC,CAAC;IAED,KAAK,MAAM,IAAI,IAAI,QAAQ,CAAC,MAAM,EAAE,EAAE,CAAC;QACrC,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC,aAAa,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC;IAChD,CAAC;IAED,MAAM,KAAK,GAAa,EAAE,CAAC;IAE3B,SAAS,YAAY,CAAC,QAAuB,EAAE,KAAa;QAC1D,MAAM,QAAQ,GAAG,QAAQ,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAC;QACxC,IAAI,CAAC,QAAQ,EAAE,CAAC;YACd,OAAO;QACT,CAAC;QAED,KAAK,MAAM,KAAK,IAAI,QAAQ,EAAE,CAAC;YAC7B,IAAI,KAAK,CAAC,OAAO,EAAE,IAAI,EAAE,EAAE,CAAC;gBAC1B,MAAM,MAAM,GAAG,IAAI,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;gBAClC,KAAK,CAAC,IAAI,CAAC,GAAG,MAAM,KAAK,KAAK,CAAC,OAAO,CAAC,IAAI,EAAE,EAAE,CAAC,CAAC;YACnD,CAAC;YACD,YAAY,CAAC,KAAK,CAAC,EAAE,EAAE,KAAK,GAAG,CAAC,CAAC,CAAC;QACpC,CAAC;IACH,CAAC;IAED,YAAY,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC;IAEtB,OAAO,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;AAC1B,CAAC","sourcesContent":["import {\n  createContext,\n  type ReactNode,\n  useContext,\n  useEffect,\n  useId,\n} from \"react\";\nimport { getAdaptor } from \"./bridges/index.js\";\n\n/** Text content surfaced to the model by a {@link DataLLM} component. */\nexport type DataLLMContent = string;\n\n/**\n * A node in the {@link DataLLM} tree. Nested `<DataLLM>` elements form a\n * hierarchy that is serialized as an indented bullet list for the model.\n */\nexport interface DataLLMNode {\n  id: string;\n  parentId: string | null;\n  content: string | null;\n}\n\n/**\n * Key under which the serialized {@link DataLLM} tree is persisted on the\n * host's `viewState`. The host exposes the value to the model on subsequent\n * turns.\n */\nexport const VIEW_CONTEXT_KEY = \"__view_context\" as const;\n\nconst nodes = new Map<string, DataLLMNode>();\n\nfunction setNode(node: DataLLMNode) {\n  nodes.set(node.id, node);\n  onChange();\n}\n\nfunction removeNode(id: string) {\n  nodes.delete(id);\n  onChange();\n}\n\nfunction onChange() {\n  const description = getLLMDescriptionString();\n  const adaptor = getAdaptor();\n  adaptor.setViewState((prevState) => ({\n    ...prevState,\n    [VIEW_CONTEXT_KEY]: description,\n  }));\n}\n\nconst ParentIdContext = createContext<string | null>(null);\n\ninterface DataLLMProps {\n  content: DataLLMContent | null | undefined;\n  children?: ReactNode;\n}\n\n/**\n * Surface in-view content to the LLM so it can reason about what the user is\n * seeing without an extra tool call.\n *\n * Each `<DataLLM>` registers `content` as a node in a tree (parented by any\n * enclosing `<DataLLM>`). The flattened tree is serialized as an indented\n * bullet list and persisted on the host's `viewState` under\n * {@link VIEW_CONTEXT_KEY}; the host then surfaces it to the model as part of\n * the next turn's context.\n *\n * Pass `null`/`undefined` for `content` to register only as a structural\n * parent (useful for grouping).\n *\n * @example\n * ```tsx\n * <DataLLM content=\"Active filters\">\n *   <DataLLM content={`Sort: ${sort}`} />\n *   <DataLLM content={`Page: ${page}`} />\n * </DataLLM>\n * ```\n *\n * @see https://docs.skybridge.tech/api-reference/data-llm\n */\nexport function DataLLM({ content, children }: DataLLMProps) {\n  const parentId = useContext(ParentIdContext);\n  const id = useId();\n\n  useEffect(() => {\n    if (content) {\n      setNode({\n        id,\n        parentId,\n        content,\n      });\n    } else {\n      removeNode(id);\n    }\n\n    return () => {\n      removeNode(id);\n    };\n  }, [id, parentId, content]);\n\n  return (\n    <ParentIdContext.Provider value={id}>{children}</ParentIdContext.Provider>\n  );\n}\n\nfunction getLLMDescriptionString(): string {\n  const byParent = new Map<string | null, DataLLMNode[]>();\n  for (const node of Array.from(nodes.values())) {\n    const key = node.parentId ?? null;\n    if (!byParent.has(key)) {\n      byParent.set(key, []);\n    }\n    byParent.get(key)?.push(node);\n  }\n\n  for (const list of byParent.values()) {\n    list.sort((a, b) => a.id.localeCompare(b.id));\n  }\n\n  const lines: string[] = [];\n\n  function traverseTree(parentId: string | null, depth: number) {\n    const children = byParent.get(parentId);\n    if (!children) {\n      return;\n    }\n\n    for (const child of children) {\n      if (child.content?.trim()) {\n        const indent = \"  \".repeat(depth);\n        lines.push(`${indent}- ${child.content.trim()}`);\n      }\n      traverseTree(child.id, depth + 1);\n    }\n  }\n\n  traverseTree(null, 0);\n\n  return lines.join(\"\\n\");\n}\n"]}

package/dist/web/generate-helpers.d.ts

@@ -64,6 +64,8 @@ type TypedToolInfoReturn<TInput, TOutput, TResponseMetadata> = ToolState<Objecti
  *   // toolInfo.output.structuredContent is typed based on view output schema
  * }
  * ```
+ *
+ * @see https://docs.skybridge.tech/api-reference/generate-helpers
  */
 export declare function generateHelpers<ServerType = never>(): {
     /**

package/dist/web/generate-helpers.js

@@ -53,6 +53,8 @@ import { useToolInfo } from "./hooks/use-tool-info.js";
  *   // toolInfo.output.structuredContent is typed based on view output schema
  * }
  * ```
+ *
+ * @see https://docs.skybridge.tech/api-reference/generate-helpers
  */
 export function generateHelpers() {
     return {

package/dist/web/generate-helpers.js.map

@@ -1 +1 @@
-{"version":3,"file":"generate-helpers.js","sourceRoot":"","sources":["../../src/web/generate-helpers.ts"],"names":[],"mappings":"AAOA,OAAO,EAIL,WAAW,GACZ,MAAM,0BAA0B,CAAC;AAClC,OAAO,EAAkB,WAAW,EAAE,MAAM,0BAA0B,CAAC;AAoBvE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqDG;AACH,MAAM,UAAU,eAAe;IAI7B,OAAO;QACL;;;;;;;;;;;;;;;;;;WAkBG;QACH,WAAW,EAAE,CACX,IAAc,EAId,EAAE;YACF,OAAO,WAAW,CAAC,IAAI,CAGtB,CAAC;QACJ,CAAC;QAED;;;;;;;;;;;;;;;;;;;;;;;;;;WA0BG;QACH,WAAW,EAAE,GAIX,EAAE;YACF,OAAO,WAAW,EAIjB,CAAC;QACJ,CAAC;KACF,CAAC;AACJ,CAAC","sourcesContent":["import type {\n  InferTools,\n  ToolInput,\n  ToolOutput,\n  ToolResponseMetadata,\n} from \"../server/index.js\";\nimport type { CallToolResponse } from \"./bridges/types.js\";\nimport {\n  type CallToolAsyncFn,\n  type CallToolFn,\n  type CallToolState,\n  useCallTool,\n} from \"./hooks/use-call-tool.js\";\nimport { type ToolState, useToolInfo } from \"./hooks/use-tool-info.js\";\nimport type { Objectify, Prettify } from \"./types.js\";\n\ntype TypedCallToolResponse<TOutput> = CallToolResponse & {\n  structuredContent: TOutput;\n};\n\ntype TypedCallToolReturn<TInput, TOutput> = Prettify<\n  CallToolState<TypedCallToolResponse<TOutput>> & {\n    callTool: CallToolFn<TInput, TypedCallToolResponse<TOutput>>;\n    callToolAsync: CallToolAsyncFn<TInput, TypedCallToolResponse<TOutput>>;\n  }\n>;\n\ntype TypedToolInfoReturn<TInput, TOutput, TResponseMetadata> = ToolState<\n  Objectify<TInput>,\n  Objectify<TOutput>,\n  Objectify<TResponseMetadata>\n>;\n\n/**\n * Creates typed versions of skybridge hooks with full type inference\n * for tool names, inputs, and outputs.\n *\n * This is the recommended way to use skybridge hooks in your views.\n * Set this up once in a dedicated file and export the typed hooks for use across your app.\n *\n * @typeParam ServerType - The type of your McpServer instance (use `typeof server`).\n *                         Must be a server instance created with method chaining.\n *                         TypeScript will validate that tools can be inferred from this type.\n *\n * @example\n * ```typescript\n * // src/server.ts\n * const server = new McpServer({ name: \"my-app\", version: \"1.0\" }, {})\n *   .registerTool({\n *     name: \"search-trip\",\n *     inputSchema: { destination: z.string() },\n *     outputSchema: { results: z.array(z.string()) },\n *     view: { component: \"search-trip\", description: \"Search trips\" },\n *   }, async ({ destination }) => {\n *     return { content: [{ type: \"text\", text: `Found trips to ${destination}` }] };\n *   });\n *\n * export type AppType = typeof server;\n * ```\n *\n * @example\n * ```typescript\n * // src/helpers.ts (one-time setup)\n * import type { AppType } from \"./server\";\n * import { generateHelpers } from \"skybridge/web\";\n *\n * export const { useCallTool, useToolInfo } = generateHelpers<AppType>();\n * ```\n *\n * @example\n * ```typescript\n * // src/views/search.tsx (usage)\n * import { useCallTool, useToolInfo } from \"../helpers\";\n *\n * export function SearchView() {\n *   const { callTool, data } = useCallTool(\"search-trip\");\n *   //                                      ^ autocomplete for tool names\n *   callTool({ destination: \"Spain\" });\n *   //         ^ autocomplete for input fields\n *\n *   const toolInfo = useToolInfo<\"search-trip\">();\n *   //                              ^ autocomplete for view names\n *   // toolInfo.input is typed based on view input schema\n *   // toolInfo.output.structuredContent is typed based on view output schema\n * }\n * ```\n */\nexport function generateHelpers<ServerType = never>() {\n  type Tools = InferTools<ServerType>;\n  type ToolNames = keyof Tools & string;\n\n  return {\n    /**\n     * Typed version of `useCallTool` that provides autocomplete for tool names\n     * and type inference for inputs and outputs.\n     *\n     * @param name - The name of the tool to call. Autocompletes based on your server's tool registry.\n     * @returns A hook with typed `callTool` function and `data` property.\n     *\n     * @example\n     * ```typescript\n     * const { callTool, data, isPending } = useCallTool(\"search-trip\");\n     * // TypeScript knows callTool expects { destination: string }\n     * callTool({ destination: \"Spain\" });\n     *\n     * // data.structuredContent is typed based on your outputSchema\n     * if (data) {\n     *   console.log(data.structuredContent.results);\n     * }\n     * ```\n     */\n    useCallTool: <ToolName extends ToolNames>(\n      name: ToolName,\n    ): TypedCallToolReturn<\n      ToolInput<ServerType, ToolName>,\n      ToolOutput<ServerType, ToolName>\n    > => {\n      return useCallTool(name) as TypedCallToolReturn<\n        ToolInput<ServerType, ToolName>,\n        ToolOutput<ServerType, ToolName>\n      >;\n    },\n\n    /**\n     * Typed version of `useToolInfo` that provides autocomplete for tool names\n     * and type inference for inputs, outputs, and responseMetadata.\n     *\n     * @typeParam K - The name of the tool. Autocompletes based on your server's tool registry.\n     * @returns A discriminated union with `status: \"pending\" | \"success\"` that narrows correctly.\n     *\n     * @example\n     * ```typescript\n     * const toolInfo = useToolInfo<\"search-trip\">();\n     * // toolInfo.input is typed as { destination: string; ... }\n     * // toolInfo.output is typed as { results: Array<...>; ... }\n     * // toolInfo.responseMetadata is typed based on _meta in callback return\n     * // toolInfo.status narrows correctly: \"pending\" | \"success\"\n     *\n     * if (toolInfo.isPending) {\n     *   // TypeScript knows output and responseMetadata are undefined here\n     *   console.log(toolInfo.input.destination);\n     * }\n     *\n     * if (toolInfo.isSuccess) {\n     *   // TypeScript knows output and responseMetadata are defined here\n     *   console.log(toolInfo.output.results);\n     *   console.log(toolInfo.responseMetadata);\n     * }\n     * ```\n     */\n    useToolInfo: <ToolName extends ToolNames>(): TypedToolInfoReturn<\n      ToolInput<ServerType, ToolName>,\n      ToolOutput<ServerType, ToolName>,\n      ToolResponseMetadata<ServerType, ToolName>\n    > => {\n      return useToolInfo() as TypedToolInfoReturn<\n        ToolInput<ServerType, ToolName>,\n        ToolOutput<ServerType, ToolName>,\n        ToolResponseMetadata<ServerType, ToolName>\n      >;\n    },\n  };\n}\n"]}
+{"version":3,"file":"generate-helpers.js","sourceRoot":"","sources":["../../src/web/generate-helpers.ts"],"names":[],"mappings":"AAOA,OAAO,EAIL,WAAW,GACZ,MAAM,0BAA0B,CAAC;AAClC,OAAO,EAAkB,WAAW,EAAE,MAAM,0BAA0B,CAAC;AAoBvE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuDG;AACH,MAAM,UAAU,eAAe;IAI7B,OAAO;QACL;;;;;;;;;;;;;;;;;;WAkBG;QACH,WAAW,EAAE,CACX,IAAc,EAId,EAAE;YACF,OAAO,WAAW,CAAC,IAAI,CAGtB,CAAC;QACJ,CAAC;QAED;;;;;;;;;;;;;;;;;;;;;;;;;;WA0BG;QACH,WAAW,EAAE,GAIX,EAAE;YACF,OAAO,WAAW,EAIjB,CAAC;QACJ,CAAC;KACF,CAAC;AACJ,CAAC","sourcesContent":["import type {\n  InferTools,\n  ToolInput,\n  ToolOutput,\n  ToolResponseMetadata,\n} from \"../server/index.js\";\nimport type { CallToolResponse } from \"./bridges/types.js\";\nimport {\n  type CallToolAsyncFn,\n  type CallToolFn,\n  type CallToolState,\n  useCallTool,\n} from \"./hooks/use-call-tool.js\";\nimport { type ToolState, useToolInfo } from \"./hooks/use-tool-info.js\";\nimport type { Objectify, Prettify } from \"./types.js\";\n\ntype TypedCallToolResponse<TOutput> = CallToolResponse & {\n  structuredContent: TOutput;\n};\n\ntype TypedCallToolReturn<TInput, TOutput> = Prettify<\n  CallToolState<TypedCallToolResponse<TOutput>> & {\n    callTool: CallToolFn<TInput, TypedCallToolResponse<TOutput>>;\n    callToolAsync: CallToolAsyncFn<TInput, TypedCallToolResponse<TOutput>>;\n  }\n>;\n\ntype TypedToolInfoReturn<TInput, TOutput, TResponseMetadata> = ToolState<\n  Objectify<TInput>,\n  Objectify<TOutput>,\n  Objectify<TResponseMetadata>\n>;\n\n/**\n * Creates typed versions of skybridge hooks with full type inference\n * for tool names, inputs, and outputs.\n *\n * This is the recommended way to use skybridge hooks in your views.\n * Set this up once in a dedicated file and export the typed hooks for use across your app.\n *\n * @typeParam ServerType - The type of your McpServer instance (use `typeof server`).\n *                         Must be a server instance created with method chaining.\n *                         TypeScript will validate that tools can be inferred from this type.\n *\n * @example\n * ```typescript\n * // src/server.ts\n * const server = new McpServer({ name: \"my-app\", version: \"1.0\" }, {})\n *   .registerTool({\n *     name: \"search-trip\",\n *     inputSchema: { destination: z.string() },\n *     outputSchema: { results: z.array(z.string()) },\n *     view: { component: \"search-trip\", description: \"Search trips\" },\n *   }, async ({ destination }) => {\n *     return { content: [{ type: \"text\", text: `Found trips to ${destination}` }] };\n *   });\n *\n * export type AppType = typeof server;\n * ```\n *\n * @example\n * ```typescript\n * // src/helpers.ts (one-time setup)\n * import type { AppType } from \"./server\";\n * import { generateHelpers } from \"skybridge/web\";\n *\n * export const { useCallTool, useToolInfo } = generateHelpers<AppType>();\n * ```\n *\n * @example\n * ```typescript\n * // src/views/search.tsx (usage)\n * import { useCallTool, useToolInfo } from \"../helpers\";\n *\n * export function SearchView() {\n *   const { callTool, data } = useCallTool(\"search-trip\");\n *   //                                      ^ autocomplete for tool names\n *   callTool({ destination: \"Spain\" });\n *   //         ^ autocomplete for input fields\n *\n *   const toolInfo = useToolInfo<\"search-trip\">();\n *   //                              ^ autocomplete for view names\n *   // toolInfo.input is typed based on view input schema\n *   // toolInfo.output.structuredContent is typed based on view output schema\n * }\n * ```\n *\n * @see https://docs.skybridge.tech/api-reference/generate-helpers\n */\nexport function generateHelpers<ServerType = never>() {\n  type Tools = InferTools<ServerType>;\n  type ToolNames = keyof Tools & string;\n\n  return {\n    /**\n     * Typed version of `useCallTool` that provides autocomplete for tool names\n     * and type inference for inputs and outputs.\n     *\n     * @param name - The name of the tool to call. Autocompletes based on your server's tool registry.\n     * @returns A hook with typed `callTool` function and `data` property.\n     *\n     * @example\n     * ```typescript\n     * const { callTool, data, isPending } = useCallTool(\"search-trip\");\n     * // TypeScript knows callTool expects { destination: string }\n     * callTool({ destination: \"Spain\" });\n     *\n     * // data.structuredContent is typed based on your outputSchema\n     * if (data) {\n     *   console.log(data.structuredContent.results);\n     * }\n     * ```\n     */\n    useCallTool: <ToolName extends ToolNames>(\n      name: ToolName,\n    ): TypedCallToolReturn<\n      ToolInput<ServerType, ToolName>,\n      ToolOutput<ServerType, ToolName>\n    > => {\n      return useCallTool(name) as TypedCallToolReturn<\n        ToolInput<ServerType, ToolName>,\n        ToolOutput<ServerType, ToolName>\n      >;\n    },\n\n    /**\n     * Typed version of `useToolInfo` that provides autocomplete for tool names\n     * and type inference for inputs, outputs, and responseMetadata.\n     *\n     * @typeParam K - The name of the tool. Autocompletes based on your server's tool registry.\n     * @returns A discriminated union with `status: \"pending\" | \"success\"` that narrows correctly.\n     *\n     * @example\n     * ```typescript\n     * const toolInfo = useToolInfo<\"search-trip\">();\n     * // toolInfo.input is typed as { destination: string; ... }\n     * // toolInfo.output is typed as { results: Array<...>; ... }\n     * // toolInfo.responseMetadata is typed based on _meta in callback return\n     * // toolInfo.status narrows correctly: \"pending\" | \"success\"\n     *\n     * if (toolInfo.isPending) {\n     *   // TypeScript knows output and responseMetadata are undefined here\n     *   console.log(toolInfo.input.destination);\n     * }\n     *\n     * if (toolInfo.isSuccess) {\n     *   // TypeScript knows output and responseMetadata are defined here\n     *   console.log(toolInfo.output.results);\n     *   console.log(toolInfo.responseMetadata);\n     * }\n     * ```\n     */\n    useToolInfo: <ToolName extends ToolNames>(): TypedToolInfoReturn<\n      ToolInput<ServerType, ToolName>,\n      ToolOutput<ServerType, ToolName>,\n      ToolResponseMetadata<ServerType, ToolName>\n    > => {\n      return useToolInfo() as TypedToolInfoReturn<\n        ToolInput<ServerType, ToolName>,\n        ToolOutput<ServerType, ToolName>,\n        ToolResponseMetadata<ServerType, ToolName>\n      >;\n    },\n  };\n}\n"]}

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

@@ -1,5 +1,6 @@
 export { type CallToolAsyncFn, type CallToolFn, type CallToolState, type SideEffects, useCallTool, } from "./use-call-tool.js";
 export { useDisplayMode } from "./use-display-mode.js";
+export { type DownloadFn, useDownload } from "./use-download.js";
 export { useFiles } from "./use-files.js";
 export { type LayoutState, useLayout } from "./use-layout.js";
 export { type OpenExternalFn, useOpenExternal } from "./use-open-external.js";

package/dist/web/hooks/index.js

@@ -1,5 +1,6 @@
 export { useCallTool, } from "./use-call-tool.js";
 export { useDisplayMode } from "./use-display-mode.js";
+export { useDownload } from "./use-download.js";
 export { useFiles } from "./use-files.js";
 export { useLayout } from "./use-layout.js";
 export { useOpenExternal } from "./use-open-external.js";

package/dist/web/hooks/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/web/hooks/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAKL,WAAW,GACZ,MAAM,oBAAoB,CAAC;AAC5B,OAAO,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAC;AACvD,OAAO,EAAE,QAAQ,EAAE,MAAM,gBAAgB,CAAC;AAC1C,OAAO,EAAoB,SAAS,EAAE,MAAM,iBAAiB,CAAC;AAC9D,OAAO,EAAuB,eAAe,EAAE,MAAM,wBAAwB,CAAC;AAC9E,OAAO,EAAuB,eAAe,EAAE,MAAM,wBAAwB,CAAC;AAC9E,OAAO,EAAE,eAAe,EAAE,MAAM,wBAAwB,CAAC;AACzD,OAAO,EAAsB,cAAc,EAAE,MAAM,uBAAuB,CAAC;AAC3E,OAAO,EAAE,sBAAsB,EAAE,MAAM,iCAAiC,CAAC;AACzE,OAAO,EAAE,kBAAkB,EAAE,MAAM,8BAA8B,CAAC;AAClE,OAAO,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAC;AACjD,OAAO,EAAkB,OAAO,EAAE,MAAM,eAAe,CAAC;AACxD,OAAO,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAC","sourcesContent":["export {\n  type CallToolAsyncFn,\n  type CallToolFn,\n  type CallToolState,\n  type SideEffects,\n  useCallTool,\n} from \"./use-call-tool.js\";\nexport { useDisplayMode } from \"./use-display-mode.js\";\nexport { useFiles } from \"./use-files.js\";\nexport { type LayoutState, useLayout } from \"./use-layout.js\";\nexport { type OpenExternalFn, useOpenExternal } from \"./use-open-external.js\";\nexport { type RequestCloseFn, useRequestClose } from \"./use-request-close.js\";\nexport { useRequestModal } from \"./use-request-modal.js\";\nexport { type RequestSizeFn, useRequestSize } from \"./use-request-size.js\";\nexport { useSendFollowUpMessage } from \"./use-send-follow-up-message.js\";\nexport { useSetOpenInAppUrl } from \"./use-set-open-in-app-url.js\";\nexport { useToolInfo } from \"./use-tool-info.js\";\nexport { type UserState, useUser } from \"./use-user.js\";\nexport { useViewState } from \"./use-view-state.js\";\n"]}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/web/hooks/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAKL,WAAW,GACZ,MAAM,oBAAoB,CAAC;AAC5B,OAAO,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAC;AACvD,OAAO,EAAmB,WAAW,EAAE,MAAM,mBAAmB,CAAC;AACjE,OAAO,EAAE,QAAQ,EAAE,MAAM,gBAAgB,CAAC;AAC1C,OAAO,EAAoB,SAAS,EAAE,MAAM,iBAAiB,CAAC;AAC9D,OAAO,EAAuB,eAAe,EAAE,MAAM,wBAAwB,CAAC;AAC9E,OAAO,EAAuB,eAAe,EAAE,MAAM,wBAAwB,CAAC;AAC9E,OAAO,EAAE,eAAe,EAAE,MAAM,wBAAwB,CAAC;AACzD,OAAO,EAAsB,cAAc,EAAE,MAAM,uBAAuB,CAAC;AAC3E,OAAO,EAAE,sBAAsB,EAAE,MAAM,iCAAiC,CAAC;AACzE,OAAO,EAAE,kBAAkB,EAAE,MAAM,8BAA8B,CAAC;AAClE,OAAO,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAC;AACjD,OAAO,EAAkB,OAAO,EAAE,MAAM,eAAe,CAAC;AACxD,OAAO,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAC","sourcesContent":["export {\n  type CallToolAsyncFn,\n  type CallToolFn,\n  type CallToolState,\n  type SideEffects,\n  useCallTool,\n} from \"./use-call-tool.js\";\nexport { useDisplayMode } from \"./use-display-mode.js\";\nexport { type DownloadFn, useDownload } from \"./use-download.js\";\nexport { useFiles } from \"./use-files.js\";\nexport { type LayoutState, useLayout } from \"./use-layout.js\";\nexport { type OpenExternalFn, useOpenExternal } from \"./use-open-external.js\";\nexport { type RequestCloseFn, useRequestClose } from \"./use-request-close.js\";\nexport { useRequestModal } from \"./use-request-modal.js\";\nexport { type RequestSizeFn, useRequestSize } from \"./use-request-size.js\";\nexport { useSendFollowUpMessage } from \"./use-send-follow-up-message.js\";\nexport { useSetOpenInAppUrl } from \"./use-set-open-in-app-url.js\";\nexport { useToolInfo } from \"./use-tool-info.js\";\nexport { type UserState, useUser } from \"./use-user.js\";\nexport { useViewState } from \"./use-view-state.js\";\n"]}

package/dist/web/hooks/test/utils.d.ts

@@ -1,10 +1,14 @@
-import type { McpUiHostContext, McpUiToolResultNotification } from "@modelcontextprotocol/ext-apps";
+import type { McpUiDownloadFileResult, McpUiHostCapabilities, McpUiHostContext, McpUiToolResultNotification } from "@modelcontextprotocol/ext-apps";
 export declare class MockResizeObserver {
     observe(): void;
     unobserve(): void;
     disconnect(): void;
 }
-export declare const getMcpAppHostPostMessageMock: (initialContext?: McpUiHostContext) => import("vitest").Mock<(message: {
+export type McpAppHostMockOptions = {
+    hostCapabilities?: McpUiHostCapabilities;
+    downloadFileResult?: McpUiDownloadFileResult;
+};
+export declare const getMcpAppHostPostMessageMock: (initialContext?: McpUiHostContext, options?: McpAppHostMockOptions) => import("vitest").Mock<(message: {
     method: string;
     id: number;
 }) => void>;

package/dist/web/hooks/test/utils.js

@@ -7,13 +7,13 @@ export class MockResizeObserver {
     disconnect() { }
 }
 const DEFAULT_CONTEXT = {};
-export const getMcpAppHostPostMessageMock = (initialContext = DEFAULT_CONTEXT) => vi.fn((message) => {
+export const getMcpAppHostPostMessageMock = (initialContext = DEFAULT_CONTEXT, options = {}) => vi.fn((message) => {
     switch (message.method) {
         case "ui/initialize": {
             const result = {
                 protocolVersion: "2025-06-18",
                 hostInfo: { name: "test-host", version: "1.0.0" },
-                hostCapabilities: {},
+                hostCapabilities: options.hostCapabilities ?? {},
                 hostContext: initialContext,
             };
             act(() => fireEvent(window, new MessageEvent("message", {
@@ -37,6 +37,17 @@ export const getMcpAppHostPostMessageMock = (initialContext = DEFAULT_CONTEXT) =
             })));
             break;
         }
+        case "ui/download-file": {
+            act(() => fireEvent(window, new MessageEvent("message", {
+                source: window.parent,
+                data: {
+                    jsonrpc: "2.0",
+                    id: message.id,
+                    result: options.downloadFileResult ?? {},
+                },
+            })));
+            break;
+        }
     }
 });
 export const fireToolInputNotification = (args) => {

package/dist/web/hooks/test/utils.js.map

@@ -1 +1 @@
-{"version":3,"file":"utils.js","sourceRoot":"","sources":["../../../../src/web/hooks/test/utils.ts"],"names":[],"mappings":"AAMA,OAAO,EAAE,SAAS,EAAE,MAAM,wBAAwB,CAAC;AACnD,OAAO,EAAE,GAAG,EAAE,MAAM,OAAO,CAAC;AAC5B,OAAO,EAAE,EAAE,EAAE,MAAM,QAAQ,CAAC;AAE5B,MAAM,OAAO,kBAAkB;IAC7B,OAAO,KAAU,CAAC;IAClB,SAAS,KAAU,CAAC;IACpB,UAAU,KAAU,CAAC;CACtB;AAED,MAAM,eAAe,GAAqB,EAAE,CAAC;AAE7C,MAAM,CAAC,MAAM,4BAA4B,GAAG,CAC1C,iBAAmC,eAAe,EAClD,EAAE,CACF,EAAE,CAAC,EAAE,CAAC,CAAC,OAAuC,EAAE,EAAE;IAChD,QAAQ,OAAO,CAAC,MAAM,EAAE,CAAC;QACvB,KAAK,eAAe,CAAC,CAAC,CAAC;YACrB,MAAM,MAAM,GAA0B;gBACpC,eAAe,EAAE,YAAY;gBAC7B,QAAQ,EAAE,EAAE,IAAI,EAAE,WAAW,EAAE,OAAO,EAAE,OAAO,EAAE;gBACjD,gBAAgB,EAAE,EAAE;gBACpB,WAAW,EAAE,cAAc;aAC5B,CAAC;YACF,GAAG,CAAC,GAAG,EAAE,CACP,SAAS,CACP,MAAM,EACN,IAAI,YAAY,CAIb,SAAS,EAAE;gBACZ,MAAM,EAAE,MAAM,CAAC,MAAM;gBACrB,IAAI,EAAE;oBACJ,OAAO,EAAE,KAAK;oBACd,EAAE,EAAE,OAAO,CAAC,EAAE;oBACd,MAAM;iBACP;aACF,CAAC,CACH,CACF,CAAC;YACF,MAAM;QACR,CAAC;QACD,KAAK,yBAAyB,CAAC,CAAC,CAAC;YAC/B,GAAG,CAAC,GAAG,EAAE,CACP,SAAS,CACP,MAAM,EACN,IAAI,YAAY,CACd,SAAS,EACT;gBACE,MAAM,EAAE,MAAM,CAAC,MAAM;gBACrB,IAAI,EAAE;oBACJ,OAAO,EAAE,KAAK;oBACd,EAAE,EAAE,OAAO,CAAC,EAAE;oBACd,MAAM,EAAE,EAAE;iBACX;aACF,CACF,CACF,CACF,CAAC;YACF,MAAM;QACR,CAAC;IACH,CAAC;AACH,CAAC,CAAC,CAAC;AAEL,MAAM,CAAC,MAAM,yBAAyB,GAAG,CAAC,IAA6B,EAAE,EAAE;IACzE,SAAS,CACP,MAAM,EACN,IAAI,YAAY,CACd,SAAS,EACT;QACE,MAAM,EAAE,MAAM,CAAC,MAAM;QACrB,IAAI,EAAE;YACJ,OAAO,EAAE,KAAK;YACd,MAAM,EAAE,6BAA6B;YACrC,MAAM,EAAE;gBACN,SAAS,EAAE,IAAI;aAChB;SACF;KACF,CACF,CACF,CAAC;AACJ,CAAC,CAAC;AAEF,MAAM,CAAC,MAAM,0BAA0B,GAAG,CAAC,MAI1C,EAAE,EAAE;IACH,SAAS,CACP,MAAM,EACN,IAAI,YAAY,CACd,SAAS,EACT;QACE,MAAM,EAAE,MAAM,CAAC,MAAM;QACrB,IAAI,EAAE;YACJ,OAAO,EAAE,KAAK;YACd,MAAM,EAAE,8BAA8B;YACtC,MAAM;SACP;KACF,CACF,CACF,CAAC;AACJ,CAAC,CAAC","sourcesContent":["import type {\n  McpUiHostContext,\n  McpUiInitializeResult,\n  McpUiToolInputNotification,\n  McpUiToolResultNotification,\n} from \"@modelcontextprotocol/ext-apps\";\nimport { fireEvent } from \"@testing-library/react\";\nimport { act } from \"react\";\nimport { vi } from \"vitest\";\n\nexport class MockResizeObserver {\n  observe(): void {}\n  unobserve(): void {}\n  disconnect(): void {}\n}\n\nconst DEFAULT_CONTEXT: McpUiHostContext = {};\n\nexport const getMcpAppHostPostMessageMock = (\n  initialContext: McpUiHostContext = DEFAULT_CONTEXT,\n) =>\n  vi.fn((message: { method: string; id: number }) => {\n    switch (message.method) {\n      case \"ui/initialize\": {\n        const result: McpUiInitializeResult = {\n          protocolVersion: \"2025-06-18\",\n          hostInfo: { name: \"test-host\", version: \"1.0.0\" },\n          hostCapabilities: {},\n          hostContext: initialContext,\n        };\n        act(() =>\n          fireEvent(\n            window,\n            new MessageEvent<{\n              jsonrpc: \"2.0\";\n              id: number;\n              result: McpUiInitializeResult;\n            }>(\"message\", {\n              source: window.parent,\n              data: {\n                jsonrpc: \"2.0\",\n                id: message.id,\n                result,\n              },\n            }),\n          ),\n        );\n        break;\n      }\n      case \"ui/update-model-context\": {\n        act(() =>\n          fireEvent(\n            window,\n            new MessageEvent<{ jsonrpc: \"2.0\"; id: number; result: unknown }>(\n              \"message\",\n              {\n                source: window.parent,\n                data: {\n                  jsonrpc: \"2.0\",\n                  id: message.id,\n                  result: {},\n                },\n              },\n            ),\n          ),\n        );\n        break;\n      }\n    }\n  });\n\nexport const fireToolInputNotification = (args: Record<string, unknown>) => {\n  fireEvent(\n    window,\n    new MessageEvent<McpUiToolInputNotification & { jsonrpc: \"2.0\" }>(\n      \"message\",\n      {\n        source: window.parent,\n        data: {\n          jsonrpc: \"2.0\",\n          method: \"ui/notifications/tool-input\",\n          params: {\n            arguments: args,\n          },\n        },\n      },\n    ),\n  );\n};\n\nexport const fireToolResultNotification = (params: {\n  content: McpUiToolResultNotification[\"params\"][\"content\"];\n  structuredContent: Record<string, unknown>;\n  _meta?: Record<string, unknown>;\n}) => {\n  fireEvent(\n    window,\n    new MessageEvent<McpUiToolResultNotification & { jsonrpc: \"2.0\" }>(\n      \"message\",\n      {\n        source: window.parent,\n        data: {\n          jsonrpc: \"2.0\",\n          method: \"ui/notifications/tool-result\",\n          params,\n        },\n      },\n    ),\n  );\n};\n"]}
+{"version":3,"file":"utils.js","sourceRoot":"","sources":["../../../../src/web/hooks/test/utils.ts"],"names":[],"mappings":"AAQA,OAAO,EAAE,SAAS,EAAE,MAAM,wBAAwB,CAAC;AACnD,OAAO,EAAE,GAAG,EAAE,MAAM,OAAO,CAAC;AAC5B,OAAO,EAAE,EAAE,EAAE,MAAM,QAAQ,CAAC;AAE5B,MAAM,OAAO,kBAAkB;IAC7B,OAAO,KAAU,CAAC;IAClB,SAAS,KAAU,CAAC;IACpB,UAAU,KAAU,CAAC;CACtB;AAED,MAAM,eAAe,GAAqB,EAAE,CAAC;AAO7C,MAAM,CAAC,MAAM,4BAA4B,GAAG,CAC1C,iBAAmC,eAAe,EAClD,UAAiC,EAAE,EACnC,EAAE,CACF,EAAE,CAAC,EAAE,CAAC,CAAC,OAAuC,EAAE,EAAE;IAChD,QAAQ,OAAO,CAAC,MAAM,EAAE,CAAC;QACvB,KAAK,eAAe,CAAC,CAAC,CAAC;YACrB,MAAM,MAAM,GAA0B;gBACpC,eAAe,EAAE,YAAY;gBAC7B,QAAQ,EAAE,EAAE,IAAI,EAAE,WAAW,EAAE,OAAO,EAAE,OAAO,EAAE;gBACjD,gBAAgB,EAAE,OAAO,CAAC,gBAAgB,IAAI,EAAE;gBAChD,WAAW,EAAE,cAAc;aAC5B,CAAC;YACF,GAAG,CAAC,GAAG,EAAE,CACP,SAAS,CACP,MAAM,EACN,IAAI,YAAY,CAIb,SAAS,EAAE;gBACZ,MAAM,EAAE,MAAM,CAAC,MAAM;gBACrB,IAAI,EAAE;oBACJ,OAAO,EAAE,KAAK;oBACd,EAAE,EAAE,OAAO,CAAC,EAAE;oBACd,MAAM;iBACP;aACF,CAAC,CACH,CACF,CAAC;YACF,MAAM;QACR,CAAC;QACD,KAAK,yBAAyB,CAAC,CAAC,CAAC;YAC/B,GAAG,CAAC,GAAG,EAAE,CACP,SAAS,CACP,MAAM,EACN,IAAI,YAAY,CACd,SAAS,EACT;gBACE,MAAM,EAAE,MAAM,CAAC,MAAM;gBACrB,IAAI,EAAE;oBACJ,OAAO,EAAE,KAAK;oBACd,EAAE,EAAE,OAAO,CAAC,EAAE;oBACd,MAAM,EAAE,EAAE;iBACX;aACF,CACF,CACF,CACF,CAAC;YACF,MAAM;QACR,CAAC;QACD,KAAK,kBAAkB,CAAC,CAAC,CAAC;YACxB,GAAG,CAAC,GAAG,EAAE,CACP,SAAS,CACP,MAAM,EACN,IAAI,YAAY,CAIb,SAAS,EAAE;gBACZ,MAAM,EAAE,MAAM,CAAC,MAAM;gBACrB,IAAI,EAAE;oBACJ,OAAO,EAAE,KAAK;oBACd,EAAE,EAAE,OAAO,CAAC,EAAE;oBACd,MAAM,EAAE,OAAO,CAAC,kBAAkB,IAAI,EAAE;iBACzC;aACF,CAAC,CACH,CACF,CAAC;YACF,MAAM;QACR,CAAC;IACH,CAAC;AACH,CAAC,CAAC,CAAC;AAEL,MAAM,CAAC,MAAM,yBAAyB,GAAG,CAAC,IAA6B,EAAE,EAAE;IACzE,SAAS,CACP,MAAM,EACN,IAAI,YAAY,CACd,SAAS,EACT;QACE,MAAM,EAAE,MAAM,CAAC,MAAM;QACrB,IAAI,EAAE;YACJ,OAAO,EAAE,KAAK;YACd,MAAM,EAAE,6BAA6B;YACrC,MAAM,EAAE;gBACN,SAAS,EAAE,IAAI;aAChB;SACF;KACF,CACF,CACF,CAAC;AACJ,CAAC,CAAC;AAEF,MAAM,CAAC,MAAM,0BAA0B,GAAG,CAAC,MAI1C,EAAE,EAAE;IACH,SAAS,CACP,MAAM,EACN,IAAI,YAAY,CACd,SAAS,EACT;QACE,MAAM,EAAE,MAAM,CAAC,MAAM;QACrB,IAAI,EAAE;YACJ,OAAO,EAAE,KAAK;YACd,MAAM,EAAE,8BAA8B;YACtC,MAAM;SACP;KACF,CACF,CACF,CAAC;AACJ,CAAC,CAAC","sourcesContent":["import type {\n  McpUiDownloadFileResult,\n  McpUiHostCapabilities,\n  McpUiHostContext,\n  McpUiInitializeResult,\n  McpUiToolInputNotification,\n  McpUiToolResultNotification,\n} from \"@modelcontextprotocol/ext-apps\";\nimport { fireEvent } from \"@testing-library/react\";\nimport { act } from \"react\";\nimport { vi } from \"vitest\";\n\nexport class MockResizeObserver {\n  observe(): void {}\n  unobserve(): void {}\n  disconnect(): void {}\n}\n\nconst DEFAULT_CONTEXT: McpUiHostContext = {};\n\nexport type McpAppHostMockOptions = {\n  hostCapabilities?: McpUiHostCapabilities;\n  downloadFileResult?: McpUiDownloadFileResult;\n};\n\nexport const getMcpAppHostPostMessageMock = (\n  initialContext: McpUiHostContext = DEFAULT_CONTEXT,\n  options: McpAppHostMockOptions = {},\n) =>\n  vi.fn((message: { method: string; id: number }) => {\n    switch (message.method) {\n      case \"ui/initialize\": {\n        const result: McpUiInitializeResult = {\n          protocolVersion: \"2025-06-18\",\n          hostInfo: { name: \"test-host\", version: \"1.0.0\" },\n          hostCapabilities: options.hostCapabilities ?? {},\n          hostContext: initialContext,\n        };\n        act(() =>\n          fireEvent(\n            window,\n            new MessageEvent<{\n              jsonrpc: \"2.0\";\n              id: number;\n              result: McpUiInitializeResult;\n            }>(\"message\", {\n              source: window.parent,\n              data: {\n                jsonrpc: \"2.0\",\n                id: message.id,\n                result,\n              },\n            }),\n          ),\n        );\n        break;\n      }\n      case \"ui/update-model-context\": {\n        act(() =>\n          fireEvent(\n            window,\n            new MessageEvent<{ jsonrpc: \"2.0\"; id: number; result: unknown }>(\n              \"message\",\n              {\n                source: window.parent,\n                data: {\n                  jsonrpc: \"2.0\",\n                  id: message.id,\n                  result: {},\n                },\n              },\n            ),\n          ),\n        );\n        break;\n      }\n      case \"ui/download-file\": {\n        act(() =>\n          fireEvent(\n            window,\n            new MessageEvent<{\n              jsonrpc: \"2.0\";\n              id: number;\n              result: McpUiDownloadFileResult;\n            }>(\"message\", {\n              source: window.parent,\n              data: {\n                jsonrpc: \"2.0\",\n                id: message.id,\n                result: options.downloadFileResult ?? {},\n              },\n            }),\n          ),\n        );\n        break;\n      }\n    }\n  });\n\nexport const fireToolInputNotification = (args: Record<string, unknown>) => {\n  fireEvent(\n    window,\n    new MessageEvent<McpUiToolInputNotification & { jsonrpc: \"2.0\" }>(\n      \"message\",\n      {\n        source: window.parent,\n        data: {\n          jsonrpc: \"2.0\",\n          method: \"ui/notifications/tool-input\",\n          params: {\n            arguments: args,\n          },\n        },\n      },\n    ),\n  );\n};\n\nexport const fireToolResultNotification = (params: {\n  content: McpUiToolResultNotification[\"params\"][\"content\"];\n  structuredContent: Record<string, unknown>;\n  _meta?: Record<string, unknown>;\n}) => {\n  fireEvent(\n    window,\n    new MessageEvent<McpUiToolResultNotification & { jsonrpc: \"2.0\" }>(\n      \"message\",\n      {\n        source: window.parent,\n        data: {\n          jsonrpc: \"2.0\",\n          method: \"ui/notifications/tool-result\",\n          params,\n        },\n      },\n    ),\n  );\n};\n"]}

package/dist/web/hooks/use-call-tool.d.ts

@@ -36,13 +36,26 @@ type CallToolErrorState = {
     data: undefined;
     error: unknown;
 };
+/**
+ * State of a {@link useCallTool} invocation, discriminated by `status`.
+ * Use `isIdle` / `isPending` / `isSuccess` / `isError` for ergonomic conditional rendering.
+ */
 export type CallToolState<TData extends CallToolResponse = CallToolResponse> = CallToolIdleState | CallToolPendingState | CallToolSuccessState<TData> | CallToolErrorState;
+/**
+ * Optional callbacks fired around a {@link useCallTool} call.
+ * `onSettled` runs after success or error.
+ */
 export type SideEffects<ToolArgs, ToolResponse> = {
     onSuccess?: (data: ToolResponse, toolArgs: ToolArgs) => void;
     onError?: (error: unknown, toolArgs: ToolArgs) => void;
     onSettled?: (data: ToolResponse | undefined, error: unknown | undefined, toolArgs: ToolArgs) => void;
 };
 type IsArgsOptional<T> = [T] extends [null] ? true : HasRequiredKeys<T> extends false ? true : false;
+/**
+ * Fire-and-forget call function returned by {@link useCallTool}. Tracks state
+ * on the hook and supports optional {@link SideEffects} callbacks. Args are
+ * optional when the tool accepts none.
+ */
 export type CallToolFn<TArgs, TResponse> = IsArgsOptional<TArgs> extends true ? {
     (): void;
     (sideEffects: SideEffects<TArgs, TResponse>): void;
@@ -52,11 +65,43 @@ export type CallToolFn<TArgs, TResponse> = IsArgsOptional<TArgs> extends true ?
     (args: TArgs): void;
     (args: TArgs, sideEffects: SideEffects<TArgs, TResponse>): void;
 };
+/**
+ * Promise-returning call function returned by {@link useCallTool}. Rejects
+ * if the tool errors; use `try/catch` for error handling.
+ */
 export type CallToolAsyncFn<TArgs, TResponse> = IsArgsOptional<TArgs> extends true ? {
     (): Promise<TResponse>;
     (args: TArgs): Promise<TResponse>;
 } : (args: TArgs) => Promise<TResponse>;
 type ToolResponseSignature = Pick<CallToolResponse, "structuredContent" | "meta">;
+/**
+ * Call a server tool from a view and track its execution state.
+ *
+ * Returns the current {@link CallToolState} plus two callers: `callTool`
+ * (fire-and-forget, with optional {@link SideEffects}) and `callToolAsync`
+ * (promise-returning). If the same instance is invoked again while a call is
+ * in flight, the older response is dropped from the rendered state (but any
+ * `onSuccess` / `onError` / `onSettled` callbacks attached to it still fire).
+ *
+ * Pair with {@link useToolInfo} to read the result of the tool invocation
+ * that produced the current view. For end-to-end type safety across tool
+ * inputs and outputs, prefer the typed helpers produced by {@link generateHelpers}
+ * over calling this hook directly.
+ *
+ * @typeParam ToolArgs - Shape of the tool's input args (`null` for no-arg tools).
+ * @typeParam ToolResponse - Shape of the tool's `structuredContent` / `meta`.
+ *
+ * @example
+ * ```tsx
+ * const { callTool, isPending, data } = useCallTool<{ query: string }>("search");
+ *
+ * <button onClick={() => callTool({ query: "skybridge" }, {
+ *   onSuccess: (res) => console.log(res.structuredContent),
+ * })} />
+ * ```
+ *
+ * @see https://docs.skybridge.tech/api-reference/use-call-tool
+ */
 export declare const useCallTool: <ToolArgs extends CallToolArgs = null, ToolResponse extends Partial<ToolResponseSignature> = Record<string, never>>(name: string) => {
     callTool: CallToolFn<ToolArgs, CallToolResponse & ToolResponse>;
     callToolAsync: CallToolAsyncFn<ToolArgs, CallToolResponse & ToolResponse>;

package/dist/web/hooks/use-call-tool.js

@@ -1,5 +1,33 @@
 import { useRef, useState } from "react";
 import { getAdaptor, } from "../bridges/index.js";
+/**
+ * Call a server tool from a view and track its execution state.
+ *
+ * Returns the current {@link CallToolState} plus two callers: `callTool`
+ * (fire-and-forget, with optional {@link SideEffects}) and `callToolAsync`
+ * (promise-returning). If the same instance is invoked again while a call is
+ * in flight, the older response is dropped from the rendered state (but any
+ * `onSuccess` / `onError` / `onSettled` callbacks attached to it still fire).
+ *
+ * Pair with {@link useToolInfo} to read the result of the tool invocation
+ * that produced the current view. For end-to-end type safety across tool
+ * inputs and outputs, prefer the typed helpers produced by {@link generateHelpers}
+ * over calling this hook directly.
+ *
+ * @typeParam ToolArgs - Shape of the tool's input args (`null` for no-arg tools).
+ * @typeParam ToolResponse - Shape of the tool's `structuredContent` / `meta`.
+ *
+ * @example
+ * ```tsx
+ * const { callTool, isPending, data } = useCallTool<{ query: string }>("search");
+ *
+ * <button onClick={() => callTool({ query: "skybridge" }, {
+ *   onSuccess: (res) => console.log(res.structuredContent),
+ * })} />
+ * ```
+ *
+ * @see https://docs.skybridge.tech/api-reference/use-call-tool
+ */
 export const useCallTool = (name) => {
     const [{ status, data, error }, setCallToolState] = useState({ status: "idle", data: undefined, error: undefined });
     const callIdRef = useRef(0);

package/dist/web/hooks/use-call-tool.js.map

@@ -1 +1 @@
-{"version":3,"file":"use-call-tool.js","sourceRoot":"","sources":["../../../src/web/hooks/use-call-tool.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,OAAO,CAAC;AAEzC,OAAO,EAGL,UAAU,GACX,MAAM,qBAAqB,CAAC;AA2F7B,MAAM,CAAC,MAAM,WAAW,GAAG,CAIzB,IAAY,EACZ,EAAE;IAGF,MAAM,CAAC,EAAE,MAAM,EAAE,IAAI,EAAE,KAAK,EAAE,EAAE,gBAAgB,CAAC,GAAG,QAAQ,CAK1D,EAAE,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,SAAS,EAAE,KAAK,EAAE,SAAS,EAAE,CAAC,CAAC;IAEzD,MAAM,SAAS,GAAG,MAAM,CAAC,CAAC,CAAC,CAAC;IAC5B,MAAM,OAAO,GAAG,UAAU,EAAE,CAAC;IAE7B,MAAM,OAAO,GAAG,KAAK,EACnB,QAAkB,EACiB,EAAE;QACrC,MAAM,MAAM,GAAG,EAAE,SAAS,CAAC,OAAO,CAAC;QACnC,gBAAgB,CAAC,EAAE,MAAM,EAAE,SAAS,EAAE,IAAI,EAAE,SAAS,EAAE,KAAK,EAAE,SAAS,EAAE,CAAC,CAAC;QAE3E,IAAI,CAAC;YACH,MAAM,IAAI,GAAG,MAAM,OAAO,CAAC,QAAQ,CACjC,IAAI,EACJ,QAAQ,CACT,CAAC;YACF,IAAI,MAAM,KAAK,SAAS,CAAC,OAAO,EAAE,CAAC;gBACjC,gBAAgB,CAAC,EAAE,MAAM,EAAE,SAAS,EAAE,IAAI,EAAE,KAAK,EAAE,SAAS,EAAE,CAAC,CAAC;YAClE,CAAC;YAED,OAAO,IAAI,CAAC;QACd,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,IAAI,MAAM,KAAK,SAAS,CAAC,OAAO,EAAE,CAAC;gBACjC,gBAAgB,CAAC,EAAE,MAAM,EAAE,OAAO,EAAE,IAAI,EAAE,SAAS,EAAE,KAAK,EAAE,CAAC,CAAC;YAChE,CAAC;YACD,MAAM,KAAK,CAAC;QACd,CAAC;IACH,CAAC,CAAC;IAEF,MAAM,aAAa,GAAG,CAAC,CAAC,QAAmB,EAAE,EAAE;QAC7C,IAAI,QAAQ,KAAK,SAAS,EAAE,CAAC;YAC3B,OAAO,OAAO,CAAC,IAAgB,CAAC,CAAC;QACnC,CAAC;QACD,OAAO,OAAO,CAAC,QAAQ,CAAC,CAAC;IAC3B,CAAC,CAAwD,CAAC;IAE1D,MAAM,QAAQ,GAAG,CAAC,CAChB,QAAqE,EACrE,WAA6D,EAC7D,EAAE;QACF,IAAI,QAAkB,CAAC;QACvB,IACE,QAAQ;YACR,OAAO,QAAQ,KAAK,QAAQ;YAC5B,CAAC,WAAW,IAAI,QAAQ;gBACtB,SAAS,IAAI,QAAQ;gBACrB,WAAW,IAAI,QAAQ,CAAC,EAC1B,CAAC;YACD,QAAQ,GAAG,IAAgB,CAAC,CAAC,uBAAuB;YACpD,WAAW,GAAG,QAAQ,CAAC;QACzB,CAAC;aAAM,CAAC;YACN,QAAQ,GAAG,CAAC,QAAQ,KAAK,SAAS,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,QAAQ,CAAa,CAAC;QACpE,CAAC;QAED,OAAO,CAAC,QAAQ,CAAC;aACd,IAAI,CAAC,CAAC,IAAI,EAAE,EAAE;YACb,WAAW,EAAE,SAAS,EAAE,CAAC,IAAI,EAAE,QAAQ,CAAC,CAAC;YACzC,WAAW,EAAE,SAAS,EAAE,CAAC,IAAI,EAAE,SAAS,EAAE,QAAQ,CAAC,CAAC;QACtD,CAAC,CAAC;aACD,KAAK,CAAC,CAAC,KAAK,EAAE,EAAE;YACf,WAAW,EAAE,OAAO,EAAE,CAAC,KAAK,EAAE,QAAQ,CAAC,CAAC;YACxC,WAAW,EAAE,SAAS,EAAE,CAAC,SAAS,EAAE,KAAK,EAAE,QAAQ,CAAC,CAAC;QACvD,CAAC,CAAC,CAAC;IACP,CAAC,CAAmD,CAAC;IAErD,MAAM,aAAa,GAAG;QACpB,MAAM;QACN,IAAI;QACJ,KAAK;QACL,MAAM,EAAE,MAAM,KAAK,MAAM;QACzB,SAAS,EAAE,MAAM,KAAK,SAAS;QAC/B,SAAS,EAAE,MAAM,KAAK,SAAS;QAC/B,OAAO,EAAE,MAAM,KAAK,OAAO;KACe,CAAC;IAE7C,OAAO;QACL,GAAG,aAAa;QAChB,QAAQ;QACR,aAAa;KACd,CAAC;AACJ,CAAC,CAAC","sourcesContent":["import { useRef, useState } from \"react\";\n\nimport {\n  type CallToolArgs,\n  type CallToolResponse,\n  getAdaptor,\n} from \"../bridges/index.js\";\nimport type { HasRequiredKeys } from \"../types.js\";\n\ntype CallToolIdleState = {\n  status: \"idle\";\n  isIdle: true;\n  isPending: false;\n  isSuccess: false;\n  isError: false;\n  data: undefined;\n  error: undefined;\n};\n\ntype CallToolPendingState = {\n  status: \"pending\";\n  isIdle: false;\n  isPending: true;\n  isSuccess: false;\n  isError: false;\n  data: undefined;\n  error: undefined;\n};\n\ntype CallToolSuccessState<TData extends CallToolResponse = CallToolResponse> = {\n  status: \"success\";\n  isIdle: false;\n  isPending: false;\n  isSuccess: true;\n  isError: false;\n  data: TData;\n  error: undefined;\n};\n\ntype CallToolErrorState = {\n  status: \"error\";\n  isIdle: false;\n  isPending: false;\n  isSuccess: false;\n  isError: true;\n  data: undefined;\n  error: unknown;\n};\n\nexport type CallToolState<TData extends CallToolResponse = CallToolResponse> =\n  | CallToolIdleState\n  | CallToolPendingState\n  | CallToolSuccessState<TData>\n  | CallToolErrorState;\n\nexport type SideEffects<ToolArgs, ToolResponse> = {\n  onSuccess?: (data: ToolResponse, toolArgs: ToolArgs) => void;\n  onError?: (error: unknown, toolArgs: ToolArgs) => void;\n  onSettled?: (\n    data: ToolResponse | undefined,\n    error: unknown | undefined,\n    toolArgs: ToolArgs,\n  ) => void;\n};\n\ntype IsArgsOptional<T> = [T] extends [null]\n  ? true\n  : HasRequiredKeys<T> extends false\n    ? true\n    : false;\n\nexport type CallToolFn<TArgs, TResponse> =\n  IsArgsOptional<TArgs> extends true\n    ? {\n        (): void;\n        (sideEffects: SideEffects<TArgs, TResponse>): void;\n        (args: TArgs): void;\n        (args: TArgs, sideEffects: SideEffects<TArgs, TResponse>): void;\n      }\n    : {\n        (args: TArgs): void;\n        (args: TArgs, sideEffects: SideEffects<TArgs, TResponse>): void;\n      };\n\nexport type CallToolAsyncFn<TArgs, TResponse> =\n  IsArgsOptional<TArgs> extends true\n    ? {\n        (): Promise<TResponse>;\n        (args: TArgs): Promise<TResponse>;\n      }\n    : (args: TArgs) => Promise<TResponse>;\n\ntype ToolResponseSignature = Pick<\n  CallToolResponse,\n  \"structuredContent\" | \"meta\"\n>;\n\nexport const useCallTool = <\n  ToolArgs extends CallToolArgs = null,\n  ToolResponse extends Partial<ToolResponseSignature> = Record<string, never>,\n>(\n  name: string,\n) => {\n  type CombinedCallToolResponse = CallToolResponse & ToolResponse;\n\n  const [{ status, data, error }, setCallToolState] = useState<\n    Omit<\n      CallToolState<CombinedCallToolResponse>,\n      \"isIdle\" | \"isPending\" | \"isSuccess\" | \"isError\"\n    >\n  >({ status: \"idle\", data: undefined, error: undefined });\n\n  const callIdRef = useRef(0);\n  const adaptor = getAdaptor();\n\n  const execute = async (\n    toolArgs: ToolArgs,\n  ): Promise<CombinedCallToolResponse> => {\n    const callId = ++callIdRef.current;\n    setCallToolState({ status: \"pending\", data: undefined, error: undefined });\n\n    try {\n      const data = await adaptor.callTool<ToolArgs, CombinedCallToolResponse>(\n        name,\n        toolArgs,\n      );\n      if (callId === callIdRef.current) {\n        setCallToolState({ status: \"success\", data, error: undefined });\n      }\n\n      return data;\n    } catch (error) {\n      if (callId === callIdRef.current) {\n        setCallToolState({ status: \"error\", data: undefined, error });\n      }\n      throw error;\n    }\n  };\n\n  const callToolAsync = ((toolArgs?: ToolArgs) => {\n    if (toolArgs === undefined) {\n      return execute(null as ToolArgs);\n    }\n    return execute(toolArgs);\n  }) as CallToolAsyncFn<ToolArgs, CombinedCallToolResponse>;\n\n  const callTool = ((\n    firstArg?: ToolArgs | SideEffects<ToolArgs, CombinedCallToolResponse>,\n    sideEffects?: SideEffects<ToolArgs, CombinedCallToolResponse>,\n  ) => {\n    let toolArgs: ToolArgs;\n    if (\n      firstArg &&\n      typeof firstArg === \"object\" &&\n      (\"onSuccess\" in firstArg ||\n        \"onError\" in firstArg ||\n        \"onSettled\" in firstArg)\n    ) {\n      toolArgs = null as ToolArgs; // no toolArgs provided\n      sideEffects = firstArg;\n    } else {\n      toolArgs = (firstArg === undefined ? null : firstArg) as ToolArgs;\n    }\n\n    execute(toolArgs)\n      .then((data) => {\n        sideEffects?.onSuccess?.(data, toolArgs);\n        sideEffects?.onSettled?.(data, undefined, toolArgs);\n      })\n      .catch((error) => {\n        sideEffects?.onError?.(error, toolArgs);\n        sideEffects?.onSettled?.(undefined, error, toolArgs);\n      });\n  }) as CallToolFn<ToolArgs, CombinedCallToolResponse>;\n\n  const callToolState = {\n    status,\n    data,\n    error,\n    isIdle: status === \"idle\",\n    isPending: status === \"pending\",\n    isSuccess: status === \"success\",\n    isError: status === \"error\",\n  } as CallToolState<CombinedCallToolResponse>;\n\n  return {\n    ...callToolState,\n    callTool,\n    callToolAsync,\n  };\n};\n"]}
+{"version":3,"file":"use-call-tool.js","sourceRoot":"","sources":["../../../src/web/hooks/use-call-tool.ts"],"names":[],"mappings":"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","sourcesContent":["import { useRef, useState } from \"react\";\n\nimport {\n  type CallToolArgs,\n  type CallToolResponse,\n  getAdaptor,\n} from \"../bridges/index.js\";\nimport type { HasRequiredKeys } from \"../types.js\";\n\ntype CallToolIdleState = {\n  status: \"idle\";\n  isIdle: true;\n  isPending: false;\n  isSuccess: false;\n  isError: false;\n  data: undefined;\n  error: undefined;\n};\n\ntype CallToolPendingState = {\n  status: \"pending\";\n  isIdle: false;\n  isPending: true;\n  isSuccess: false;\n  isError: false;\n  data: undefined;\n  error: undefined;\n};\n\ntype CallToolSuccessState<TData extends CallToolResponse = CallToolResponse> = {\n  status: \"success\";\n  isIdle: false;\n  isPending: false;\n  isSuccess: true;\n  isError: false;\n  data: TData;\n  error: undefined;\n};\n\ntype CallToolErrorState = {\n  status: \"error\";\n  isIdle: false;\n  isPending: false;\n  isSuccess: false;\n  isError: true;\n  data: undefined;\n  error: unknown;\n};\n\n/**\n * State of a {@link useCallTool} invocation, discriminated by `status`.\n * Use `isIdle` / `isPending` / `isSuccess` / `isError` for ergonomic conditional rendering.\n */\nexport type CallToolState<TData extends CallToolResponse = CallToolResponse> =\n  | CallToolIdleState\n  | CallToolPendingState\n  | CallToolSuccessState<TData>\n  | CallToolErrorState;\n\n/**\n * Optional callbacks fired around a {@link useCallTool} call.\n * `onSettled` runs after success or error.\n */\nexport type SideEffects<ToolArgs, ToolResponse> = {\n  onSuccess?: (data: ToolResponse, toolArgs: ToolArgs) => void;\n  onError?: (error: unknown, toolArgs: ToolArgs) => void;\n  onSettled?: (\n    data: ToolResponse | undefined,\n    error: unknown | undefined,\n    toolArgs: ToolArgs,\n  ) => void;\n};\n\ntype IsArgsOptional<T> = [T] extends [null]\n  ? true\n  : HasRequiredKeys<T> extends false\n    ? true\n    : false;\n\n/**\n * Fire-and-forget call function returned by {@link useCallTool}. Tracks state\n * on the hook and supports optional {@link SideEffects} callbacks. Args are\n * optional when the tool accepts none.\n */\nexport type CallToolFn<TArgs, TResponse> =\n  IsArgsOptional<TArgs> extends true\n    ? {\n        (): void;\n        (sideEffects: SideEffects<TArgs, TResponse>): void;\n        (args: TArgs): void;\n        (args: TArgs, sideEffects: SideEffects<TArgs, TResponse>): void;\n      }\n    : {\n        (args: TArgs): void;\n        (args: TArgs, sideEffects: SideEffects<TArgs, TResponse>): void;\n      };\n\n/**\n * Promise-returning call function returned by {@link useCallTool}. Rejects\n * if the tool errors; use `try/catch` for error handling.\n */\nexport type CallToolAsyncFn<TArgs, TResponse> =\n  IsArgsOptional<TArgs> extends true\n    ? {\n        (): Promise<TResponse>;\n        (args: TArgs): Promise<TResponse>;\n      }\n    : (args: TArgs) => Promise<TResponse>;\n\ntype ToolResponseSignature = Pick<\n  CallToolResponse,\n  \"structuredContent\" | \"meta\"\n>;\n\n/**\n * Call a server tool from a view and track its execution state.\n *\n * Returns the current {@link CallToolState} plus two callers: `callTool`\n * (fire-and-forget, with optional {@link SideEffects}) and `callToolAsync`\n * (promise-returning). If the same instance is invoked again while a call is\n * in flight, the older response is dropped from the rendered state (but any\n * `onSuccess` / `onError` / `onSettled` callbacks attached to it still fire).\n *\n * Pair with {@link useToolInfo} to read the result of the tool invocation\n * that produced the current view. For end-to-end type safety across tool\n * inputs and outputs, prefer the typed helpers produced by {@link generateHelpers}\n * over calling this hook directly.\n *\n * @typeParam ToolArgs - Shape of the tool's input args (`null` for no-arg tools).\n * @typeParam ToolResponse - Shape of the tool's `structuredContent` / `meta`.\n *\n * @example\n * ```tsx\n * const { callTool, isPending, data } = useCallTool<{ query: string }>(\"search\");\n *\n * <button onClick={() => callTool({ query: \"skybridge\" }, {\n *   onSuccess: (res) => console.log(res.structuredContent),\n * })} />\n * ```\n *\n * @see https://docs.skybridge.tech/api-reference/use-call-tool\n */\nexport const useCallTool = <\n  ToolArgs extends CallToolArgs = null,\n  ToolResponse extends Partial<ToolResponseSignature> = Record<string, never>,\n>(\n  name: string,\n) => {\n  type CombinedCallToolResponse = CallToolResponse & ToolResponse;\n\n  const [{ status, data, error }, setCallToolState] = useState<\n    Omit<\n      CallToolState<CombinedCallToolResponse>,\n      \"isIdle\" | \"isPending\" | \"isSuccess\" | \"isError\"\n    >\n  >({ status: \"idle\", data: undefined, error: undefined });\n\n  const callIdRef = useRef(0);\n  const adaptor = getAdaptor();\n\n  const execute = async (\n    toolArgs: ToolArgs,\n  ): Promise<CombinedCallToolResponse> => {\n    const callId = ++callIdRef.current;\n    setCallToolState({ status: \"pending\", data: undefined, error: undefined });\n\n    try {\n      const data = await adaptor.callTool<ToolArgs, CombinedCallToolResponse>(\n        name,\n        toolArgs,\n      );\n      if (callId === callIdRef.current) {\n        setCallToolState({ status: \"success\", data, error: undefined });\n      }\n\n      return data;\n    } catch (error) {\n      if (callId === callIdRef.current) {\n        setCallToolState({ status: \"error\", data: undefined, error });\n      }\n      throw error;\n    }\n  };\n\n  const callToolAsync = ((toolArgs?: ToolArgs) => {\n    if (toolArgs === undefined) {\n      return execute(null as ToolArgs);\n    }\n    return execute(toolArgs);\n  }) as CallToolAsyncFn<ToolArgs, CombinedCallToolResponse>;\n\n  const callTool = ((\n    firstArg?: ToolArgs | SideEffects<ToolArgs, CombinedCallToolResponse>,\n    sideEffects?: SideEffects<ToolArgs, CombinedCallToolResponse>,\n  ) => {\n    let toolArgs: ToolArgs;\n    if (\n      firstArg &&\n      typeof firstArg === \"object\" &&\n      (\"onSuccess\" in firstArg ||\n        \"onError\" in firstArg ||\n        \"onSettled\" in firstArg)\n    ) {\n      toolArgs = null as ToolArgs; // no toolArgs provided\n      sideEffects = firstArg;\n    } else {\n      toolArgs = (firstArg === undefined ? null : firstArg) as ToolArgs;\n    }\n\n    execute(toolArgs)\n      .then((data) => {\n        sideEffects?.onSuccess?.(data, toolArgs);\n        sideEffects?.onSettled?.(data, undefined, toolArgs);\n      })\n      .catch((error) => {\n        sideEffects?.onError?.(error, toolArgs);\n        sideEffects?.onSettled?.(undefined, error, toolArgs);\n      });\n  }) as CallToolFn<ToolArgs, CombinedCallToolResponse>;\n\n  const callToolState = {\n    status,\n    data,\n    error,\n    isIdle: status === \"idle\",\n    isPending: status === \"pending\",\n    isSuccess: status === \"success\",\n    isError: status === \"error\",\n  } as CallToolState<CombinedCallToolResponse>;\n\n  return {\n    ...callToolState,\n    callTool,\n    callToolAsync,\n  };\n};\n"]}

package/dist/web/hooks/use-call-tool.test.js

@@ -20,8 +20,27 @@ describe("useCallTool - onSuccess callback", () => {
         content: [{ type: "text", text: "test result" }],
         structuredContent: { result: "test" },
         isError: false,
+        meta: {},
     };
     const error = new Error("test error");
+    it("should normalize _meta to meta when SDK returns _meta instead of meta", async () => {
+        const rawSdkResponse = {
+            content: [{ type: "text", text: "result" }],
+            structuredContent: { value: 1 },
+            isError: false,
+            _meta: { secret: "only visible to widget" },
+        };
+        OpenaiMock.callTool.mockResolvedValueOnce(rawSdkResponse);
+        const { result } = renderHook(() => useCallTool(toolName));
+        await act(async () => {
+            result.current.callTool(args);
+        });
+        await waitFor(() => {
+            expect(result.current.data).toMatchObject({
+                meta: { secret: "only visible to widget" },
+            });
+        });
+    });
     it("should call window.openai.callTool with correct arguments", async () => {
         const { result } = renderHook(() => useCallTool(toolName));
         await act(async () => {
@@ -101,8 +120,14 @@ describe("useCallTool - onSuccess callback", () => {
     });
     it("should always return last call started state", async () => {
         const { result } = renderHook(() => useCallTool(toolName));
-        const firstCallData = { ...data, result: "first call result" };
-        const secondCallData = { ...data, result: "second call result" };
+        const firstCallData = {
+            ...data,
+            structuredContent: { result: "first call result" },
+        };
+        const secondCallData = {
+            ...data,
+            structuredContent: { result: "second call result" },
+        };
         const { promise: firstCallToolPromise, resolve: resolveFirstCallTool } = Promise.withResolvers();
         const { promise: secondCallToolPromise, resolve: resolveSecondCallTool } = Promise.withResolvers();
         OpenaiMock.callTool