@miragon/mcp-toolkit-ui 0.10.1

package/dist/app/builder/labels.d.ts

@@ -0,0 +1,78 @@
+/**
+ * Shared label contract for the visual LayoutBuilder.
+ *
+ * Extracted from `layout-builder.tsx` so the presentational sub-components
+ * (Toolbar, PipelineStrip, Workspace, CatalogueSheet, SaveDialog, PreviewPane)
+ * can depend on the labels without importing the orchestrating container —
+ * which would create an import cycle. React-free and `mcp-use`-free.
+ */
+export interface LayoutBuilderLabels {
+    title?: string;
+    builderBadge?: string;
+    previewBadge?: string;
+    catalogue?: string;
+    save?: string;
+    done?: string;
+    viewLayoutTab?: string;
+    viewPipelineTab?: string;
+    viewPreviewTab?: string;
+    saveDialogTitle?: string;
+    saveDialogDescription?: string;
+    saveNameLabel?: string;
+    saveDescriptionLabel?: string;
+    saveConfirm?: string;
+    cancel?: string;
+    pipelineHeader?: string;
+    keysHeader?: string;
+    stepsHeader?: string;
+    keyName?: string;
+    keyValue?: string;
+    stepContextId?: string;
+    stepPickerLabel?: string;
+    addKey?: string;
+    addStep?: string;
+    emptyKeys?: string;
+    emptySteps?: string;
+    statusUpToDate?: string;
+    statusPending?: string;
+    statusRefreshing?: string;
+    paletteHeader?: string;
+    paletteEmpty?: string;
+    canvasEmpty?: string;
+    canvasDropHint?: string;
+    addRow?: string;
+    addTab?: string;
+    removeRow?: string;
+    renameTab?: string;
+    removeTab?: string;
+    tabsLabel?: string;
+    catalogueDescription?: string;
+    catalogueKeys?: string;
+    catalogueSteps?: string;
+    catalogueUnreachable?: string;
+    catalogueUnreachableEmpty?: string;
+    catalogueProducedBy?: string;
+    catalogueConsumedBy?: string;
+    catalogueNeedsKeys?: string;
+    cataloguePickKey?: string;
+    catalogueAddProducingStep?: string;
+    catalogueLive?: string;
+    catalogueMissing?: string;
+    /** Banner shown when the catalogue fetch fails (prefixes the reason). */
+    catalogueError?: string;
+    /** Heading for the pipeline-validation warning banner. */
+    validationWarning?: string;
+    /** Inline message when a save fails (prefixes the reason). */
+    saveError?: string;
+    /** Inline message when a tab rename is rejected (duplicate label). */
+    renameDuplicate?: string;
+}
+export declare const DEFAULT_LABELS: Required<LayoutBuilderLabels>;
+/**
+ * MIME type used to carry a widget id across the palette → canvas drag.
+ * Shared between the palette items and the canvas drop targets.
+ */
+export declare const WIDGET_DRAG_MIME = "application/x-mcp-widget-id";
+/** Refresh status for the auto-apply chip and the pipeline strip. */
+export type RefreshStatus = "idle" | "pending" | "refreshing";
+//# sourceMappingURL=labels.d.ts.map

