skybridge 0.0.0-dev.f3fc72c → 0.0.0-dev.f40327b

package/dist/web/bridges/types.d.ts

@@ -0,0 +1,171 @@
+import type { CallToolResult, EmbeddedResource, ResourceLink } from "@modelcontextprotocol/sdk/types.js";
+import type { useSyncExternalStore } from "react";
+import type { ViewHostType } from "../../server/index.js";
+/**
+ * Globals injected on `window.skybridge` by the host. Tells the view which
+ * runtime it's running under and where to reach the MCP server.
+ */
+export type SkybridgeProperties = {
+    hostType: ViewHostType;
+    serverUrl: string;
+};
+declare global {
+    interface Window {
+        skybridge: SkybridgeProperties;
+    }
+}
+/** Arguments passed to a tool call. `null` for tools that take no input. */
+export type CallToolArgs = Record<string, unknown> | null;
+/**
+ * Result of a tool call as surfaced to the view: MCP `content` blocks plus
+ * the typed `structuredContent` and optional `meta`. `isError` is set when
+ * the server marks the call as failed.
+ */
+export type CallToolResponse = {
+    content: CallToolResult["content"];
+    structuredContent: NonNullable<CallToolResult["structuredContent"]>;
+    isError: NonNullable<CallToolResult["isError"]>;
+    meta?: CallToolResult["_meta"];
+};
+/**
+ * How the view is laid out by the host. `"modal"` is host-driven (see
+ * {@link useRequestModal}); `"pip"`, `"inline"`, and `"fullscreen"` are
+ * requestable via {@link useDisplayMode}.
+ */
+export type DisplayMode = "pip" | "inline" | "fullscreen" | "modal";
+/** Subset of {@link DisplayMode} that the view can request from the host. */
+export type RequestDisplayMode = Exclude<DisplayMode, "modal">;
+/** Host theme. Mirror this in your view's styling for a native feel. */
+export type Theme = "light" | "dark";
+/** Coarse device class reported by the host. `"unknown"` when unavailable. */
+export type DeviceType = "mobile" | "tablet" | "desktop" | "unknown";
+/** Pixel insets the view should keep clear of (notches, home indicators, etc.). */
+export type SafeAreaInsets = {
+    top: number;
+    right: number;
+    bottom: number;
+    left: number;
+};
+/** Wrapper around {@link SafeAreaInsets} exposed via {@link useLayout}. */
+export type SafeArea = {
+    insets: SafeAreaInsets;
+};
+/** Device and input-capability hints exposed via {@link useUser}. */
+export type UserAgent = {
+    device: {
+        type: DeviceType;
+    };
+    capabilities: {
+        hover: boolean;
+        touch: boolean;
+    };
+};
+/**
+ * Full snapshot of state the host exposes to the view. Most fields are
+ * better accessed through their dedicated hooks (`useLayout`, `useUser`,
+ * `useToolInfo`, etc.) — read this directly only for advanced cases.
+ */
+export interface HostContext {
+    theme: Theme;
+    locale: string;
+    displayMode: DisplayMode;
+    safeArea: SafeArea;
+    maxHeight: number | undefined;
+    userAgent: UserAgent;
+    toolInput: Record<string, unknown> | null;
+    toolOutput: Record<string, unknown> | null;
+    toolResponseMetadata: Record<string, unknown> | null;
+    display: {
+        mode: DisplayMode;
+        params?: Record<string, unknown>;
+    };
+    viewState: Record<string, unknown> | null;
+}
+/** @internal `useSyncExternalStore` subscribe signature, re-exported for bridge implementations. */
+export type Subscribe = Parameters<typeof useSyncExternalStore>[0];
+/** @internal Bridge contract implemented by per-host bridge classes. */
+export interface Bridge<Context> {
+    subscribe(key: keyof Context): Subscribe;
+    subscribe(keys: readonly (keyof Context)[]): Subscribe;
+    getSnapshot<K extends keyof Context>(key: K): Context[K] | undefined;
+}
+/** @internal Per-key snapshot store backing {@link useHostContext}. */
+export type HostContextStore<K extends keyof HostContext> = {
+    subscribe: Subscribe;
+    getSnapshot: () => HostContext[K];
+};
+/** Persisted view state shape (a plain object). See {@link useViewState}. */
+export type ViewState = Record<string, unknown>;
+/** Updater form accepted when writing to view state. */
+export type SetViewStateAction = ViewState | ((prevState: ViewState | null) => ViewState);
+/** Reference to a host-managed file (returned by {@link useFiles}). */
+export type FileMetadata = {
+    fileId: string;
+    fileName?: string;
+    mimeType?: string;
+};
+/** Options for {@link useFiles}'s `upload`. `library: true` saves into the user's library when supported. */
+export type UploadFileOptions = {
+    library?: boolean;
+};
+/** Options for {@link useRequestModal}'s `open` call. */
+export type RequestModalOptions = {
+    title?: string;
+    params?: Record<string, unknown>;
+    template?: string;
+    anchor?: {
+        top?: number;
+        left?: number;
+        width?: number;
+        height?: number;
+    };
+};
+/**
+ * Options for {@link useOpenExternal}. Set `redirectUrl: false` to tell the
+ * host not to append its `?redirectUrl=…` tracking query parameter when
+ * opening allowlisted targets.
+ */
+export type OpenExternalOptions = {
+    redirectUrl?: false;
+};
+/** Options for {@link useSendFollowUpMessage}. */
+export type SendFollowUpMessageOptions = {
+    scrollToBottom?: boolean;
+};
+/** Options for {@link useRequestSize}. Omit a dimension to leave it unchanged. */
+export type RequestSizeOptions = {
+    width?: number;
+    height?: number;
+};
+export type DownloadParams = {
+    contents: (EmbeddedResource | ResourceLink)[];
+};
+export type DownloadResult = {
+    isError?: boolean;
+};
+/**
+ * @internal
+ * Low-level interface every host bridge implements. End-user code should use
+ * the React hooks (`useCallTool`, `useViewState`, `useFiles`, …) rather than
+ * calling this directly.
+ */
+export interface Adaptor {
+    getHostContextStore<K extends keyof HostContext>(key: K): HostContextStore<K>;
+    callTool<ToolArgs extends CallToolArgs = null, ToolResponse extends CallToolResponse = CallToolResponse>(name: string, args: ToolArgs): Promise<ToolResponse>;
+    requestDisplayMode(mode: RequestDisplayMode): Promise<{
+        mode: RequestDisplayMode;
+    }>;
+    requestClose(): Promise<void>;
+    requestSize(size: RequestSizeOptions): Promise<void>;
+    sendFollowUpMessage(prompt: string, options?: SendFollowUpMessageOptions): Promise<void>;
+    openExternal(href: string, options?: OpenExternalOptions): void;
+    download(params: DownloadParams): Promise<DownloadResult>;
+    setViewState(stateOrUpdater: SetViewStateAction): Promise<void>;
+    uploadFile(file: File, options?: UploadFileOptions): Promise<FileMetadata>;
+    getFileDownloadUrl(file: FileMetadata): Promise<{
+        downloadUrl: string;
+    }>;
+    selectFiles(): Promise<FileMetadata[]>;
+    openModal(options: RequestModalOptions): void;
+    setOpenInAppUrl(href: string): Promise<void>;
+}

