skybridge 0.0.0-dev.f1ff41a → 0.0.0-dev.f2073a1

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

@@ -1,6 +1,39 @@
+/**
+ * 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) => Promise<import("../index.js").FileMetadata>;
+    upload: (file: File, options?: import("../index.js").UploadFileOptions) => Promise<import("../index.js").FileMetadata>;
     getDownloadUrl: (file: import("../index.js").FileMetadata) => Promise<{
         downloadUrl: string;
     }>;
+    selectFiles: () => Promise<import("../index.js").FileMetadata[]>;
 };

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

@@ -1,9 +1,42 @@
 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 {
         upload: adaptor.uploadFile,
         getDownloadUrl: adaptor.getFileDownloadUrl,
+        selectFiles: adaptor.selectFiles,
     };
 }
 //# sourceMappingURL=use-files.js.map

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;KAC3C,CAAC;AACJ,CAAC"}
+{"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-files.test.js

@@ -1,24 +1,56 @@
 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 { useFiles } from "./use-files.js";
 describe("useFiles", () => {
     const OpenaiMock = {
-        uploadFile: vi.fn(),
+        uploadFile: vi.fn().mockResolvedValue({
+            fileId: `sediment://file_abc123`,
+        }),
         getFileDownloadUrl: vi.fn(),
+        widgetState: null,
+        setWidgetState: vi.fn(),
     };
     beforeEach(() => {
-        vi.stubGlobal("skybridge", { hostType: "apps-sdk" });
+        HostAdaptor.resetInstance();
+        McpAppBridge.resetInstance();
+        AppsSdkBridge.resetInstance();
+        vi.stubGlobal("skybridge", {});
         vi.stubGlobal("openai", OpenaiMock);
+        vi.stubGlobal("parent", { postMessage: vi.fn() });
     });
     afterEach(() => {
         vi.unstubAllGlobals();
-        vi.resetAllMocks();
+        vi.clearAllMocks();
+        HostAdaptor.resetInstance();
+        McpAppBridge.resetInstance();
+        AppsSdkBridge.resetInstance();
     });
     const dummyFile = new File([], "test.txt");
     it("should upload a file to ChatGPT", () => {
         const { result } = renderHook(() => useFiles());
         result.current.upload(dummyFile);
-        expect(OpenaiMock.uploadFile).toHaveBeenCalledWith(dummyFile);
+        expect(OpenaiMock.uploadFile).toHaveBeenCalledWith(dummyFile, undefined);
+    });
+    it("should upload a file with library option", () => {
+        const { result } = renderHook(() => useFiles());
+        result.current.upload(dummyFile, { library: true });
+        expect(OpenaiMock.uploadFile).toHaveBeenCalledWith(dummyFile, {
+            library: true,
+        });
+    });
+    it("should select files from ChatGPT", async () => {
+        const selectedFiles = [
+            { fileId: "file_1", fileName: "doc.pdf", mimeType: "application/pdf" },
+        ];
+        OpenaiMock.selectFiles = vi.fn().mockResolvedValue(selectedFiles);
+        const { result } = renderHook(() => useFiles());
+        const files = await result.current.selectFiles();
+        expect(OpenaiMock.selectFiles).toHaveBeenCalled();
+        expect(files).toEqual(selectedFiles);
+        delete OpenaiMock.selectFiles;
     });
     it("should download a file from ChatGPT", () => {
         const fileId = "123";

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

@@ -1 +1 @@
-{"version":3,"file":"use-files.test.js","sourceRoot":"","sources":["../../../src/web/hooks/use-files.test.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,wBAAwB,CAAC;AACpD,OAAO,EAAE,SAAS,EAAE,UAAU,EAAE,QAAQ,EAAE,MAAM,EAAE,EAAE,EAAE,EAAE,EAAE,MAAM,QAAQ,CAAC;AACzE,OAAO,EAAE,QAAQ,EAAE,MAAM,gBAAgB,CAAC;AAE1C,QAAQ,CAAC,UAAU,EAAE,GAAG,EAAE;IACxB,MAAM,UAAU,GAAG;QACjB,UAAU,EAAE,EAAE,CAAC,EAAE,EAAE;QACnB,kBAAkB,EAAE,EAAE,CAAC,EAAE,EAAE;KAC5B,CAAC;IAEF,UAAU,CAAC,GAAG,EAAE;QACd,EAAE,CAAC,UAAU,CAAC,WAAW,EAAE,EAAE,QAAQ,EAAE,UAAU,EAAE,CAAC,CAAC;QACrD,EAAE,CAAC,UAAU,CAAC,QAAQ,EAAE,UAAU,CAAC,CAAC;IACtC,CAAC,CAAC,CAAC;IAEH,SAAS,CAAC,GAAG,EAAE;QACb,EAAE,CAAC,gBAAgB,EAAE,CAAC;QACtB,EAAE,CAAC,aAAa,EAAE,CAAC;IACrB,CAAC,CAAC,CAAC;IAEH,MAAM,SAAS,GAAG,IAAI,IAAI,CAAC,EAAE,EAAE,UAAU,CAAC,CAAC;IAE3C,EAAE,CAAC,iCAAiC,EAAE,GAAG,EAAE;QACzC,MAAM,EAAE,MAAM,EAAE,GAAG,UAAU,CAAC,GAAG,EAAE,CAAC,QAAQ,EAAE,CAAC,CAAC;QAEhD,MAAM,CAAC,OAAO,CAAC,MAAM,CAAC,SAAS,CAAC,CAAC;QACjC,MAAM,CAAC,UAAU,CAAC,UAAU,CAAC,CAAC,oBAAoB,CAAC,SAAS,CAAC,CAAC;IAChE,CAAC,CAAC,CAAC;IAEH,EAAE,CAAC,qCAAqC,EAAE,GAAG,EAAE;QAC7C,MAAM,MAAM,GAAG,KAAK,CAAC;QACrB,MAAM,EAAE,MAAM,EAAE,GAAG,UAAU,CAAC,GAAG,EAAE,CAAC,QAAQ,EAAE,CAAC,CAAC;QAEhD,MAAM,CAAC,OAAO,CAAC,cAAc,CAAC,EAAE,MAAM,EAAE,CAAC,CAAC;QAC1C,MAAM,CAAC,UAAU,CAAC,kBAAkB,CAAC,CAAC,oBAAoB,CAAC,EAAE,MAAM,EAAE,CAAC,CAAC;IACzE,CAAC,CAAC,CAAC;AACL,CAAC,CAAC,CAAC"}
+{"version":3,"file":"use-files.test.js","sourceRoot":"","sources":["../../../src/web/hooks/use-files.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 { useFiles } from \"./use-files.js\";\n\ndescribe(\"useFiles\", () => {\n  const OpenaiMock: Record<string, unknown> = {\n    uploadFile: vi.fn().mockResolvedValue({\n      fileId: `sediment://file_abc123`,\n    }),\n    getFileDownloadUrl: vi.fn(),\n    widgetState: null,\n    setWidgetState: vi.fn(),\n  };\n\n  beforeEach(() => {\n    HostAdaptor.resetInstance();\n    McpAppBridge.resetInstance();\n    AppsSdkBridge.resetInstance();\n    vi.stubGlobal(\"skybridge\", {});\n    vi.stubGlobal(\"openai\", OpenaiMock);\n    vi.stubGlobal(\"parent\", { postMessage: vi.fn() });\n  });\n\n  afterEach(() => {\n    vi.unstubAllGlobals();\n    vi.clearAllMocks();\n    HostAdaptor.resetInstance();\n    McpAppBridge.resetInstance();\n    AppsSdkBridge.resetInstance();\n  });\n\n  const dummyFile = new File([], \"test.txt\");\n\n  it(\"should upload a file to ChatGPT\", () => {\n    const { result } = renderHook(() => useFiles());\n\n    result.current.upload(dummyFile);\n    expect(OpenaiMock.uploadFile).toHaveBeenCalledWith(dummyFile, undefined);\n  });\n\n  it(\"should upload a file with library option\", () => {\n    const { result } = renderHook(() => useFiles());\n\n    result.current.upload(dummyFile, { library: true });\n    expect(OpenaiMock.uploadFile).toHaveBeenCalledWith(dummyFile, {\n      library: true,\n    });\n  });\n\n  it(\"should select files from ChatGPT\", async () => {\n    const selectedFiles = [\n      { fileId: \"file_1\", fileName: \"doc.pdf\", mimeType: \"application/pdf\" },\n    ];\n    OpenaiMock.selectFiles = vi.fn().mockResolvedValue(selectedFiles);\n\n    const { result } = renderHook(() => useFiles());\n\n    const files = await result.current.selectFiles();\n    expect(OpenaiMock.selectFiles).toHaveBeenCalled();\n    expect(files).toEqual(selectedFiles);\n\n    delete OpenaiMock.selectFiles;\n  });\n\n  it(\"should download a file from ChatGPT\", () => {\n    const fileId = \"123\";\n    const { result } = renderHook(() => useFiles());\n\n    result.current.getDownloadUrl({ fileId });\n    expect(OpenaiMock.getFileDownloadUrl).toHaveBeenCalledWith({ fileId });\n  });\n});\n"]}

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

@@ -0,0 +1,44 @@
+import type { McpUiHostCapabilities } from "@modelcontextprotocol/ext-apps";
+/**
+ * Known host applications, as normalized slugs. Unrecognized hosts surface
+ * their raw `hostInfo.name` string instead.
+ */
+export type Host = "chatgpt" | "claude" | "cursor" | "goose" | "mistral-vibe" | "alpic";
+/**
+ * OpenAI MCP extensions the host advertises. Each flag is `true` only when the
+ * host sends a truthy `hostCapabilities.experimental["openai/<name>"]`, so every flag is
+ * `false` before the handshake and on hosts other than ChatGPT.
+ */
+export type OpenAIHostCapabilities = {
+    /** Read, subscribe to and write the file opened through a file entrypoint. */
+    resource: boolean;
+    /** Titles, thumbnails and background content in `ui/update-model-context`. */
+    modelContext: boolean;
+    /** `ui/message` targets and titled items. */
+    message: boolean;
+    /** Open a local file with `openai/files/open`. */
+    files: boolean;
+};
+export type HostInfo = {
+    name: Host | (string & {}) | undefined;
+    version: string | undefined;
+    /** The host's MCP Apps capabilities, `undefined` until the handshake. */
+    capabilities: McpUiHostCapabilities | undefined;
+    /** OpenAI MCP extensions the host supports. */
+    openaiCapabilities: OpenAIHostCapabilities;
+};
+/**
+ * Identity and capabilities of the host application rendering the view, from
+ * the MCP Apps `ui/initialize` handshake. `name` is normalized to a
+ * {@link Host} slug when recognized, otherwise the raw string; `name`,
+ * `version` and `capabilities` are `undefined` until the handshake resolves
+ * (the view renders first and re-renders once it lands).
+ *
+ * @example
+ * ```tsx
+ * const { name, openaiCapabilities } = useHost();
+ * if (name === "claude") return <ClaudeLayout />;
+ * if (openaiCapabilities.files) return <OpenFileButton />;
+ * ```
+ */
+export declare function useHost(): HostInfo;

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

