@botiverse/porthole 0.1.0 → 0.1.1

package/dist/bridge/bridge.js

@@ -134,18 +134,26 @@ export function createBridge(options) {
                     return refuse(capability, "no-user-activation");
                 }
             }
+            // The effect, run once: when the person's "yes" calls `proceed` (inside its own click, so an
+            // effect that needs a gesture gets one), or after `confirm` resolves accepted.
+            let effect = null;
+            const run = () => (effect ??= perform(capability, args));
             if (confirms) {
                 if (options.confirm === undefined) {
                     return refuse(capability, "no-confirm");
                 }
-                let accepted = false;
+                let answer = false;
                 try {
-                    accepted = await options.confirm({ capability, args, display });
+                    answer = await options.confirm({ capability, args, display }, () => void run());
                 }
                 catch {
-                    accepted = false;
+                    answer = effect === null ? false : "accepted";
                 }
-                if (!accepted) {
+                if (effect === null && answer !== true && answer !== "accepted") {
+                    if (answer === "redirected") {
+                        return refuse(capability, "redirected");
+                    }
+                    // Declines in a row mute the display; a yes starts the count again.
                     declines += 1;
                     if (declines >= config.limits.declinesBeforeMute && !muted) {
                         muted = true;
@@ -153,7 +161,13 @@ export function createBridge(options) {
                     }
                     return refuse(capability, "declined");
                 }
+                declines = 0;
             }
+            return run();
+        },
+    };
+    async function perform(capability, args) {
+        {
             if (capabilitySpec(capability).served === "event") {
                 if (capability === "resize") {
                     const size = args;
@@ -179,6 +193,6 @@ export function createBridge(options) {
             catch (error) {
                 return refuse(capability, "failed", error instanceof Error ? error.message : String(error));
             }
-        },
-    };
+        }
+    }
 }

package/dist/bridge/types.d.ts

@@ -29,10 +29,24 @@ export type ConfirmRequest = {
     };
 }[CapabilityName];
 /**
- * Asks a person. Resolves true only if they accept. The host's UI, or the React binding's default
- * dialog; drawn outside the frame, never inside it.
+ * What the person chose. `true`/`"accepted"`: the call goes. `false`/`"declined"`: it doesn't,
+ * and the decline counts toward muting the display. `"redirected"`: it doesn't go, but the person
+ * took it elsewhere (edited the prompt first, say), so it neither counts as a decline nor resets
+ * the count. The host decides which its UI's choices are.
  */
-export type Confirm = (request: ConfirmRequest) => Promise<boolean>;
+export type ConfirmAnswer = boolean | "accepted" | "declined" | "redirected";
+/**
+ * Runs the call's effect now, inside the caller's own gesture, and counts as accepted. A host
+ * whose effect needs the person's gesture (opening a window) calls it from the click handler of
+ * its own "yes" button, rather than resolving the promise and letting the effect run after.
+ */
+export type Proceed = () => void;
+/**
+ * Asks a person. Resolves with their answer. The host's UI, or the React binding's default
+ * dialog; drawn outside the frame, never inside it. `proceed` (optional to use) runs the effect
+ * within the "yes" click itself.
+ */
+export type Confirm = (request: ConfirmRequest, proceed: Proceed) => Promise<ConfirmAnswer>;
 /** Why a call didn't run. */
 export type Refusal = 
 /** The config doesn't declare it. */
@@ -45,6 +59,8 @@ export type Refusal =
  | "no-confirm"
 /** The person declined. */
  | "declined"
+/** The person took it elsewhere (edited it first): not sent, not counted as a decline. */
+ | "redirected"
 /** The display was muted after too many declines (until it runs again). */
  | "muted" | "rate-limited"
 /** The host's handler threw or rejected. */

package/dist/compile/policy.d.ts

@@ -48,8 +48,8 @@ export declare function allowAttribute(_config: PortholeConfig): string;
 export declare function embedderFrameSources(config: PortholeConfig): string[];
 /**
  * The CSP the embedding page sends (a header, or the host's own document's policy), for every kind
- * of display it shows. It sets no `default-src`: it restricts frames only, leaving the host's own
- * scripts, styles and fetches to the host's policy. `child-src` repeats `frame-src` for engines
- * that read frames from it.
+ * of display it shows. Frames only: no `default-src`, so the host's own scripts, styles and
+ * fetches stay its policy's; and no `child-src`, which the host's workers would fall back to (every
+ * engine Porthole supports reads frames from `frame-src`, P038).
  */
 export declare function embedderCsp(configs: readonly PortholeConfig[]): string;

