@botiverse/porthole 0.0.0-stage → 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,23 @@
+/**
+ * `@botiverse/porthole`: the framework-agnostic core. One config (a preset's) compiles into the
+ * frame's policies, the shell, and the agent manual; the host mounts displays under it.
+ */
+export { CAPABILITIES, CAPABILITY_NAMES, capabilitySpec, isCapabilityName, type CapabilityArgs, type CapabilityName, type CapabilityResults, type CapabilitySpec, type Gate, type HandledCapability, } from "./config/capabilities.ts";
+export type { CapabilityConfig, CapabilityMap, ColorScheme, DisplayMode, EgressConfig, EmbedderConfig, GuideConfig, IsolationKind, LayoutConfig, Limits, PortholeConfig, ThemeConfig, ThemeValue, } from "./config/schema.ts";
+export { BUILT_IN_TOPICS, ConfigError, isOriginSource, validateConfig } from "./config/validate.ts";
+export { LIBRARY_CDNS, presets, type PresetName, type PresetOptions, type UrlPresetOptions, } from "./presets/presets.ts";
+export { compile, type CompiledConfig } from "./compile/compile.ts";
+export { allEgressOrigins, declaredCapabilities, effectiveGates, egressOrigins, embedderCsp, type CspDirective, type EgressKind, } from "./compile/policy.ts";
+export { shellPlan, type ShellPlan } from "./shell/plan.ts";
+export type { ShellDocumentOptions } from "./shell/document.ts";
+export { generateGuide, generateToolDescription, type BuiltInTopic, type GuideTopic, } from "./guide/guide.ts";
+export { GUIDE_EXAMPLES, type GuideExample } from "./guide/examples.ts";
+export { CHART_PALETTE, DEFAULT_THEME, DEFAULT_THEME_EVENT, DEFAULT_THEME_VARIABLES, resolveTheme, themeDefault, } from "./theme/variables.ts";
+export type { FrameLocation, FrameSource, InstanceLocator, InstanceRef, ServedDocument, } from "./isolation/types.ts";
+export type { PlatformHost, Surface, SurfaceSpec } from "./platform/types.ts";
+export type { Transport } from "./transport/types.ts";
+export type { AdapterConnection, AdapterEvent, AdapterSession, ProtocolAdapter, ShellConnection, } from "./protocol/adapter.ts";
+export { MCP_APPS_METHODS, MCP_APPS_PROTOCOL_VERSION, MCP_APPS_STYLE_VARIABLES, PORTHOLE_STYLES, type HostContext, } from "./protocol/mcp-apps.ts";
+export type { CallContext, CallOutcome, CapabilityHandler, CapabilityHandlers, Confirm, ConfirmRequest, HostFunctionBridge, Refusal, } from "./bridge/types.ts";
+export { createHost } from "./host/create-host.ts";
+export type { DisplayControls, DisplayEvents, DisplayHandle, HostOptions, MountOptions, PortholeHost, } from "./host/types.ts";

package/dist/index.js

@@ -0,0 +1,19 @@
+/**
+ * `@botiverse/porthole`: the framework-agnostic core. One config (a preset's) compiles into the
+ * frame's policies, the shell, and the agent manual; the host mounts displays under it.
+ */
+// The config and its vocabulary.
+export { CAPABILITIES, CAPABILITY_NAMES, capabilitySpec, isCapabilityName, } from "./config/capabilities.js";
+export { BUILT_IN_TOPICS, ConfigError, isOriginSource, validateConfig } from "./config/validate.js";
+// Presets.
+export { LIBRARY_CDNS, presets, } from "./presets/presets.js";
+// The compiler.
+export { compile } from "./compile/compile.js";
+export { allEgressOrigins, declaredCapabilities, effectiveGates, egressOrigins, embedderCsp, } from "./compile/policy.js";
+export { shellPlan } from "./shell/plan.js";
+export { generateGuide, generateToolDescription, } from "./guide/guide.js";
+export { GUIDE_EXAMPLES } from "./guide/examples.js";
+// Theme.
+export { CHART_PALETTE, DEFAULT_THEME, DEFAULT_THEME_EVENT, DEFAULT_THEME_VARIABLES, resolveTheme, themeDefault, } from "./theme/variables.js";
+export { MCP_APPS_METHODS, MCP_APPS_PROTOCOL_VERSION, MCP_APPS_STYLE_VARIABLES, PORTHOLE_STYLES, } from "./protocol/mcp-apps.js";
+export { createHost } from "./host/create-host.js";