package/dist/web/bridges/types.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=types.js.map

package/dist/web/bridges/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../../src/web/bridges/types.ts"],"names":[],"mappings":"","sourcesContent":["import type {\n  CallToolResult,\n  EmbeddedResource,\n  ResourceLink,\n} from \"@modelcontextprotocol/sdk/types.js\";\nimport type { useSyncExternalStore } from \"react\";\nimport type { ViewHostType } from \"../../server/index.js\";\n\n/**\n * Globals injected on `window.skybridge` by the host. Tells the view which\n * runtime it's running under and where to reach the MCP server.\n */\nexport type SkybridgeProperties = {\n  hostType: ViewHostType;\n  serverUrl: string;\n};\n\ndeclare global {\n  interface Window {\n    skybridge: SkybridgeProperties;\n  }\n}\n\n/** Arguments passed to a tool call. `null` for tools that take no input. */\nexport type CallToolArgs = Record<string, unknown> | null;\n\n/**\n * Result of a tool call as surfaced to the view: MCP `content` blocks plus\n * the typed `structuredContent` and optional `meta`. `isError` is set when\n * the server marks the call as failed.\n */\nexport type CallToolResponse = {\n  content: CallToolResult[\"content\"];\n  structuredContent: NonNullable<CallToolResult[\"structuredContent\"]>;\n  isError: NonNullable<CallToolResult[\"isError\"]>;\n  meta?: CallToolResult[\"_meta\"];\n};\n\n/**\n * How the view is laid out by the host. `\"modal\"` is host-driven (see\n * {@link useRequestModal}); `\"pip\"`, `\"inline\"`, and `\"fullscreen\"` are\n * requestable via {@link useDisplayMode}.\n */\nexport type DisplayMode = \"pip\" | \"inline\" | \"fullscreen\" | \"modal\";\n/** Subset of {@link DisplayMode} that the view can request from the host. */\nexport type RequestDisplayMode = Exclude<DisplayMode, \"modal\">;\n\n/** Host theme. Mirror this in your view's styling for a native feel. */\nexport type Theme = \"light\" | \"dark\";\n\n/** Coarse device class reported by the host. `\"unknown\"` when unavailable. */\nexport type DeviceType = \"mobile\" | \"tablet\" | \"desktop\" | \"unknown\";\n\n/** Pixel insets the view should keep clear of (notches, home indicators, etc.). */\nexport type SafeAreaInsets = {\n  top: number;\n  right: number;\n  bottom: number;\n  left: number;\n};\n\n/** Wrapper around {@link SafeAreaInsets} exposed via {@link useLayout}. */\nexport type SafeArea = {\n  insets: SafeAreaInsets;\n};\n\n/** Device and input-capability hints exposed via {@link useUser}. */\nexport type UserAgent = {\n  device: {\n    type: DeviceType;\n  };\n  capabilities: {\n    hover: boolean;\n    touch: boolean;\n  };\n};\n\n/**\n * Full snapshot of state the host exposes to the view. Most fields are\n * better accessed through their dedicated hooks (`useLayout`, `useUser`,\n * `useToolInfo`, etc.) — read this directly only for advanced cases.\n */\nexport interface HostContext {\n  theme: Theme;\n  locale: string;\n  displayMode: DisplayMode;\n  safeArea: SafeArea;\n  maxHeight: number | undefined;\n  userAgent: UserAgent;\n  toolInput: Record<string, unknown> | null;\n  toolOutput: Record<string, unknown> | null;\n  toolResponseMetadata: Record<string, unknown> | null;\n  display: {\n    mode: DisplayMode;\n    params?: Record<string, unknown>;\n  };\n  viewState: Record<string, unknown> | null;\n}\n\n/** @internal `useSyncExternalStore` subscribe signature, re-exported for bridge implementations. */\nexport type Subscribe = Parameters<typeof useSyncExternalStore>[0];\n\n/** @internal Bridge contract implemented by per-host bridge classes. */\nexport interface Bridge<Context> {\n  subscribe(key: keyof Context): Subscribe;\n  subscribe(keys: readonly (keyof Context)[]): Subscribe;\n  getSnapshot<K extends keyof Context>(key: K): Context[K] | undefined;\n}\n\n/** @internal Per-key snapshot store backing {@link useHostContext}. */\nexport type HostContextStore<K extends keyof HostContext> = {\n  subscribe: Subscribe;\n  getSnapshot: () => HostContext[K];\n};\n\n/** Persisted view state shape (a plain object). See {@link useViewState}. */\nexport type ViewState = Record<string, unknown>;\n\n/** Updater form accepted when writing to view state. */\nexport type SetViewStateAction =\n  | ViewState\n  | ((prevState: ViewState | null) => ViewState);\n\n/** Reference to a host-managed file (returned by {@link useFiles}). */\nexport type FileMetadata = {\n  fileId: string;\n  fileName?: string;\n  mimeType?: string;\n};\n\n/** Options for {@link useFiles}'s `upload`. `library: true` saves into the user's library when supported. */\nexport type UploadFileOptions = { library?: boolean };\n\n/** Options for {@link useRequestModal}'s `open` call. */\nexport type RequestModalOptions = {\n  title?: string;\n  params?: Record<string, unknown>;\n  template?: string;\n  anchor?: { top?: number; left?: number; width?: number; height?: number };\n};\n\n/**\n * Options for {@link useOpenExternal}. Set `redirectUrl: false` to tell the\n * host not to append its `?redirectUrl=…` tracking query parameter when\n * opening allowlisted targets.\n */\nexport type OpenExternalOptions = {\n  redirectUrl?: false;\n};\n\n/** Options for {@link useSendFollowUpMessage}. */\nexport type SendFollowUpMessageOptions = { scrollToBottom?: boolean };\n\n/** Options for {@link useRequestSize}. Omit a dimension to leave it unchanged. */\nexport type RequestSizeOptions = {\n  width?: number;\n  height?: number;\n};\n\nexport type DownloadParams = {\n  contents: (EmbeddedResource | ResourceLink)[];\n};\n\nexport type DownloadResult = {\n  isError?: boolean;\n};\n\n/**\n * @internal\n * Low-level interface every host bridge implements. End-user code should use\n * the React hooks (`useCallTool`, `useViewState`, `useFiles`, …) rather than\n * calling this directly.\n */\nexport interface Adaptor {\n  getHostContextStore<K extends keyof HostContext>(key: K): HostContextStore<K>;\n  callTool<\n    ToolArgs extends CallToolArgs = null,\n    ToolResponse extends CallToolResponse = CallToolResponse,\n  >(name: string, args: ToolArgs): Promise<ToolResponse>;\n  requestDisplayMode(mode: RequestDisplayMode): Promise<{\n    mode: RequestDisplayMode;\n  }>;\n  requestClose(): Promise<void>;\n  requestSize(size: RequestSizeOptions): Promise<void>;\n  sendFollowUpMessage(\n    prompt: string,\n    options?: SendFollowUpMessageOptions,\n  ): Promise<void>;\n  openExternal(href: string, options?: OpenExternalOptions): void;\n  download(params: DownloadParams): Promise<DownloadResult>;\n  setViewState(stateOrUpdater: SetViewStateAction): Promise<void>;\n  uploadFile(file: File, options?: UploadFileOptions): Promise<FileMetadata>;\n  getFileDownloadUrl(file: FileMetadata): Promise<{ downloadUrl: string }>;\n  selectFiles(): Promise<FileMetadata[]>;\n  openModal(options: RequestModalOptions): void;\n  setOpenInAppUrl(href: string): Promise<void>;\n}\n"]}

