skybridge 1.0.1 → 1.0.3

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":"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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\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-display-mode.d.ts

@@ -1,4 +1,24 @@
 import type { RequestDisplayMode } from "../bridges/types.js";
+/**
+ * Read and change the view's display mode (`"inline"`, `"pip"`, `"fullscreen"`).
+ *
+ * Returns a tuple `[displayMode, setDisplayMode]`. `setDisplayMode` asks the
+ * host to switch modes — the host returns the mode it actually applied, which
+ * may differ from the request. The reported value also updates when the host
+ * changes the mode on its own (e.g. user expands the widget).
+ *
+ * `"modal"` is reachable via {@link useRequestModal}, not this hook. To react
+ * to layout changes that come with display-mode switches (e.g. `maxHeight`),
+ * pair with {@link useLayout}.
+ *
+ * @example
+ * ```tsx
+ * const [mode, setMode] = useDisplayMode();
+ * <button onClick={() => setMode("fullscreen")}>Expand</button>
+ * ```
+ *
+ * @see https://docs.skybridge.tech/api-reference/use-display-mode
+ */
 export declare function useDisplayMode(): readonly [import("../index.js").DisplayMode, (mode: RequestDisplayMode) => Promise<{
     mode: RequestDisplayMode;
 }>];

package/dist/web/hooks/use-display-mode.js

@@ -1,5 +1,25 @@
 import { useCallback } from "react";
 import { getAdaptor, useHostContext } from "../bridges/index.js";
