skybridge 0.0.0-dev.ffe77e9 → 0.0.0-next.086b7ec

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-open-external.test.js

@@ -1,30 +1,38 @@
 import { renderHook, waitFor } from "@testing-library/react";
 import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import { HostAdaptor } from "../bridges/adaptor.js";
 import { McpAppBridge } from "../bridges/mcp-app/bridge.js";
 import { getMcpAppHostPostMessageMock, MockResizeObserver, } from "./test/utils.js";
 import { useOpenExternal } from "./use-open-external.js";
 describe("useOpenExternal", () => {
     describe("apps-sdk host", () => {
         let openExternalMock;
+        let postMessageMock;
         beforeEach(() => {
             openExternalMock = vi.fn();
             vi.stubGlobal("openai", {
                 openExternal: openExternalMock,
             });
             vi.stubGlobal("skybridge", { hostType: "apps-sdk" });
+            vi.stubGlobal("ResizeObserver", MockResizeObserver);
+            postMessageMock = getMcpAppHostPostMessageMock();
+            vi.stubGlobal("parent", { postMessage: postMessageMock });
         });
         afterEach(() => {
+            HostAdaptor.resetInstance();
+            McpAppBridge.resetInstance();
             vi.unstubAllGlobals();
             vi.resetAllMocks();
         });
-        it("should return a function that calls window.openai.openExternal with the href", () => {
+        it("should call window.openai.openExternal even without a redirectUrl option", () => {
             const { result } = renderHook(() => useOpenExternal());
             const href = "https://example.com";
             result.current(href);
             expect(openExternalMock).toHaveBeenCalledTimes(1);
             expect(openExternalMock).toHaveBeenCalledWith({ href });
+            expect(postMessageMock).not.toHaveBeenCalledWith(expect.objectContaining({ method: "ui/open-link" }), "*");
         });
-        it("should forward redirectUrl false option to window.openai.openExternal", () => {
+        it("should call window.openai.openExternal when redirectUrl is false", () => {
             const { result } = renderHook(() => useOpenExternal());
             const href = "https://example.com";
             result.current(href, { redirectUrl: false });
@@ -38,15 +46,17 @@ describe("useOpenExternal", () => {
     describe("mcp-app host", () => {
         let postMessageMock;
         beforeEach(() => {
+            vi.stubGlobal("openai", undefined);
             vi.stubGlobal("skybridge", { hostType: "mcp-app" });
             vi.stubGlobal("ResizeObserver", MockResizeObserver);
             postMessageMock = getMcpAppHostPostMessageMock();
             vi.stubGlobal("parent", { postMessage: postMessageMock });
         });
         afterEach(async () => {
+            HostAdaptor.resetInstance();
+            McpAppBridge.resetInstance();
             vi.unstubAllGlobals();
             vi.resetAllMocks();
-            McpAppBridge.resetInstance();
         });
         it("should return a function that sends ui/open-link request to the MCP host", async () => {
             const { result } = renderHook(() => useOpenExternal());

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

@@ -1 +1 @@
-{"version":3,"file":"use-open-external.test.js","sourceRoot":"","sources":["../../../src/web/hooks/use-open-external.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 { McpAppBridge } from \"../bridges/mcp-app/bridge.js\";\nimport {\n  getMcpAppHostPostMessageMock,\n  MockResizeObserver,\n} from \"./test/utils.js\";\nimport { useOpenExternal } from \"./use-open-external.js\";\n\ndescribe(\"useOpenExternal\", () => {\n  describe(\"apps-sdk host\", () => {\n    let openExternalMock: ReturnType<typeof vi.fn>;\n\n    beforeEach(() => {\n      openExternalMock = vi.fn();\n      vi.stubGlobal(\"openai\", {\n        openExternal: openExternalMock,\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.openExternal with the href\", () => {\n      const { result } = renderHook(() => useOpenExternal());\n\n      const href = \"https://example.com\";\n      result.current(href);\n\n      expect(openExternalMock).toHaveBeenCalledTimes(1);\n      expect(openExternalMock).toHaveBeenCalledWith({ href });\n    });\n\n    it(\"should forward redirectUrl false option to window.openai.openExternal\", () => {\n      const { result } = renderHook(() => useOpenExternal());\n\n      const href = \"https://example.com\";\n      result.current(href, { redirectUrl: false });\n\n      expect(openExternalMock).toHaveBeenCalledTimes(1);\n      expect(openExternalMock).toHaveBeenCalledWith({\n        href,\n        redirectUrl: false,\n      });\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 return a function that sends ui/open-link request to the MCP host\", async () => {\n      const { result } = renderHook(() => useOpenExternal());\n\n      const href = \"https://example.com\";\n      result.current(href, { redirectUrl: false });\n\n      await waitFor(() => {\n        expect(postMessageMock).toHaveBeenCalledWith(\n          expect.objectContaining({\n            jsonrpc: \"2.0\",\n            method: \"ui/open-link\",\n            params: { url: href },\n          }),\n          \"*\",\n        );\n      });\n    });\n  });\n});\n"]}
+{"version":3,"file":"use-open-external.test.js","sourceRoot":"","sources":["../../../src/web/hooks/use-open-external.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 { HostAdaptor } from \"../bridges/adaptor.js\";\nimport { McpAppBridge } from \"../bridges/mcp-app/bridge.js\";\nimport {\n  getMcpAppHostPostMessageMock,\n  MockResizeObserver,\n} from \"./test/utils.js\";\nimport { useOpenExternal } from \"./use-open-external.js\";\n\ndescribe(\"useOpenExternal\", () => {\n  describe(\"apps-sdk host\", () => {\n    let openExternalMock: ReturnType<typeof vi.fn>;\n    let postMessageMock: ReturnType<typeof getMcpAppHostPostMessageMock>;\n\n    beforeEach(() => {\n      openExternalMock = vi.fn();\n      vi.stubGlobal(\"openai\", {\n        openExternal: openExternalMock,\n      });\n      vi.stubGlobal(\"skybridge\", { hostType: \"apps-sdk\" });\n      vi.stubGlobal(\"ResizeObserver\", MockResizeObserver);\n      postMessageMock = getMcpAppHostPostMessageMock();\n      vi.stubGlobal(\"parent\", { postMessage: postMessageMock });\n    });\n\n    afterEach(() => {\n      HostAdaptor.resetInstance();\n      McpAppBridge.resetInstance();\n      vi.unstubAllGlobals();\n      vi.resetAllMocks();\n    });\n\n    it(\"should call window.openai.openExternal even without a redirectUrl option\", () => {\n      const { result } = renderHook(() => useOpenExternal());\n\n      const href = \"https://example.com\";\n      result.current(href);\n\n      expect(openExternalMock).toHaveBeenCalledTimes(1);\n      expect(openExternalMock).toHaveBeenCalledWith({ href });\n      expect(postMessageMock).not.toHaveBeenCalledWith(\n        expect.objectContaining({ method: \"ui/open-link\" }),\n        \"*\",\n      );\n    });\n\n    it(\"should call window.openai.openExternal when redirectUrl is false\", () => {\n      const { result } = renderHook(() => useOpenExternal());\n\n      const href = \"https://example.com\";\n      result.current(href, { redirectUrl: false });\n\n      expect(openExternalMock).toHaveBeenCalledTimes(1);\n      expect(openExternalMock).toHaveBeenCalledWith({\n        href,\n        redirectUrl: false,\n      });\n    });\n  });\n\n  describe(\"mcp-app host\", () => {\n    let postMessageMock: ReturnType<typeof getMcpAppHostPostMessageMock>;\n\n    beforeEach(() => {\n      vi.stubGlobal(\"openai\", undefined);\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      HostAdaptor.resetInstance();\n      McpAppBridge.resetInstance();\n      vi.unstubAllGlobals();\n      vi.resetAllMocks();\n    });\n\n    it(\"should return a function that sends ui/open-link request to the MCP host\", async () => {\n      const { result } = renderHook(() => useOpenExternal());\n\n      const href = \"https://example.com\";\n      result.current(href, { redirectUrl: false });\n\n      await waitFor(() => {\n        expect(postMessageMock).toHaveBeenCalledWith(\n          expect.objectContaining({\n            jsonrpc: \"2.0\",\n            method: \"ui/open-link\",\n            params: { url: href },\n          }),\n          \"*\",\n        );\n      });\n    });\n  });\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,47 @@
+import { act, renderHook } from "@testing-library/react";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import { HostAdaptor } from "../bridges/adaptor.js";
+import { getAdaptor } from "../bridges/get-adaptor.js";
+import { McpAppBridge } from "../bridges/mcp-app/bridge.js";
+import { useRequestClose } from "./use-request-close.js";
+describe("useRequestClose", () => {
+    beforeEach(() => {
+        HostAdaptor.resetInstance();
+        McpAppBridge.resetInstance();
+        vi.stubGlobal("skybridge", { hostType: "mcp-app" });
+        vi.stubGlobal("openai", undefined);
+        vi.stubGlobal("parent", { postMessage: vi.fn() });
+    });
+    afterEach(() => {
+        vi.unstubAllGlobals();
+        vi.resetAllMocks();
+        HostAdaptor.resetInstance();
+        McpAppBridge.resetInstance();
+    });
+    it("calls app.requestTeardown via the MCP path", async () => {
+        const requestTeardown = vi.fn().mockResolvedValue(undefined);
+        // biome-ignore lint/suspicious/noExplicitAny: test seam
+        const adaptor = getAdaptor();
+        adaptor.mcp.getApp = vi.fn().mockResolvedValue({ requestTeardown });
+        const { result } = renderHook(() => useRequestClose());
+        await act(async () => {
+            await result.current();
+        });
+        expect(requestTeardown).toHaveBeenCalledTimes(1);
+    });
+    it("calls app.requestTeardown even when window.openai is present", async () => {
+        vi.stubGlobal("openai", { requestClose: vi.fn() });
+        HostAdaptor.resetInstance();
+        McpAppBridge.resetInstance();
+        const requestTeardown = vi.fn().mockResolvedValue(undefined);
+        // biome-ignore lint/suspicious/noExplicitAny: test seam
+        const adaptor = getAdaptor();
+        adaptor.mcp.getApp = vi.fn().mockResolvedValue({ requestTeardown });
+        const { result } = renderHook(() => useRequestClose());
+        await act(async () => {
+            await result.current();
+        });
+        expect(requestTeardown).toHaveBeenCalledTimes(1);
+    });
+});
+//# 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,GAAG,EAAE,UAAU,EAAE,MAAM,wBAAwB,CAAC;AACzD,OAAO,EAAE,SAAS,EAAE,UAAU,EAAE,QAAQ,EAAE,MAAM,EAAE,EAAE,EAAE,EAAE,EAAE,MAAM,QAAQ,CAAC;AACzE,OAAO,EAAE,WAAW,EAAE,MAAM,uBAAuB,CAAC;AACpD,OAAO,EAAE,UAAU,EAAE,MAAM,2BAA2B,CAAC;AACvD,OAAO,EAAE,YAAY,EAAE,MAAM,8BAA8B,CAAC;AAC5D,OAAO,EAAE,eAAe,EAAE,MAAM,wBAAwB,CAAC;AAEzD,QAAQ,CAAC,iBAAiB,EAAE,GAAG,EAAE;IAC/B,UAAU,CAAC,GAAG,EAAE;QACd,WAAW,CAAC,aAAa,EAAE,CAAC;QAC5B,YAAY,CAAC,aAAa,EAAE,CAAC;QAC7B,EAAE,CAAC,UAAU,CAAC,WAAW,EAAE,EAAE,QAAQ,EAAE,SAAS,EAAE,CAAC,CAAC;QACpD,EAAE,CAAC,UAAU,CAAC,QAAQ,EAAE,SAAS,CAAC,CAAC;QACnC,EAAE,CAAC,UAAU,CAAC,QAAQ,EAAE,EAAE,WAAW,EAAE,EAAE,CAAC,EAAE,EAAE,EAAE,CAAC,CAAC;IACpD,CAAC,CAAC,CAAC;IAEH,SAAS,CAAC,GAAG,EAAE;QACb,EAAE,CAAC,gBAAgB,EAAE,CAAC;QACtB,EAAE,CAAC,aAAa,EAAE,CAAC;QACnB,WAAW,CAAC,aAAa,EAAE,CAAC;QAC5B,YAAY,CAAC,aAAa,EAAE,CAAC;IAC/B,CAAC,CAAC,CAAC;IAEH,EAAE,CAAC,4CAA4C,EAAE,KAAK,IAAI,EAAE;QAC1D,MAAM,eAAe,GAAG,EAAE,CAAC,EAAE,EAAE,CAAC,iBAAiB,CAAC,SAAS,CAAC,CAAC;QAC7D,wDAAwD;QACxD,MAAM,OAAO,GAAG,UAAU,EAAS,CAAC;QACpC,OAAO,CAAC,GAAG,CAAC,MAAM,GAAG,EAAE,CAAC,EAAE,EAAE,CAAC,iBAAiB,CAAC,EAAE,eAAe,EAAE,CAAC,CAAC;QAEpE,MAAM,EAAE,MAAM,EAAE,GAAG,UAAU,CAAC,GAAG,EAAE,CAAC,eAAe,EAAE,CAAC,CAAC;QACvD,MAAM,GAAG,CAAC,KAAK,IAAI,EAAE;YACnB,MAAM,MAAM,CAAC,OAAO,EAAE,CAAC;QACzB,CAAC,CAAC,CAAC;QAEH,MAAM,CAAC,eAAe,CAAC,CAAC,qBAAqB,CAAC,CAAC,CAAC,CAAC;IACnD,CAAC,CAAC,CAAC;IAEH,EAAE,CAAC,8DAA8D,EAAE,KAAK,IAAI,EAAE;QAC5E,EAAE,CAAC,UAAU,CAAC,QAAQ,EAAE,EAAE,YAAY,EAAE,EAAE,CAAC,EAAE,EAAE,EAAE,CAAC,CAAC;QACnD,WAAW,CAAC,aAAa,EAAE,CAAC;QAC5B,YAAY,CAAC,aAAa,EAAE,CAAC;QAE7B,MAAM,eAAe,GAAG,EAAE,CAAC,EAAE,EAAE,CAAC,iBAAiB,CAAC,SAAS,CAAC,CAAC;QAC7D,wDAAwD;QACxD,MAAM,OAAO,GAAG,UAAU,EAAS,CAAC;QACpC,OAAO,CAAC,GAAG,CAAC,MAAM,GAAG,EAAE,CAAC,EAAE,EAAE,CAAC,iBAAiB,CAAC,EAAE,eAAe,EAAE,CAAC,CAAC;QAEpE,MAAM,EAAE,MAAM,EAAE,GAAG,UAAU,CAAC,GAAG,EAAE,CAAC,eAAe,EAAE,CAAC,CAAC;QACvD,MAAM,GAAG,CAAC,KAAK,IAAI,EAAE;YACnB,MAAM,MAAM,CAAC,OAAO,EAAE,CAAC;QACzB,CAAC,CAAC,CAAC;QAEH,MAAM,CAAC,eAAe,CAAC,CAAC,qBAAqB,CAAC,CAAC,CAAC,CAAC;IACnD,CAAC,CAAC,CAAC;AACL,CAAC,CAAC,CAAC","sourcesContent":["import { act, renderHook } from \"@testing-library/react\";\nimport { afterEach, beforeEach, describe, expect, it, vi } from \"vitest\";\nimport { HostAdaptor } from \"../bridges/adaptor.js\";\nimport { getAdaptor } from \"../bridges/get-adaptor.js\";\nimport { McpAppBridge } from \"../bridges/mcp-app/bridge.js\";\nimport { useRequestClose } from \"./use-request-close.js\";\n\ndescribe(\"useRequestClose\", () => {\n  beforeEach(() => {\n    HostAdaptor.resetInstance();\n    McpAppBridge.resetInstance();\n    vi.stubGlobal(\"skybridge\", { hostType: \"mcp-app\" });\n    vi.stubGlobal(\"openai\", undefined);\n    vi.stubGlobal(\"parent\", { postMessage: vi.fn() });\n  });\n\n  afterEach(() => {\n    vi.unstubAllGlobals();\n    vi.resetAllMocks();\n    HostAdaptor.resetInstance();\n    McpAppBridge.resetInstance();\n  });\n\n  it(\"calls app.requestTeardown via the MCP path\", async () => {\n    const requestTeardown = vi.fn().mockResolvedValue(undefined);\n    // biome-ignore lint/suspicious/noExplicitAny: test seam\n    const adaptor = getAdaptor() as any;\n    adaptor.mcp.getApp = vi.fn().mockResolvedValue({ requestTeardown });\n\n    const { result } = renderHook(() => useRequestClose());\n    await act(async () => {\n      await result.current();\n    });\n\n    expect(requestTeardown).toHaveBeenCalledTimes(1);\n  });\n\n  it(\"calls app.requestTeardown even when window.openai is present\", async () => {\n    vi.stubGlobal(\"openai\", { requestClose: vi.fn() });\n    HostAdaptor.resetInstance();\n    McpAppBridge.resetInstance();\n\n    const requestTeardown = vi.fn().mockResolvedValue(undefined);\n    // biome-ignore lint/suspicious/noExplicitAny: test seam\n    const adaptor = getAdaptor() as any;\n    adaptor.mcp.getApp = vi.fn().mockResolvedValue({ requestTeardown });\n\n    const { result } = renderHook(() => useRequestClose());\n    await act(async () => {\n      await result.current();\n    });\n\n    expect(requestTeardown).toHaveBeenCalledTimes(1);\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-modal.test.js

@@ -1,11 +1,18 @@
 import { renderHook } from "@testing-library/react";
 import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import { HostAdaptor } from "../bridges/adaptor.js";
+import { AppsSdkBridge } from "../bridges/apps-sdk/bridge.js";
+import { McpAppBridge } from "../bridges/mcp-app/bridge.js";
 import { useRequestModal } from "./use-request-modal.js";
 describe("useRequestModal", () => {
     let requestModalMock;
     beforeEach(() => {
+        HostAdaptor.resetInstance();
+        McpAppBridge.resetInstance();
+        AppsSdkBridge.resetInstance();
         requestModalMock = vi.fn();
         vi.stubGlobal("skybridge", { hostType: "apps-sdk" });
+        vi.stubGlobal("parent", { postMessage: vi.fn() });
         vi.stubGlobal("openai", {
             requestModal: requestModalMock,
             view: { mode: "inline" },
@@ -14,6 +21,9 @@ describe("useRequestModal", () => {
     afterEach(() => {
         vi.unstubAllGlobals();
         vi.resetAllMocks();
+        HostAdaptor.resetInstance();
+        McpAppBridge.resetInstance();
+        AppsSdkBridge.resetInstance();
     });
     it("should return an object with open, isOpen, and params properties where isOpen is false when mode is not modal", () => {
         const { result } = renderHook(() => useRequestModal());

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

@@ -1 +1 @@
-{"version":3,"file":"use-request-modal.test.js","sourceRoot":"","sources":["../../../src/web/hooks/use-request-modal.test.ts"],"names":[],"mappings":"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","sourcesContent":["import { renderHook } from \"@testing-library/react\";\nimport { afterEach, beforeEach, describe, expect, it, vi } from \"vitest\";\nimport { useRequestModal } from \"./use-request-modal.js\";\n\ndescribe(\"useRequestModal\", () => {\n  let requestModalMock: ReturnType<typeof vi.fn>;\n\n  beforeEach(() => {\n    requestModalMock = vi.fn();\n    vi.stubGlobal(\"skybridge\", { hostType: \"apps-sdk\" });\n    vi.stubGlobal(\"openai\", {\n      requestModal: requestModalMock,\n      view: { mode: \"inline\" },\n    });\n  });\n\n  afterEach(() => {\n    vi.unstubAllGlobals();\n    vi.resetAllMocks();\n  });\n\n  it(\"should return an object with open, isOpen, and params properties where isOpen is false when mode is not modal\", () => {\n    const { result } = renderHook(() => useRequestModal());\n\n    expect(typeof result.current).toBe(\"object\");\n    expect(result.current).toHaveProperty(\"open\");\n    expect(result.current).toHaveProperty(\"isOpen\");\n    expect(result.current).toHaveProperty(\"params\");\n\n    const { open, isOpen, params } = result.current;\n    expect(typeof open).toBe(\"function\");\n    expect(isOpen).toBe(false);\n    expect(params).toBeUndefined();\n  });\n\n  it(\"should return isOpen as true when mode is modal\", () => {\n    vi.stubGlobal(\"openai\", {\n      requestModal: requestModalMock,\n      view: { mode: \"modal\" },\n    });\n\n    const { result } = renderHook(() => useRequestModal());\n    const { isOpen } = result.current;\n\n    expect(isOpen).toBe(true);\n  });\n\n  it(\"should return params from view when available\", () => {\n    const testParams = { foo: \"bar\", baz: 42 };\n    vi.stubGlobal(\"openai\", {\n      requestModal: requestModalMock,\n      view: { mode: \"modal\", params: testParams },\n    });\n\n    const { result } = renderHook(() => useRequestModal());\n    const { params } = result.current;\n\n    expect(params).toEqual(testParams);\n  });\n\n  it(\"should call window.openai.requestModal with the options when open is called\", () => {\n    const { result } = renderHook(() => useRequestModal());\n    const { open } = result.current;\n\n    const options = {\n      title: \"Test Modal\",\n      params: { foo: \"bar\" },\n      template: \"ui://view/modal-template.html\",\n    };\n    open(options);\n\n    expect(requestModalMock).toHaveBeenCalledTimes(1);\n    expect(requestModalMock).toHaveBeenCalledWith(options);\n  });\n});\n"]}
+{"version":3,"file":"use-request-modal.test.js","sourceRoot":"","sources":["../../../src/web/hooks/use-request-modal.test.ts"],"names":[],"mappings":"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","sourcesContent":["import { renderHook } from \"@testing-library/react\";\nimport { afterEach, beforeEach, describe, expect, it, vi } from \"vitest\";\nimport { HostAdaptor } from \"../bridges/adaptor.js\";\nimport { AppsSdkBridge } from \"../bridges/apps-sdk/bridge.js\";\nimport { McpAppBridge } from \"../bridges/mcp-app/bridge.js\";\nimport { useRequestModal } from \"./use-request-modal.js\";\n\ndescribe(\"useRequestModal\", () => {\n  let requestModalMock: ReturnType<typeof vi.fn>;\n\n  beforeEach(() => {\n    HostAdaptor.resetInstance();\n    McpAppBridge.resetInstance();\n    AppsSdkBridge.resetInstance();\n    requestModalMock = vi.fn();\n    vi.stubGlobal(\"skybridge\", { hostType: \"apps-sdk\" });\n    vi.stubGlobal(\"parent\", { postMessage: vi.fn() });\n    vi.stubGlobal(\"openai\", {\n      requestModal: requestModalMock,\n      view: { mode: \"inline\" },\n    });\n  });\n\n  afterEach(() => {\n    vi.unstubAllGlobals();\n    vi.resetAllMocks();\n    HostAdaptor.resetInstance();\n    McpAppBridge.resetInstance();\n    AppsSdkBridge.resetInstance();\n  });\n\n  it(\"should return an object with open, isOpen, and params properties where isOpen is false when mode is not modal\", () => {\n    const { result } = renderHook(() => useRequestModal());\n\n    expect(typeof result.current).toBe(\"object\");\n    expect(result.current).toHaveProperty(\"open\");\n    expect(result.current).toHaveProperty(\"isOpen\");\n    expect(result.current).toHaveProperty(\"params\");\n\n    const { open, isOpen, params } = result.current;\n    expect(typeof open).toBe(\"function\");\n    expect(isOpen).toBe(false);\n    expect(params).toBeUndefined();\n  });\n\n  it(\"should return isOpen as true when mode is modal\", () => {\n    vi.stubGlobal(\"openai\", {\n      requestModal: requestModalMock,\n      view: { mode: \"modal\" },\n    });\n\n    const { result } = renderHook(() => useRequestModal());\n    const { isOpen } = result.current;\n\n    expect(isOpen).toBe(true);\n  });\n\n  it(\"should return params from view when available\", () => {\n    const testParams = { foo: \"bar\", baz: 42 };\n    vi.stubGlobal(\"openai\", {\n      requestModal: requestModalMock,\n      view: { mode: \"modal\", params: testParams },\n    });\n\n    const { result } = renderHook(() => useRequestModal());\n    const { params } = result.current;\n\n    expect(params).toEqual(testParams);\n  });\n\n  it(\"should call window.openai.requestModal with the options when open is called\", () => {\n    const { result } = renderHook(() => useRequestModal());\n    const { open } = result.current;\n\n    const options = {\n      title: \"Test Modal\",\n      params: { foo: \"bar\" },\n      template: \"ui://view/modal-template.html\",\n    };\n    open(options);\n\n    expect(requestModalMock).toHaveBeenCalledTimes(1);\n    expect(requestModalMock).toHaveBeenCalledWith(options);\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 {};

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

@@ -0,0 +1,47 @@
+import { renderHook, waitFor } from "@testing-library/react";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import { HostAdaptor } from "../bridges/adaptor.js";
+import { McpAppBridge } from "../bridges/mcp-app/bridge.js";
+import { getMcpAppHostPostMessageMock, MockResizeObserver, } from "./test/utils.js";
+import { useRequestSize } from "./use-request-size.js";
+describe("useRequestSize", () => {
+    let postMessageMock;
+    beforeEach(() => {
+        HostAdaptor.resetInstance();
+        McpAppBridge.resetInstance();
+        vi.stubGlobal("skybridge", { hostType: "mcp-app" });
+        vi.stubGlobal("openai", undefined);
+        vi.stubGlobal("ResizeObserver", MockResizeObserver);
+        postMessageMock = getMcpAppHostPostMessageMock();
+        vi.stubGlobal("parent", { postMessage: postMessageMock });
+    });
+    afterEach(() => {
+        vi.unstubAllGlobals();
+        vi.resetAllMocks();
+        HostAdaptor.resetInstance();
+        McpAppBridge.resetInstance();
+    });
+    it("sends a ui/notifications/size-changed notification with width and height", async () => {
+        const { result } = renderHook(() => useRequestSize());
+        await result.current({ width: 800, height: 400 });
+        await waitFor(() => {
+            expect(postMessageMock).toHaveBeenCalledWith(expect.objectContaining({
+                jsonrpc: "2.0",
+                method: "ui/notifications/size-changed",
+                params: { width: 800, height: 400 },
+            }), "*");
+        });
+    });
+    it("forwards height-only payloads as-is", async () => {
+        const { result } = renderHook(() => useRequestSize());
+        await result.current({ height: 400 });
+        await waitFor(() => {
+            expect(postMessageMock).toHaveBeenCalledWith(expect.objectContaining({
+                jsonrpc: "2.0",
+                method: "ui/notifications/size-changed",
+                params: { height: 400 },
+            }), "*");
+        });
+    });
+});
+//# sourceMappingURL=use-request-size.test.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"use-request-size.test.js","sourceRoot":"","sources":["../../../src/web/hooks/use-request-size.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,WAAW,EAAE,MAAM,uBAAuB,CAAC;AACpD,OAAO,EAAE,YAAY,EAAE,MAAM,8BAA8B,CAAC;AAC5D,OAAO,EACL,4BAA4B,EAC5B,kBAAkB,GACnB,MAAM,iBAAiB,CAAC;AACzB,OAAO,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAC;AAEvD,QAAQ,CAAC,gBAAgB,EAAE,GAAG,EAAE;IAC9B,IAAI,eAAgE,CAAC;IAErE,UAAU,CAAC,GAAG,EAAE;QACd,WAAW,CAAC,aAAa,EAAE,CAAC;QAC5B,YAAY,CAAC,aAAa,EAAE,CAAC;QAC7B,EAAE,CAAC,UAAU,CAAC,WAAW,EAAE,EAAE,QAAQ,EAAE,SAAS,EAAE,CAAC,CAAC;QACpD,EAAE,CAAC,UAAU,CAAC,QAAQ,EAAE,SAAS,CAAC,CAAC;QACnC,EAAE,CAAC,UAAU,CAAC,gBAAgB,EAAE,kBAAkB,CAAC,CAAC;QACpD,eAAe,GAAG,4BAA4B,EAAE,CAAC;QACjD,EAAE,CAAC,UAAU,CAAC,QAAQ,EAAE,EAAE,WAAW,EAAE,eAAe,EAAE,CAAC,CAAC;IAC5D,CAAC,CAAC,CAAC;IAEH,SAAS,CAAC,GAAG,EAAE;QACb,EAAE,CAAC,gBAAgB,EAAE,CAAC;QACtB,EAAE,CAAC,aAAa,EAAE,CAAC;QACnB,WAAW,CAAC,aAAa,EAAE,CAAC;QAC5B,YAAY,CAAC,aAAa,EAAE,CAAC;IAC/B,CAAC,CAAC,CAAC;IAEH,EAAE,CAAC,0EAA0E,EAAE,KAAK,IAAI,EAAE;QACxF,MAAM,EAAE,MAAM,EAAE,GAAG,UAAU,CAAC,GAAG,EAAE,CAAC,cAAc,EAAE,CAAC,CAAC;QAEtD,MAAM,MAAM,CAAC,OAAO,CAAC,EAAE,KAAK,EAAE,GAAG,EAAE,MAAM,EAAE,GAAG,EAAE,CAAC,CAAC;QAElD,MAAM,OAAO,CAAC,GAAG,EAAE;YACjB,MAAM,CAAC,eAAe,CAAC,CAAC,oBAAoB,CAC1C,MAAM,CAAC,gBAAgB,CAAC;gBACtB,OAAO,EAAE,KAAK;gBACd,MAAM,EAAE,+BAA+B;gBACvC,MAAM,EAAE,EAAE,KAAK,EAAE,GAAG,EAAE,MAAM,EAAE,GAAG,EAAE;aACpC,CAAC,EACF,GAAG,CACJ,CAAC;QACJ,CAAC,CAAC,CAAC;IACL,CAAC,CAAC,CAAC;IAEH,EAAE,CAAC,qCAAqC,EAAE,KAAK,IAAI,EAAE;QACnD,MAAM,EAAE,MAAM,EAAE,GAAG,UAAU,CAAC,GAAG,EAAE,CAAC,cAAc,EAAE,CAAC,CAAC;QAEtD,MAAM,MAAM,CAAC,OAAO,CAAC,EAAE,MAAM,EAAE,GAAG,EAAE,CAAC,CAAC;QAEtC,MAAM,OAAO,CAAC,GAAG,EAAE;YACjB,MAAM,CAAC,eAAe,CAAC,CAAC,oBAAoB,CAC1C,MAAM,CAAC,gBAAgB,CAAC;gBACtB,OAAO,EAAE,KAAK;gBACd,MAAM,EAAE,+BAA+B;gBACvC,MAAM,EAAE,EAAE,MAAM,EAAE,GAAG,EAAE;aACxB,CAAC,EACF,GAAG,CACJ,CAAC;QACJ,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 { HostAdaptor } from \"../bridges/adaptor.js\";\nimport { McpAppBridge } from \"../bridges/mcp-app/bridge.js\";\nimport {\n  getMcpAppHostPostMessageMock,\n  MockResizeObserver,\n} from \"./test/utils.js\";\nimport { useRequestSize } from \"./use-request-size.js\";\n\ndescribe(\"useRequestSize\", () => {\n  let postMessageMock: ReturnType<typeof getMcpAppHostPostMessageMock>;\n\n  beforeEach(() => {\n    HostAdaptor.resetInstance();\n    McpAppBridge.resetInstance();\n    vi.stubGlobal(\"skybridge\", { hostType: \"mcp-app\" });\n    vi.stubGlobal(\"openai\", undefined);\n    vi.stubGlobal(\"ResizeObserver\", MockResizeObserver);\n    postMessageMock = getMcpAppHostPostMessageMock();\n    vi.stubGlobal(\"parent\", { postMessage: postMessageMock });\n  });\n\n  afterEach(() => {\n    vi.unstubAllGlobals();\n    vi.resetAllMocks();\n    HostAdaptor.resetInstance();\n    McpAppBridge.resetInstance();\n  });\n\n  it(\"sends a ui/notifications/size-changed notification with width and height\", async () => {\n    const { result } = renderHook(() => useRequestSize());\n\n    await result.current({ width: 800, height: 400 });\n\n    await waitFor(() => {\n      expect(postMessageMock).toHaveBeenCalledWith(\n        expect.objectContaining({\n          jsonrpc: \"2.0\",\n          method: \"ui/notifications/size-changed\",\n          params: { width: 800, height: 400 },\n        }),\n        \"*\",\n      );\n    });\n  });\n\n  it(\"forwards height-only payloads as-is\", async () => {\n    const { result } = renderHook(() => useRequestSize());\n\n    await result.current({ height: 400 });\n\n    await waitFor(() => {\n      expect(postMessageMock).toHaveBeenCalledWith(\n        expect.objectContaining({\n          jsonrpc: \"2.0\",\n          method: \"ui/notifications/size-changed\",\n          params: { height: 400 },\n        }),\n        \"*\",\n      );\n    });\n  });\n});\n"]}

package/dist/web/hooks/use-send-follow-up-message.d.ts

@@ -1,2 +1,19 @@
 import { type SendFollowUpMessageOptions } from "../bridges/index.js";
+/**
+ * Send a follow-up message to the LLM on behalf of the view, as if the user
+ * had sent it. Use to chain interactions from view UI (e.g. a button that
+ * triggers the next assistant turn).
+ *
+ * Pass `scrollToBottom: false` to keep the chat scroll position when the host
+ * posts the message. This option is Apps-SDK-only; it is silently ignored in
+ * the MCP Apps runtime.
+ *
+ * @example
+ * ```tsx
+ * const send = useSendFollowUpMessage();
+ * <button onClick={() => send("Summarize the last 5 results")}>Summarize</button>
+ * ```
+ *
+ * @see https://docs.skybridge.tech/api-reference/use-send-follow-up-message
+ */
 export declare function useSendFollowUpMessage(): (prompt: string, options?: SendFollowUpMessageOptions) => Promise<void>;