@botiverse/porthole 0.0.1 → 0.1.1

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";

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,51 @@
+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;
+    /**
+     * Fill the container's height (a url-mode app, which reports no size), at least
+     * `initialHeightPx`, instead of taking the content's.
+     */
+    readonly fill?: boolean;
+    /** 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;
+    /** Every load of the frame's document, the first included. */
+    onLoad(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 {};