@@ -0,0 +1,45 @@
+import { useMemo } from "react";
+import { useMcpAppContext } from "../bridges/index.js";
+const HOST_BY_REPORTED_NAME = {
+    chatgpt: "chatgpt",
+    Claude: "claude",
+    Cursor: "cursor",
+    "MCP-UI Host": "goose",
+    "Le Chat": "mistral-vibe",
+    "alpic-playground": "alpic",
+};
+/**
+ * Identity and capabilities of the host application rendering the view, from
+ * the MCP Apps `ui/initialize` handshake. `name` is normalized to a
+ * {@link Host} slug when recognized, otherwise the raw string; `name`,
+ * `version` and `capabilities` are `undefined` until the handshake resolves
+ * (the view renders first and re-renders once it lands).
+ *
+ * @example
+ * ```tsx
+ * const { name, openaiCapabilities } = useHost();
+ * if (name === "claude") return <ClaudeLayout />;
+ * if (openaiCapabilities.files) return <OpenFileButton />;
+ * ```
+ */
+export function useHost() {
+    const hostInfo = useMcpAppContext("hostInfo");
+    const capabilities = useMcpAppContext("hostCapabilities") ?? undefined;
+    const name = hostInfo?.name;
+    const openaiCapabilities = useMemo(() => {
+        const supports = (extension) => Boolean(capabilities?.experimental?.[`openai/${extension}`]);
+        return {
+            resource: supports("resource"),
+            modelContext: supports("modelContext"),
+            message: supports("message"),
+            files: supports("files"),
+        };
+    }, [capabilities]);
+    return {
+        name: name !== undefined ? (HOST_BY_REPORTED_NAME[name] ?? name) : undefined,
+        version: hostInfo?.version,
+        capabilities,
+        openaiCapabilities,
+    };
+}
+//# sourceMappingURL=use-host.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"use-host.js","sourceRoot":"","sources":["../../../src/web/hooks/use-host.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,OAAO,EAAE,MAAM,OAAO,CAAC;AAChC,OAAO,EAAE,gBAAgB,EAAE,MAAM,qBAAqB,CAAC;AAcvD,MAAM,qBAAqB,GAAyB;IAClD,OAAO,EAAE,SAAS;IAClB,MAAM,EAAE,QAAQ;IAChB,MAAM,EAAE,QAAQ;IAChB,aAAa,EAAE,OAAO;IACtB,SAAS,EAAE,cAAc;IACzB,kBAAkB,EAAE,OAAO;CAC5B,CAAC;AA2BF;;;;;;;;;;;;;GAaG;AACH,MAAM,UAAU,OAAO;IACrB,MAAM,QAAQ,GAAG,gBAAgB,CAAC,UAAU,CAAC,CAAC;IAC9C,MAAM,YAAY,GAAG,gBAAgB,CAAC,kBAAkB,CAAC,IAAI,SAAS,CAAC;IACvE,MAAM,IAAI,GAAG,QAAQ,EAAE,IAAI,CAAC;IAC5B,MAAM,kBAAkB,GAAG,OAAO,CAAC,GAAG,EAAE;QACtC,MAAM,QAAQ,GAAG,CAAC,SAAiB,EAAE,EAAE,CACrC,OAAO,CAAC,YAAY,EAAE,YAAY,EAAE,CAAC,UAAU,SAAS,EAAE,CAAC,CAAC,CAAC;QAC/D,OAAO;YACL,QAAQ,EAAE,QAAQ,CAAC,UAAU,CAAC;YAC9B,YAAY,EAAE,QAAQ,CAAC,cAAc,CAAC;YACtC,OAAO,EAAE,QAAQ,CAAC,SAAS,CAAC;YAC5B,KAAK,EAAE,QAAQ,CAAC,OAAO,CAAC;SACzB,CAAC;IACJ,CAAC,EAAE,CAAC,YAAY,CAAC,CAAC,CAAC;IAEnB,OAAO;QACL,IAAI,EACF,IAAI,KAAK,SAAS,CAAC,CAAC,CAAC,CAAC,qBAAqB,CAAC,IAAI,CAAC,IAAI,IAAI,CAAC,CAAC,CAAC,CAAC,SAAS;QACxE,OAAO,EAAE,QAAQ,EAAE,OAAO;QAC1B,YAAY;QACZ,kBAAkB;KACnB,CAAC;AACJ,CAAC","sourcesContent":["import type { McpUiHostCapabilities } from \"@modelcontextprotocol/ext-apps\";\nimport { useMemo } from \"react\";\nimport { useMcpAppContext } from \"../bridges/index.js\";\n\n/**\n * Known host applications, as normalized slugs. Unrecognized hosts surface\n * their raw `hostInfo.name` string instead.\n */\nexport type Host =\n  | \"chatgpt\"\n  | \"claude\"\n  | \"cursor\"\n  | \"goose\"\n  | \"mistral-vibe\"\n  | \"alpic\";\n\nconst HOST_BY_REPORTED_NAME: Record<string, Host> = {\n  chatgpt: \"chatgpt\",\n  Claude: \"claude\",\n  Cursor: \"cursor\",\n  \"MCP-UI Host\": \"goose\",\n  \"Le Chat\": \"mistral-vibe\",\n  \"alpic-playground\": \"alpic\",\n};\n\n/**\n * OpenAI MCP extensions the host advertises. Each flag is `true` only when the\n * host sends a truthy `hostCapabilities.experimental[\"openai/<name>\"]`, so every flag is\n * `false` before the handshake and on hosts other than ChatGPT.\n */\nexport type OpenAIHostCapabilities = {\n  /** Read, subscribe to and write the file opened through a file entrypoint. */\n  resource: boolean;\n  /** Titles, thumbnails and background content in `ui/update-model-context`. */\n  modelContext: boolean;\n  /** `ui/message` targets and titled items. */\n  message: boolean;\n  /** Open a local file with `openai/files/open`. */\n  files: boolean;\n};\n\nexport type HostInfo = {\n  name: Host | (string & {}) | undefined;\n  version: string | undefined;\n  /** The host's MCP Apps capabilities, `undefined` until the handshake. */\n  capabilities: McpUiHostCapabilities | undefined;\n  /** OpenAI MCP extensions the host supports. */\n  openaiCapabilities: OpenAIHostCapabilities;\n};\n\n/**\n * Identity and capabilities of the host application rendering the view, from\n * the MCP Apps `ui/initialize` handshake. `name` is normalized to a\n * {@link Host} slug when recognized, otherwise the raw string; `name`,\n * `version` and `capabilities` are `undefined` until the handshake resolves\n * (the view renders first and re-renders once it lands).\n *\n * @example\n * ```tsx\n * const { name, openaiCapabilities } = useHost();\n * if (name === \"claude\") return <ClaudeLayout />;\n * if (openaiCapabilities.files) return <OpenFileButton />;\n * ```\n */\nexport function useHost(): HostInfo {\n  const hostInfo = useMcpAppContext(\"hostInfo\");\n  const capabilities = useMcpAppContext(\"hostCapabilities\") ?? undefined;\n  const name = hostInfo?.name;\n  const openaiCapabilities = useMemo(() => {\n    const supports = (extension: string) =>\n      Boolean(capabilities?.experimental?.[`openai/${extension}`]);\n    return {\n      resource: supports(\"resource\"),\n      modelContext: supports(\"modelContext\"),\n      message: supports(\"message\"),\n      files: supports(\"files\"),\n    };\n  }, [capabilities]);\n\n  return {\n    name:\n      name !== undefined ? (HOST_BY_REPORTED_NAME[name] ?? name) : undefined,\n    version: hostInfo?.version,\n    capabilities,\n    openaiCapabilities,\n  };\n}\n"]}

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

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

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

