/**
 * Cross-host UI client — types and wire constants.
 *
 * The cross-host client (`connectUI`) renders one Synapse-authored component in
 * any MCP Apps host (ChatGPT, Claude, NimbleBrain) and standalone. Apps code
 * against `synapse.*` and never touch the bridge. This is a **push-first** surface: the tool output that spawned
 * the widget is delivered at render (`data()` / `onData()`); `callTool()` is the
 * pull escape hatch, advertised per host via `capabilities()`.
 *
 * This layer intentionally has ZERO dependency on `@modelcontextprotocol/*` — the
 * bridge is JSON-RPC over `postMessage`, spoken by hand, so the IIFE that apps
 * inline stays tiny (no Zod, no ext-apps schemas).
 */
/**
 * The bridge the client resolved to, as reported by `synapse.host()`:
 * `"mcp-apps"` in a frame, `"generic"` standalone. It names the bridge, not the
 * product — every framing host speaks the same one. Apps should rarely branch on
 * it; `capabilities()` is the supported way to feature-detect.
 */
type HostKind = "mcp-apps" | "generic";
/** Resolved theme. `mode` always resolves to light or dark. `tokens` are CSS
 *  custom properties the host publishes — the MCP Apps adapter reads them from
 *  `hostContext.styles.variables`; where a host sends none they stay empty and the
 *  SDK's neutral defaults back them. */
interface SynapseUITheme {
    mode: "light" | "dark";
    tokens: Record<string, string>;
}
/** What the active host actually supports. `data()`/`onData()`/`theme()`/
 *  `resize()` work everywhere; these three vary. */
interface HostCapabilities {
    /** `callTool()` can reach the server (widget→server fetch). */
    pull: boolean;
    /** `sendPrompt()` reaches the agent conversation. */
    sendPrompt: boolean;
    /** `openLink()` opens an external URL through the host. */
    openLink: boolean;
}
/** Thrown by `callTool()` when the active host offers no widget→server call. */
declare class HostUnsupportedError extends Error {
    constructor(feature: string, host: HostKind);
}
/**
 * Thrown by `callTool()` when the tool result says the call failed
 * (`isError: true`). MCP reports a tool failure inside the result rather than as
 * a JSON-RPC error, and a host reports a refusal the same way — ChatGPT answers a
 * call to a tool the app may not see with an `isError` result — so without this a
 * failure would resolve as if it were data. The message is the result's first
 * text block; the whole result is on `result`.
 */
declare class ToolCallError extends Error {
    readonly result: unknown;
    constructor(name: string, result: unknown);
}
interface ConnectUIOptions {
    /** App name — informational; forwarded to hosts that accept an appInfo. */
    name?: string;
    /** App semver — informational. */
    version?: string;
    /**
     * Force a host adapter instead of auto-detecting. Used by preview harnesses,
     * SSR, and tests; production apps omit it and let the SDK feature-detect.
     * `"mcp-apps"` → MCP Apps standard adapter, `"generic"` → inline adapter.
     */
    host?: HostKind;
    /**
     * `id` of the `<script type="application/json">` element carrying pushed data
     * baked into the HTML (the SSR / standalone path). Defaults to
     * {@link SYNAPSE_DATA_ELEMENT_ID}.
     */
    dataElementId?: string;
    /**
     * Auto-report content height to the host on layout changes (MCP Apps only).
     * Defaults to `true`. Set `false` to size manually via `resize()`.
     */
    autoResize?: boolean;
    /** Window to bind to. Defaults to the global `window`. Injectable for tests. */
    window?: Window & typeof globalThis;
}
/**
 * The public cross-host client. Bound to `synapse` by convention.
 *
 * ```ts
 * const synapse = connectUI();
 * synapse.onData(render);          // future pushes/updates
 * render(synapse.data());          // current value (may be null → empty state)
 * ```
 */
