@catalystiq/test-kit 0.0.0-stage → 0.2.0

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

@@ -0,0 +1,190 @@
+/**
+ * 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 { test as base, expect } from '@playwright/test';
+import { McpAppsHost } from "./protocol.js";
+export const HOST_ORIGIN = 'https://host.mcp-apps.test';
+export const SANDBOX_ORIGIN = 'https://sandbox.mcp-apps.test';
+const APP_URL = `${SANDBOX_ORIGIN}/app.html`;
+/** A CSP for the app document that lets inline code run and nothing load or connect. */
+export 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'";
+const HOST_HTML = `<!doctype html>
+<html lang="en"><head><meta charset="utf-8"><title>MCP Apps test host</title>
+<style>html,body{margin:0;padding:0}iframe{display:block;border:0;background:transparent}</style></head>
+<body><iframe id="app" title="app"></iframe><dialog id="host-dialog">Allow this?</dialog>
+<script>
+  const config = /*__CONFIG__*/ null;
+  const frame = document.getElementById('app');
+  frame.setAttribute('sandbox', config.sandbox);
+  document.documentElement.style.colorScheme = config.theme;
+  document.documentElement.style.background = config.theme === 'dark' ? '#212121' : '#ffffff';
+  const size = (s) => { if (s.width !== undefined) frame.style.width = s.width + 'px'; if (s.height !== undefined) frame.style.height = s.height + 'px'; };
+  size(config.frame);
+  window.__tkResize = size;
+  window.__tkToApp = (message) => frame.contentWindow.postMessage(message, '*');
+  addEventListener('message', (event) => {
+    if (event.source !== frame.contentWindow) return;
+    const message = event.data;
+    if (message && typeof message === 'object' && typeof message.tkOpenai === 'string') { window.__tkOpenai(message); return; }
+    if (message && typeof message === 'object' && message.jsonrpc === '2.0') window.__tkHostReceive(message);
+  });
+  frame.src = config.appUrl;
+</script></body></html>`;
+function openaiScript(mode) {
+    if (mode === 'none')
+        return '';
+    const upload = mode === 'upload-rejects'
+        ? `() => Promise.reject(new Error('no upload'))`
+        : `(file) => { parent.postMessage({ tkOpenai: 'upload', name: file && file.name }, '*'); return Promise.resolve({ fileId: 'file-fixture' }); }`;
+    const download = mode === 'upload-only'
+        ? ''
+        : mode === 'download-rejects'
+            ? `getFileDownloadUrl: () => Promise.reject(new Error('no link')),`
+            : `getFileDownloadUrl: ({ fileId }) => { parent.postMessage({ tkOpenai: 'download', name: fileId }, '*'); return Promise.resolve({ downloadUrl: 'https://files.mcp-apps.test/' + fileId }); },`;
+    return `<script>window.openai = { uploadFile: ${upload}, ${download} };</script>`;
+}
+function withHeadScript(html, script) {
+    if (script === '')
+        return html;
+    return /<head[^>]*>/i.test(html) ? html.replace(/<head[^>]*>/i, (head) => `${head}${script}`) : `${script}${html}`;
+}
+export class BrowserHost extends McpAppsHost {
+    page;
+    /** Console errors, page errors and failed requests, in order. */
+    problems = [];
+    /** Requests that were neither the host page nor the app document. */
+    strayRequests = [];
+    /** What the app asked of `window.openai`: `upload <file name>` or `download <file id>`. */
+    openaiCalls = [];
+    constructor(page, options) {
+        super(options);
+        this.page = page;
+    }
+    /** The app's iframe, to find things in. */
+    get ui() {
+        return this.page.frameLocator('#app');
+    }
+    /** The app's frame, to evaluate in. */
+    frame() {
+        const frame = this.page.frames().find((f) => f.url() === APP_URL);
+        if (!frame)
+            throw new Error('test-kit host: the app frame is not there');
+        return frame;
+    }
+    /** A modal in the host page, as a permission prompt opens one: the frame goes inert and loses focus. */
+    async openHostDialog() {
+        await this.page.evaluate(() => document.getElementById('host-dialog').showModal());
+    }
+    async closeHostDialog() {
+        await this.page.evaluate(() => document.getElementById('host-dialog').close());
+    }
+    /** The app document's sideways overflow, in pixels. */
+    sidewaysOverflow() {
+        return this.frame().evaluate(() => {
+            const root = document.documentElement;
+            return Math.max(root.scrollWidth, document.body.scrollWidth) - root.clientWidth;
+        });
+    }
+    /** Fails on a console or page error, a stray request or a tool call the test did not expect. */
+    assertClean() {
+        expect(this.problems, 'console errors, page errors, failed requests').toEqual([]);
+        expect(this.strayRequests, 'requests other than the host page and the app').toEqual([]);
+        expect(this.unanswered, 'tool calls the test did not expect').toEqual([]);
+    }
+}
+const HOSTS = new WeakMap();
+/** Opens the app in a host page, handshake done unless the host refuses it. */
+export async function openApp(page, options) {
+    const { html, csp = STRICT_APP_CSP, sandbox = 'allow-scripts allow-forms', network } = options;
+    const openai = options.openai ?? 'none';
+    if (options.profile !== 'chatgpt' && openai !== 'none') {
+        throw new Error('test-kit host: window.openai belongs to the chatgpt profile');
+    }
+    const host = new BrowserHost(page, options);
+    HOSTS.set(page, [...(HOSTS.get(page) ?? []), host]);
+    const width = options.width ?? 720;
+    const height = options.displayMode === 'fullscreen' ? (options.height ?? 900) : (options.height ?? 400);
+    page.on('console', (m) => {
+        if (m.type() === 'error')
+            host.problems.push(`console error: ${m.text()}`);
+    });
+    page.on('pageerror', (e) => host.problems.push(`page error: ${e.message}`));
+    page.on('requestfailed', (r) => {
+        if (!host.strayRequests.includes(r.url()))
+            host.problems.push(`request failed: ${r.url()}`);
+    });
+    await page.setViewportSize({ width: width + 40, height: Math.max(height, options.height ?? 900) + 40 });
+    await page.emulateMedia({ colorScheme: options.theme ?? 'light' });
+    await page.route('**/*', async (route) => {
+        const url = route.request().url();
+        if (url === `${HOST_ORIGIN}/`) {
+            const config = { theme: options.theme ?? 'light', sandbox, appUrl: APP_URL, frame: { width, height } };
+            await route.fulfill({ contentType: 'text/html', body: HOST_HTML.replace('/*__CONFIG__*/ null', JSON.stringify(config)) });
+        }
+        else if (url === APP_URL) {
+            await route.fulfill({
+                contentType: 'text/html',
+                headers: csp === null ? {} : { 'content-security-policy': csp },
+                body: withHeadScript(html, openaiScript(openai)),
+            });
+        }
+        else if (!(await network?.(route))) {
+            host.strayRequests.push(url);
+            await route.abort('blockedbyclient');
+        }
+    });
+    await page.exposeFunction('__tkHostReceive', (message) => host.receive(message));
+    await page.exposeFunction('__tkOpenai', (message) => {
+        host.openaiCalls.push(`${message.tkOpenai} ${message.name ?? ''}`.trim());
+    });
+    host.post = async (message) => {
+        await page.evaluate((m) => window.__tkToApp(m), message);
+    };
+    host.resize = async (s) => {
+        await page.evaluate((size) => window.__tkResize(size), s);
+    };
+    await page.goto(`${HOST_ORIGIN}/`);
+    // The frame is opaque to its host, as a chat client's is.
+    await page.waitForFunction(() => {
+        const frame = document.getElementById('app');
+        return frame !== null && frame.contentDocument === null;
+    });
+    if (!options.refuseInitialize) {
+        const deadline = Date.now() + 15_000;
+        while (!host.initialized) {
+            if (Date.now() > deadline)
+                throw new Error('test-kit host: the app never sent ui/notifications/initialized');
+            await page.waitForTimeout(20);
+        }
+    }
+    return host;
+}
+/**
+ * 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 const test = base.extend({
+    mcpAppsHostWatch: [
+        async ({ page }, use) => {
+            const problems = [];
+            page.on('pageerror', (error) => problems.push(`page error: ${error.message}`));
+            await page.route('**/*', async (route) => {
+                problems.push(`request outside the host: ${route.request().url()}`);
+                await route.abort('blockedbyclient');
+            });
+            await use();
+            for (const host of HOSTS.get(page) ?? [])
+                host.assertClean();
+            if ((HOSTS.get(page) ?? []).length === 0)
+                expect(problems, 'page errors and requests').toEqual([]);
+        },
+        { auto: true },
+    ],
+});
+export { expect };

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

