@botiverse/porthole 0.1.0 → 0.1.1

package/dist/guide/guide.js

@@ -63,6 +63,8 @@ function network(config) {
     const parts = [...groups].map(([words, origins]) => `${words} from ${origins.join(", ")}`);
     return `Network: only ${parts.join("; ")}. Anything else fails.`;
 }
+/** Whether a whole document takes the theme only when it declares support (ThemeConfig.documents). */
+const optsIn = (config) => config.mode === "artifact" && (config.theme.documents ?? "declared") === "declared";
 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) {
@@ -100,9 +102,11 @@ function widget(c) {
     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)
+    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} ${optsIn(config) ? `It shows in light, as you style it; to follow the person's light or dark theme, declare it in its head (<meta name="color-scheme" content="light dark">) and draw with the variables below.` : "It runs in the person's light or dark theme."} It runs 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, "", optsIn(config)
+        ? `Colors, for a ${noun} that declares light and dark: every color from these variables, never hard-coded, so both work; its own background then stays transparent (it sits on the app's surface).`
+        : `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

package/dist/host/create-host.js

@@ -3,10 +3,13 @@ import { compile } from "../compile/compile.js";
 import { declaredCapabilities } from "../compile/policy.js";
 import { capabilitySpec } from "../config/capabilities.js";
 import { locateServed } from "./locate.js";
+import { watchOutcome } from "./outcome.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 long a display may take to load before its outcome is a timeout, by default. */
+const DEFAULT_LOAD_TIMEOUT_MS = 15_000;
 /** 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"]);
@@ -52,11 +55,13 @@ export function createHost(config, options = {}) {
             let restarts = 0;
             let generation = 0;
             let abort = null;
+            let outcomeWatch = null;
+            let themeFrame = null;
+            const view = container.ownerDocument.defaultView;
             // 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 = {};
@@ -107,6 +112,8 @@ export function createHost(config, options = {}) {
             const stop = () => {
                 abort?.abort();
                 abort = null;
+                outcomeWatch?.stop();
+                outcomeWatch = null;
                 connection?.close();
                 connection = null;
                 surface?.destroy();
@@ -120,10 +127,29 @@ export function createHost(config, options = {}) {
                     allow: compiled.allow,
                     referrerPolicy: compiled.referrerPolicy,
                     colorScheme: scheme,
-                    initialHeightPx: height,
+                    // An app reports no size: its frame fills the host's container, at least the minimum.
+                    ...(speaks
+                        ? { initialHeightPx: height }
+                        : { fill: true, initialHeightPx: config.limits.minHeightPx }),
                 });
                 surface = created;
+                const watch = watchOutcome({
+                    surface: created,
+                    source,
+                    speaks,
+                    timeoutMs: config.limits.loadTimeoutMs ?? DEFAULT_LOAD_TIMEOUT_MS,
+                    onOutcome: (outcome) => emit("outcome", outcome),
+                });
+                outcomeWatch = watch;
                 if (!speaks) {
+                    // No handshake in url mode: the app's first document loading is as ready as it gets.
+                    let ready = false;
+                    created.onLoad(() => {
+                        if (!ready) {
+                            ready = true;
+                            emit("initialized", undefined);
+                        }
+                    });
                     return;
                 }
                 const bridge = createBridge({
@@ -143,6 +169,7 @@ export function createHost(config, options = {}) {
                     hostContext,
                     emit: (event) => {
                         if (event.type === "initialized") {
+                            watch.initialized();
                             emit("initialized", undefined);
                         }
                     },
@@ -208,6 +235,23 @@ export function createHost(config, options = {}) {
                 setTheme(next) {
                     scheme = next;
                     surface?.setColorScheme(next);
+                    // Read the host's values two frames later: a host that restyles its page for the new
+                    // scheme on its next frame has done so by then.
+                    if (view === null) {
+                        connection?.hostContextChanged(hostContext());
+                        return;
+                    }
+                    if (themeFrame !== null) {
+                        view.cancelAnimationFrame(themeFrame);
+                    }
+                    themeFrame = view.requestAnimationFrame(() => {
+                        themeFrame = view.requestAnimationFrame(() => {
+                            themeFrame = null;
+                            connection?.hostContextChanged(hostContext());
+                        });
+                    });
+                },
+                refreshTheme() {
                     connection?.hostContextChanged(hostContext());
                 },
                 on(event, listener) {

package/dist/host/locate.js

@@ -7,5 +7,10 @@ import { checkFrameLocation } from "../isolation/served.js";
 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 };
+    return {
+        kind: "url",
+        url: new URL(location.url).href,
+        origin: location.origin,
+        ...(location.reports === true ? { reports: true } : {}),
+    };
 }

package/dist/host/outcome.d.ts

@@ -0,0 +1,24 @@
+import { type FrameSource } from "../isolation/types.ts";
+import type { Surface } from "../platform/types.ts";
+import type { FrameBlock, FrameOutcome } from "./types.ts";
+interface FrameStatus {
+    readonly state: "entering" | "blocked";
+    readonly reason?: FrameBlock;
+    readonly status?: number;
+}
+/** A frame-status message, or null for anything else. */
+export declare function parseFrameStatus(data: unknown): FrameStatus | null;
+export interface OutcomeWatch {
+    /** The frame finished its handshake. */
+    initialized(): void;
+    stop(): void;
+}
+export declare function watchOutcome(options: {
+    readonly surface: Surface;
+    readonly source: FrameSource;
+    /** Whether the frame speaks for itself (a shell or a view): then its handshake is the proof. */
+    readonly speaks: boolean;
+    readonly timeoutMs: number;
+    readonly onOutcome: (outcome: FrameOutcome) => void;
+}): OutcomeWatch;
+export {};

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

@@ -51,9 +51,36 @@ export interface MountOptions {
     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. */
+    /** 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;
@@ -75,8 +102,13 @@ export interface DisplayEvents {
 }
 export interface DisplayControls {
     readonly displayId: string;
-    /** The theme flipped: the frame is re-themed in place, without a reload. */
+    /**
+     * 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;

package/dist/index.d.ts

@@ -4,7 +4,9 @@
  */
 export { CAPABILITIES, CAPABILITY_NAMES, capabilitySpec, isCapabilityName, type CapabilityArgs, type CapabilityName, type CapabilityResults, type CapabilitySpec, type Gate, type HandledCapability, } from "./config/capabilities.ts";
 export type { CapabilityConfig, CapabilityMap, ColorScheme, DisplayMode, EgressConfig, EmbedderConfig, GuideConfig, IsolationKind, LayoutConfig, Limits, PortholeConfig, ThemeConfig, ThemeValue, } from "./config/schema.ts";
-export { BUILT_IN_TOPICS, ConfigError, isOriginSource, validateConfig } from "./config/validate.ts";
+export { 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";
@@ -18,6 +20,6 @@ export type { PlatformHost, Surface, SurfaceSpec } from "./platform/types.ts";
 export type { Transport } from "./transport/types.ts";
 export type { AdapterConnection, AdapterEvent, AdapterSession, ProtocolAdapter, ShellConnection, } from "./protocol/adapter.ts";
 export { MCP_APPS_METHODS, MCP_APPS_PROTOCOL_VERSION, MCP_APPS_STYLE_VARIABLES, PORTHOLE_STYLES, type HostContext, } from "./protocol/mcp-apps.ts";
-export type { CallContext, CallOutcome, CapabilityHandler, CapabilityHandlers, Confirm, ConfirmRequest, HostFunctionBridge, Refusal, } from "./bridge/types.ts";
+export 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

@@ -4,7 +4,9 @@
  */
 // The config and its vocabulary.
 export { CAPABILITIES, CAPABILITY_NAMES, capabilitySpec, isCapabilityName, } from "./config/capabilities.js";
-export { BUILT_IN_TOPICS, ConfigError, isOriginSource, validateConfig } from "./config/validate.js";
+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.

package/dist/isolation/served.d.ts

@@ -8,6 +8,9 @@ interface ParsedOrigin {
 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

package/dist/isolation/served.js

@@ -19,6 +19,26 @@ export function parseOrigin(origin) {
 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

package/dist/isolation/types.d.ts

@@ -64,7 +64,15 @@ export interface FrameLocation {
     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
@@ -84,4 +92,5 @@ export type FrameSource = {
     readonly kind: "url";
     readonly url: string;
     readonly origin: string;
+    readonly reports?: boolean;
 };

package/dist/isolation/types.js

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

package/dist/platform/types.d.ts

@@ -15,6 +15,11 @@ export interface SurfaceSpec {
     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;
 }
@@ -35,6 +40,8 @@ export interface Surface {
      * 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> {

package/dist/platform/web.js

@@ -23,7 +23,9 @@ export const webPlatform = {
             border: "0",
             background: "transparent",
             colorScheme: spec.colorScheme,
-            height: `${Math.max(0, Math.round(spec.initialHeightPx))}px`,
+            ...(spec.fill === true
+                ? { height: "100%", minHeight: `${Math.max(0, Math.round(spec.initialHeightPx))}px` }
+                : { height: `${Math.max(0, Math.round(spec.initialHeightPx))}px` }),
         });
         const origin = spec.source.kind === "srcdoc" ? "null" : spec.source.origin;
         if (spec.source.kind === "srcdoc") {
@@ -33,9 +35,13 @@ export const webPlatform = {
             frame.src = spec.source.url;
         }
         const navigated = new Set();
+        const loaded = new Set();
         let loads = 0;
         frame.addEventListener("load", () => {
             loads += 1;
+            for (const listener of loaded) {
+                listener();
+            }
             if (loads > 1) {
                 for (const listener of navigated) {
                     listener();
@@ -49,7 +55,9 @@ export const webPlatform = {
             transport,
             element: frame,
             setHeight(px) {
-                frame.style.height = `${Math.max(0, Math.round(px))}px`;
+                if (spec.fill !== true) {
+                    frame.style.height = `${Math.max(0, Math.round(px))}px`;
+                }
             },
             setColorScheme(scheme) {
                 frame.style.colorScheme = scheme;
@@ -58,12 +66,17 @@ export const webPlatform = {
                 const activation = view.navigator.userActivation;
                 return activation === undefined ? undefined : activation.isActive;
             },
+            onLoad(listener) {
+                loaded.add(listener);
+                return () => loaded.delete(listener);
+            },
             onNavigated(listener) {
                 navigated.add(listener);
                 return () => navigated.delete(listener);
             },
             destroy() {
                 navigated.clear();
+                loaded.clear();
                 transport.close();
                 frame.remove();
             },

package/dist/presets/presets.d.ts

@@ -1,5 +1,5 @@
 import type { CapabilityName } from "../config/capabilities.ts";
-import type { CapabilityConfig, EgressConfig, EmbedderConfig, GuideConfig, IsolationKind, LayoutConfig, Limits, PortholeConfig, ThemeValue } from "../config/schema.ts";
+import type { CapabilityConfig, EgressConfig, EmbedderConfig, GuideConfig, IsolationKind, LayoutConfig, Limits, PortholeConfig, ThemeValue, UrlSandboxExtra } from "../config/schema.ts";
 /**
  * The preset policy layer (P001): named configs with safe defaults. Every preset starts with
  * egress closed and only the capabilities that carry nothing out of the frame (its size, its
@@ -14,10 +14,14 @@ export interface PresetOptions {
     };
     /** Origins to open, added to the preset's (closed) egress. */
     readonly egress?: EgressConfig;
-    /** Theme defaults to change or variables to add, and the theme event's name. */
+    /**
+     * Theme defaults to change, variables to add, or (null) defaults to drop; the theme event's
+     * name; and whether whole documents follow the person's scheme (`ThemeConfig.documents`).
+     */
     readonly theme?: {
-        readonly variables?: Readonly<Record<string, ThemeValue>>;
+        readonly variables?: Readonly<Record<string, ThemeValue | null>>;
         readonly event?: string;
+        readonly documents?: "declared" | "always";
     };
     readonly limits?: Partial<Limits>;
     readonly layout?: Partial<LayoutConfig>;
@@ -30,6 +34,8 @@ export interface PresetOptions {
 /** The url preset's options: where the app is served, and the embedding page's extra frames. */
 export interface UrlPresetOptions {
     readonly contentOrigins: readonly string[];
+    /** Sandbox tokens to add for the app (popups for an OAuth flow, modals, downloads; P037). */
+    readonly sandbox?: readonly UrlSandboxExtra[];
     readonly limits?: Partial<Limits>;
     readonly layout?: Partial<LayoutConfig>;
     readonly embedder?: EmbedderConfig;

package/dist/presets/presets.js

@@ -62,6 +62,19 @@ const mergeEgress = (base, extra) => {
     }
     return merged;
 };
+/** The default variables, with the host's changes and additions, less those it dropped (null). */
+function themeVariables(changes) {
+    const variables = { ...DEFAULT_THEME_VARIABLES };
+    for (const [name, value] of Object.entries(changes ?? {})) {
+        if (value === null) {
+            delete variables[name];
+        }
+        else {
+            variables[name] = value;
+        }
+    }
+    return variables;
+}
 function build(mode, defaults, options) {
     const capabilities = {
         ...BASE_CAPABILITIES,
@@ -80,8 +93,9 @@ function build(mode, defaults, options) {
         capabilities,
         egress: mergeEgress({}, options.egress),
         theme: {
-            variables: { ...DEFAULT_THEME_VARIABLES, ...options.theme?.variables },
+            variables: themeVariables(options.theme?.variables),
             event: options.theme?.event ?? DEFAULT_THEME_EVENT,
+            ...(options.theme?.documents === undefined ? {} : { documents: options.theme.documents }),
         },
         limits: { ...BASE_LIMITS, ...defaults.limits, ...options.limits },
         layout: { ...BASE_LAYOUT, ...options.layout },
@@ -121,5 +135,6 @@ export const presets = {
         guide: {},
         contentOrigins: options.contentOrigins,
         embedder: options.embedder ?? {},
+        ...(options.sandbox === undefined ? {} : { sandbox: options.sandbox }),
     }),
 };

package/dist/react/frame.d.ts

@@ -2,6 +2,7 @@ import { type CSSProperties, type ReactElement, type ReactNode } from "react";
 import type { CapabilityHandlers, Confirm, Refusal } from "../bridge/types.ts";
 import type { CapabilityName } from "../config/capabilities.ts";
 import type { ColorScheme, PortholeConfig } from "../config/schema.ts";
+import type { FrameOutcome } from "../host/types.ts";
 import type { InstanceLocator, InstanceRef } from "../isolation/types.ts";
 /** The height a display holds before it has reported its own. */
 export declare const PLACEHOLDER_HEIGHT_PX = 96;
@@ -67,6 +68,21 @@ export interface PortholeFrameProps {
     readonly onRefused?: (capability: CapabilityName, refusal: Refusal) => void;
     /** Too many declines: the display stops asking until it runs again. */
     readonly onMuted?: () => void;
+    /**
+     * How the frame's first document went: loaded, blocked (and why), or a timeout. A host shows its
+     * own fallback (a url-mode app "Open in a new tab") on anything but loaded.
+     */
+    readonly onOutcome?: (outcome: FrameOutcome) => void;
+    /**
+     * Other ids this display had (the call's id, before the display's own settled): its remembered
+     * height is found under them, for a frame that mounts again under its new id.
+     */
+    readonly aliases?: readonly string[];
+    /**
+     * Change it when the host's theme values change without a scheme flip (or after an async
+     * restyle): the running frame reads them again.
+     */
+    readonly themeKey?: string | number;
     /** Draws the placeholder instead of the default one. */
     readonly renderPlaceholder?: (props: PlaceholderProps) => ReactNode;
     readonly className?: string;