@botiverse/porthole 0.0.1 → 0.1.0

package/dist/guide/guide.js

@@ -0,0 +1,261 @@
+import { capabilitySpec } from "../config/capabilities.js";
+import { BUILT_IN_TOPICS } from "../config/validate.js";
+import { declaredCapabilities, effectiveGates, egressOrigins, sandboxTokens, } from "../compile/policy.js";
+import { shellPlan } from "../shell/plan.js";
+import { themeDefault } from "../theme/variables.js";
+import { GUIDE_EXAMPLES } from "./examples.js";
+const VARIABLE = /--[a-z0-9]+(?:-[a-z0-9]+)*/gu;
+function context(config) {
+    const variables = Object.keys(config.theme.variables);
+    const has = (...names) => names.every((name) => variables.includes(name));
+    const declared = new Set(declaredCapabilities(config));
+    const globals = new Set(shellPlan(config)?.globals ?? []);
+    return {
+        config,
+        noun: config.mode === "artifact" ? "page" : config.mode === "mcp-app" ? "view" : "widget",
+        has,
+        when: (text) => (has(...(text.match(VARIABLE) ?? [])) ? text : null),
+        names: (prefix, except = []) => variables
+            .filter((name) => name.startsWith(prefix) && !except.some((other) => name.startsWith(other)))
+            .join(", "),
+        declared: (name) => declared.has(name),
+        global: (name) => globals.has(name),
+    };
+}
+/** Lines, without those left out (null); "" is a blank line, and blank lines never repeat. */
+const lines = (...each) => each
+    .filter((line) => line !== null)
+    .join("\n")
+    .replace(/\n{3,}/gu, "\n\n")
+    .trim();
+const KIND_WORDS = {
+    script: "scripts",
+    style: "styles",
+    font: "fonts",
+    img: "images",
+    media: "audio and video",
+    connect: "data (fetch, WebSocket)",
+};
+/** What content may load, in prose, from the same origins the CSP lists. */
+function network(config) {
+    const kinds = ["script", "style", "font", "img", "media", "connect"];
+    const open = kinds
+        .map((kind) => [kind, egressOrigins(config, kind)])
+        .filter(([, origins]) => origins.length > 0);
+    if (open.length === 0) {
+        return "Network: none. Nothing loads from outside (no scripts, styles, fonts, images or data from any server) and any fetch fails, so write everything inline: SVG and CSS draw charts well.";
+    }
+    // Origins that serve the same kinds go together: "scripts, styles and data from a, b; fonts from c".
+    const byOrigin = new Map();
+    for (const [kind, origins] of open) {
+        for (const origin of origins) {
+            byOrigin.set(origin, [...(byOrigin.get(origin) ?? []), kind]);
+        }
+    }
+    const groups = new Map();
+    for (const [origin, each] of byOrigin) {
+        const words = each.map((kind) => KIND_WORDS[kind]);
+        const key = words.length === 1
+            ? (words[0] ?? "")
+            : `${words.slice(0, -1).join(", ")} and ${words.at(-1)}`;
+        groups.set(key, [...(groups.get(key) ?? []), origin]);
+    }
+    const parts = [...groups].map(([words, origins]) => `${words} from ${origins.join(", ")}`);
+    return `Network: only ${parts.join("; ")}. Anything else fails.`;
+}
+const loadsScripts = (config) => egressOrigins(config, "script").length > 0;
+/** What the sandbox withholds, from the sandbox tokens and the shell's own walls. */
+function forbidden(config) {
+    const tokens = sandboxTokens(config);
+    const items = ["position: fixed", "full screen"];
+    if (!tokens.includes("allow-modals")) {
+        items.push("alert/confirm/prompt");
+    }
+    if (!tokens.includes("allow-forms")) {
+        items.push("forms that submit");
+    }
+    if (!tokens.includes("allow-popups")) {
+        items.push("popups and new windows");
+    }
+    if (!tokens.includes("allow-downloads")) {
+        items.push("downloads");
+    }
+    items.push("clipboard writes", "frames (iframe, object, embed)", "WebRTC");
+    return `Not allowed: ${items.join(", ")}.`;
+}
+function widget(c) {
+    const { config, noun } = c;
+    const { layout, limits } = config;
+    const title = noun === "page" ? "Pages" : noun === "view" ? "Views" : "Widgets";
+    const tool = config.guide.toolName === undefined ? "" : ` (${config.guide.toolName})`;
+    const what = config.mode === "artifact"
+        ? "What you pass: a whole HTML document (<!doctype html>, <head>, <body>). It is written into its frame once all of it has arrived, then its scripts run in order."
+        : config.mode === "mcp-app"
+            ? "What you pass: an MCP Apps view, a whole HTML document that talks to its host through the official App SDK (@modelcontextprotocol/ext-apps) or the protocol's own messages."
+            : "What you pass: SVG that starts with <svg, or an HTML fragment: no <!doctype>, <html>, <head> or <body>. Order it styles, then markup, then scripts: people see the styled markup as you write it, and scripts run once all of it is written, in order, each external one loaded before the next runs.";
+    const height = c.declared("resize")
+        ? `Its height follows its content, at most ${limits.maxHeightPx.toLocaleString("en-US")} px (then it scrolls inside).`
+        : "Its height is fixed by the app: keep it short, or let it scroll inside.";
+    const viewBox = layout.narrowWidthPx + 20;
+    const smallest = Math.round(((13 * layout.minWidthPx) / viewBox) * 10) / 10;
+    const largest = Math.round(((13 * 400) / viewBox) * 10) / 10;
+    const textSize = themeDefault(config.theme.variables["--font-text-md-size"] ?? "14px", "light").replace(/^(\d+(?:\.\d+)?)px$/u, "$1 px");
+    return lines(`# ${title}${tool}`, "", what, "", `Where it runs: in a sandboxed frame as wide as the column it sits in, about ${layout.narrowWidthPx} px on a phone (${layout.minWidthPx} on a small one) and ${layout.wideWidthPx} on a desktop; the same ${noun} is read on both, so never write for one of them. Design for ${layout.narrowWidthPx} first; where the layout depends on the width, read it as it runs (the box's clientWidth, again from a ResizeObserver). ${height} It runs in the person's light or dark theme, and again each time it is shown${loadsScripts(config) ? ": pin library versions" : ""}.`, "", "Sizes that read on a phone:", c.when(`- Words go in HTML (titles, notes, legends, readouts): it keeps its size and wraps. The frame's text is already ${textSize} --font-sans in --color-text-primary; notes --font-text-sm-size, never under 12 px.`), `- An SVG scales with the frame: its text shows at font-size × frame width ÷ viewBox width, so a 680-wide viewBox turns 12 into 5 px on a phone. Draw it for the phone: viewBox="0 0 ${viewBox} H", no text under 13, width="100%" style="max-width: 400px"; its text then shows at ${smallest} to ${largest} px on every screen. Or draw it 1 unit = 1 px with a script (topic chart).`, `- The frame never scrolls sideways: nothing fixed wider than ${layout.minWidthPx} px; images max-width: 100%; a grid or flex child with long text min-width: 0; a wide table or code block in its own box with overflow-x: auto.`, "- Cards in a row wrap (flex-wrap: wrap; flex: 1 1 100px), or a grid of repeat(auto-fit, minmax(160px, 1fr)): at most 2 columns under 500 px, never a fixed repeat(3, …).", "- Touch: anything clickable is at least 44 px tall. Phones don't hover: what a hover shows, a tap (click) shows too.", "", `${forbidden(config)} ${network(config)} Keep it under ${Math.floor(limits.maxBytes / 1000)} KB.`, loadsScripts(config)
+        ? "\nLibraries: pin an exact version at least two weeks old (chart.js@4.4.1 in its URL), never @latest or a range, so the code can't be swapped under you and draws the same every time."
+        : null, "", `Colors: every color from these variables, never hard-coded, so light and dark both work. The ${noun}'s own background is transparent (it sits on the app's surface).`, c.names("--color-background-") === "" ? null : `- Surfaces: ${c.names("--color-background-")}`, c.names("--color-text-") === "" ? null : `- Text: ${c.names("--color-text-")}`, c.names("--color-border-") === ""
+        ? null
+        : `- Borders: ${c.names("--color-border-")}${c.names("--color-ring-") === "" ? "" : `; focus rings: ${c.names("--color-ring-")}`}`, c.names("--color-accent") === ""
+        ? null
+        : `- Accent: ${[
+            c.when("--color-accent (a button)"),
+            c.when("--color-accent-soft (a selected item's fill)"),
+            c.when("in a figure, --color-chart-1 (topic chart)"),
+        ]
+            .filter((part) => part !== null)
+            .join("; ")}`, c.names("--font-") === "" ? null : `- Type: ${c.names("--font-")}`, c.names("--border-") === "" && c.names("--shadow-") === ""
+        ? null
+        : `- Shape: ${[c.names("--border-"), c.names("--shadow-")].filter((each) => each !== "").join(", ")}`, otherVariables(c) === "" ? null : `- Also: ${otherVariables(c)}`, "", exampleFits(c, GUIDE_EXAMPLES.stats)
+        ? `Cards that read in both themes, and wrap on a phone:\n${GUIDE_EXAMPLES.stats}\n`
+        : null, c.when(`Don't use --color-background-primary as a card's fill: it is the app's own surface, so a card on it vanishes.`), `A theme change updates the variables in place and fires window "${config.theme.event}": CSS that uses var(...) follows by itself; a canvas or a library you gave colors to must redraw.`, config.mode === "inline"
+        ? "Buttons and inputs already match the app (its borders, radius, colors and focus ring, 44 px tall): use them as they are, or restyle them with your own CSS."
+        : null, "", "Diagrams (boxes and arrows): show the mechanism asked about (what calls what, where data goes), only the parts the ask names; label each arrow with what moves.", `- Top to bottom, at most 2 boxes a row, in the phone viewBox; the title in HTML above. Too much for one glance on a phone: make two.`, "- SVG doesn't wrap: break lines yourself. A box is its longest line + 24 wide (13 px text takes about 7 units a character, a 14 px bold name 8.5: a 136-wide box holds 16); a name and a line, 52 tall; 16 between boxes.", c.when("- Boxes fill none, stroke --color-border-secondary; at most one stands out: stroke --color-chart-1, 2 wide, fill --color-chart-1 at fill-opacity 0.12. Arrows --color-text-tertiary, in the gaps, never across a box, their labels beside them. Every <text> sets fill: names --color-text-primary, the rest --color-text-secondary."), exampleFits(c, GUIDE_EXAMPLES.diagram) ? `\n${GUIDE_EXAMPLES.diagram}` : null);
+}
+/** Variables outside the groups the colors list names. */
+function otherVariables(c) {
+    const grouped = [
+        "--color-background-",
+        "--color-text-",
+        "--color-border-",
+        "--color-ring-",
+        "--color-accent",
+        "--color-chart-",
+        "--font-",
+        "--border-",
+        "--shadow-",
+    ];
+    return Object.keys(c.config.theme.variables)
+        .filter((name) => !grouped.some((prefix) => name.startsWith(prefix)))
+        .join(", ");
+}
+/** Whether an example uses only declared variables and loads nothing. */
+function exampleFits(c, example) {
+    return c.has(...(example.match(VARIABLE) ?? [])) && !/https?:\/\//u.test(example);
+}
+function chart(c) {
+    const { config } = c;
+    const categorical = Object.keys(config.theme.variables).filter((name) => /^--color-chart-\d+$/u.test(name));
+    const sequential = Object.keys(config.theme.variables).filter((name) => /^--color-chart-seq-\d+$/u.test(name));
+    const libraries = loadsScripts(config)
+        ? `Libraries (Chart.js, ECharts, d3) draw in px too, in a box with a set height (Chart.js responsive: true, maintainAspectRatio: false). They don't read CSS variables: pass in getComputedStyle(document.documentElement).getPropertyValue("${categorical[0] ?? "--color-text-primary"}").trim(), redraw on window "${config.theme.event}", and override their palette and white background.`
+        : "No chart library loads here: draw the SVG yourself, from a script, as below.";
+    return lines(`# Charts (a chart is a ${c.noun})`, "", "Pick the form first: a trend over time → line; compare categories → horizontal bars; x against y → scatter; one number → a big number, not a chart; a few numbers → a table, not a chart.", "", "The look:", '- The title states the finding, with its number ("Failed builds fell from 9 to 2 a week"), not the topic; a line under it says what is measured, in what unit.', c.when("- Grey first: the data in a quiet grey (--color-text-disabled), one accent (--color-chart-1) on what the title is about. More hues only for series that differ in kind and must each be found."), "- Values on the marks or a light axis, not both; label only the points the finding rests on. Bars start at zero.", "- Write the numbers once, as rows, and draw marks, labels and readout from them.", "", "Size: draw it at the frame's width, 1 unit = 1 px: read the box's clientWidth, draw an <svg> that wide with 12 px text, and again from a ResizeObserver. Its text stays 12 px on every screen; keep x labels 44 px apart. No script: the phone viewBox (topic widget). Bars need no SVG: an HTML grid row per category.", "", libraries, "", categorical.length === 0 ? null : "Colors:", categorical.length === 0
+        ? null
+        : `- Series of different kinds: ${categorical[0]} … ${categorical.at(-1)}, in this order, never cycled, at most ${categorical.length} (fold the rest into "Other"); a series keeps its color when a filter hides others.`, sequential.length === 0
+        ? null
+        : `- Magnitude (a heatmap): ${sequential[0]} … ${sequential.at(-1)}, 1 nearest zero.${c.has("--color-chart-neg", "--color-chart-mid", "--color-chart-pos") ? " Above or below a midpoint: --color-chart-neg, --color-chart-mid, --color-chart-pos." : ""}`, c.when("- Never a rainbow. Status (good, bad) uses --color-text-success, --color-text-warning, --color-text-danger with a word, never as a series color."), c.when("- Text is never in a series color: --color-text-primary or --color-text-secondary; the mark beside it carries identity."), "", c.when("Marks: 2 px lines, bars with a 2 px gap; grid lines --color-border-tertiary, 1 px; one y axis (two scales: two charts); the legend in HTML."), "", 'Reading values: a readout line in HTML that a tap on a column fills (each column a hit area the plot\'s height), the latest values shown before any tap; a "Table" toggle for the numbers.', exampleFits(c, GUIDE_EXAMPLES.line)
+        ? `\nA line chart drawn at the frame's width, its numbers on a tap:\n${GUIDE_EXAMPLES.line}`
+        : null, exampleFits(c, GUIDE_EXAMPLES.bars)
+        ? `\nBars in HTML, under a title like the line chart's:\n${GUIDE_EXAMPLES.bars}`
+        : null);
+}
+/** How a capability's gates read to the author: one sentence each. */
+function gateWords(gates, effect) {
+    const sentences = [];
+    if (gates.includes("confirm")) {
+        sentences.push(`The app shows the person ${effect} first, and nothing happens unless they confirm.`);
+    }
+    if (gates.includes("user-activation")) {
+        sentences.push("Call it from a click (it needs one).");
+    }
+    for (const gate of gates) {
+        if (typeof gate === "object") {
+            sentences.push(`At most ${gate.rateLimit.perMinute} a minute.`);
+        }
+    }
+    return sentences.join(" ");
+}
+const ENTRIES = {
+    sendPrompt: (c, gates) => c.global("sendPrompt")
+        ? `- sendPrompt(text): asks to send text to you as the person's message (at most ${c.config.limits.maxPromptChars.toLocaleString("en-US")} characters). Use it for "explain this point", "try these settings". ${gateWords(gates, "the whole text")} It returns a promise: true if it was sent.`
+        : `- Messages: the MCP Apps request ui/message (with the App SDK, app.sendMessage) asks to send text to you as the person's message. ${gateWords(gates, "the whole text")}`,
+    openLink: (c, gates) => c.global("openLink")
+        ? `- openLink(url): asks to open an http(s) link in a new tab; a click on an <a href> does the same for you. ${gateWords(gates, "the link")} It returns a promise: true if it opened.`
+        : `- Links: the MCP Apps request ui/open-link (with the App SDK, app.openLink) asks to open an http(s) link in a new tab. ${gateWords(gates, "the link")}`,
+    downloadFile: (_c, gates) => `- Downloads: the MCP Apps request ui/download-file (with the App SDK, app.downloadFile). ${gateWords(gates, "the file")}`,
+    callTool: (_c, gates) => `- Tools: the MCP Apps request tools/call (with the App SDK, app.callServerTool). ${gateWords(gates, "the call")}`,
+    readData: (_c, gates) => `- Data: the MCP Apps request resources/read (with the App SDK, app.readServerResource). ${gateWords(gates, "the request")}`,
+    setModelContext: (_c, gates) => `- Context for the agent: the MCP Apps request ui/update-model-context (with the App SDK, app.updateModelContext). ${gateWords(gates, "it")}`,
+    reportError: (c, gates) => `- Errors: what your code throws, and anything the sandbox blocks, is reported to the app (at most ${c.config.limits.maxErrorReports} a run). ${gateWords(gates, "it")}`.trim(),
+    resize: () => "",
+};
+function interactive(c) {
+    const { config, noun } = c;
+    const entries = declaredCapabilities(config)
+        .map((name) => {
+        const own = config.capabilities[name]?.guide;
+        return own === undefined ? ENTRIES[name](c, effectiveGates(config, name)) : `- ${own}`;
+    })
+        .filter((entry) => entry !== "");
+    const state = config.isolation === "opaque"
+        ? `- State isn't saved: localStorage works but lasts only while the ${noun} is on screen, and a reload or another device starts fresh. Keep what matters in the ${noun}'s code.`
+        : `- localStorage is kept for this ${noun} in this browser; another device starts fresh.`;
+    const none = entries.length === 0
+        ? `- It can only draw: it has no way to send anything to you or the app.`
+        : null;
+    return lines(`# Interactive ${noun}s`, "", ...entries, none, state);
+}
+const TOPICS = {
+    widget,
+    chart,
+    interactive,
+};
+/** The manual for `topics`, in the order asked (all built-in topics by default). */
+export function generateGuide(config, topics) {
+    const c = context(config);
+    const own = config.guide.topics ?? {};
+    return (topics ?? BUILT_IN_TOPICS)
+        .map((topic) => {
+        if (Object.hasOwn(TOPICS, topic)) {
+            return TOPICS[topic](c);
+        }
+        const text = own[topic];
+        if (text === undefined) {
+            throw new RangeError(`No guide topic ${JSON.stringify(topic)}`);
+        }
+        return text;
+    })
+        .join("\n\n");
+}
+/** The description of the host's show tool, for the agent's tool list. */
+export function generateToolDescription(config) {
+    const c = context(config);
+    const { layout } = config;
+    const what = config.mode === "artifact"
+        ? "Show a whole HTML page you write: a report, a document, a small app."
+        : config.mode === "mcp-app"
+            ? "Show an MCP Apps view."
+            : "Render an SVG or an HTML fragment you write, shown inline: charts, diagrams, explainers, small interactive tools.";
+    const origins = [
+        ...new Set(["script", "style", "font", "img", "media", "connect"].flatMap((kind) => egressOrigins(config, kind))),
+    ];
+    const net = origins.length === 0
+        ? "with no network (nothing loads from outside)"
+        : `loading only from ${origins.join(", ")}`;
+    const globals = declaredCapabilities(config).flatMap((name) => {
+        const spec = capabilitySpec(name);
+        if (spec.global === undefined || !c.global(spec.global)) {
+            return [];
+        }
+        if (spec.global === "sendPrompt") {
+            return ["sendPrompt(text) asks the person to send text to you as their message."];
+        }
+        if (spec.global === "openLink") {
+            return ["openLink(url) asks the person to open a link."];
+        }
+        return [];
+    });
+    const read = config.guide.guideToolName === undefined
+        ? ""
+        : ` Read ${config.guide.guideToolName} once before your first ${c.noun}${config.mode === "inline" ? " (topic chart before your first chart)" : ""}.`;
+    return `${what} It runs in a sandbox about ${layout.narrowWidthPx} px wide on a phone and ${layout.wideWidthPx} on a desktop, from the same code${c.declared("resize") ? " (its height follows the content)" : ""}, in the person's light or dark theme through CSS variables, ${net}. ${globals.join(" ")}${read} Each time it is shown it runs again from this code.`.replace(/ {2,}/gu, " ");
+}

