@botiverse/porthole 0.0.0-stage → 0.1.0

package/dist/mcp/index.js

@@ -0,0 +1,25 @@
+/**
+ * `@botiverse/porthole/mcp`: the MCP Apps adapter for full MCP Apps views (P007): the host-side
+ * subset of the protocol (the handshake and host context, tool input and result, cancellation,
+ * teardown, sizes and errors; `ui/message`, `ui/open-link`, `ui/download-file`, `tools/call`,
+ * `resources/read` and `ui/update-model-context` through the bridge; the sandbox-proxy handshake),
+ * implemented as a `ProtocolAdapter` against the core's seams. It depends on the core only, never
+ * on the MCP SDK.
+ *
+ *   const view = readViewResource(await client.readResource({ uri }));
+ *   const host = createHost(presets.mcpApp({ egress: view.egress, capabilities: { callTool: {} } }), {
+ *     adapter: mcpAppsAdapter(),
+ *     handlers: { callTool: ({ name, arguments: args }) => client.callTool({ name, arguments: args }) },
+ *   });
+ *   const display = host.mount(element, { displayId, title, scheme, document: view.html });
+ *   display.sendToolInput(args);
+ *   display.sendToolResult(await client.callTool({ name, arguments: args }));
+ *
+ * Tool visibility (`_meta.ui.visibility`) is the host's policy: its `callTool` handler refuses a
+ * tool the view may not call.
+ */
+export { mcpAppsAdapter, viewHostContext, } from "./adapter.js";
+export { sandboxProxyDocument } from "./proxy.js";
+export { VIEW_MIME_TYPE, readViewResource, viewEgress } from "./view.js";
+export { MCP_APPS_METHODS, MCP_APPS_PROTOCOL_VERSION, MCP_APPS_STYLE_VARIABLES, PORTHOLE_STYLES, } from "../protocol/mcp-apps.js";
+export { JSON_RPC_ERRORS, parseJsonRpc, } from "../protocol/jsonrpc.js";

package/dist/mcp/proxy.d.ts

@@ -0,0 +1,25 @@
+import type { CompiledConfig } from "../compile/compile.ts";
+/**
+ * The MCP Apps sandbox proxy (spec § Sandbox proxy), served by `/server` on a scope's origin: a
+ * second origin, never the host's, where a view gets `allow-scripts allow-same-origin` (P016).
+ * It announces itself (`sandbox-proxy-ready`) until its host answers with the view's HTML
+ * (`sandbox-resource-ready`), then becomes the view: it writes the shell's document into its own,
+ * with the view's HTML as data in the shell's plan (never as markup for the page's parser, which
+ * could build what the shell's guards can't see), and the shell renders it inert, guarded, then
+ * runs it, under the CSP the proxy's headers already carry. Writing a document erases
+ * the window's listeners, so nothing of the proxy is left once the view runs, and the view talks
+ * to its host directly: the relay the spec describes is the identity here (P026).
+ *
+ * The proxy takes the HTML only from its parent, only from the host origins, and only once. It
+ * ignores the message's `csp`, `sandbox` and `permissions`: the policy is the one its headers set
+ * from the config and the view's declared egress when the host's backend issued it, and the
+ * frame's sandbox and `allow` are the host's, from the same config.
+ */
+export declare const SANDBOX_PROXY_RUNTIME: string;
+/**
+ * The proxy's document for a view under `compiled` (an `mcp-app` config with domain isolation),
+ * taking the view only from `hostOrigins`. The document it becomes is exactly
+ * `compiled.shellDocument({ origins: hostOrigins, document: html, cspMeta: false })`: the shell,
+ * carrying the view as data.
+ */
+export declare function sandboxProxyDocument(compiled: CompiledConfig, hostOrigins: readonly string[]): string;

package/dist/mcp/proxy.js

