@catalystiq/test-kit 0.0.0-stage → 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 CatalystIQ
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,24 @@
-# Temporary Holding Version
+# @catalystiq/test-kit
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Shared test helpers: one package, added to part by part. Pin an exact version (`"@catalystiq/test-kit": "0.2.0"`);
+Dependabot raises it.
+
+| Part | Import | What |
+|---|---|---|
+| Setup | `@catalystiq/test-kit/setup/config`, `/setup`, `/setup/dom` | Vitest defaults and the safety setup: credentials stripped, network blocked, production and `.env*` databases refused, React warnings fail the test. (`dist/setup/README.md` in the package) |
+| Neon test database | `tk-neon-test-db` (bin), `@catalystiq/test-kit/neon-test-db` | `npm run test:db`: a short-lived schema-only Neon branch for one command, deleted afterwards; moved from github-actions' vendored `scripts/neon-test-db.mjs`. (`dist/neon-test-db/README.md` in the package) |
+| MCP Apps host | `@catalystiq/test-kit/mcp-apps-host`, `/mcp-apps-host/playwright` | A fake ChatGPT or Claude host for an MCP Apps card, in jsdom and in Playwright, and `tk-check-bundle`. (`dist/mcp-apps-host/README.md` in the package) |
+
+Vitest 4.1 and Node 22.18 or later. Every peer dependency is optional; install what the parts you use need (`vitest`,
+`@playwright/test`, `@testing-library/react`, `@testing-library/jest-dom`).
+
+## Developing
+
+`npm test` runs the unit suite and the rule proofs: each rule is shown working, then cut out of a copy of `src` and shown
+failing (`test/support/run-fixture.ts`). `npm run test:browser` runs the Playwright host and its rule proofs (Chromium).
+`npm run typecheck`, `npm run lint`, `npm run build`.
+
+## Releasing
+
+Raise `version` in `package.json` in a pull request. After it merges, publish a GitHub release tagged `v<version>`;
+`.github/workflows/publish.yml` checks the tag matches, runs the checks, and publishes to npm.

package/dist/bin/check-allowlist.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/bin/check-allowlist.js

@@ -0,0 +1,23 @@
+#!/usr/bin/env node
+// tk-check-allowlist <file> [--base origin/main]: fails when the React-warning allow-list grew against its base.
+import { checkAllowListAgainstBase } from "../bundle/allow-list-base.js";
+const args = process.argv.slice(2);
+const at = args.indexOf('--base');
+const base = at >= 0 ? args[at + 1] : 'origin/main';
+const file = args.find((a, i) => !a.startsWith('--') && args[i - 1] !== '--base');
+try {
+    if (!file || !base)
+        throw new Error('usage: tk-check-allowlist <file> [--base origin/main]');
+    const problems = checkAllowListAgainstBase(file, base);
+    if (problems.length > 0) {
+        console.error(`tk-check-allowlist: ${file} grew against ${base}; its entries only shrink:\n  ${problems.join('\n  ')}`);
+        process.exitCode = 1;
+    }
+    else {
+        console.log(`ok   ${file} did not grow against ${base}`);
+    }
+}
+catch (error) {
+    console.error(`tk-check-allowlist: ${error.message}`);
+    process.exitCode = 1;
+}

package/dist/bin/check-bundle.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/bin/check-bundle.js

@@ -0,0 +1,19 @@
+#!/usr/bin/env node
+// tk-check-bundle [--config tk-bundles.json] [--write]: see src/bundle/manifest.ts.
+import { runBundleCheck } from "../bundle/manifest.js";
+const args = process.argv.slice(2);
+const at = args.indexOf('--config');
+const config = at >= 0 ? args[at + 1] : 'tk-bundles.json';
+const write = args.includes('--write');
+try {
+    if (!config)
+        throw new Error('--config needs a path');
+    const results = runBundleCheck(process.cwd(), config, write);
+    for (const r of results)
+        console.log(`${r.ok ? 'ok  ' : 'FAIL'} ${r.message}`);
+    process.exitCode = results.every((r) => r.ok) ? 0 : 1;
+}
+catch (error) {
+    console.error(`tk-check-bundle: ${error.message}`);
+    process.exitCode = 1;
+}

package/dist/bundle/allow-list-base.d.ts