@@ -0,0 +1,59 @@
+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 { useHost } from "./use-host.js";
+const stubHost = (hostInfo) => {
+    vi.stubGlobal("parent", {
+        postMessage: getMcpAppHostPostMessageMock({}, { hostInfo }),
+    });
+};
+describe("useHost", () => {
+    beforeEach(() => {
+        HostAdaptor.resetInstance();
+        McpAppBridge.resetInstance();
+        vi.stubGlobal("openai", undefined);
+        vi.stubGlobal("skybridge", {});
+        vi.stubGlobal("ResizeObserver", MockResizeObserver);
+    });
+    afterEach(() => {
+        vi.unstubAllGlobals();
+        vi.resetAllMocks();
+        McpAppBridge.resetInstance();
+        HostAdaptor.resetInstance();
+    });
+    it("is undefined before the handshake resolves, then populated after", async () => {
+        stubHost({ name: "Claude", version: "1.2.3" });
+        const { result } = renderHook(() => useHost());
+        expect(result.current.name).toBeUndefined();
+        expect(result.current.version).toBeUndefined();
+        await waitFor(() => {
+            expect(result.current.name).toBe("claude");
+            expect(result.current.version).toBe("1.2.3");
+        });
+    });
+    it.each([
+        ["chatgpt", "chatgpt"],
+        ["Claude", "claude"],
+        ["Cursor", "cursor"],
+        ["MCP-UI Host", "goose"],
+        ["Le Chat", "mistral-vibe"],
+        ["alpic-playground", "alpic"],
+    ])("normalizes reported name %j to slug %j", async (reported, slug) => {
+        stubHost({ name: reported, version: "1.0.0" });
+        const { result } = renderHook(() => useHost());
+        await waitFor(() => {
+            expect(result.current.name).toBe(slug);
+        });
+    });
+    it("preserves an unrecognized reported name as-is", async () => {
+        stubHost({ name: "Some Future Host", version: "9.9.9" });
+        const { result } = renderHook(() => useHost());
+        await waitFor(() => {
+            expect(result.current.name).toBe("Some Future Host");
+            expect(result.current.version).toBe("9.9.9");
+        });
+    });
+});
+//# sourceMappingURL=use-host.test.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"use-host.test.js","sourceRoot":"","sources":["../../../src/web/hooks/use-host.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 { type Host, useHost } from \"./use-host.js\";\n\nconst stubHost = (hostInfo?: { name: string; version: string }) => {\n  vi.stubGlobal(\"parent\", {\n    postMessage: getMcpAppHostPostMessageMock({}, { hostInfo }),\n  });\n};\n\ndescribe(\"useHost\", () => {\n  beforeEach(() => {\n    HostAdaptor.resetInstance();\n    McpAppBridge.resetInstance();\n    vi.stubGlobal(\"openai\", undefined);\n    vi.stubGlobal(\"skybridge\", {});\n    vi.stubGlobal(\"ResizeObserver\", MockResizeObserver);\n  });\n\n  afterEach(() => {\n    vi.unstubAllGlobals();\n    vi.resetAllMocks();\n    McpAppBridge.resetInstance();\n    HostAdaptor.resetInstance();\n  });\n\n  it(\"is undefined before the handshake resolves, then populated after\", async () => {\n    stubHost({ name: \"Claude\", version: \"1.2.3\" });\n    const { result } = renderHook(() => useHost());\n\n    expect(result.current.name).toBeUndefined();\n    expect(result.current.version).toBeUndefined();\n\n    await waitFor(() => {\n      expect(result.current.name).toBe(\"claude\");\n      expect(result.current.version).toBe(\"1.2.3\");\n    });\n  });\n\n  it.each<[string, Host]>([\n    [\"chatgpt\", \"chatgpt\"],\n    [\"Claude\", \"claude\"],\n    [\"Cursor\", \"cursor\"],\n    [\"MCP-UI Host\", \"goose\"],\n    [\"Le Chat\", \"mistral-vibe\"],\n    [\"alpic-playground\", \"alpic\"],\n  ])(\"normalizes reported name %j to slug %j\", async (reported, slug) => {\n    stubHost({ name: reported, version: \"1.0.0\" });\n    const { result } = renderHook(() => useHost());\n\n    await waitFor(() => {\n      expect(result.current.name).toBe(slug);\n    });\n  });\n\n  it(\"preserves an unrecognized reported name as-is\", async () => {\n    stubHost({ name: \"Some Future Host\", version: \"9.9.9\" });\n    const { result } = renderHook(() => useHost());\n\n    await waitFor(() => {\n      expect(result.current.name).toBe(\"Some Future Host\");\n      expect(result.current.version).toBe(\"9.9.9\");\n    });\n  });\n});\n"]}