package/dist/app/builder/labels.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"labels.d.ts","sourceRoot":"","sources":["../../../src/app/builder/labels.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,MAAM,WAAW,mBAAmB;IAClC,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,YAAY,CAAC,EAAE,MAAM,CAAA;IACrB,YAAY,CAAC,EAAE,MAAM,CAAA;IACrB,SAAS,CAAC,EAAE,MAAM,CAAA;IAClB,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,aAAa,CAAC,EAAE,MAAM,CAAA;IACtB,eAAe,CAAC,EAAE,MAAM,CAAA;IACxB,cAAc,CAAC,EAAE,MAAM,CAAA;IACvB,eAAe,CAAC,EAAE,MAAM,CAAA;IACxB,qBAAqB,CAAC,EAAE,MAAM,CAAA;IAC9B,aAAa,CAAC,EAAE,MAAM,CAAA;IACtB,oBAAoB,CAAC,EAAE,MAAM,CAAA;IAC7B,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,cAAc,CAAC,EAAE,MAAM,CAAA;IACvB,UAAU,CAAC,EAAE,MAAM,CAAA;IACnB,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB,aAAa,CAAC,EAAE,MAAM,CAAA;IACtB,eAAe,CAAC,EAAE,MAAM,CAAA;IACxB,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB,SAAS,CAAC,EAAE,MAAM,CAAA;IAClB,UAAU,CAAC,EAAE,MAAM,CAAA;IACnB,cAAc,CAAC,EAAE,MAAM,CAAA;IACvB,aAAa,CAAC,EAAE,MAAM,CAAA;IACtB,gBAAgB,CAAC,EAAE,MAAM,CAAA;IACzB,aAAa,CAAC,EAAE,MAAM,CAAA;IACtB,YAAY,CAAC,EAAE,MAAM,CAAA;IACrB,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB,cAAc,CAAC,EAAE,MAAM,CAAA;IACvB,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,SAAS,CAAC,EAAE,MAAM,CAAA;IAClB,SAAS,CAAC,EAAE,MAAM,CAAA;IAClB,SAAS,CAAC,EAAE,MAAM,CAAA;IAClB,SAAS,CAAC,EAAE,MAAM,CAAA;IAClB,oBAAoB,CAAC,EAAE,MAAM,CAAA;IAC7B,aAAa,CAAC,EAAE,MAAM,CAAA;IACtB,cAAc,CAAC,EAAE,MAAM,CAAA;IACvB,oBAAoB,CAAC,EAAE,MAAM,CAAA;IAC7B,yBAAyB,CAAC,EAAE,MAAM,CAAA;IAClC,mBAAmB,CAAC,EAAE,MAAM,CAAA;IAC5B,mBAAmB,CAAC,EAAE,MAAM,CAAA;IAC5B,kBAAkB,CAAC,EAAE,MAAM,CAAA;IAC3B,gBAAgB,CAAC,EAAE,MAAM,CAAA;IACzB,yBAAyB,CAAC,EAAE,MAAM,CAAA;IAClC,aAAa,CAAC,EAAE,MAAM,CAAA;IACtB,gBAAgB,CAAC,EAAE,MAAM,CAAA;IACzB,yEAAyE;IACzE,cAAc,CAAC,EAAE,MAAM,CAAA;IACvB,0DAA0D;IAC1D,iBAAiB,CAAC,EAAE,MAAM,CAAA;IAC1B,8DAA8D;IAC9D,SAAS,CAAC,EAAE,MAAM,CAAA;IAClB,sEAAsE;IACtE,eAAe,CAAC,EAAE,MAAM,CAAA;CACzB;AAED,eAAO,MAAM,cAAc,EAAE,QAAQ,CAAC,mBAAmB,CA0DxD,CAAA;AAED;;;GAGG;AACH,eAAO,MAAM,gBAAgB,gCAAgC,CAAA;AAE7D,qEAAqE;AACrE,MAAM,MAAM,aAAa,GAAG,MAAM,GAAG,SAAS,GAAG,YAAY,CAAA"}

package/dist/app/builder/labels.js

@@ -0,0 +1,71 @@
+/**
+ * Shared label contract for the visual LayoutBuilder.
+ *
+ * Extracted from `layout-builder.tsx` so the presentational sub-components
+ * (Toolbar, PipelineStrip, Workspace, CatalogueSheet, SaveDialog, PreviewPane)
+ * can depend on the labels without importing the orchestrating container —
+ * which would create an import cycle. React-free and `mcp-use`-free.
+ */
+export const DEFAULT_LABELS = {
+    title: "View Builder",
+    builderBadge: "Builder",
+    previewBadge: "Preview",
+    catalogue: "Catalogue",
+    save: "Save",
+    done: "Done",
+    viewLayoutTab: "Layout",
+    viewPipelineTab: "Pipeline",
+    viewPreviewTab: "Preview",
+    saveDialogTitle: "Save dashboard",
+    saveDialogDescription: "Persists the current layout along with the keys and steps that populate it.",
+    saveNameLabel: "Name",
+    saveDescriptionLabel: "Description",
+    saveConfirm: "Save dashboard",
+    cancel: "Cancel",
+    pipelineHeader: "Pipeline",
+    keysHeader: "Keys",
+    stepsHeader: "Steps",
+    keyName: "key",
+    keyValue: 'value, "literal", true, {…}',
+    stepContextId: "ctx id",
+    stepPickerLabel: "pick a step",
+    addKey: "Add key",
+    addStep: "Add step",
+    emptyKeys: "No keys seeded.",
+    emptySteps: "No steps configured.",
+    statusUpToDate: "Up to date",
+    statusPending: "Applying soon…",
+    statusRefreshing: "Applying…",
+    paletteHeader: "Palette",
+    paletteEmpty: "No widgets reachable yet — seed a key or add a step.",
+    canvasEmpty: "Drag a widget here, or click one in the palette.",
+    canvasDropHint: "Drop to add",
+    addRow: "Add row",
+    addTab: "Add tab",
+    removeRow: "Remove row",
+    renameTab: "Rename tab",
+    removeTab: "Remove tab",
+    tabsLabel: "Tabs",
+    catalogueDescription: "Every key and widget the framework knows about, whether or not it's reachable right now.",
+    catalogueKeys: "Keys",
+    catalogueSteps: "Steps",
+    catalogueUnreachable: "Unreachable widgets",
+    catalogueUnreachableEmpty: "Every registered widget is reachable.",
+    catalogueProducedBy: "produced by",
+    catalogueConsumedBy: "consumed by",
+    catalogueNeedsKeys: "needs",
+    cataloguePickKey: "Add as key",
+    catalogueAddProducingStep: "Add producing step",
+    catalogueLive: "live",
+    catalogueMissing: "missing",
+    catalogueError: "Couldn't refresh the builder catalogue",
+    validationWarning: "This pipeline won't render as configured",
+    saveError: "Couldn't save",
+    renameDuplicate: "A tab with that name already exists.",
+};
+/**
+ * MIME type used to carry a widget id across the palette → canvas drag.
+ * Shared between the palette items and the canvas drop targets.
+ */
+export const WIDGET_DRAG_MIME = "application/x-mcp-widget-id";
+//# sourceMappingURL=labels.js.map