@@ -0,0 +1,106 @@
+import { MCP_APPS_METHODS } from "../protocol/mcp-apps.js";
+/**
+ * The MCP Apps sandbox proxy (spec § Sandbox proxy), served by `/server` on a scope's origin: a
+ * second origin, never the host's, where a view gets `allow-scripts allow-same-origin` (P016).
+ * It announces itself (`sandbox-proxy-ready`) until its host answers with the view's HTML
+ * (`sandbox-resource-ready`), then becomes the view: it writes the shell's document into its own,
+ * with the view's HTML as data in the shell's plan (never as markup for the page's parser, which
+ * could build what the shell's guards can't see), and the shell renders it inert, guarded, then
+ * runs it, under the CSP the proxy's headers already carry. Writing a document erases
+ * the window's listeners, so nothing of the proxy is left once the view runs, and the view talks
+ * to its host directly: the relay the spec describes is the identity here (P026).
+ *
+ * The proxy takes the HTML only from its parent, only from the host origins, and only once. It
+ * ignores the message's `csp`, `sandbox` and `permissions`: the policy is the one its headers set
+ * from the config and the view's declared egress when the host's backend issued it, and the
+ * frame's sandbox and `allow` are the host's, from the same config.
+ */
+export const SANDBOX_PROXY_RUNTIME = String.raw `(() => {
+  "use strict";
+  const setup = __SETUP__;
+  if (window.parent === window) {
+    return;
+  }
+  let done = false;
+  window.addEventListener("message", (event) => {
+    if (done || event.source !== window.parent || setup.origins.indexOf(event.origin) === -1) {
+      return;
+    }
+    const data = event.data;
+    if (data === null || typeof data !== "object" || data.jsonrpc !== "2.0" || data.method !== setup.resource) {
+      return;
+    }
+    const params = data.params;
+    if (params === null || typeof params !== "object" || typeof params.html !== "string") {
+      return;
+    }
+    done = true;
+    // The view goes into the shell's plan as a JSON string, safe inside its <script>.
+    const literal = JSON.stringify(params.html)
+      .replace(/</g, "\\u003c")
+      .replace(/\u2028/g, "\\u2028")
+      .replace(/\u2029/g, "\\u2029");
+    const page = setup.shell.replace(setup.slot, () => literal);
+    document.open();
+    document.write(page);
+    document.close();
+  });
+  // Say so until answered: the host may start listening after this runs. Nothing secret is said.
+  let tries = 0;
+  const announce = () => {
+    if (done || tries >= 40) {
+      return;
+    }
+    tries += 1;
+    window.parent.postMessage({ jsonrpc: "2.0", method: setup.ready, params: {} }, "*");
+    setTimeout(announce, 250);
+  };
+  announce();
+})();`;
+/** Where the view's HTML goes in the shell's plan: a string no view can produce as JSON. */
+const VIEW_SLOT = "porthole-view-slot-7f3a9c";
+/** JSON that is safe inside a `<script>`: no `</script>`, no `<!--`. */
+const scriptJson = (value) => JSON.stringify(value)
+    .replace(/</gu, "\\u003c")
+    .replace(/\u2028/gu, "\\u2028")
+    .replace(/\u2029/gu, "\\u2029");
+/**
+ * The proxy's document for a view under `compiled` (an `mcp-app` config with domain isolation),
+ * taking the view only from `hostOrigins`. The document it becomes is exactly
+ * `compiled.shellDocument({ origins: hostOrigins, document: html, cspMeta: false })`: the shell,
+ * carrying the view as data.
+ */
+export function sandboxProxyDocument(compiled, hostOrigins) {
+    if (compiled.config.mode !== "mcp-app") {
+        throw new TypeError(`The sandbox proxy serves MCP Apps views, not ${compiled.config.mode}`);
+    }
+    // The shell with a slot for the view: the slot's JSON literal, replaced by the view's.
+    const shell = compiled.shellDocument({
+        origins: hostOrigins,
+        document: VIEW_SLOT,
+        cspMeta: false,
+    });
+    const slot = JSON.stringify(VIEW_SLOT);
+    if (shell.split(slot).length !== 2) {
+        throw new Error("The shell document must hold the view's slot exactly once");
+    }
+    const runtime = SANDBOX_PROXY_RUNTIME.replace("__SETUP__", () => scriptJson({
+        origins: hostOrigins,
+        shell,
+        slot,
+        ready: MCP_APPS_METHODS.sandboxProxyReady,
+        resource: MCP_APPS_METHODS.sandboxResourceReady,
+    }));
+    return `<!doctype html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<meta name="referrer" content="no-referrer">
+<title>Sandbox</title>
+</head>
+<body>
+<script>${runtime}</script>
+</body>
+</html>
+`;
+}

package/dist/mcp/view.d.ts