package/dist/web/bridges/use-host-context.d.ts

@@ -0,0 +1,7 @@
+import type { HostContext } from "./types.js";
+/**
+ * @internal
+ * Subscribe to a single {@link HostContext} key via `useSyncExternalStore`.
+ * Used to build the higher-level hooks; prefer those for app code.
+ */
+export declare const useHostContext: <K extends keyof HostContext>(key: K) => HostContext[K];

package/dist/web/bridges/use-host-context.js

@@ -0,0 +1,13 @@
+import { useSyncExternalStore } from "react";
+import { getAdaptor } from "./get-adaptor.js";
+/**
+ * @internal
+ * Subscribe to a single {@link HostContext} key via `useSyncExternalStore`.
+ * Used to build the higher-level hooks; prefer those for app code.
+ */
+export const useHostContext = (key) => {
+    const adaptor = getAdaptor();
+    const store = adaptor.getHostContextStore(key);
+    return useSyncExternalStore(store.subscribe, store.getSnapshot);
+};
+//# sourceMappingURL=use-host-context.js.map

package/dist/web/bridges/use-host-context.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"use-host-context.js","sourceRoot":"","sources":["../../../src/web/bridges/use-host-context.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,oBAAoB,EAAE,MAAM,OAAO,CAAC;AAC7C,OAAO,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAG9C;;;;GAIG;AACH,MAAM,CAAC,MAAM,cAAc,GAAG,CAC5B,GAAM,EACU,EAAE;IAClB,MAAM,OAAO,GAAG,UAAU,EAAE,CAAC;IAC7B,MAAM,KAAK,GAAG,OAAO,CAAC,mBAAmB,CAAC,GAAG,CAAC,CAAC;IAE/C,OAAO,oBAAoB,CAAC,KAAK,CAAC,SAAS,EAAE,KAAK,CAAC,WAAW,CAAC,CAAC;AAClE,CAAC,CAAC","sourcesContent":["import { useSyncExternalStore } from \"react\";\nimport { getAdaptor } from \"./get-adaptor.js\";\nimport type { HostContext } from \"./types.js\";\n\n/**\n * @internal\n * Subscribe to a single {@link HostContext} key via `useSyncExternalStore`.\n * Used to build the higher-level hooks; prefer those for app code.\n */\nexport const useHostContext = <K extends keyof HostContext>(\n  key: K,\n): HostContext[K] => {\n  const adaptor = getAdaptor();\n  const store = adaptor.getHostContextStore(key);\n\n  return useSyncExternalStore(store.subscribe, store.getSnapshot);\n};\n"]}

package/dist/web/components/modal-provider.d.ts

@@ -0,0 +1,4 @@
+import { type ReactNode } from "react";
+export declare function ModalProvider({ children }: {
+    children: ReactNode;
+}): import("react/jsx-runtime").JSX.Element;

package/dist/web/components/modal-provider.js

@@ -0,0 +1,45 @@
+import { jsx as _jsx, Fragment as _Fragment, jsxs as _jsxs } from "react/jsx-runtime";
+import { useEffect, useSyncExternalStore } from "react";
+import { McpAppAdaptor } from "../bridges/index.js";
+const modalStyles = `
+.sb-modal-backdrop {
+  position: fixed;
+  inset: 0;
+  background: rgba(0, 0, 0, 0.5);
+  z-index: 9998;
+}
+.sb-modal-container {
+  border-radius: 12px;
+  position: fixed;
+  inset: 0;
+  margin: auto;
+  width: fit-content;
+  height: fit-content;
+  background: white;
+  z-index: 9999;
+}
+`;
+export function ModalProvider({ children }) {
+    const adaptor = McpAppAdaptor.getInstance();
+    const { mode } = useSyncExternalStore(adaptor.getHostContextStore("display").subscribe, adaptor.getHostContextStore("display").getSnapshot);
+    const isOpen = mode === "modal";
+    const handleBackdropClick = (e) => {
+        if (e.target === e.currentTarget) {
+            adaptor.closeModal();
+        }
+    };
+    useEffect(() => {
+        if (!isOpen) {
+            return;
+        }
+        const handler = (e) => {
+            if (e.key === "Escape") {
+                adaptor.closeModal();
+            }
+        };
+        document.addEventListener("keydown", handler);
+        return () => document.removeEventListener("keydown", handler);
+    }, [isOpen, adaptor]);
+    return (_jsxs(_Fragment, { children: [_jsx("style", { children: modalStyles }), isOpen && (_jsx("div", { role: "dialog", className: "sb-modal-backdrop", onClick: handleBackdropClick })), _jsx("div", { className: isOpen ? "sb-modal-container" : undefined, children: children })] }));
+}
+//# sourceMappingURL=modal-provider.js.map

