@botiverse/porthole 0.0.1 → 0.1.1

package/dist/host/outcome.js

@@ -0,0 +1,134 @@
+import { FRAME_STATUS_METHOD } from "../isolation/types.js";
+/**
+ * How a display's first document went (P040). A frame's content is another origin's, so the host
+ * can't look inside; it goes by what it can see:
+ *
+ * - a shell or view that speaks for itself is loaded when it finishes its handshake;
+ * - a page of Porthole's `/server` says how it went (`porthole/notifications/frame-status`): it is
+ *   entering an app, or blocked (its ticket used, no cookie kept in a frame, the app down); a url
+ *   app is loaded when its document loads after the entry page;
+ * - a load from which nothing ever spoke, where something should have, is a page that never ran:
+ *   framing refused;
+ * - an app from a host's own gateway is loaded on its first load, unless its page says it is
+ *   blocked (the gateway may send the same message);
+ * - nothing settled in `timeoutMs`: a timeout.
+ */
+/** How long after a load the frame's word may still arrive. */
+const SETTLE_MS = 400;
+const BLOCKS = [
+    "framing",
+    "cookies",
+    "session",
+    "upstream",
+    "not-found",
+    "error",
+];
+/** A frame-status message, or null for anything else. */
+export function parseFrameStatus(data) {
+    if (data === null || typeof data !== "object") {
+        return null;
+    }
+    const message = data;
+    if (message.jsonrpc !== "2.0" || message.method !== FRAME_STATUS_METHOD) {
+        return null;
+    }
+    const params = message.params;
+    if (params === null || typeof params !== "object") {
+        return null;
+    }
+    if (params.state === "entering") {
+        return { state: "entering" };
+    }
+    if (params.state !== "blocked") {
+        return null;
+    }
+    const reason = BLOCKS.includes(params.reason)
+        ? params.reason
+        : "error";
+    return {
+        state: "blocked",
+        reason,
+        ...(typeof params.status === "number" && Number.isInteger(params.status)
+            ? { status: params.status }
+            : {}),
+    };
+}
+export function watchOutcome(options) {
+    const { surface, source, speaks } = options;
+    const reports = source.kind === "url" && source.reports === true;
+    let decided = false;
+    let heard = false;
+    let entering = false;
+    let loads = 0;
+    const timers = new Set();
+    const later = (ms, run) => {
+        const timer = setTimeout(() => {
+            timers.delete(timer);
+            run();
+        }, ms);
+        timers.add(timer);
+    };
+    const stop = () => {
+        for (const timer of timers) {
+            clearTimeout(timer);
+        }
+        timers.clear();
+        unlisten();
+        unload();
+    };
+    const decide = (outcome) => {
+        if (!decided) {
+            decided = true;
+            stop();
+            options.onOutcome(outcome);
+        }
+    };
+    const unlisten = surface.transport.listen((data) => {
+        heard = true;
+        const status = parseFrameStatus(data);
+        if (status?.state === "entering") {
+            entering = true;
+        }
+        else if (status?.state === "blocked") {
+            decide({
+                state: "blocked",
+                reason: status.reason ?? "error",
+                ...(status.status === undefined ? {} : { status: status.status }),
+            });
+        }
+    });
+    const neverRan = () => later(SETTLE_MS, () => {
+        if (!heard) {
+            decide({ state: "blocked", reason: "framing" });
+        }
+    });
+    const unload = surface.onLoad(() => {
+        loads += 1;
+        if (decided) {
+            return;
+        }
+        if (speaks) {
+            // A served shell or view says something before its first load ends; one that never did
+            // never ran. (An opaque srcdoc frame always runs: its handshake decides.)
+            if (source.kind === "url") {
+                neverRan();
+            }
+            return;
+        }
+        if (!reports) {
+            later(SETTLE_MS, () => decide({ state: "loaded" }));
+            return;
+        }
+        if (entering && loads >= 2) {
+            decide({ state: "loaded" });
+        }
+        else if (!entering) {
+            neverRan();
+        }
+    });
+    later(options.timeoutMs, () => decide({ state: "timeout" }));
+    return {
+        initialized: () => decide({ state: "loaded" }),
+        stop,
+    };
+}

package/dist/host/types.d.ts