package/dist/isolation/served.d.ts

@@ -0,0 +1,32 @@
+import type { FrameLocation } from "./types.ts";
+interface ParsedOrigin {
+    readonly scheme: string;
+    readonly host: string;
+    readonly port: string;
+}
+/** `scheme://host[:port]`, lowercase, nothing else; null for anything that isn't exactly that. */
+export declare function parseOrigin(origin: string): ParsedOrigin | null;
+/** Whether `origin` is an exact origin (`https://host[:port]`, lowercase, no path). */
+export declare function isExactOrigin(origin: unknown): origin is string;
+/**
+ * Whether two hosts may be the same site. Without the public-suffix list this errs one way only:
+ * it says "same site" whenever the hosts are equal or share their last two labels, so a pair it
+ * calls cross-site always is (a refused pair, like `a.github.io` and `b.github.io`, may not be:
+ * a safe failure). An IP address is a site of its own; `localhost`'s subdomains are each one, as
+ * browsers treat an unlisted top-level name as a public suffix.
+ */
+export declare function maybeSameSite(hostA: string, hostB: string): boolean;
+/**
+ * Whether `origin` matches a frame source as the config writes them (`https://*.example.com`,
+ * `http://*.localhost:8790`, or an exact origin): same scheme and port; `*.` matches one or more
+ * labels below the name, never the name itself.
+ */
+export declare function originMatchesSource(origin: string, source: string): boolean;
+/**
+ * Throws unless `location` is a frame a host on `hostOrigin` may load for a config whose content
+ * is served from `contentOrigins`: its URL is on its stated origin, that origin is one the config
+ * names, and it is not of the host's own site (a same-site frame with `allow-same-origin` could
+ * reach cookies and storage the host shares with its site).
+ */
+export declare function checkFrameLocation(location: FrameLocation, contentOrigins: readonly string[], hostOrigin: string): void;
+export {};

package/dist/isolation/served.js