package/dist/web/components/modal-provider.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"modal-provider.js","sourceRoot":"","sources":["../../../src/web/components/modal-provider.tsx"],"names":[],"mappings":";AAAA,OAAO,EAAkB,SAAS,EAAE,oBAAoB,EAAE,MAAM,OAAO,CAAC;AACxE,OAAO,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AAEpD,MAAM,WAAW,GAAG;;;;;;;;;;;;;;;;;CAiBnB,CAAC;AAEF,MAAM,UAAU,aAAa,CAAC,EAAE,QAAQ,EAA2B;IACjE,MAAM,OAAO,GAAG,aAAa,CAAC,WAAW,EAAE,CAAC;IAE5C,MAAM,EAAE,IAAI,EAAE,GAAG,oBAAoB,CACnC,OAAO,CAAC,mBAAmB,CAAC,SAAS,CAAC,CAAC,SAAS,EAChD,OAAO,CAAC,mBAAmB,CAAC,SAAS,CAAC,CAAC,WAAW,CACnD,CAAC;IACF,MAAM,MAAM,GAAG,IAAI,KAAK,OAAO,CAAC;IAEhC,MAAM,mBAAmB,GAAG,CAAC,CAAmB,EAAE,EAAE;QAClD,IAAI,CAAC,CAAC,MAAM,KAAK,CAAC,CAAC,aAAa,EAAE,CAAC;YACjC,OAAO,CAAC,UAAU,EAAE,CAAC;QACvB,CAAC;IACH,CAAC,CAAC;IAEF,SAAS,CAAC,GAAG,EAAE;QACb,IAAI,CAAC,MAAM,EAAE,CAAC;YACZ,OAAO;QACT,CAAC;QACD,MAAM,OAAO,GAAG,CAAC,CAAgB,EAAE,EAAE;YACnC,IAAI,CAAC,CAAC,GAAG,KAAK,QAAQ,EAAE,CAAC;gBACvB,OAAO,CAAC,UAAU,EAAE,CAAC;YACvB,CAAC;QACH,CAAC,CAAC;QACF,QAAQ,CAAC,gBAAgB,CAAC,SAAS,EAAE,OAAO,CAAC,CAAC;QAC9C,OAAO,GAAG,EAAE,CAAC,QAAQ,CAAC,mBAAmB,CAAC,SAAS,EAAE,OAAO,CAAC,CAAC;IAChE,CAAC,EAAE,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;IAEtB,OAAO,CACL,8BACE,0BAAQ,WAAW,GAAS,EAC3B,MAAM,IAAI,CAET,cACE,IAAI,EAAC,QAAQ,EACb,SAAS,EAAC,mBAAmB,EAC7B,OAAO,EAAE,mBAAmB,GAC5B,CACH,EACD,cAAK,SAAS,EAAE,MAAM,CAAC,CAAC,CAAC,oBAAoB,CAAC,CAAC,CAAC,SAAS,YACtD,QAAQ,GACL,IACL,CACJ,CAAC;AACJ,CAAC","sourcesContent":["import { type ReactNode, useEffect, useSyncExternalStore } from \"react\";\nimport { McpAppAdaptor } from \"../bridges/index.js\";\n\nconst modalStyles = `\n.sb-modal-backdrop {\n  position: fixed;\n  inset: 0;\n  background: rgba(0, 0, 0, 0.5);\n  z-index: 9998;\n}\n.sb-modal-container {\n  border-radius: 12px;\n  position: fixed;\n  inset: 0;\n  margin: auto;\n  width: fit-content;\n  height: fit-content;\n  background: white;\n  z-index: 9999;\n}\n`;\n\nexport function ModalProvider({ children }: { children: ReactNode }) {\n  const adaptor = McpAppAdaptor.getInstance();\n\n  const { mode } = useSyncExternalStore(\n    adaptor.getHostContextStore(\"display\").subscribe,\n    adaptor.getHostContextStore(\"display\").getSnapshot,\n  );\n  const isOpen = mode === \"modal\";\n\n  const handleBackdropClick = (e: React.MouseEvent) => {\n    if (e.target === e.currentTarget) {\n      adaptor.closeModal();\n    }\n  };\n\n  useEffect(() => {\n    if (!isOpen) {\n      return;\n    }\n    const handler = (e: KeyboardEvent) => {\n      if (e.key === \"Escape\") {\n        adaptor.closeModal();\n      }\n    };\n    document.addEventListener(\"keydown\", handler);\n    return () => document.removeEventListener(\"keydown\", handler);\n  }, [isOpen, adaptor]);\n\n  return (\n    <>\n      <style>{modalStyles}</style>\n      {isOpen && (\n        // biome-ignore lint/a11y/useKeyWithClickEvents: backdrop isn't focusable\n        <div\n          role=\"dialog\"\n          className=\"sb-modal-backdrop\"\n          onClick={handleBackdropClick}\n        />\n      )}\n      <div className={isOpen ? \"sb-modal-container\" : undefined}>\n        {children}\n      </div>\n    </>\n  );\n}\n"]}

package/dist/web/create-store.d.ts

@@ -0,0 +1,29 @@
+import { type StateCreator } from "zustand";
+import type { UnknownObject } from "./types.js";
+/**
+ * Create a Zustand store that is bidirectionally synced with the host's
+ * `viewState`. Local store updates persist to the host, and external host
+ * updates rehydrate the store — making the store the single source of truth
+ * for state that should survive view remounts.
+ *
+ * Use this when you outgrow {@link useViewState} and want first-class Zustand
+ * ergonomics (selectors, actions, middleware). Otherwise prefer `useViewState`.
+ *
+ * Skybridge-internal context fields (see {@link DataLLM}) are filtered out
+ * automatically before reaching your store.
+ *
+ * @typeParam State - Shape of the store's state. Must be a plain object.
+ *
+ * @example
+ * ```ts
+ * export const useStore = createStore<{ count: number; inc: () => void }>(
+ *   (set) => ({
+ *     count: 0,
+ *     inc: () => set((s) => ({ count: s.count + 1 })),
+ *   }),
+ * );
+ * ```
+ *
+ * @see https://docs.skybridge.tech/api-reference/create-store
+ */
+export declare function createStore<State extends UnknownObject>(storeCreator: StateCreator<State, [], [], State>, defaultState?: State | (() => State)): import("zustand").UseBoundStore<import("zustand").StoreApi<State>>;