@@ -0,0 +1,31 @@
+import type { EgressConfig } from "../config/schema.ts";
+/**
+ * What a host reads from an MCP Apps view's resource before showing it: the HTML, and the egress
+ * the view declares, in Porthole's vocabulary so it goes into a config (P003).
+ */
+/** The style variables MCP Apps standardizes: one list, the core's (P028). */
+export { MCP_APPS_STYLE_VARIABLES } from "../protocol/mcp-apps.ts";
+/**
+ * A view's `_meta.ui.csp` as egress: `connectDomains` to connect, `resourceDomains` to scripts,
+ * styles, images, fonts and media. What isn't an exact origin (or `https://*.` one) is dropped,
+ * never widened. `frameDomains` and `baseUriDomains` open nothing: the shell removes nested frames
+ * (P006) and `base-uri` stays `'none'`, so a view that needs either runs without it.
+ */
+export declare function viewEgress(csp: unknown): EgressConfig;
+/** A view, as `resources/read` gives it. */
+export interface ViewResource {
+    readonly uri: string;
+    /** The view's whole document. */
+    readonly html: string;
+    /** What the view declares it reaches (its `_meta.ui.csp`), as egress. */
+    readonly egress: EgressConfig;
+    /** Whether the view asks the host for a border and background (`_meta.ui.prefersBorder`). */
+    readonly prefersBorder?: boolean;
+}
+/** The MIME type of an MCP Apps view. */
+export declare const VIEW_MIME_TYPE = "text/html;profile=mcp-app";
+/**
+ * The view in a `resources/read` result: its first content of the MCP Apps MIME type, as text or
+ * base64. Null when there is none.
+ */
+export declare function readViewResource(result: unknown): ViewResource | null;

package/dist/mcp/view.js

@@ -0,0 +1,72 @@
+import { isOriginSource } from "../config/validate.js";
+/**
+ * What a host reads from an MCP Apps view's resource before showing it: the HTML, and the egress
+ * the view declares, in Porthole's vocabulary so it goes into a config (P003).
+ */
+/** The style variables MCP Apps standardizes: one list, the core's (P028). */
+export { MCP_APPS_STYLE_VARIABLES } from "../protocol/mcp-apps.js";
+const isRecord = (value) => value !== null && typeof value === "object" && !Array.isArray(value);
+/** A declared domain as a CSP source Porthole accepts, or null (`'self'`, `*`, paths, quotes). */
+function originOf(value) {
+    if (typeof value !== "string") {
+        return null;
+    }
+    const source = value.trim().toLowerCase().replace(/\/$/u, "");
+    return isOriginSource(source) ? source : null;
+}
+const origins = (value) => Array.isArray(value)
+    ? [...new Set(value.map(originOf).filter((each) => each !== null))]
+    : [];
+/**
+ * A view's `_meta.ui.csp` as egress: `connectDomains` to connect, `resourceDomains` to scripts,
+ * styles, images, fonts and media. What isn't an exact origin (or `https://*.` one) is dropped,
+ * never widened. `frameDomains` and `baseUriDomains` open nothing: the shell removes nested frames
+ * (P006) and `base-uri` stays `'none'`, so a view that needs either runs without it.
+ */
+export function viewEgress(csp) {
+    if (!isRecord(csp)) {
+        return {};
+    }
+    const connect = origins(csp.connectDomains);
+    const resource = origins(csp.resourceDomains);
+    return {
+        ...(connect.length > 0 ? { connect } : {}),
+        ...(resource.length > 0
+            ? { script: resource, style: resource, img: resource, font: resource, media: resource }
+            : {}),
+    };
+}
+/** The MIME type of an MCP Apps view. */
+export const VIEW_MIME_TYPE = "text/html;profile=mcp-app";
+/**
+ * The view in a `resources/read` result: its first content of the MCP Apps MIME type, as text or
+ * base64. Null when there is none.
+ */
+export function readViewResource(result) {
+    const contents = isRecord(result) && Array.isArray(result.contents) ? result.contents : [];
+    for (const content of contents) {
+        if (!isRecord(content) || typeof content.mimeType !== "string") {
+            continue;
+        }
+        if (content.mimeType.replace(/\s/gu, "").toLowerCase() !== VIEW_MIME_TYPE) {
+            continue;
+        }
+        const html = typeof content.text === "string"
+            ? content.text
+            : typeof content.blob === "string"
+                ? new TextDecoder().decode(Uint8Array.from(atob(content.blob), (char) => char.charCodeAt(0)))
+                : null;
+        if (html === null) {
+            continue;
+        }
+        const meta = content["_meta"];
+        const ui = isRecord(meta) && isRecord(meta.ui) ? meta.ui : {};
+        return {
+            uri: typeof content.uri === "string" ? content.uri : "",
+            html,
+            egress: viewEgress(ui.csp),
+            ...(typeof ui.prefersBorder === "boolean" ? { prefersBorder: ui.prefersBorder } : {}),
+        };
+    }
+    return null;
+}