@@ -0,0 +1,97 @@
+/**
+ * Checks for served frames (domain and external isolation), shared by the host's mount and by
+ * `/server`: a served origin must be one the config names, and never of the host's own site
+ * (P016, P020). Pure, no DOM and no Node, so both sides run the same code.
+ */
+const EXACT_ORIGIN = /^(https?):\/\/([a-z0-9.-]+|\[[0-9a-f:.]+\])(?::(\d{1,5}))?$/u;
+const IPV4 = /^\d{1,3}(\.\d{1,3}){3}$/u;
+const DEFAULT_PORTS = { http: "80", https: "443" };
+/** `scheme://host[:port]`, lowercase, nothing else; null for anything that isn't exactly that. */
+export function parseOrigin(origin) {
+    const match = EXACT_ORIGIN.exec(origin);
+    if (match === null) {
+        return null;
+    }
+    const [, scheme = "", host = "", port] = match;
+    return { scheme, host, port: port ?? DEFAULT_PORTS[scheme] ?? "" };
+}
+/** Whether `origin` is an exact origin (`https://host[:port]`, lowercase, no path). */
+export function isExactOrigin(origin) {
+    return typeof origin === "string" && parseOrigin(origin) !== null;
+}
+/**
+ * Whether two hosts may be the same site. Without the public-suffix list this errs one way only:
+ * it says "same site" whenever the hosts are equal or share their last two labels, so a pair it
+ * calls cross-site always is (a refused pair, like `a.github.io` and `b.github.io`, may not be:
+ * a safe failure). An IP address is a site of its own; `localhost`'s subdomains are each one, as
+ * browsers treat an unlisted top-level name as a public suffix.
+ */
+export function maybeSameSite(hostA, hostB) {
+    const a = hostA.toLowerCase().replace(/\.$/u, "");
+    const b = hostB.toLowerCase().replace(/\.$/u, "");
+    if (a === b) {
+        return true;
+    }
+    if (IPV4.test(a) || IPV4.test(b) || a.startsWith("[") || b.startsWith("[")) {
+        return false;
+    }
+    const labelsA = a.split(".").toReversed();
+    const labelsB = b.split(".").toReversed();
+    let shared = 0;
+    while (shared < labelsA.length &&
+        shared < labelsB.length &&
+        labelsA[shared] === labelsB[shared]) {
+        shared += 1;
+    }
+    return shared >= 2;
+}
+/**
+ * Whether `origin` matches a frame source as the config writes them (`https://*.example.com`,
+ * `http://*.localhost:8790`, or an exact origin): same scheme and port; `*.` matches one or more
+ * labels below the name, never the name itself.
+ */
+export function originMatchesSource(origin, source) {
+    const parsed = parseOrigin(origin);
+    const wildcard = /^(https?):\/\/\*\.([a-z0-9.-]+)(?::(\d{1,5}))?$/u.exec(source);
+    if (parsed === null) {
+        return false;
+    }
+    if (wildcard === null) {
+        const exact = parseOrigin(source);
+        return (exact !== null &&
+            exact.scheme === parsed.scheme &&
+            exact.host === parsed.host &&
+            exact.port === parsed.port);
+    }
+    const [, scheme = "", suffix = "", port] = wildcard;
+    return (scheme === parsed.scheme &&
+        (port ?? DEFAULT_PORTS[scheme]) === parsed.port &&
+        parsed.host.endsWith(`.${suffix}`) &&
+        parsed.host.length > suffix.length + 1);
+}
+/**
+ * Throws unless `location` is a frame a host on `hostOrigin` may load for a config whose content
+ * is served from `contentOrigins`: its URL is on its stated origin, that origin is one the config
+ * names, and it is not of the host's own site (a same-site frame with `allow-same-origin` could
+ * reach cookies and storage the host shares with its site).
+ */
+export function checkFrameLocation(location, contentOrigins, hostOrigin) {
+    const origin = parseOrigin(location.origin);
+    let url;
+    try {
+        url = new URL(location.url);
+    }
+    catch {
+        throw new TypeError(`The located URL ${JSON.stringify(location.url)} is not a URL`);
+    }
+    if (origin === null || url.origin !== location.origin) {
+        throw new TypeError(`The located URL ${JSON.stringify(location.url)} is not on its origin ${JSON.stringify(location.origin)}`);
+    }
+    if (!contentOrigins.some((source) => originMatchesSource(location.origin, source))) {
+        throw new TypeError(`The located origin ${location.origin} is not one of the config's content origins`);
+    }
+    const host = parseOrigin(hostOrigin);
+    if (host !== null && maybeSameSite(origin.host, host.host)) {
+        throw new TypeError(`The located origin ${location.origin} may be the same site as the host (${hostOrigin}): content must be served from a registrable domain the host uses for nothing else`);
+    }
+}

package/dist/isolation/types.d.ts