package/dist/web/create-store.js

@@ -0,0 +1,64 @@
+import { dequal } from "dequal/lite";
+import { create } from "zustand";
+import { getAdaptor } from "./bridges/index.js";
+import { filterViewContext, getInitialState, injectViewContext, serializeState, } from "./helpers/state.js";
+/**
+ * Create a Zustand store that is bidirectionally synced with the host's
+ * `viewState`. Local store updates persist to the host, and external host
+ * updates rehydrate the store — making the store the single source of truth
+ * for state that should survive view remounts.
+ *
+ * Use this when you outgrow {@link useViewState} and want first-class Zustand
+ * ergonomics (selectors, actions, middleware). Otherwise prefer `useViewState`.
+ *
+ * Skybridge-internal context fields (see {@link DataLLM}) are filtered out
+ * automatically before reaching your store.
+ *
+ * @typeParam State - Shape of the store's state. Must be a plain object.
+ *
+ * @example
+ * ```ts
+ * export const useStore = createStore<{ count: number; inc: () => void }>(
+ *   (set) => ({
+ *     count: 0,
+ *     inc: () => set((s) => ({ count: s.count + 1 })),
+ *   }),
+ * );
+ * ```
+ *
+ * @see https://docs.skybridge.tech/api-reference/create-store
+ */
+export function createStore(storeCreator, defaultState) {
+    const initialState = getInitialState(defaultState);
+    const store = create()((...args) => {
+        const baseStore = storeCreator(...args);
+        if (initialState !== null) {
+            return { ...baseStore, ...initialState };
+        }
+        return baseStore;
+    });
+    // Bidirectional sync between the Zustand store and the adaptor's viewState.
+    // Store changes persist to the host; external viewState changes rehydrate the store.
+    store.subscribe((state) => {
+        const serializedState = serializeState(state);
+        if (serializedState !== null && serializedState !== undefined) {
+            const stateToPersist = injectViewContext(serializedState);
+            if (stateToPersist !== null) {
+                getAdaptor().setViewState(stateToPersist);
+            }
+        }
+    });
+    const viewStateStore = getAdaptor().getHostContextStore("viewState");
+    viewStateStore.subscribe(() => {
+        const externalState = viewStateStore.getSnapshot();
+        if (externalState !== null) {
+            const filtered = filterViewContext(externalState);
+            const current = serializeState(store.getState());
+            if (!dequal(filtered, current)) {
+                store.setState(filtered);
+            }
+        }
+    });
+    return store;
+}
+//# sourceMappingURL=create-store.js.map

package/dist/web/create-store.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"create-store.js","sourceRoot":"","sources":["../../src/web/create-store.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AACrC,OAAO,EAAE,MAAM,EAAqB,MAAM,SAAS,CAAC;AACpD,OAAO,EAAE,UAAU,EAAE,MAAM,oBAAoB,CAAC;AAChD,OAAO,EACL,iBAAiB,EACjB,eAAe,EACf,iBAAiB,EACjB,cAAc,GACf,MAAM,oBAAoB,CAAC;AAG5B;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,MAAM,UAAU,WAAW,CACzB,YAAgD,EAChD,YAAoC;IAEpC,MAAM,YAAY,GAAG,eAAe,CAAC,YAAY,CAAC,CAAC;IAEnD,MAAM,KAAK,GAAG,MAAM,EAAS,CAC3B,CAAC,GAAG,IAAoD,EAAE,EAAE;QAC1D,MAAM,SAAS,GAAG,YAAY,CAAC,GAAG,IAAI,CAAC,CAAC;QAExC,IAAI,YAAY,KAAK,IAAI,EAAE,CAAC;YAC1B,OAAO,EAAE,GAAG,SAAS,EAAE,GAAG,YAAY,EAAE,CAAC;QAC3C,CAAC;QAED,OAAO,SAAS,CAAC;IACnB,CAAC,CACF,CAAC;IAEF,4EAA4E;IAC5E,qFAAqF;IACrF,KAAK,CAAC,SAAS,CAAC,CAAC,KAAY,EAAE,EAAE;QAC/B,MAAM,eAAe,GAAG,cAAc,CAAC,KAAK,CAAC,CAAC;QAC9C,IAAI,eAAe,KAAK,IAAI,IAAI,eAAe,KAAK,SAAS,EAAE,CAAC;YAC9D,MAAM,cAAc,GAAG,iBAAiB,CAAC,eAAwB,CAAC,CAAC;YACnE,IAAI,cAAc,KAAK,IAAI,EAAE,CAAC;gBAC5B,UAAU,EAAE,CAAC,YAAY,CAAC,cAAc,CAAC,CAAC;YAC5C,CAAC;QACH,CAAC;IACH,CAAC,CAAC,CAAC;IAEH,MAAM,cAAc,GAAG,UAAU,EAAE,CAAC,mBAAmB,CAAC,WAAW,CAAC,CAAC;IACrE,cAAc,CAAC,SAAS,CAAC,GAAG,EAAE;QAC5B,MAAM,aAAa,GAAG,cAAc,CAAC,WAAW,EAAE,CAAC;QACnD,IAAI,aAAa,KAAK,IAAI,EAAE,CAAC;YAC3B,MAAM,QAAQ,GAAG,iBAAiB,CAAC,aAAa,CAAU,CAAC;YAC3D,MAAM,OAAO,GAAG,cAAc,CAAC,KAAK,CAAC,QAAQ,EAAE,CAAU,CAAC;YAC1D,IAAI,CAAC,MAAM,CAAC,QAAQ,EAAE,OAAO,CAAC,EAAE,CAAC;gBAC/B,KAAK,CAAC,QAAQ,CAAC,QAAQ,CAAC,CAAC;YAC3B,CAAC;QACH,CAAC;IACH,CAAC,CAAC,CAAC;IAEH,OAAO,KAAK,CAAC;AACf,CAAC","sourcesContent":["import { dequal } from \"dequal/lite\";\nimport { create, type StateCreator } from \"zustand\";\nimport { getAdaptor } from \"./bridges/index.js\";\nimport {\n  filterViewContext,\n  getInitialState,\n  injectViewContext,\n  serializeState,\n} from \"./helpers/state.js\";\nimport type { UnknownObject } from \"./types.js\";\n\n/**\n * Create a Zustand store that is bidirectionally synced with the host's\n * `viewState`. Local store updates persist to the host, and external host\n * updates rehydrate the store — making the store the single source of truth\n * for state that should survive view remounts.\n *\n * Use this when you outgrow {@link useViewState} and want first-class Zustand\n * ergonomics (selectors, actions, middleware). Otherwise prefer `useViewState`.\n *\n * Skybridge-internal context fields (see {@link DataLLM}) are filtered out\n * automatically before reaching your store.\n *\n * @typeParam State - Shape of the store's state. Must be a plain object.\n *\n * @example\n * ```ts\n * export const useStore = createStore<{ count: number; inc: () => void }>(\n *   (set) => ({\n *     count: 0,\n *     inc: () => set((s) => ({ count: s.count + 1 })),\n *   }),\n * );\n * ```\n *\n * @see https://docs.skybridge.tech/api-reference/create-store\n */\nexport function createStore<State extends UnknownObject>(\n  storeCreator: StateCreator<State, [], [], State>,\n  defaultState?: State | (() => State),\n) {\n  const initialState = getInitialState(defaultState);\n\n  const store = create<State>()(\n    (...args: Parameters<StateCreator<State, [], [], State>>) => {\n      const baseStore = storeCreator(...args);\n\n      if (initialState !== null) {\n        return { ...baseStore, ...initialState };\n      }\n\n      return baseStore;\n    },\n  );\n\n  // Bidirectional sync between the Zustand store and the adaptor's viewState.\n  // Store changes persist to the host; external viewState changes rehydrate the store.\n  store.subscribe((state: State) => {\n    const serializedState = serializeState(state);\n    if (serializedState !== null && serializedState !== undefined) {\n      const stateToPersist = injectViewContext(serializedState as State);\n      if (stateToPersist !== null) {\n        getAdaptor().setViewState(stateToPersist);\n      }\n    }\n  });\n\n  const viewStateStore = getAdaptor().getHostContextStore(\"viewState\");\n  viewStateStore.subscribe(() => {\n    const externalState = viewStateStore.getSnapshot();\n    if (externalState !== null) {\n      const filtered = filterViewContext(externalState) as State;\n      const current = serializeState(store.getState()) as State;\n      if (!dequal(filtered, current)) {\n        store.setState(filtered);\n      }\n    }\n  });\n\n  return store;\n}\n"]}