@@ -0,0 +1,3 @@
+/** The file as `base` has it, or null when the base has no such file. Throws when the base ref itself is missing. */
+export declare function readAtBase(file: string, base: string, cwd?: string): unknown;
+export declare function checkAllowListAgainstBase(file: string, base: string, cwd?: string): string[];

package/dist/bundle/allow-list-base.js

@@ -0,0 +1,27 @@
+/** `tk-check-allowlist`: the React-warning allow-list may only shrink against its base branch. */
+import { execFileSync } from 'node:child_process';
+import { relative, resolve } from 'node:path';
+import { allowListGrowth, parseAllowList, readAllowList } from "../setup/allow-list.js";
+/** The file as `base` has it, or null when the base has no such file. Throws when the base ref itself is missing. */
+export function readAtBase(file, base, cwd = process.cwd()) {
+    const git = (args) => execFileSync('git', args, { cwd, encoding: 'utf8', stdio: ['ignore', 'pipe', 'pipe'] });
+    try {
+        git(['rev-parse', '--verify', '--quiet', `${base}^{commit}`]);
+    }
+    catch {
+        throw new Error(`the base ${base} is not in this checkout: fetch it (actions/checkout with fetch-depth: 0)`);
+    }
+    // `<rev>:./path` is relative to the working directory, which survives a symlinked checkout path.
+    const path = relative(cwd, resolve(cwd, file)).split('\\').join('/');
+    try {
+        return JSON.parse(git(['show', `${base}:./${path}`]));
+    }
+    catch {
+        return null;
+    }
+}
+export function checkAllowListAgainstBase(file, base, cwd = process.cwd()) {
+    const current = readAllowList(resolve(cwd, file));
+    const atBase = readAtBase(file, base, cwd);
+    return allowListGrowth(current, atBase === null ? null : parseAllowList(atBase, `${file} at ${base}`));
+}

package/dist/bundle/manifest.d.ts

@@ -0,0 +1,29 @@
+export type VersionSource = {
+    file: string;
+    pattern: string;
+} | {
+    file: string;
+    pointer: string;
+};
+export interface BundleEntry {
+    bundle: string;
+    version: VersionSource;
+    manifest?: string;
+}
+export interface BundleManifest {
+    version: string;
+    sha256: string;
+}
+export interface BundleResult {
+    bundle: string;
+    ok: boolean;
+    message: string;
+}
+export declare function parseBundleConfig(value: unknown, source?: string): BundleEntry[];
+export declare function readVersion(root: string, source: VersionSource): string;
+export declare function manifestPath(entry: BundleEntry): string;
+/** Checks one bundle against its manifest. */
+export declare function checkBundle(root: string, entry: BundleEntry): BundleResult;
+/** Records one bundle's manifest, refusing a changed bundle under an unchanged version. */
+export declare function writeBundleManifest(root: string, entry: BundleEntry): BundleResult;
+export declare function runBundleCheck(root: string, configFile: string, write: boolean): BundleResult[];

package/dist/bundle/manifest.js

