@botiverse/porthole 0.1.6 → 0.1.7

package/src/guide/guide.ts

@@ -11,12 +11,12 @@ import {
   declaredCapabilities,
   effectiveGates,
   egressOrigins,
-  sandboxTokens,
   type EgressKind,
 } from "../compile/policy.ts";
 import { shellPlan } from "../shell/plan.ts";
 import { themeDefault } from "../theme/variables.ts";
 import { GUIDE_EXAMPLES } from "./examples.ts";
+import { manualLimits, sizeWords } from "./limits.ts";
 
 /**
  * The agent manual and the tool description, generated from the config (PRINCIPLE 3, 10): the
@@ -129,30 +129,6 @@ const optsIn = (config: PortholeConfig): boolean =>
 const loadsScripts = (config: PortholeConfig): boolean =>
   egressOrigins(config, "script").length > 0;
 
-/** What the sandbox withholds, from the sandbox tokens and the shell's own walls. */
-function forbidden(config: PortholeConfig, c: Context): string {
-  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(
-    c.global("copyText") ? "the clipboard (copy buttons call copyText)" : "the clipboard",
-    "frames (iframe, object, embed)",
-    "WebRTC",
-  );
-  return `Not allowed: ${items.join(", ")}.`;
-}
-
 function widget(c: Context): string {
   const { config, noun } = c;
   const { layout, limits } = config;
@@ -164,9 +140,10 @@ function widget(c: Context): string {
       : 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 stated = manualLimits(config, network(config));
+  const said = (id: string) => stated.find((limit) => limit.id === id)?.text ?? "";
+  const fills = layout.kind === "fill";
+  const themeless = config.theme.documents === "never";
   const viewBox = layout.narrowWidthPx + 20;
   const smallest = Math.round(((13 * layout.minWidthPx) / viewBox) * 10) / 10;
   const largest = Math.round(((13 * 400) / viewBox) * 10) / 10;
@@ -180,7 +157,7 @@ function widget(c: Context): string {
     "",
     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" : ""}.`,
+    `Where it runs: ${fills ? `in a sandboxed frame that fills the viewer, about ${layout.narrowWidthPx} px wide on a phone (${layout.minWidthPx} on a small one) and as wide as the window on a desktop` : `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 ${fills ? "window's innerWidth, again on resize" : "box's clientWidth, again from a ResizeObserver"}). ${said("layout")} ${said("theme")} It runs again each time it is shown${loadsScripts(config) ? ": pin library versions" : ""}.`,
     "",
     "Sizes that read on a phone:",
     c.when(
@@ -190,15 +167,22 @@ function widget(c: Context): string {
     `- 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.",
+    fills
+      ? null
+      : "- No position: fixed: the frame grows with its content, so a fixed element covers it.",
     "",
-    `${forbidden(config, c)} ${network(config)} Keep it under ${Math.floor(limits.maxBytes / 1000)} KB.`,
+    "The sandbox:",
+    ...stated.filter((limit) => limit.topic === "sandbox").map((limit) => `- ${limit.text}`),
+    `Keep it under ${sizeWords(limits.maxBytes)}.`,
     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,
     "",
-    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).`,
+    themeless
+      ? `Colors: these variables hold the app's light palette; use them, or colors of your own. Give the ${noun} its own background.`
+      : 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-") === ""
@@ -225,7 +209,9 @@ function widget(c: Context): string {
     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.`,
+    themeless
+      ? null
+      : `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,
@@ -272,7 +258,7 @@ function chart(c: Context): string {
     /^--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.`
+    ? `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()${config.theme.documents === "never" ? "" : `, 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})`,
@@ -362,8 +348,8 @@ const ENTRIES: { readonly [N in CapabilityName]: (c: Context, gates: readonly Ga
         : `- Copying: the request porthole/copy-text with { text } (at most ${MAX_COPY_CHARS.toLocaleString("en-US")} characters) copies text to the person's clipboard, and the app shows them what was copied; nothing else in the ${c.noun} can write the clipboard. ${gateWords(gates, "the text")}`,
     annotate: (c) =>
       `- Comments: the person may point at parts of the ${c.noun} to comment on them. Give headings and the parts that matter stable ids (id="revenue"), so comments stay on them when the ${c.noun} is written again.`,
-    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(),
+    reportError: (c) =>
+      `- ${manualLimits(c.config, "").find((limit) => limit.id === "errors")?.text ?? ""}`,
     resize: () => "",
   };
 
@@ -375,17 +361,18 @@ function interactive(c: Context): string {
       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.`
-      : config.storage?.shared === undefined
-        ? `- localStorage is kept for this ${noun} in this browser; another device starts fresh.`
-        : `- localStorage is shared by every ${noun} in this ${config.storage.shared}, in this browser (another device starts fresh): prefix your keys with a name of this ${noun}'s own ("budget:filters", not "filters"), or ${noun}s overwrite each other.`;
+  const stated = manualLimits(config, "");
+  const stored = stated.find((limit) => limit.id === "storage");
+  const state = stored === undefined ? null : `- ${stored.text}`;
+  // Without reportError the capability list has no errors entry: say that nothing reports them.
+  const errors = c.declared("reportError")
+    ? null
+    : `- ${stated.find((limit) => limit.id === "errors")?.text ?? ""}`;
   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);
+  return lines(`# Interactive ${noun}s`, "", ...entries, errors, none, state);
 }
 
 const TOPICS: Readonly<Record<BuiltInTopic, (c: Context) => string>> = {
@@ -459,7 +446,15 @@ export function generateToolDescription(config: PortholeConfig): string {
     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(
+  const where =
+    layout.kind === "fill"
+      ? `It fills the viewer in a sandbox about ${layout.narrowWidthPx} px wide on a phone, from the same code on every screen`
+      : `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)" : ""}`;
+  const theme =
+    config.theme.documents === "never"
+      ? "always in light (the app doesn't theme it)"
+      : "in the person's light or dark theme through CSS variables";
+  return `${what} ${where}, ${theme}, ${net}. ${globals.join(" ")}${read} Each time it is shown it runs again from this code.`.replace(
     / {2,}/gu,
     " ",
   );

package/src/guide/limits.ts

@@ -0,0 +1,224 @@
+import { declaredCapabilities, egressOrigins, sandboxTokens } from "../compile/policy.ts";
+import type { CapabilityName } from "../config/capabilities.ts";
+import type { PortholeConfig } from "../config/schema.ts";
+import { shellPlan } from "../shell/plan.ts";
+
+/**
+ * The sandbox's limits as the manual states them (P064): each a short line, derived from the
+ * config, for what silently changes how content behaves. Every limit has an id, and the
+ * conformance suite has a named check for each (`LIMIT_CHECKS`), so the manual can't claim what
+ * no browser test proves. What differs by engine is stated as the behavior safe on all of them.
+ */
+
+export const LIMIT_IDS = [
+  "layout",
+  "theme",
+  "silent",
+  "network",
+  "inline-assets",
+  "dialogs",
+  "print",
+  "downloads",
+  "forms",
+  "link-schemes",
+  "windows",
+  "devices",
+  "workers",
+  "sound",
+  "address",
+  "shell",
+  "storage",
+  "errors",
+] as const;
+
+export type LimitId = (typeof LIMIT_IDS)[number];
+
+/** Where the manual states a limit: where it runs, the sandbox list, or the interactive topic. */
+export type LimitTopic = "where" | "sandbox" | "interactive";
+
+export interface ManualLimit {
+  readonly id: LimitId;
+  readonly text: string;
+  readonly topic: LimitTopic;
+}
+
+const TOPICS: { readonly [Id in LimitId]: LimitTopic } = {
+  layout: "where",
+  theme: "where",
+  storage: "interactive",
+  errors: "interactive",
+  silent: "sandbox",
+  network: "sandbox",
+  "inline-assets": "sandbox",
+  dialogs: "sandbox",
+  print: "sandbox",
+  downloads: "sandbox",
+  forms: "sandbox",
+  "link-schemes": "sandbox",
+  windows: "sandbox",
+  devices: "sandbox",
+  workers: "sandbox",
+  sound: "sandbox",
+  address: "sandbox",
+  shell: "sandbox",
+};
+
+const noun = (config: PortholeConfig): string =>
+  config.mode === "artifact" ? "page" : config.mode === "mcp-app" ? "view" : "widget";
+
+/** Whether content may load `kind` from somewhere outside (listed origins, or any https site). */
+const opens = (config: PortholeConfig, kind: "img" | "style" | "font" | "media"): boolean =>
+  egressOrigins(config, kind).length > 0 ||
+  (config.egress.anyHttps ?? []).some((each) => each === kind);
+
+/**
+ * The limits the manual states for `config`, in the order it states them. `network` is the
+ * caller's (the egress line, from the CSP's own sources); `storage` goes in the interactive topic.
+ * Url mode has no shell and no manual: none.
+ */
+export function manualLimits(config: PortholeConfig, network: string): ManualLimit[] {
+  if (config.mode === "url") {
+    return [];
+  }
+  const tokens = sandboxTokens(config);
+  const declared = new Set<CapabilityName>(declaredCapabilities(config));
+  const globals = new Set(shellPlan(config)?.globals ?? []);
+  const it = noun(config);
+  const out: ManualLimit[] = [];
+  const add = (id: LimitId, text: string | null) => {
+    if (text !== null) {
+      out.push({ id, text, topic: TOPICS[id] });
+    }
+  };
+
+  // Where it runs (P065): a card that grows with its content, or the whole viewer.
+  add(
+    "layout",
+    config.layout.kind === "fill"
+      ? "It is as tall as the window: the page scrolls itself, and position: fixed and sticky work."
+      : declared.has("resize")
+        ? `Its height follows its content, at most ${config.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 documents = config.theme.documents ?? "declared";
+  add(
+    "theme",
+    config.mode !== "artifact" || documents === "always"
+      ? "It runs in the person's light or dark theme."
+      : documents === "never"
+        ? "It always shows in light: the app doesn't theme it, so style it yourself; prefers-color-scheme may report the reader's system setting, so don't rely on it."
+        : '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.',
+  );
+
+  add(
+    "silent",
+    "What the sandbox blocks fails silently: a blocked script, style or image just doesn't load, a blocked fetch rejects, and nothing shows an error.",
+  );
+  add("network", network);
+  // Assets: what isn't opened goes inline (Network: none already says "everything inline").
+  const anywhere = (kind: "img" | "font" | "media") =>
+    (config.egress.anyHttps ?? []).some((each) => each === kind);
+  const passive = (["img", "font", "media"] as const).filter((kind) => !anywhere(kind));
+  const listed = passive.some((kind) => opens(config, kind)) || opens(config, "style");
+  const anyOpen =
+    listed ||
+    egressOrigins(config, "script").length > 0 ||
+    egressOrigins(config, "connect").length > 0 ||
+    passive.length < 3;
+  if (anyOpen) {
+    const images =
+      passive.length === 0
+        ? null
+        : passive.every((kind) => !opens(config, kind))
+          ? "images, icons, fonts and sound go inline (data: URLs or SVG)"
+          : "images, fonts and sound from anywhere not listed go inline (data: URLs or SVG)";
+    const css = opens(config, "style") ? "other CSS goes in a <style>" : "CSS goes in a <style>";
+    const said = [images, css].filter((each) => each !== null).join("; ");
+    add("inline-assets", `${said.charAt(0).toUpperCase()}${said.slice(1)}.`);
+  }
+  if (!tokens.includes("allow-modals")) {
+    add(
+      "dialogs",
+      "alert, confirm and prompt show nothing: confirm returns false and prompt null. Draw your own dialogs.",
+    );
+    add("print", "window.print() does nothing.");
+  }
+  if (!tokens.includes("allow-downloads")) {
+    add(
+      "downloads",
+      `Downloads don't work: <a download>, data: and blob: links, saves from script.${declared.has("downloadFile") ? " To give the person a file, ask the app (ui/download-file; with the App SDK, app.downloadFile)." : ""}`,
+    );
+  }
+  if (!tokens.includes("allow-forms")) {
+    add(
+      "forms",
+      'Forms never submit, and some browsers fire no submit event: use them as UI, give buttons type="button" and handle their click.',
+    );
+  }
+  add(
+    "link-schemes",
+    `mailto:, tel: and sms: links open nothing: show the address or number as text${globals.has("copyText") ? " (with a copy button)" : ""}.`,
+  );
+  if (!tokens.includes("allow-popups")) {
+    add(
+      "windows",
+      globals.has("openLink") || declared.has("openLink")
+        ? "window.open and target=_blank open no window (window.open returns null or throws): links open in a new tab through the app (openLink; a click on <a href> does it)."
+        : "Links to other pages, window.open and target=_blank open nothing (window.open returns null or throws).",
+    );
+  }
+  add(
+    "devices",
+    "Camera, microphone, location and sharing are denied without asking (they reject, or aren't there); file inputs and FileReader work.",
+  );
+  add(
+    "workers",
+    "Web Workers from blob: URLs work; service workers can't be registered (even reading navigator.serviceWorker can throw), and WebRTC is gone.",
+  );
+  add("sound", "Sound (and video with sound) plays only from a click: call play() in its handler.");
+  add(
+    "address",
+    config.isolation === "opaque"
+      ? `The ${it}'s address is about:srcdoc: it has no query string or hash to read.`
+      : `The ${it}'s address is its own (with Porthole's one-time ticket), never the app's: read no parameters from it.`,
+  );
+  add(
+    "shell",
+    `document.write and document.open throw; nested frames (iframe, object, embed) are removed; full screen and the clipboard are closed${globals.has("copyText") ? " (copy buttons call copyText)" : ""}.`,
+  );
+  add(
+    "storage",
+    config.isolation === "opaque"
+      ? `State isn't saved: localStorage works but lasts only while the ${it} is on screen, and a reload or another device starts fresh. Keep what matters in the ${it}'s code.`
+      : config.storage?.scope !== undefined
+        ? `localStorage is kept for ${config.storage.scope}, in this browser; another browser or device starts fresh. Reads and writes can throw (private windows, strict settings): wrap them in try/catch and keep only what can be lost.`
+        : config.storage?.shared === undefined
+          ? `localStorage is kept for this ${it} in this browser; another device starts fresh. Reads and writes can throw (private windows, strict settings): wrap them in try/catch and keep only what can be lost.`
+          : `localStorage is shared by every ${it} in this ${config.storage.shared}, in this browser (another device starts fresh): prefix your keys with a name of this ${it}'s own ("budget:filters", not "filters"), or ${it}s overwrite each other. Reads and writes can throw (private windows, strict settings): wrap them in try/catch and keep only what can be lost.`,
+  );
+  // Where the content's errors go (P065): never promise feedback that doesn't come.
+  const reports = config.limits.maxErrorReports;
+  const rate = (config.capabilities.reportError?.gates ?? [{ rateLimit: { perMinute: 10 } }]).find(
+    (gate): gate is { readonly rateLimit: { readonly perMinute: number } } =>
+      typeof gate === "object",
+  );
+  const atMost = rate === undefined ? "" : ` At most ${rate.rateLimit.perMinute} a minute.`;
+  add(
+    "errors",
+    !declared.has("reportError")
+      ? "Errors: nothing reports what your code throws, to you or the app: test what you write."
+      : config.errors === "agent"
+        ? `Errors: what your code throws, and anything the sandbox blocks, comes back to you (at most ${reports} a run), so you can fix it.${atMost}`
+        : config.errors === "host"
+          ? `Errors: what your code throws, and anything the sandbox blocks, goes to the app (at most ${reports} a run), not to you: test what you write.${atMost}`
+          : `Errors: what your code throws, and anything the sandbox blocks, is reported to the app (at most ${reports} a run).${atMost}`,
+  );
+  return out;
+}
+
+/** A byte limit in words: KB under a megabyte, MB above. */
+export function sizeWords(bytes: number): string {
+  return bytes < 1_000_000
+    ? `${Math.floor(bytes / 1000)} KB`
+    : `${Math.round((bytes / 1_048_576) * 10) / 10} MB`;
+}

package/src/host/create-host.ts

@@ -108,7 +108,9 @@ export function createHost<C extends AdapterConnection = ShellConnection>(
         emit("error", { message, source: "host" });
       };
 
-      let scheme: ColorScheme = mount.scheme;
+      // A page the host doesn't theme (`documents: "never"`, P065) is always given light.
+      const themeless = config.theme.documents === "never";
+      let scheme: ColorScheme = themeless ? "light" : mount.scheme;
       let height = mount.initialHeightPx ?? 0;
       let surface: Surface | null = null;
       let connection: C | null = null;
@@ -323,8 +325,9 @@ export function createHost<C extends AdapterConnection = ShellConnection>(
           referrerPolicy: compiled.referrerPolicy,
           colorScheme: scheme,
           // An app reports no size: its frame fills the host's container, at least the minimum;
-          // so does any display the host mounts to fill (its content scrolls inside).
-          ...(speaks && mount.fill !== true
+          // so does any display the host mounts to fill, or whose layout fills (P065): its
+          // content scrolls itself.
+          ...(speaks && mount.fill !== true && config.layout.kind !== "fill"
             ? { initialHeightPx: height }
             : { fill: true, initialHeightPx: config.limits.minHeightPx }),
         });
@@ -443,6 +446,9 @@ export function createHost<C extends AdapterConnection = ShellConnection>(
         displayId: mount.displayId,
         annotations,
         setTheme(next: ColorScheme) {
+          if (themeless) {
+            return;
+          }
           scheme = next;
           surface?.setColorScheme(next);
           // Read the host's values two frames later: a host that restyles its page for the new

package/src/presets/presets.ts

@@ -37,7 +37,7 @@ export interface PresetOptions {
   readonly theme?: {
     readonly variables?: Readonly<Record<string, ThemeValue | null>>;
     readonly event?: string;
-    readonly documents?: "declared" | "always";
+    readonly documents?: "declared" | "always" | "never";
   };
   readonly limits?: Partial<Limits>;
   readonly layout?: Partial<LayoutConfig>;
@@ -48,6 +48,8 @@ export interface PresetOptions {
   readonly embedder?: EmbedderConfig;
   /** Domain isolation: what displays sharing an origin share (`StorageConfig`), for the manual. */
   readonly storage?: StorageConfig;
+  /** Where the content's errors go (`PortholeConfig.errors`); `none` drops `reportError`. */
+  readonly errors?: "agent" | "host" | "none";
 }
 
 /** The url preset's options: where the app is served, and the embedding page's extra frames. */
@@ -156,6 +158,9 @@ function build(
   const capabilities: { -readonly [N in CapabilityName]?: CapabilityConfig } = {
     ...BASE_CAPABILITIES,
   };
+  if (options.errors === "none") {
+    delete capabilities.reportError;
+  }
   for (const [name, value] of Object.entries(options.capabilities ?? {}) as [
     CapabilityName,
     CapabilityConfig | false,
@@ -182,6 +187,7 @@ function build(
     contentOrigins: options.contentOrigins ?? [],
     embedder: options.embedder ?? {},
     ...(options.storage === undefined ? {} : { storage: options.storage }),
+    ...(options.errors === undefined ? {} : { errors: options.errors }),
   });
 }
 

package/src/react/frame.tsx

@@ -392,7 +392,11 @@ export function PortholeFrame(props: PortholeFrameProps): ReactElement {
         position: "relative",
         width: "100%",
         // A display that fills takes its parent's height (the host sizes the parent, or this box).
-        ...(props.fill === true || props.config.mode === "url" ? { height: "100%" } : {}),
+        ...(props.fill === true ||
+        props.config.mode === "url" ||
+        props.config.layout.kind === "fill"
+          ? { height: "100%" }
+          : {}),
         ...(state === "running" ? {} : { minHeight: Math.max(height, PLACEHOLDER_HEIGHT_PX) }),
         ...props.style,
       }}
@@ -434,7 +438,7 @@ function Mount({ frame, page, initialHeightPx, placeholder, run }: MountProps):
   // By value: a config or instance made inline (each render) is the same display.
   const config = useByValue(frame.config);
   const instance = useByValue(frame.instance);
-  const fills = config.mode === "url" || frame.fill === true;
+  const fills = config.mode === "url" || frame.fill === true || config.layout.kind === "fill";
 
   // The latest props, read when the display calls back (never during render).
   const latest = useEffectEvent(() => frame);

package/src/shell/plan.ts

@@ -26,7 +26,7 @@ export interface ShellPlan {
   /** The window event fired after a theme change. */
   readonly themeEvent: string;
   /** Whether a whole document takes the person's scheme: when it declares it, or always. */
-  readonly themeDocuments: "declared" | "always";
+  readonly themeDocuments: "declared" | "always" | "never";
   /** `memory`: an opaque origin has no storage, so a map stands in for the frame's life. */
   readonly storage: "memory" | "native";
   readonly maxErrorReports: number;

package/src/shell/runtime.ts

@@ -567,7 +567,7 @@ export const SHELL_RUNTIME = String.raw`(() => {
     document.body.replaceWith(document.importNode(parsed.body, true));
     root = null;
     const declaredScheme = parsed.querySelector('meta[name="color-scheme" i]');
-    themed = plan.themeDocuments === "always" || (declaredScheme !== null && /\bdark\b/i.test(declaredScheme.getAttribute("content") || ""));
+    themed = plan.themeDocuments !== "never" && (plan.themeDocuments === "always" || (declaredScheme !== null && /\bdark\b/i.test(declaredScheme.getAttribute("content") || "")));
     schemeFollows();
     await runScripts(scripts);
     announceLoaded();