package/dist/app/builder/labels.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"labels.js","sourceRoot":"","sources":["../../../src/app/builder/labels.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAgEH,MAAM,CAAC,MAAM,cAAc,GAAkC;IAC3D,KAAK,EAAE,cAAc;IACrB,YAAY,EAAE,SAAS;IACvB,YAAY,EAAE,SAAS;IACvB,SAAS,EAAE,WAAW;IACtB,IAAI,EAAE,MAAM;IACZ,IAAI,EAAE,MAAM;IACZ,aAAa,EAAE,QAAQ;IACvB,eAAe,EAAE,UAAU;IAC3B,cAAc,EAAE,SAAS;IACzB,eAAe,EAAE,gBAAgB;IACjC,qBAAqB,EACnB,6EAA6E;IAC/E,aAAa,EAAE,MAAM;IACrB,oBAAoB,EAAE,aAAa;IACnC,WAAW,EAAE,gBAAgB;IAC7B,MAAM,EAAE,QAAQ;IAChB,cAAc,EAAE,UAAU;IAC1B,UAAU,EAAE,MAAM;IAClB,WAAW,EAAE,OAAO;IACpB,OAAO,EAAE,KAAK;IACd,QAAQ,EAAE,6BAA6B;IACvC,aAAa,EAAE,QAAQ;IACvB,eAAe,EAAE,aAAa;IAC9B,MAAM,EAAE,SAAS;IACjB,OAAO,EAAE,UAAU;IACnB,SAAS,EAAE,iBAAiB;IAC5B,UAAU,EAAE,sBAAsB;IAClC,cAAc,EAAE,YAAY;IAC5B,aAAa,EAAE,gBAAgB;IAC/B,gBAAgB,EAAE,WAAW;IAC7B,aAAa,EAAE,SAAS;IACxB,YAAY,EAAE,sDAAsD;IACpE,WAAW,EAAE,kDAAkD;IAC/D,cAAc,EAAE,aAAa;IAC7B,MAAM,EAAE,SAAS;IACjB,MAAM,EAAE,SAAS;IACjB,SAAS,EAAE,YAAY;IACvB,SAAS,EAAE,YAAY;IACvB,SAAS,EAAE,YAAY;IACvB,SAAS,EAAE,MAAM;IACjB,oBAAoB,EAClB,0FAA0F;IAC5F,aAAa,EAAE,MAAM;IACrB,cAAc,EAAE,OAAO;IACvB,oBAAoB,EAAE,qBAAqB;IAC3C,yBAAyB,EAAE,uCAAuC;IAClE,mBAAmB,EAAE,aAAa;IAClC,mBAAmB,EAAE,aAAa;IAClC,kBAAkB,EAAE,OAAO;IAC3B,gBAAgB,EAAE,YAAY;IAC9B,yBAAyB,EAAE,oBAAoB;IAC/C,aAAa,EAAE,MAAM;IACrB,gBAAgB,EAAE,SAAS;IAC3B,cAAc,EAAE,wCAAwC;IACxD,iBAAiB,EAAE,0CAA0C;IAC7D,SAAS,EAAE,eAAe;IAC1B,eAAe,EAAE,sCAAsC;CACxD,CAAA;AAED;;;GAGG;AACH,MAAM,CAAC,MAAM,gBAAgB,GAAG,6BAA6B,CAAA"}

package/dist/app/builder/status-chip.d.ts

@@ -0,0 +1,10 @@
+import type { LayoutBuilderLabels, RefreshStatus } from "./labels.js";
+/**
+ * Compact auto-apply status chip. Shared by the Toolbar and the
+ * PipelineStrip so both surfaces show the same refresh state.
+ */
+export declare function StatusChip({ status, L, }: {
+    status: RefreshStatus;
+    L: Required<LayoutBuilderLabels>;
+}): import("react").JSX.Element;
+//# sourceMappingURL=status-chip.d.ts.map