package/dist/web/create-store.test.js

@@ -0,0 +1,129 @@
+import { cleanup } from "@testing-library/react";
+import { afterEach, beforeEach, describe, expect, it, vi, } from "vitest";
+import { McpAppAdaptor } from "./bridges/mcp-app/adaptor.js";
+import { McpAppBridge } from "./bridges/mcp-app/bridge.js";
+import { createStore } from "./create-store.js";
+import { VIEW_CONTEXT_KEY } from "./data-llm.js";
+import { getMcpAppHostPostMessageMock, MockResizeObserver, } from "./hooks/test/utils.js";
+describe("createStore", () => {
+    afterEach(() => {
+        vi.unstubAllGlobals();
+        vi.resetAllMocks();
+    });
+    describe("apps-sdk mode", () => {
+        let OpenaiMock;
+        beforeEach(() => {
+            OpenaiMock = {
+                widgetState: null,
+                setWidgetState: vi.fn().mockResolvedValue(undefined),
+            };
+            vi.stubGlobal("openai", OpenaiMock);
+            vi.stubGlobal("skybridge", { hostType: "apps-sdk" });
+        });
+        it("should create a store without default state", () => {
+            const storeCreator = () => ({
+                count: 0,
+            });
+            const store = createStore(storeCreator);
+            expect(store.getState()).toEqual({ count: 0 });
+        });
+        it("should create a store with default state", () => {
+            const storeCreator = () => ({
+                count: 0,
+                name: "initial",
+            });
+            const defaultState = { count: 5, name: "default" };
+            const store = createStore(storeCreator, defaultState);
+            expect(store.getState()).toEqual({ count: 5, name: "default" });
+        });
+        it("should initialize from window.openai.widgetState when available", () => {
+            const storeCreator = () => ({
+                count: 0,
+                name: "initial",
+            });
+            const windowState = { count: 20, name: "window" };
+            OpenaiMock.widgetState = { modelContent: windowState };
+            const store = createStore(storeCreator);
+            expect(store.getState()).toEqual({ count: 20, name: "window" });
+        });
+        it("should persist state changes to window.openai.setWidgetState", async () => {
+            const storeCreator = (set) => ({
+                count: 0,
+                increment: () => set((state) => ({ count: state.count + 1 })),
+            });
+            const store = createStore(storeCreator);
+            store.getState().increment();
+            await vi.waitFor(() => {
+                expect(OpenaiMock.setWidgetState).toHaveBeenCalled();
+            });
+            const callArgs = OpenaiMock.setWidgetState.mock.calls[0]?.[0];
+            expect(callArgs).toEqual({
+                modelContent: { count: 1 },
+                privateContent: {},
+            });
+        });
+        it("should filter view context from initial state", () => {
+            const storeCreator = () => ({
+                count: 0,
+            });
+            const windowState = {
+                count: 5,
+                [VIEW_CONTEXT_KEY]: "context-value",
+            };
+            OpenaiMock.widgetState = { modelContent: windowState };
+            const store = createStore(storeCreator);
+            expect(store.getState()).toEqual({ count: 5 });
+            expect(store.getState()[VIEW_CONTEXT_KEY]).toBeUndefined();
+        });
+    });
+    describe("mcp-app mode", () => {
+        beforeEach(() => {
+            vi.stubGlobal("skybridge", { hostType: "mcp-app" });
+            vi.stubGlobal("ResizeObserver", MockResizeObserver);
+        });
+        afterEach(async () => {
+            cleanup();
+            McpAppBridge.resetInstance();
+            McpAppAdaptor.resetInstance();
+        });
+        it("should initialize with null viewState", () => {
+            const adaptor = McpAppAdaptor.getInstance();
+            const viewState = adaptor.getHostContextStore("viewState").getSnapshot();
+            expect(viewState).toBeNull();
+        });
+        it("should create a store with default state when no persisted state exists", () => {
+            const storeCreator = () => ({
+                count: 0,
+            });
+            const store = createStore(storeCreator);
+            expect(store.getState()).toEqual({ count: 0 });
+        });
+        it("should update in-memory state via setViewState", async () => {
+            const adaptor = McpAppAdaptor.getInstance();
+            vi.spyOn(adaptor, "setViewState").mockResolvedValue(undefined);
+            const storeCreator = (set) => ({
+                count: 0,
+                increment: () => set((state) => ({ count: state.count + 1 })),
+            });
+            const store = createStore(storeCreator);
+            store.getState().increment();
+            await vi.waitFor(() => {
+                expect(adaptor.setViewState).toHaveBeenCalledWith({ count: 1 });
+            });
+        });
+        it("should notify listeners when view state changes", async () => {
+            const postMessageMock = getMcpAppHostPostMessageMock();
+            vi.stubGlobal("parent", { postMessage: postMessageMock });
+            const adaptor = McpAppAdaptor.getInstance();
+            const listener = vi.fn();
+            adaptor.getHostContextStore("viewState").subscribe(listener);
+            await adaptor.setViewState({ count: 42 });
+            expect(postMessageMock).toHaveBeenCalledWith(expect.objectContaining({ method: "ui/update-model-context" }), "*");
+            expect(listener).toHaveBeenCalled();
+            expect(adaptor.getHostContextStore("viewState").getSnapshot()).toEqual({
+                count: 42,
+            });
+        });
+    });
+});
+//# sourceMappingURL=create-store.test.js.map

