@botiverse/porthole 0.1.3 → 0.1.5

package/dist/compile/policy.d.ts

@@ -1,5 +1,5 @@
 import { type CapabilityName, type Gate } from "../config/capabilities.ts";
-import type { EgressConfig, PortholeConfig } from "../config/schema.ts";
+import type { PortholeConfig } from "../config/schema.ts";
 /**
  * The frame's policies, derived from the config: its CSP (in the shell's `<meta>` for opaque
  * frames, in headers for served ones), its `sandbox` and `allow` attributes, and the `frame-src`
@@ -7,7 +7,9 @@ import type { EgressConfig, PortholeConfig } from "../config/schema.ts";
  */
 /** A CSP directive: its name, then its sources. */
 export type CspDirective = readonly [name: string, ...sources: string[]];
-export type EgressKind = keyof EgressConfig;
+export type EgressKind = "connect" | "script" | "style" | "img" | "font" | "media";
+/** Whether `kind` loads from any https site (`EgressConfig.anyHttps`, P059): passive kinds only. */
+export declare function anyHttps(config: PortholeConfig, kind: EgressKind): boolean;
 /** The capabilities a config declares, in vocabulary order. */
 export declare function declaredCapabilities(config: PortholeConfig): CapabilityName[];
 /** The gates a declared capability runs under: its own, else the vocabulary's defaults. */
@@ -55,3 +57,9 @@ export declare function embedderFrameSources(config: PortholeConfig): string[];
  * engine Porthole supports reads frames from `frame-src`, P038).
  */
 export declare function embedderCsp(configs: readonly PortholeConfig[]): string;
+/**
+ * The `frame-src` sources the embedding page must allow for every kind of display it shows, as a
+ * list, for a host that writes its own policy around them (empty: it frames nothing of
+ * Porthole's but `srcdoc`, which needs none).
+ */
+export declare function embedderFrameSourcesOf(configs: readonly PortholeConfig[]): string[];

package/dist/compile/policy.js

@@ -1,4 +1,8 @@
 import { CAPABILITIES } from "../config/capabilities.js";
