@botiverse/porthole 0.1.3 → 0.1.5

package/src/config/validate.ts

@@ -1,5 +1,10 @@
 import { CAPABILITY_NAMES, isCapabilityName, type Gate } from "./capabilities.ts";
-import { URL_PERMISSIONS, URL_SANDBOX_EXTRAS, type PortholeConfig } from "./schema.ts";
+import {
+  PASSIVE_KINDS,
+  URL_PERMISSIONS,
+  URL_SANDBOX_EXTRAS,
+  type PortholeConfig,
+} from "./schema.ts";
 
 /**
  * Checks a config before anything is derived from it. Every string that ends up in a CSP, an
@@ -22,6 +27,155 @@ export class ConfigError extends Error {
 export const BUILT_IN_TOPICS = ["widget", "chart", "interactive"] as const;
 
 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: string): string | null {
+  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;
 
@@ -50,6 +204,12 @@ export function originSourceProblem(value: unknown): string | null {
   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"}`;
   }
@@ -131,6 +291,7 @@ export function validateConfig(input: unknown): PortholeConfig {
       "embedder",
       "sandbox",
       "permissions",
+      "storage",
     ],
     "config",
   );
@@ -173,10 +334,26 @@ export function validateConfig(input: unknown): PortholeConfig {
 
   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 as unknown[]).forEach((kind, index) => {
+      if (!(PASSIVE_KINDS as readonly unknown[]).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");
@@ -315,6 +492,20 @@ export function validateConfig(input: unknown): PortholeConfig {
     });
   }
 
+  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/src/conformance/behavior.ts

@@ -197,7 +197,8 @@ export const BEHAVIOR_PROBES: readonly Probe[] = [
   {
     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");
@@ -210,6 +211,13 @@ export const BEHAVIOR_PROBES: readonly Probe[] = [
       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 as unknown as { flips: string[] }).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"))
@@ -477,6 +485,17 @@ export const BEHAVIOR_PROBES: readonly Probe[] = [
         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/src/conformance/kit.ts

@@ -22,6 +22,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 {
@@ -49,6 +54,17 @@ export function attack(code: string, markup = ""): string {
 (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/src/conformance/probes.ts

@@ -335,6 +335,13 @@ const sdkProbe = (preset: "inline" | "artifact" | "mcp-app"): Probe => ({
 export type { Probe, ProbeContext } from "./kit.ts";
 export { attack } from "./kit.ts";
 
+/**
+ * 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: string, origin: string) =>
+  `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: readonly Probe[] = [
   // ── 0: the shell's own wiring, in a real frame ─────────────────────────────────────────────
   {
@@ -440,10 +447,14 @@ export const PROBES: readonly Probe[] = [
       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([]);
@@ -489,12 +500,16 @@ export const PROBES: readonly Probe[] = [
     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;`,
+    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([]);
@@ -1106,6 +1121,10 @@ export function leakTests(
           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 {
         await Promise.all(closers.map((close) => close()));

package/src/conformance/served.ts

@@ -38,8 +38,17 @@ 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`. */
@@ -74,6 +83,9 @@ type Fixtures = { page: Page; browserName: string };
 
 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: Frame): Promise<Record<string, string>> {
   return frame.evaluate(() => {
@@ -185,13 +197,16 @@ export function servedTests(
       ["domain", (scope: string) => host.shell(scope)],
       ["url", (scope: string) => host.app(scope)],
     ] as const;
+    // A served shell draws (and has a height to click in) once its host gives it content.
+    const showMode = (page: Page, mode: "domain" | "url", instance: InstanceRef) =>
+      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);
@@ -203,7 +218,7 @@ export function servedTests(
         `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);
         },
@@ -213,7 +228,7 @@ export function servedTests(
         `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`);
@@ -246,7 +261,7 @@ export function servedTests(
         `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: Page[] = [];
@@ -283,13 +298,13 @@ export function servedTests(
       "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();
       },
@@ -367,7 +382,7 @@ export function servedTests(
       "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) => {

package/src/guide/guide.ts

@@ -7,6 +7,7 @@ import {
 import type { PortholeConfig } from "../config/schema.ts";
 import { BUILT_IN_TOPICS } from "../config/validate.ts";
 import {
+  anyHttps,
   declaredCapabilities,
   effectiveGates,
   egressOrigins,
@@ -83,11 +84,20 @@ const KIND_WORDS: Readonly<Record<EgressKind, string>> = {
   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: PortholeConfig, kind: EgressKind): string[] => [
+  ...(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: PortholeConfig): string {
   const kinds: EgressKind[] = ["script", "style", "font", "img", "media", "connect"];
   const open = kinds
-    .map((kind) => [kind, egressOrigins(config, kind)] as const)
+    .map((kind) => [kind, sourcesFor(config, kind)] as const)
     .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.";
@@ -368,7 +378,9 @@ function interactive(c: Context): string {
   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.`
@@ -417,10 +429,19 @@ export function generateToolDescription(config: PortholeConfig): string {
       ),
     ),
   ];
+  const passive = (["img", "media", "font"] as const)
+    .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
+    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)) {

package/src/host/create-host.ts

@@ -26,6 +26,7 @@ import { shellAdapter } from "../protocol/shell-adapter.ts";
 import { resolveTheme } from "../theme/variables.ts";
 import type {
   AnnotationControls,
+  HostErrorKind,
   DisplayEvents,
   DisplayHandle,
   HostOptions,
@@ -96,6 +97,16 @@ export function createHost<C extends AdapterConnection = ShellConnection>(
           (listener as (detail: DisplayEvents[E]) => void)(detail);
         }
       };
+      // What the content did wrong (the agent's to hear and fix), and what failed on the host's
+      // side (its own to handle), each on its own event and on `error` with its source.
+      const contentError = (message: string) => {
+        emit("contentError", { message });
+        emit("error", { message, source: "content" });
+      };
+      const hostError = (message: string, kind: HostErrorKind) => {
+        emit("hostError", { message, kind });
+        emit("error", { message, source: "host" });
+      };
 
       let scheme: ColorScheme = mount.scheme;
       let height = mount.initialHeightPx ?? 0;
@@ -277,7 +288,7 @@ export function createHost<C extends AdapterConnection = ShellConnection>(
             return;
           }
           case "error":
-            emit("error", { message: event.message });
+            contentError(event.message);
             return;
           case "refused":
             emit("refused", { capability: event.capability, refusal: event.refusal });
@@ -311,8 +322,9 @@ export function createHost<C extends AdapterConnection = ShellConnection>(
           allow: compiled.allow,
           referrerPolicy: compiled.referrerPolicy,
           colorScheme: scheme,
-          // An app reports no size: its frame fills the host's container, at least the minimum.
-          ...(speaks
+          // 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
             ? { initialHeightPx: height }
             : { fill: true, initialHeightPx: config.limits.minHeightPx }),
         });
@@ -377,9 +389,7 @@ export function createHost<C extends AdapterConnection = ShellConnection>(
             run();
           } else {
             stop();
-            emit("error", {
-              message: "The content kept navigating its frame away; it was stopped.",
-            });
+            contentError("The content kept navigating its frame away; it was stopped.");
           }
         });
       };
@@ -396,6 +406,7 @@ export function createHost<C extends AdapterConnection = ShellConnection>(
             html: compiled.shellDocument({
               origins: [container.ownerDocument.defaultView?.location.origin ?? ""],
               title: mount.title,
+              ...nonceOf(options.nonce),
               ...(mount.document === undefined ? {} : { document: mount.document }),
             }),
           });
@@ -418,7 +429,9 @@ export function createHost<C extends AdapterConnection = ShellConnection>(
           },
           (error: unknown) => {
             if (mine === generation && !controller.signal.aborted) {
-              emit("error", { message: error instanceof Error ? error.message : String(error) });
+              // The host's own failure (its backend down, access gone): never the content's.
+              hostError(error instanceof Error ? error.message : String(error), "locate");
+              emit("outcome", { state: "blocked", reason: "locate" });
             }
           },
         );
@@ -488,3 +501,9 @@ export function createHost<C extends AdapterConnection = ShellConnection>(
     },
   };
 }
+
+/** The host's nonce option, read now (`HostOptions.nonce`). */
+function nonceOf(nonce: HostOptions["nonce"]): { nonce?: string } {
+  const value = typeof nonce === "function" ? nonce() : nonce;
+  return value === undefined || value === "" ? {} : { nonce: value };
+}