package/dist/host/create-host.d.ts

@@ -0,0 +1,8 @@
+import type { PortholeConfig } from "../config/schema.ts";
+import type { AdapterConnection, ShellConnection } from "../protocol/adapter.ts";
+import type { HostOptions, PortholeHost } from "./types.ts";
+/**
+ * Compiles `config` once and returns a host that mounts displays under it. Throws a `ConfigError`
+ * for a bad config.
+ */
+export declare function createHost<C extends AdapterConnection = ShellConnection>(config: PortholeConfig, options?: HostOptions<C>): PortholeHost<C>;

package/dist/host/create-host.js

@@ -0,0 +1,248 @@
+import { createBridge } from "../bridge/bridge.js";
+import { compile } from "../compile/compile.js";
+import { declaredCapabilities } from "../compile/policy.js";
+import { capabilitySpec } from "../config/capabilities.js";
+import { locateServed } from "./locate.js";
+import { webPlatform } from "../platform/web.js";
+import { MCP_APPS_STYLE_VARIABLES, PORTHOLE_STYLES, } from "../protocol/mcp-apps.js";
+import { shellAdapter } from "../protocol/shell-adapter.js";
+import { resolveTheme } from "../theme/variables.js";
+/** How many times a display is started again after its content navigated its frame away. */
+const MAX_RESTARTS = 3;
+const BASE_KEYS = new Set(["hostContextChanged", "teardown", "close"]);
+const STANDARD = new Set(MCP_APPS_STYLE_VARIABLES);
+/**
+ * Compiles `config` once and returns a host that mounts displays under it. Throws a `ConfigError`
+ * for a bad config.
+ */
+export function createHost(config, options = {}) {
+    const compiled = compile(config);
+    if ((config.isolation === "domain" || config.isolation === "external") &&
+        options.locator === undefined) {
+        throw new TypeError(`${config.isolation} isolation needs a locator (HostOptions.locator)`);
+    }
+    // A url frame is someone else's app: no shell, no protocol, and its navigations are its own.
+    const speaks = config.mode !== "url";
+    const adapter = (options.adapter ?? shellAdapter);
+    const platform = options.platform ?? webPlatform;
+    const hostInfo = options.hostInfo ?? { name: "porthole", version: "0" };
+    return {
+        compiled,
+        mount(container, mount) {
+            const handlers = { ...options.handlers, ...mount.handlers };
+            const missing = declaredCapabilities(config).filter((name) => capabilitySpec(name).served === "handler" &&
+                handlers[name] === undefined);
+            if (missing.length > 0) {
+                throw new TypeError(`No handler for the declared capabilities: ${missing.join(", ")}`);
+            }
+            if (config.isolation !== "opaque" && mount.instance === undefined) {
+                throw new TypeError(`${config.isolation} isolation needs MountOptions.instance`);
+            }
+            const listeners = new Map();
+            const emit = (event, detail) => {
+                for (const listener of listeners.get(event) ?? []) {
+                    listener(detail);
+                }
+            };
+            let scheme = mount.scheme;
+            let height = mount.initialHeightPx ?? 0;
+            let surface = null;
+            let connection = null;
+            let destroyed = false;
+            let restarts = 0;
+            let generation = 0;
+            let abort = null;
+            // The adapter's own operations, the last call of each, replayed into every new frame.
+            const replay = new Map();
+            const hostContext = () => {
+                const width = container.getBoundingClientRect().width;
+                const view = container.ownerDocument.defaultView;
+                // The spec's names in `styles` (the App SDK refuses others there), the rest in our field.
+                const variables = resolveTheme(config.theme, scheme, options.theme?.(scheme));
+                const standard = {};
+                const own = {};
+                for (const [name, value] of Object.entries(variables)) {
+                    (STANDARD.has(name) ? standard : own)[name] = value;
+                }
+                return {
+                    theme: scheme,
+                    styles: { variables: standard },
+                    ...(Object.keys(own).length === 0 ? {} : { [PORTHOLE_STYLES]: { variables: own } }),
+                    displayMode: "inline",
+                    availableDisplayModes: ["inline"],
+                    ...(width > 0 ? { containerDimensions: { maxWidth: Math.round(width) } } : {}),
+                    ...(view === null
+                        ? {}
+                        : {
+                            locale: view.navigator.language,
+                            timeZone: Intl.DateTimeFormat().resolvedOptions().timeZone,
+                            platform: "web",
+                        }),
+                    ...options.hostContext?.(),
+                };
+            };
+            const onBridge = (event) => {
+                switch (event.type) {
+                    case "resize": {
+                        const next = Math.min(config.limits.maxHeightPx, Math.max(config.limits.minHeightPx, Math.ceil(event.height)));
+                        height = next;
+                        surface?.setHeight(next);
+                        emit("resize", {
+                            height: next,
+                            ...(event.width === undefined ? {} : { width: event.width }),
+                        });
+                        return;
+                    }
+                    case "error":
+                        emit("error", { message: event.message });
+                        return;
+                    case "refused":
+                        emit("refused", { capability: event.capability, refusal: event.refusal });
+                        return;
+                    case "muted":
+                        emit("muted", undefined);
+                        return;
+                }
+            };
+            const stop = () => {
+                abort?.abort();
+                abort = null;
+                connection?.close();
+                connection = null;
+                surface?.destroy();
+                surface = null;
+            };
+            const start = (source) => {
+                const created = platform.createSurface(container, {
+                    source,
+                    title: mount.title,
+                    sandbox: compiled.sandbox,
+                    allow: compiled.allow,
+                    referrerPolicy: compiled.referrerPolicy,
+                    colorScheme: scheme,
+                    initialHeightPx: height,
+                });
+                surface = created;
+                if (!speaks) {
+                    return;
+                }
+                const bridge = createBridge({
+                    config,
+                    display: { id: mount.displayId, title: mount.title },
+                    handlers,
+                    ...(options.confirm === undefined ? {} : { confirm: options.confirm }),
+                    userActivation: () => created.userActivation(),
+                    onEvent: onBridge,
+                });
+                const opened = adapter.connect({
+                    display: { id: mount.displayId, title: mount.title },
+                    compiled,
+                    transport: created.transport,
+                    bridge,
+                    hostInfo,
+                    hostContext,
+                    emit: (event) => {
+                        if (event.type === "initialized") {
+                            emit("initialized", undefined);
+                        }
+                    },
+                    ...(mount.document === undefined ? {} : { document: mount.document }),
+                });
+                connection = opened;
+                for (const [name, args] of replay) {
+                    opened[name]?.(...args);
+                }
+                created.onNavigated(() => {
+                    emit("navigated", undefined);
+                    if (restarts < MAX_RESTARTS) {
+                        restarts += 1;
+                        run();
+                    }
+                    else {
+                        stop();
+                        emit("error", {
+                            message: "The content kept navigating its frame away; it was stopped.",
+                        });
+                    }
+                });
+            };
+            const run = () => {
+                stop();
+                if (destroyed) {
+                    return;
+                }
+                generation += 1;
+                if (config.isolation === "opaque") {
+                    start({
+                        kind: "srcdoc",
+                        html: compiled.shellDocument({
+                            origins: [container.ownerDocument.defaultView?.location.origin ?? ""],
+                            title: mount.title,
+                            ...(mount.document === undefined ? {} : { document: mount.document }),
+                        }),
+                    });
+                    return;
+                }
+                const mine = generation;
+                const controller = new AbortController();
+                abort = controller;
+                const locator = options.locator;
+                const instance = mount.instance;
+                if (locator === undefined || instance === undefined) {
+                    return;
+                }
+                const hostOrigin = container.ownerDocument.defaultView?.location.origin ?? "";
+                locateServed(locator, instance, config, hostOrigin, controller.signal).then((source) => {
+                    if (mine === generation && !destroyed) {
+                        start(source);
+                    }
+                }, (error) => {
+                    if (mine === generation && !controller.signal.aborted) {
+                        emit("error", { message: error instanceof Error ? error.message : String(error) });
+                    }
+                });
+            };
+            run();
+            const controls = {
+                displayId: mount.displayId,
+                setTheme(next) {
+                    scheme = next;
+                    surface?.setColorScheme(next);
+                    connection?.hostContextChanged(hostContext());
+                },
+                on(event, listener) {
+                    const set = listeners.get(event) ?? new Set();
+                    set.add(listener);
+                    listeners.set(event, set);
+                    return () => set.delete(listener);
+                },
+                reload() {
+                    restarts = 0;
+                    run();
+                },
+                destroy() {
+                    destroyed = true;
+                    stop();
+                    listeners.clear();
+                },
+            };
+            // The adapter's own operations (`setContent` for the shell adapter): forwarded to the frame
+            // running now, and remembered (the last call of each) for a frame started again.
+            return new Proxy(controls, {
+                get(target, key, receiver) {
+                    if (typeof key === "string" && !(key in target) && !BASE_KEYS.has(key)) {
+                        return (...args) => {
+                            replay.delete(key);
+                            replay.set(key, args);
+                            const operation = connection?.[key];
+                            return typeof operation === "function"
+                                ? operation.apply(connection, args)
+                                : undefined;
+                        };
+                    }
+                    return Reflect.get(target, key, receiver);
+                },
+            });
+        },
+    };
+}