package/dist/app/builder/status-chip.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"status-chip.d.ts","sourceRoot":"","sources":["../../../src/app/builder/status-chip.tsx"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,mBAAmB,EAAE,aAAa,EAAE,MAAM,aAAa,CAAA;AAErE;;;GAGG;AACH,wBAAgB,UAAU,CAAC,EACzB,MAAM,EACN,CAAC,GACF,EAAE;IACD,MAAM,EAAE,aAAa,CAAA;IACrB,CAAC,EAAE,QAAQ,CAAC,mBAAmB,CAAC,CAAA;CACjC,+BAuBA"}

package/dist/app/builder/status-chip.js

@@ -0,0 +1,16 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { CircleDot, Loader2 } from "lucide-react";
+/**
+ * Compact auto-apply status chip. Shared by the Toolbar and the
+ * PipelineStrip so both surfaces show the same refresh state.
+ */
+export function StatusChip({ status, L, }) {
+    if (status === "idle") {
+        return (_jsxs("span", { className: "text-muted-foreground inline-flex items-center gap-1.5", children: [_jsx(CircleDot, { className: "size-3" }), L.statusUpToDate] }));
+    }
+    if (status === "pending") {
+        return (_jsxs("span", { className: "inline-flex items-center gap-1.5 text-amber-600 dark:text-amber-400", children: [_jsx("span", { className: "size-1.5 animate-pulse rounded-full bg-amber-500" }), L.statusPending] }));
+    }
+    return (_jsxs("span", { className: "text-primary inline-flex items-center gap-1.5", children: [_jsx(Loader2, { className: "size-3 animate-spin" }), L.statusRefreshing] }));
+}
+//# sourceMappingURL=status-chip.js.map

package/dist/app/builder/status-chip.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"status-chip.js","sourceRoot":"","sources":["../../../src/app/builder/status-chip.tsx"],"names":[],"mappings":";AAAA,OAAO,EAAE,SAAS,EAAE,OAAO,EAAE,MAAM,cAAc,CAAA;AAGjD;;;GAGG;AACH,MAAM,UAAU,UAAU,CAAC,EACzB,MAAM,EACN,CAAC,GAIF;IACC,IAAI,MAAM,KAAK,MAAM,EAAE,CAAC;QACtB,OAAO,CACL,gBAAM,SAAS,EAAC,wDAAwD,aACtE,KAAC,SAAS,IAAC,SAAS,EAAC,QAAQ,GAAG,EAC/B,CAAC,CAAC,cAAc,IACZ,CACR,CAAA;IACH,CAAC;IACD,IAAI,MAAM,KAAK,SAAS,EAAE,CAAC;QACzB,OAAO,CACL,gBAAM,SAAS,EAAC,qEAAqE,aACnF,eAAM,SAAS,EAAC,kDAAkD,GAAG,EACpE,CAAC,CAAC,aAAa,IACX,CACR,CAAA;IACH,CAAC;IACD,OAAO,CACL,gBAAM,SAAS,EAAC,+CAA+C,aAC7D,KAAC,OAAO,IAAC,SAAS,EAAC,qBAAqB,GAAG,EAC1C,CAAC,CAAC,gBAAgB,IACd,CACR,CAAA;AACH,CAAC"}

package/dist/app/host-bridge.d.ts