package/dist/compile/policy.js

@@ -69,7 +69,8 @@ export function sandboxTokens(config) {
         case "domain":
             return ["allow-scripts", "allow-same-origin"];
         case "external":
-            return ["allow-scripts", "allow-same-origin", "allow-forms"];
+            // The host may add a documented few (popups, modals, downloads), never top navigation.
+            return ["allow-scripts", "allow-same-origin", "allow-forms", ...(config.sandbox ?? [])];
     }
 }
 /**
@@ -92,15 +93,11 @@ export function embedderFrameSources(config) {
 }
 /**
  * The CSP the embedding page sends (a header, or the host's own document's policy), for every kind
- * of display it shows. It sets no `default-src`: it restricts frames only, leaving the host's own
- * scripts, styles and fetches to the host's policy. `child-src` repeats `frame-src` for engines
- * that read frames from it.
+ * of display it shows. Frames only: no `default-src`, so the host's own scripts, styles and
+ * fetches stay its policy's; and no `child-src`, which the host's workers would fall back to (every
+ * engine Porthole supports reads frames from `frame-src`, P038).
  */
 export function embedderCsp(configs) {
     const sources = unique(configs.flatMap(embedderFrameSources));
-    const all = sources.length === 0 ? ["'none'"] : sources;
-    return serializeCsp([
-        ["frame-src", ...all],
-        ["child-src", ...all],
-    ]);
+    return serializeCsp([["frame-src", ...(sources.length === 0 ? ["'none'"] : sources)]]);
 }

package/dist/config/schema.d.ts

@@ -67,6 +67,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 {
     /** The tallest the frame grows before its content scrolls inside it. */
@@ -83,7 +90,19 @@ 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 declare const URL_SANDBOX_EXTRAS: readonly ["allow-popups", "allow-popups-to-escape-sandbox", "allow-modals", "allow-downloads"];
+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). */
@@ -128,4 +147,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/dist/config/schema.js

@@ -1 +1,11 @@
-export {};
+/**
+ * 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",
+];

package/dist/config/validate.d.ts

@@ -1,4 +1,4 @@
-import type { PortholeConfig } from "./schema.ts";
+import { type PortholeConfig } from "./schema.ts";
 /**
  * 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
@@ -16,5 +16,7 @@ export declare const BUILT_IN_TOPICS: readonly ["widget", "chart", "interactive"
  * every subdomain) and an optional port, nothing else. Insecure schemes only for loopback names.
  */
 export declare function isOriginSource(value: unknown): value is string;
+/** Why `value` isn't an origin source Porthole accepts, in words to act on; null if it is. */
+export declare function originSourceProblem(value: unknown): string | null;
 /** Returns `input` as a config once every field checks out; throws a `ConfigError` otherwise. */
 export declare function validateConfig(input: unknown): PortholeConfig;

package/dist/config/validate.js

@@ -1,4 +1,5 @@
 import { CAPABILITY_NAMES, isCapabilityName } from "./capabilities.js";
