@botiverse/porthole 0.1.5 → 0.1.7

package/dist/conformance/probes.js

@@ -4,6 +4,7 @@ import { resolveTheme } from "../theme/variables.js";
 import { attack, inline, js } from "./kit.js";
 import { BEHAVIOR_PROBES } from "./behavior.js";
 import { CLIPBOARD_PROBES } from "./clipboard.js";
+import { LIMIT_PROBES } from "./limits.js";
 import { readFileSync } from "node:fs";
 import { createRequire } from "node:module";
 import { httpOracle, settle, udpOracle, } from "./oracles.js";
@@ -832,6 +833,7 @@ export const PROBES = [
     },
     ...BEHAVIOR_PROBES,
     ...CLIPBOARD_PROBES,
+    ...LIMIT_PROBES,
 ];
 /** Every probe as a test entry (see `ConformanceTest`). */
 export function leakTests(host, options = {}) {

package/dist/conformance/served.js

@@ -189,6 +189,19 @@ export function servedTests(host, options = {}) {
                 expect(await host.canaryHits(`${mode}-popup`)).toBe(0);
             });
         }
+        define("served.domain.address", "a served frame's address is its own, carrying at most Porthole's ticket: never the app's", async ({ page }) => {
+            const display = await host.show(page, host.shell("address"), { content: SHELL_CONTENT });
+            const frame = await display.frame();
+            const seen = await frame.evaluate(() => ({
+                origin: location.origin,
+                search: location.search,
+                hash: location.hash,
+            }));
+            expect(seen.origin).toBe(display.origin);
+            expect(seen.search).toMatch(/^(\?ticket=[^&]+)?$/u);
+            expect(seen.hash).toBe("");
+            expect(seen.origin).not.toBe(new URL(page.url()).origin);
+        });
         define("served.domain.storage-scope", "storage persists within a scope and is never shared across scopes", async ({ page }) => {
             const first = await host.show(page, host.shell("scope-a"), { content: SHELL_CONTENT });
             await (await first.frame()).evaluate(() => localStorage.setItem("kept", "a"));
@@ -250,27 +263,76 @@ export function servedTests(host, options = {}) {
                 expect(shown.origin).not.toBe(location.origin);
             }
         });