+/** Whether `kind` loads from any https site (`EgressConfig.anyHttps`, P059): passive kinds only. */
+export function anyHttps(config, kind) {
+    return (config.egress.anyHttps ?? []).some((each) => each === kind);
+}
 /** The capabilities a config declares, in vocabulary order. */
 export function declaredCapabilities(config) {
     return Object.keys(CAPABILITIES).filter((name) => config.capabilities[name] !== undefined);
@@ -34,13 +38,15 @@ export function frameCspDirectives(config) {
         return [];
     }
     const origins = (kind) => egressOrigins(config, kind);
+    // Any https site, for passive kinds a host opened so (P059); never for what runs or talks.
+    const https = (kind) => (anyHttps(config, kind) ? ["https:"] : []);
     return [
         ["default-src", "'none'"],
         ["script-src", "'unsafe-inline'", "'unsafe-eval'", "blob:", ...origins("script")],
         ["style-src", "'unsafe-inline'", ...origins("style")],
-        ["font-src", "data:", ...origins("font")],
-        ["img-src", "data:", "blob:", ...origins("img")],
-        ["media-src", "data:", "blob:", ...origins("media")],
+        ["font-src", "data:", ...https("font"), ...origins("font")],
+        ["img-src", "data:", "blob:", ...https("img"), ...origins("img")],
+        ["media-src", "data:", "blob:", ...https("media"), ...origins("media")],
         ["connect-src", ...list(origins("connect"))],
         ["worker-src", "blob:"],
         ["child-src", "blob:"],
@@ -102,6 +108,14 @@ export function embedderFrameSources(config) {
  * engine Porthole supports reads frames from `frame-src`, P038).
  */
 export function embedderCsp(configs) {
-    const sources = unique(configs.flatMap(embedderFrameSources));
+    const sources = embedderFrameSourcesOf(configs);
     return serializeCsp([["frame-src", ...(sources.length === 0 ? ["'none'"] : sources)]]);
 }
+/**
+ * The `frame-src` sources the embedding page must allow for every kind of display it shows, as a
+ * list, for a host that writes its own policy around them (empty: it frames nothing of
+ * Porthole's but `srcdoc`, which needs none).
+ */
+export function embedderFrameSourcesOf(configs) {
+    return unique(configs.flatMap(embedderFrameSources));
+}

package/dist/config/schema.d.ts

@@ -58,7 +58,16 @@ export interface EgressConfig {
     readonly img?: readonly string[];
     readonly font?: readonly string[];
     readonly media?: readonly string[];
+    /**
+     * Passive content that may load from any https site (P059): images, audio and video, fonts, for
+     * pages that hotlink them. Never scripts, styles or data. It opens a channel out: a viewer's
+     * address and a visit signal reach any site, and data can leave in the URL.
+     */
+    readonly anyHttps?: readonly PassiveKind[];
 }
+/** What `EgressConfig.anyHttps` may open: content that runs nothing (P059). */
+export declare const PASSIVE_KINDS: readonly ["img", "media", "font"];
+export type PassiveKind = (typeof PASSIVE_KINDS)[number];
 export interface ThemeConfig {
     /**
      * Every CSS variable the content may read, with its default per scheme. The shell injects
@@ -157,4 +166,15 @@ export interface PortholeConfig {
     readonly sandbox?: readonly UrlSandboxExtra[];
     /** Url mode only: features delegated to the frame (`URL_PERMISSIONS`); none by default. */
     readonly permissions?: readonly UrlPermission[];
+    /**
+     * Domain isolation: how far a display's storage reaches, for the manual. Storage is per origin,
+     * and the host picks each display's origin (`InstanceRef.scope`); a host that gives several
+     * displays one scope (all of a conversation's widgets) names it here (`{ shared:
+     * "conversation" }`), so the manual says storage is shared across it and keys need a prefix.
+     */
+    readonly storage?: StorageConfig;
+}
+export interface StorageConfig {
+    /** What the displays sharing one origin have in common, as a noun ("conversation"). */
+    readonly shared?: string;
 }

package/dist/config/schema.js

@@ -1,3 +1,5 @@
+/** What `EgressConfig.anyHttps` may open: content that runs nothing (P059). */
+export const PASSIVE_KINDS = ["img", "media", "font"];
 /**
  * Sandbox tokens a url-mode frame may add to its baseline, by the host's choice (P037): a
  * person's own running app (a dev server's preview) may need popups (an OAuth flow), modals and

package/dist/config/validate.js

@@ -1,5 +1,5 @@
 import { CAPABILITY_NAMES, isCapabilityName } from "./capabilities.js";
-import { URL_PERMISSIONS, URL_SANDBOX_EXTRAS } from "./schema.js";
+import { PASSIVE_KINDS, URL_PERMISSIONS, URL_SANDBOX_EXTRAS, } from "./schema.js";
 /**
  * Checks a config before anything is derived from it. Every string that ends up in a CSP, an
  * attribute or the shell is checked here, so a malformed origin can't inject a directive
@@ -17,6 +17,147 @@ export class ConfigError extends Error {
 /** The built-in manual topics; a host's own topics may not reuse these names. */
 export const BUILT_IN_TOPICS = ["widget", "chart", "interactive"];
 const LOOPBACK = /^(localhost|127\.0\.0\.1|\[::1\])$|\.localhost$/u;
+/**
+ * Suffixes under which anyone can register or publish a name (a public suffix): a wildcard over
+ * one (`https://*.co.uk`, `https://*.github.io`) opens every stranger's site. Single labels (`com`,
+ * `dev`) are refused by rule; these are the common multi-label ones, registries' and hosting
+ * platforms'. Not the whole Public Suffix List: a wildcard should name the host's own domain.
+ */
+const PUBLIC_SUFFIXES = new Set([
+    // Registries' second levels.
+    ...["co", "org", "ac", "gov", "me", "net", "ltd", "plc", "sch", "nhs", "police"].map((each) => `${each}.uk`),
+    ...["com", "net", "org", "edu", "gov", "asn", "id"].map((each) => `${each}.au`),
+    ...["co", "org", "net", "ac", "govt", "geek", "school"].map((each) => `${each}.nz`),
+    ...["co", "ne", "or", "ac", "go", "ad", "ed", "gr", "lg"].map((each) => `${each}.jp`),
+    ...["co", "or", "ne", "ac", "go", "re"].map((each) => `${each}.kr`),
+    ...["com", "net", "org", "gov", "edu"].flatMap((each) => [
+        "br",
+        "cn",
+        "hk",
+        "tw",
+        "sg",
+        "my",
+        "mx",
+        "ar",
+        "tr",
+        "ua",
+        "pl",
+        "ph",
+        "pk",
+        "ng",
+        "eg",
+        "sa",
+        "vn",
+        "co",
+    ].map((country) => `${each}.${country}`)),
+    ...["co", "net", "org", "gen", "firm", "ind", "ac", "edu", "gov", "res"].map((each) => `${each}.in`),
+    ...["co", "org", "ac", "gov", "net", "web"].map((each) => `${each}.za`),
+    ...["co", "org", "ac", "gov", "net", "muni"].map((each) => `${each}.il`),
+    "co.id",
+    "or.id",
+    "ac.id",
+    "co.th",
+    "or.th",
+    "ac.th",
+    "co.ke",
+    "co.tz",
+    "co.ug",
+    "com.de",
+    "co.at",
+    "or.at",
+    "ac.at",
+    "co.it",
+    "com.es",
+    "nom.es",
+    "com.fr",
+    "asso.fr",
+    "eu.org",
+    "us.com",
+    "uk.com",
+    "eu.com",
+    "uk.net",
+    "gb.net",
+    "jpn.com",
+    "kr.com",
+    // Hosting platforms: anyone gets a name under these.
+    "github.io",
+    "githubusercontent.com",
+    "gitlab.io",
+    "bitbucket.io",
+    "pages.dev",
+    "workers.dev",
+    "r2.dev",
+    "vercel.app",
+    "now.sh",
+    "netlify.app",
+    "netlify.com",
+    "herokuapp.com",
+    "herokussl.com",
+    "appspot.com",
+    "web.app",
+    "firebaseapp.com",
+    "cloudfunctions.net",
+    "run.app",
+    "googleusercontent.com",
+    "blogspot.com",
+    "azurewebsites.net",
+    "azurestaticapps.net",
+    "azureedge.net",
+    "blob.core.windows.net",
+    "cloudapp.net",
+    "trafficmanager.net",
+    "cloudfront.net",
+    "amazonaws.com",
+    "s3.amazonaws.com",
+    "elasticbeanstalk.com",
+    "awsapprunner.com",
+    "amplifyapp.com",
+    "fly.dev",
+    "onrender.com",
+    "railway.app",
+    "up.railway.app",
+    "glitch.me",
+    "repl.co",
+    "replit.app",
+    "replit.dev",
+    "surge.sh",
+    "deno.dev",
+    "ngrok.io",
+    "ngrok-free.app",
+    "ngrok.app",
+    "loca.lt",
+    "trycloudflare.com",
+    "codesandbox.io",
+    "csb.app",
+    "stackblitz.io",
+    "webcontainer.io",
+    "neocities.org",
+    "wordpress.com",
+    "tumblr.com",
+    "wixsite.com",
+    "squarespace.com",
+    "myshopify.com",
+    "carrd.co",
+    "notion.site",
+    "framer.app",
+    "webflow.io",
+    "readthedocs.io",
+    "gitbook.io",
+    "sourceforge.net",
+    "digitaloceanspaces.com",
+    "ondigitalocean.app",
+    "b-cdn.net",
+    "jsdelivr.net",
+]);
+/** Why a wildcard's base can't be wildcarded, or null: a public suffix, or a single label. */
+function wildcardProblem(base) {
+    if (base === "localhost") {
+        return null;
+    }
+    return !base.includes(".") || PUBLIC_SUFFIXES.has(base)
+        ? `is a wildcard over a public suffix (*.${base}): anyone can serve a site under it; name a domain of your own (https://*.cdn.example.com)`
+        : null;
+}
 const HOST = /^(\*\.)?([a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?)(\.[a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?)*$/u;
 /**
  * Whether `value` is a CSP host source Porthole accepts: a scheme, a host (optionally `*.` for
@@ -42,6 +183,12 @@ export function originSourceProblem(value) {
     if (host !== "[::1]" && !HOST.test(host)) {
         return `${JSON.stringify(value)} ${shape}`;
     }
+    if (host.startsWith("*.")) {
+        const problem = wildcardProblem(host.slice(2));
+        if (problem !== null) {
+            return `${JSON.stringify(value)} ${problem}`;
+        }
+    }
     if ((scheme === "http" || scheme === "ws") && !LOOPBACK.test(host.replace(/^\*\./u, "x."))) {
         return `${JSON.stringify(value)} uses ${scheme} off loopback: ${scheme} is allowed only for localhost, *.localhost, 127.0.0.1 and [::1] (loopback development); use ${scheme === "http" ? "https" : "wss"}`;
     }
@@ -111,6 +258,7 @@ export function validateConfig(input) {
         "embedder",
         "sandbox",
         "permissions",
+        "storage",
     ], "config");
     if (!MODES.includes(config.mode)) {
         fail("config.mode", `must be one of ${MODES.join(", ")}`);
@@ -146,10 +294,23 @@ export function validateConfig(input) {
     }
     const egress = object(config.egress, "config.egress");
     const kinds = ["connect", "script", "style", "img", "font", "media"];
-    only(egress, kinds, "config.egress");
+    only(egress, [...kinds, "anyHttps"], "config.egress");
     for (const kind of kinds) {
         sources(egress[kind], `config.egress.${kind}`);
     }
+    if (egress.anyHttps !== undefined) {
+        if (!Array.isArray(egress.anyHttps)) {
+            fail("config.egress.anyHttps", `must be a list of ${PASSIVE_KINDS.join(", ")}`);
+        }
+        egress.anyHttps.forEach((kind, index) => {
+            if (!PASSIVE_KINDS.includes(kind)) {
+                fail(`config.egress.anyHttps[${index}]`, `${JSON.stringify(kind)}: only images, media and fonts may load from any https site (P059), never scripts, styles or data`);
+            }
+        });
+        if (config.mode === "url") {
+            fail("config.egress.anyHttps", "url mode has no egress control");
+        }
+    }
     const theme = object(config.theme, "config.theme");
     only(theme, ["variables", "event", "documents"], "config.theme");
     if (theme.documents !== undefined &&
@@ -258,6 +419,17 @@ export function validateConfig(input) {
             }
         });
     }
+    if (config.storage !== undefined) {
+        const storage = object(config.storage, "config.storage");
+        only(storage, ["shared"], "config.storage");
+        if (config.isolation !== "domain") {
+            fail("config.storage", "only domain isolation keeps storage across displays");
+        }
+        if (storage.shared !== undefined &&
+            (typeof storage.shared !== "string" || !/^[a-z][a-z -]{0,39}$/u.test(storage.shared))) {
+            fail("config.storage.shared", 'must be a short lowercase noun ("conversation")');
+        }
+    }
     if (config.permissions !== undefined) {
         if (config.mode !== "url") {
             fail("config.permissions", "only url mode may be delegated features");

package/dist/conformance/behavior.js

@@ -156,7 +156,7 @@ export const BEHAVIOR_PROBES = [
     {
         id: "11.theme-flip",
         item: 11,
-        title: "a theme flip re-themes the running content in place, and tells it once",
+        title: "a theme flip re-themes the running content in place, and tells it once; no event without one",
         async run(context) {
             const config = inline({ theme: { event: "app:theme" } });
             const light = resolveTheme(config.theme, "light");
@@ -169,6 +169,13 @@ export const BEHAVIOR_PROBES = [
             const frame = await display.frame();
             await expect(frame.locator("p")).toHaveText("themed");
             expect(await variable(frame, "--color-text-primary")).toBe(light["--color-text-primary"]);
+            const flips = () => read(frame, () => window.flips);
+            // Mounting, and a host telling it the scheme it already has, are no flip: no event (#3).
+            await settle(400);
+            expect(await flips(), "no theme event at mount").toEqual([]);
+            await display.setTheme("light");
+            await settle(400);
+            expect(await flips(), "no theme event for the scheme it has").toEqual([]);
             await display.setTheme("dark");
             await expect
                 .poll(() => variable(frame, "--color-text-primary"))
@@ -418,6 +425,12 @@ export const BEHAVIOR_PROBES = [
                 content: PROMPT_CONTENT,
             });
             await click(display, "#ask");
+            // A host that always has a confirm function (a default dialog) asks anyway: what this case
+            // proves can't happen there (P058). Its answer is no, so nothing is sent either way.
+            const asked = await display.answerNextConfirmation(false, { timeoutMs: 1_500 }).then(() => true, () => false);
+            if (asked) {
+                context.inapplicable("this host always has a confirm function (a default dialog), so a display without one can't be shown; it asked the person instead");
+            }
             expect(await bodyData(display, "result")).toBe("false");
             expect(await refusals(display)).toContain("sendPrompt:no-confirm");
             expect(await display.calls()).toEqual([]);

package/dist/conformance/kit.d.ts

@@ -20,6 +20,11 @@ export interface ProbeContext {
     requestsTo(origin: string): string[];
     /** Records a measured engine fact in the report. */
     measured(text: string): void;
+    /**
+     * Ends the probe as inapplicable on this host (reported as skipped, with the reason): what it
+     * proves can't be observed here, through no fault of the host's isolation (P058).
+     */
+    inapplicable(reason: string): never;
 }
 export interface Probe {
     /** Stable id, `<item>.<channel>`: what `LeakSuiteOptions.skip` names. */

package/dist/conformance/kit.js

@@ -11,6 +11,17 @@ export function attack(code, markup = "") {
 (async () => {
   const r = {};
   const wait = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+  // Whether a policy blocks \`origin\` though the frame's own allows it: then it is the page's,
+  // which an opaque frame inherits (P058). \`attempt\` loads something from it once more.
+  const inheritedBlocks = async (origin, attempt) => {
+    let blocked = false;
+    const seen = (event) => { if (String(event.blockedURI).indexOf(origin) === 0) blocked = true; };
+    document.addEventListener("securitypolicyviolation", seen);
+    try { await attempt(); } catch (e) {}
+    await wait(300);
+    document.removeEventListener("securitypolicyviolation", seen);
+    return blocked;
+  };
   try {
 ${code}
   } catch (error) {

package/dist/conformance/probes.js

@@ -255,6 +255,11 @@ const sdkProbe = (preset) => ({
     },
 });
 export { attack } from "./kit.js";
+/**
+ * Why a positive control can't pass on this host: an opaque (`srcdoc`) frame inherits the
+ * embedding page's whole policy, and the page's own closes what the config opens (P058).
+ */
+const INHERITED = (directive, origin) => `the page's own CSP, which an opaque frame inherits, blocks ${origin} (${directive}): content in opaque frames here is as closed as the page, whatever its config opens. Domain mode's frames don't inherit it.`;
 export const PROBES = [
     // ── 0: the shell's own wiring, in a real frame ─────────────────────────────────────────────
     {
@@ -358,10 +363,14 @@ export const PROBES = [
       worker.onmessage = (event) => (event.data === "sent" ? resolve() : reject());
       worker.onerror = reject;
     }));
-    r.allowed = await fetch(${js(allowed.origin)} + "/allowed").then((response) => response.text(), () => "blocked");`),
+    r.allowed = await fetch(${js(allowed.origin)} + "/allowed").then((response) => response.text(), () => "blocked");
+    r.inherited = await inheritedBlocks(${js(allowed.origin)}, () => fetch(${js(allowed.origin)} + "/policy").catch(() => {}));`),
             });
             const verdict = await context.result(display, 20_000);
             await settle();
+            if (verdict.allowed !== "oracle" && verdict.inherited === true) {
+                context.inapplicable(INHERITED("connect-src", allowed.origin));
+            }
             expect(verdict.allowed, "the allowed origin (the positive control)").toBe("oracle");
             expect(allowed.requests().map((request) => request.path)).toContain("/allowed");
             expect(canary.requests(), "requests reached the canary").toEqual([]);
@@ -405,10 +414,14 @@ export const PROBES = [
     try { new Worker(${js(`${c}/worker.js`)}); } catch (e) {}
     const ok = document.getElementById("ok");
     r.allowed = await new Promise((resolve) => { if (ok.complete && ok.naturalWidth > 0) resolve("loaded"); ok.onload = () => resolve("loaded"); ok.onerror = () => resolve("blocked"); setTimeout(() => resolve("timeout"), 3000); });
-    r.script = typeof globalThis.__portholeOracleScript;`, markup),
+    r.script = typeof globalThis.__portholeOracleScript;
+    r.inherited = await inheritedBlocks(${js(allowed.origin)}, () => { new Image().src = ${js(`${allowed.origin}/policy.png`)}; });`, markup),
             });
             const verdict = await context.result(display, 20_000);
             await settle();
+            if (verdict.allowed !== "loaded" && verdict.inherited === true) {
+                context.inapplicable(INHERITED("img-src", allowed.origin));
+            }
             expect(verdict.allowed, "the allowed image (the positive control)").toBe("loaded");
             expect(canary.requests(), "resources loaded from the canary").toEqual([]);
             expect(context.requestsTo(canary.origin)).toEqual([]);
@@ -857,6 +870,10 @@ export function leakTests(host, options = {}) {
                     },
                     requestsTo: (origin) => requests.filter((url) => url.startsWith(`${origin}/`) || url === origin),
                     measured: (text) => info.annotations.push({ type: "measured", description: text }),
+                    inapplicable: (why) => {
+                        info.skip(true, `inapplicable on this host: ${why}`);
+                        throw new Error(`inapplicable on this host: ${why}`);
+                    },
                 });
             }
             finally {

package/dist/conformance/served.d.ts

@@ -35,8 +35,15 @@ export interface ServedConformanceHost {
      * Shows `instance` in `page` as the host does: a fresh ticket from its backend, framed under
      * the config's sandbox, in an embedding page that sends the config's `embedderCsp`. The same page
      * may show several, one after another.
+     *
+     * For a served shell the suite gives `options.content`, a line of HTML: a host that speaks to
+     * the shell (`createHost`, the React binding) sends it as the display's content, since a shell
+     * draws nothing (and reports no height) until it has content, and the cases click inside it. A
+     * host whose frame has a height of its own may ignore it.
      */
-    show(page: Page, instance: InstanceRef): Promise<ServedDisplay>;
+    show(page: Page, instance: InstanceRef, options?: {
+        readonly content?: string;
+    }): Promise<ServedDisplay>;
     /** A fresh ticketed location for `instance`, as the host's backend issues it. */
     locate(instance: InstanceRef): Promise<FrameLocation>;
     /** Navigates `page` to a page on an origin that is not one of the host's, framing `url`. */

package/dist/conformance/served.js

@@ -14,6 +14,8 @@
 import { expect } from "@playwright/test";
 import { MCP_APPS_METHODS } from "../protocol/mcp-apps.js";
 const SETTLE_MS = 800;
+/** What a served shell is given to draw (`ServedConformanceHost.show`'s `content`). */
+const SHELL_CONTENT = '<p id="porthole-probe-content">Porthole conformance probe</p>';
 /** What the frame can see of its host: everything here must be closed to it. */
 async function reachIntoHost(frame) {
     return frame.evaluate(() => {
@@ -109,21 +111,23 @@ export function servedTests(host, options = {}) {
             ["domain", (scope) => host.shell(scope)],
             ["url", (scope) => host.app(scope)],
         ];
+        // A served shell draws (and has a height to click in) once its host gives it content.
+        const showMode = (page, mode, instance) => host.show(page, instance, mode === "domain" ? { content: SHELL_CONTENT } : {});
         for (const [mode, instance] of modes) {
             define(`served.${mode}.origin`, "content runs on its own origin, never the host's", async ({ page }) => {
-                const display = await host.show(page, instance(`${mode}-origin`));
+                const display = await showMode(page, mode, instance(`${mode}-origin`));
                 const frame = await display.frame();
                 const origin = await frame.evaluate(() => window.origin);
                 expect(origin).toBe(display.origin);
                 expect(origin).not.toBe(new URL(page.url()).origin);
             });
             define(`served.${mode}.no-reach`, "content can't reach the host's DOM, storage, cookies or URL", async ({ page }) => {
-                const display = await host.show(page, instance(`${mode}-reach`));
+                const display = await showMode(page, mode, instance(`${mode}-reach`));
                 await plantHostSecrets(page);
                 expect(await reachIntoHost(await display.frame())).toEqual(CLOSED);
             });
             define(`served.${mode}.no-top-navigation`, "content can't navigate the host's page, even after a click", async ({ page }) => {
-                const display = await host.show(page, instance(`${mode}-top`));
+                const display = await showMode(page, mode, instance(`${mode}-top`));
                 const frame = await display.frame();
                 const before = page.url();
                 const target = await host.canary(`${mode}-top`);
@@ -153,7 +157,7 @@ export function servedTests(host, options = {}) {
                 expect(await host.canaryHits(`${mode}-top`)).toBe(0);
             });
             define(`served.${mode}.no-popups`, "content can't open a window, even after a click", async ({ page }) => {
-                const display = await host.show(page, instance(`${mode}-popup`));
+                const display = await showMode(page, mode, instance(`${mode}-popup`));
                 const frame = await display.frame();
                 const target = await host.canary(`${mode}-popup`);
                 const opened = [];
@@ -186,13 +190,13 @@ export function servedTests(host, options = {}) {
             });
         }
         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"));
+            const first = await host.show(page, host.shell("scope-a"), { content: SHELL_CONTENT });
             await (await first.frame()).evaluate(() => localStorage.setItem("kept", "a"));
             await first.destroy();
-            const again = await host.show(page, host.shell("scope-a"));
+            const again = await host.show(page, host.shell("scope-a"), { content: SHELL_CONTENT });
             expect(await (await again.frame()).evaluate(() => localStorage.getItem("kept"))).toBe("a");
             expect(again.origin).toBe(first.origin);
-            const other = await host.show(page, host.shell("scope-b"));
+            const other = await host.show(page, host.shell("scope-b"), { content: SHELL_CONTENT });
             expect(other.origin).not.toBe(first.origin);
             expect(await (await other.frame()).evaluate(() => localStorage.getItem("kept"))).toBeNull();
         });
@@ -247,7 +251,7 @@ export function servedTests(host, options = {}) {
             }
         });
         define("served.domain.egress", "the CSP in the document's headers closes egress", async ({ page }) => {
-            const display = await host.show(page, host.shell("egress"));
+            const display = await host.show(page, host.shell("egress"), { content: SHELL_CONTENT });
             const frame = await display.frame();
             const fetched = await frame.evaluate(async (url) => {
                 try {

package/dist/guide/guide.d.ts

@@ -10,6 +10,8 @@ import { BUILT_IN_TOPICS } from "../config/validate.ts";
 export type BuiltInTopic = (typeof BUILT_IN_TOPICS)[number];
 /** A topic name: a built-in one, or one of the config's own (`guide.topics`). */
 export type GuideTopic = BuiltInTopic | (string & {});
+/** What the manual calls `https:` (any https site), where a config opens passive kinds to it. */
+export declare const ANY_HTTPS_SITE = "any https site";
 /** The manual for `topics`, in the order asked (all built-in topics by default). */
 export declare function generateGuide(config: PortholeConfig, topics?: readonly GuideTopic[]): string;
 /** The description of the host's show tool, for the agent's tool list. */

package/dist/guide/guide.js

@@ -1,6 +1,6 @@
 import { MAX_COPY_CHARS, capabilitySpec, } from "../config/capabilities.js";
 import { BUILT_IN_TOPICS } from "../config/validate.js";
-import { declaredCapabilities, effectiveGates, egressOrigins, sandboxTokens, } from "../compile/policy.js";
+import { anyHttps, declaredCapabilities, effectiveGates, egressOrigins, sandboxTokens, } from "../compile/policy.js";
 import { shellPlan } from "../shell/plan.js";
 import { themeDefault } from "../theme/variables.js";
 import { GUIDE_EXAMPLES } from "./examples.js";
@@ -36,11 +36,18 @@ const KIND_WORDS = {
     media: "audio and video",
     connect: "data (fetch, WebSocket)",
 };
+/** What the manual calls `https:` (any https site), where a config opens passive kinds to it. */
+export const ANY_HTTPS_SITE = "any https site";
+/** The sources content may load `kind` from, as the manual names them: origins, any https site. */
+const sourcesFor = (config, kind) => [
+    ...(anyHttps(config, kind) ? [ANY_HTTPS_SITE] : []),
+    ...egressOrigins(config, kind),
+];
 /** What content may load, in prose, from the same origins the CSP lists. */
 function network(config) {
     const kinds = ["script", "style", "font", "img", "media", "connect"];
     const open = kinds
-        .map((kind) => [kind, egressOrigins(config, kind)])
+        .map((kind) => [kind, sourcesFor(config, kind)])
         .filter(([, origins]) => origins.length > 0);
     if (open.length === 0) {
         return "Network: none. Nothing loads from outside (no scripts, styles, fonts, images or data from any server) and any fetch fails, so write everything inline: SVG and CSS draw charts well.";
@@ -206,7 +213,9 @@ function interactive(c) {
         .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.`
-        : `- localStorage is kept for this ${noun} in this browser; another device starts fresh.`;
+        : 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 none = entries.length === 0
         ? `- It can only draw: it has no way to send anything to you or the app.`
         : null;
@@ -246,9 +255,17 @@ export function generateToolDescription(config) {
     const origins = [
         ...new Set(["script", "style", "font", "img", "media", "connect"].flatMap((kind) => egressOrigins(config, kind))),
     ];
-    const net = origins.length === 0
+    const passive = ["img", "media", "font"]
+        .filter((kind) => anyHttps(config, kind))
+        .map((kind) => KIND_WORDS[kind]);
+    const fromAnywhere = passive.length === 0
+        ? ""
+        : `${passive.length === 1 ? passive[0] : `${passive.slice(0, -1).join(", ")} and ${passive.at(-1)}`} from ${ANY_HTTPS_SITE}`;
+    const net = origins.length === 0 && fromAnywhere === ""
         ? "with no network (nothing loads from outside)"
-        : `loading only from ${origins.join(", ")}`;
+        : origins.length === 0
+            ? `loading only ${fromAnywhere}`
+            : `loading only from ${origins.join(", ")}${fromAnywhere === "" ? "" : `, and ${fromAnywhere}`}`;
     const globals = declaredCapabilities(config).flatMap((name) => {
         const spec = capabilitySpec(name);
         if (spec.global === undefined || !c.global(spec.global)) {