@botiverse/porthole 0.1.0 → 0.1.2

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 } : {}),
+  };
 }

package/src/host/outcome.ts

@@ -0,0 +1,177 @@
+import { FRAME_STATUS_METHOD, type FrameSource } from "../isolation/types.ts";
+import type { Surface } from "../platform/types.ts";
+import type { FrameBlock, FrameOutcome } from "./types.ts";
+
+/**
+ * How a display's first document went (P040). A frame's content is another origin's, so the host
+ * can't look inside; it goes by what it can see:
+ *
+ * - a shell or view that speaks for itself is loaded when it finishes its handshake;
+ * - a page of Porthole's `/server` says how it went (`porthole/notifications/frame-status`): it is
+ *   entering an app, or blocked (its ticket used, no cookie kept in a frame, the app down); a url
+ *   app is loaded when its document loads after the entry page;
+ * - a load from which nothing ever spoke, where something should have, is a page that never ran:
+ *   framing refused;
+ * - an app from a host's own gateway is loaded on its first load, unless its page says it is
+ *   blocked (the gateway may send the same message);
+ * - nothing settled in `timeoutMs`: a timeout.
+ */
+
+/** How long after a load the frame's word may still arrive. */
+const SETTLE_MS = 400;
+
+const BLOCKS: readonly FrameBlock[] = [
+  "framing",
+  "cookies",
+  "session",
+  "upstream",
+  "denied",
+  "not-found",
+  "error",
+];
+
+interface FrameStatus {
+  readonly state: "entering" | "blocked";
+  readonly reason?: FrameBlock;
+  readonly status?: number;
+  readonly code?: string;
+}
+
+/** A frame-status message, or null for anything else. */
+export function parseFrameStatus(data: unknown): FrameStatus | null {
+  if (data === null || typeof data !== "object") {
+    return null;
+  }
+  const message = data as { jsonrpc?: unknown; method?: unknown; params?: unknown };
+  if (message.jsonrpc !== "2.0" || message.method !== FRAME_STATUS_METHOD) {
+    return null;
+  }
+  const params = message.params as {
+    state?: unknown;
+    reason?: unknown;
+    status?: unknown;
+    code?: unknown;
+  } | null;
+  if (params === null || typeof params !== "object") {
+    return null;
+  }
+  if (params.state === "entering") {
+    return { state: "entering" };
+  }
+  if (params.state !== "blocked") {
+    return null;
+  }
+  const reason = BLOCKS.includes(params.reason as FrameBlock)
+    ? (params.reason as FrameBlock)
+    : "error";
+  return {
+    state: "blocked",
+    reason,
+    ...(typeof params.status === "number" && Number.isInteger(params.status)
+      ? { status: params.status }
+      : {}),
+    ...(typeof params.code === "string" && /^[a-z0-9-]{1,40}$/u.test(params.code)
+      ? { code: params.code }
+      : {}),
+  };
+}
+
+export interface OutcomeWatch {
+  /** The frame finished its handshake. */
+  initialized(): void;
+  stop(): void;
+}
+
+export function watchOutcome(options: {
+  readonly surface: Surface;
+  readonly source: FrameSource;
+  /** Whether the frame speaks for itself (a shell or a view): then its handshake is the proof. */
+  readonly speaks: boolean;
+  readonly timeoutMs: number;
+  readonly onOutcome: (outcome: FrameOutcome) => void;
+}): OutcomeWatch {
+  const { surface, source, speaks } = options;
+  const reports = source.kind === "url" && source.reports === true;
+  // The first outcome; after a load, only a later block (a status page, access revoked) is told.
+  let decided: FrameOutcome["state"] | null = null;
+  let heard = false;
+  let entering = false;
+  let loads = 0;
+  const timers = new Set<ReturnType<typeof setTimeout>>();
+  const later = (ms: number, run: () => void) => {
+    const timer = setTimeout(() => {
+      timers.delete(timer);
+      run();
+    }, ms);
+    timers.add(timer);
+  };
+  const clearTimers = () => {
+    for (const timer of timers) {
+      clearTimeout(timer);
+    }
+    timers.clear();
+  };
+  const stop = () => {
+    clearTimers();
+    unlisten();
+    unload();
+  };
+  const decide = (outcome: FrameOutcome) => {
+    if (decided === null) {
+      decided = outcome.state;
+      clearTimers();
+      options.onOutcome(outcome);
+    } else if (decided === "loaded" && outcome.state === "blocked") {
+      decided = "blocked";
+      options.onOutcome(outcome);
+    }
+  };
+  const unlisten = surface.transport.listen((data) => {
+    heard = true;
+    const status = parseFrameStatus(data);
+    if (status?.state === "entering") {
+      entering = true;
+    } else if (status?.state === "blocked") {
+      decide({
+        state: "blocked",
+        reason: status.reason ?? "error",
+        ...(status.status === undefined ? {} : { status: status.status }),
+        ...(status.code === undefined ? {} : { code: status.code }),
+      });
+    }
+  });
+  const neverRan = () =>
+    later(SETTLE_MS, () => {
+      if (!heard) {
+        decide({ state: "blocked", reason: "framing" });
+      }
+    });
+  const unload = surface.onLoad(() => {
+    loads += 1;
+    if (decided !== null) {
+      return;
+    }
+    if (speaks) {
+      // A served shell or view says something before its first load ends; one that never did
+      // never ran. (An opaque srcdoc frame always runs: its handshake decides.)
+      if (source.kind === "url") {
+        neverRan();
+      }
+      return;
+    }
+    if (!reports) {
+      later(SETTLE_MS, () => decide({ state: "loaded" }));
+      return;
+    }
+    if (entering && loads >= 2) {
+      decide({ state: "loaded" });
+    } else if (!entering) {
+      neverRan();
+    }
+  });
+  later(options.timeoutMs, () => decide({ state: "timeout" }));
+  return {
+    initialized: () => decide({ state: "loaded" }),
+    stop,
+  };
+}