@@ -0,0 +1,211 @@
+import { type ReactNode } from "react";
+/**
+ * The host capabilities a hand-built widget needs, abstracted away from any one
+ * host runtime. A `HostBridge` is the single seam a portable widget talks to:
+ * write the widget against {@link useHostBridge} and it runs unchanged in our
+ * own `mcp-use` host, inside ChatGPT (OpenAI Apps SDK), or as a standalone web
+ * app driven directly by a `@modelcontextprotocol/sdk` client — only the
+ * surrounding adapter changes.
+ *
+ * This is deliberately the *minimum* a deterministic UI needs, not a mirror of
+ * any host's full surface. Each adapter maps these verbs onto its host and
+ * fails soft where the host cannot honour them (see the per-factory docs).
+ */
+export interface HostBridge {
+    /**
+     * Invoke an MCP tool on the connected server and resolve with its raw
+     * response (typically `{ structuredContent, content, … }`). Callers decode it
+     * with `parseToolResult`. Rejects if the call fails so a widget's own error
+     * state (TanStack Query, try/catch) can surface it.
+     */
+    callTool(name: string, args: Record<string, unknown>): Promise<unknown>;
+    /**
+     * Hand a natural-language prompt back to the conversation to drive a new model
+     * turn (navigate to another widget, ask the agent to analyse something). In
+     * hosts without a conversation (standalone web app) this is a no-op unless an
+     * `onFollowup` handler is supplied.
+     */
+    sendFollowup(prompt: string): void;
+    /**
+     * Ask the host to open a URL outside the (often sandboxed) widget frame.
+     * Falls back to `window.open` only where no host bridge mediates links.
+     */
+    openExternal(url: string): void;
+    /**
+     * The structured data this widget was rendered with, if the host pushed any
+     * (the tool result's `structuredContent` / `toolOutput`). Returns `null` when
+     * the host delivers data another way (e.g. props) or has none.
+     */
+    getWidgetData<T>(): T | null;
+    /**
+     * Persist a short text the model should see on the next turn (selection,
+     * filter, current view). Optional: not every host exposes model context, and
+     * a standalone web app has no model at all — callers must guard its absence.
+     */
+    setModelContext?(text: string): void;
+    /** The host's colour-scheme preference, when it reports one. */
+    theme?: "light" | "dark";
+}
+/**
+ * Provide an explicit {@link HostBridge} to a subtree. Wrap a portable widget in
+ * the adapter for the host it is running in — {@link createChatGptHostBridge},
+ * {@link createStandaloneHostBridge}, or {@link createMcpUseHostBridge} — and
+ * every `useHostBridge()` below resolves to it.
+ *
+ * Omitting the provider is supported: {@link useHostBridge} (and, for backward
+ * compatibility, `useHostActions`) then fall back to the `mcp-use`/react default
+ * bridge so existing widgets keep working without any wrapping.
+ */
+export declare function HostBridgeProvider({ bridge, children, }: {
+    bridge: HostBridge;
+    children: ReactNode;
+}): ReactNode;
+/**
+ * Read the explicit {@link HostBridge} from context, or `null` if no
+ * {@link HostBridgeProvider} is present. Adapters that want to *fall back* to the
+ * default `mcp-use` bridge (rather than throw) use this instead of
+ * {@link useHostBridge}.
+ */
+export declare function useHostBridgeOrNull(): HostBridge | null;
+/**
+ * The {@link HostBridge} for the current subtree. Resolution order:
+ *
+ * 1. An explicit bridge from the nearest {@link HostBridgeProvider}.
+ * 2. The default `mcp-use`/react bridge ({@link createMcpUseHostBridge}), so a
+ *    widget mounted in our own host needs no provider.
+ *
+ * The `mcp-use` hooks the default bridge wraps must run under an `mcp-use`
+ * provider/host context; outside one (e.g. a bare unit test render) wrap the
+ * widget in a `HostBridgeProvider` with a {@link createStandaloneHostBridge}
+ * instead. This hook never returns `null`: a portable widget can always assume a
+ * bridge exists.
+ */
+export declare function useHostBridge(): HostBridge;
+/**
+ * Build a {@link HostBridge} backed by `mcp-use`/react — the default for widgets
+ * running in the toolkit's own host. Wraps `useWidget()` (host actions,
+ * `toolOutput`, `theme`) and `useCallTool` so it preserves exactly the behaviour
+ * widgets had before the bridge abstraction:
+ *
+ * - `openExternal` routes through the host's `openExternal` and falls back to
+ *   `window.open` when no host bridge is wired (local dev preview) — mirroring
+ *   the original `useHostActions.openLink`.
+ * - `sendFollowup` routes through `sendFollowUpMessage` and swallows rejections
+ *   with a `console.warn`, as `useHostActions` did.
+ *
+ * Must be called inside an `mcp-use` host context (it calls `mcp-use` hooks).
+ * Use {@link createMcpUseHostBridge} for the standalone factory variant.
+ */
+export declare function useMcpUseHostBridge(): HostBridge;
+/**
+ * Factory form of {@link useMcpUseHostBridge} for symmetry with the other
+ * adapters. Because the `mcp-use` bridge is hook-driven (it reads live host
+ * context), the "factory" is really the hook itself — call it from a component.
+ *
+ * @example
+ * function MyWidget() {
+ *   const bridge = createMcpUseHostBridge() // === useMcpUseHostBridge()
+ *   // …or rely on useHostBridge()'s default and skip the provider entirely.
+ * }
+ */
+export declare const createMcpUseHostBridge: typeof useMcpUseHostBridge;
+/**
+ * Minimal structural view of the OpenAI Apps SDK `window.openai` object this
+ * adapter reads. Every field is optional: the real SDK shape varies across
+ * versions and host builds, so the adapter probes each method/field defensively
+ * and degrades to a no-op (with a `console.warn`) rather than assuming presence.
+ *
+ * Assumptions documented here (verify against the Apps SDK you target):
+ * - `callTool(name, args)` resolves with the tool response. Required for tool
+ *   calls; without it `callTool` rejects with a clear error.
+ * - `sendFollowUpMessage` is called with `{ prompt }` (older builds) — we also
+ *   accept a bare-string signature and try both shapes.
+ * - `openExternal` is called with `{ href }`.
+ * - `toolOutput` (preferred) or `toolResponseMetadata` carries the structured
+ *   widget data; `setWidgetState(state)` persists model-visible state.
+ * - `theme` is `"light"` | `"dark"`.
+ */
+export interface OpenAiAppsSdk {
+    callTool?: (name: string, args: Record<string, unknown>) => Promise<unknown>;
+    sendFollowUpMessage?: (arg: {
+        prompt: string;
+    } | string) => unknown;
+    sendFollowupMessage?: (arg: {
+        prompt: string;
+    } | string) => unknown;
+    openExternal?: (payload: {
+        href: string;
+    } | string) => unknown;
+    toolOutput?: unknown;
+    toolResponseMetadata?: unknown;
+    setWidgetState?: (state: Record<string, unknown>) => unknown;
+    theme?: unknown;
+}
+/**
+ * Build a {@link HostBridge} for the OpenAI Apps SDK (ChatGPT). Reads the host's
+ * `window.openai` object and maps the bridge verbs onto it **defensively** —
+ * every method is probed before use, and a missing one degrades to a logged
+ * no-op (or, for `callTool`, a rejected promise) instead of crashing the widget.
+ * This is what lets the *same* hand-built widget run in ChatGPT with no code
+ * change, even across Apps SDK versions whose surface drifts.
+ *
+ * Pass an explicit `sdk` to test the guards without a real `window.openai`
+ * (passing `null` exercises the fully-absent path). See {@link OpenAiAppsSdk}
+ * for the documented assumptions about the SDK shape.
+ */
+export declare function createChatGptHostBridge(sdk?: OpenAiAppsSdk | null): HostBridge;
+/** Options for {@link createStandaloneHostBridge}. */
+export interface StandaloneHostBridgeOptions {
+    /**
+     * The only required capability: how to call a tool on the server. In a
+     * standalone web app this typically wraps a `@modelcontextprotocol/sdk`
+     * `Client.callTool({ name, arguments })`, but any function with this shape
+     * works — that injection is the whole point: hand-built widgets render
+     * against *any* existing MCP server without the toolkit's host runtime.
+     */
+    callTool: (name: string, args: Record<string, unknown>) => Promise<unknown>;
+    /**
+     * Supply the structured data a widget reads via `getWidgetData()`. A static
+     * value, or a getter `() => value` that is re-read on each call (so the data
+     * can change without rebuilding the bridge). Any function is treated as a
+     * getter — widget data is never itself a function. Optional: many standalone
+     * widgets fetch everything through `callTool` instead.
+     */
+    getData?: unknown;
+    /**
+     * Handle a `sendFollowup` prompt. A standalone app has no conversation, so
+     * this is where you wire "ask the model" to your own chat UI, a toast, or a
+     * logger. Omit to make `sendFollowup` a logged no-op.
+     */
+    onFollowup?: (prompt: string) => void;
+    /**
+     * Handle `openExternal`. Defaults to `window.open(url, "_blank")` when omitted
+     * (a standalone app is not sandboxed, so that is safe).
+     */
+    onOpenExternal?: (url: string) => void;
+    /** Handle `setModelContext`. Omit to make it a logged no-op. */
+    onModelContext?: (text: string) => void;
+    /** Static theme to report to widgets. */
+    theme?: "light" | "dark";
+}
+/**
+ * Build a {@link HostBridge} for a standalone web app driven against an existing
+ * MCP server — no toolkit host, no `createFrameworkApp`. You inject `callTool`
+ * (usually a thin wrapper over a `@modelcontextprotocol/sdk` client); the
+ * conversation-shaped verbs (`sendFollowup`, `setModelContext`) are no-ops
+ * unless you wire handlers, and `openExternal` defaults to `window.open`.
+ *
+ * This is the decoupling layer that turns the toolkit's hand-built widgets into
+ * a reusable UI kit for *any* MCP server: render `<HostBridgeProvider bridge=…>`
+ * once at the app root and every portable widget below works. The widget fixture
+ * harness also builds on this factory so host simulation has a single source.
+ *
+ * @example
+ * const client = new Client(…) // @modelcontextprotocol/sdk
+ * const bridge = createStandaloneHostBridge({
+ *   callTool: (name, args) => client.callTool({ name, arguments: args }),
+ *   getData: () => currentRecord,
+ * })
+ */
+export declare function createStandaloneHostBridge(options: StandaloneHostBridgeOptions): HostBridge;
+//# sourceMappingURL=host-bridge.d.ts.map