@@ -0,0 +1,127 @@
+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. */
+/** Why a display's frame showed nothing of its content (`FrameOutcome`). */
+export type FrameBlock = 
+/** The page that frames it isn't one its server allows (frame-ancestors), or it never ran. */
+"framing"
+/** The browser keeps no cookie for it inside a frame (WebKit, P025): open it on a tab. */
+ | "cookies"
+/** Its ticket was used or its session ended. */
+ | "session"
+/** Its app didn't answer. */
+ | "upstream" | "not-found" | "error";
+/**
+ * How a display's first document went, once per run: it loaded (a shell or view finished its
+ * handshake; a url-mode app's document loaded), it was blocked (and why), or nothing settled in
+ * `limits.loadTimeoutMs`. A host shows its own fallback ("Open in a new tab") on anything but
+ * loaded.
+ */
+export type FrameOutcome = {
+    readonly state: "loaded";
+} | {
+    readonly state: "blocked";
+    readonly reason: FrameBlock;
+    readonly status?: number;
+} | {
+    readonly state: "timeout";
+};
+export interface DisplayEvents {
+    /** The frame finished its handshake (url mode, which has none: its first document loaded). */
+    readonly initialized: undefined;
+    /** How the frame's first document went (`FrameOutcome`). */
+    readonly outcome: FrameOutcome;
+    /** 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. The host's values are
+     * read two animation frames later, once a host that restyles its page asynchronously has.
+     */
+    setTheme(scheme: ColorScheme): void;
+    /** The host's theme values changed (same scheme): read them now and re-theme the frame. */
+    refreshTheme(): 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 {};

package/dist/index.d.ts

@@ -0,0 +1,25 @@
+/**
+ * `@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, originSourceProblem, validateConfig, } from "./config/validate.ts";
+export { URL_SANDBOX_EXTRAS, type UrlSandboxExtra } from "./config/schema.ts";
+export { hostOriginProblem, isHostOrigin } from "./isolation/served.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, ConfirmAnswer, ConfirmRequest, Proceed, 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,21 @@
+/**
+ * `@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, originSourceProblem, validateConfig, } from "./config/validate.js";
+export { URL_SANDBOX_EXTRAS } from "./config/schema.js";
+export { hostOriginProblem, isHostOrigin } from "./isolation/served.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,35 @@
+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;
+export declare function isHostOrigin(origin: unknown): origin is string;
+/** Why `origin` can't be a host origin, in words a host's developer can act on; null if it can. */
+export declare function hostOriginProblem(origin: unknown): string | 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 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,117 @@
+/**
+ * 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;
+}
+/**
+ * A host page's origin, exactly as `location.origin` and a message's `event.origin` give it:
+ * `scheme://host[:port]`, lowercase, any scheme (an Electron or Tauri app's own registered scheme,
+ * `ferry://app`, `app://local`), never `"null"` (an opaque origin isn't one origin: every opaque
+ * page says "null") and never a path. The shell takes messages only from these, exactly.
+ */
+const HOST_ORIGIN = /^[a-z][a-z0-9+.-]*:\/\/([a-z0-9]([a-z0-9-]*[a-z0-9])?(\.[a-z0-9]([a-z0-9-]*[a-z0-9])?)*|\[[0-9a-f:.]+\])(:\d{1,5})?$/u;
+export function isHostOrigin(origin) {
+    return typeof origin === "string" && origin.length <= 300 && HOST_ORIGIN.test(origin);
+}
+/** Why `origin` can't be a host origin, in words a host's developer can act on; null if it can. */
+export function hostOriginProblem(origin) {
+    if (isHostOrigin(origin)) {
+        return null;
+    }
+    if (origin === "null") {
+        return 'the host page\'s origin is opaque ("null"): serve it from a real origin (an Electron custom protocol must be registered as standard, and file: pages have none)';
+    }
+    return `${JSON.stringify(origin)} is not an exact origin (scheme://host[:port], lowercase, no path)`;
+}
+/**
+ * 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,96 @@
+/**
+ * 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;
+    /**
+     * Whether the pages there report how loading went (`porthole/notifications/frame-status`):
+     * Porthole's `/server` does, so a page that never ran (refused framing) can be told apart from
+     * one that loaded. A host's own gateway may send the same message without this.
+     */
+    readonly reports?: boolean;
+}
+/** The message a served page sends its host about loading (own-prefixed, P040). */
+export declare const FRAME_STATUS_METHOD = "porthole/notifications/frame-status";
+/**
+ * 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;
+    readonly reports?: boolean;
+};

package/dist/isolation/types.js

@@ -0,0 +1,2 @@
+/** The message a served page sends its host about loading (own-prefixed, P040). */
+export const FRAME_STATUS_METHOD = "porthole/notifications/frame-status";

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