package/dist/host/locate.d.ts

@@ -0,0 +1,8 @@
+import type { PortholeConfig } from "../config/schema.ts";
+import type { FrameSource, InstanceLocator, InstanceRef } from "../isolation/types.ts";
+/**
+ * Where a served frame (domain or external isolation) loads from: the host's locator answers, and
+ * `checkFrameLocation` checks the answer (one of the config's content origins, never the host's
+ * own site) before any frame is made.
+ */
+export declare function locateServed(locator: InstanceLocator, instance: InstanceRef, config: PortholeConfig, hostOrigin: string, signal?: AbortSignal): Promise<FrameSource>;

package/dist/host/locate.js

@@ -0,0 +1,11 @@
+import { checkFrameLocation } from "../isolation/served.js";
+/**
+ * Where a served frame (domain or external isolation) loads from: the host's locator answers, and
+ * `checkFrameLocation` checks the answer (one of the config's content origins, never the host's
+ * own site) before any frame is made.
+ */
+export async function locateServed(locator, instance, config, hostOrigin, signal) {
+    const location = await locator.locate(instance, signal);
+    checkFrameLocation(location, config.contentOrigins, hostOrigin);
+    return { kind: "url", url: new URL(location.url).href, origin: location.origin };
+}

package/dist/host/types.d.ts