package/dist/platform/types.d.ts

@@ -0,0 +1,44 @@
+import type { ColorScheme } from "../config/schema.ts";
+import type { FrameSource } from "../isolation/types.ts";
+import type { Transport } from "../transport/types.ts";
+/**
+ * The platform-host seam (ARCHITECTURE § Platform hosts): what owns the isolation primitive and
+ * the transport. The web's is an `<iframe>` with `postMessage`; a native web view is another
+ * implementation of the same interface, not a fork.
+ */
+/** What to create: the frame's document and its policy attributes, all from the compiled config. */
+export interface SurfaceSpec {
+    readonly source: FrameSource;
+    /** The frame's accessible name. */
+    readonly title: string;
+    readonly sandbox: string;
+    readonly allow: string;
+    readonly referrerPolicy: "no-referrer";
+    readonly colorScheme: ColorScheme;
+    /** The height to start at (a remembered height, so a frame mounting again doesn't jump). */
+    readonly initialHeightPx: number;
+}
+/** One isolated frame. */
+export interface Surface {
+    readonly transport: Transport;
+    /** The platform's own element for the frame (an `HTMLIFrameElement` on the web). */
+    readonly element: unknown;
+    setHeight(px: number): void;
+    setColorScheme(scheme: ColorScheme): void;
+    /**
+     * Whether the embedding page has transient user activation now (a gesture in the frame
+     * activates its ancestors), or undefined where the platform can't tell.
+     */
+    userActivation(): boolean | undefined;
+    /**
+     * The frame loaded a document other than the one it was given: the content navigated it. The
+     * framework starts it again from its content and reports it.
+     */
+    onNavigated(listener: () => void): () => void;
+    destroy(): void;
+}
+export interface PlatformHost<Container = HTMLElement> {
+    readonly name: string;
+    /** Creates an isolated frame in `container`, its policy set before its document loads. */
+    createSurface(container: Container, spec: SurfaceSpec): Surface;
+}

package/dist/platform/types.js

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

package/dist/platform/web.d.ts

@@ -0,0 +1,8 @@
+import type { PlatformHost } from "./types.ts";
+/**
+ * The web platform: an `<iframe>` whose policy attributes are set before its document is given,
+ * talking over `postMessage`. Its first load is the document it was given; any later load is the
+ * content navigating its frame away (a navigation the embedding page's `frame-src` let through, or
+ * one to a document of the frame's own), which the framework answers by starting it again.
+ */
+export declare const webPlatform: PlatformHost;

package/dist/platform/web.js

@@ -0,0 +1,72 @@
+import { postMessageTransport } from "../transport/post-message.js";
+/**
+ * The web platform: an `<iframe>` whose policy attributes are set before its document is given,
+ * talking over `postMessage`. Its first load is the document it was given; any later load is the
+ * content navigating its frame away (a navigation the embedding page's `frame-src` let through, or
+ * one to a document of the frame's own), which the framework answers by starting it again.
+ */
+export const webPlatform = {
+    name: "web",
+    createSurface(container, spec) {
+        // oxlint-disable-next-line react/iframe-missing-sandbox -- set from the compiled config, next
+        const frame = container.ownerDocument.createElement("iframe");
+        // Policy first: the sandbox and Permissions Policy must be in place before the document is.
+        frame.setAttribute("sandbox", spec.sandbox);
+        frame.setAttribute("allow", spec.allow);
+        frame.setAttribute("referrerpolicy", spec.referrerPolicy);
+        frame.setAttribute("loading", "eager");
+        frame.title = spec.title;
+        frame.dataset.portholeFrame = "";
+        Object.assign(frame.style, {
+            display: "block",
+            width: "100%",
+            border: "0",
+            background: "transparent",
+            colorScheme: spec.colorScheme,
+            height: `${Math.max(0, Math.round(spec.initialHeightPx))}px`,
+        });
+        const origin = spec.source.kind === "srcdoc" ? "null" : spec.source.origin;
+        if (spec.source.kind === "srcdoc") {
+            frame.srcdoc = spec.source.html;
+        }
+        else {
+            frame.src = spec.source.url;
+        }
+        const navigated = new Set();
+        let loads = 0;
+        frame.addEventListener("load", () => {
+            loads += 1;
+            if (loads > 1) {
+                for (const listener of navigated) {
+                    listener();
+                }
+            }
+        });
+        container.append(frame);
+        const view = container.ownerDocument.defaultView ?? window;
+        const transport = postMessageTransport(() => frame.contentWindow, origin, view);
+        return {
+            transport,
+            element: frame,
+            setHeight(px) {
+                frame.style.height = `${Math.max(0, Math.round(px))}px`;
+            },
+            setColorScheme(scheme) {
+                frame.style.colorScheme = scheme;
+            },
+            userActivation() {
+                const activation = view.navigator.userActivation;
+                return activation === undefined ? undefined : activation.isActive;
+            },
+            onNavigated(listener) {
+                navigated.add(listener);
+                return () => navigated.delete(listener);
+            },
+            destroy() {
+                navigated.clear();
+                transport.close();
+                frame.remove();
+            },
+        };
+    },
+};