package/dist/web/create-store.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"create-store.test.js","sourceRoot":"","sources":["../../src/web/create-store.test.ts"],"names":[],"mappings":"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","sourcesContent":["import { cleanup } from \"@testing-library/react\";\nimport {\n  afterEach,\n  beforeEach,\n  describe,\n  expect,\n  it,\n  type Mock,\n  vi,\n} from \"vitest\";\nimport type { StateCreator } from \"zustand\";\nimport { McpAppAdaptor } from \"./bridges/mcp-app/adaptor.js\";\nimport { McpAppBridge } from \"./bridges/mcp-app/bridge.js\";\nimport { createStore } from \"./create-store.js\";\nimport { VIEW_CONTEXT_KEY } from \"./data-llm.js\";\nimport {\n  getMcpAppHostPostMessageMock,\n  MockResizeObserver,\n} from \"./hooks/test/utils.js\";\n\ndescribe(\"createStore\", () => {\n  afterEach(() => {\n    vi.unstubAllGlobals();\n    vi.resetAllMocks();\n  });\n\n  describe(\"apps-sdk mode\", () => {\n    let OpenaiMock: {\n      widgetState: unknown;\n      setWidgetState: Mock;\n    };\n\n    beforeEach(() => {\n      OpenaiMock = {\n        widgetState: null,\n        setWidgetState: vi.fn().mockResolvedValue(undefined),\n      };\n      vi.stubGlobal(\"openai\", OpenaiMock);\n      vi.stubGlobal(\"skybridge\", { hostType: \"apps-sdk\" });\n    });\n\n    it(\"should create a store without default state\", () => {\n      type TestState = { count: number };\n      const storeCreator: StateCreator<TestState, [], [], TestState> = () => ({\n        count: 0,\n      });\n\n      const store = createStore(storeCreator);\n\n      expect(store.getState()).toEqual({ count: 0 });\n    });\n\n    it(\"should create a store with default state\", () => {\n      type TestState = { count: number; name: string };\n      const storeCreator: StateCreator<TestState, [], [], TestState> = () => ({\n        count: 0,\n        name: \"initial\",\n      });\n      const defaultState = { count: 5, name: \"default\" };\n\n      const store = createStore(storeCreator, defaultState);\n\n      expect(store.getState()).toEqual({ count: 5, name: \"default\" });\n    });\n\n    it(\"should initialize from window.openai.widgetState when available\", () => {\n      type TestState = { count: number; name: string };\n      const storeCreator: StateCreator<TestState, [], [], TestState> = () => ({\n        count: 0,\n        name: \"initial\",\n      });\n      const windowState = { count: 20, name: \"window\" };\n      OpenaiMock.widgetState = { modelContent: windowState };\n\n      const store = createStore(storeCreator);\n\n      expect(store.getState()).toEqual({ count: 20, name: \"window\" });\n    });\n\n    it(\"should persist state changes to window.openai.setWidgetState\", async () => {\n      type TestState = { count: number; increment: () => void };\n      const storeCreator: StateCreator<TestState, [], [], TestState> = (\n        set,\n      ) => ({\n        count: 0,\n        increment: () => set((state) => ({ count: state.count + 1 })),\n      });\n\n      const store = createStore(storeCreator);\n      store.getState().increment();\n\n      await vi.waitFor(() => {\n        expect(OpenaiMock.setWidgetState).toHaveBeenCalled();\n      });\n\n      const callArgs = OpenaiMock.setWidgetState.mock.calls[0]?.[0];\n      expect(callArgs).toEqual({\n        modelContent: { count: 1 },\n        privateContent: {},\n      });\n    });\n\n    it(\"should filter view context from initial state\", () => {\n      type TestState = { count: number };\n      const storeCreator: StateCreator<TestState, [], [], TestState> = () => ({\n        count: 0,\n      });\n      const windowState = {\n        count: 5,\n        [VIEW_CONTEXT_KEY]: \"context-value\",\n      };\n      OpenaiMock.widgetState = { modelContent: windowState };\n\n      const store = createStore(storeCreator);\n\n      expect(store.getState()).toEqual({ count: 5 });\n      expect(\n        (store.getState() as Record<string, unknown>)[VIEW_CONTEXT_KEY],\n      ).toBeUndefined();\n    });\n  });\n\n  describe(\"mcp-app mode\", () => {\n    beforeEach(() => {\n      vi.stubGlobal(\"skybridge\", { hostType: \"mcp-app\" });\n      vi.stubGlobal(\"ResizeObserver\", MockResizeObserver);\n    });\n\n    afterEach(async () => {\n      cleanup();\n      McpAppBridge.resetInstance();\n      McpAppAdaptor.resetInstance();\n    });\n\n    it(\"should initialize with null viewState\", () => {\n      const adaptor = McpAppAdaptor.getInstance();\n      const viewState = adaptor.getHostContextStore(\"viewState\").getSnapshot();\n\n      expect(viewState).toBeNull();\n    });\n\n    it(\"should create a store with default state when no persisted state exists\", () => {\n      type TestState = { count: number };\n      const storeCreator: StateCreator<TestState, [], [], TestState> = () => ({\n        count: 0,\n      });\n\n      const store = createStore(storeCreator);\n\n      expect(store.getState()).toEqual({ count: 0 });\n    });\n\n    it(\"should update in-memory state via setViewState\", async () => {\n      const adaptor = McpAppAdaptor.getInstance();\n      vi.spyOn(adaptor, \"setViewState\").mockResolvedValue(undefined);\n\n      type TestState = { count: number; increment: () => void };\n      const storeCreator: StateCreator<TestState, [], [], TestState> = (\n        set,\n      ) => ({\n        count: 0,\n        increment: () => set((state) => ({ count: state.count + 1 })),\n      });\n\n      const store = createStore(storeCreator);\n      store.getState().increment();\n\n      await vi.waitFor(() => {\n        expect(adaptor.setViewState).toHaveBeenCalledWith({ count: 1 });\n      });\n    });\n\n    it(\"should notify listeners when view state changes\", async () => {\n      const postMessageMock = getMcpAppHostPostMessageMock();\n      vi.stubGlobal(\"parent\", { postMessage: postMessageMock });\n\n      const adaptor = McpAppAdaptor.getInstance();\n      const listener = vi.fn();\n\n      adaptor.getHostContextStore(\"viewState\").subscribe(listener);\n      await adaptor.setViewState({ count: 42 });\n\n      expect(postMessageMock).toHaveBeenCalledWith(\n        expect.objectContaining({ method: \"ui/update-model-context\" }),\n        \"*\",\n      );\n      expect(listener).toHaveBeenCalled();\n      expect(adaptor.getHostContextStore(\"viewState\").getSnapshot()).toEqual({\n        count: 42,\n      });\n    });\n  });\n});\n"]}