@@ -0,0 +1,124 @@
+/**
+ * `tk-check-bundle`: a built card bundle that changed must carry a new version. Hosts cache an MCP Apps resource by its
+ * URI, so a card whose bytes changed under the same version reaches some users and not others.
+ *
+ * Each bundle has a committed manifest beside it, `{ "version": "…", "sha256": "…" }`. `--write` records the bundle's
+ * hash and current version, and REFUSES when the hash moved but the version did not; the check (CI) fails unless the
+ * manifest matches the bundle and version exactly, so the manifest is updated in the same change as the bundle.
+ *
+ * The config, `tk-bundles.json` at the repository root:
+ *
+ *     { "bundles": [{
+ *         "bundle": "src/card/generated/card.html",
+ *         "version": { "file": "src/card/version.ts", "pattern": "CARD_VERSION = '([^']+)'" },
+ *         "manifest": "src/card/generated/card.version.json"
+ *     }] }
+ *
+ * `version` is a regular expression whose first group is the version, or `{ "file": "package.json", "pointer":
+ * "/version" }` for a JSON file. `manifest` defaults to the bundle's path plus `.version.json`.
+ */
+import { createHash } from 'node:crypto';
+import { existsSync, readFileSync, writeFileSync } from 'node:fs';
+import { resolve } from 'node:path';
+export function parseBundleConfig(value, source = 'tk-bundles.json') {
+    const bundles = value?.bundles;
+    if (!Array.isArray(bundles))
+        throw new Error(`${source} must be { "bundles": [...] }`);
+    if (bundles.length === 0)
+        throw new Error(`${source} lists no bundles: a check over nothing proves nothing`);
+    return bundles.map((raw, i) => {
+        const e = raw;
+        if (!e || typeof e.bundle !== 'string')
+            throw new Error(`${source}: bundle ${i} needs a "bundle" path`);
+        const v = e.version;
+        if (!v || typeof v.file !== 'string' || (typeof v.pattern !== 'string' && typeof v.pointer !== 'string')) {
+            throw new Error(`${source}: bundle ${i} needs "version": { "file", "pattern" } or { "file", "pointer" }`);
+        }
+        return { bundle: e.bundle, version: v, ...(typeof e.manifest === 'string' ? { manifest: e.manifest } : {}) };
+    });
+}
+function jsonPointer(value, pointer) {
+    if (pointer === '')
+        return value;
+    return pointer
+        .split('/')
+        .slice(1)
+        .map((part) => part.replaceAll('~1', '/').replaceAll('~0', '~'))
+        .reduce((at, key) => (at && typeof at === 'object' ? at[key] : undefined), value);
+}
+export function readVersion(root, source) {
+    const path = resolve(root, source.file);
+    if (!existsSync(path))
+        throw new Error(`the version file ${source.file} does not exist`);
+    const text = readFileSync(path, 'utf8');
+    if ('pattern' in source) {
+        const match = new RegExp(source.pattern).exec(text);
+        if (!match?.[1])
+            throw new Error(`no version in ${source.file}: /${source.pattern}/ matched no first group`);
+        return match[1];
+    }
+    const found = jsonPointer(JSON.parse(text), source.pointer);
+    if (typeof found !== 'string' && typeof found !== 'number')
+        throw new Error(`no version at ${source.pointer} in ${source.file}`);
+    return String(found);
+}
+export function manifestPath(entry) {
+    return entry.manifest ?? `${entry.bundle}.version.json`;
+}
+function current(root, entry) {
+    const path = resolve(root, entry.bundle);
+    if (!existsSync(path))
+        throw new Error(`the bundle ${entry.bundle} does not exist; build it first`);
+    return { version: readVersion(root, entry.version), sha256: createHash('sha256').update(readFileSync(path)).digest('hex') };
+}
+function recorded(root, entry) {
+    const path = resolve(root, manifestPath(entry));
+    if (!existsSync(path))
+        return null;
+    const value = JSON.parse(readFileSync(path, 'utf8'));
+    if (typeof value.version !== 'string' || typeof value.sha256 !== 'string')
+        throw new Error(`${manifestPath(entry)} is not { version, sha256 }`);
+    return { version: value.version, sha256: value.sha256 };
+}
+const UNCHANGED_VERSION = (entry, version) => `${entry.bundle} changed but its version is still ${version}. Raise the version, rebuild, then run tk-check-bundle --write.`;
+/** Checks one bundle against its manifest. */
+export function checkBundle(root, entry) {
+    try {
+        const now = current(root, entry);
+        const was = recorded(root, entry);
+        if (was === null)
+            return { bundle: entry.bundle, ok: false, message: `${manifestPath(entry)} is missing: run tk-check-bundle --write` };
+        if (was.sha256 !== now.sha256 && was.version === now.version) {
+            return { bundle: entry.bundle, ok: false, message: UNCHANGED_VERSION(entry, now.version) };
+        }
+        if (was.sha256 !== now.sha256 || was.version !== now.version) {
+            return { bundle: entry.bundle, ok: false, message: `${manifestPath(entry)} is out of date: run tk-check-bundle --write and commit it` };
+        }
+        return { bundle: entry.bundle, ok: true, message: `${entry.bundle} ${now.version}` };
+    }
+    catch (error) {
+        return { bundle: entry.bundle, ok: false, message: error.message };
+    }
+}
+/** Records one bundle's manifest, refusing a changed bundle under an unchanged version. */
+export function writeBundleManifest(root, entry) {
+    try {
+        const now = current(root, entry);
+        const was = recorded(root, entry);
+        if (was !== null && was.sha256 !== now.sha256 && was.version === now.version) {
+            return { bundle: entry.bundle, ok: false, message: UNCHANGED_VERSION(entry, now.version) };
+        }
+        writeFileSync(resolve(root, manifestPath(entry)), `${JSON.stringify(now, null, 2)}\n`);
+        return { bundle: entry.bundle, ok: true, message: `wrote ${manifestPath(entry)} (${now.version})` };
+    }
+    catch (error) {
+        return { bundle: entry.bundle, ok: false, message: error.message };
+    }
+}
+export function runBundleCheck(root, configFile, write) {
+    const path = resolve(root, configFile);
+    if (!existsSync(path))
+        throw new Error(`${configFile} does not exist`);
+    const entries = parseBundleConfig(JSON.parse(readFileSync(path, 'utf8')), configFile);
+    return entries.map((entry) => (write ? writeBundleManifest(root, entry) : checkBundle(root, entry)));
+}