package/dist/presets/presets.d.ts

@@ -0,0 +1,65 @@
+import type { CapabilityName } from "../config/capabilities.ts";
+import type { CapabilityConfig, EgressConfig, EmbedderConfig, GuideConfig, IsolationKind, LayoutConfig, Limits, PortholeConfig, ThemeValue } from "../config/schema.ts";
+/**
+ * The preset policy layer (P001): named configs with safe defaults. Every preset starts with
+ * egress closed and only the capabilities that carry nothing out of the frame (its size, its
+ * errors, both to the host only); a host declares the rest, and each gets its default gates
+ * unless the host names its own. A preset returns a validated config.
+ */
+/** What a host may change about a preset. Anything else is the preset's. */
+export interface PresetOptions {
+    /** Capabilities to declare (merged over the preset's), or `false` to drop one the preset has. */
+    readonly capabilities?: {
+        readonly [N in CapabilityName]?: CapabilityConfig | false;
+    };
+    /** Origins to open, added to the preset's (closed) egress. */
+    readonly egress?: EgressConfig;
+    /** Theme defaults to change or variables to add, and the theme event's name. */
+    readonly theme?: {
+        readonly variables?: Readonly<Record<string, ThemeValue>>;
+        readonly event?: string;
+    };
+    readonly limits?: Partial<Limits>;
+    readonly layout?: Partial<LayoutConfig>;
+    readonly guide?: GuideConfig;
+    /** `opaque` (default) or `domain` for a served document (needs `contentOrigins`). */
+    readonly isolation?: Exclude<IsolationKind, "external">;
+    readonly contentOrigins?: readonly string[];
+    readonly embedder?: EmbedderConfig;
+}
+/** The url preset's options: where the app is served, and the embedding page's extra frames. */
+export interface UrlPresetOptions {
+    readonly contentOrigins: readonly string[];
+    readonly limits?: Partial<Limits>;
+    readonly layout?: Partial<LayoutConfig>;
+    readonly embedder?: EmbedderConfig;
+}
+/**
+ * Library CDNs a host may open with one line (`egress: LIBRARY_CDNS`): read-only package caches
+ * for scripts, styles, fonts, images and data, plus Google Fonts. Not on by default: every preset
+ * starts with egress closed.
+ */
+export declare const LIBRARY_CDNS: EgressConfig;
+export declare const presets: {
+    /**
+     * An HTML fragment or SVG an agent wrote, drawn inline (a card in a conversation): an opaque
+     * frame with the shell, streamed as it is written.
+     */
+    readonly inlineWidget: (options?: PresetOptions) => PortholeConfig;
+    /**
+     * A whole HTML page: written into an opaque frame by the shell where the host has the page, or
+     * served on its own origin (`isolation: "domain"`). A document scrolls inside past a shorter cap.
+     */
+    readonly artifact: (options?: PresetOptions) => PortholeConfig;
+    /**
+     * A standard MCP Apps view, through an MCP Apps adapter. The view's own `_meta.ui.csp` is
+     * mapped into `egress` by that adapter; the host declares the capabilities it serves.
+     */
+    readonly mcpApp: (options?: PresetOptions) => PortholeConfig;
+    /**
+     * A running app by URL (a dev server's preview): frame, isolation and access auth only. No
+     * shell, no capabilities, no egress control: the app is someone else's, on its own origin.
+     */
+    readonly url: (options: UrlPresetOptions) => PortholeConfig;
+};
+export type PresetName = keyof typeof presets;

