skybridge 0.0.0-dev.b0f5d5c → 0.0.0-dev.b0f7f92

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-register-view-tool.d.ts

@@ -0,0 +1,38 @@
+import type { ZodRawShapeCompat } from "@modelcontextprotocol/sdk/server/zod-compat.js";
+import type { ViewToolConfig, ViewToolHandler } from "../bridges/types.js";
+/**
+ * Register a tool the view exposes to the host and model — the MCP Apps
+ * "app-provided tools" feature. A view tool runs *inside the view*: the host
+ * discovers it via `tools/list` and invokes it via `tools/call`, and the
+ * handler executes against the view's live state. It is the inverse of
+ * {@link useCallTool} (which calls a server tool). Registered on mount, removed
+ * on unmount; re-registered when `config.name` changes.
+ *
+ * MCP Apps only — on the Apps SDK (`window.openai`) runtime it is a no-op.
+ *
+ * @example
+ * ```tsx
+ * import * as z from "zod";
+ * import { useRegisterViewTool } from "skybridge/web";
+ *
+ * useRegisterViewTool(
+ *   {
+ *     name: "chess_make_move",
+ *     description: "Play a move in algebraic notation, e.g. 'e4' or 'Nf3'.",
+ *     inputSchema: { san: z.string() },
+ *     annotations: { readOnlyHint: false },
+ *   },
+ *   ({ san }) => {
+ *     const move = game.move(san);
+ *     return {
+ *       content: [{ type: "text", text: move ? `Played ${move.san}` : "Illegal move" }],
+ *       structuredContent: { fen: game.fen() },
+ *       isError: !move,
+ *     };
+ *   },
+ * );
+ * ```
+ *
+ * @see https://docs.skybridge.tech/api-reference/use-register-view-tool
+ */
+export declare const useRegisterViewTool: <TInput extends ZodRawShapeCompat = ZodRawShapeCompat>(config: ViewToolConfig<TInput>, handler: ViewToolHandler<TInput>) => void;

package/dist/web/hooks/use-register-view-tool.js

@@ -0,0 +1,50 @@
+import { useEffect, useRef } from "react";
+import { getAdaptor } from "../bridges/index.js";
+/**
+ * Register a tool the view exposes to the host and model — the MCP Apps
+ * "app-provided tools" feature. A view tool runs *inside the view*: the host
+ * discovers it via `tools/list` and invokes it via `tools/call`, and the
+ * handler executes against the view's live state. It is the inverse of
+ * {@link useCallTool} (which calls a server tool). Registered on mount, removed
+ * on unmount; re-registered when `config.name` changes.
+ *
+ * MCP Apps only — on the Apps SDK (`window.openai`) runtime it is a no-op.
+ *
+ * @example
+ * ```tsx
+ * import * as z from "zod";
+ * import { useRegisterViewTool } from "skybridge/web";
+ *
+ * useRegisterViewTool(
+ *   {
+ *     name: "chess_make_move",
+ *     description: "Play a move in algebraic notation, e.g. 'e4' or 'Nf3'.",
+ *     inputSchema: { san: z.string() },
+ *     annotations: { readOnlyHint: false },
+ *   },
+ *   ({ san }) => {
+ *     const move = game.move(san);
+ *     return {
+ *       content: [{ type: "text", text: move ? `Played ${move.san}` : "Illegal move" }],
+ *       structuredContent: { fen: game.fen() },
+ *       isError: !move,
+ *     };
+ *   },
+ * );
+ * ```
+ *
+ * @see https://docs.skybridge.tech/api-reference/use-register-view-tool
+ */
+export const useRegisterViewTool = (config, handler) => {
+    const { name } = config;
+    const configRef = useRef(config);
+    configRef.current = config;
+    const handlerRef = useRef(handler);
+    handlerRef.current = handler;
+    useEffect(() => {
+        const adaptor = getAdaptor();
+        const wrappedHandler = (args) => handlerRef.current(args);
+        return adaptor.registerViewTool({ ...configRef.current, name }, wrappedHandler);
+    }, [name]);
+};
+//# sourceMappingURL=use-register-view-tool.js.map