package/dist/app/host-bridge.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"host-bridge.d.ts","sourceRoot":"","sources":["../../src/app/host-bridge.tsx"],"names":[],"mappings":"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"}

package/dist/app/host-bridge.js

@@ -0,0 +1,247 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { createContext, useContext, useMemo } from "react";
+import { useWidget } from "mcp-use/react";
+const HostBridgeContext = createContext(null);
+/**
+ * Provide an explicit {@link HostBridge} to a subtree. Wrap a portable widget in
+ * the adapter for the host it is running in — {@link createChatGptHostBridge},
+ * {@link createStandaloneHostBridge}, or {@link createMcpUseHostBridge} — and
+ * every `useHostBridge()` below resolves to it.
+ *
+ * Omitting the provider is supported: {@link useHostBridge} (and, for backward
+ * compatibility, `useHostActions`) then fall back to the `mcp-use`/react default
+ * bridge so existing widgets keep working without any wrapping.
+ */
+export function HostBridgeProvider({ bridge, children, }) {
+    return _jsx(HostBridgeContext.Provider, { value: bridge, children: children });
+}
+/**
+ * Read the explicit {@link HostBridge} from context, or `null` if no
+ * {@link HostBridgeProvider} is present. Adapters that want to *fall back* to the
+ * default `mcp-use` bridge (rather than throw) use this instead of
+ * {@link useHostBridge}.
+ */
+export function useHostBridgeOrNull() {
+    return useContext(HostBridgeContext);
+}
+/**
+ * The {@link HostBridge} for the current subtree. Resolution order:
+ *
+ * 1. An explicit bridge from the nearest {@link HostBridgeProvider}.
+ * 2. The default `mcp-use`/react bridge ({@link createMcpUseHostBridge}), so a
+ *    widget mounted in our own host needs no provider.
+ *
+ * The `mcp-use` hooks the default bridge wraps must run under an `mcp-use`
+ * provider/host context; outside one (e.g. a bare unit test render) wrap the
+ * widget in a `HostBridgeProvider` with a {@link createStandaloneHostBridge}
+ * instead. This hook never returns `null`: a portable widget can always assume a
+ * bridge exists.
+ */
+export function useHostBridge() {
+    const explicit = useContext(HostBridgeContext);
+    // Always call the default-bridge hook (Rules of Hooks): it's cheap and only
+    // *used* when no explicit bridge is provided. The mcp-use hooks underneath are
+    // host-context readers, safe to call even when their result goes unused.
+    const fallback = useMcpUseHostBridge();
+    return explicit ?? fallback;
+}
+/**
+ * Build a {@link HostBridge} backed by `mcp-use`/react — the default for widgets
+ * running in the toolkit's own host. Wraps `useWidget()` (host actions,
+ * `toolOutput`, `theme`) and `useCallTool` so it preserves exactly the behaviour
+ * widgets had before the bridge abstraction:
+ *
+ * - `openExternal` routes through the host's `openExternal` and falls back to
+ *   `window.open` when no host bridge is wired (local dev preview) — mirroring
+ *   the original `useHostActions.openLink`.
+ * - `sendFollowup` routes through `sendFollowUpMessage` and swallows rejections
+ *   with a `console.warn`, as `useHostActions` did.
+ *
+ * Must be called inside an `mcp-use` host context (it calls `mcp-use` hooks).
+ * Use {@link createMcpUseHostBridge} for the standalone factory variant.
+ */
+export function useMcpUseHostBridge() {
+    const widget = useWidget();
+    const { callTool, sendFollowUpMessage, openExternal, output, theme, setState } = widget;
+    return useMemo(() => ({
+        callTool: (name, args) => callTool(name, args),
+        sendFollowup: (prompt) => {
+            void sendFollowUpMessage(prompt).catch((err) => {
+                console.warn("[host-bridge] sendFollowUpMessage failed:", err);
+            });
+        },
+        openExternal: (url) => {
+            try {
+                openExternal(url);
+            }
+            catch {
+                // No host bridge (local dev preview) — fall back to window.open.
+                if (typeof window !== "undefined")
+                    window.open(url, "_blank", "noopener");
+            }
+        },
+        getWidgetData: () => output ?? null,
+        setModelContext: (text) => {
+            void setState({ __model_context: text }).catch((err) => {
+                console.warn("[host-bridge] setState (model context) failed:", err);
+            });
+        },
+        theme: theme === "dark" ? "dark" : "light",
+    }), [callTool, sendFollowUpMessage, openExternal, output, theme, setState]);
+}
+/**
+ * Factory form of {@link useMcpUseHostBridge} for symmetry with the other
+ * adapters. Because the `mcp-use` bridge is hook-driven (it reads live host
+ * context), the "factory" is really the hook itself — call it from a component.
+ *
+ * @example
+ * function MyWidget() {
+ *   const bridge = createMcpUseHostBridge() // === useMcpUseHostBridge()
+ *   // …or rely on useHostBridge()'s default and skip the provider entirely.
+ * }
+ */
+export const createMcpUseHostBridge = useMcpUseHostBridge;
+/**
+ * Resolve the `window.openai` object, or `null` outside a browser / when the SDK
+ * is absent. Pulled out so the no-SDK fallback path is unit-testable by passing
+ * an explicit object (or `null`).
+ */
+function resolveOpenAi(explicit) {
+    if (explicit !== undefined)
+        return explicit;
+    if (typeof window === "undefined")
+        return null;
+    const candidate = window.openai;
+    return candidate && typeof candidate === "object" ? candidate : null;
+}
+/**
+ * Build a {@link HostBridge} for the OpenAI Apps SDK (ChatGPT). Reads the host's
+ * `window.openai` object and maps the bridge verbs onto it **defensively** —
+ * every method is probed before use, and a missing one degrades to a logged
+ * no-op (or, for `callTool`, a rejected promise) instead of crashing the widget.
+ * This is what lets the *same* hand-built widget run in ChatGPT with no code
+ * change, even across Apps SDK versions whose surface drifts.
+ *
+ * Pass an explicit `sdk` to test the guards without a real `window.openai`
+ * (passing `null` exercises the fully-absent path). See {@link OpenAiAppsSdk}
+ * for the documented assumptions about the SDK shape.
+ */
+export function createChatGptHostBridge(sdk) {
+    const openai = resolveOpenAi(sdk);
+    return {
+        callTool: (name, args) => {
+            if (typeof openai?.callTool !== "function") {
+                console.warn("[host-bridge] window.openai.callTool unavailable — cannot call", name);
+                return Promise.reject(new Error(`[host-bridge] OpenAI Apps SDK callTool is unavailable; cannot invoke "${name}".`));
+            }
+            return Promise.resolve(openai.callTool(name, args));
+        },
+        sendFollowup: (prompt) => {
+            const fn = openai?.sendFollowUpMessage ?? openai?.sendFollowupMessage;
+            if (typeof fn !== "function") {
+                console.warn("[host-bridge] window.openai.sendFollowUpMessage unavailable — no-op");
+                return;
+            }
+            try {
+                // Newer builds take `{ prompt }`; try that first, then a bare string.
+                const result = fn({ prompt });
+                if (result instanceof Promise) {
+                    result.catch((err) => {
+                        console.warn("[host-bridge] sendFollowUpMessage rejected:", err);
+                    });
+                }
+            }
+            catch {
+                try {
+                    fn(prompt);
+                }
+                catch (err) {
+                    console.warn("[host-bridge] sendFollowUpMessage failed:", err);
+                }
+            }
+        },
+        openExternal: (url) => {
+            if (typeof openai?.openExternal === "function") {
+                try {
+                    openai.openExternal({ href: url });
+                    return;
+                }
+                catch (err) {
+                    console.warn("[host-bridge] window.openai.openExternal failed:", err);
+                }
+            }
+            if (typeof window !== "undefined")
+                window.open(url, "_blank", "noopener");
+        },
+        getWidgetData: () => {
+            const data = openai?.toolOutput ?? openai?.toolResponseMetadata;
+            return data ?? null;
+        },
+        setModelContext: (text) => {
+            if (typeof openai?.setWidgetState !== "function") {
+                console.warn("[host-bridge] window.openai.setWidgetState unavailable — model context no-op");
+                return;
+            }
+            try {
+                openai.setWidgetState({ __model_context: text });
+            }
+            catch (err) {
+                console.warn("[host-bridge] setWidgetState failed:", err);
+            }
+        },
+        theme: openai?.theme === "dark" ? "dark" : openai?.theme === "light" ? "light" : undefined,
+    };
+}
+/**
+ * Build a {@link HostBridge} for a standalone web app driven against an existing
+ * MCP server — no toolkit host, no `createFrameworkApp`. You inject `callTool`
+ * (usually a thin wrapper over a `@modelcontextprotocol/sdk` client); the
+ * conversation-shaped verbs (`sendFollowup`, `setModelContext`) are no-ops
+ * unless you wire handlers, and `openExternal` defaults to `window.open`.
+ *
+ * This is the decoupling layer that turns the toolkit's hand-built widgets into
+ * a reusable UI kit for *any* MCP server: render `<HostBridgeProvider bridge=…>`
+ * once at the app root and every portable widget below works. The widget fixture
+ * harness also builds on this factory so host simulation has a single source.
+ *
+ * @example
+ * const client = new Client(…) // @modelcontextprotocol/sdk
+ * const bridge = createStandaloneHostBridge({
+ *   callTool: (name, args) => client.callTool({ name, arguments: args }),
+ *   getData: () => currentRecord,
+ * })
+ */
+export function createStandaloneHostBridge(options) {
+    const { callTool, getData, onFollowup, onOpenExternal, onModelContext, theme } = options;
+    return {
+        callTool: (name, args) => callTool(name, args),
+        sendFollowup: (prompt) => {
+            if (onFollowup) {
+                onFollowup(prompt);
+                return;
+            }
+            console.warn("[host-bridge] standalone bridge has no onFollowup handler — prompt dropped");
+        },
+        openExternal: (url) => {
+            if (onOpenExternal) {
+                onOpenExternal(url);
+                return;
+            }
+            if (typeof window !== "undefined")
+                window.open(url, "_blank", "noopener");
+        },
+        getWidgetData: () => {
+            const data = typeof getData === "function" ? getData() : getData;
+            return data ?? null;
+        },
+        setModelContext: (text) => {
+            if (onModelContext) {
+                onModelContext(text);
+                return;
+            }
+            console.warn("[host-bridge] standalone bridge has no onModelContext handler — context dropped");
+        },
+        theme,
+    };
+}
+//# sourceMappingURL=host-bridge.js.map