@@ -0,0 +1,139 @@
+/**
+ * The host's half of the MCP Apps protocol, with no transport: a message from the app in, messages to the app out
+ * through `post`. The in-memory form (`./memory.ts`, for jsdom) and the Playwright form (`./playwright.ts`) both drive
+ * this one class, so the two answer every message the same way.
+ *
+ * Every message is recorded in order, both ways (`log`), so a test asserts on the wire, not on the DOM's opinion of
+ * what happened.
+ */
+export type Json = Record<string, unknown>;
+export interface RpcMessage {
+    jsonrpc?: '2.0';
+    id?: number | string;
+    method?: string;
+    params?: Json;
+    result?: unknown;
+    error?: {
+        code: number;
+        message: string;
+        data?: unknown;
+    };
+}
+export interface Recorded {
+    from: 'app' | 'host';
+    message: RpcMessage;
+}
+/**
+ * The two hosts. `chatgpt` takes `ui/update-model-context` and can give the page `window.openai`'s file functions;
+ * `claude` lists no model-context capability and refuses the method with -32601. Everything else is the same.
+ */
+export type HostProfile = 'chatgpt' | 'claude';
+export type Theme = 'light' | 'dark';
+export type DisplayMode = 'inline' | 'fullscreen' | 'pip';
+/** A tool call's answer: a result, or `undefined` for a call the test did not expect. A throw is the call failing. */
+export type ToolAnswer = (name: string, args: Json) => Json | undefined | Promise<Json | undefined>;
+export interface ToolCall {
+    name: string;
+    arguments: Json;
+}
+/** One thing the app asked the host to do, as a test states it. */
+export type Action = {
+    tool: string;
+    arguments: Json;
+} | {
+    message: string;
+} | {
+    context: string;
+} | {
+    link: string;
+} | {
+    display: string;
+};
+export interface HostOptions {
+    profile: HostProfile;
+    /** The tool the host says opened the app. */
+    tool?: {
+        name: string;
+        inputSchema?: Json;
+    };
+    /** Sent as `ui/notifications/tool-input` right after `initialized`; left out when undefined. */
+    toolInput?: Json;
+    /** Sent as `ui/notifications/tool-result` after the input; null sends none. */
+    toolResult?: Json | null;
+    /** Answers each `tools/call`. Default: none, so every call is unexpected. */
+    answer?: ToolAnswer;
+    /** Hold every tool call's answer (or the named tools') until `release()`. */
+    hold?: boolean | readonly string[];
+    theme?: Theme;
+    displayMode?: DisplayMode;
+    availableDisplayModes?: DisplayMode[];
+    /** `declared` grants a mode the app declared and the host lists; `inline` never moves; `fail` refuses the request. */
+    displayModes?: 'declared' | 'inline' | 'fail';
+    locale?: string;
+    /** An IANA zone; null gives none. */
+    timeZone?: string | null;
+    width?: number;
+    height?: number;
+    /** `ui/open-link`: opened, refused (`isError: true`), or failed (a JSON-RPC error). */
+    openLink?: 'open' | 'refuse' | 'fail';
+    /** `ui/message`: accepted, refused by the person (`isError: true`), or unsupported (no capability, -32601). */
+    message?: 'accept' | 'refuse' | 'unsupported';
+    /** `ui/update-model-context` on the chatgpt profile: answered, never answered, or refused with -32601. */
+    modelContext?: 'accept' | 'ignore' | 'reject';
+    /** Answer `ui/initialize` with an error. */
+    refuseInitialize?: boolean;
+    /** Merged over the profile's capabilities and context. */
+    hostCapabilities?: Json;
+    hostContext?: Json;
+}
+export declare class McpAppsHost {
+    readonly options: HostOptions;
+    readonly log: Recorded[];
+    /** Tool calls the test had no answer for. */
+    readonly unanswered: ToolCall[];
+    /** The app's `ui/initialize` params, once it sent them. */
+    initialize: Json | null;
+    initialized: boolean;
+    hostContext: Json;
+    readonly hostCapabilities: Json;
+    /** Set by the transport: how a message reaches the app, and how the frame is resized. */
+    post: (message: RpcMessage) => void | Promise<void>;
+    resize: (size: {
+        width?: number;
+        height?: number;
+    }) => void | Promise<void>;
+    private readonly held;
+    private readonly pending;
+    private nextId;
+    constructor(options: HostOptions);
+    /** Every message the app sent with `method`, in order. */
+    sent(method: string): RpcMessage[];
+    /** The app's tool calls, optionally of one tool. */
+    calls(name?: string): ToolCall[];
+    /** The methods the app sent, in order. */
+    methods(): string[];
+    /** Everything the app asked of the host, in order: tool calls, messages, context, links, display modes. */
+    actions(): Action[];
+    messages(): string[];
+    modelContext(): string[];
+    links(): string[];
+    /** Answers every held tool call, in the order the app made them. */
+    release(): Promise<void>;
+    /** A later tool result, as the next model call in a conversation would send. */
+    sendToolResult(result: Json): Promise<void>;
+    sendToolInput(args: Json): Promise<void>;
+    cancelTool(reason?: string): Promise<void>;
+    /** `ui/notifications/host-context-changed`, merged into what the host holds. */
+    changeContext(patch: Json): Promise<void>;
+    setTheme(theme: Theme): Promise<void>;
+    /** `ui/resource-teardown`, answering the app's reply. */
+    teardown(): Promise<RpcMessage>;
+    /** A request from the host; resolves with the app's reply. */
+    request(method: string, params: Json): Promise<RpcMessage>;
+    private deliver;
+    private answer;
+    private refuse;
+    private holds;
+    /** One message from the app. */
+    receive(message: RpcMessage): Promise<void>;
+}

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