+/**
+ * Read and change the view's display mode (`"inline"`, `"pip"`, `"fullscreen"`).
+ *
+ * Returns a tuple `[displayMode, setDisplayMode]`. `setDisplayMode` asks the
+ * host to switch modes — the host returns the mode it actually applied, which
+ * may differ from the request. The reported value also updates when the host
+ * changes the mode on its own (e.g. user expands the widget).
+ *
+ * `"modal"` is reachable via {@link useRequestModal}, not this hook. To react
+ * to layout changes that come with display-mode switches (e.g. `maxHeight`),
+ * pair with {@link useLayout}.
+ *
+ * @example
+ * ```tsx
+ * const [mode, setMode] = useDisplayMode();
+ * <button onClick={() => setMode("fullscreen")}>Expand</button>
+ * ```
+ *
+ * @see https://docs.skybridge.tech/api-reference/use-display-mode
+ */
 export function useDisplayMode() {
     const displayMode = useHostContext("displayMode");
     const adaptor = getAdaptor();

package/dist/web/hooks/use-display-mode.js.map

@@ -1 +1 @@
-{"version":3,"file":"use-display-mode.js","sourceRoot":"","sources":["../../../src/web/hooks/use-display-mode.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,MAAM,OAAO,CAAC;AACpC,OAAO,EAAE,UAAU,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAC;AAGjE,MAAM,UAAU,cAAc;IAC5B,MAAM,WAAW,GAAG,cAAc,CAAC,aAAa,CAAC,CAAC;IAClD,MAAM,OAAO,GAAG,UAAU,EAAE,CAAC;IAC7B,MAAM,cAAc,GAAG,WAAW,CAChC,CAAC,IAAwB,EAAE,EAAE,CAAC,OAAO,CAAC,kBAAkB,CAAC,IAAI,CAAC,EAC9D,CAAC,OAAO,CAAC,CACV,CAAC;IAEF,OAAO,CAAC,WAAW,EAAE,cAAc,CAAU,CAAC;AAChD,CAAC","sourcesContent":["import { useCallback } from \"react\";\nimport { getAdaptor, useHostContext } from \"../bridges/index.js\";\nimport type { RequestDisplayMode } from \"../bridges/types.js\";\n\nexport function useDisplayMode() {\n  const displayMode = useHostContext(\"displayMode\");\n  const adaptor = getAdaptor();\n  const setDisplayMode = useCallback(\n    (mode: RequestDisplayMode) => adaptor.requestDisplayMode(mode),\n    [adaptor],\n  );\n\n  return [displayMode, setDisplayMode] as const;\n}\n"]}
+{"version":3,"file":"use-display-mode.js","sourceRoot":"","sources":["../../../src/web/hooks/use-display-mode.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,MAAM,OAAO,CAAC;AACpC,OAAO,EAAE,UAAU,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAC;AAGjE;;;;;;;;;;;;;;;;;;;GAmBG;AACH,MAAM,UAAU,cAAc;IAC5B,MAAM,WAAW,GAAG,cAAc,CAAC,aAAa,CAAC,CAAC;IAClD,MAAM,OAAO,GAAG,UAAU,EAAE,CAAC;IAC7B,MAAM,cAAc,GAAG,WAAW,CAChC,CAAC,IAAwB,EAAE,EAAE,CAAC,OAAO,CAAC,kBAAkB,CAAC,IAAI,CAAC,EAC9D,CAAC,OAAO,CAAC,CACV,CAAC;IAEF,OAAO,CAAC,WAAW,EAAE,cAAc,CAAU,CAAC;AAChD,CAAC","sourcesContent":["import { useCallback } from \"react\";\nimport { getAdaptor, useHostContext } from \"../bridges/index.js\";\nimport type { RequestDisplayMode } from \"../bridges/types.js\";\n\n/**\n * Read and change the view's display mode (`\"inline\"`, `\"pip\"`, `\"fullscreen\"`).\n *\n * Returns a tuple `[displayMode, setDisplayMode]`. `setDisplayMode` asks the\n * host to switch modes — the host returns the mode it actually applied, which\n * may differ from the request. The reported value also updates when the host\n * changes the mode on its own (e.g. user expands the widget).\n *\n * `\"modal\"` is reachable via {@link useRequestModal}, not this hook. To react\n * to layout changes that come with display-mode switches (e.g. `maxHeight`),\n * pair with {@link useLayout}.\n *\n * @example\n * ```tsx\n * const [mode, setMode] = useDisplayMode();\n * <button onClick={() => setMode(\"fullscreen\")}>Expand</button>\n * ```\n *\n * @see https://docs.skybridge.tech/api-reference/use-display-mode\n */\nexport function useDisplayMode() {\n  const displayMode = useHostContext(\"displayMode\");\n  const adaptor = getAdaptor();\n  const setDisplayMode = useCallback(\n    (mode: RequestDisplayMode) => adaptor.requestDisplayMode(mode),\n    [adaptor],\n  );\n\n  return [displayMode, setDisplayMode] as const;\n}\n"]}

package/dist/web/hooks/use-download.d.ts

@@ -0,0 +1,5 @@
+import type { DownloadParams, DownloadResult } from "../bridges/types.js";
+export type DownloadFn = (params: DownloadParams) => Promise<DownloadResult>;
+export declare function useDownload(): {
+    download: DownloadFn;
+};

package/dist/web/hooks/use-download.js

@@ -0,0 +1,8 @@
+import { useCallback } from "react";
+import { getAdaptor } from "../bridges/index.js";
+export function useDownload() {
+    const adaptor = getAdaptor();
+    const download = useCallback((params) => adaptor.download(params), [adaptor]);
+    return { download };
+}
+//# sourceMappingURL=use-download.js.map

package/dist/web/hooks/use-download.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"use-download.js","sourceRoot":"","sources":["../../../src/web/hooks/use-download.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,MAAM,OAAO,CAAC;AACpC,OAAO,EAAE,UAAU,EAAE,MAAM,qBAAqB,CAAC;AAKjD,MAAM,UAAU,WAAW;IACzB,MAAM,OAAO,GAAG,UAAU,EAAE,CAAC;IAC7B,MAAM,QAAQ,GAAG,WAAW,CAC1B,CAAC,MAAM,EAAE,EAAE,CAAC,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAC,EACpC,CAAC,OAAO,CAAC,CACV,CAAC;IAEF,OAAO,EAAE,QAAQ,EAAE,CAAC;AACtB,CAAC","sourcesContent":["import { useCallback } from \"react\";\nimport { getAdaptor } from \"../bridges/index.js\";\nimport type { DownloadParams, DownloadResult } from \"../bridges/types.js\";\n\nexport type DownloadFn = (params: DownloadParams) => Promise<DownloadResult>;\n\nexport function useDownload(): { download: DownloadFn } {\n  const adaptor = getAdaptor();\n  const download = useCallback<DownloadFn>(\n    (params) => adaptor.download(params),\n    [adaptor],\n  );\n\n  return { download };\n}\n"]}

package/dist/web/hooks/use-download.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/web/hooks/use-download.test.js

@@ -0,0 +1,95 @@
+import { renderHook, waitFor } from "@testing-library/react";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import { AppsSdkAdaptor } from "../bridges/apps-sdk/adaptor.js";
+import { McpAppBridge } from "../bridges/mcp-app/bridge.js";
+import { getMcpAppHostPostMessageMock, MockResizeObserver, } from "./test/utils.js";
+import { useDownload } from "./use-download.js";
+const params = {
+    contents: [
+        {
+            type: "resource",
+            resource: {
+                uri: "file:///export.json",
+                mimeType: "application/json",
+                text: '{"hello":"world"}',
+            },
+        },
+    ],
+};
+describe("useDownload", () => {
+    describe("apps-sdk host", () => {
+        beforeEach(() => {
+            vi.stubGlobal("openai", {});
+            vi.stubGlobal("skybridge", { hostType: "apps-sdk" });
+        });
+        afterEach(() => {
+            vi.unstubAllGlobals();
+            vi.resetAllMocks();
+            AppsSdkAdaptor.resetInstance();
+        });
+        it("returns { isError: true } and logs an error", async () => {
+            const errorSpy = vi.spyOn(console, "error").mockImplementation(() => { });
+            const { result } = renderHook(() => useDownload());
+            const res = await result.current.download(params);
+            expect(res).toEqual({ isError: true });
+            expect(errorSpy).toHaveBeenCalledWith(expect.stringContaining("not supported on Apps SDK"));
+        });
+    });
+    describe("mcp-app host without downloadFile capability", () => {
+        beforeEach(() => {
+            vi.stubGlobal("skybridge", { hostType: "mcp-app" });
+            vi.stubGlobal("ResizeObserver", MockResizeObserver);
+            vi.stubGlobal("parent", { postMessage: getMcpAppHostPostMessageMock() });
+        });
+        afterEach(async () => {
+            vi.unstubAllGlobals();
+            vi.resetAllMocks();
+            McpAppBridge.resetInstance();
+        });
+        it("returns { isError: true } and logs an error", async () => {
+            const errorSpy = vi.spyOn(console, "error").mockImplementation(() => { });
+            const { result } = renderHook(() => useDownload());
+            const res = await result.current.download(params);
+            expect(res).toEqual({ isError: true });
+            expect(errorSpy).toHaveBeenCalledWith(expect.stringContaining("does not support ui/download-file"));
+        });
+    });
+    describe("mcp-app host with downloadFile capability", () => {
+        let postMessageMock;
+        beforeEach(() => {
+            vi.stubGlobal("skybridge", { hostType: "mcp-app" });
+            vi.stubGlobal("ResizeObserver", MockResizeObserver);
+            postMessageMock = getMcpAppHostPostMessageMock({}, { hostCapabilities: { downloadFile: {} } });
+            vi.stubGlobal("parent", { postMessage: postMessageMock });
+        });
+        afterEach(async () => {
+            vi.unstubAllGlobals();
+            vi.resetAllMocks();
+            McpAppBridge.resetInstance();
+        });
+        it("sends ui/download-file with the provided contents", async () => {
+            const { result } = renderHook(() => useDownload());
+            const res = await result.current.download(params);
+            expect(res).toEqual({});
+            await waitFor(() => {
+                expect(postMessageMock).toHaveBeenCalledWith(expect.objectContaining({
+                    jsonrpc: "2.0",
+                    method: "ui/download-file",
+                    params,
+                }), "*");
+            });
+        });
+        it("returns { isError: true } when the host denies the request", async () => {
+            McpAppBridge.resetInstance();
+            postMessageMock = getMcpAppHostPostMessageMock({}, {
+                hostCapabilities: { downloadFile: {} },
+                downloadFileResult: { isError: true },
+            });
+            vi.stubGlobal("parent", { postMessage: postMessageMock });
+            const { result } = renderHook(() => useDownload());
+            const res = await result.current.download(params);
+            expect(res).toEqual({ isError: true });
+        });
+    });
+});
+//# sourceMappingURL=use-download.test.js.map

package/dist/web/hooks/use-download.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"use-download.test.js","sourceRoot":"","sources":["../../../src/web/hooks/use-download.test.ts"],"names":[],"mappings":"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","sourcesContent":["import { renderHook, waitFor } from \"@testing-library/react\";\nimport { afterEach, beforeEach, describe, expect, it, vi } from \"vitest\";\nimport { AppsSdkAdaptor } from \"../bridges/apps-sdk/adaptor.js\";\nimport { McpAppBridge } from \"../bridges/mcp-app/bridge.js\";\nimport type { DownloadParams } from \"../bridges/types.js\";\nimport {\n  getMcpAppHostPostMessageMock,\n  MockResizeObserver,\n} from \"./test/utils.js\";\nimport { useDownload } from \"./use-download.js\";\n\nconst params: DownloadParams = {\n  contents: [\n    {\n      type: \"resource\",\n      resource: {\n        uri: \"file:///export.json\",\n        mimeType: \"application/json\",\n        text: '{\"hello\":\"world\"}',\n      },\n    },\n  ],\n};\n\ndescribe(\"useDownload\", () => {\n  describe(\"apps-sdk host\", () => {\n    beforeEach(() => {\n      vi.stubGlobal(\"openai\", {});\n      vi.stubGlobal(\"skybridge\", { hostType: \"apps-sdk\" });\n    });\n\n    afterEach(() => {\n      vi.unstubAllGlobals();\n      vi.resetAllMocks();\n      AppsSdkAdaptor.resetInstance();\n    });\n\n    it(\"returns { isError: true } and logs an error\", async () => {\n      const errorSpy = vi.spyOn(console, \"error\").mockImplementation(() => {});\n      const { result } = renderHook(() => useDownload());\n\n      const res = await result.current.download(params);\n\n      expect(res).toEqual({ isError: true });\n      expect(errorSpy).toHaveBeenCalledWith(\n        expect.stringContaining(\"not supported on Apps SDK\"),\n      );\n    });\n  });\n\n  describe(\"mcp-app host without downloadFile capability\", () => {\n    beforeEach(() => {\n      vi.stubGlobal(\"skybridge\", { hostType: \"mcp-app\" });\n      vi.stubGlobal(\"ResizeObserver\", MockResizeObserver);\n      vi.stubGlobal(\"parent\", { postMessage: getMcpAppHostPostMessageMock() });\n    });\n\n    afterEach(async () => {\n      vi.unstubAllGlobals();\n      vi.resetAllMocks();\n      McpAppBridge.resetInstance();\n    });\n\n    it(\"returns { isError: true } and logs an error\", async () => {\n      const errorSpy = vi.spyOn(console, \"error\").mockImplementation(() => {});\n      const { result } = renderHook(() => useDownload());\n\n      const res = await result.current.download(params);\n\n      expect(res).toEqual({ isError: true });\n      expect(errorSpy).toHaveBeenCalledWith(\n        expect.stringContaining(\"does not support ui/download-file\"),\n      );\n    });\n  });\n\n  describe(\"mcp-app host with downloadFile capability\", () => {\n    let postMessageMock: ReturnType<typeof getMcpAppHostPostMessageMock>;\n\n    beforeEach(() => {\n      vi.stubGlobal(\"skybridge\", { hostType: \"mcp-app\" });\n      vi.stubGlobal(\"ResizeObserver\", MockResizeObserver);\n      postMessageMock = getMcpAppHostPostMessageMock(\n        {},\n        { hostCapabilities: { downloadFile: {} } },\n      );\n      vi.stubGlobal(\"parent\", { postMessage: postMessageMock });\n    });\n\n    afterEach(async () => {\n      vi.unstubAllGlobals();\n      vi.resetAllMocks();\n      McpAppBridge.resetInstance();\n    });\n\n    it(\"sends ui/download-file with the provided contents\", async () => {\n      const { result } = renderHook(() => useDownload());\n\n      const res = await result.current.download(params);\n\n      expect(res).toEqual({});\n      await waitFor(() => {\n        expect(postMessageMock).toHaveBeenCalledWith(\n          expect.objectContaining({\n            jsonrpc: \"2.0\",\n            method: \"ui/download-file\",\n            params,\n          }),\n          \"*\",\n        );\n      });\n    });\n\n    it(\"returns { isError: true } when the host denies the request\", async () => {\n      McpAppBridge.resetInstance();\n      postMessageMock = getMcpAppHostPostMessageMock(\n        {},\n        {\n          hostCapabilities: { downloadFile: {} },\n          downloadFileResult: { isError: true },\n        },\n      );\n      vi.stubGlobal(\"parent\", { postMessage: postMessageMock });\n\n      const { result } = renderHook(() => useDownload());\n\n      const res = await result.current.download(params);\n\n      expect(res).toEqual({ isError: true });\n    });\n  });\n});\n"]}

package/dist/web/hooks/use-files.d.ts

@@ -1,3 +1,35 @@
+/**
+ * File operations bound to the current host: `upload` a `File`, resolve a
+ * `downloadUrl` for an uploaded file, and `selectFiles` to open the host's
+ * native file picker.
+ *
+ * Currently Apps-SDK-only — calling any of these from MCP Apps throws.
+ * `selectFiles` additionally requires a ChatGPT host version that exposes the
+ * picker; it throws if the capability is unavailable.
+ *
+ * `upload` returns `FileMetadata` (`fileId`, optional `fileName`, `mimeType`).
+ * To pass an uploaded file to a tool whose input uses {@link FileRef}, first
+ * call `getDownloadUrl` and then build the ref yourself — field names differ
+ * (camelCase on the client, snake_case in the schema) and `download_url` is
+ * required.
+ *
+ * @example
+ * ```tsx
+ * const { upload, getDownloadUrl } = useFiles();
+ * const meta = await upload(file);
+ * const { downloadUrl } = await getDownloadUrl(meta);
+ * callTool({
+ *   document: {
+ *     file_id: meta.fileId,
+ *     download_url: downloadUrl,
+ *     file_name: meta.fileName,
+ *     mime_type: meta.mimeType,
+ *   },
+ * });
+ * ```
+ *
+ * @see https://docs.skybridge.tech/api-reference/use-files
+ */
 export declare function useFiles(): {
     upload: (file: File, options?: import("../index.js").UploadFileOptions) => Promise<import("../index.js").FileMetadata>;
     getDownloadUrl: (file: import("../index.js").FileMetadata) => Promise<{

package/dist/web/hooks/use-files.js

@@ -1,4 +1,36 @@
 import { getAdaptor } from "../bridges/index.js";
+/**
+ * File operations bound to the current host: `upload` a `File`, resolve a
+ * `downloadUrl` for an uploaded file, and `selectFiles` to open the host's
+ * native file picker.
+ *
+ * Currently Apps-SDK-only — calling any of these from MCP Apps throws.
+ * `selectFiles` additionally requires a ChatGPT host version that exposes the
+ * picker; it throws if the capability is unavailable.
+ *
+ * `upload` returns `FileMetadata` (`fileId`, optional `fileName`, `mimeType`).
+ * To pass an uploaded file to a tool whose input uses {@link FileRef}, first
+ * call `getDownloadUrl` and then build the ref yourself — field names differ
+ * (camelCase on the client, snake_case in the schema) and `download_url` is
+ * required.
+ *
+ * @example
+ * ```tsx
+ * const { upload, getDownloadUrl } = useFiles();
+ * const meta = await upload(file);
+ * const { downloadUrl } = await getDownloadUrl(meta);
+ * callTool({
+ *   document: {
+ *     file_id: meta.fileId,
+ *     download_url: downloadUrl,
+ *     file_name: meta.fileName,
+ *     mime_type: meta.mimeType,
+ *   },
+ * });
+ * ```
+ *
+ * @see https://docs.skybridge.tech/api-reference/use-files
+ */
 export function useFiles() {
     const adaptor = getAdaptor();
     return {

package/dist/web/hooks/use-files.js.map

@@ -1 +1 @@
-{"version":3,"file":"use-files.js","sourceRoot":"","sources":["../../../src/web/hooks/use-files.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,qBAAqB,CAAC;AAEjD,MAAM,UAAU,QAAQ;IACtB,MAAM,OAAO,GAAG,UAAU,EAAE,CAAC;IAC7B,OAAO;QACL,MAAM,EAAE,OAAO,CAAC,UAAU;QAC1B,cAAc,EAAE,OAAO,CAAC,kBAAkB;QAC1C,WAAW,EAAE,OAAO,CAAC,WAAW;KACjC,CAAC;AACJ,CAAC","sourcesContent":["import { getAdaptor } from \"../bridges/index.js\";\n\nexport function useFiles() {\n  const adaptor = getAdaptor();\n  return {\n    upload: adaptor.uploadFile,\n    getDownloadUrl: adaptor.getFileDownloadUrl,\n    selectFiles: adaptor.selectFiles,\n  };\n}\n"]}
+{"version":3,"file":"use-files.js","sourceRoot":"","sources":["../../../src/web/hooks/use-files.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,qBAAqB,CAAC;AAEjD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AACH,MAAM,UAAU,QAAQ;IACtB,MAAM,OAAO,GAAG,UAAU,EAAE,CAAC;IAC7B,OAAO;QACL,MAAM,EAAE,OAAO,CAAC,UAAU;QAC1B,cAAc,EAAE,OAAO,CAAC,kBAAkB;QAC1C,WAAW,EAAE,OAAO,CAAC,WAAW;KACjC,CAAC;AACJ,CAAC","sourcesContent":["import { getAdaptor } from \"../bridges/index.js\";\n\n/**\n * File operations bound to the current host: `upload` a `File`, resolve a\n * `downloadUrl` for an uploaded file, and `selectFiles` to open the host's\n * native file picker.\n *\n * Currently Apps-SDK-only — calling any of these from MCP Apps throws.\n * `selectFiles` additionally requires a ChatGPT host version that exposes the\n * picker; it throws if the capability is unavailable.\n *\n * `upload` returns `FileMetadata` (`fileId`, optional `fileName`, `mimeType`).\n * To pass an uploaded file to a tool whose input uses {@link FileRef}, first\n * call `getDownloadUrl` and then build the ref yourself — field names differ\n * (camelCase on the client, snake_case in the schema) and `download_url` is\n * required.\n *\n * @example\n * ```tsx\n * const { upload, getDownloadUrl } = useFiles();\n * const meta = await upload(file);\n * const { downloadUrl } = await getDownloadUrl(meta);\n * callTool({\n *   document: {\n *     file_id: meta.fileId,\n *     download_url: downloadUrl,\n *     file_name: meta.fileName,\n *     mime_type: meta.mimeType,\n *   },\n * });\n * ```\n *\n * @see https://docs.skybridge.tech/api-reference/use-files\n */\nexport function useFiles() {\n  const adaptor = getAdaptor();\n  return {\n    upload: adaptor.uploadFile,\n    getDownloadUrl: adaptor.getFileDownloadUrl,\n    selectFiles: adaptor.selectFiles,\n  };\n}\n"]}

package/dist/web/hooks/use-layout.d.ts

@@ -18,5 +18,7 @@ export type LayoutState = {
  * // Respect safe area insets
  * const paddingTop = safeArea.insets.top;
  * ```
+ *
+ * @see https://docs.skybridge.tech/api-reference/use-layout
  */
 export declare function useLayout(): LayoutState;

package/dist/web/hooks/use-layout.js

@@ -13,6 +13,8 @@ import { useHostContext } from "../bridges/index.js";
  * // Respect safe area insets
  * const paddingTop = safeArea.insets.top;
  * ```
+ *
+ * @see https://docs.skybridge.tech/api-reference/use-layout
  */
 export function useLayout() {
     const theme = useHostContext("theme");

package/dist/web/hooks/use-layout.js.map

@@ -1 +1 @@
-{"version":3,"file":"use-layout.js","sourceRoot":"","sources":["../../../src/web/hooks/use-layout.ts"],"names":[],"mappings":"AAAA,OAAO,EAA6B,cAAc,EAAE,MAAM,qBAAqB,CAAC;AAQhF;;;;;;;;;;;;;;GAcG;AACH,MAAM,UAAU,SAAS;IACvB,MAAM,KAAK,GAAG,cAAc,CAAC,OAAO,CAAC,CAAC;IACtC,MAAM,SAAS,GAAG,cAAc,CAAC,WAAW,CAAC,CAAC;IAC9C,MAAM,QAAQ,GAAG,cAAc,CAAC,UAAU,CAAC,CAAC;IAE5C,OAAO,EAAE,KAAK,EAAE,SAAS,EAAE,QAAQ,EAAE,CAAC;AACxC,CAAC","sourcesContent":["import { type SafeArea, type Theme, useHostContext } from \"../bridges/index.js\";\n\nexport type LayoutState = {\n  theme: Theme;\n  maxHeight: number | undefined;\n  safeArea: SafeArea;\n};\n\n/**\n * Hook for accessing layout and visual environment information.\n * These values may change on resize or theme toggle.\n *\n * @example\n * ```tsx\n * const { theme, maxHeight, safeArea } = useLayout();\n *\n * // Apply theme-aware styling\n * const backgroundColor = theme === \"dark\" ? \"#1a1a1a\" : \"#ffffff\";\n *\n * // Respect safe area insets\n * const paddingTop = safeArea.insets.top;\n * ```\n */\nexport function useLayout(): LayoutState {\n  const theme = useHostContext(\"theme\");\n  const maxHeight = useHostContext(\"maxHeight\");\n  const safeArea = useHostContext(\"safeArea\");\n\n  return { theme, maxHeight, safeArea };\n}\n"]}
+{"version":3,"file":"use-layout.js","sourceRoot":"","sources":["../../../src/web/hooks/use-layout.ts"],"names":[],"mappings":"AAAA,OAAO,EAA6B,cAAc,EAAE,MAAM,qBAAqB,CAAC;AAQhF;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,UAAU,SAAS;IACvB,MAAM,KAAK,GAAG,cAAc,CAAC,OAAO,CAAC,CAAC;IACtC,MAAM,SAAS,GAAG,cAAc,CAAC,WAAW,CAAC,CAAC;IAC9C,MAAM,QAAQ,GAAG,cAAc,CAAC,UAAU,CAAC,CAAC;IAE5C,OAAO,EAAE,KAAK,EAAE,SAAS,EAAE,QAAQ,EAAE,CAAC;AACxC,CAAC","sourcesContent":["import { type SafeArea, type Theme, useHostContext } from \"../bridges/index.js\";\n\nexport type LayoutState = {\n  theme: Theme;\n  maxHeight: number | undefined;\n  safeArea: SafeArea;\n};\n\n/**\n * Hook for accessing layout and visual environment information.\n * These values may change on resize or theme toggle.\n *\n * @example\n * ```tsx\n * const { theme, maxHeight, safeArea } = useLayout();\n *\n * // Apply theme-aware styling\n * const backgroundColor = theme === \"dark\" ? \"#1a1a1a\" : \"#ffffff\";\n *\n * // Respect safe area insets\n * const paddingTop = safeArea.insets.top;\n * ```\n *\n * @see https://docs.skybridge.tech/api-reference/use-layout\n */\nexport function useLayout(): LayoutState {\n  const theme = useHostContext(\"theme\");\n  const maxHeight = useHostContext(\"maxHeight\");\n  const safeArea = useHostContext(\"safeArea\");\n\n  return { theme, maxHeight, safeArea };\n}\n"]}

package/dist/web/hooks/use-open-external.d.ts

@@ -1,3 +1,20 @@
 import type { OpenExternalOptions } from "../bridges/types.js";
+/** Function that opens a URL outside the view's iframe, returned by {@link useOpenExternal}. */
 export type OpenExternalFn = (href: string, options?: OpenExternalOptions) => void;
+/**
+ * Open an external URL through the host (e.g. in the user's browser).
+ *
+ * Use this instead of `window.open` or anchor `target="_blank"`, which are
+ * unreliable inside a sandboxed iframe. Hosts may transform the URL (e.g.
+ * ChatGPT appends a `?redirectUrl=…` parameter for allowlisted targets — pass
+ * `redirectUrl: false` to suppress it).
+ *
+ * @example
+ * ```tsx
+ * const openExternal = useOpenExternal();
+ * <button onClick={() => openExternal("https://example.com")}>Open docs</button>
+ * ```
+ *
+ * @see https://docs.skybridge.tech/api-reference/use-open-external
+ */
 export declare function useOpenExternal(): OpenExternalFn;

package/dist/web/hooks/use-open-external.js

@@ -1,5 +1,21 @@
 import { useCallback } from "react";
 import { getAdaptor } from "../bridges/index.js";
+/**
+ * Open an external URL through the host (e.g. in the user's browser).
+ *
+ * Use this instead of `window.open` or anchor `target="_blank"`, which are
+ * unreliable inside a sandboxed iframe. Hosts may transform the URL (e.g.
+ * ChatGPT appends a `?redirectUrl=…` parameter for allowlisted targets — pass
+ * `redirectUrl: false` to suppress it).
+ *
+ * @example
+ * ```tsx
+ * const openExternal = useOpenExternal();
+ * <button onClick={() => openExternal("https://example.com")}>Open docs</button>
+ * ```
+ *
+ * @see https://docs.skybridge.tech/api-reference/use-open-external
+ */
 export function useOpenExternal() {
     const adaptor = getAdaptor();
     const openExternal = useCallback((href, options) => adaptor.openExternal(href, options), [adaptor]);

package/dist/web/hooks/use-open-external.js.map

@@ -1 +1 @@
-{"version":3,"file":"use-open-external.js","sourceRoot":"","sources":["../../../src/web/hooks/use-open-external.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,MAAM,OAAO,CAAC;AACpC,OAAO,EAAE,UAAU,EAAE,MAAM,qBAAqB,CAAC;AAQjD,MAAM,UAAU,eAAe;IAC7B,MAAM,OAAO,GAAG,UAAU,EAAE,CAAC;IAC7B,MAAM,YAAY,GAAG,WAAW,CAC9B,CAAC,IAAY,EAAE,OAA6B,EAAE,EAAE,CAC9C,OAAO,CAAC,YAAY,CAAC,IAAI,EAAE,OAAO,CAAC,EACrC,CAAC,OAAO,CAAC,CACV,CAAC;IAEF,OAAO,YAAY,CAAC;AACtB,CAAC","sourcesContent":["import { useCallback } from \"react\";\nimport { getAdaptor } from \"../bridges/index.js\";\nimport type { OpenExternalOptions } from \"../bridges/types.js\";\n\nexport type OpenExternalFn = (\n  href: string,\n  options?: OpenExternalOptions,\n) => void;\n\nexport function useOpenExternal(): OpenExternalFn {\n  const adaptor = getAdaptor();\n  const openExternal = useCallback(\n    (href: string, options?: OpenExternalOptions) =>\n      adaptor.openExternal(href, options),\n    [adaptor],\n  );\n\n  return openExternal;\n}\n"]}
+{"version":3,"file":"use-open-external.js","sourceRoot":"","sources":["../../../src/web/hooks/use-open-external.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,MAAM,OAAO,CAAC;AACpC,OAAO,EAAE,UAAU,EAAE,MAAM,qBAAqB,CAAC;AASjD;;;;;;;;;;;;;;;GAeG;AACH,MAAM,UAAU,eAAe;IAC7B,MAAM,OAAO,GAAG,UAAU,EAAE,CAAC;IAC7B,MAAM,YAAY,GAAG,WAAW,CAC9B,CAAC,IAAY,EAAE,OAA6B,EAAE,EAAE,CAC9C,OAAO,CAAC,YAAY,CAAC,IAAI,EAAE,OAAO,CAAC,EACrC,CAAC,OAAO,CAAC,CACV,CAAC;IAEF,OAAO,YAAY,CAAC;AACtB,CAAC","sourcesContent":["import { useCallback } from \"react\";\nimport { getAdaptor } from \"../bridges/index.js\";\nimport type { OpenExternalOptions } from \"../bridges/types.js\";\n\n/** Function that opens a URL outside the view's iframe, returned by {@link useOpenExternal}. */\nexport type OpenExternalFn = (\n  href: string,\n  options?: OpenExternalOptions,\n) => void;\n\n/**\n * Open an external URL through the host (e.g. in the user's browser).\n *\n * Use this instead of `window.open` or anchor `target=\"_blank\"`, which are\n * unreliable inside a sandboxed iframe. Hosts may transform the URL (e.g.\n * ChatGPT appends a `?redirectUrl=…` parameter for allowlisted targets — pass\n * `redirectUrl: false` to suppress it).\n *\n * @example\n * ```tsx\n * const openExternal = useOpenExternal();\n * <button onClick={() => openExternal(\"https://example.com\")}>Open docs</button>\n * ```\n *\n * @see https://docs.skybridge.tech/api-reference/use-open-external\n */\nexport function useOpenExternal(): OpenExternalFn {\n  const adaptor = getAdaptor();\n  const openExternal = useCallback(\n    (href: string, options?: OpenExternalOptions) =>\n      adaptor.openExternal(href, options),\n    [adaptor],\n  );\n\n  return openExternal;\n}\n"]}

package/dist/web/hooks/use-request-close.d.ts

@@ -1,2 +1,16 @@
+/** Function that asks the host to close the current view, returned by {@link useRequestClose}. */
 export type RequestCloseFn = () => Promise<void>;
+/**
+ * Ask the host to close (dismiss) the current view. The host decides whether
+ * to honor the request. Useful from modal views or after a terminal action
+ * like "Done".
+ *
+ * @example
+ * ```tsx
+ * const close = useRequestClose();
+ * <button onClick={() => close()}>Done</button>
+ * ```
+ *
+ * @see https://docs.skybridge.tech/api-reference/use-request-close
+ */
 export declare function useRequestClose(): RequestCloseFn;

package/dist/web/hooks/use-request-close.js

@@ -1,5 +1,18 @@
 import { useCallback } from "react";
 import { getAdaptor } from "../bridges/index.js";
+/**
+ * Ask the host to close (dismiss) the current view. The host decides whether
+ * to honor the request. Useful from modal views or after a terminal action
+ * like "Done".
+ *
+ * @example
+ * ```tsx
+ * const close = useRequestClose();
+ * <button onClick={() => close()}>Done</button>
+ * ```
+ *
+ * @see https://docs.skybridge.tech/api-reference/use-request-close
+ */
 export function useRequestClose() {
     const adaptor = getAdaptor();
     const requestClose = useCallback(() => adaptor.requestClose(), [adaptor]);

package/dist/web/hooks/use-request-close.js.map

@@ -1 +1 @@
-{"version":3,"file":"use-request-close.js","sourceRoot":"","sources":["../../../src/web/hooks/use-request-close.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,MAAM,OAAO,CAAC;AACpC,OAAO,EAAE,UAAU,EAAE,MAAM,qBAAqB,CAAC;AAIjD,MAAM,UAAU,eAAe;IAC7B,MAAM,OAAO,GAAG,UAAU,EAAE,CAAC;IAC7B,MAAM,YAAY,GAAG,WAAW,CAAC,GAAG,EAAE,CAAC,OAAO,CAAC,YAAY,EAAE,EAAE,CAAC,OAAO,CAAC,CAAC,CAAC;IAE1E,OAAO,YAAY,CAAC;AACtB,CAAC","sourcesContent":["import { useCallback } from \"react\";\nimport { getAdaptor } from \"../bridges/index.js\";\n\nexport type RequestCloseFn = () => Promise<void>;\n\nexport function useRequestClose(): RequestCloseFn {\n  const adaptor = getAdaptor();\n  const requestClose = useCallback(() => adaptor.requestClose(), [adaptor]);\n\n  return requestClose;\n}\n"]}
+{"version":3,"file":"use-request-close.js","sourceRoot":"","sources":["../../../src/web/hooks/use-request-close.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,MAAM,OAAO,CAAC;AACpC,OAAO,EAAE,UAAU,EAAE,MAAM,qBAAqB,CAAC;AAKjD;;;;;;;;;;;;GAYG;AACH,MAAM,UAAU,eAAe;IAC7B,MAAM,OAAO,GAAG,UAAU,EAAE,CAAC;IAC7B,MAAM,YAAY,GAAG,WAAW,CAAC,GAAG,EAAE,CAAC,OAAO,CAAC,YAAY,EAAE,EAAE,CAAC,OAAO,CAAC,CAAC,CAAC;IAE1E,OAAO,YAAY,CAAC;AACtB,CAAC","sourcesContent":["import { useCallback } from \"react\";\nimport { getAdaptor } from \"../bridges/index.js\";\n\n/** Function that asks the host to close the current view, returned by {@link useRequestClose}. */\nexport type RequestCloseFn = () => Promise<void>;\n\n/**\n * Ask the host to close (dismiss) the current view. The host decides whether\n * to honor the request. Useful from modal views or after a terminal action\n * like \"Done\".\n *\n * @example\n * ```tsx\n * const close = useRequestClose();\n * <button onClick={() => close()}>Done</button>\n * ```\n *\n * @see https://docs.skybridge.tech/api-reference/use-request-close\n */\nexport function useRequestClose(): RequestCloseFn {\n  const adaptor = getAdaptor();\n  const requestClose = useCallback(() => adaptor.requestClose(), [adaptor]);\n\n  return requestClose;\n}\n"]}