package/dist/web/hooks/use-model-context.d.ts

@@ -0,0 +1,44 @@
+import type { OpenAIHostContext } from "../bridges/mcp-app/types.js";
+import type { ModelContextParams } from "../bridges/types.js";
+/** Model context the view attached, as ChatGPT reports it back. */
+export type ModelContextState = OpenAIHostContext["openai/modelContext"];
+/**
+ * Send content to the model through the MCP Apps `ui/update-model-context`
+ * request. Each `update` replaces what this hook sent before. Outside ChatGPT
+ * it is merged with the {@link useViewState} state, which wins on shared
+ * `structuredContent` keys.
+ *
+ * ChatGPT also reads the OpenAI presentation metadata, shows each block as a
+ * composer attachment and reports the attached context back:
+ * `_meta["openai/title"]`, `_meta["openai/thumbnail"]` on text blocks, and
+ * `annotations.audience: ["assistant"]` to hide a block from the user.
+ *
+ * - `supported`: whether the host advertises `updateModelContext` or
+ *   `openai/modelContext`.
+ * - `context`: ChatGPT only, the attached context; `null` once the user
+ *   removed it, `undefined` when the host never reported one.
+ * - `update`: replaces the context and resolves with ChatGPT's `updateId`,
+ *   to compare with `context.updateId`. Rejects with `NotSupportedError` on
+ *   hosts that don't advertise model context updates.
+ *
+ * @example
+ * ```tsx
+ * const { supported, update } = useModelContext();
+ * update({
+ *   content: [
+ *     {
+ *       type: "text",
+ *       text: "Selected: M6 hex bolt",
+ *       _meta: { "openai/title": "Hex bolt" },
+ *     },
+ *   ],
+ * });
+ * ```
+ *
+ * @see https://docs.skybridge.tech/api-reference/use-model-context
+ */
+export declare function useModelContext(): {
+    supported: boolean;
+    context: ModelContextState;
+    update: (params: ModelContextParams) => Promise<string | undefined>;
+};