@@ -0,0 +1,87 @@
+/**
+ * The isolation-mode seam. Opaque frames need nothing from outside: the host builds the shell
+ * document and the frame is `srcdoc`. Served modes (domain, and url mode's external app) load a
+ * URL, so the host asks a locator for one; the locator is the host's own code, typically a call to
+ * the host's backend, which asks `/server` for a ticketed URL after deciding the viewer may see it.
+ *
+ * Storage is keyed by origin. In domain mode each storage scope gets its own subdomain of the
+ * content domain (`<label>.example-usercontent.com`, the label derived from the scope by `/server`,
+ * not guessable from it), so content with the same scope shares an origin and its storage and
+ * nothing else does. The host chooses the scope (PRINCIPLE 8): per display, per conversation, per
+ * app. Browsers partition a framed origin's storage by the top-level site, so it is stable within
+ * one host app.
+ */
+import type { EgressConfig } from "../config/schema.ts";
+/**
+ * Which document a served frame loads. `preset` names the config it is served under (the server's
+ * `configs`); the artifact and the proxy default to their presets' names.
+ */
+export type ServedDocument = 
+/** The shell, served with its CSP in headers; content arrives over the transport as for opaque. */
+{
+    readonly kind: "shell";
+    readonly preset: string;
+}
+/** A stored page (artifact mode), by id and version: versions are immutable. */
+ | {
+    readonly kind: "artifact";
+    readonly id: string;
+    readonly version: string;
+    /** Default `artifact`. */
+    readonly preset?: string;
+}
+/**
+ * The MCP Apps sandbox proxy: a second origin the host hands the view's HTML to, which becomes
+ * the view. `egress` is what the view declares (`_meta.ui.csp`, mapped by `/mcp`'s
+ * `viewEgress`), opened on top of the config's: its CSP goes out in the proxy's headers, before
+ * the HTML arrives.
+ */
+ | {
+    readonly kind: "mcp-proxy";
+    readonly preset?: string;
+    readonly egress?: EgressConfig;
+}
+/**
+ * Someone else's running app (url mode), e.g. a dev server behind the host's preview gateway:
+ * `url` is where the host's upstream finds it; the frame lands on its path and query.
+ */
+ | {
+    readonly kind: "external";
+    readonly url: string;
+};
+/** One served instance: where its storage lives, and what it shows. */
+export interface InstanceRef {
+    /**
+     * What the content's origin, and so its storage, is keyed by. Instances with the same scope
+     * share an origin. Opaque to Porthole: the host picks it (a display id, an app id).
+     */
+    readonly scope: string;
+    readonly document: ServedDocument;
+}
+/** Where a served frame loads from. */
+export interface FrameLocation {
+    /** The URL the frame loads, carrying a one-time ticket where the content is private. */
+    readonly url: string;
+    /** Its origin: the host takes messages only from this origin, from this frame. */
+    readonly origin: string;
+}
+/**
+ * Turns an instance into the URL its frame loads. Implemented by the host, usually by asking its
+ * own backend (which authenticates the viewer and calls `PortholeServer.issue`). Called on every
+ * mount: a ticket is good once.
+ */
+export interface InstanceLocator {
+    locate(instance: InstanceRef, signal?: AbortSignal): Promise<FrameLocation>;
+}
+/**
+ * Where a frame's document comes from: built by the host (`srcdoc`, opaque isolation), or loaded
+ * from a URL (domain and external isolation).
+ */
+export type FrameSource = {
+    readonly kind: "srcdoc";
+    readonly html: string;
+} | {
+    readonly kind: "url";
+    readonly url: string;
+    readonly origin: string;
+};

package/dist/isolation/types.js

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

package/dist/mcp/adapter.d.ts