package/dist/mcp-apps-host/README.md

@@ -0,0 +1,70 @@
+# `@catalystiq/test-kit/mcp-apps-host`
+
+One fake MCP Apps host, in two forms that share one protocol core, so a card meets the same answers in jsdom and in a
+real browser. Every message is recorded both ways (`host.log`, `from: 'app' | 'host'`), and a console error, a page
+error, a stray network request or a tool call the test did not expect fails the test.
+
+## Profiles
+
+| | `chatgpt` | `claude` |
+|---|---|---|
+| `updateModelContext` capability | listed | not listed; `ui/update-model-context` answers -32601 |
+| `window.openai` (browser form) | optional stub: `openai: 'both' \| 'upload-only' \| 'upload-rejects' \| 'download-rejects'` | refused |
+
+Both: `openLinks`, `serverTools`, `logging`, `message`; the app's `protocolVersion` is echoed; after `initialized` the
+host sends `tool-input` (when given) then `tool-result`.
+
+Options both forms take: `answer(name, args)` (return `undefined` for a call you did not expect), `hold` (hold answers
+until `release()`), `theme`, `displayMode`, `displayModes: 'declared' | 'inline' | 'fail'`, `openLink`, `message`,
+`modelContext` (chatgpt), `refuseInitialize`, `width`, `height`, `locale`, `timeZone`, `hostCapabilities`,
+`hostContext`. As the host: `sendToolResult`, `sendToolInput`, `cancelTool`, `changeContext`, `setTheme`, `teardown`.
+To read: `calls(name?)`, `sent(method)`, `methods()`, `actions()`, `messages()`, `modelContext()`, `links()`,
+`unanswered`.
+
+## jsdom (Vitest)
+
+```ts
+// @vitest-environment jsdom
+import { createMemoryHost } from '@catalystiq/test-kit/mcp-apps-host';
+
+const host = createMemoryHost({ profile: 'chatgpt', toolResult: { content: [], structuredContent: { items: 2 } } });
+await app.connect(host.transport); // or host.installParent() for an app that connects to window.parent itself
+```
+
+Messages arrive on a microtask, as `postMessage` delivers them. Opened in a test, the host fails it when it ends on any
+problem; `assertClean()` asks at any moment; `network(url)` answers a request the test expects.
+
+## Playwright
+
+```ts
+import { openApp, test, expect } from '@catalystiq/test-kit/mcp-apps-host/playwright';
+
+test('the card', async ({ page }) => {
+  const host = await openApp(page, { html: cardBundleHtml, profile: 'claude', toolResult });
+  await host.ui.getByRole('button', { name: 'Confirm' }).click();
+  expect(host.calls('create_lead')).toHaveLength(1);
+});
+```
+
+The host page is on `https://host.mcp-apps.test`, the card on `https://sandbox.mcp-apps.test` in an iframe without
+`allow-same-origin` (opaque to the host), under `STRICT_APP_CSP` unless `csp` says otherwise. Nothing leaves the
+machine: other requests are aborted and recorded (`network(route)` serves one the test expects). The exported `test`
+checks every host when the test ends, and refuses any request from a page that opened none. Install Chromium with
+`npx playwright install chromium`.
+
+## `tk-check-bundle`
+
+A card whose bytes changed must carry a new version, or hosts that cached it by URI serve the old one. List your
+bundles in `tk-bundles.json`:
+
+```json
+{ "bundles": [{
+  "bundle": "src/card/generated/card.html",
+  "version": { "file": "src/card/version.ts", "pattern": "CARD_VERSION = '([^']+)'" }
+}] }
+```
+
+(`"version": { "file": "package.json", "pointer": "/version" }` reads JSON.) `tk-check-bundle --write` records
+`{ version, sha256 }` beside each bundle (`<bundle>.version.json`) and refuses when the bytes changed but the version
+did not; `tk-check-bundle` in CI fails unless every manifest matches its bundle and version. A config listing no
+bundles fails.