package/dist/web/data-llm.d.ts

@@ -0,0 +1,47 @@
+import { type ReactNode } from "react";
+/** Text content surfaced to the model by a {@link DataLLM} component. */
+export type DataLLMContent = string;
+/**
+ * A node in the {@link DataLLM} tree. Nested `<DataLLM>` elements form a
+ * hierarchy that is serialized as an indented bullet list for the model.
+ */
+export interface DataLLMNode {
+    id: string;
+    parentId: string | null;
+    content: string | null;
+}
+/**
+ * Key under which the serialized {@link DataLLM} tree is persisted on the
+ * host's `viewState`. The host exposes the value to the model on subsequent
+ * turns.
+ */
+export declare const VIEW_CONTEXT_KEY: "__view_context";
+interface DataLLMProps {
+    content: DataLLMContent | null | undefined;
+    children?: ReactNode;
+}
+/**
+ * Surface in-view content to the LLM so it can reason about what the user is
+ * seeing without an extra tool call.
+ *
+ * Each `<DataLLM>` registers `content` as a node in a tree (parented by any
+ * enclosing `<DataLLM>`). The flattened tree is serialized as an indented
+ * bullet list and persisted on the host's `viewState` under
+ * {@link VIEW_CONTEXT_KEY}; the host then surfaces it to the model as part of
+ * the next turn's context.
+ *
+ * Pass `null`/`undefined` for `content` to register only as a structural
+ * parent (useful for grouping).
+ *
+ * @example
+ * ```tsx
+ * <DataLLM content="Active filters">
+ *   <DataLLM content={`Sort: ${sort}`} />
+ *   <DataLLM content={`Page: ${page}`} />
+ * </DataLLM>
+ * ```
+ *
+ * @see https://docs.skybridge.tech/api-reference/data-llm
+ */
+export declare function DataLLM({ content, children }: DataLLMProps): import("react/jsx-runtime").JSX.Element;
+export {};

package/dist/{src/web → web}/data-llm.js

@@ -1,6 +1,12 @@
 import { jsx as _jsx } from "react/jsx-runtime";
 import { createContext, useContext, useEffect, useId, } from "react";
-export const WIDGET_CONTEXT_KEY = "__widget_context";
+import { getAdaptor } from "./bridges/index.js";
+/**
+ * Key under which the serialized {@link DataLLM} tree is persisted on the
+ * host's `viewState`. The host exposes the value to the model on subsequent
+ * turns.
+ */
+export const VIEW_CONTEXT_KEY = "__view_context";
 const nodes = new Map();
 function setNode(node) {
     nodes.set(node.id, node);
@@ -12,12 +18,36 @@ function removeNode(id) {
 }
 function onChange() {
     const description = getLLMDescriptionString();
-    window.openai.setWidgetState({
-        ...window.openai.widgetState,
-        [WIDGET_CONTEXT_KEY]: description,
-    });
+    const adaptor = getAdaptor();
+    adaptor.setViewState((prevState) => ({
+        ...prevState,
+        [VIEW_CONTEXT_KEY]: description,
+    }));
 }
 const ParentIdContext = createContext(null);
+/**
+ * Surface in-view content to the LLM so it can reason about what the user is
+ * seeing without an extra tool call.
+ *
+ * Each `<DataLLM>` registers `content` as a node in a tree (parented by any
+ * enclosing `<DataLLM>`). The flattened tree is serialized as an indented
+ * bullet list and persisted on the host's `viewState` under
+ * {@link VIEW_CONTEXT_KEY}; the host then surfaces it to the model as part of
+ * the next turn's context.
+ *
+ * Pass `null`/`undefined` for `content` to register only as a structural
+ * parent (useful for grouping).
+ *
+ * @example
+ * ```tsx
+ * <DataLLM content="Active filters">
+ *   <DataLLM content={`Sort: ${sort}`} />
+ *   <DataLLM content={`Page: ${page}`} />
+ * </DataLLM>
+ * ```
+ *
+ * @see https://docs.skybridge.tech/api-reference/data-llm
+ */
 export function DataLLM({ content, children }) {
     const parentId = useContext(ParentIdContext);
     const id = useId();