@@ -0,0 +1,43 @@
+import type { AdapterConnection, ProtocolAdapter } from "../protocol/adapter.ts";
+import { type HostContext } from "../protocol/mcp-apps.ts";
+/**
+ * The MCP Apps adapter (P004, P007): the host side of the protocol for full MCP Apps views, written
+ * against the core's seams and no SDK. It answers the view's handshake with the host context and
+ * the capabilities the config declares, carries the view's requests into the bridge (which alone
+ * decides whether they run), reports sizes, errors and teardown requests, and sends the view its
+ * tool input, result and cancellation, never before the view said it was initialized (spec §
+ * Sandbox proxy, 6). Behind the sandbox proxy it hands the proxy the view's HTML first.
+ */
+/** The tool call a view was made for: its host context's `toolInfo`. */
+export interface ToolInfo {
+    /** The JSON-RPC id of the `tools/call`. */
+    readonly id?: string | number;
+    /** The tool's definition (name, input schema, …) as the server listed it. */
+    readonly tool: Readonly<Record<string, unknown>>;
+}
+export interface McpAppsAdapterOptions {
+    /** The tool call each display shows, by display id. */
+    readonly toolInfo?: (displayId: string) => ToolInfo | undefined;
+    /** How long `teardown` waits for the view's answer, ms (default 3000). */
+    readonly teardownTimeoutMs?: number;
+}
+/** A tool's result as MCP carries it (`CallToolResult`): content, structured content, `_meta`. */
+export type ToolResult = Readonly<Record<string, unknown>>;
+/** What a host drives on an MCP Apps view, besides the framework's own controls. */
+export interface McpAppConnection extends AdapterConnection {
+    /** The tool's arguments so far, while the agent writes them (dropped once the whole went). */
+    sendToolInputPartial(args: Readonly<Record<string, unknown>>): void;
+    /** The tool's whole arguments, once. */
+    sendToolInput(args: Readonly<Record<string, unknown>>): void;
+    /** The tool's result. */
+    sendToolResult(result: ToolResult): void;
+    /** The tool call was cancelled (by the person, an error, a policy). */
+    sendToolCancelled(reason?: string): void;
+}
+/**
+ * The host context as a view may receive it: Porthole's fields as they are, its theme variables
+ * cut to the names the standard defines (the official SDK refuses any other).
+ */
+export declare function viewHostContext(context: HostContext, toolInfo?: ToolInfo): Readonly<Record<string, unknown>>;
+/** The MCP Apps adapter: pass it as `HostOptions.adapter` with the `mcpApp` preset. */
+export declare function mcpAppsAdapter(options?: McpAppsAdapterOptions): ProtocolAdapter<McpAppConnection>;

package/dist/mcp/adapter.js