package/dist/mcp-apps-host/index.d.ts

@@ -0,0 +1,3 @@
+/** The fake MCP Apps host: the protocol core and its in-memory (jsdom) form. The Playwright form is `./playwright`. */
+export { McpAppsHost, type Action, type DisplayMode, type HostOptions, type HostProfile, type Json, type Recorded, type RpcMessage, type Theme, type ToolAnswer, type ToolCall, } from './protocol.ts';
+export { createMemoryHost, MemoryHost, type MemoryHostOptions, type MemoryTransport } from './memory.ts';

package/dist/mcp-apps-host/index.js

@@ -0,0 +1,3 @@
+/** The fake MCP Apps host: the protocol core and its in-memory (jsdom) form. The Playwright form is `./playwright`. */
+export { McpAppsHost, } from "./protocol.js";
+export { createMemoryHost, MemoryHost } from "./memory.js";

package/dist/mcp-apps-host/memory.d.ts

@@ -0,0 +1,37 @@
+import { McpAppsHost, type HostOptions, type RpcMessage } from './protocol.ts';
+export interface MemoryTransport {
+    start(): Promise<void>;
+    send(message: RpcMessage): Promise<void>;
+    close(): Promise<void>;
+    onmessage?: (message: RpcMessage) => void;
+    onclose?: () => void;
+    onerror?: (error: Error) => void;
+}
+export interface MemoryHostOptions extends HostOptions {
+    /** A request the test expects: answer it (a Response) or return undefined to refuse it as stray. */
+    network?: (url: string) => Response | undefined;
+    /** Fail the test when it ends on any problem. Default: true. */
+    failOnProblems?: boolean;
+}
+export declare class MemoryHost extends McpAppsHost {
+    readonly transport: MemoryTransport;
+    /** Console errors, page errors and stray requests, in order. */
+    readonly problems: string[];
+    readonly strayRequests: string[];
+    private readonly undo;
+    private closed;
+    constructor(options: MemoryHostOptions);
+    private watch;
+    /**
+     * For an app that connects to `window.parent` itself (`new PostMessageTransport(window.parent, window.parent)`):
+     * replaces `window.parent` with a stand-in whose `postMessage` reaches this host, and answers with `message` events
+     * whose `source` is that stand-in. Undone by `close()`.
+     */
+    installParent(): Window;
+    /** Puts back everything the host replaced. */
+    close(): void;
+    /** Throws listing every problem: console and page errors, stray requests, unexpected tool calls. */
+    assertClean(): void;
+}
+/** Opens a host for the current test. */
+export declare function createMemoryHost(options: MemoryHostOptions): MemoryHost;

package/dist/mcp-apps-host/memory.js