package/dist/web/hooks/use-model-context.js

@@ -0,0 +1,63 @@
+import { ContentBlockSchema } from "@modelcontextprotocol/core";
+import { useCallback, useMemo } from "react";
+import * as z from "zod/v4";
+import { getAdaptor, useMcpAppContext } from "../bridges/index.js";
+import { useHost } from "./use-host.js";
+const ModelContextSchema = z
+    .object({
+    updateId: z.string().min(1),
+    content: z.array(ContentBlockSchema).optional(),
+    structuredContent: z.record(z.string(), z.unknown()).optional(),
+})
+    .nullable();
+/**
+ * Send content to the model through the MCP Apps `ui/update-model-context`
+ * request. Each `update` replaces what this hook sent before. Outside ChatGPT
+ * it is merged with the {@link useViewState} state, which wins on shared
+ * `structuredContent` keys.
+ *
+ * ChatGPT also reads the OpenAI presentation metadata, shows each block as a
+ * composer attachment and reports the attached context back:
+ * `_meta["openai/title"]`, `_meta["openai/thumbnail"]` on text blocks, and
+ * `annotations.audience: ["assistant"]` to hide a block from the user.
+ *
+ * - `supported`: whether the host advertises `updateModelContext` or
+ *   `openai/modelContext`.
+ * - `context`: ChatGPT only, the attached context; `null` once the user
+ *   removed it, `undefined` when the host never reported one.
+ * - `update`: replaces the context and resolves with ChatGPT's `updateId`,
+ *   to compare with `context.updateId`. Rejects with `NotSupportedError` on
+ *   hosts that don't advertise model context updates.
+ *
+ * @example
+ * ```tsx
+ * const { supported, update } = useModelContext();
+ * update({
+ *   content: [
+ *     {
+ *       type: "text",
+ *       text: "Selected: M6 hex bolt",
+ *       _meta: { "openai/title": "Hex bolt" },
+ *     },
+ *   ],
+ * });
+ * ```
+ *
+ * @see https://docs.skybridge.tech/api-reference/use-model-context
+ */
+export function useModelContext() {
+    const { capabilities, openaiCapabilities } = useHost();
+    const reported = useMcpAppContext("openai/modelContext");
+    const context = useMemo(() => {
+        const parsed = ModelContextSchema.safeParse(reported);
+        return parsed.success ? parsed.data : undefined;
+    }, [reported]);
+    const update = useCallback((params) => getAdaptor().updateModelContext(params), []);
+    return {
+        supported: Boolean(capabilities?.updateModelContext) ||
+            openaiCapabilities.modelContext,
+        context,
+        update,
+    };
+}
+//# sourceMappingURL=use-model-context.js.map