package/dist/web/hooks/use-register-view-tool.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"use-register-view-tool.js","sourceRoot":"","sources":["../../../src/web/hooks/use-register-view-tool.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,SAAS,EAAE,MAAM,EAAE,MAAM,OAAO,CAAC;AAC1C,OAAO,EAAE,UAAU,EAAE,MAAM,qBAAqB,CAAC;AAOjD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AACH,MAAM,CAAC,MAAM,mBAAmB,GAAG,CAGjC,MAA8B,EAC9B,OAAgC,EAChC,EAAE;IACF,MAAM,EAAE,IAAI,EAAE,GAAG,MAAM,CAAC;IACxB,MAAM,SAAS,GAAG,MAAM,CAAC,MAAM,CAAC,CAAC;IACjC,SAAS,CAAC,OAAO,GAAG,MAAM,CAAC;IAC3B,MAAM,UAAU,GAAG,MAAM,CAAC,OAAO,CAAC,CAAC;IACnC,UAAU,CAAC,OAAO,GAAG,OAAO,CAAC;IAE7B,SAAS,CAAC,GAAG,EAAE;QACb,MAAM,OAAO,GAAG,UAAU,EAAE,CAAC;QAC7B,MAAM,cAAc,GAAuB,CAAC,IAAI,EAAE,EAAE,CAClD,UAAU,CAAC,OAAO,CAAC,IAA8C,CAAC,CAAC;QAErE,OAAO,OAAO,CAAC,gBAAgB,CAC7B,EAAE,GAAG,SAAS,CAAC,OAAO,EAAE,IAAI,EAAE,EAC9B,cAAc,CACf,CAAC;IACJ,CAAC,EAAE,CAAC,IAAI,CAAC,CAAC,CAAC;AACb,CAAC,CAAC","sourcesContent":["import type { ZodRawShapeCompat } from \"@modelcontextprotocol/sdk/server/zod-compat.js\";\nimport { useEffect, useRef } from \"react\";\nimport { getAdaptor } from \"../bridges/index.js\";\nimport type {\n  AnyViewToolHandler,\n  ViewToolConfig,\n  ViewToolHandler,\n} from \"../bridges/types.js\";\n\n/**\n * Register a tool the view exposes to the host and model — the MCP Apps\n * \"app-provided tools\" feature. A view tool runs *inside the view*: the host\n * discovers it via `tools/list` and invokes it via `tools/call`, and the\n * handler executes against the view's live state. It is the inverse of\n * {@link useCallTool} (which calls a server tool). Registered on mount, removed\n * on unmount; re-registered when `config.name` changes.\n *\n * MCP Apps only — on the Apps SDK (`window.openai`) runtime it is a no-op.\n *\n * @example\n * ```tsx\n * import * as z from \"zod\";\n * import { useRegisterViewTool } from \"skybridge/web\";\n *\n * useRegisterViewTool(\n *   {\n *     name: \"chess_make_move\",\n *     description: \"Play a move in algebraic notation, e.g. 'e4' or 'Nf3'.\",\n *     inputSchema: { san: z.string() },\n *     annotations: { readOnlyHint: false },\n *   },\n *   ({ san }) => {\n *     const move = game.move(san);\n *     return {\n *       content: [{ type: \"text\", text: move ? `Played ${move.san}` : \"Illegal move\" }],\n *       structuredContent: { fen: game.fen() },\n *       isError: !move,\n *     };\n *   },\n * );\n * ```\n *\n * @see https://docs.skybridge.tech/api-reference/use-register-view-tool\n */\nexport const useRegisterViewTool = <\n  TInput extends ZodRawShapeCompat = ZodRawShapeCompat,\n>(\n  config: ViewToolConfig<TInput>,\n  handler: ViewToolHandler<TInput>,\n) => {\n  const { name } = config;\n  const configRef = useRef(config);\n  configRef.current = config;\n  const handlerRef = useRef(handler);\n  handlerRef.current = handler;\n\n  useEffect(() => {\n    const adaptor = getAdaptor();\n    const wrappedHandler: AnyViewToolHandler = (args) =>\n      handlerRef.current(args as Parameters<ViewToolHandler<TInput>>[0]);\n\n    return adaptor.registerViewTool(\n      { ...configRef.current, name },\n      wrappedHandler,\n    );\n  }, [name]);\n};\n"]}

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