@@ -0,0 +1,158 @@
+/**
+ * The in-memory form of the host, for a Vitest file under jsdom. The app connects to `host.transport` as its bundle
+ * connects to `window.parent` (with ext-apps: `await app.connect(host.transport)`); each message is delivered on a
+ * microtask, as `postMessage` delivers it, so an ordering bug shows here as it would in a frame. An app that connects
+ * to `window.parent` itself gets a stand-in parent from `host.installParent()`.
+ *
+ * While the host is open, a console error, a page error (`window` `error` event) or a network request (`fetch`,
+ * `XMLHttpRequest`) is a problem, and so is a tool call the test gave no answer for. Opened inside a test, the host
+ * fails that test on any problem when it ends; `assertClean()` asks the same at any moment.
+ */
+import { onTestFinished } from 'vitest';
+import { McpAppsHost } from "./protocol.js";
+export class MemoryHost extends McpAppsHost {
+    transport;
+    /** Console errors, page errors and stray requests, in order. */
+    problems = [];
+    strayRequests = [];
+    undo = [];
+    closed = false;
+    constructor(options) {
+        super(options);
+        const transport = {
+            start: async () => { },
+            send: async (message) => {
+                queueMicrotask(() => {
+                    this.receive(message).catch((error) => this.problems.push(`host: ${String(error)}`));
+                });
+            },
+            close: async () => {
+                transport.onclose?.();
+            },
+        };
+        this.transport = transport;
+        this.post = (message) => {
+            queueMicrotask(() => transport.onmessage?.(structuredClone(message)));
+        };
+        this.watch(options);
+    }
+    watch(options) {
+        const realError = console.error;
+        const host = this;
+        const recording = function recordingConsoleError(...args) {
+            host.problems.push(`console error: ${args.map(String).join(' ')}`);
+            return realError.apply(this, args);
+        };
+        console.error = recording;
+        this.undo.push(() => {
+            if (console.error === recording)
+                console.error = realError;
+        });
+        if (typeof window !== 'undefined') {
+            const onError = (event) => this.problems.push(`page error: ${event.message || String(event.error)}`);
+            window.addEventListener('error', onError);
+            this.undo.push(() => window.removeEventListener('error', onError));
+        }
+        const stray = (url) => {
+            this.strayRequests.push(url);
+            return new TypeError(`test-kit host: a request the test did not expect: ${url}`);
+        };
+        if (typeof globalThis.fetch === 'function') {
+            const realFetch = globalThis.fetch;
+            const guarded = (async (input) => {
+                const url = typeof input === 'string' ? input : input instanceof URL ? input.href : input.url;
+                if (/^(data|blob):/.test(url))
+                    return realFetch(input);
+                const answered = options.network?.(url);
+                if (answered)
+                    return answered;
+                throw stray(url);
+            });
+            globalThis.fetch = guarded;
+            this.undo.push(() => {
+                if (globalThis.fetch === guarded)
+                    globalThis.fetch = realFetch;
+            });
+        }
+        const Xhr = globalThis.XMLHttpRequest;
+        if (Xhr) {
+            const realOpen = Xhr.prototype.open;
+            const realSend = Xhr.prototype.send;
+            const urls = new WeakMap();
+            Xhr.prototype.open = function open(...args) {
+                urls.set(this, String(args[1]));
+                return realOpen.apply(this, args);
+            };
+            Xhr.prototype.send = function send() {
+                throw stray(urls.get(this) ?? 'an XMLHttpRequest');
+            };
+            this.undo.push(() => {
+                Xhr.prototype.open = realOpen;
+                Xhr.prototype.send = realSend;
+            });
+        }
+        if (options.failOnProblems ?? true) {
+            try {
+                onTestFinished(() => {
+                    this.close();
+                    this.assertClean();
+                });
+            }
+            catch {
+                // Opened outside a test (a beforeAll): the test calls assertClean() itself.
+            }
+        }
+    }
+    /**
+     * For an app that connects to `window.parent` itself (`new PostMessageTransport(window.parent, window.parent)`):
+     * replaces `window.parent` with a stand-in whose `postMessage` reaches this host, and answers with `message` events
+     * whose `source` is that stand-in. Undone by `close()`.
+     */
+    installParent() {
+        if (typeof window === 'undefined')
+            throw new Error('test-kit host: installParent() needs a jsdom window');
+        const original = Object.getOwnPropertyDescriptor(window, 'parent');
+        const parent = {
+            postMessage: (message) => {
+                queueMicrotask(() => {
+                    this.receive(structuredClone(message)).catch((error) => this.problems.push(`host: ${String(error)}`));
+                });
+            },
+        };
+        Object.defineProperty(window, 'parent', { value: parent, configurable: true });
+        this.post = (message) => {
+            queueMicrotask(() => {
+                const event = new MessageEvent('message', { data: structuredClone(message) });
+                Object.defineProperty(event, 'source', { value: parent });
+                window.dispatchEvent(event);
+            });
+        };
+        this.undo.push(() => {
+            if (original)
+                Object.defineProperty(window, 'parent', original);
+        });
+        return parent;
+    }
+    /** Puts back everything the host replaced. */
+    close() {
+        if (this.closed)
+            return;
+        this.closed = true;
+        for (const undo of this.undo.splice(0).reverse())
+            undo();
+    }
+    /** Throws listing every problem: console and page errors, stray requests, unexpected tool calls. */
+    assertClean() {
+        const lines = [
+            ...this.problems,
+            ...this.strayRequests.map((url) => `stray request: ${url}`),
+            ...this.unanswered.map((call) => `unexpected tool call: ${call.name} ${JSON.stringify(call.arguments)}`),
+        ];
+        if (lines.length > 0)
+            throw new Error(`The MCP Apps test host saw problems:\n${lines.join('\n')}`);
+    }
+}
+/** Opens a host for the current test. */
+export function createMemoryHost(options) {
+    return new MemoryHost(options);
+}