@@ -0,0 +1,272 @@
+/**
+ * The host's half of the MCP Apps protocol, with no transport: a message from the app in, messages to the app out
+ * through `post`. The in-memory form (`./memory.ts`, for jsdom) and the Playwright form (`./playwright.ts`) both drive
+ * this one class, so the two answer every message the same way.
+ *
+ * Every message is recorded in order, both ways (`log`), so a test asserts on the wire, not on the DOM's opinion of
+ * what happened.
+ */
+const HOST_INFO = {
+    chatgpt: { name: 'test-kit-chatgpt-host', version: '1.0.0' },
+    claude: { name: 'test-kit-claude-host', version: '1.0.0' },
+};
+function textOf(params) {
+    const content = (params?.content ?? []);
+    return content.map((part) => (typeof part.text === 'string' ? part.text : '')).join('\n');
+}
+function actionOf(message) {
+    const p = message.params;
+    switch (message.method) {
+        case 'tools/call':
+            return { tool: String(p?.name), arguments: (p?.arguments ?? {}) };
+        case 'ui/message':
+            return { message: textOf(p) };
+        case 'ui/update-model-context':
+            return { context: textOf(p) };
+        case 'ui/open-link':
+            return { link: String(p?.url) };
+        case 'ui/request-display-mode':
+            return { display: String(p?.mode) };
+        default:
+            return null;
+    }
+}
+export class McpAppsHost {
+    options;
+    log = [];
+    /** Tool calls the test had no answer for. */
+    unanswered = [];
+    /** The app's `ui/initialize` params, once it sent them. */
+    initialize = null;
+    initialized = false;
+    hostContext;
+    hostCapabilities;
+    /** Set by the transport: how a message reaches the app, and how the frame is resized. */
+    post = () => {
+        throw new Error('test-kit: the host has no transport yet');
+    };
+    resize = () => { };
+    held = [];
+    pending = new Map();
+    nextId = 1_000_000;
+    constructor(options) {
+        if (options.profile !== 'chatgpt' && options.profile !== 'claude') {
+            throw new Error(`test-kit: unknown host profile ${String(options.profile)}; use 'chatgpt' or 'claude'`);
+        }
+        if (options.profile === 'claude' && options.modelContext !== undefined) {
+            throw new Error('test-kit: the claude profile takes no model context, so `modelContext` does not apply');
+        }
+        this.options = options;
+        const mode = options.displayMode ?? 'inline';
+        const width = options.width ?? 720;
+        this.hostContext = {
+            theme: options.theme ?? 'light',
+            displayMode: mode,
+            availableDisplayModes: options.availableDisplayModes ?? ['inline', 'fullscreen'],
+            locale: options.locale ?? 'en-US',
+            ...(options.timeZone === null ? {} : { timeZone: options.timeZone ?? 'America/New_York' }),
+            ...(options.tool ? { toolInfo: { tool: { inputSchema: { type: 'object' }, ...options.tool } } } : {}),
+            containerDimensions: mode === 'fullscreen' ? { width, height: options.height ?? 900 } : { width, maxHeight: 6000 },
+            ...options.hostContext,
+        };
+        const message = options.message ?? 'accept';
+        this.hostCapabilities = {
+            openLinks: {},
+            serverTools: {},
+            logging: {},
+            ...(message === 'unsupported' ? {} : { message: { text: {} } }),
+            ...(options.profile === 'chatgpt' && options.modelContext !== 'reject' ? { updateModelContext: { text: {} } } : {}),
+            ...options.hostCapabilities,
+        };
+    }
+    // ─── What a test reads ─────────────────────────────────────────────────────
+    /** Every message the app sent with `method`, in order. */
+    sent(method) {
+        return this.log.filter((r) => r.from === 'app' && r.message.method === method).map((r) => r.message);
+    }
+    /** The app's tool calls, optionally of one tool. */
+    calls(name) {
+        return this.sent('tools/call')
+            .map((m) => ({ name: String(m.params?.name), arguments: (m.params?.arguments ?? {}) }))
+            .filter((c) => name === undefined || c.name === name);
+    }
+    /** The methods the app sent, in order. */
+    methods() {
+        return this.log.flatMap((r) => (r.from === 'app' && r.message.method ? [r.message.method] : []));
+    }
+    /** Everything the app asked of the host, in order: tool calls, messages, context, links, display modes. */
+    actions() {
+        return this.log.flatMap((r) => {
+            if (r.from !== 'app')
+                return [];
+            const action = actionOf(r.message);
+            return action ? [action] : [];
+        });
+    }
+    messages() {
+        return this.sent('ui/message').map((m) => textOf(m.params));
+    }
+    modelContext() {
+        return this.sent('ui/update-model-context').map((m) => textOf(m.params));
+    }
+    links() {
+        return this.sent('ui/open-link').map((m) => String(m.params?.url));
+    }
+    // ─── What a test does as the host ──────────────────────────────────────────
+    /** Answers every held tool call, in the order the app made them. */
+    async release() {
+        for (const send of this.held.splice(0))
+            await send();
+    }
+    /** A later tool result, as the next model call in a conversation would send. */
+    sendToolResult(result) {
+        return this.deliver({ jsonrpc: '2.0', method: 'ui/notifications/tool-result', params: result });
+    }
+    sendToolInput(args) {
+        return this.deliver({ jsonrpc: '2.0', method: 'ui/notifications/tool-input', params: { arguments: args } });
+    }
+    cancelTool(reason = 'cancelled by the person') {
+        return this.deliver({ jsonrpc: '2.0', method: 'ui/notifications/tool-cancelled', params: { reason } });
+    }
+    /** `ui/notifications/host-context-changed`, merged into what the host holds. */
+    changeContext(patch) {
+        this.hostContext = { ...this.hostContext, ...patch };
+        return this.deliver({ jsonrpc: '2.0', method: 'ui/notifications/host-context-changed', params: patch });
+    }
+    setTheme(theme) {
+        return this.changeContext({ theme });
+    }
+    /** `ui/resource-teardown`, answering the app's reply. */
+    teardown() {
+        return this.request('ui/resource-teardown', {});
+    }
+    /** A request from the host; resolves with the app's reply. */
+    request(method, params) {
+        const id = this.nextId++;
+        return new Promise((resolve, reject) => {
+            this.pending.set(id, resolve);
+            this.deliver({ jsonrpc: '2.0', id, method, params }).catch(reject);
+        });
+    }
+    // ─── The protocol ──────────────────────────────────────────────────────────
+    async deliver(message) {
+        const full = { jsonrpc: '2.0', ...message };
+        this.log.push({ from: 'host', message: full });
+        await this.post(full);
+    }
+    answer(id, result) {
+        return this.deliver({ jsonrpc: '2.0', id, result });
+    }
+    refuse(id, message, code = -32000, data) {
+        return this.deliver({ jsonrpc: '2.0', id, error: { code, message, ...(data === undefined ? {} : { data }) } });
+    }
+    holds(name) {
+        const hold = this.options.hold;
+        return hold === true || (Array.isArray(hold) && hold.includes(name));
+    }
+    /** One message from the app. */
+    async receive(message) {
+        if (message === null || typeof message !== 'object' || message.jsonrpc !== '2.0')
+            return;
+        this.log.push({ from: 'app', message });
+        const { id, method } = message;
+        const params = message.params ?? {};
+        if (method === undefined) {
+            if (id !== undefined) {
+                this.pending.get(id)?.(message);
+                this.pending.delete(id);
+            }
+            return;
+        }
+        if (id === undefined) {
+            if (method === 'ui/notifications/initialized') {
+                this.initialized = true;
+                if (this.options.toolInput !== undefined)
+                    await this.sendToolInput(this.options.toolInput);
+                if (this.options.toolResult)
+                    await this.sendToolResult(this.options.toolResult);
+            }
+            else if (method === 'ui/notifications/size-changed' && this.hostContext.displayMode === 'inline') {
+                const { width, height } = params;
+                await this.resize({ ...(width === undefined ? {} : { width }), ...(height === undefined ? {} : { height }) });
+            }
+            return;
+        }
+        switch (method) {
+            case 'ui/initialize':
+                this.initialize = params;
+                if (this.options.refuseInitialize)
+                    return this.refuse(id, 'this host takes no app', -32603);
+                return this.answer(id, {
+                    protocolVersion: params.protocolVersion,
+                    hostInfo: HOST_INFO[this.options.profile],
+                    hostCapabilities: this.hostCapabilities,
+                    hostContext: this.hostContext,
+                });
+            case 'tools/call': {
+                const call = { name: String(params.name), arguments: (params.arguments ?? {}) };
+                const send = async () => {
+                    let result;
+                    try {
+                        result = await (this.options.answer ?? (() => undefined))(call.name, call.arguments);
+                    }
+                    catch (error) {
+                        const { code, data } = error;
+                        return this.refuse(id, String(error?.message ?? error), typeof code === 'number' ? code : -32000, data);
+                    }
+                    if (result === undefined) {
+                        this.unanswered.push(call);
+                        return this.refuse(id, `the test host has no answer for ${call.name}`, -32603);
+                    }
+                    return this.answer(id, result);
+                };
+                if (this.holds(call.name)) {
+                    this.held.push(send);
+                    return;
+                }
+                return send();
+            }
+            case 'ui/message': {
+                const mode = this.options.message ?? 'accept';
+                if (mode === 'unsupported')
+                    return this.refuse(id, 'Method not found', -32601);
+                return this.answer(id, mode === 'refuse' ? { isError: true } : {});
+            }
+            case 'ui/update-model-context': {
+                if (this.options.profile === 'claude' || this.options.modelContext === 'reject') {
+                    return this.refuse(id, 'Method not found', -32601);
+                }
+                if (this.options.modelContext === 'ignore')
+                    return;
+                return this.answer(id, {});
+            }
+            case 'ui/open-link': {
+                const mode = this.options.openLink ?? 'open';
+                if (mode === 'fail')
+                    return this.refuse(id, 'blocked');
+                return this.answer(id, mode === 'refuse' ? { isError: true } : {});
+            }
+            case 'ui/request-display-mode': {
+                const rule = this.options.displayModes ?? 'declared';
+                if (rule === 'fail')
+                    return this.refuse(id, 'no display mode change here');
+                const asked = String(params.mode);
+                const declared = this.initialize?.appCapabilities?.availableDisplayModes ?? [];
+                const listed = this.hostContext.availableDisplayModes ?? [];
+                const grant = rule === 'declared' && declared.includes(asked) && listed.includes(asked);
+                const mode = grant ? asked : String(this.hostContext.displayMode);
+                await this.answer(id, { mode });
+                if (grant && mode !== this.hostContext.displayMode) {
+                    if (mode === 'fullscreen')
+                        await this.resize({ height: this.options.height ?? 900 });
+                    await this.changeContext({ displayMode: mode });
+                }
+                return;
+            }
+            case 'ping':
+                return this.answer(id, {});
+            default:
+                return this.refuse(id, `Method not found: ${method}`, -32601);
+        }
+    }
+}