interface SynapseUIClient {
    /** The current pushed data, or `null` before anything has been delivered. */
    data<T = unknown>(): T | null;
    /** Subscribe to data updates (NOT replayed — read `data()` for the current
     *  value). Returns an unsubscribe. */
    onData<T = unknown>(cb: (data: T) => void): () => void;
    /** The current resolved theme. */
    theme(): SynapseUITheme;
    /** Subscribe to theme changes. The client already applies the theme to the DOM
     *  (`data-theme` attribute + CSS variables) before this fires. */
    onTheme(cb: (theme: SynapseUITheme) => void): () => void;
    /** Widget→server tool call. Resolves with the tool result. Rejects with
     *  {@link ToolCallError} when the result reports failure (`isError: true`), and
     *  with {@link HostUnsupportedError} where the host advertises no pull
     *  (`capabilities().pull === false`). */
    callTool<O = unknown>(name: string, args?: Record<string, unknown>): Promise<O>;
    /** Send a follow-up message to the agent conversation. No-op where unsupported. */
    sendPrompt(text: string): void;
    /** Open an external URL through the host (falls back to `window.open`). */
    openLink(url: string): void;
    /** Report content height to the host. Omit `height` to measure `document.body`. */
    resize(height?: number): void;
    /** What the active host supports. */
    capabilities(): HostCapabilities;
    /** The resolved host — an escape hatch; prefer `capabilities()`. */
    host(): HostKind;
    /** Tear down listeners/observers. */
    destroy(): void;
}
/**
 * Internal adapter contract. One per host bridge; the client is a thin façade
 * over the selected adapter.
 */
interface HostAdapter {
    readonly host: HostKind;
    getData<T = unknown>(): T | null;
    onData<T = unknown>(cb: (data: T) => void): () => void;
    getTheme(): SynapseUITheme;
    onTheme(cb: (theme: SynapseUITheme) => void): () => void;
    callTool<O = unknown>(name: string, args?: Record<string, unknown>): Promise<O>;
    sendPrompt(text: string): void;
    openLink(url: string): void;
    resize(height?: number): void;
    capabilities(): HostCapabilities;
    /** Begin listening / send the ready handshake / read baked-in data. Called once
     *  by `connectUI` synchronously so `getData()` is populated on return. */
    start(): void;
    destroy(): void;
}
/** Default `id` of the baked-in data `<script type="application/json">`. */
declare const SYNAPSE_DATA_ELEMENT_ID = "synapse-ui-data";

/**
 * Connect a Synapse-authored component to whatever host it renders in — any MCP
 * Apps host, or a plain/standalone page — behind one push-first API. Detects
 * whether it is framed, selects an adapter, and applies the
 * host theme to the DOM before returning.
 *
 * Synchronous: `data()` is populated from baked-in data (where present) on
 * return, and pushed updates arrive via `onData`. Bind the result to `synapse`:
 *
 * ```ts
 * const synapse = connectUI({ name: "my-widget", version: "1.0.0" });
 * synapse.onData(render);        // future pushes/updates
 * render(synapse.data());        // current value (null → empty state)
 * ```
 */
declare function connectUI(options?: ConnectUIOptions): SynapseUIClient;

/**
 * Minimal window shape the detector inspects. Kept structural so detection is
 * unit-testable with a plain object — no full `Window` fake required.
 */
interface DetectableWindow {
    parent?: unknown;
}
/**
 * Detect the bridge from the browsing context.
 *
 *  - a nested browsing context (`parent !== self`, or a cross-origin access that
 *    throws) → **mcp-apps**: every host that frames a component speaks the MCP
 *    Apps standard.
 *  - top-level document → **generic** (inline / standalone).
 *
 * Nothing on the window names the host. `window.openai` in particular does not:
 * ChatGPT injects it into every frame it serves, whatever the component is.
 * Which host answered is in the handshake, not here.
 */
declare function detectHostKind(win: DetectableWindow): HostKind;
/** Build the adapter for an explicit host kind (`options.host` or a detected one). */
declare function adapterForKind(kind: HostKind, win: Window & typeof globalThis, options: ConnectUIOptions): HostAdapter;
/** Select and construct the host adapter, honoring `options.host` when set. */
declare function selectAdapter(win: Window & typeof globalThis, options: ConnectUIOptions): HostAdapter;

export { type ConnectUIOptions as C, type HostAdapter as H, type SynapseUITheme as S, ToolCallError as T, type HostCapabilities as a, type HostKind as b, HostUnsupportedError as c, SYNAPSE_DATA_ELEMENT_ID as d, type SynapseUIClient as e, adapterForKind as f, connectUI as g, detectHostKind as h, selectAdapter as s };