@@ -0,0 +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

@@ -0,0 +1,21 @@
+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]);
+    return requestClose;
+}
+//# sourceMappingURL=use-request-close.js.map

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

@@ -0,0 +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;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"]}

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

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

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

@@ -0,0 +1,52 @@
+import { renderHook, waitFor } from "@testing-library/react";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import { McpAppBridge } from "../bridges/mcp-app/bridge.js";
+import { getMcpAppHostPostMessageMock, MockResizeObserver, } from "./test/utils.js";
+import { useRequestClose } from "./use-request-close.js";
+describe("useRequestClose", () => {
+    describe("apps-sdk host", () => {
+        let requestCloseMock;
+        beforeEach(() => {
+            requestCloseMock = vi.fn().mockResolvedValue(undefined);
+            vi.stubGlobal("openai", {
+                requestClose: requestCloseMock,
+            });
+            vi.stubGlobal("skybridge", { hostType: "apps-sdk" });
+        });
+        afterEach(() => {
+            vi.unstubAllGlobals();
+            vi.resetAllMocks();
+        });
+        it("should return a function that calls window.openai.requestClose", async () => {
+            const { result } = renderHook(() => useRequestClose());
+            await result.current();
+            expect(requestCloseMock).toHaveBeenCalledTimes(1);
+            expect(requestCloseMock).toHaveBeenCalledWith();
+        });
+    });
+    describe("mcp-app host", () => {
+        let postMessageMock;
+        beforeEach(() => {
+            vi.stubGlobal("skybridge", { hostType: "mcp-app" });
+            vi.stubGlobal("ResizeObserver", MockResizeObserver);
+            postMessageMock = getMcpAppHostPostMessageMock();
+            vi.stubGlobal("parent", { postMessage: postMessageMock });
+        });
+        afterEach(async () => {
+            vi.unstubAllGlobals();
+            vi.resetAllMocks();
+            McpAppBridge.resetInstance();
+        });
+        it("should send a ui/notifications/request-teardown notification to the MCP host", async () => {
+            const { result } = renderHook(() => useRequestClose());
+            await result.current();
+            await waitFor(() => {
+                expect(postMessageMock).toHaveBeenCalledWith(expect.objectContaining({
+                    jsonrpc: "2.0",
+                    method: "ui/notifications/request-teardown",
+                }), "*");
+            });
+        });
+    });
+});
+//# sourceMappingURL=use-request-close.test.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"use-request-close.test.js","sourceRoot":"","sources":["../../../src/web/hooks/use-request-close.test.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,OAAO,EAAE,MAAM,wBAAwB,CAAC;AAC7D,OAAO,EAAE,SAAS,EAAE,UAAU,EAAE,QAAQ,EAAE,MAAM,EAAE,EAAE,EAAE,EAAE,EAAE,MAAM,QAAQ,CAAC;AACzE,OAAO,EAAE,YAAY,EAAE,MAAM,8BAA8B,CAAC;AAC5D,OAAO,EACL,4BAA4B,EAC5B,kBAAkB,GACnB,MAAM,iBAAiB,CAAC;AACzB,OAAO,EAAE,eAAe,EAAE,MAAM,wBAAwB,CAAC;AAEzD,QAAQ,CAAC,iBAAiB,EAAE,GAAG,EAAE;IAC/B,QAAQ,CAAC,eAAe,EAAE,GAAG,EAAE;QAC7B,IAAI,gBAA0C,CAAC;QAE/C,UAAU,CAAC,GAAG,EAAE;YACd,gBAAgB,GAAG,EAAE,CAAC,EAAE,EAAE,CAAC,iBAAiB,CAAC,SAAS,CAAC,CAAC;YACxD,EAAE,CAAC,UAAU,CAAC,QAAQ,EAAE;gBACtB,YAAY,EAAE,gBAAgB;aAC/B,CAAC,CAAC;YACH,EAAE,CAAC,UAAU,CAAC,WAAW,EAAE,EAAE,QAAQ,EAAE,UAAU,EAAE,CAAC,CAAC;QACvD,CAAC,CAAC,CAAC;QAEH,SAAS,CAAC,GAAG,EAAE;YACb,EAAE,CAAC,gBAAgB,EAAE,CAAC;YACtB,EAAE,CAAC,aAAa,EAAE,CAAC;QACrB,CAAC,CAAC,CAAC;QAEH,EAAE,CAAC,gEAAgE,EAAE,KAAK,IAAI,EAAE;YAC9E,MAAM,EAAE,MAAM,EAAE,GAAG,UAAU,CAAC,GAAG,EAAE,CAAC,eAAe,EAAE,CAAC,CAAC;YAEvD,MAAM,MAAM,CAAC,OAAO,EAAE,CAAC;YAEvB,MAAM,CAAC,gBAAgB,CAAC,CAAC,qBAAqB,CAAC,CAAC,CAAC,CAAC;YAClD,MAAM,CAAC,gBAAgB,CAAC,CAAC,oBAAoB,EAAE,CAAC;QAClD,CAAC,CAAC,CAAC;IACL,CAAC,CAAC,CAAC;IAEH,QAAQ,CAAC,cAAc,EAAE,GAAG,EAAE;QAC5B,IAAI,eAAgE,CAAC;QAErE,UAAU,CAAC,GAAG,EAAE;YACd,EAAE,CAAC,UAAU,CAAC,WAAW,EAAE,EAAE,QAAQ,EAAE,SAAS,EAAE,CAAC,CAAC;YACpD,EAAE,CAAC,UAAU,CAAC,gBAAgB,EAAE,kBAAkB,CAAC,CAAC;YACpD,eAAe,GAAG,4BAA4B,EAAE,CAAC;YACjD,EAAE,CAAC,UAAU,CAAC,QAAQ,EAAE,EAAE,WAAW,EAAE,eAAe,EAAE,CAAC,CAAC;QAC5D,CAAC,CAAC,CAAC;QAEH,SAAS,CAAC,KAAK,IAAI,EAAE;YACnB,EAAE,CAAC,gBAAgB,EAAE,CAAC;YACtB,EAAE,CAAC,aAAa,EAAE,CAAC;YACnB,YAAY,CAAC,aAAa,EAAE,CAAC;QAC/B,CAAC,CAAC,CAAC;QAEH,EAAE,CAAC,8EAA8E,EAAE,KAAK,IAAI,EAAE;YAC5F,MAAM,EAAE,MAAM,EAAE,GAAG,UAAU,CAAC,GAAG,EAAE,CAAC,eAAe,EAAE,CAAC,CAAC;YAEvD,MAAM,MAAM,CAAC,OAAO,EAAE,CAAC;YAEvB,MAAM,OAAO,CAAC,GAAG,EAAE;gBACjB,MAAM,CAAC,eAAe,CAAC,CAAC,oBAAoB,CAC1C,MAAM,CAAC,gBAAgB,CAAC;oBACtB,OAAO,EAAE,KAAK;oBACd,MAAM,EAAE,mCAAmC;iBAC5C,CAAC,EACF,GAAG,CACJ,CAAC;YACJ,CAAC,CAAC,CAAC;QACL,CAAC,CAAC,CAAC;IACL,CAAC,CAAC,CAAC;AACL,CAAC,CAAC,CAAC","sourcesContent":["import { renderHook, waitFor } from \"@testing-library/react\";\nimport { afterEach, beforeEach, describe, expect, it, vi } from \"vitest\";\nimport { McpAppBridge } from \"../bridges/mcp-app/bridge.js\";\nimport {\n  getMcpAppHostPostMessageMock,\n  MockResizeObserver,\n} from \"./test/utils.js\";\nimport { useRequestClose } from \"./use-request-close.js\";\n\ndescribe(\"useRequestClose\", () => {\n  describe(\"apps-sdk host\", () => {\n    let requestCloseMock: ReturnType<typeof vi.fn>;\n\n    beforeEach(() => {\n      requestCloseMock = vi.fn().mockResolvedValue(undefined);\n      vi.stubGlobal(\"openai\", {\n        requestClose: requestCloseMock,\n      });\n      vi.stubGlobal(\"skybridge\", { hostType: \"apps-sdk\" });\n    });\n\n    afterEach(() => {\n      vi.unstubAllGlobals();\n      vi.resetAllMocks();\n    });\n\n    it(\"should return a function that calls window.openai.requestClose\", async () => {\n      const { result } = renderHook(() => useRequestClose());\n\n      await result.current();\n\n      expect(requestCloseMock).toHaveBeenCalledTimes(1);\n      expect(requestCloseMock).toHaveBeenCalledWith();\n    });\n  });\n\n  describe(\"mcp-app host\", () => {\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      vi.stubGlobal(\"parent\", { postMessage: postMessageMock });\n    });\n\n    afterEach(async () => {\n      vi.unstubAllGlobals();\n      vi.resetAllMocks();\n      McpAppBridge.resetInstance();\n    });\n\n    it(\"should send a ui/notifications/request-teardown notification to the MCP host\", async () => {\n      const { result } = renderHook(() => useRequestClose());\n\n      await result.current();\n\n      await waitFor(() => {\n        expect(postMessageMock).toHaveBeenCalledWith(\n          expect.objectContaining({\n            jsonrpc: \"2.0\",\n            method: \"ui/notifications/request-teardown\",\n          }),\n          \"*\",\n        );\n      });\n    });\n  });\n});\n"]}

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