package/dist/neon-test-db/README.md

@@ -0,0 +1,53 @@
+# `tk-neon-test-db`
+
+The local database test run, `npm run test:db`: a short-lived Neon branch for one command, deleted afterwards.
+
+It moved here from `getcatalystiq/github-actions` (`scripts/neon-test-db.mjs`), which every app vendored unchanged. The
+script is the same; apps now run it from the package.
+
+## Use it
+
+```json
+{
+  "devDependencies": { "@catalystiq/test-kit": "<exact version>" },
+  "scripts": { "test:db": "NEON_TEST_DB_PROJECT=… NEON_TEST_DB_PARENT=… NEON_TEST_DB_REFUSE=… tk-neon-test-db -- npm run ci:db" }
+}
+```
+
+## What it does
+
+- It **cuts** a short-lived, **schema-only** branch of `NEON_TEST_DB_PARENT` (the parent's schema, none of its rows, so
+  never production data), runs the command after `--` with `DATABASE_URL` set to that branch, and **deletes** the branch
+  it made whatever the command did, a Ctrl-C included. It deletes nothing else: the delete names the id this run created.
+- Under the kit's Vitest setup, `DATABASE_URL` holds a password, so the credential strip deletes it in each worker unless
+  the config lists it in `keepEnv` (`defineTestKitConfig({ keepEnv: ['DATABASE_URL'] })`), which also lets the tests
+  reach its host. Neon's serverless HTTP driver queries the region's gateway (`api.<region>.neon.tech`) instead, so a
+  suite that uses it lists that host in `allowHosts` too (the setup README, Network).
+- The branch carries an **expiry** (default 2 hours, at most 6), so a branch whose process died is collected by Neon.
+- It **refuses** a project listed in `NEON_TEST_DB_REFUSE` (name production's) before any call.
+- The connection string is never printed. The branch is named `tmp/test-db-<user>-<UTC yyyymmddhhmmss>-<4 hex>`.
+- `NEON_TEST_DB_INIT=parent-data` asks for a **data** copy instead, only of a parent whose branch id (never a name) is
+  listed in `NEON_TEST_DB_DATA_PARENTS`: the parents the repository names as customer-free. The branch must come back as
+  a data copy of that parent, or it is deleted unused.
+
+## Configuration
+
+From the environment (a repository's `.env.local` is not read; export them or use `dotenv --`):
+
+| Variable | Meaning |
+|---|---|
+| `NEON_API_KEY` | A key that reaches the project (a personal key, or `neonctl`'s token for a short run). |
+| `NEON_TEST_DB_PROJECT` | The Neon project id. |
+| `NEON_TEST_DB_PARENT` | The parent branch id (`br-…`) or name whose schema is copied. Never production's. |
+| `NEON_TEST_DB_REFUSE` | Project ids this command refuses outright (name production). |
+| `NEON_TEST_DB_DATABASE` | The database to connect to (default: the branch's one database that is not `postgres`). |
+| `NEON_TEST_DB_EXPIRES` | Minutes until Neon deletes the branch on its own (default 120, at most 360). |
+| `NEON_TEST_DB_KEEP=1` | Keep the branch afterwards (it still expires); prints its id, never its password. |
+| `NEON_TEST_DB_INIT` | `schema-only` (the default) or `parent-data` (above). |
+| `NEON_TEST_DB_DATA_PARENTS` | The branch ids `parent-data` may copy. |
+
+Exit codes: the command's own; 1 when the branch could not be made, checked or deleted; 2 for a configuration problem;
+128 + the signal number after a signal (130 for a Ctrl-C).
+
+The module also exports `readConfig`, `branchName` and `main` (`@catalystiq/test-kit/neon-test-db`), for a repository
+that wants to test its own `test:db` wiring.