@@ -0,0 +1,327 @@
+import { egressOrigins } from "../compile/policy.js";
+import { JSON_RPC_ERRORS, parseJsonRpc, } from "../protocol/jsonrpc.js";
+import { MCP_APPS_METHODS, MCP_APPS_PROTOCOL_VERSION, } from "../protocol/mcp-apps.js";
+import { MCP_APPS_STYLE_VARIABLES } from "../protocol/mcp-apps.js";
+const isRecord = (value) => value !== null && typeof value === "object" && !Array.isArray(value);
+/** Levels of `notifications/message` that are errors: they go to the host as `reportError`. */
+const ERROR_LEVELS = new Set(["error", "critical", "alert", "emergency"]);
+const DISPLAY_MODES = new Set(["inline", "fullscreen", "pip"]);
+const STYLE_VARIABLES = new Set(MCP_APPS_STYLE_VARIABLES);
+/**
+ * The host context as a view may receive it: Porthole's fields as they are, its theme variables
+ * cut to the names the standard defines (the official SDK refuses any other).
+ */
+export function viewHostContext(context, toolInfo) {
+    const out = {};
+    for (const [key, value] of Object.entries(context)) {
+        if (value !== undefined && key !== "styles") {
+            out[key] = value;
+        }
+    }
+    const variables = {};
+    for (const [name, value] of Object.entries(context.styles?.variables ?? {})) {
+        if (STYLE_VARIABLES.has(name) && typeof value === "string") {
+            variables[name] = value;
+        }
+    }
+    out.styles = { variables };
+    if (toolInfo !== undefined) {
+        out.toolInfo = toolInfo;
+    }
+    return out;
+}
+/** The text of a `ui/message`'s content: its text blocks, in order (the spec's examples send one). */
+function messageText(content) {
+    const blocks = Array.isArray(content) ? content : [content];
+    const texts = blocks.flatMap((block) => isRecord(block) && block.type === "text" && typeof block.text === "string" ? [block.text] : []);
+    return texts.length === 0 ? null : texts.join("\n\n");
+}
+/** Whether the host page has a live user gesture (a gesture in a frame activates its ancestors). */
+function hostActivation() {
+    const activation = globalThis
+        .navigator?.userActivation;
+    return activation === undefined ? undefined : activation.isActive;
+}
+function connect(session, options) {
+    const { transport, bridge } = session;
+    let closed = false;
+    let initialized = false;
+    let inputSent = false;
+    let resourceSent = false;
+    /** What the host said before the view was initialized: sent, in order, once it is. */
+    let queue = [];
+    const pending = new Map();
+    let nextId = 1;
+    const send = (message) => {
+        if (!closed) {
+            transport.send(message);
+        }
+    };
+    const notify = (method, params) => {
+        const message = { jsonrpc: "2.0", method, params };
+        if (initialized) {
+            send(message);
+        }
+        else {
+            queue.push(message);
+        }
+    };
+    const answer = (id, result) => send({ jsonrpc: "2.0", id, result });
+    const refuse = (id, code, message) => send({ jsonrpc: "2.0", id, error: { code, message } });
+    const hostCapabilities = () => {
+        const declared = (name) => bridge.declared(name);
+        const { config } = session.compiled;
+        const connectDomains = egressOrigins(config, "connect");
+        const resourceDomains = [
+            ...new Set(["script", "style", "img", "font", "media"].flatMap((kind) => egressOrigins(config, kind))),
+        ];
+        return {
+            logging: {},
+            ...(declared("openLink") ? { openLinks: {} } : {}),
+            ...(declared("downloadFile") ? { downloadFile: {} } : {}),
+            ...(declared("callTool") ? { serverTools: {} } : {}),
+            ...(declared("readData") ? { serverResources: {} } : {}),
+            ...(declared("sendPrompt") ? { message: { text: {} } } : {}),
+            ...(declared("setModelContext")
+                ? { updateModelContext: { text: {}, structuredContent: {} } }
+                : {}),
+            sandbox: {
+                csp: {
+                    ...(connectDomains.length > 0 ? { connectDomains } : {}),
+                    ...(resourceDomains.length > 0 ? { resourceDomains } : {}),
+                },
+            },
+        };
+    };
+    /** Runs a capability through the bridge and answers the request with what it gives. */
+    async function call(request, capability, args, result) {
+        const userActivated = hostActivation();
+        let outcome;
+        try {
+            outcome = await bridge.call(capability, args, userActivated === undefined ? undefined : { userActivated });
+        }
+        catch {
+            refuse(request.id, JSON_RPC_ERRORS.internal, `${request.method} failed`);
+            return;
+        }
+        if (outcome.ok) {
+            answer(request.id, result(outcome.value));
+        }
+        else if (outcome.refusal === "not-declared") {
+            refuse(request.id, JSON_RPC_ERRORS.methodNotFound, `${request.method} isn't offered here`);
+        }
+        else {
+            // The spec's "implementation-defined" error for a refused request.
+            refuse(request.id, -32_000, `${request.method} refused (${outcome.refusal})`);
+        }
+    }
+    /** `{}` when a host function did it, `{ isError: true }` when it said it couldn't. */
+    const done = (value) => value === false ? { isError: true } : {};
+    async function onRequest(request) {
+        const params = request.params ?? {};
+        const invalid = (what) => refuse(request.id, JSON_RPC_ERRORS.invalidParams, `${request.method}: ${what}`);
+        switch (request.method) {
+            case MCP_APPS_METHODS.initialize:
+                answer(request.id, {
+                    protocolVersion: MCP_APPS_PROTOCOL_VERSION,
+                    hostInfo: session.hostInfo,
+                    hostCapabilities: hostCapabilities(),
+                    hostContext: viewHostContext(session.hostContext(), options.toolInfo?.(session.display.id)),
+                });
+                return;
+            case "ping":
+                answer(request.id, {});
+                return;
+            case MCP_APPS_METHODS.message: {
+                const text = params.role === "user" ? messageText(params.content) : null;
+                if (text === null) {
+                    invalid('needs role "user" and text content');
+                    return;
+                }
+                await call(request, "sendPrompt", { text }, done);
+                return;
+            }
+            case MCP_APPS_METHODS.openLink:
+                if (typeof params.url !== "string") {
+                    invalid("needs a url");
+                    return;
+                }
+                await call(request, "openLink", { url: params.url }, done);
+                return;
+            case MCP_APPS_METHODS.downloadFile:
+                if (!Array.isArray(params.contents)) {
+                    invalid("needs contents");
+                    return;
+                }
+                await call(request, "downloadFile", { contents: params.contents }, done);
+                return;
+            case MCP_APPS_METHODS.callTool:
+                if (typeof params.name !== "string" ||
+                    (params.arguments !== undefined && !isRecord(params.arguments))) {
+                    invalid("needs a tool name and object arguments");
+                    return;
+                }
+                await call(request, "callTool", { name: params.name, arguments: params.arguments ?? {} }, (value) => (isRecord(value) ? value : { content: [] }));
+                return;
+            case MCP_APPS_METHODS.readResource:
+                if (typeof params.uri !== "string") {
+                    invalid("needs a uri");
+                    return;
+                }
+                await call(request, "readData", { uri: params.uri }, (value) => isRecord(value) ? value : { contents: [] });
+                return;
+            case MCP_APPS_METHODS.updateModelContext:
+                if ((params.content !== undefined && !Array.isArray(params.content)) ||
+                    (params.structuredContent !== undefined && !isRecord(params.structuredContent))) {
+                    invalid("content is a list, structuredContent an object");
+                    return;
+                }
+                await call(request, "setModelContext", {
+                    ...(params.content === undefined ? {} : { content: params.content }),
+                    ...(params.structuredContent === undefined
+                        ? {}
+                        : { structuredContent: params.structuredContent }),
+                }, () => ({}));
+                return;
+            case MCP_APPS_METHODS.requestDisplayMode: {
+                if (typeof params.mode !== "string" || !DISPLAY_MODES.has(params.mode)) {
+                    invalid("needs a display mode");
+                    return;
+                }
+                // Changing how a display is shown is the host's own layout: the view keeps its mode, and
+                // the answer says so (spec: return the current mode when the request isn't granted).
+                answer(request.id, { mode: session.hostContext().displayMode });
+                return;
+            }
+            default:
+                refuse(request.id, JSON_RPC_ERRORS.methodNotFound, `${request.method} isn't offered here`);
+        }
+    }
+    function onNotification(method, params) {
+        switch (method) {
+            case MCP_APPS_METHODS.sandboxProxyReady:
+                // Behind the sandbox proxy: it takes the view's HTML once, then becomes the view (P026).
+                if (!resourceSent && session.document !== undefined) {
+                    resourceSent = true;
+                    send({
+                        jsonrpc: "2.0",
+                        method: MCP_APPS_METHODS.sandboxResourceReady,
+                        params: { html: session.document },
+                    });
+                }
+                return;
+            case MCP_APPS_METHODS.initialized:
+                if (!initialized) {
+                    initialized = true;
+                    const waiting = queue;
+                    queue = [];
+                    for (const message of waiting) {
+                        send(message);
+                    }
+                    session.emit({ type: "initialized" });
+                }
+                return;
+            case MCP_APPS_METHODS.sizeChanged: {
+                const { height, width } = params;
+                const size = (value) => typeof value === "number" && Number.isFinite(value) && value >= 0;
+                if (size(height)) {
+                    void bridge.call("resize", { height, ...(size(width) ? { width } : {}) });
+                }
+                return;
+            }
+            case MCP_APPS_METHODS.log:
+                if (typeof params.level === "string" && ERROR_LEVELS.has(params.level)) {
+                    const data = params.data;
+                    void bridge.call("reportError", {
+                        message: (typeof data === "string" ? data : (JSON.stringify(data) ?? "")).slice(0, 2_000),
+                    });
+                }
+                return;
+            case MCP_APPS_METHODS.requestTeardown:
+                session.emit({ type: "teardown-requested" });
+                return;
+            default:
+        }
+    }
+    const unlisten = transport.listen((raw) => {
+        const message = parseJsonRpc(raw);
+        if (message === null || closed) {
+            return;
+        }
+        if (!("method" in message)) {
+            const waiting = pending.get(message.id);
+            pending.delete(message.id);
+            waiting?.();
+            return;
+        }
+        if ("id" in message) {
+            void onRequest(message);
+        }
+        else {
+            onNotification(message.method, message.params ?? {});
+        }
+    });
+    return {
+        hostContextChanged(context) {
+            if (initialized) {
+                send({
+                    jsonrpc: "2.0",
+                    method: MCP_APPS_METHODS.hostContextChanged,
+                    params: viewHostContext(context),
+                });
+            }
+        },
+        teardown() {
+            if (closed || !initialized) {
+                return Promise.resolve();
+            }
+            return new Promise((resolve) => {
+                const id = nextId++;
+                const finish = () => {
+                    clearTimeout(timer);
+                    pending.delete(id);
+                    resolve();
+                };
+                const timer = setTimeout(finish, options.teardownTimeoutMs ?? 3_000);
+                pending.set(id, finish);
+                send({ jsonrpc: "2.0", id, method: MCP_APPS_METHODS.resourceTeardown, params: {} });
+            });
+        },
+        close() {
+            closed = true;
+            unlisten();
+            queue = [];
+            for (const waiting of pending.values()) {
+                waiting();
+            }
+        },
+        sendToolInputPartial(args) {
+            if (inputSent) {
+                return;
+            }
+            if (!initialized) {
+                // Only the latest draft matters to a view that hasn't seen any.
+                queue = queue.filter((message) => !("method" in message) || message.method !== MCP_APPS_METHODS.toolInputPartial);
+            }
+            notify(MCP_APPS_METHODS.toolInputPartial, { arguments: args });
+        },
+        sendToolInput(args) {
+            if (inputSent) {
+                return;
+            }
+            inputSent = true;
+            queue = queue.filter((message) => !("method" in message) || message.method !== MCP_APPS_METHODS.toolInputPartial);
+            notify(MCP_APPS_METHODS.toolInput, { arguments: args });
+        },
+        sendToolResult(result) {
+            notify(MCP_APPS_METHODS.toolResult, result);
+        },
+        sendToolCancelled(reason) {
+            notify(MCP_APPS_METHODS.toolCancelled, reason === undefined ? {} : { reason });
+        },
+    };
+}
+/** The MCP Apps adapter: pass it as `HostOptions.adapter` with the `mcpApp` preset. */
+export function mcpAppsAdapter(options = {}) {
+    return { name: "mcp-apps", connect: (session) => connect(session, options) };
+}

package/dist/mcp/index.d.ts

@@ -0,0 +1,27 @@
+/**
+ * `@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, type McpAppConnection, type McpAppsAdapterOptions, type ToolInfo, type ToolResult, } from "./adapter.ts";
+export { sandboxProxyDocument } from "./proxy.ts";
+export { VIEW_MIME_TYPE, readViewResource, viewEgress, type ViewResource } from "./view.ts";
+export type { AdapterConnection, AdapterEvent, AdapterSession, ProtocolAdapter, } from "../protocol/adapter.ts";
+export type { HostContext } from "../protocol/mcp-apps.ts";
+export { MCP_APPS_METHODS, MCP_APPS_PROTOCOL_VERSION, MCP_APPS_STYLE_VARIABLES, PORTHOLE_STYLES, } from "../protocol/mcp-apps.ts";
+export { JSON_RPC_ERRORS, parseJsonRpc, type JsonRpcMessage, type JsonRpcRequest, type JsonRpcResponse, } from "../protocol/jsonrpc.ts";