@@ -1,6 +1,21 @@
 import { type RequestModalOptions } from "../bridges/index.js";
 /**
- * Triggers a modal containing the view rendered in display mode "modal"
+ * Open the current view in a modal overlay (`displayMode === "modal"`).
+ *
+ * Returns `{ isOpen, params, open }`: `open(opts)` triggers the host to render
+ * the view in a modal, optionally passing `params` that are surfaced back via
+ * `params` here. Useful for confirmation flows, detail panels, or any modal
+ * lifecycle owned by the host.
+ *
+ * Use {@link useDisplayMode} for non-modal display modes.
+ *
+ * @example
+ * ```tsx
+ * const { isOpen, open } = useRequestModal();
+ * <button onClick={() => open({ params: { id: 42 } })}>Show details</button>
+ * ```
+ *
+ * @see https://docs.skybridge.tech/api-reference/use-request-modal
  */
 export declare function useRequestModal(): {
     isOpen: boolean;

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

@@ -1,7 +1,22 @@
 import { useCallback } from "react";
 import { getAdaptor, useHostContext, } from "../bridges/index.js";
 /**
- * Triggers a modal containing the view rendered in display mode "modal"
+ * Open the current view in a modal overlay (`displayMode === "modal"`).
+ *
+ * Returns `{ isOpen, params, open }`: `open(opts)` triggers the host to render
+ * the view in a modal, optionally passing `params` that are surfaced back via
+ * `params` here. Useful for confirmation flows, detail panels, or any modal
+ * lifecycle owned by the host.
+ *
+ * Use {@link useDisplayMode} for non-modal display modes.
+ *
+ * @example
+ * ```tsx
+ * const { isOpen, open } = useRequestModal();
+ * <button onClick={() => open({ params: { id: 42 } })}>Show details</button>
+ * ```
+ *
+ * @see https://docs.skybridge.tech/api-reference/use-request-modal
  */
 export function useRequestModal() {
     const adaptor = getAdaptor();

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

@@ -1 +1 @@
-{"version":3,"file":"use-request-modal.js","sourceRoot":"","sources":["../../../src/web/hooks/use-request-modal.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,MAAM,OAAO,CAAC;AACpC,OAAO,EACL,UAAU,EAEV,cAAc,GACf,MAAM,qBAAqB,CAAC;AAE7B;;GAEG;AACH,MAAM,UAAU,eAAe;IAC7B,MAAM,OAAO,GAAG,UAAU,EAAE,CAAC;IAC7B,MAAM,OAAO,GAAG,cAAc,CAAC,SAAS,CAAC,CAAC;IAC1C,MAAM,IAAI,GAAG,WAAW,CACtB,CAAC,IAAyB,EAAE,EAAE,CAAC,OAAO,CAAC,SAAS,CAAC,IAAI,CAAC,EACtD,CAAC,OAAO,CAAC,CACV,CAAC;IACF,OAAO;QACL,MAAM,EAAE,OAAO,CAAC,IAAI,KAAK,OAAO;QAChC,MAAM,EAAE,OAAO,CAAC,MAAM;QACtB,IAAI;KACL,CAAC;AACJ,CAAC","sourcesContent":["import { useCallback } from \"react\";\nimport {\n  getAdaptor,\n  type RequestModalOptions,\n  useHostContext,\n} from \"../bridges/index.js\";\n\n/**\n * Triggers a modal containing the view rendered in display mode \"modal\"\n */\nexport function useRequestModal() {\n  const adaptor = getAdaptor();\n  const display = useHostContext(\"display\");\n  const open = useCallback(\n    (opts: RequestModalOptions) => adaptor.openModal(opts),\n    [adaptor],\n  );\n  return {\n    isOpen: display.mode === \"modal\",\n    params: display.params,\n    open,\n  };\n}\n"]}
+{"version":3,"file":"use-request-modal.js","sourceRoot":"","sources":["../../../src/web/hooks/use-request-modal.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,MAAM,OAAO,CAAC;AACpC,OAAO,EACL,UAAU,EAEV,cAAc,GACf,MAAM,qBAAqB,CAAC;AAE7B;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAM,UAAU,eAAe;IAC7B,MAAM,OAAO,GAAG,UAAU,EAAE,CAAC;IAC7B,MAAM,OAAO,GAAG,cAAc,CAAC,SAAS,CAAC,CAAC;IAC1C,MAAM,IAAI,GAAG,WAAW,CACtB,CAAC,IAAyB,EAAE,EAAE,CAAC,OAAO,CAAC,SAAS,CAAC,IAAI,CAAC,EACtD,CAAC,OAAO,CAAC,CACV,CAAC;IACF,OAAO;QACL,MAAM,EAAE,OAAO,CAAC,IAAI,KAAK,OAAO;QAChC,MAAM,EAAE,OAAO,CAAC,MAAM;QACtB,IAAI;KACL,CAAC;AACJ,CAAC","sourcesContent":["import { useCallback } from \"react\";\nimport {\n  getAdaptor,\n  type RequestModalOptions,\n  useHostContext,\n} from \"../bridges/index.js\";\n\n/**\n * Open the current view in a modal overlay (`displayMode === \"modal\"`).\n *\n * Returns `{ isOpen, params, open }`: `open(opts)` triggers the host to render\n * the view in a modal, optionally passing `params` that are surfaced back via\n * `params` here. Useful for confirmation flows, detail panels, or any modal\n * lifecycle owned by the host.\n *\n * Use {@link useDisplayMode} for non-modal display modes.\n *\n * @example\n * ```tsx\n * const { isOpen, open } = useRequestModal();\n * <button onClick={() => open({ params: { id: 42 } })}>Show details</button>\n * ```\n *\n * @see https://docs.skybridge.tech/api-reference/use-request-modal\n */\nexport function useRequestModal() {\n  const adaptor = getAdaptor();\n  const display = useHostContext(\"display\");\n  const open = useCallback(\n    (opts: RequestModalOptions) => adaptor.openModal(opts),\n    [adaptor],\n  );\n  return {\n    isOpen: display.mode === \"modal\",\n    params: display.params,\n    open,\n  };\n}\n"]}

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

@@ -0,0 +1,20 @@
+import type { RequestSizeOptions } from "../bridges/types.js";
+/** Function that asks the host to resize the view, returned by {@link useRequestSize}. */
+export type RequestSizeFn = (size: RequestSizeOptions) => Promise<void>;
+/**
+ * Ask the host to resize the view iframe. The applied size is host-driven —
+ * the host decides whether and how to honor the request, and {@link useLayout}
+ * still reports the final `maxHeight` it allows.
+ *
+ * Pair with a `ResizeObserver` on your root element to react to content size
+ * changes without hard-coded values.
+ *
+ * @example
+ * ```tsx
+ * const requestSize = useRequestSize();
+ * useEffect(() => { requestSize({ height: rootRef.current!.scrollHeight }); }, [content]);
+ * ```
+ *
+ * @see https://docs.skybridge.tech/api-reference/use-request-size
+ */
+export declare function useRequestSize(): RequestSizeFn;

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

@@ -0,0 +1,24 @@
+import { useCallback } from "react";
+import { getAdaptor } from "../bridges/index.js";
+/**
+ * Ask the host to resize the view iframe. The applied size is host-driven —
+ * the host decides whether and how to honor the request, and {@link useLayout}
+ * still reports the final `maxHeight` it allows.
+ *
+ * Pair with a `ResizeObserver` on your root element to react to content size
+ * changes without hard-coded values.
+ *
+ * @example
+ * ```tsx
+ * const requestSize = useRequestSize();
+ * useEffect(() => { requestSize({ height: rootRef.current!.scrollHeight }); }, [content]);
+ * ```
+ *
+ * @see https://docs.skybridge.tech/api-reference/use-request-size
+ */
+export function useRequestSize() {
+    const adaptor = getAdaptor();
+    const requestSize = useCallback((size) => adaptor.requestSize(size), [adaptor]);
+    return requestSize;
+}
+//# sourceMappingURL=use-request-size.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"use-request-size.js","sourceRoot":"","sources":["../../../src/web/hooks/use-request-size.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,MAAM,OAAO,CAAC;AACpC,OAAO,EAAE,UAAU,EAAE,MAAM,qBAAqB,CAAC;AAMjD;;;;;;;;;;;;;;;GAeG;AACH,MAAM,UAAU,cAAc;IAC5B,MAAM,OAAO,GAAG,UAAU,EAAE,CAAC;IAC7B,MAAM,WAAW,GAAG,WAAW,CAC7B,CAAC,IAAwB,EAAE,EAAE,CAAC,OAAO,CAAC,WAAW,CAAC,IAAI,CAAC,EACvD,CAAC,OAAO,CAAC,CACV,CAAC;IAEF,OAAO,WAAW,CAAC;AACrB,CAAC","sourcesContent":["import { useCallback } from \"react\";\nimport { getAdaptor } from \"../bridges/index.js\";\nimport type { RequestSizeOptions } from \"../bridges/types.js\";\n\n/** Function that asks the host to resize the view, returned by {@link useRequestSize}. */\nexport type RequestSizeFn = (size: RequestSizeOptions) => Promise<void>;\n\n/**\n * Ask the host to resize the view iframe. The applied size is host-driven —\n * the host decides whether and how to honor the request, and {@link useLayout}\n * still reports the final `maxHeight` it allows.\n *\n * Pair with a `ResizeObserver` on your root element to react to content size\n * changes without hard-coded values.\n *\n * @example\n * ```tsx\n * const requestSize = useRequestSize();\n * useEffect(() => { requestSize({ height: rootRef.current!.scrollHeight }); }, [content]);\n * ```\n *\n * @see https://docs.skybridge.tech/api-reference/use-request-size\n */\nexport function useRequestSize(): RequestSizeFn {\n  const adaptor = getAdaptor();\n  const requestSize = useCallback(\n    (size: RequestSizeOptions) => adaptor.requestSize(size),\n    [adaptor],\n  );\n\n  return requestSize;\n}\n"]}

package/dist/web/hooks/use-request-size.test.d.ts

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