+import { 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
@@ -22,24 +23,29 @@ const HOST = /^(\*\.)?([a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?)(\.[a-z0-9]([a-z0-9-]{
  * every subdomain) and an optional port, nothing else. Insecure schemes only for loopback names.
  */
 export function isOriginSource(value) {
+    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) {
+    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, message) => {
     throw new ConfigError(path, message);
@@ -64,8 +70,9 @@ function sources(value, path) {
         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);
         }
     });
 }
@@ -102,6 +109,7 @@ export function validateConfig(input) {
         "guide",
         "contentOrigins",
         "embedder",
+        "sandbox",
     ], "config");
     if (!MODES.includes(config.mode)) {
         fail("config.mode", `must be one of ${MODES.join(", ")}`);
@@ -142,7 +150,12 @@ export function validateConfig(input) {
         sources(egress[kind], `config.egress.${kind}`);
     }
     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)}]`;
@@ -175,10 +188,13 @@ export function validateConfig(input) {
         "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 > limits.maxHeightPx) {
         fail("config.limits.minHeightPx", "must not exceed maxHeightPx");
     }
@@ -226,5 +242,20 @@ export function validateConfig(input) {
     sources(Array.isArray(embedder.frameSrc)
         ? embedder.frameSrc.filter((source) => source !== "'self'")
         : embedder.frameSrc, "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.forEach((token, index) => {
+            if (!URL_SANDBOX_EXTRAS.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;
 }

package/dist/conformance/behavior.js

@@ -248,6 +248,56 @@ export const BEHAVIOR_PROBES = [
             expect(styles.height, "a control is tall enough to tap").toBeGreaterThanOrEqual(44);
         },
     },
+    {
+        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, id) => `<!doctype html><html><head><title>Page</title>${head}</head><body><p id="${id}">page</p></body></html>`;
+            const scheme = (display, id) => 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/dist/conformance/index.d.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,6 +96,6 @@ export interface LeakSuiteOptions {
     /** Probe ids to skip, each with the reason (shown in the report). */
     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";
-export { defineServedSuite, type ServedConformanceHost, type ServedDisplay, type ServedSuiteOptions, } from "./served.ts";
+export { defineServedSuite, servedTests, type ServedConformanceHost, type ServedDisplay, type ServedSuiteOptions, } from "./served.ts";

package/dist/conformance/index.js

@@ -1,4 +1,4 @@
-export { defineLeakSuite, PROBES } from "./probes.js";
+export { defineLeakSuite, leakTests, PROBES, } from "./probes.js";
 export { httpOracle, settle, udpOracle } from "./oracles.js";
 // The served modes' cases (domain and url mode), with their own host interface.
-export { defineServedSuite, } from "./served.js";
+export { defineServedSuite, servedTests, } from "./served.js";

package/dist/conformance/probes.d.ts

@@ -1,9 +1,33 @@
-import { type PlaywrightTestArgs, type PlaywrightTestOptions, type PlaywrightWorkerArgs, type PlaywrightWorkerOptions, type TestType } from "@playwright/test";
+import { type PlaywrightTestArgs, type PlaywrightTestOptions, type PlaywrightWorkerArgs, type PlaywrightWorkerOptions, type Page, type TestInfo, type TestType } from "@playwright/test";
 import type { ConformanceHost, LeakSuiteOptions } from "./index.ts";
 import { type Probe } from "./kit.ts";
 export type { Probe, ProbeContext } from "./kit.ts";
 export { attack } from "./kit.ts";
 export declare const PROBES: readonly Probe[];
 type AnyTest = TestType<PlaywrightTestArgs & PlaywrightTestOptions, 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 declare function leakTests(host: ConformanceHost, options?: LeakSuiteOptions): ConformanceTest[];
+/**
+ * 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 declare function defineLeakSuite(test: AnyTest, host: ConformanceHost, options?: LeakSuiteOptions): void;

package/dist/conformance/probes.js

@@ -818,48 +818,59 @@ export const PROBES = [
     },
     ...BEHAVIOR_PROBES,
 ];
-/** Registers every probe as a test, grouped by egress item. */
+/** Every probe as a test entry (see `ConformanceTest`). */
+export function leakTests(host, options = {}) {
+    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 = [];
+            const requests = [];
+            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.portholeProbe
+                            ?.done))
+                            .catch(() => false), { timeout: timeoutMs })
+                            .toBe(true);
+                        return (await display.frame()).evaluate(() => window.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, host, options = {}) {
     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 = [];
-                const requests = [];
-                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
-                                .portholeProbe?.done))
-                                .catch(() => false), { timeout: timeoutMs })
-                                .toBe(true);
-                            return (await display.frame()).evaluate(() => window.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/dist/conformance/served.d.ts

@@ -12,6 +12,7 @@
  * one exists (a canary URL the host counts requests to), that nothing got through.
  */
 import { type Frame, type Page, 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";
 /** One served display, as the host shows it. */
@@ -65,4 +66,10 @@ export interface ServedSuiteOptions {
     readonly skip?: Readonly<Record<string, string>>;
 }
 /** 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 declare function defineServedSuite(test: TestType<object, object>, host: ServedConformanceHost, options?: ServedSuiteOptions): void;
+/** Every served-mode case as a test entry (see `ConformanceTest`). */
+export declare function servedTests(host: ServedConformanceHost, options?: ServedSuiteOptions): ConformanceTest[];

package/dist/conformance/served.js

@@ -71,17 +71,40 @@ async function plantHostSecrets(page) {
     });
 }
 /** 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, host, options = {}) {
     const typed = test;
+    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, options = {}) {
+    const tests = [];
+    let info = null;
+    // The case being run's own TestInfo (for an expected failure measured on one engine).
+    const typed = {
+        fail: (condition, reason) => info?.fail(condition, reason),
+    };
     const define = (id, title, body) => {
-        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) => host.shell(scope)],
             ["url", (scope) => host.app(scope)],
@@ -307,5 +330,6 @@ export function defineServedSuite(test, host, options = {}) {
             })
                 .toBe("ready");
         });
-    });
+    }
+    return tests;
 }