package/dist/presets/presets.js

@@ -0,0 +1,125 @@
+import { validateConfig } from "../config/validate.js";
+import { DEFAULT_THEME_EVENT, DEFAULT_THEME_VARIABLES } from "../theme/variables.js";
+/**
+ * Library CDNs a host may open with one line (`egress: LIBRARY_CDNS`): read-only package caches
+ * for scripts, styles, fonts, images and data, plus Google Fonts. Not on by default: every preset
+ * starts with egress closed.
+ */
+export const LIBRARY_CDNS = {
+    script: [
+        "https://cdnjs.cloudflare.com",
+        "https://cdn.jsdelivr.net",
+        "https://unpkg.com",
+        "https://esm.sh",
+    ],
+    style: [
+        "https://cdnjs.cloudflare.com",
+        "https://cdn.jsdelivr.net",
+        "https://unpkg.com",
+        "https://esm.sh",
+        "https://fonts.googleapis.com",
+    ],
+    font: [
+        "https://fonts.gstatic.com",
+        "https://cdnjs.cloudflare.com",
+        "https://cdn.jsdelivr.net",
+        "https://unpkg.com",
+        "https://esm.sh",
+    ],
+    img: [
+        "https://cdnjs.cloudflare.com",
+        "https://cdn.jsdelivr.net",
+        "https://unpkg.com",
+        "https://esm.sh",
+    ],
+    connect: [
+        "https://cdnjs.cloudflare.com",
+        "https://cdn.jsdelivr.net",
+        "https://unpkg.com",
+        "https://esm.sh",
+    ],
+};
+const BASE_LIMITS = {
+    maxHeightPx: 2_000,
+    minHeightPx: 24,
+    maxBytes: 200_000,
+    maxLiveFrames: 8,
+    declinesBeforeMute: 3,
+    maxPromptChars: 8_000,
+    maxErrorReports: 5,
+};
+const BASE_LAYOUT = { minWidthPx: 280, narrowWidthPx: 300, wideWidthPx: 750 };
+/** Only what reports to the host and carries nothing out: the frame's size and its errors. */
+const BASE_CAPABILITIES = { resize: {}, reportError: {} };
+const mergeEgress = (base, extra) => {
+    const kinds = ["connect", "script", "style", "img", "font", "media"];
+    const merged = {};
+    for (const kind of kinds) {
+        const origins = [...new Set([...(base[kind] ?? []), ...(extra?.[kind] ?? [])])];
+        if (origins.length > 0) {
+            merged[kind] = origins;
+        }
+    }
+    return merged;
+};
+function build(mode, defaults, options) {
+    const capabilities = {
+        ...BASE_CAPABILITIES,
+    };
+    for (const [name, value] of Object.entries(options.capabilities ?? {})) {
+        if (value === false) {
+            delete capabilities[name];
+        }
+        else {
+            capabilities[name] = value;
+        }
+    }
+    return validateConfig({
+        mode,
+        isolation: options.isolation ?? "opaque",
+        capabilities,
+        egress: mergeEgress({}, options.egress),
+        theme: {
+            variables: { ...DEFAULT_THEME_VARIABLES, ...options.theme?.variables },
+            event: options.theme?.event ?? DEFAULT_THEME_EVENT,
+        },
+        limits: { ...BASE_LIMITS, ...defaults.limits, ...options.limits },
+        layout: { ...BASE_LAYOUT, ...options.layout },
+        guide: options.guide ?? {},
+        contentOrigins: options.contentOrigins ?? [],
+        embedder: options.embedder ?? {},
+    });
+}
+export const presets = {
+    /**
+     * An HTML fragment or SVG an agent wrote, drawn inline (a card in a conversation): an opaque
+     * frame with the shell, streamed as it is written.
+     */
+    inlineWidget: (options = {}) => build("inline", {}, options),
+    /**
+     * A whole HTML page: written into an opaque frame by the shell where the host has the page, or
+     * served on its own origin (`isolation: "domain"`). A document scrolls inside past a shorter cap.
+     */
+    artifact: (options = {}) => build("artifact", { limits: { maxHeightPx: 720, minHeightPx: 120 } }, options),
+    /**
+     * A standard MCP Apps view, through an MCP Apps adapter. The view's own `_meta.ui.csp` is
+     * mapped into `egress` by that adapter; the host declares the capabilities it serves.
+     */
+    mcpApp: (options = {}) => build("mcp-app", {}, options),
+    /**
+     * A running app by URL (a dev server's preview): frame, isolation and access auth only. No
+     * shell, no capabilities, no egress control: the app is someone else's, on its own origin.
+     */
+    url: (options) => validateConfig({
+        mode: "url",
+        isolation: "external",
+        capabilities: {},
+        egress: {},
+        theme: { variables: {}, event: DEFAULT_THEME_EVENT },
+        limits: { ...BASE_LIMITS, maxHeightPx: 4_000, minHeightPx: 120, ...options.limits },
+        layout: { ...BASE_LAYOUT, ...options.layout },
+        guide: {},
+        contentOrigins: options.contentOrigins,
+        embedder: options.embedder ?? {},
+    }),
+};