package/dist/web/hooks/use-model-context.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"use-model-context.js","sourceRoot":"","sources":["../../../src/web/hooks/use-model-context.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,kBAAkB,EAAE,MAAM,4BAA4B,CAAC;AAChE,OAAO,EAAE,WAAW,EAAE,OAAO,EAAE,MAAM,OAAO,CAAC;AAC7C,OAAO,KAAK,CAAC,MAAM,QAAQ,CAAC;AAC5B,OAAO,EAAE,UAAU,EAAE,gBAAgB,EAAE,MAAM,qBAAqB,CAAC;AAGnE,OAAO,EAAE,OAAO,EAAE,MAAM,eAAe,CAAC;AAExC,MAAM,kBAAkB,GAAG,CAAC;KACzB,MAAM,CAAC;IACN,QAAQ,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC;IAC3B,OAAO,EAAE,CAAC,CAAC,KAAK,CAAC,kBAAkB,CAAC,CAAC,QAAQ,EAAE;IAC/C,iBAAiB,EAAE,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC,OAAO,EAAE,CAAC,CAAC,QAAQ,EAAE;CAChE,CAAC;KACD,QAAQ,EAAE,CAAC;AAKd;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AACH,MAAM,UAAU,eAAe;IAK7B,MAAM,EAAE,YAAY,EAAE,kBAAkB,EAAE,GAAG,OAAO,EAAE,CAAC;IACvD,MAAM,QAAQ,GAAG,gBAAgB,CAAC,qBAAqB,CAAC,CAAC;IACzD,MAAM,OAAO,GAAG,OAAO,CAAC,GAAG,EAAE;QAC3B,MAAM,MAAM,GAAG,kBAAkB,CAAC,SAAS,CAAC,QAAQ,CAAC,CAAC;QACtD,OAAO,MAAM,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC,SAAS,CAAC;IAClD,CAAC,EAAE,CAAC,QAAQ,CAAC,CAAC,CAAC;IACf,MAAM,MAAM,GAAG,WAAW,CACxB,CAAC,MAA0B,EAAE,EAAE,CAAC,UAAU,EAAE,CAAC,kBAAkB,CAAC,MAAM,CAAC,EACvE,EAAE,CACH,CAAC;IAEF,OAAO;QACL,SAAS,EACP,OAAO,CAAC,YAAY,EAAE,kBAAkB,CAAC;YACzC,kBAAkB,CAAC,YAAY;QACjC,OAAO;QACP,MAAM;KACP,CAAC;AACJ,CAAC","sourcesContent":["import { ContentBlockSchema } from \"@modelcontextprotocol/core\";\nimport { useCallback, useMemo } from \"react\";\nimport * as z from \"zod/v4\";\nimport { getAdaptor, useMcpAppContext } from \"../bridges/index.js\";\nimport type { OpenAIHostContext } from \"../bridges/mcp-app/types.js\";\nimport type { ModelContextParams } from \"../bridges/types.js\";\nimport { useHost } from \"./use-host.js\";\n\nconst ModelContextSchema = z\n  .object({\n    updateId: z.string().min(1),\n    content: z.array(ContentBlockSchema).optional(),\n    structuredContent: z.record(z.string(), z.unknown()).optional(),\n  })\n  .nullable();\n\n/** Model context the view attached, as ChatGPT reports it back. */\nexport type ModelContextState = OpenAIHostContext[\"openai/modelContext\"];\n\n/**\n * Send content to the model through the MCP Apps `ui/update-model-context`\n * request. Each `update` replaces what this hook sent before. Outside ChatGPT\n * it is merged with the {@link useViewState} state, which wins on shared\n * `structuredContent` keys.\n *\n * ChatGPT also reads the OpenAI presentation metadata, shows each block as a\n * composer attachment and reports the attached context back:\n * `_meta[\"openai/title\"]`, `_meta[\"openai/thumbnail\"]` on text blocks, and\n * `annotations.audience: [\"assistant\"]` to hide a block from the user.\n *\n * - `supported`: whether the host advertises `updateModelContext` or\n *   `openai/modelContext`.\n * - `context`: ChatGPT only, the attached context; `null` once the user\n *   removed it, `undefined` when the host never reported one.\n * - `update`: replaces the context and resolves with ChatGPT's `updateId`,\n *   to compare with `context.updateId`. Rejects with `NotSupportedError` on\n *   hosts that don't advertise model context updates.\n *\n * @example\n * ```tsx\n * const { supported, update } = useModelContext();\n * update({\n *   content: [\n *     {\n *       type: \"text\",\n *       text: \"Selected: M6 hex bolt\",\n *       _meta: { \"openai/title\": \"Hex bolt\" },\n *     },\n *   ],\n * });\n * ```\n *\n * @see https://docs.skybridge.tech/api-reference/use-model-context\n */\nexport function useModelContext(): {\n  supported: boolean;\n  context: ModelContextState;\n  update: (params: ModelContextParams) => Promise<string | undefined>;\n} {\n  const { capabilities, openaiCapabilities } = useHost();\n  const reported = useMcpAppContext(\"openai/modelContext\");\n  const context = useMemo(() => {\n    const parsed = ModelContextSchema.safeParse(reported);\n    return parsed.success ? parsed.data : undefined;\n  }, [reported]);\n  const update = useCallback(\n    (params: ModelContextParams) => getAdaptor().updateModelContext(params),\n    [],\n  );\n\n  return {\n    supported:\n      Boolean(capabilities?.updateModelContext) ||\n      openaiCapabilities.modelContext,\n    context,\n    update,\n  };\n}\n"]}

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

