skybridge 1.0.2 → 1.0.3

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

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

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

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

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

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

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

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

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

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

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

@@ -1,3 +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

@@ -1,5 +1,21 @@
 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]);

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

@@ -1 +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;AAKjD,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\nexport type RequestSizeFn = (size: RequestSizeOptions) => Promise<void>;\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"]}
+{"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-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>;

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

@@ -1,5 +1,22 @@
 import { useCallback } from "react";
 import { getAdaptor, } 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 function useSendFollowUpMessage() {
     const adaptor = getAdaptor();
     const sendFollowUpMessage = useCallback((prompt, options) => adaptor.sendFollowUpMessage(prompt, options), [adaptor]);

package/dist/web/hooks/use-send-follow-up-message.js.map

@@ -1 +1 @@
-{"version":3,"file":"use-send-follow-up-message.js","sourceRoot":"","sources":["../../../src/web/hooks/use-send-follow-up-message.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,MAAM,OAAO,CAAC;AACpC,OAAO,EACL,UAAU,GAEX,MAAM,qBAAqB,CAAC;AAE7B,MAAM,UAAU,sBAAsB;IACpC,MAAM,OAAO,GAAG,UAAU,EAAE,CAAC;IAC7B,MAAM,mBAAmB,GAAG,WAAW,CACrC,CAAC,MAAc,EAAE,OAAoC,EAAE,EAAE,CACvD,OAAO,CAAC,mBAAmB,CAAC,MAAM,EAAE,OAAO,CAAC,EAC9C,CAAC,OAAO,CAAC,CACV,CAAC;IAEF,OAAO,mBAAmB,CAAC;AAC7B,CAAC","sourcesContent":["import { useCallback } from \"react\";\nimport {\n  getAdaptor,\n  type SendFollowUpMessageOptions,\n} from \"../bridges/index.js\";\n\nexport function useSendFollowUpMessage() {\n  const adaptor = getAdaptor();\n  const sendFollowUpMessage = useCallback(\n    (prompt: string, options?: SendFollowUpMessageOptions) =>\n      adaptor.sendFollowUpMessage(prompt, options),\n    [adaptor],\n  );\n\n  return sendFollowUpMessage;\n}\n"]}
+{"version":3,"file":"use-send-follow-up-message.js","sourceRoot":"","sources":["../../../src/web/hooks/use-send-follow-up-message.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,MAAM,OAAO,CAAC;AACpC,OAAO,EACL,UAAU,GAEX,MAAM,qBAAqB,CAAC;AAE7B;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,UAAU,sBAAsB;IACpC,MAAM,OAAO,GAAG,UAAU,EAAE,CAAC;IAC7B,MAAM,mBAAmB,GAAG,WAAW,CACrC,CAAC,MAAc,EAAE,OAAoC,EAAE,EAAE,CACvD,OAAO,CAAC,mBAAmB,CAAC,MAAM,EAAE,OAAO,CAAC,EAC9C,CAAC,OAAO,CAAC,CACV,CAAC;IAEF,OAAO,mBAAmB,CAAC;AAC7B,CAAC","sourcesContent":["import { useCallback } from \"react\";\nimport {\n  getAdaptor,\n  type SendFollowUpMessageOptions,\n} from \"../bridges/index.js\";\n\n/**\n * Send a follow-up message to the LLM on behalf of the view, as if the user\n * had sent it. Use to chain interactions from view UI (e.g. a button that\n * triggers the next assistant turn).\n *\n * Pass `scrollToBottom: false` to keep the chat scroll position when the host\n * posts the message. This option is Apps-SDK-only; it is silently ignored in\n * the MCP Apps runtime.\n *\n * @example\n * ```tsx\n * const send = useSendFollowUpMessage();\n * <button onClick={() => send(\"Summarize the last 5 results\")}>Summarize</button>\n * ```\n *\n * @see https://docs.skybridge.tech/api-reference/use-send-follow-up-message\n */\nexport function useSendFollowUpMessage() {\n  const adaptor = getAdaptor();\n  const sendFollowUpMessage = useCallback(\n    (prompt: string, options?: SendFollowUpMessageOptions) =>\n      adaptor.sendFollowUpMessage(prompt, options),\n    [adaptor],\n  );\n\n  return sendFollowUpMessage;\n}\n"]}

package/dist/web/hooks/use-set-open-in-app-url.d.ts

@@ -1 +1,18 @@
+/**
+ * Override the target URL the host opens from its fullscreen "Open in <App>"
+ * affordance. If unset, the host opens the view's current iframe path.
+ *
+ * Currently Apps-SDK-only — calling this from MCP Apps throws.
+ *
+ * Call this once your view has enough context to construct the canonical URL
+ * (e.g. a permalink to the entity the user is currently viewing).
+ *
+ * @example
+ * ```tsx
+ * const setOpenInAppUrl = useSetOpenInAppUrl();
+ * useEffect(() => { setOpenInAppUrl(`https://example.com/orders/${orderId}`); }, [orderId]);
+ * ```
+ *
+ * @see https://docs.skybridge.tech/api-reference/use-set-open-in-app-url
+ */
 export declare function useSetOpenInAppUrl(): (href: string) => Promise<void>;

package/dist/web/hooks/use-set-open-in-app-url.js

@@ -1,5 +1,22 @@
 import { useCallback } from "react";
 import { getAdaptor } from "../bridges/index.js";
+/**
+ * Override the target URL the host opens from its fullscreen "Open in <App>"
+ * affordance. If unset, the host opens the view's current iframe path.
+ *
+ * Currently Apps-SDK-only — calling this from MCP Apps throws.
+ *
+ * Call this once your view has enough context to construct the canonical URL
+ * (e.g. a permalink to the entity the user is currently viewing).
+ *
+ * @example
+ * ```tsx
+ * const setOpenInAppUrl = useSetOpenInAppUrl();
+ * useEffect(() => { setOpenInAppUrl(`https://example.com/orders/${orderId}`); }, [orderId]);
+ * ```
+ *
+ * @see https://docs.skybridge.tech/api-reference/use-set-open-in-app-url
+ */
 export function useSetOpenInAppUrl() {
     const adaptor = getAdaptor();
     const setOpenInAppUrl = useCallback((href) => adaptor.setOpenInAppUrl(href), [adaptor]);

package/dist/web/hooks/use-set-open-in-app-url.js.map

@@ -1 +1 @@
-{"version":3,"file":"use-set-open-in-app-url.js","sourceRoot":"","sources":["../../../src/web/hooks/use-set-open-in-app-url.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,MAAM,OAAO,CAAC;AACpC,OAAO,EAAE,UAAU,EAAE,MAAM,qBAAqB,CAAC;AAEjD,MAAM,UAAU,kBAAkB;IAChC,MAAM,OAAO,GAAG,UAAU,EAAE,CAAC;IAC7B,MAAM,eAAe,GAAG,WAAW,CACjC,CAAC,IAAY,EAAE,EAAE,CAAC,OAAO,CAAC,eAAe,CAAC,IAAI,CAAC,EAC/C,CAAC,OAAO,CAAC,CACV,CAAC;IAEF,OAAO,eAAe,CAAC;AACzB,CAAC","sourcesContent":["import { useCallback } from \"react\";\nimport { getAdaptor } from \"../bridges/index.js\";\n\nexport function useSetOpenInAppUrl() {\n  const adaptor = getAdaptor();\n  const setOpenInAppUrl = useCallback(\n    (href: string) => adaptor.setOpenInAppUrl(href),\n    [adaptor],\n  );\n\n  return setOpenInAppUrl;\n}\n"]}
+{"version":3,"file":"use-set-open-in-app-url.js","sourceRoot":"","sources":["../../../src/web/hooks/use-set-open-in-app-url.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,MAAM,OAAO,CAAC;AACpC,OAAO,EAAE,UAAU,EAAE,MAAM,qBAAqB,CAAC;AAEjD;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,UAAU,kBAAkB;IAChC,MAAM,OAAO,GAAG,UAAU,EAAE,CAAC;IAC7B,MAAM,eAAe,GAAG,WAAW,CACjC,CAAC,IAAY,EAAE,EAAE,CAAC,OAAO,CAAC,eAAe,CAAC,IAAI,CAAC,EAC/C,CAAC,OAAO,CAAC,CACV,CAAC;IAEF,OAAO,eAAe,CAAC;AACzB,CAAC","sourcesContent":["import { useCallback } from \"react\";\nimport { getAdaptor } from \"../bridges/index.js\";\n\n/**\n * Override the target URL the host opens from its fullscreen \"Open in <App>\"\n * affordance. If unset, the host opens the view's current iframe path.\n *\n * Currently Apps-SDK-only — calling this from MCP Apps throws.\n *\n * Call this once your view has enough context to construct the canonical URL\n * (e.g. a permalink to the entity the user is currently viewing).\n *\n * @example\n * ```tsx\n * const setOpenInAppUrl = useSetOpenInAppUrl();\n * useEffect(() => { setOpenInAppUrl(`https://example.com/orders/${orderId}`); }, [orderId]);\n * ```\n *\n * @see https://docs.skybridge.tech/api-reference/use-set-open-in-app-url\n */\nexport function useSetOpenInAppUrl() {\n  const adaptor = getAdaptor();\n  const setOpenInAppUrl = useCallback(\n    (href: string) => adaptor.setOpenInAppUrl(href),\n    [adaptor],\n  );\n\n  return setOpenInAppUrl;\n}\n"]}

package/dist/web/hooks/use-tool-info.d.ts

@@ -1,4 +1,5 @@
 import type { UnknownObject } from "../types.js";
+/** {@link useToolInfo} state before the tool has been invoked. */
 export type ToolIdleState = {
     status: "idle";
     isIdle: true;
@@ -8,6 +9,7 @@ export type ToolIdleState = {
     output: undefined;
     responseMetadata: undefined;
 };
+/** {@link useToolInfo} state while the tool is executing — `input` is available, output is not yet. */
 export type ToolPendingState<ToolInput extends UnknownObject> = {
     status: "pending";
     isIdle: false;
@@ -17,6 +19,7 @@ export type ToolPendingState<ToolInput extends UnknownObject> = {
     output: undefined;
     responseMetadata: undefined;
 };
+/** {@link useToolInfo} state once the tool returned — `input`, `output`, and `responseMetadata` are all available. */
 export type ToolSuccessState<ToolInput extends UnknownObject, ToolOutput extends UnknownObject, ToolResponseMetadata extends UnknownObject> = {
     status: "success";
     isIdle: false;
@@ -26,11 +29,41 @@ export type ToolSuccessState<ToolInput extends UnknownObject, ToolOutput extends
     output: ToolOutput;
     responseMetadata: ToolResponseMetadata;
 };
+/**
+ * Discriminated union describing the tool invocation that triggered the
+ * current view render. Use `isIdle` / `isPending` / `isSuccess` to narrow.
+ */
 export type ToolState<ToolInput extends UnknownObject, ToolOutput extends UnknownObject, ToolResponseMetadata extends UnknownObject> = ToolIdleState | ToolPendingState<ToolInput> | ToolSuccessState<ToolInput, ToolOutput, ToolResponseMetadata>;
 type ToolSignature = {
     input: UnknownObject;
     output: UnknownObject;
     responseMetadata: UnknownObject;
 };
+/**
+ * Access the tool invocation that produced the current view: its `input`,
+ * resulting `output`, and `responseMetadata`. The shape evolves as the tool
+ * runs (idle → pending → success), exposed through {@link ToolState}.
+ *
+ * For full input/output typing per tool name, prefer the typed `useToolInfo`
+ * returned by {@link generateHelpers} over the generic form.
+ *
+ * @typeParam TS - Optional partial shape `{ input, output, responseMetadata }`
+ * to refine each field's type. When omitted, each typed field resolves to
+ * `never` — pass an explicit shape or use the typed helper from
+ * {@link generateHelpers} to get usable types.
+ *
+ * @example
+ * ```tsx
+ * const { isSuccess, input, output } = useToolInfo<{
+ *   input: { query: string };
+ *   output: { results: Result[] };
+ * }>();
+ *
+ * if (!isSuccess || !output) return <Skeleton />;
+ * return <Results items={output.results} />;
+ * ```
+ *
+ * @see https://docs.skybridge.tech/api-reference/use-tool-info
+ */
 export declare function useToolInfo<TS extends Partial<ToolSignature> = Record<string, never>>(): ToolState<UnknownObject & TS["input"], UnknownObject & TS["output"], UnknownObject & TS["responseMetadata"]>;
 export {};

package/dist/web/hooks/use-tool-info.js

@@ -8,6 +8,32 @@ function deriveStatus(input, output, responseMetadata) {
     }
     return "success";
 }
+/**
+ * Access the tool invocation that produced the current view: its `input`,
+ * resulting `output`, and `responseMetadata`. The shape evolves as the tool
+ * runs (idle → pending → success), exposed through {@link ToolState}.
+ *
+ * For full input/output typing per tool name, prefer the typed `useToolInfo`
+ * returned by {@link generateHelpers} over the generic form.
+ *
+ * @typeParam TS - Optional partial shape `{ input, output, responseMetadata }`
+ * to refine each field's type. When omitted, each typed field resolves to
+ * `never` — pass an explicit shape or use the typed helper from
+ * {@link generateHelpers} to get usable types.
+ *
+ * @example
+ * ```tsx
+ * const { isSuccess, input, output } = useToolInfo<{
+ *   input: { query: string };
+ *   output: { results: Result[] };
+ * }>();
+ *
+ * if (!isSuccess || !output) return <Skeleton />;
+ * return <Results items={output.results} />;
+ * ```
+ *
+ * @see https://docs.skybridge.tech/api-reference/use-tool-info
+ */
 export function useToolInfo() {
     const input = useHostContext("toolInput");
     const output = useHostContext("toolOutput");

package/dist/web/hooks/use-tool-info.js.map

@@ -1 +1 @@
-{"version":3,"file":"use-tool-info.js","sourceRoot":"","sources":["../../../src/web/hooks/use-tool-info.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAC;AAoDrD,SAAS,YAAY,CACnB,KAAqC,EACrC,MAAsC,EACtC,gBAAgD;IAEhD,IAAI,KAAK,KAAK,IAAI,EAAE,CAAC;QACnB,OAAO,MAAM,CAAC;IAChB,CAAC;IACD,IAAI,MAAM,KAAK,IAAI,IAAI,gBAAgB,KAAK,IAAI,EAAE,CAAC;QACjD,OAAO,SAAS,CAAC;IACnB,CAAC;IACD,OAAO,SAAS,CAAC;AACnB,CAAC;AAED,MAAM,UAAU,WAAW;IAGzB,MAAM,KAAK,GAAG,cAAc,CAAC,WAAW,CAAC,CAAC;IAC1C,MAAM,MAAM,GAAG,cAAc,CAAC,YAAY,CAAC,CAAC;IAC5C,MAAM,gBAAgB,GAAG,cAAc,CAAC,sBAAsB,CAAC,CAAC;IAEhE,MAAM,MAAM,GAAG,YAAY,CAAC,KAAK,EAAE,MAAM,EAAE,gBAAgB,CAAC,CAAC;IAM7D,OAAO;QACL,KAAK;QACL,MAAM;QACN,MAAM,EAAE,MAAM,KAAK,MAAM;QACzB,SAAS,EAAE,MAAM,KAAK,SAAS;QAC/B,SAAS,EAAE,MAAM,KAAK,SAAS;QAC/B,MAAM;QACN,gBAAgB;KACqB,CAAC;AAC1C,CAAC","sourcesContent":["import { useHostContext } from \"../bridges/index.js\";\nimport type { UnknownObject } from \"../types.js\";\n\nexport type ToolIdleState = {\n  status: \"idle\";\n  isIdle: true;\n  isPending: false;\n  isSuccess: false;\n  input: undefined;\n  output: undefined;\n  responseMetadata: undefined;\n};\n\nexport type ToolPendingState<ToolInput extends UnknownObject> = {\n  status: \"pending\";\n  isIdle: false;\n  isPending: true;\n  isSuccess: false;\n  input: ToolInput;\n  output: undefined;\n  responseMetadata: undefined;\n};\n\nexport type ToolSuccessState<\n  ToolInput extends UnknownObject,\n  ToolOutput extends UnknownObject,\n  ToolResponseMetadata extends UnknownObject,\n> = {\n  status: \"success\";\n  isIdle: false;\n  isPending: false;\n  isSuccess: true;\n  input: ToolInput;\n  output: ToolOutput;\n  responseMetadata: ToolResponseMetadata;\n};\n\nexport type ToolState<\n  ToolInput extends UnknownObject,\n  ToolOutput extends UnknownObject,\n  ToolResponseMetadata extends UnknownObject,\n> =\n  | ToolIdleState\n  | ToolPendingState<ToolInput>\n  | ToolSuccessState<ToolInput, ToolOutput, ToolResponseMetadata>;\n\ntype ToolSignature = {\n  input: UnknownObject;\n  output: UnknownObject;\n  responseMetadata: UnknownObject;\n};\n\nfunction deriveStatus(\n  input: Record<string, unknown> | null,\n  output: Record<string, unknown> | null,\n  responseMetadata: Record<string, unknown> | null,\n): \"idle\" | \"pending\" | \"success\" {\n  if (input === null) {\n    return \"idle\";\n  }\n  if (output === null && responseMetadata === null) {\n    return \"pending\";\n  }\n  return \"success\";\n}\n\nexport function useToolInfo<\n  TS extends Partial<ToolSignature> = Record<string, never>,\n>() {\n  const input = useHostContext(\"toolInput\");\n  const output = useHostContext(\"toolOutput\");\n  const responseMetadata = useHostContext(\"toolResponseMetadata\");\n\n  const status = deriveStatus(input, output, responseMetadata);\n\n  type Input = UnknownObject & TS[\"input\"];\n  type Output = UnknownObject & TS[\"output\"];\n  type Metadata = UnknownObject & TS[\"responseMetadata\"];\n\n  return {\n    input,\n    status,\n    isIdle: status === \"idle\",\n    isPending: status === \"pending\",\n    isSuccess: status === \"success\",\n    output,\n    responseMetadata,\n  } as ToolState<Input, Output, Metadata>;\n}\n"]}
+{"version":3,"file":"use-tool-info.js","sourceRoot":"","sources":["../../../src/web/hooks/use-tool-info.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAC;AA2DrD,SAAS,YAAY,CACnB,KAAqC,EACrC,MAAsC,EACtC,gBAAgD;IAEhD,IAAI,KAAK,KAAK,IAAI,EAAE,CAAC;QACnB,OAAO,MAAM,CAAC;IAChB,CAAC;IACD,IAAI,MAAM,KAAK,IAAI,IAAI,gBAAgB,KAAK,IAAI,EAAE,CAAC;QACjD,OAAO,SAAS,CAAC;IACnB,CAAC;IACD,OAAO,SAAS,CAAC;AACnB,CAAC;AAED;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,MAAM,UAAU,WAAW;IAGzB,MAAM,KAAK,GAAG,cAAc,CAAC,WAAW,CAAC,CAAC;IAC1C,MAAM,MAAM,GAAG,cAAc,CAAC,YAAY,CAAC,CAAC;IAC5C,MAAM,gBAAgB,GAAG,cAAc,CAAC,sBAAsB,CAAC,CAAC;IAEhE,MAAM,MAAM,GAAG,YAAY,CAAC,KAAK,EAAE,MAAM,EAAE,gBAAgB,CAAC,CAAC;IAM7D,OAAO;QACL,KAAK;QACL,MAAM;QACN,MAAM,EAAE,MAAM,KAAK,MAAM;QACzB,SAAS,EAAE,MAAM,KAAK,SAAS;QAC/B,SAAS,EAAE,MAAM,KAAK,SAAS;QAC/B,MAAM;QACN,gBAAgB;KACqB,CAAC;AAC1C,CAAC","sourcesContent":["import { useHostContext } from \"../bridges/index.js\";\nimport type { UnknownObject } from \"../types.js\";\n\n/** {@link useToolInfo} state before the tool has been invoked. */\nexport type ToolIdleState = {\n  status: \"idle\";\n  isIdle: true;\n  isPending: false;\n  isSuccess: false;\n  input: undefined;\n  output: undefined;\n  responseMetadata: undefined;\n};\n\n/** {@link useToolInfo} state while the tool is executing — `input` is available, output is not yet. */\nexport type ToolPendingState<ToolInput extends UnknownObject> = {\n  status: \"pending\";\n  isIdle: false;\n  isPending: true;\n  isSuccess: false;\n  input: ToolInput;\n  output: undefined;\n  responseMetadata: undefined;\n};\n\n/** {@link useToolInfo} state once the tool returned — `input`, `output`, and `responseMetadata` are all available. */\nexport type ToolSuccessState<\n  ToolInput extends UnknownObject,\n  ToolOutput extends UnknownObject,\n  ToolResponseMetadata extends UnknownObject,\n> = {\n  status: \"success\";\n  isIdle: false;\n  isPending: false;\n  isSuccess: true;\n  input: ToolInput;\n  output: ToolOutput;\n  responseMetadata: ToolResponseMetadata;\n};\n\n/**\n * Discriminated union describing the tool invocation that triggered the\n * current view render. Use `isIdle` / `isPending` / `isSuccess` to narrow.\n */\nexport type ToolState<\n  ToolInput extends UnknownObject,\n  ToolOutput extends UnknownObject,\n  ToolResponseMetadata extends UnknownObject,\n> =\n  | ToolIdleState\n  | ToolPendingState<ToolInput>\n  | ToolSuccessState<ToolInput, ToolOutput, ToolResponseMetadata>;\n\ntype ToolSignature = {\n  input: UnknownObject;\n  output: UnknownObject;\n  responseMetadata: UnknownObject;\n};\n\nfunction deriveStatus(\n  input: Record<string, unknown> | null,\n  output: Record<string, unknown> | null,\n  responseMetadata: Record<string, unknown> | null,\n): \"idle\" | \"pending\" | \"success\" {\n  if (input === null) {\n    return \"idle\";\n  }\n  if (output === null && responseMetadata === null) {\n    return \"pending\";\n  }\n  return \"success\";\n}\n\n/**\n * Access the tool invocation that produced the current view: its `input`,\n * resulting `output`, and `responseMetadata`. The shape evolves as the tool\n * runs (idle → pending → success), exposed through {@link ToolState}.\n *\n * For full input/output typing per tool name, prefer the typed `useToolInfo`\n * returned by {@link generateHelpers} over the generic form.\n *\n * @typeParam TS - Optional partial shape `{ input, output, responseMetadata }`\n * to refine each field's type. When omitted, each typed field resolves to\n * `never` — pass an explicit shape or use the typed helper from\n * {@link generateHelpers} to get usable types.\n *\n * @example\n * ```tsx\n * const { isSuccess, input, output } = useToolInfo<{\n *   input: { query: string };\n *   output: { results: Result[] };\n * }>();\n *\n * if (!isSuccess || !output) return <Skeleton />;\n * return <Results items={output.results} />;\n * ```\n *\n * @see https://docs.skybridge.tech/api-reference/use-tool-info\n */\nexport function useToolInfo<\n  TS extends Partial<ToolSignature> = Record<string, never>,\n>() {\n  const input = useHostContext(\"toolInput\");\n  const output = useHostContext(\"toolOutput\");\n  const responseMetadata = useHostContext(\"toolResponseMetadata\");\n\n  const status = deriveStatus(input, output, responseMetadata);\n\n  type Input = UnknownObject & TS[\"input\"];\n  type Output = UnknownObject & TS[\"output\"];\n  type Metadata = UnknownObject & TS[\"responseMetadata\"];\n\n  return {\n    input,\n    status,\n    isIdle: status === \"idle\",\n    isPending: status === \"pending\",\n    isSuccess: status === \"success\",\n    output,\n    responseMetadata,\n  } as ToolState<Input, Output, Metadata>;\n}\n"]}

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

@@ -14,5 +14,7 @@ export type UserState = {
  * // Access device type
  * const isMobile = userAgent.device.type === "mobile";
  * ```
+ *
+ * @see https://docs.skybridge.tech/api-reference/use-user
  */
 export declare function useUser(): UserState;

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

@@ -26,6 +26,8 @@ function normalizeLocale(locale) {
  * // Access device type
  * const isMobile = userAgent.device.type === "mobile";
  * ```
+ *
+ * @see https://docs.skybridge.tech/api-reference/use-user
  */
 export function useUser() {
     const rawLocale = useHostContext("locale");

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

@@ -1 +1 @@
-{"version":3,"file":"use-user.js","sourceRoot":"","sources":["../../../src/web/hooks/use-user.ts"],"names":[],"mappings":"AAAA,OAAO,EAAkB,cAAc,EAAE,MAAM,qBAAqB,CAAC;AAOrE,MAAM,cAAc,GAAG,OAAO,CAAC;AAE/B;;;;;;GAMG;AACH,SAAS,eAAe,CAAC,MAAc;IACrC,IAAI,CAAC;QACH,OAAO,IAAI,IAAI,CAAC,MAAM,CAAC,MAAM,CAAC,OAAO,CAAC,IAAI,EAAE,GAAG,CAAC,CAAC,CAAC,QAAQ,EAAE,CAAC;IAC/D,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,cAAc,CAAC;IACxB,CAAC;AACH,CAAC;AAED;;;;;;;;;;;GAWG;AACH,MAAM,UAAU,OAAO;IACrB,MAAM,SAAS,GAAG,cAAc,CAAC,QAAQ,CAAC,CAAC;IAC3C,MAAM,SAAS,GAAG,cAAc,CAAC,WAAW,CAAC,CAAC;IAE9C,OAAO,EAAE,MAAM,EAAE,eAAe,CAAC,SAAS,CAAC,EAAE,SAAS,EAAE,CAAC;AAC3D,CAAC","sourcesContent":["import { type UserAgent, useHostContext } from \"../bridges/index.js\";\n\nexport type UserState = {\n  locale: string;\n  userAgent: UserAgent;\n};\n\nconst DEFAULT_LOCALE = \"en-US\";\n\n/**\n * Normalizes a locale string to canonical BCP 47 format using {@link Intl.Locale}.\n *\n * Handles underscored identifiers returned by the ChatGPT mobile app (e.g. \"fr_FR\" → \"fr-FR\"),\n * incorrect casing (e.g. \"en-us\" → \"en-US\"), and complex subtags (e.g. \"zh_Hans_CN\" → \"zh-Hans-CN\").\n * Falls back to \"en-US\" if the locale is invalid.\n */\nfunction normalizeLocale(locale: string): string {\n  try {\n    return new Intl.Locale(locale.replace(/_/g, \"-\")).toString();\n  } catch {\n    return DEFAULT_LOCALE;\n  }\n}\n\n/**\n * Hook for accessing session-stable user information.\n * These values are set once at initialization and do not change during the session.\n *\n * @example\n * ```tsx\n * const { locale, userAgent } = useUser();\n *\n * // Access device type\n * const isMobile = userAgent.device.type === \"mobile\";\n * ```\n */\nexport function useUser(): UserState {\n  const rawLocale = useHostContext(\"locale\");\n  const userAgent = useHostContext(\"userAgent\");\n\n  return { locale: normalizeLocale(rawLocale), userAgent };\n}\n"]}
+{"version":3,"file":"use-user.js","sourceRoot":"","sources":["../../../src/web/hooks/use-user.ts"],"names":[],"mappings":"AAAA,OAAO,EAAkB,cAAc,EAAE,MAAM,qBAAqB,CAAC;AAOrE,MAAM,cAAc,GAAG,OAAO,CAAC;AAE/B;;;;;;GAMG;AACH,SAAS,eAAe,CAAC,MAAc;IACrC,IAAI,CAAC;QACH,OAAO,IAAI,IAAI,CAAC,MAAM,CAAC,MAAM,CAAC,OAAO,CAAC,IAAI,EAAE,GAAG,CAAC,CAAC,CAAC,QAAQ,EAAE,CAAC;IAC/D,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,cAAc,CAAC;IACxB,CAAC;AACH,CAAC;AAED;;;;;;;;;;;;;GAaG;AACH,MAAM,UAAU,OAAO;IACrB,MAAM,SAAS,GAAG,cAAc,CAAC,QAAQ,CAAC,CAAC;IAC3C,MAAM,SAAS,GAAG,cAAc,CAAC,WAAW,CAAC,CAAC;IAE9C,OAAO,EAAE,MAAM,EAAE,eAAe,CAAC,SAAS,CAAC,EAAE,SAAS,EAAE,CAAC;AAC3D,CAAC","sourcesContent":["import { type UserAgent, useHostContext } from \"../bridges/index.js\";\n\nexport type UserState = {\n  locale: string;\n  userAgent: UserAgent;\n};\n\nconst DEFAULT_LOCALE = \"en-US\";\n\n/**\n * Normalizes a locale string to canonical BCP 47 format using {@link Intl.Locale}.\n *\n * Handles underscored identifiers returned by the ChatGPT mobile app (e.g. \"fr_FR\" → \"fr-FR\"),\n * incorrect casing (e.g. \"en-us\" → \"en-US\"), and complex subtags (e.g. \"zh_Hans_CN\" → \"zh-Hans-CN\").\n * Falls back to \"en-US\" if the locale is invalid.\n */\nfunction normalizeLocale(locale: string): string {\n  try {\n    return new Intl.Locale(locale.replace(/_/g, \"-\")).toString();\n  } catch {\n    return DEFAULT_LOCALE;\n  }\n}\n\n/**\n * Hook for accessing session-stable user information.\n * These values are set once at initialization and do not change during the session.\n *\n * @example\n * ```tsx\n * const { locale, userAgent } = useUser();\n *\n * // Access device type\n * const isMobile = userAgent.device.type === \"mobile\";\n * ```\n *\n * @see https://docs.skybridge.tech/api-reference/use-user\n */\nexport function useUser(): UserState {\n  const rawLocale = useHostContext(\"locale\");\n  const userAgent = useHostContext(\"userAgent\");\n\n  return { locale: normalizeLocale(rawLocale), userAgent };\n}\n"]}

package/dist/web/hooks/use-view-state.d.ts

@@ -1,4 +1,25 @@
 import { type SetStateAction } from "react";
 import type { UnknownObject } from "../types.js";
+/**
+ * Persist a piece of UI state on the host, so it survives view remounts and
+ * is restored on subsequent renders of the same tool invocation.
+ *
+ * Returns a `[state, setState]` pair with the same ergonomics as
+ * `useState`. State is filtered to strip Skybridge-internal context fields
+ * (see {@link DataLLM}) before being returned to your component.
+ *
+ * Provide a `defaultState` (value or lazy initializer) to get a non-nullable
+ * tuple; omit it for `T | null`.
+ *
+ * @typeParam T - Shape of the persisted state. Must be a plain object.
+ *
+ * @example
+ * ```tsx
+ * const [filters, setFilters] = useViewState({ sort: "newest", page: 1 });
+ * setFilters((f) => ({ ...f, page: f.page + 1 }));
+ * ```
+ *
+ * @see https://docs.skybridge.tech/api-reference/use-view-state
+ */
 export declare function useViewState<T extends UnknownObject>(defaultState: T | (() => T)): readonly [T, (state: SetStateAction<T>) => void];
 export declare function useViewState<T extends UnknownObject>(defaultState?: T | (() => T | null) | null): readonly [T | null, (state: SetStateAction<T | null>) => void];

package/dist/web/hooks/use-view-state.js.map

@@ -1 +1 @@
-{"version":3,"file":"use-view-state.js","sourceRoot":"","sources":["../../../src/web/hooks/use-view-state.ts"],"names":[],"mappings":"AAAA,OAAO,EAAuB,WAAW,EAAE,SAAS,EAAE,QAAQ,EAAE,MAAM,OAAO,CAAC;AAC9E,OAAO,EAAE,UAAU,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAC;AACjE,OAAO,EAAE,iBAAiB,EAAE,iBAAiB,EAAE,MAAM,qBAAqB,CAAC;AAS3E,MAAM,UAAU,YAAY,CAC1B,YAA0C;IAE1C,MAAM,OAAO,GAAG,UAAU,EAAE,CAAC;IAC7B,MAAM,mBAAmB,GAAG,cAAc,CAAC,WAAW,CAAa,CAAC;IAEpE,MAAM,CAAC,SAAS,EAAE,aAAa,CAAC,GAAG,QAAQ,CAAW,GAAG,EAAE;QACzD,IAAI,mBAAmB,KAAK,IAAI,EAAE,CAAC;YACjC,OAAO,iBAAiB,CAAC,mBAAmB,CAAC,CAAC;QAChD,CAAC;QAED,OAAO,OAAO,YAAY,KAAK,UAAU;YACvC,CAAC,CAAC,YAAY,EAAE;YAChB,CAAC,CAAC,CAAC,YAAY,IAAI,IAAI,CAAC,CAAC;IAC7B,CAAC,CAAC,CAAC;IAEH,SAAS,CAAC,GAAG,EAAE;QACb,IAAI,mBAAmB,KAAK,IAAI,EAAE,CAAC;YACjC,aAAa,CAAC,iBAAiB,CAAC,mBAAmB,CAAC,CAAC,CAAC;QACxD,CAAC;IACH,CAAC,EAAE,CAAC,mBAAmB,CAAC,CAAC,CAAC;IAE1B,MAAM,YAAY,GAAG,WAAW,CAC9B,CAAC,KAA+B,EAAE,EAAE;QAClC,aAAa,CAAC,CAAC,SAAS,EAAE,EAAE;YAC1B,MAAM,QAAQ,GAAG,OAAO,KAAK,KAAK,UAAU,CAAC,CAAC,CAAC,KAAK,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC;YACxE,MAAM,UAAU,GAAG,iBAAiB,CAAC,QAAQ,CAAC,CAAC;YAE/C,IAAI,UAAU,KAAK,IAAI,EAAE,CAAC;gBACxB,OAAO,CAAC,YAAY,CAAC,UAAU,CAAC,CAAC;YACnC,CAAC;YAED,OAAO,iBAAiB,CAAC,UAAU,CAAC,CAAC;QACvC,CAAC,CAAC,CAAC;IACL,CAAC,EACD,CAAC,OAAO,CAAC,CACV,CAAC;IAEF,OAAO,CAAC,SAAS,EAAE,YAAY,CAAU,CAAC;AAC5C,CAAC","sourcesContent":["import { type SetStateAction, useCallback, useEffect, useState } from \"react\";\nimport { getAdaptor, useHostContext } from \"../bridges/index.js\";\nimport { filterViewContext, injectViewContext } from \"../helpers/state.js\";\nimport type { UnknownObject } from \"../types.js\";\n\nexport function useViewState<T extends UnknownObject>(\n  defaultState: T | (() => T),\n): readonly [T, (state: SetStateAction<T>) => void];\nexport function useViewState<T extends UnknownObject>(\n  defaultState?: T | (() => T | null) | null,\n): readonly [T | null, (state: SetStateAction<T | null>) => void];\nexport function useViewState<T extends UnknownObject>(\n  defaultState?: T | (() => T | null) | null,\n): readonly [T | null, (state: SetStateAction<T | null>) => void] {\n  const adaptor = getAdaptor();\n  const viewStateFromBridge = useHostContext(\"viewState\") as T | null;\n\n  const [viewState, _setViewState] = useState<T | null>(() => {\n    if (viewStateFromBridge !== null) {\n      return filterViewContext(viewStateFromBridge);\n    }\n\n    return typeof defaultState === \"function\"\n      ? defaultState()\n      : (defaultState ?? null);\n  });\n\n  useEffect(() => {\n    if (viewStateFromBridge !== null) {\n      _setViewState(filterViewContext(viewStateFromBridge));\n    }\n  }, [viewStateFromBridge]);\n\n  const setViewState = useCallback(\n    (state: SetStateAction<T | null>) => {\n      _setViewState((prevState) => {\n        const newState = typeof state === \"function\" ? state(prevState) : state;\n        const stateToSet = injectViewContext(newState);\n\n        if (stateToSet !== null) {\n          adaptor.setViewState(stateToSet);\n        }\n\n        return filterViewContext(stateToSet);\n      });\n    },\n    [adaptor],\n  );\n\n  return [viewState, setViewState] as const;\n}\n"]}
+{"version":3,"file":"use-view-state.js","sourceRoot":"","sources":["../../../src/web/hooks/use-view-state.ts"],"names":[],"mappings":"AAAA,OAAO,EAAuB,WAAW,EAAE,SAAS,EAAE,QAAQ,EAAE,MAAM,OAAO,CAAC;AAC9E,OAAO,EAAE,UAAU,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAC;AACjE,OAAO,EAAE,iBAAiB,EAAE,iBAAiB,EAAE,MAAM,qBAAqB,CAAC;AA8B3E,MAAM,UAAU,YAAY,CAC1B,YAA0C;IAE1C,MAAM,OAAO,GAAG,UAAU,EAAE,CAAC;IAC7B,MAAM,mBAAmB,GAAG,cAAc,CAAC,WAAW,CAAa,CAAC;IAEpE,MAAM,CAAC,SAAS,EAAE,aAAa,CAAC,GAAG,QAAQ,CAAW,GAAG,EAAE;QACzD,IAAI,mBAAmB,KAAK,IAAI,EAAE,CAAC;YACjC,OAAO,iBAAiB,CAAC,mBAAmB,CAAC,CAAC;QAChD,CAAC;QAED,OAAO,OAAO,YAAY,KAAK,UAAU;YACvC,CAAC,CAAC,YAAY,EAAE;YAChB,CAAC,CAAC,CAAC,YAAY,IAAI,IAAI,CAAC,CAAC;IAC7B,CAAC,CAAC,CAAC;IAEH,SAAS,CAAC,GAAG,EAAE;QACb,IAAI,mBAAmB,KAAK,IAAI,EAAE,CAAC;YACjC,aAAa,CAAC,iBAAiB,CAAC,mBAAmB,CAAC,CAAC,CAAC;QACxD,CAAC;IACH,CAAC,EAAE,CAAC,mBAAmB,CAAC,CAAC,CAAC;IAE1B,MAAM,YAAY,GAAG,WAAW,CAC9B,CAAC,KAA+B,EAAE,EAAE;QAClC,aAAa,CAAC,CAAC,SAAS,EAAE,EAAE;YAC1B,MAAM,QAAQ,GAAG,OAAO,KAAK,KAAK,UAAU,CAAC,CAAC,CAAC,KAAK,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC;YACxE,MAAM,UAAU,GAAG,iBAAiB,CAAC,QAAQ,CAAC,CAAC;YAE/C,IAAI,UAAU,KAAK,IAAI,EAAE,CAAC;gBACxB,OAAO,CAAC,YAAY,CAAC,UAAU,CAAC,CAAC;YACnC,CAAC;YAED,OAAO,iBAAiB,CAAC,UAAU,CAAC,CAAC;QACvC,CAAC,CAAC,CAAC;IACL,CAAC,EACD,CAAC,OAAO,CAAC,CACV,CAAC;IAEF,OAAO,CAAC,SAAS,EAAE,YAAY,CAAU,CAAC;AAC5C,CAAC","sourcesContent":["import { type SetStateAction, useCallback, useEffect, useState } from \"react\";\nimport { getAdaptor, useHostContext } from \"../bridges/index.js\";\nimport { filterViewContext, injectViewContext } from \"../helpers/state.js\";\nimport type { UnknownObject } from \"../types.js\";\n\n/**\n * Persist a piece of UI state on the host, so it survives view remounts and\n * is restored on subsequent renders of the same tool invocation.\n *\n * Returns a `[state, setState]` pair with the same ergonomics as\n * `useState`. State is filtered to strip Skybridge-internal context fields\n * (see {@link DataLLM}) before being returned to your component.\n *\n * Provide a `defaultState` (value or lazy initializer) to get a non-nullable\n * tuple; omit it for `T | null`.\n *\n * @typeParam T - Shape of the persisted state. Must be a plain object.\n *\n * @example\n * ```tsx\n * const [filters, setFilters] = useViewState({ sort: \"newest\", page: 1 });\n * setFilters((f) => ({ ...f, page: f.page + 1 }));\n * ```\n *\n * @see https://docs.skybridge.tech/api-reference/use-view-state\n */\nexport function useViewState<T extends UnknownObject>(\n  defaultState: T | (() => T),\n): readonly [T, (state: SetStateAction<T>) => void];\nexport function useViewState<T extends UnknownObject>(\n  defaultState?: T | (() => T | null) | null,\n): readonly [T | null, (state: SetStateAction<T | null>) => void];\nexport function useViewState<T extends UnknownObject>(\n  defaultState?: T | (() => T | null) | null,\n): readonly [T | null, (state: SetStateAction<T | null>) => void] {\n  const adaptor = getAdaptor();\n  const viewStateFromBridge = useHostContext(\"viewState\") as T | null;\n\n  const [viewState, _setViewState] = useState<T | null>(() => {\n    if (viewStateFromBridge !== null) {\n      return filterViewContext(viewStateFromBridge);\n    }\n\n    return typeof defaultState === \"function\"\n      ? defaultState()\n      : (defaultState ?? null);\n  });\n\n  useEffect(() => {\n    if (viewStateFromBridge !== null) {\n      _setViewState(filterViewContext(viewStateFromBridge));\n    }\n  }, [viewStateFromBridge]);\n\n  const setViewState = useCallback(\n    (state: SetStateAction<T | null>) => {\n      _setViewState((prevState) => {\n        const newState = typeof state === \"function\" ? state(prevState) : state;\n        const stateToSet = injectViewContext(newState);\n\n        if (stateToSet !== null) {\n          adaptor.setViewState(stateToSet);\n        }\n\n        return filterViewContext(stateToSet);\n      });\n    },\n    [adaptor],\n  );\n\n  return [viewState, setViewState] as const;\n}\n"]}

package/dist/web/mount-view.d.ts

@@ -1 +1,20 @@
+/**
+ * Mount a view's root React component into `#root`. Each view file's entry
+ * point should call this exactly once.
+ *
+ * Wraps the component in `StrictMode`, applies host-specific providers
+ * automatically (e.g. modal support for MCP Apps), and installs the dev-mode
+ * logging proxy for `window.openai` calls.
+ *
+ * @param component - Your root React element (already constructed, e.g. `<App />`).
+ *
+ * @example
+ * ```tsx
+ * // src/views/search.tsx
+ * import { mountView } from "skybridge/web";
+ * import { App } from "./App";
+ *
+ * mountView(<App />);
+ * ```
+ */
 export declare const mountView: (component: React.ReactNode) => void;

package/dist/web/mount-view.js

@@ -3,6 +3,25 @@ import { createElement, StrictMode } from "react";
 import { createRoot } from "react-dom/client";
 import { installOpenAILoggingProxy } from "./proxy.js";
 let rootInstance = null;
+/**
+ * Mount a view's root React component into `#root`. Each view file's entry
+ * point should call this exactly once.
+ *
+ * Wraps the component in `StrictMode`, applies host-specific providers
+ * automatically (e.g. modal support for MCP Apps), and installs the dev-mode
+ * logging proxy for `window.openai` calls.
+ *
+ * @param component - Your root React element (already constructed, e.g. `<App />`).
+ *
+ * @example
+ * ```tsx
+ * // src/views/search.tsx
+ * import { mountView } from "skybridge/web";
+ * import { App } from "./App";
+ *
+ * mountView(<App />);
+ * ```
+ */
 export const mountView = (component) => {
     const rootElement = document.getElementById("root");
     if (!rootElement) {

package/dist/web/mount-view.js.map

@@ -1 +1 @@
-{"version":3,"file":"mount-view.js","sourceRoot":"","sources":["../../src/web/mount-view.ts"],"names":[],"mappings":"AAAA,qCAAqC;AAErC,OAAO,EAAE,aAAa,EAAE,UAAU,EAAE,MAAM,OAAO,CAAC;AAClD,OAAO,EAAE,UAAU,EAAa,MAAM,kBAAkB,CAAC;AACzD,OAAO,EAAE,yBAAyB,EAAE,MAAM,YAAY,CAAC;AAEvD,IAAI,YAAY,GAAgB,IAAI,CAAC;AAErC,MAAM,CAAC,MAAM,SAAS,GAAG,CAAC,SAA0B,EAAE,EAAE;IACtD,MAAM,WAAW,GAAG,QAAQ,CAAC,cAAc,CAAC,MAAM,CAAC,CAAC;IACpD,IAAI,CAAC,WAAW,EAAE,CAAC;QACjB,MAAM,IAAI,KAAK,CAAC,wBAAwB,CAAC,CAAC;IAC5C,CAAC;IAED,IAAI,CAAC,YAAY,EAAE,CAAC;QAClB,YAAY,GAAG,UAAU,CAAC,WAAW,CAAC,CAAC;IACzC,CAAC;IAED,IAAI,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,GAAG,EAAE,CAAC;QACxB,yBAAyB,EAAE,CAAC;IAC9B,CAAC;IAED,MAAM,QAAQ,GAAG,MAAM,CAAC,SAAS,EAAE,QAAQ,CAAC;IAE5C,CAAC,KAAK,IAAI,EAAE;QACV,IAAI,GAAG,GAAG,SAAS,CAAC;QACpB,IAAI,QAAQ,KAAK,SAAS,EAAE,CAAC;YAC3B,MAAM,EAAE,aAAa,EAAE,GAAG,MAAM,MAAM,CAAC,gCAAgC,CAAC,CAAC;YACzE,GAAG,GAAG,aAAa,CAAC,aAAa,EAAE,IAAI,EAAE,SAAS,CAAC,CAAC;QACtD,CAAC;QACD,YAAY,CAAC,MAAM,CAAC,aAAa,CAAC,UAAU,EAAE,IAAI,EAAE,GAAG,CAAC,CAAC,CAAC;IAC5D,CAAC,CAAC,EAAE,CAAC;AACP,CAAC,CAAC","sourcesContent":["/// <reference types=\"vite/client\" />\n\nimport { createElement, StrictMode } from \"react\";\nimport { createRoot, type Root } from \"react-dom/client\";\nimport { installOpenAILoggingProxy } from \"./proxy.js\";\n\nlet rootInstance: Root | null = null;\n\nexport const mountView = (component: React.ReactNode) => {\n  const rootElement = document.getElementById(\"root\");\n  if (!rootElement) {\n    throw new Error(\"Root element not found\");\n  }\n\n  if (!rootInstance) {\n    rootInstance = createRoot(rootElement);\n  }\n\n  if (import.meta.env.DEV) {\n    installOpenAILoggingProxy();\n  }\n\n  const hostType = window.skybridge?.hostType;\n\n  (async () => {\n    let app = component;\n    if (hostType === \"mcp-app\") {\n      const { ModalProvider } = await import(\"./components/modal-provider.js\");\n      app = createElement(ModalProvider, null, component);\n    }\n    rootInstance.render(createElement(StrictMode, null, app));\n  })();\n};\n"]}
+{"version":3,"file":"mount-view.js","sourceRoot":"","sources":["../../src/web/mount-view.ts"],"names":[],"mappings":"AAAA,qCAAqC;AAErC,OAAO,EAAE,aAAa,EAAE,UAAU,EAAE,MAAM,OAAO,CAAC;AAClD,OAAO,EAAE,UAAU,EAAa,MAAM,kBAAkB,CAAC;AACzD,OAAO,EAAE,yBAAyB,EAAE,MAAM,YAAY,CAAC;AAEvD,IAAI,YAAY,GAAgB,IAAI,CAAC;AAErC;;;;;;;;;;;;;;;;;;GAkBG;AACH,MAAM,CAAC,MAAM,SAAS,GAAG,CAAC,SAA0B,EAAE,EAAE;IACtD,MAAM,WAAW,GAAG,QAAQ,CAAC,cAAc,CAAC,MAAM,CAAC,CAAC;IACpD,IAAI,CAAC,WAAW,EAAE,CAAC;QACjB,MAAM,IAAI,KAAK,CAAC,wBAAwB,CAAC,CAAC;IAC5C,CAAC;IAED,IAAI,CAAC,YAAY,EAAE,CAAC;QAClB,YAAY,GAAG,UAAU,CAAC,WAAW,CAAC,CAAC;IACzC,CAAC;IAED,IAAI,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,GAAG,EAAE,CAAC;QACxB,yBAAyB,EAAE,CAAC;IAC9B,CAAC;IAED,MAAM,QAAQ,GAAG,MAAM,CAAC,SAAS,EAAE,QAAQ,CAAC;IAE5C,CAAC,KAAK,IAAI,EAAE;QACV,IAAI,GAAG,GAAG,SAAS,CAAC;QACpB,IAAI,QAAQ,KAAK,SAAS,EAAE,CAAC;YAC3B,MAAM,EAAE,aAAa,EAAE,GAAG,MAAM,MAAM,CAAC,gCAAgC,CAAC,CAAC;YACzE,GAAG,GAAG,aAAa,CAAC,aAAa,EAAE,IAAI,EAAE,SAAS,CAAC,CAAC;QACtD,CAAC;QACD,YAAY,CAAC,MAAM,CAAC,aAAa,CAAC,UAAU,EAAE,IAAI,EAAE,GAAG,CAAC,CAAC,CAAC;IAC5D,CAAC,CAAC,EAAE,CAAC;AACP,CAAC,CAAC","sourcesContent":["/// <reference types=\"vite/client\" />\n\nimport { createElement, StrictMode } from \"react\";\nimport { createRoot, type Root } from \"react-dom/client\";\nimport { installOpenAILoggingProxy } from \"./proxy.js\";\n\nlet rootInstance: Root | null = null;\n\n/**\n * Mount a view's root React component into `#root`. Each view file's entry\n * point should call this exactly once.\n *\n * Wraps the component in `StrictMode`, applies host-specific providers\n * automatically (e.g. modal support for MCP Apps), and installs the dev-mode\n * logging proxy for `window.openai` calls.\n *\n * @param component - Your root React element (already constructed, e.g. `<App />`).\n *\n * @example\n * ```tsx\n * // src/views/search.tsx\n * import { mountView } from \"skybridge/web\";\n * import { App } from \"./App\";\n *\n * mountView(<App />);\n * ```\n */\nexport const mountView = (component: React.ReactNode) => {\n  const rootElement = document.getElementById(\"root\");\n  if (!rootElement) {\n    throw new Error(\"Root element not found\");\n  }\n\n  if (!rootInstance) {\n    rootInstance = createRoot(rootElement);\n  }\n\n  if (import.meta.env.DEV) {\n    installOpenAILoggingProxy();\n  }\n\n  const hostType = window.skybridge?.hostType;\n\n  (async () => {\n    let app = component;\n    if (hostType === \"mcp-app\") {\n      const { ModalProvider } = await import(\"./components/modal-provider.js\");\n      app = createElement(ModalProvider, null, component);\n    }\n    rootInstance.render(createElement(StrictMode, null, app));\n  })();\n};\n"]}

package/dist/web/plugin/plugin.d.ts

@@ -1,5 +1,33 @@
 import type { Plugin } from "vite";
+/** Options for the {@link skybridge} Vite plugin. */
 export interface SkybridgePluginOptions {
+    /** Directory scanned for view modules. Defaults to `"src/views"`. */
     viewsDir?: string;
 }
+/**
+ * Vite plugin that wires a Skybridge project's view files into Vite.
+ *
+ * For each `.tsx` / `.jsx` file in `viewsDir` with a default export, the
+ * plugin:
+ * - exposes a virtual entry that calls {@link mountView} with the view's
+ *   default export,
+ * - generates `.skybridge/views.d.ts` to augment {@link ViewNameRegistry} so
+ *   {@link ViewName} narrows to the actual view names,
+ * - rewrites `<DataLLM>` JSX so the host can extract its content,
+ * - warns in dev if a view file is missing a default export.
+ *
+ * Add it to your `vite.config.ts` alongside `@vitejs/plugin-react`.
+ *
+ * @example
+ * ```ts
+ * // vite.config.ts
+ * import { defineConfig } from "vite";
+ * import react from "@vitejs/plugin-react";
+ * import { skybridge } from "skybridge/vite";
+ *
+ * export default defineConfig({
+ *   plugins: [react(), skybridge({ viewsDir: "src/views" })],
+ * });
+ * ```
+ */
 export declare function skybridge(options?: SkybridgePluginOptions): Plugin;

package/dist/web/plugin/plugin.js

@@ -17,6 +17,32 @@ function getViewEntryPattern(viewsDir) {
     const escaped = viewsDir.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
     return new RegExp(`${escaped}\\/(?:[^/]+\\.(?:jsx|tsx)|[^/]+\\/index\\.(?:tsx|jsx))(?:\\?.*)?$`);
 }
+/**
+ * Vite plugin that wires a Skybridge project's view files into Vite.
+ *
+ * For each `.tsx` / `.jsx` file in `viewsDir` with a default export, the
+ * plugin:
+ * - exposes a virtual entry that calls {@link mountView} with the view's
+ *   default export,
+ * - generates `.skybridge/views.d.ts` to augment {@link ViewNameRegistry} so
+ *   {@link ViewName} narrows to the actual view names,
+ * - rewrites `<DataLLM>` JSX so the host can extract its content,
+ * - warns in dev if a view file is missing a default export.
+ *
+ * Add it to your `vite.config.ts` alongside `@vitejs/plugin-react`.
+ *
+ * @example
+ * ```ts
+ * // vite.config.ts
+ * import { defineConfig } from "vite";
+ * import react from "@vitejs/plugin-react";
+ * import { skybridge } from "skybridge/vite";
+ *
+ * export default defineConfig({
+ *   plugins: [react(), skybridge({ viewsDir: "src/views" })],
+ * });
+ * ```
+ */
 export function skybridge(options) {
     const rawViewsDir = options?.viewsDir ?? "src/views";
     let resolvedViewsDir;