package/dist/protocol/adapter.d.ts

@@ -0,0 +1,73 @@
+import type { HostFunctionBridge } from "../bridge/types.ts";
+import type { CompiledConfig } from "../compile/compile.ts";
+import type { Transport } from "../transport/types.ts";
+import type { HostContext } from "./mcp-apps.ts";
+/**
+ * The protocol-adapter seam (P004): the only layer that knows a wire protocol's method names and
+ * shapes. The framework speaks capabilities and lifecycle; an adapter translates.
+ *
+ * - Frame → host: the adapter validates each message (dropping what it doesn't recognize, and
+ *   answering an unknown request with "method not found"), turns every capability use into
+ *   `bridge.call(...)` (including sizes and errors, which the bridge turns into the framework's
+ *   own events), answers the handshake with `hostContext()`, and reports lifecycle with `emit`.
+ * - Host → frame: the framework calls the connection; the adapter encodes and sends.
+ *
+ * The bridge alone decides whether a call runs (declared, valid, gated); an adapter never calls a
+ * host handler itself.
+ */
+/** What the framework gives an adapter for one display. */
+export interface AdapterSession {
+    readonly display: {
+        readonly id: string;
+        readonly title: string;
+    };
+    readonly compiled: CompiledConfig;
+    readonly transport: Transport;
+    readonly bridge: HostFunctionBridge;
+    readonly hostInfo: {
+        readonly name: string;
+        readonly version: string;
+    };
+    /** The host context as of now: theme, its variables, display mode, sizes, locale. */
+    hostContext(): HostContext;
+    /** Lifecycle the framework acts on. */
+    emit(event: AdapterEvent): void;
+    /**
+     * The mount's whole document, when the host passed one (an MCP Apps view): for an adapter that
+     * delivers it itself, as through a sandbox proxy. In opaque isolation the framework has already
+     * put it in the frame, hardened.
+     */
+    readonly document?: string;
+}
+export type AdapterEvent = 
+/** The view finished its handshake; content may be sent. */
+{
+    readonly type: "initialized";
+}
+/** The view asked to be closed. */
+ | {
+    readonly type: "teardown-requested";
+};
+/** What the framework drives on every adapter. Adapters add their protocol's own operations. */
+export interface AdapterConnection {
+    /** The host context changed (a theme flip, a new width): tell the view. */
+    hostContextChanged(context: HostContext): void;
+    /** Asks the view to clean up before it is removed; resolves when it answered or gave up. */
+    teardown(): Promise<void>;
+    /** Stops listening. The framework closes the transport. */
+    close(): void;
+}
+export interface ProtocolAdapter<C extends AdapterConnection = AdapterConnection> {
+    readonly name: string;
+    connect(session: AdapterSession): C;
+}
+/**
+ * The core adapter's connection: the MCP Apps subset the shell speaks (inline widgets, artifact
+ * pages). Content goes as `tool-input-partial` while it is written, then `tool-input` once.
+ */
+export interface ShellConnection extends AdapterConnection {
+    /** The content so far (`partial`, drawn inert, any number of times), then whole, once. */
+    setContent(html: string, options?: {
+        readonly partial?: boolean;
+    }): void;
+}

package/dist/protocol/adapter.js

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