@@ -1 +1,20 @@
-export declare function useOpenExternal(): (href: string) => void;
+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,8 +1,24 @@
 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) => adaptor.openExternal(href), [adaptor]);
+    const openExternal = useCallback((href, options) => adaptor.openExternal(href, options), [adaptor]);
     return openExternal;
 }
 //# sourceMappingURL=use-open-external.js.map

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;AAEjD,MAAM,UAAU,eAAe;IAC7B,MAAM,OAAO,GAAG,UAAU,EAAE,CAAC;IAC7B,MAAM,YAAY,GAAG,WAAW,CAC9B,CAAC,IAAY,EAAE,EAAE,CAAC,OAAO,CAAC,YAAY,CAAC,IAAI,CAAC,EAC5C,CAAC,OAAO,CAAC,CACV,CAAC;IAEF,OAAO,YAAY,CAAC;AACtB,CAAC"}
+{"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,49 +1,74 @@
-import { renderHook } from "@testing-library/react";
+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("skybridge", {});
+            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 call window.openai.openExternal when redirectUrl is false", () => {
+            const { result } = renderHook(() => useOpenExternal());
+            const href = "https://example.com";
+            result.current(href, { redirectUrl: false });
+            expect(openExternalMock).toHaveBeenCalledTimes(1);
+            expect(openExternalMock).toHaveBeenCalledWith({
+                href,
+                redirectUrl: false,
+            });
         });
     });
     describe("mcp-app host", () => {
-        const mockPostMessage = vi.fn();
+        let postMessageMock;
         beforeEach(() => {
-            vi.stubGlobal("parent", { postMessage: mockPostMessage });
-            vi.stubGlobal("skybridge", { hostType: "mcp-app" });
+            vi.stubGlobal("openai", undefined);
+            vi.stubGlobal("skybridge", {});
+            vi.stubGlobal("ResizeObserver", MockResizeObserver);
+            postMessageMock = getMcpAppHostPostMessageMock();
+            vi.stubGlobal("parent", { postMessage: postMessageMock });
         });
-        afterEach(() => {
+        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", () => {
+        it("should return a function that sends ui/open-link request to the MCP host", async () => {
             const { result } = renderHook(() => useOpenExternal());
             const href = "https://example.com";
-            result.current(href);
-            expect(mockPostMessage).toHaveBeenCalledWith(expect.objectContaining({
-                jsonrpc: "2.0",
-                method: "ui/open-link",
-                params: { url: href },
-            }), "*");
+            result.current(href, { redirectUrl: false });
+            await waitFor(() => {
+                expect(postMessageMock).toHaveBeenCalledWith(expect.objectContaining({
+                    jsonrpc: "2.0",
+                    method: "ui/open-link",
+                    params: { url: href },
+                }), "*");
+            });
         });
     });
 });