@botiverse/porthole 0.1.6 → 0.1.8

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,160 @@
+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.');
+    // What a block does on the page, and where it is reported: as the Errors line says (#4).
+    const blocked = "a blocked script, style or image just doesn't load and a blocked fetch rejects";
+    add("silent", !declared.has("reportError")
+        ? "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."
+        : config.errors === "agent"
+            ? `What the sandbox blocks shows nothing on the page: ${blocked}. Each block comes back to you as an error, so check them.`
+            : config.errors === "host"
+                ? `What the sandbox blocks shows nothing on the page: ${blocked}. The app is told of each block, but you aren't: test what you write.`
+                : `What the sandbox blocks shows nothing on the page: ${blocked}. Each block is reported to the app.`);
+    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.6",
+  "version": "0.1.8",
   "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": [

package/src/config/schema.ts

@@ -86,9 +86,11 @@ export interface ThemeConfig {
    * Whether a whole document (an artifact page) takes the person's light or dark scheme:
    * `declared` (default): only a page that declares it supports both
    * (`<meta name="color-scheme" content="light dark">`); any other page shows as its author
-   * styled it, in light. `always`: every page. The variables are there either way.
+   * styled it, in light. `always`: every page. `never` (pages only, P065): the host has no
+   * theme for it: it always gets the light values, its frame says light, and no theme change
+   * reaches it. The variables are there in every case.
    */
-  readonly documents?: "declared" | "always";
+  readonly documents?: "declared" | "always" | "never";
 }
 
 export interface Limits {
@@ -143,6 +145,13 @@ export interface LayoutConfig {
   readonly narrowWidthPx: number;
   /** The widest the frame is (a desktop column). */
   readonly wideWidthPx: number;
+  /**
+   * How the frame sits in the host (P065). `flow` (default): a card in a column, as tall as its
+   * content (up to `maxHeightPx`). `fill`: it fills the viewer (the page itself): as tall as its
+   * container, the content scrolling itself, `position: fixed` and `sticky` working. Every mount
+   * then fills (`MountOptions.fill`), and the manual says so.
+   */
+  readonly kind?: "flow" | "fill";
 }
 
 export interface GuideConfig {
@@ -193,9 +202,23 @@ export interface PortholeConfig {
    * "conversation" }`), so the manual says storage is shared across it and keys need a prefix.
    */
   readonly storage?: StorageConfig;
+  /**
+   * Where the content's own errors go, for the manual (P065): `agent`, back to the agent that
+   * wrote it; `host`, to the app only (the agent never sees them); `none`, nowhere (the config
+   * declares no `reportError`). Absent: the manual says they are reported to the app.
+   */
+  readonly errors?: "agent" | "host" | "none";
 }
 
 export interface StorageConfig {
-  /** What the displays sharing one origin have in common, as a noun ("conversation"). */
+  /**
+   * What the displays sharing one origin at once have in common, as a noun ("conversation"):
+   * the manual tells authors to prefix their keys.
+   */
   readonly shared?: string;
+  /**
+   * What one display's storage is kept for, when only one display uses its origin at a time, in
+   * words ("this artifact, across its versions", P065): the manual says so, with no prefix advice.
+   */
+  readonly scope?: string;
 }

package/src/config/validate.ts

@@ -292,6 +292,7 @@ export function validateConfig(input: unknown): PortholeConfig {
       "sandbox",
       "permissions",
       "storage",
+      "errors",
     ],
     "config",
   );
@@ -360,9 +361,16 @@ export function validateConfig(input: unknown): PortholeConfig {
   if (
     theme.documents !== undefined &&
     theme.documents !== "declared" &&
-    theme.documents !== "always"
+    theme.documents !== "always" &&
+    theme.documents !== "never"
   ) {
-    fail("config.theme.documents", 'must be "declared" or "always"');
+    fail("config.theme.documents", 'must be "declared", "always" or "never"');
+  }
+  if (theme.documents === "never" && config.mode !== "artifact") {
+    fail(
+      "config.theme.documents",
+      '"never" is for whole pages: a fragment takes the theme it is drawn in',
+    );
   }
   const variables = object(theme.variables, "config.theme.variables");
   for (const [name, value] of Object.entries(variables)) {
@@ -414,7 +422,10 @@ export function validateConfig(input: unknown): PortholeConfig {
   }
 
   const layout = object(config.layout, "config.layout");
-  only(layout, ["minWidthPx", "narrowWidthPx", "wideWidthPx"], "config.layout");
+  only(layout, ["minWidthPx", "narrowWidthPx", "wideWidthPx", "kind"], "config.layout");
+  if (layout.kind !== undefined && layout.kind !== "flow" && layout.kind !== "fill") {
+    fail("config.layout.kind", 'must be "flow" or "fill"');
+  }
   for (const name of ["minWidthPx", "narrowWidthPx", "wideWidthPx"]) {
     positive(layout[name], `config.layout.${name}`, 10_000);
   }
@@ -494,7 +505,22 @@ export function validateConfig(input: unknown): PortholeConfig {
 
   if (config.storage !== undefined) {
     const storage = object(config.storage, "config.storage");
-    only(storage, ["shared"], "config.storage");
+    only(storage, ["shared", "scope"], "config.storage");
+    if (storage.shared !== undefined && storage.scope !== undefined) {
+      fail(
+        "config.storage",
+        "shared (several displays at once) or scope (one at a time), not both",
+      );
+    }
+    if (
+      storage.scope !== undefined &&
+      (typeof storage.scope !== "string" || !/^[a-z][a-z ,'-]{0,59}$/u.test(storage.scope))
+    ) {
+      fail(
+        "config.storage.scope",
+        'must be short lowercase words ("this artifact, across its versions")',
+      );
+    }
     if (config.isolation !== "domain") {
       fail("config.storage", "only domain isolation keeps storage across displays");
     }
@@ -506,6 +532,20 @@ export function validateConfig(input: unknown): PortholeConfig {
     }
   }
 
+  if (config.errors !== undefined) {
+    if (config.errors !== "agent" && config.errors !== "host" && config.errors !== "none") {
+      fail("config.errors", 'must be "agent", "host" or "none"');
+    }
+    if ((config.errors === "none") !== (capabilities.reportError === undefined)) {
+      fail(
+        "config.errors",
+        config.errors === "none"
+          ? '"none" means no reportError: drop the capability'
+          : `${JSON.stringify(config.errors)} needs the reportError capability, which carries them`,
+      );
+    }
+  }
+
   if (config.permissions !== undefined) {
     if (config.mode !== "url") {
       fail("config.permissions", "only url mode may be delegated features");

package/src/conformance/index.ts

@@ -40,6 +40,8 @@ export interface LaunchSpec {
   readonly scheme?: ColorScheme;
   /** The frame's width, px. */
   readonly widthPx?: number;
+  /** The height of the box the frame sits in, px: for a layout that fills it (`layout.kind`). */
+  readonly heightPx?: number;
   /** The host's live values for theme variables, per scheme (as `HostOptions.theme` answers). */
   readonly hostTheme?: {
     readonly light?: Readonly<Record<string, string>>;

package/src/conformance/kit.ts

@@ -34,7 +34,8 @@ export interface Probe {
   readonly id: string;
   /**
    * The DESIGN.md egress-table item it proves; 0 for the shell's own wiring and interop, 11 for
-   * behavior (streaming, sizing, theming), 12 for host-function gates, 13 for the clipboard.
+   * behavior (streaming, sizing, theming), 12 for host-function gates, 13 for the clipboard, 14
+   * for the manual's claims about the sandbox (`LIMIT_CHECKS`).
    */
   readonly item: number;
   readonly title: string;