@@ -0,0 +1,95 @@
+import type { Confirm, CapabilityHandlers, Refusal } from "../bridge/types.ts";
+import type { CompiledConfig } from "../compile/compile.ts";
+import type { CapabilityName } from "../config/capabilities.ts";
+import type { ColorScheme } from "../config/schema.ts";
+import type { InstanceLocator, InstanceRef } from "../isolation/types.ts";
+import type { PlatformHost } from "../platform/types.ts";
+import type { AdapterConnection, ProtocolAdapter, ShellConnection } from "../protocol/adapter.ts";
+import type { HostContext } from "../protocol/mcp-apps.ts";
+/**
+ * The host-side API (framework-agnostic; the web platform by default). A host compiles a config
+ * once (`createHost`), then mounts a display per piece of content. Everything here is mechanism;
+ * the host passes policy: its handlers, who confirms, its theme values.
+ */
+export interface HostOptions<C extends AdapterConnection = ShellConnection> {
+    /** Handlers for the declared capabilities; a mount may pass its own over these. */
+    readonly handlers?: CapabilityHandlers;
+    /** Who confirms `confirm`-gated calls. Absent: those calls are refused. */
+    readonly confirm?: Confirm;
+    /**
+     * The host's live values for the config's theme variables, for `scheme` (read from its own
+     * design tokens). A name it leaves out, or answers empty, gets the config's default.
+     */
+    readonly theme?: (scheme: ColorScheme) => Readonly<Record<string, string | null | undefined>>;
+    /** The host's own context fields (locale, time zone, platform): merged into the host context. */
+    readonly hostContext?: () => Partial<HostContext>;
+    /** How the host names itself in the handshake. */
+    readonly hostInfo?: {
+        readonly name: string;
+        readonly version: string;
+    };
+    /** The protocol adapter. Default: the core's shell adapter (inline and artifact modes). */
+    readonly adapter?: ProtocolAdapter<C>;
+    /** The platform host. Default: the web's iframe host. */
+    readonly platform?: PlatformHost;
+    /** Required for domain and external isolation: where an instance's frame loads from. */
+    readonly locator?: InstanceLocator;
+}
+export interface MountOptions {
+    /** The host's id for this display: what its height is remembered by, and calls name. */
+    readonly displayId: string;
+    /** The display's accessible name and the title its confirmations show (the host's words). */
+    readonly title: string;
+    readonly scheme: ColorScheme;
+    /** Handlers for this display only, over the host's. */
+    readonly handlers?: CapabilityHandlers;
+    /** Domain and external isolation: the instance to locate. */
+    readonly instance?: InstanceRef;
+    /** A whole document the frame starts with (an MCP Apps view), hardened by the shell. */
+    readonly document?: string;
+    /** The height to start at, before the content reports its own. */
+    readonly initialHeightPx?: number;
+}
+/** What a display reports, by event name. */
+export interface DisplayEvents {
+    /** The frame finished its handshake. */
+    readonly initialized: undefined;
+    /** The content's size, after the config's limits. */
+    readonly resize: {
+        readonly height: number;
+        readonly width?: number;
+    };
+    /** What the content threw, or what the sandbox blocked (its own words: untrusted). */
+    readonly error: {
+        readonly message: string;
+    };
+    /** The content navigated its frame away; the frame was started again from its content. */
+    readonly navigated: undefined;
+    /** A call didn't run. */
+    readonly refused: {
+        readonly capability: CapabilityName;
+        readonly refusal: Refusal;
+    };
+    /** Too many declines: the display stops asking until it runs again. */
+    readonly muted: undefined;
+}
+export interface DisplayControls {
+    readonly displayId: string;
+    /** The theme flipped: the frame is re-themed in place, without a reload. */
+    setTheme(scheme: ColorScheme): void;
+    on<E extends keyof DisplayEvents>(event: E, listener: (detail: DisplayEvents[E]) => void): () => void;
+    /** Runs the content again from the start, in a new frame. */
+    reload(): void;
+    /** Tears the view down and removes the frame. */
+    destroy(): void;
+}
+/** A mounted display: the framework's controls plus the adapter's own operations. */
+export type DisplayHandle<C extends AdapterConnection = ShellConnection> = DisplayControls & Omit<C, keyof AdapterConnection>;
+export interface PortholeHost<C extends AdapterConnection = ShellConnection> {
+    readonly compiled: CompiledConfig;
+    /**
+     * Creates a display in `container`. Throws if a declared capability served by a handler has
+     * none (here or in the host's options), so a manual never teaches a function nobody serves.
+     */
+    mount(container: HTMLElement, options: MountOptions): DisplayHandle<C>;
+}

package/dist/host/types.js

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