package/dist/mcp-apps-host/playwright.d.ts

@@ -0,0 +1,60 @@
+/**
+ * The Playwright form of the host: a real browser page on a host origin holding the app in a sandboxed iframe on another
+ * origin (no `allow-same-origin`, so the frame is opaque to its host, as a chat client's is), served under a CSP header.
+ * No socket opens: `page.route` serves the two documents and aborts and records every other request. The protocol runs
+ * in Node (`McpAppsHost`, the same class the in-memory form drives), so both forms answer alike.
+ *
+ * Use the exported `test`: on every page it fails the test on a console error, a page error, a stray request or a tool
+ * call the test gave no answer for, without the test asking.
+ */
+import { expect, type Frame, type FrameLocator, type Page, type Route } from '@playwright/test';
+import { McpAppsHost, type HostOptions } from './protocol.ts';
+export declare const HOST_ORIGIN = "https://host.mcp-apps.test";
+export declare const SANDBOX_ORIGIN = "https://sandbox.mcp-apps.test";
+/** A CSP for the app document that lets inline code run and nothing load or connect. */
+export declare const STRICT_APP_CSP = "default-src 'none'; script-src 'unsafe-inline'; style-src 'unsafe-inline'; img-src data: blob:; font-src data:; connect-src 'none'; frame-src 'none'; base-uri 'none'; form-action 'none'";
+/** ChatGPT's `window.openai` file functions in the app: absent, both, only `uploadFile`, or one of them failing. */
+export type OpenaiStub = 'none' | 'both' | 'upload-only' | 'upload-rejects' | 'download-rejects';
+export interface BrowserHostOptions extends HostOptions {
+    /** The app's document (a built card bundle). */
+    html: string;
+    /** The app document's CSP header; null sends none. Default: {@link STRICT_APP_CSP}. */
+    csp?: string | null;
+    /** The iframe's `sandbox`. Default `allow-scripts allow-forms`. */
+    sandbox?: string;
+    /** Only on the chatgpt profile. Default `none`. */
+    openai?: OpenaiStub;
+    /** A request the test expects: fulfil it and answer true; false leaves it stray. */
+    network?: (route: Route) => Promise<boolean>;
+}
+export declare class BrowserHost extends McpAppsHost {
+    readonly page: Page;
+    /** Console errors, page errors and failed requests, in order. */
+    readonly problems: string[];
+    /** Requests that were neither the host page nor the app document. */
+    readonly strayRequests: string[];
+    /** What the app asked of `window.openai`: `upload <file name>` or `download <file id>`. */
+    readonly openaiCalls: string[];
+    constructor(page: Page, options: HostOptions);
+    /** The app's iframe, to find things in. */
+    get ui(): FrameLocator;
+    /** The app's frame, to evaluate in. */
+    frame(): Frame;
+    /** A modal in the host page, as a permission prompt opens one: the frame goes inert and loses focus. */
+    openHostDialog(): Promise<void>;
+    closeHostDialog(): Promise<void>;
+    /** The app document's sideways overflow, in pixels. */
+    sidewaysOverflow(): Promise<number>;
+    /** Fails on a console or page error, a stray request or a tool call the test did not expect. */
+    assertClean(): void;
+}
+/** Opens the app in a host page, handshake done unless the host refuses it. */
+export declare function openApp(page: Page, options: BrowserHostOptions): Promise<BrowserHost>;
+/**
+ * Playwright's `test` with the host's watch on every page: requests a page makes before or outside `openApp` are
+ * refused and recorded, and when the test ends every host it opened must be clean.
+ */
+export declare const test: import("@playwright/test").TestType<import("@playwright/test").PlaywrightTestArgs & import("@playwright/test").PlaywrightTestOptions & {
+    mcpAppsHostWatch: void;
+}, import("@playwright/test").PlaywrightWorkerArgs & import("@playwright/test").PlaywrightWorkerOptions>;
+export { expect };