skybridge 0.0.0-dev.e1b8fe1 → 0.0.0-dev.e1ca873

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, openai } = useHost();
+ * if (name === "claude") return <ClaudeLayout />;
+ * if (openai.files) return <OpenFileButton />;
+ * ```
+ */
+export function useHost() {
+    const hostInfo = useMcpAppContext("hostInfo");
+    const capabilities = useMcpAppContext("hostCapabilities") ?? undefined;
+    const name = hostInfo?.name;
+    const openai = 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,
+        openai,
+    };
+}
+//# 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,MAAM,GAAG,OAAO,CAAC,GAAG,EAAE;QAC1B,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,MAAM;KACP,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  openai: 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, openai } = useHost();\n * if (name === \"claude\") return <ClaudeLayout />;\n * if (openai.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 openai = 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    openai,\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,42 @@
+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, and is merged
+ * with the {@link useViewState} state, which the view state 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`.
+ * - `context`: ChatGPT only, the attached context; `null` once the user
+ *   removed it, `undefined` when the host never reported one.
+ * - `update`: replaces the context. 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<void>;
+};

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, and is merged
+ * with the {@link useViewState} state, which the view state 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`.
+ * - `context`: ChatGPT only, the attached context; `null` once the user
+ *   removed it, `undefined` when the host never reported one.
+ * - `update`: replaces the context. 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, openai } = useHost();
+    const reported = useMcpAppContext("openai/modelContext");
+    const context = useMemo(() => {
+        if (reported === undefined) {
+            return undefined;
+        }
+        const parsed = ModelContextSchema.safeParse(reported);
+        return parsed.success ? parsed.data : undefined;
+    }, [reported]);
+    const update = useCallback((params) => getAdaptor().updateModelContext(params), []);
+    return {
+        supported: Boolean(capabilities?.updateModelContext) || openai.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;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AACH,MAAM,UAAU,eAAe;IAK7B,MAAM,EAAE,YAAY,EAAE,MAAM,EAAE,GAAG,OAAO,EAAE,CAAC;IAC3C,MAAM,QAAQ,GAAG,gBAAgB,CAAC,qBAAqB,CAAC,CAAC;IACzD,MAAM,OAAO,GAAG,OAAO,CAAC,GAAG,EAAE;QAC3B,IAAI,QAAQ,KAAK,SAAS,EAAE,CAAC;YAC3B,OAAO,SAAS,CAAC;QACnB,CAAC;QACD,MAAM,MAAM,GAAG,kBAAkB,CAAC,SAAS,CAAC,QAAQ,CAAC,CAAC;QACtD,OAAO,MAAM,CAAC,OAAO,CAAC,CAAC,CAAE,MAAM,CAAC,IAA0B,CAAC,CAAC,CAAC,SAAS,CAAC;IACzE,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,EAAE,OAAO,CAAC,YAAY,EAAE,kBAAkB,CAAC,IAAI,MAAM,CAAC,YAAY;QAC3E,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, and is merged\n * with the {@link useViewState} state, which the view state 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`.\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. Rejects with `NotSupportedError` on hosts\n *   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<void>;\n} {\n  const { capabilities, openai } = useHost();\n  const reported = useMcpAppContext(\"openai/modelContext\");\n  const context = useMemo(() => {\n    if (reported === undefined) {\n      return undefined;\n    }\n    const parsed = ModelContextSchema.safeParse(reported);\n    return parsed.success ? (parsed.data as ModelContextState) : undefined;\n  }, [reported]);\n  const update = useCallback(\n    (params: ModelContextParams) => getAdaptor().updateModelContext(params),\n    [],\n  );\n\n  return {\n    supported: Boolean(capabilities?.updateModelContext) || openai.modelContext,\n    context,\n    update,\n  };\n}\n"]}

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

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

@@ -0,0 +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, options) => adaptor.openExternal(href, options), [adaptor]);
+    return openExternal;
+}
+//# sourceMappingURL=use-open-external.js.map

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

@@ -0,0 +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;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.d.ts

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

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

@@ -0,0 +1,75 @@
+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", {});
+            vi.stubGlobal("ResizeObserver", MockResizeObserver);
+            postMessageMock = getMcpAppHostPostMessageMock();
+            vi.stubGlobal("parent", { postMessage: postMessageMock });
+        });
+        afterEach(() => {
+            HostAdaptor.resetInstance();
+            McpAppBridge.resetInstance();
+            vi.unstubAllGlobals();
+            vi.resetAllMocks();
+        });
+        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", () => {
+        let postMessageMock;
+        beforeEach(() => {
+            vi.stubGlobal("openai", undefined);
+            vi.stubGlobal("skybridge", {});
+            vi.stubGlobal("ResizeObserver", MockResizeObserver);
+            postMessageMock = getMcpAppHostPostMessageMock();
+            vi.stubGlobal("parent", { postMessage: postMessageMock });
+        });
+        afterEach(async () => {
+            HostAdaptor.resetInstance();
+            McpAppBridge.resetInstance();
+            vi.unstubAllGlobals();
+            vi.resetAllMocks();
+        });
+        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, { redirectUrl: false });
+            await waitFor(() => {
+                expect(postMessageMock).toHaveBeenCalledWith(expect.objectContaining({
+                    jsonrpc: "2.0",
+                    method: "ui/open-link",
+                    params: { url: href },
+                }), "*");
+            });
+        });
+    });
+});
+//# sourceMappingURL=use-open-external.test.js.map

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

@@ -0,0 +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 { 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\", {});\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\", {});\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,37 @@
+import type { ViewToolConfig, ViewToolHandler, ViewToolInputShape } 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 ViewToolInputShape = ViewToolInputShape>(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":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,EAAE,MAAM,OAAO,CAAC;AAC1C,OAAO,EAAE,UAAU,EAAE,MAAM,qBAAqB,CAAC;AAQjD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;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 { useEffect, useRef } from \"react\";\nimport { getAdaptor } from \"../bridges/index.js\";\nimport type {\n  AnyViewToolHandler,\n  ViewToolConfig,\n  ViewToolHandler,\n  ViewToolInputShape,\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 ViewToolInputShape = ViewToolInputShape,\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", {});
+        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":"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","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\", {});\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

@@ -0,0 +1,24 @@
+import { type RequestModalOptions } from "../bridges/index.js";
+/**
+ * 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;
+    params: Record<string, unknown> | undefined;
+    open: (opts: RequestModalOptions) => void;
+};