-        define("served.domain.egress", "the CSP in the document's headers closes egress", async ({ page }) => {
+        define("served.domain.egress", "the CSP in the document's headers closes egress; only what the config opens to any https site (images, media) reaches it", async ({ page }) => {
             const display = await host.show(page, host.shell("egress"), { content: SHELL_CONTENT });
             const frame = await display.frame();
-            const fetched = await frame.evaluate(async (url) => {
+            const kinds = ["fetch", "img", "media", "script", "style", "frame"];
+            const urls = Object.fromEntries(await Promise.all(kinds.map(async (kind) => [kind, await host.canary(`egress-${kind}`)])));
+            // Each kind tried once; the policy that applied is read from the violations it raises.
+            const seen = await frame.evaluate(async (each) => {
+                const policies = [];
+                document.addEventListener("securitypolicyviolation", (event) => policies.push(event.originalPolicy));
+                let fetched = "sent";
                 try {
-                    await fetch(url, { mode: "no-cors" });
-                    return "sent";
+                    await fetch(each.fetch, { mode: "no-cors" });
                 }
                 catch {
-                    return "blocked";
+                    fetched = "blocked";
                 }
-            }, await host.canary("egress-fetch"));
-            await frame.evaluate((url) => {
                 const image = new Image();
-                image.src = url;
+                image.src = each.img;
                 document.body.append(image);
-            }, await host.canary("egress-img"));
+                const audio = document.createElement("audio");
+                audio.preload = "auto";
+                audio.src = each.media;
+                document.body.append(audio);
+                const script = document.createElement("script");
+                script.src = each.script;
+                document.body.append(script);
+                const link = document.createElement("link");
+                link.rel = "stylesheet";
+                link.href = each.style;
+                document.head.append(link);
+                const nested = document.createElement("iframe");
+                nested.src = each.frame;
+                document.body.append(nested);
+                await new Promise((resolve) => setTimeout(resolve, 800));
+                return { fetched, policy: policies.find((policy) => /connect-src/u.test(policy)) ?? "" };
+            }, urls);
             await page.waitForTimeout(SETTLE_MS);
-            expect(fetched).toBe("blocked");
-            expect(await host.canaryHits("egress-fetch")).toBe(0);
-            expect(await host.canaryHits("egress-img")).toBe(0);
+            expect(seen.fetched).toBe("blocked");
+            expect(seen.policy, "a CSP applied to the document").not.toBe("");
+            const sources = new Map(seen.policy
+                .split(";")
+                .map((directive) => directive.trim().split(/\s+/u))
+                .map(([name = "", ...rest]) => [name, rest]));
+            // What runs or talks never opens to any site (P059), whatever the config.
+            for (const name of ["script-src", "style-src", "connect-src", "frame-src", "default-src"]) {
+                expect(sources.get(name) ?? [], `${name} opens no scheme`).not.toContain("https:");
+            }
+            for (const kind of ["fetch", "script", "style", "frame"]) {
+                expect(await host.canaryHits(`egress-${kind}`), kind).toBe(0);
+            }
+            // Images and media: closed, unless the config opened them to any https site (P059);
+            // then, the canary being an https site, an image reaches it, as the config means.
+            const https = (kind) => (sources.get(`${kind}-src`) ?? []).includes("https:") &&
+                new URL(urls[kind]).protocol === "https:";
+            const opened = ["img", "media"].filter(https);
+            if (opened.length > 0) {
+                info?.annotations.push({
+                    type: "expected",
+                    description: `${opened.join(" and ")} load from any https site under this config (anyHttps, P059): ${opened.includes("img") ? "the image is asserted to reach the outside site" : "measured, not asserted"}; script, style, connect and frames still can't`,
+                });
+            }
+            if (https("img")) {
+                expect(await host.canaryHits("egress-img"), "the image, as the config opens it").toBeGreaterThan(0);
+            }
+            else {
+                expect(await host.canaryHits("egress-img"), "img").toBe(0);
+            }
+            if (!https("media")) {
+                expect(await host.canaryHits("egress-media"), "media").toBe(0);
+            }
         });
         const resourceReady = (html) => ({
             jsonrpc: "2.0",

package/dist/guide/guide.js

@@ -1,9 +1,10 @@
 import { MAX_COPY_CHARS, capabilitySpec, } from "../config/capabilities.js";
 import { BUILT_IN_TOPICS } from "../config/validate.js";
-import { anyHttps, declaredCapabilities, effectiveGates, egressOrigins, sandboxTokens, } from "../compile/policy.js";
+import { anyHttps, declaredCapabilities, effectiveGates, egressOrigins, } from "../compile/policy.js";
 import { shellPlan } from "../shell/plan.js";
 import { themeDefault } from "../theme/variables.js";
 import { GUIDE_EXAMPLES } from "./examples.js";
+import { manualLimits, sizeWords } from "./limits.js";
 const VARIABLE = /--[a-z0-9]+(?:-[a-z0-9]+)*/gu;
 function context(config) {
     const variables = Object.keys(config.theme.variables);
@@ -73,25 +74,6 @@ function network(config) {
 /** 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, c) {
-    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) {
     const { config, noun } = c;
     const { layout, limits } = config;
@@ -102,18 +84,23 @@ function widget(c) {
         : 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) => 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;
     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} ${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, c)} ${network(config)} Keep it under ${Math.floor(limits.maxBytes / 1000)} KB.`, loadsScripts(config)
+    return lines(`# ${title}${tool}`, "", what, "", `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(`- 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.", fills
+        ? null
+        : "- No position: fixed: the frame grows with its content, so a fixed element covers it.", "", "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).`, 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, "", 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-") === ""
         ? null
         : `- Borders: ${c.names("--color-border-")}${c.names("--color-ring-") === "" ? "" : `; focus rings: ${c.names("--color-ring-")}`}`, c.names("--color-accent") === ""
         ? null
@@ -127,7 +114,9 @@ function widget(c) {
         ? null
         : `- Shape: ${[c.names("--border-"), c.names("--shadow-")].filter((each) => each !== "").join(", ")}`, otherVariables(c) === "" ? null : `- Also: ${otherVariables(c)}`, "", exampleFits(c, GUIDE_EXAMPLES.stats)
         ? `Cards that read in both themes, and wrap on a phone:\n${GUIDE_EXAMPLES.stats}\n`
-        : null, c.when(`Don't use --color-background-primary as a card's fill: it is the app's own surface, so a card on it vanishes.`), `A theme change updates the variables in place and fires window "${config.theme.event}": CSS that uses var(...) follows by itself; a canvas or a library you gave colors to must redraw.`, config.mode === "inline"
+        : null, c.when(`Don't use --color-background-primary as a card's fill: it is the app's own surface, so a card on it vanishes.`), 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, "", "Diagrams (boxes and arrows): show the mechanism asked about (what calls what, where data goes), only the parts the ask names; label each arrow with what moves.", `- Top to bottom, at most 2 boxes a row, in the phone viewBox; the title in HTML above. Too much for one glance on a phone: make two.`, "- SVG doesn't wrap: break lines yourself. A box is its longest line + 24 wide (13 px text takes about 7 units a character, a 14 px bold name 8.5: a 136-wide box holds 16); a name and a line, 52 tall; 16 between boxes.", c.when("- Boxes fill none, stroke --color-border-secondary; at most one stands out: stroke --color-chart-1, 2 wide, fill --color-chart-1 at fill-opacity 0.12. Arrows --color-text-tertiary, in the gaps, never across a box, their labels beside them. Every <text> sets fill: names --color-text-primary, the rest --color-text-secondary."), exampleFits(c, GUIDE_EXAMPLES.diagram) ? `\n${GUIDE_EXAMPLES.diagram}` : null);
 }
@@ -157,7 +146,7 @@ function chart(c) {
     const categorical = Object.keys(config.theme.variables).filter((name) => /^--color-chart-\d+$/u.test(name));
     const sequential = Object.keys(config.theme.variables).filter((name) => /^--color-chart-seq-\d+$/u.test(name));
     const libraries = loadsScripts(config)
-        ? `Libraries (Chart.js, ECharts, d3) draw in px too, in a box with a set height (Chart.js responsive: true, maintainAspectRatio: false). They don't read CSS variables: pass in getComputedStyle(document.documentElement).getPropertyValue("${categorical[0] ?? "--color-text-primary"}").trim(), redraw on window "${config.theme.event}", and override their palette and white background.`
+        ? `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})`, "", "Pick the form first: a trend over time → line; compare categories → horizontal bars; x against y → scatter; one number → a big number, not a chart; a few numbers → a table, not a chart.", "", "The look:", '- The title states the finding, with its number ("Failed builds fell from 9 to 2 a week"), not the topic; a line under it says what is measured, in what unit.', c.when("- Grey first: the data in a quiet grey (--color-text-disabled), one accent (--color-chart-1) on what the title is about. More hues only for series that differ in kind and must each be found."), "- Values on the marks or a light axis, not both; label only the points the finding rests on. Bars start at zero.", "- Write the numbers once, as rows, and draw marks, labels and readout from them.", "", "Size: draw it at the frame's width, 1 unit = 1 px: read the box's clientWidth, draw an <svg> that wide with 12 px text, and again from a ResizeObserver. Its text stays 12 px on every screen; keep x labels 44 px apart. No script: the phone viewBox (topic widget). Bars need no SVG: an HTML grid row per category.", "", libraries, "", categorical.length === 0 ? null : "Colors:", categorical.length === 0
         ? null
@@ -200,7 +189,7 @@ const ENTRIES = {
         ? `- copyText(text): copies text to the person's clipboard (at most ${MAX_COPY_CHARS.toLocaleString("en-US")} characters), and the app shows them what was copied. Use it for every copy button: nothing else in the ${c.noun} can write the clipboard. ${gateWords(gates, "the text")} It returns a promise: true if it was copied.`
         : `- 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: () => "",
 };
 function interactive(c) {
@@ -211,15 +200,17 @@ function interactive(c) {
         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 = {
     widget,
@@ -282,5 +273,11 @@ export function generateToolDescription(config) {
     const read = config.guide.guideToolName === undefined
         ? ""
         : ` Read ${config.guide.guideToolName} once before your first ${c.noun}${config.mode === "inline" ? " (topic chart before your first chart)" : ""}.`;
-    return `${what} It runs in a sandbox about ${layout.narrowWidthPx} px wide on a phone and ${layout.wideWidthPx} on a desktop, from the same code${c.declared("resize") ? " (its height follows the content)" : ""}, in the person's light or dark theme through CSS variables, ${net}. ${globals.join(" ")}${read} Each time it is shown it runs again from this code.`.replace(/ {2,}/gu, " ");
+    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/dist/guide/limits.d.ts

@@ -0,0 +1,24 @@
+import type { PortholeConfig } from "../config/schema.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 declare const LIMIT_IDS: readonly ["layout", "theme", "silent", "network", "inline-assets", "dialogs", "print", "downloads", "forms", "link-schemes", "windows", "devices", "workers", "sound", "address", "shell", "storage", "errors"];
+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;
+}
+/**
+ * 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 declare function manualLimits(config: PortholeConfig, network: string): ManualLimit[];
+/** A byte limit in words: KB under a megabyte, MB above. */
+export declare function sizeWords(bytes: number): string;

package/dist/guide/limits.js

@@ -0,0 +1,152 @@
+import { declaredCapabilities, egressOrigins, sandboxTokens } from "../compile/policy.js";
+import { shellPlan } from "../shell/plan.js";
+/**
+ * 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",
+];
+const TOPICS = {
+    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) => 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, kind) => 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, network) {
+    if (config.mode === "url") {
+        return [];
+    }
+    const tokens = sandboxTokens(config);
+    const declared = new Set(declaredCapabilities(config));
+    const globals = new Set(shellPlan(config)?.globals ?? []);
+    const it = noun(config);
+    const out = [];
+    const add = (id, text) => {
+        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) => (config.egress.anyHttps ?? []).some((each) => each === kind);
+    const passive = ["img", "font", "media"].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) => 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) {
+    return bytes < 1_000_000
+        ? `${Math.floor(bytes / 1000)} KB`
+        : `${Math.round((bytes / 1_048_576) * 10) / 10} MB`;
+}

package/dist/host/create-host.js

@@ -67,7 +67,9 @@ export function createHost(config, options = {}) {
                 emit("hostError", { message, kind });
                 emit("error", { message, source: "host" });
             };
-            let scheme = mount.scheme;
+            // A page the host doesn't theme (`documents: "never"`, P065) is always given light.
+            const themeless = config.theme.documents === "never";
+            let scheme = themeless ? "light" : mount.scheme;
             let height = mount.initialHeightPx ?? 0;
             let surface = null;
             let connection = null;
@@ -271,8 +273,9 @@ export function createHost(config, options = {}) {
                     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 }),
                 });
@@ -386,6 +389,9 @@ export function createHost(config, options = {}) {
                 displayId: mount.displayId,
                 annotations,
                 setTheme(next) {
+                    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/dist/presets/presets.d.ts

@@ -21,7 +21,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>;
@@ -32,6 +32,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. */
 export interface UrlPresetOptions {

package/dist/presets/presets.js

@@ -83,6 +83,9 @@ function build(mode, defaults, options) {
     const capabilities = {
         ...BASE_CAPABILITIES,
     };
+    if (options.errors === "none") {
+        delete capabilities.reportError;
+    }
     for (const [name, value] of Object.entries(options.capabilities ?? {})) {
         if (value === false) {
             delete capabilities[name];
@@ -107,6 +110,7 @@ function build(mode, defaults, options) {
         contentOrigins: options.contentOrigins ?? [],
         embedder: options.embedder ?? {},
         ...(options.storage === undefined ? {} : { storage: options.storage }),
+        ...(options.errors === undefined ? {} : { errors: options.errors }),
     });
 }
 export const presets = {

package/dist/react/frame.js

@@ -147,7 +147,11 @@ export function PortholeFrame(props) {
             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,
         }, children: state === "running" ? (_jsx(Mount, { frame: props, page: page, initialHeightPx: height, placeholder: placeholder, run: run }, String(props.generation ?? 0))) : (placeholder({ state, title: props.title, run })) }));
@@ -163,7 +167,7 @@ function Mount({ frame, page, initialHeightPx, placeholder, run }) {
     // 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);
     const notify = useEffectEvent((event, detail) => {

package/dist/shell/plan.d.ts

@@ -27,7 +27,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/dist/shell/runtime.js

@@ -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();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@botiverse/porthole",
-  "version": "0.1.5",
+  "version": "0.1.7",
   "description": "A host-side sandbox for agent-made HTML: isolation, egress hardening, a themed shell, gated host functions, and the agent manual, from one config.",
   "license": "Apache-2.0",
   "files": [