@botiverse/porthole 0.1.0 → 0.1.1

package/src/config/schema.ts

@@ -71,6 +71,13 @@ export interface ThemeConfig {
   readonly variables: Readonly<Record<string, ThemeValue>>;
   /** The window event the shell fires after the theme changed, for code that must redraw. */
   readonly event: string;
+  /**
+   * 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.
+   */
+  readonly documents?: "declared" | "always";
 }
 
 export interface Limits {
@@ -88,8 +95,27 @@ export interface Limits {
   readonly maxPromptChars: number;
   /** The most errors one run of a display reports. */
   readonly maxErrorReports: number;
+  /**
+   * How long a display may take to load before its outcome is a timeout (ms). Optional; 15 s
+   * when absent.
+   */
+  readonly loadTimeoutMs?: number;
 }
 
+/**
+ * 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
+ * downloads. Never top navigation, and nothing for other modes.
+ */
+export const URL_SANDBOX_EXTRAS = [
+  "allow-popups",
+  "allow-popups-to-escape-sandbox",
+  "allow-modals",
+  "allow-downloads",
+] as const;
+
+export type UrlSandboxExtra = (typeof URL_SANDBOX_EXTRAS)[number];
+
 /** Where the host shows the content, for the manual's size rules. */
 export interface LayoutConfig {
   /** The narrowest the frame ever is (a small phone). */
@@ -137,4 +163,6 @@ export interface PortholeConfig {
    */
   readonly contentOrigins: readonly string[];
   readonly embedder: EmbedderConfig;
+  /** Url mode only: sandbox tokens added to its baseline (`URL_SANDBOX_EXTRAS`). */
+  readonly sandbox?: readonly UrlSandboxExtra[];
 }

package/src/config/validate.ts

@@ -1,5 +1,5 @@
 import { CAPABILITY_NAMES, isCapabilityName, type Gate } from "./capabilities.ts";
-import type { PortholeConfig } from "./schema.ts";
+import { 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
@@ -30,24 +30,30 @@ const HOST =
  * every subdomain) and an optional port, nothing else. Insecure schemes only for loopback names.
  */
 export function isOriginSource(value: unknown): value is string {
+  return originSourceProblem(value) === null;
+}
+
+/** Why `value` isn't an origin source Porthole accepts, in words to act on; null if it is. */
+export function originSourceProblem(value: unknown): string | null {
+  const shape = "is not an origin (scheme://host[:port], lowercase, no path)";
   if (typeof value !== "string" || value.length > 253 + 16) {
-    return false;
+    return `${JSON.stringify(value)} ${shape}`;
   }
   const match = /^(https|http|wss|ws):\/\/([^/:]+|\[::1\])(:(\d{1,5}))?$/u.exec(value);
   if (match === null) {
-    return false;
+    return `${JSON.stringify(value)} ${shape}`;
   }
   const [, scheme, host = "", , port] = match;
   if (port !== undefined && (Number(port) < 1 || Number(port) > 65_535)) {
-    return false;
+    return `${JSON.stringify(value)} has no valid port`;
   }
   if (host !== "[::1]" && !HOST.test(host)) {
-    return false;
+    return `${JSON.stringify(value)} ${shape}`;
   }
   if ((scheme === "http" || scheme === "ws") && !LOOPBACK.test(host.replace(/^\*\./u, "x."))) {
-    return false;
+    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"}`;
   }
-  return true;
+  return null;
 }
 
 const fail = (path: string, message: string): never => {
@@ -78,11 +84,9 @@ function sources(value: unknown, path: string): void {
     return;
   }
   value.forEach((source, index) => {
-    if (!isOriginSource(source)) {
-      fail(
-        `${path}[${index}]`,
-        `${JSON.stringify(source)} is not an origin (scheme://host[:port], lowercase, no path)`,
-      );
+    const problem = originSourceProblem(source);
+    if (problem !== null) {
+      fail(`${path}[${index}]`, problem);
     }
   });
 }
@@ -125,6 +129,7 @@ export function validateConfig(input: unknown): PortholeConfig {
       "guide",
       "contentOrigins",
       "embedder",
+      "sandbox",
     ],
     "config",
   );
@@ -173,7 +178,14 @@ export function validateConfig(input: unknown): PortholeConfig {
   }
 
   const theme = object(config.theme, "config.theme");
-  only(theme, ["variables", "event"], "config.theme");
+  only(theme, ["variables", "event", "documents"], "config.theme");
+  if (
+    theme.documents !== undefined &&
+    theme.documents !== "declared" &&
+    theme.documents !== "always"
+  ) {
+    fail("config.theme.documents", 'must be "declared" or "always"');
+  }
   const variables = object(theme.variables, "config.theme.variables");
   for (const [name, value] of Object.entries(variables)) {
     const path = `config.theme.variables[${JSON.stringify(name)}]`;
@@ -212,10 +224,13 @@ export function validateConfig(input: unknown): PortholeConfig {
     "maxPromptChars",
     "maxErrorReports",
   ];
-  only(limits, limitNames, "config.limits");
+  only(limits, [...limitNames, "loadTimeoutMs"], "config.limits");
   for (const name of limitNames) {
     positive(limits[name], `config.limits.${name}`);
   }
+  if (limits.loadTimeoutMs !== undefined) {
+    positive(limits.loadTimeoutMs, "config.limits.loadTimeoutMs", 600_000);
+  }
   if ((limits.minHeightPx as number) > (limits.maxHeightPx as number)) {
     fail("config.limits.minHeightPx", "must not exceed maxHeightPx");
   }
@@ -280,5 +295,24 @@ export function validateConfig(input: unknown): PortholeConfig {
     "config.embedder.frameSrc",
   );
 
+  if (config.sandbox !== undefined) {
+    if (config.mode !== "url") {
+      fail("config.sandbox", "only url mode may add sandbox tokens");
+    }
+    if (!Array.isArray(config.sandbox)) {
+      fail("config.sandbox", "must be an array of sandbox tokens");
+    }
+    (config.sandbox as unknown[]).forEach((token, index) => {
+      if (!(URL_SANDBOX_EXTRAS as readonly unknown[]).includes(token)) {
+        fail(
+          `config.sandbox[${index}]`,
+          /top-navigation|same-origin/u.test(String(token))
+            ? `${JSON.stringify(token)} is never granted (P037)`
+            : `must be one of ${URL_SANDBOX_EXTRAS.join(", ")}`,
+        );
+      }
+    });
+  }
+
   return input as PortholeConfig;
 }

package/src/conformance/behavior.ts

@@ -295,6 +295,61 @@ export const BEHAVIOR_PROBES: readonly Probe[] = [
     },
   },
 
+  {
+    id: "11.document-theme",
+    item: 11,
+    title:
+      "a whole page takes the person's scheme only when it declares it supports it (or the host says always)",
+    async run(context) {
+      const page = (head: string, id: string) =>
+        `<!doctype html><html><head><title>Page</title>${head}</head><body><p id="${id}">page</p></body></html>`;
+      const scheme = (display: LaunchedDisplay, id: string) =>
+        display.frame().then(async (frame) => {
+          await expect(frame.locator(`#${id}`)).toHaveText("page");
+          return frame.evaluate(() => ({
+            scheme: getComputedStyle(document.documentElement).colorScheme,
+            theme: document.documentElement.getAttribute("data-theme"),
+            variable:
+              getComputedStyle(document.documentElement)
+                .getPropertyValue("--color-text-primary")
+                .trim() !== "",
+          }));
+        });
+      const plain = await context.launch({
+        config: presets.artifact(),
+        scheme: "dark",
+        content: page("", "plain"),
+      });
+      // An author's own page, declaring nothing: shown as styled, in light; the variables are there.
+      expect(await scheme(plain, "plain")).toEqual({
+        scheme: "normal",
+        theme: null,
+        variable: true,
+      });
+      await plain.setTheme("light");
+      await plain.setTheme("dark");
+      await settle(300);
+      expect(await scheme(plain, "plain")).toEqual({
+        scheme: "normal",
+        theme: null,
+        variable: true,
+      });
+      const declared = await context.launch({
+        config: presets.artifact(),
+        scheme: "dark",
+        content: page('<meta name="color-scheme" content="light dark">', "declared"),
+      });
+      await expect.poll(async () => (await scheme(declared, "declared")).theme).toBe("dark");
+      expect((await scheme(declared, "declared")).scheme).toBe("dark");
+      const always = await context.launch({
+        config: presets.artifact({ theme: { documents: "always" } }),
+        scheme: "dark",
+        content: page("", "always"),
+      });
+      await expect.poll(async () => (await scheme(always, "always")).theme).toBe("dark");
+    },
+  },
+
   // ── 12: the host-function gates ────────────────────────────────────────────────────────────
   {
     id: "12.prompt-gesture-confirm",

package/src/conformance/index.ts

@@ -1,11 +1,17 @@
 /**
  * `@botiverse/porthole/conformance`: the leak/conformance suite (P008), runnable by any host
  * against its own integration. A host implements `ConformanceHost` (how to show one display in a
- * page and drive it), then registers the suite in its Playwright project:
+ * page and drive it), then registers the tests in a spec file of its own, so they are located
+ * there (`playwright test conformance.spec.ts`, `--grep "\[1\.connect\]"`):
  *
  *   import { test } from "@playwright/test";
- *   import { defineLeakSuite } from "@botiverse/porthole/conformance";
- *   defineLeakSuite(test, myHost);
+ *   import { leakTests } from "@botiverse/porthole/conformance";
+ *   for (const each of leakTests(myHost)) {
+ *     test(each.title, ({ page, browserName }, info) => each.run({ page, browserName }, info));
+ *   }
+ *
+ * The host's own `@playwright/test` (and, for the App SDK probes, `@modelcontextprotocol/ext-apps`)
+ * is what runs it: Porthole declares neither (P041).
  *
  * Each probe attempts one egress or escape channel (DESIGN.md § Egress hardening) and asserts,
  * with an out-of-band oracle where one exists (an HTTP canary that also counts connections, a UDP
@@ -90,12 +96,20 @@ export interface LeakSuiteOptions {
   readonly skip?: Readonly<Record<string, string>>;
 }
 
-export { defineLeakSuite, PROBES, type Probe } from "./probes.ts";
+export {
+  defineLeakSuite,
+  leakTests,
+  PROBES,
+  type ConformanceFixtures,
+  type ConformanceTest,
+  type Probe,
+} from "./probes.ts";
 export { httpOracle, settle, udpOracle, type HttpOracle, type UdpOracle } from "./oracles.ts";
 
 // The served modes' cases (domain and url mode), with their own host interface.
 export {
   defineServedSuite,
+  servedTests,
   type ServedConformanceHost,
   type ServedDisplay,
   type ServedSuiteOptions,

package/src/conformance/probes.ts

@@ -4,6 +4,8 @@ import {
   type PlaywrightTestOptions,
   type PlaywrightWorkerArgs,
   type PlaywrightWorkerOptions,
+  type Page,
+  type TestInfo,
   type TestType,
 } from "@playwright/test";
 import { presets } from "../presets/presets.ts";
@@ -1030,64 +1032,98 @@ type AnyTest = TestType<
   PlaywrightWorkerArgs & PlaywrightWorkerOptions
 >;
 
-/** Registers every probe as a test, grouped by egress item. */
+/** The fixtures a conformance test uses. */
+export interface ConformanceFixtures {
+  readonly page: Page;
+  readonly browserName: string;
+}
+
+/**
+ * One conformance test, for a host's own spec file to register: its tests are then located in that
+ * file, so `playwright test my-conformance.spec.ts` (or `--grep "\[1\.connect\]"`) finds them.
+ *
+ *   for (const each of leakTests(myHost)) {
+ *     test(each.title, ({ page, browserName }, info) => each.run({ page, browserName }, info));
+ *   }
+ */
+export interface ConformanceTest {
+  readonly id: string;
+  /** `[<id>] <what it proves>`: the probe id is greppable. */
+  readonly title: string;
+  run(fixtures: ConformanceFixtures, info: TestInfo): Promise<void>;
+}
+
+/** Every probe as a test entry (see `ConformanceTest`). */
+export function leakTests(
+  host: ConformanceHost,
+  options: LeakSuiteOptions = {},
+): ConformanceTest[] {
+  return PROBES.map((probe) => ({
+    id: probe.id,
+    title: `[${probe.id}] ${probe.title}`,
+    async run({ page, browserName }, info) {
+      const reason = options.skip?.[probe.id];
+      info.skip(reason !== undefined, reason);
+      const closers: (() => Promise<void>)[] = [];
+      const requests: string[] = [];
+      page.on("response", (response) => requests.push(response.url()));
+      try {
+        await probe.run({
+          page,
+          engine: browserName,
+          launch: (spec) => host.launch(page, spec),
+          http: async (files) => {
+            const oracle = await httpOracle(files);
+            closers.push(() => oracle.close());
+            return oracle;
+          },
+          udp: async () => {
+            const oracle = await udpOracle();
+            closers.push(() => oracle.close());
+            return oracle;
+          },
+          result: async (display, timeoutMs = 10_000) => {
+            await expect
+              .poll(
+                async () =>
+                  (await display.frame())
+                    .evaluate(() =>
+                      Boolean(
+                        (window as unknown as { portholeProbe?: { done?: boolean } }).portholeProbe
+                          ?.done,
+                      ),
+                    )
+                    .catch(() => false),
+                { timeout: timeoutMs },
+              )
+              .toBe(true);
+            return (await display.frame()).evaluate(
+              () => (window as unknown as { portholeProbe: Record<string, unknown> }).portholeProbe,
+            );
+          },
+          requestsTo: (origin) =>
+            requests.filter((url) => url.startsWith(`${origin}/`) || url === origin),
+          measured: (text) => info.annotations.push({ type: "measured", description: text }),
+        });
+      } finally {
+        await Promise.all(closers.map((close) => close()));
+      }
+    },
+  }));
+}
+
+/**
+ * Registers every probe as a test. Its tests are located in Porthole's own files; a host that
+ * wants to select them by its spec file registers `leakTests` itself instead.
+ */
 export function defineLeakSuite(
   test: AnyTest,
   host: ConformanceHost,
   options: LeakSuiteOptions = {},
 ): void {
   test.describe(`Porthole leak suite (${host.name})`, () => {
-    for (const probe of PROBES) {
-      test(`[${probe.id}] ${probe.title}`, async ({ page, browserName }) => {
-        const reason = options.skip?.[probe.id];
-        test.skip(reason !== undefined, reason);
-        const closers: (() => Promise<void>)[] = [];
-        const requests: string[] = [];
-        page.on("response", (response) => requests.push(response.url()));
-        try {
-          await probe.run({
-            page,
-            engine: browserName,
-            launch: (spec) => host.launch(page, spec),
-            http: async (files) => {
-              const oracle = await httpOracle(files);
-              closers.push(() => oracle.close());
-              return oracle;
-            },
-            udp: async () => {
-              const oracle = await udpOracle();
-              closers.push(() => oracle.close());
-              return oracle;
-            },
-            result: async (display, timeoutMs = 10_000) => {
-              await expect
-                .poll(
-                  async () =>
-                    (await display.frame())
-                      .evaluate(() =>
-                        Boolean(
-                          (window as unknown as { portholeProbe?: { done?: boolean } })
-                            .portholeProbe?.done,
-                        ),
-                      )
-                      .catch(() => false),
-                  { timeout: timeoutMs },
-                )
-                .toBe(true);
-              return (await display.frame()).evaluate(
-                () =>
-                  (window as unknown as { portholeProbe: Record<string, unknown> }).portholeProbe,
-              );
-            },
-            requestsTo: (origin) =>
-              requests.filter((url) => url.startsWith(`${origin}/`) || url === origin),
-            measured: (text) =>
-              test.info().annotations.push({ type: "measured", description: text }),
-          });
-        } finally {
-          await Promise.all(closers.map((close) => close()));
-        }
-      });
+    for (const each of leakTests(host, options)) {
+      test(each.title, ({ page, browserName }, info) => each.run({ page, browserName }, info));
     }
   });
 }

package/src/conformance/served.ts

@@ -11,7 +11,8 @@
  * Each case attempts one escape or access channel and asserts, with an out-of-band oracle where
  * one exists (a canary URL the host counts requests to), that nothing got through.
  */
-import { expect, type Frame, type Page, type TestType } from "@playwright/test";
+import { expect, type Frame, type Page, type TestInfo, type TestType } from "@playwright/test";
+import type { ConformanceTest } from "./probes.ts";
 import type { EgressConfig } from "../config/schema.ts";
 import type { FrameLocation, InstanceRef } from "../isolation/types.ts";
 import { MCP_APPS_METHODS } from "../protocol/mcp-apps.ts";
@@ -137,22 +138,49 @@ async function plantHostSecrets(page: Page): Promise<void> {
 }
 
 /** Registers every served-mode case as a test. */
+/**
+ * Registers every served-mode case as a test. A host that wants to select them by its own spec
+ * file registers `servedTests` itself (see `ConformanceTest`).
+ */
 export function defineServedSuite(
   test: TestType<object, object>,
   host: ServedConformanceHost,
   options: ServedSuiteOptions = {},
 ): void {
   const typed = test as unknown as TestType<Fixtures, object>;
+  typed.describe(`served modes (${host.name})`, () => {
+    for (const each of servedTests(host, options)) {
+      // Playwright reads the fixtures a test uses from its parameter's destructuring.
+      typed(each.title, ({ page, browserName }, info) => each.run({ page, browserName }, info));
+    }
+  });
+}
+
+/** Every served-mode case as a test entry (see `ConformanceTest`). */
+export function servedTests(
+  host: ServedConformanceHost,
+  options: ServedSuiteOptions = {},
+): ConformanceTest[] {
+  const tests: ConformanceTest[] = [];
+  let info: TestInfo | null = null;
+  // The case being run's own TestInfo (for an expected failure measured on one engine).
+  const typed = {
+    fail: (condition: boolean, reason: string) => info?.fail(condition, reason),
+  };
   const define = (id: string, title: string, body: (fixtures: Fixtures) => Promise<void>) => {
-    const reason = options.skip?.[id];
-    // Playwright reads the fixtures a test uses from its parameter's destructuring.
-    typed(`${id}: ${title}`, async ({ page, browserName }) => {
-      typed.skip(reason !== undefined, reason);
-      await body({ page, browserName });
+    tests.push({
+      id,
+      title: `${id}: ${title}`,
+      async run({ page, browserName }, testInfo) {
+        const reason = options.skip?.[id];
+        testInfo.skip(reason !== undefined, reason);
+        info = testInfo;
+        await body({ page, browserName });
+      },
     });
   };
 
-  typed.describe(`served modes (${host.name})`, () => {
+  {
     const modes = [
       ["domain", (scope: string) => host.shell(scope)],
       ["url", (scope: string) => host.app(scope)],
@@ -468,5 +496,6 @@ export function defineServedSuite(
           .toBe("ready");
       },
     );
-  });
+  }
+  return tests;
 }

package/src/guide/guide.ts

@@ -107,6 +107,10 @@ function network(config: PortholeConfig): string {
   return `Network: only ${parts.join("; ")}. Anything else fails.`;
 }
 
+/** Whether a whole document takes the theme only when it declares support (ThemeConfig.documents). */
+const optsIn = (config: PortholeConfig): boolean =>
+  config.mode === "artifact" && (config.theme.documents ?? "declared") === "declared";
+
 const loadsScripts = (config: PortholeConfig): boolean =>
   egressOrigins(config, "script").length > 0;
 
@@ -157,7 +161,7 @@ function widget(c: Context): string {
     "",
     what,
     "",
-    `Where it runs: in a sandboxed frame as wide as the column it sits in, about ${layout.narrowWidthPx} px on a phone (${layout.minWidthPx} on a small one) and ${layout.wideWidthPx} on a desktop; the same ${noun} is read on both, so never write for one of them. Design for ${layout.narrowWidthPx} first; where the layout depends on the width, read it as it runs (the box's clientWidth, again from a ResizeObserver). ${height} It runs in the person's light or dark theme, and again each time it is shown${loadsScripts(config) ? ": pin library versions" : ""}.`,
+    `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(
@@ -173,7 +177,9 @@ function widget(c: Context): string {
       ? "\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,
     "",
-    `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).`,
+    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-") === ""

package/src/host/create-host.ts

@@ -4,6 +4,7 @@ import { declaredCapabilities } from "../compile/policy.ts";
 import { capabilitySpec } from "../config/capabilities.ts";
 import type { ColorScheme, PortholeConfig } from "../config/schema.ts";
 import { locateServed } from "./locate.ts";
+import { watchOutcome, type OutcomeWatch } from "./outcome.ts";
 import type { FrameSource } from "../isolation/types.ts";
 import { webPlatform } from "../platform/web.ts";
 import type { Surface } from "../platform/types.ts";
@@ -23,6 +24,9 @@ import type {
   PortholeHost,
 } from "./types.ts";
 
+/** How long a display may take to load before its outcome is a timeout, by default. */
+const DEFAULT_LOAD_TIMEOUT_MS = 15_000;
+
 /** How many times a display is started again after its content navigated its frame away. */
 const MAX_RESTARTS = 3;
 
@@ -81,12 +85,14 @@ export function createHost<C extends AdapterConnection = ShellConnection>(
       let restarts = 0;
       let generation = 0;
       let abort: AbortController | null = null;
+      let outcomeWatch: OutcomeWatch | null = null;
+      let themeFrame: number | null = null;
+      const view = container.ownerDocument.defaultView;
       // The adapter's own operations, the last call of each, replayed into every new frame.
       const replay = new Map<string, unknown[]>();
 
       const hostContext = (): HostContext => {
         const width = container.getBoundingClientRect().width;
-        const view = container.ownerDocument.defaultView;
         // The spec's names in `styles` (the App SDK refuses others there), the rest in our field.
         const variables = resolveTheme(config.theme, scheme, options.theme?.(scheme));
         const standard: Record<string, string> = {};
@@ -142,6 +148,8 @@ export function createHost<C extends AdapterConnection = ShellConnection>(
       const stop = () => {
         abort?.abort();
         abort = null;
+        outcomeWatch?.stop();
+        outcomeWatch = null;
         connection?.close();
         connection = null;
         surface?.destroy();
@@ -156,10 +164,29 @@ export function createHost<C extends AdapterConnection = ShellConnection>(
           allow: compiled.allow,
           referrerPolicy: compiled.referrerPolicy,
           colorScheme: scheme,
-          initialHeightPx: height,
+          // An app reports no size: its frame fills the host's container, at least the minimum.
+          ...(speaks
+            ? { initialHeightPx: height }
+            : { fill: true, initialHeightPx: config.limits.minHeightPx }),
         });
         surface = created;
+        const watch = watchOutcome({
+          surface: created,
+          source,
+          speaks,
+          timeoutMs: config.limits.loadTimeoutMs ?? DEFAULT_LOAD_TIMEOUT_MS,
+          onOutcome: (outcome) => emit("outcome", outcome),
+        });
+        outcomeWatch = watch;
         if (!speaks) {
+          // No handshake in url mode: the app's first document loading is as ready as it gets.
+          let ready = false;
+          created.onLoad(() => {
+            if (!ready) {
+              ready = true;
+              emit("initialized", undefined);
+            }
+          });
           return;
         }
         const bridge = createBridge({
@@ -179,6 +206,7 @@ export function createHost<C extends AdapterConnection = ShellConnection>(
           hostContext,
           emit: (event) => {
             if (event.type === "initialized") {
+              watch.initialized();
               emit("initialized", undefined);
             }
           },
@@ -249,6 +277,23 @@ export function createHost<C extends AdapterConnection = ShellConnection>(
         setTheme(next: ColorScheme) {
           scheme = next;
           surface?.setColorScheme(next);
+          // Read the host's values two frames later: a host that restyles its page for the new
+          // scheme on its next frame has done so by then.
+          if (view === null) {
+            connection?.hostContextChanged(hostContext());
+            return;
+          }
+          if (themeFrame !== null) {
+            view.cancelAnimationFrame(themeFrame);
+          }
+          themeFrame = view.requestAnimationFrame(() => {
+            themeFrame = view.requestAnimationFrame(() => {
+              themeFrame = null;
+              connection?.hostContextChanged(hostContext());
+            });
+          });
+        },
+        refreshTheme() {
           connection?.hostContextChanged(hostContext());
         },
         on<E extends keyof DisplayEvents>(event: E, listener: (detail: DisplayEvents[E]) => void) {

package/src/host/locate.ts

@@ -16,5 +16,10 @@ export async function locateServed(
 ): Promise<FrameSource> {
   const location = await locator.locate(instance, signal);
   checkFrameLocation(location, config.contentOrigins, hostOrigin);
-  return { kind: "url", url: new URL(location.url).href, origin: location.origin };
+  return {
+    kind: "url",
+    url: new URL(location.url).href,
+    origin: location.origin,
+    ...(location.reports === true ? { reports: true } : {}),
+  };
 }