@cyanheads/mcp-ts-core 0.13.10 → 0.13.12

package/dist/testing/apps/cdp-pipe.js

@@ -0,0 +1,200 @@
+/**
+ * @fileoverview Chrome DevTools Protocol client over `--remote-debugging-pipe`. The
+ * browser reads commands from its fd 3 and writes responses and events to its fd 4, each
+ * message one JSON text ended by a NUL byte. No DevTools port is opened, and Chromium
+ * exits when fd 3 closes, so a harness that dies takes its browser with it.
+ *
+ * Sessions are flat: a command for a target carries the `sessionId` from
+ * `Target.attachToTarget({ flatten: true })` or `Target.setAutoAttach({ flatten: true })`,
+ * and events arrive on one stream tagged with theirs. Events are dispatched synchronously
+ * in arrival order, so subscribe before sending the command whose events you need.
+ * @module src/testing/apps/cdp-pipe
+ */
+import { spawn } from 'node:child_process';
+/** A command that failed; an aborted command rejects with its signal's reason instead. */
+export class CdpError extends Error {
+    name = 'CdpError';
+    kind;
+    method;
+    code;
+    constructor(kind, method, message, code) {
+        super(`${method}: ${message}`);
+        this.kind = kind;
+        this.method = method;
+        this.code = code;
+    }
+}
+/** A CDP connection over a pair of streams: `input` from the browser, `output` to it. */
+export class CdpPipe {
+    #output;
+    #pending = new Map();
+    #listeners = new Map();
+    #closed = Promise.withResolvers();
+    #nextId = 1;
+    #isClosed = false;
+    #closeReason = '';
+    #partial = [];
+    constructor(input, output) {
+        this.#output = output;
+        input.on('data', (chunk) => this.#receive(chunk));
+        input.on('end', () => this.close('the browser closed the DevTools pipe'));
+        input.on('error', (err) => this.close(`the DevTools pipe failed: ${err.message}`));
+        output.on('error', (err) => this.close(`the DevTools pipe failed: ${err.message}`));
+    }
+    /** Resolves once the pipe has closed, from either end. */
+    get closed() {
+        return this.#closed.promise;
+    }
+    get isClosed() {
+        return this.#isClosed;
+    }
+    /** Send one command and resolve with its result. */
+    send(method, params = {}, options = {}) {
+        const { sessionId, signal } = options;
+        if (signal?.aborted)
+            return Promise.reject(signal.reason);
+        if (this.#isClosed)
+            return Promise.reject(new CdpError('closed', method, this.#closeReason));
+        const id = this.#nextId++;
+        const { promise, resolve, reject } = Promise.withResolvers();
+        const onAbort = () => {
+            this.#pending.delete(id);
+            reject(signal?.reason);
+        };
+        signal?.addEventListener('abort', onAbort, { once: true });
+        this.#pending.set(id, {
+            method,
+            sessionId,
+            resolve: resolve,
+            reject,
+            release: () => signal?.removeEventListener('abort', onAbort),
+        });
+        const message = { id, method, params, ...(sessionId !== undefined && { sessionId }) };
+        this.#output.write(`${JSON.stringify(message)}\0`);
+        return promise;
+    }
+    /** Call `listener` for every `method` event until the returned function is called. */
+    on(method, listener) {
+        let listeners = this.#listeners.get(method);
+        if (!listeners) {
+            listeners = new Set();
+            this.#listeners.set(method, listeners);
+        }
+        const entry = listener;
+        listeners.add(entry);
+        return () => listeners.delete(entry);
+    }
+    /**
+     * End the pipe to the browser (Chromium exits on reading EOF) and reject every pending
+     * command as `closed`. Idempotent.
+     */
+    close(reason = 'the DevTools pipe was closed') {
+        if (this.#isClosed)
+            return;
+        this.#isClosed = true;
+        this.#closeReason = reason;
+        this.#partial = [];
+        if (!this.#output.writableEnded && !this.#output.destroyed)
+            this.#output.end();
+        for (const pending of this.#pending.values()) {
+            pending.release();
+            pending.reject(new CdpError('closed', pending.method, reason));
+        }
+        this.#pending.clear();
+        this.#closed.resolve();
+    }
+    #receive(chunk) {
+        let start = 0;
+        for (let end = chunk.indexOf(0); end !== -1; end = chunk.indexOf(0, start)) {
+            if (this.#isClosed)
+                return;
+            this.#partial.push(chunk.subarray(start, end));
+            const text = Buffer.concat(this.#partial).toString('utf8');
+            this.#partial = [];
+            this.#dispatch(text);
+            start = end + 1;
+        }
+        if (start < chunk.length && !this.#isClosed) {
+            this.#partial.push(Buffer.from(chunk.subarray(start)));
+        }
+    }
+    #dispatch(text) {
+        let message;
+        try {
+            message = JSON.parse(text);
+        }
+        catch {
+            this.close(`the browser sent a message that is not JSON: ${text.slice(0, 80)}`);
+            return;
+        }
+        if (message.id !== undefined) {
+            this.#settle(message.id, message);
+            return;
+        }
+        if (message.method === undefined)
+            return;
+        const params = message.params ?? {};
+        if (message.method === 'Target.detachedFromTarget')
+            this.#detach(params.sessionId);
+        for (const listener of this.#listeners.get(message.method) ?? []) {
+            listener(params, message.sessionId);
+        }
+    }
+    #settle(id, message) {
+        const pending = this.#pending.get(id);
+        if (!pending)
+            return;
+        this.#pending.delete(id);
+        pending.release();
+        const { error } = message;
+        if (error) {
+            const detail = error.data ? `${error.message} (${error.data})` : error.message;
+            pending.reject(new CdpError('protocol', pending.method, detail, error.code));
+        }
+        else {
+            pending.resolve(message.result ?? {});
+        }
+    }
+    #detach(sessionId) {
+        for (const [id, pending] of this.#pending) {
+            if (pending.sessionId !== sessionId)
+                continue;
+            this.#pending.delete(id);
+            pending.release();
+            pending.reject(new CdpError('detached', pending.method, `session ${String(sessionId)} detached`));
+        }
+    }
+}
+const STDERR_TAIL_CHARS = 8 * 1024;
+/**
+ * Spawn `executable` with a CDP pipe on its fds 3 (commands in) and 4 (messages out).
+ * Rejects with the spawn error (`ENOENT`, `EACCES`, ...) when the process cannot start.
+ * Stdin and stdout are discarded.
+ */
+export async function spawnPiped(executable, args) {
+    const child = spawn(executable, args, {
+        stdio: ['ignore', 'ignore', 'pipe', 'pipe', 'pipe'],
+    });
+    const exited = new Promise((resolve) => child.once('exit', (code, signal) => resolve({ code, signal })));
+    await new Promise((resolve, reject) => {
+        child.once('spawn', resolve);
+        child.once('error', reject);
+    });
+    const cdp = new CdpPipe(child.stdio[4], child.stdio[3]);
+    void exited.then(({ code, signal }) => cdp.close(`the browser exited ${signal ? `on ${signal}` : `with code ${code}`}`));
+    let tail = '';
+    child.stderr?.setEncoding('utf8').on('data', (text) => {
+        tail = (tail + text).slice(-STDERR_TAIL_CHARS);
+    });
+    return {
+        pid: child.pid,
+        cdp,
+        exited,
+        stderrTail: () => tail,
+        kill: () => {
+            if (child.exitCode === null && child.signalCode === null)
+                child.kill('SIGKILL');
+        },
+    };
+}
+//# sourceMappingURL=cdp-pipe.js.map

package/dist/testing/apps/cdp-pipe.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cdp-pipe.js","sourceRoot":"","sources":["../../../src/testing/apps/cdp-pipe.ts"],"names":[],"mappings":"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"}

package/dist/testing/apps/csp.d.ts

@@ -0,0 +1,17 @@
+/**
+ * @fileoverview Builds the `Content-Security-Policy` header the sandbox applies to an MCP
+ * Apps view, from the resource's `_meta.ui.csp`, as the MCP Apps specification prescribes
+ * ("Content Security Policy Enforcement"; "Restrictive Default" when no metadata is given).
+ * `eval` stays blocked: no `'unsafe-eval'` is ever added.
+ * @module src/testing/apps/csp
+ */
+/** The domain lists of a resource's `_meta.ui.csp`. */
+export interface AppCspMetadata {
+    baseUriDomains?: string[];
+    connectDomains?: string[];
+    frameDomains?: string[];
+    resourceDomains?: string[];
+}
+/** The CSP header value for a view whose resource declared `csp` (or nothing). */
+export declare function buildCsp(csp: AppCspMetadata | undefined): string;
+//# sourceMappingURL=csp.d.ts.map

package/dist/testing/apps/csp.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"csp.d.ts","sourceRoot":"","sources":["../../../src/testing/apps/csp.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAIH,uDAAuD;AACvD,MAAM,WAAW,cAAc;IAC7B,cAAc,CAAC,EAAE,MAAM,EAAE,CAAC;IAC1B,cAAc,CAAC,EAAE,MAAM,EAAE,CAAC;IAC1B,YAAY,CAAC,EAAE,MAAM,EAAE,CAAC;IACxB,eAAe,CAAC,EAAE,MAAM,EAAE,CAAC;CAC5B;AAiBD,kFAAkF;AAClF,wBAAgB,QAAQ,CAAC,GAAG,EAAE,cAAc,GAAG,SAAS,GAAG,MAAM,CA4BhE"}

package/dist/testing/apps/csp.js

@@ -0,0 +1,50 @@
+/**
+ * @fileoverview Builds the `Content-Security-Policy` header the sandbox applies to an MCP
+ * Apps view, from the resource's `_meta.ui.csp`, as the MCP Apps specification prescribes
+ * ("Content Security Policy Enforcement"; "Restrictive Default" when no metadata is given).
+ * `eval` stays blocked: no `'unsafe-eval'` is ever added.
+ * @module src/testing/apps/csp
+ */
+import { validationError } from '../../types-global/errors.js';
+const RESTRICTIVE_DEFAULT = [
+    "default-src 'none'",
+    "script-src 'self' 'unsafe-inline'",
+    "style-src 'self' 'unsafe-inline'",
+    "img-src 'self' data:",
+    "media-src 'self' data:",
+    "connect-src 'none'",
+    "frame-src 'none'",
+    "object-src 'none'",
+    "base-uri 'self'",
+].join('; ');
+/** Characters that would let a domain entry end its directive or add a source keyword. */
+const UNSAFE_ENTRY = /[;\r\n'"\s,]/;
+/** The CSP header value for a view whose resource declared `csp` (or nothing). */
+export function buildCsp(csp) {
+    if (!csp)
+        return RESTRICTIVE_DEFAULT;
+    const list = (field) => {
+        const entries = csp[field] ?? [];
+        for (const entry of entries) {
+            if (typeof entry !== 'string' || entry === '' || UNSAFE_ENTRY.test(entry)) {
+                throw validationError(`The resource's _meta.ui.csp.${field} holds ${JSON.stringify(entry)}, which is not a plain origin. Remove separators, quotes, and whitespace from CSP domain entries.`, { reason: 'invalid_csp_entry', field });
+            }
+        }
+        return entries.join(' ');
+    };
+    const resources = list('resourceDomains');
+    const withSources = (head, sources) => (sources ? `${head} ${sources}` : head);
+    return [
+        "default-src 'none'",
+        withSources("script-src 'self' 'unsafe-inline'", resources),
+        withSources("style-src 'self' 'unsafe-inline'", resources),
+        withSources("connect-src 'self'", list('connectDomains')),
+        withSources("img-src 'self' data:", resources),
+        withSources("font-src 'self'", resources),
+        withSources("media-src 'self' data:", resources),
+        `frame-src ${list('frameDomains') || "'none'"}`,
+        "object-src 'none'",
+        `base-uri ${list('baseUriDomains') || "'self'"}`,
+    ].join('; ');
+}
+//# sourceMappingURL=csp.js.map

package/dist/testing/apps/csp.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"csp.js","sourceRoot":"","sources":["../../../src/testing/apps/csp.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,EAAE,eAAe,EAAE,MAAM,0BAA0B,CAAC;AAU3D,MAAM,mBAAmB,GAAG;IAC1B,oBAAoB;IACpB,mCAAmC;IACnC,kCAAkC;IAClC,sBAAsB;IACtB,wBAAwB;IACxB,oBAAoB;IACpB,kBAAkB;IAClB,mBAAmB;IACnB,iBAAiB;CAClB,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;AAEb,0FAA0F;AAC1F,MAAM,YAAY,GAAG,cAAc,CAAC;AAEpC,kFAAkF;AAClF,MAAM,UAAU,QAAQ,CAAC,GAA+B;IACtD,IAAI,CAAC,GAAG;QAAE,OAAO,mBAAmB,CAAC;IACrC,MAAM,IAAI,GAAG,CAAC,KAA2B,EAAU,EAAE;QACnD,MAAM,OAAO,GAAG,GAAG,CAAC,KAAK,CAAC,IAAI,EAAE,CAAC;QACjC,KAAK,MAAM,KAAK,IAAI,OAAO,EAAE,CAAC;YAC5B,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,KAAK,EAAE,IAAI,YAAY,CAAC,IAAI,CAAC,KAAK,CAAC,EAAE,CAAC;gBAC1E,MAAM,eAAe,CACnB,+BAA+B,KAAK,UAAU,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,mGAAmG,EACtK,EAAE,MAAM,EAAE,mBAAmB,EAAE,KAAK,EAAE,CACvC,CAAC;YACJ,CAAC;QACH,CAAC;QACD,OAAO,OAAO,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;IAC3B,CAAC,CAAC;IACF,MAAM,SAAS,GAAG,IAAI,CAAC,iBAAiB,CAAC,CAAC;IAC1C,MAAM,WAAW,GAAG,CAAC,IAAY,EAAE,OAAe,EAAE,EAAE,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,GAAG,IAAI,IAAI,OAAO,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC;IAC/F,OAAO;QACL,oBAAoB;QACpB,WAAW,CAAC,mCAAmC,EAAE,SAAS,CAAC;QAC3D,WAAW,CAAC,kCAAkC,EAAE,SAAS,CAAC;QAC1D,WAAW,CAAC,oBAAoB,EAAE,IAAI,CAAC,gBAAgB,CAAC,CAAC;QACzD,WAAW,CAAC,sBAAsB,EAAE,SAAS,CAAC;QAC9C,WAAW,CAAC,iBAAiB,EAAE,SAAS,CAAC;QACzC,WAAW,CAAC,wBAAwB,EAAE,SAAS,CAAC;QAChD,aAAa,IAAI,CAAC,cAAc,CAAC,IAAI,QAAQ,EAAE;QAC/C,mBAAmB;QACnB,YAAY,IAAI,CAAC,gBAAgB,CAAC,IAAI,QAAQ,EAAE;KACjD,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;AACf,CAAC"}

package/dist/testing/apps/host-pages.d.ts

@@ -0,0 +1,47 @@
+/**
+ * @fileoverview The two loopback origins of the headless MCP Apps host. The host origin
+ * serves a page holding the sandbox iframe; the sandbox origin serves the sandbox proxy
+ * page with the view's CSP as an HTTP header. The proxy announces
+ * `ui/notifications/sandbox-proxy-ready`; on `ui/notifications/sandbox-resource-ready` it
+ * creates the inner view iframe and writes the view HTML into it (an about:blank child
+ * inherits the proxy's origin and CSP); it relays every other message both ways except a
+ * `ui/notifications/sandbox-*` one, a name the spec reserves for host and proxy.
+ *
+ * Both iframes carry the view's permissions-policy `allow` value, set before each frame
+ * loads: a frame can only delegate a feature its own frame was granted, and writing the
+ * view into the inner frame is not a navigation, so its policy is fixed when it is created.
+ *
+ * The host-side relay is not part of the host page: it runs in an isolated world
+ * ({@link HOST_WORLD}) installed over CDP, and reports through a binding only that world
+ * can see, so the view cannot reach the channel to Node.
+ * @module src/testing/apps/host-pages
+ */
+/** The isolated world the host relay runs in. */
+export declare const HOST_WORLD = "__mcpAppsHost";
+/** Binding the relay calls with each message from the sandbox, as JSON. */
+export declare const RECEIVE_BINDING = "__mcpAppsHostReceive";
+/** Function the relay defines in its world; Node calls it with each message for the view. */
+export declare const SEND_FUNCTION = "__mcpAppsHostSend";
+/** Function the relay defines to set the sandbox iframe's height in CSS pixels. */
+export declare const RESIZE_FUNCTION = "__mcpAppsHostResize";
+/** The id of the sandbox iframe in the host page. */
+export declare const SANDBOX_FRAME_ID = "mcp-apps-sandbox";
+/** Both origins, listening on 127.0.0.1. */
+export interface HostPages {
+    close(): Promise<void>;
+    readonly hostUrl: string;
+    /** The relay script, installed in {@link HOST_WORLD} before the host page loads. */
+    readonly relayScript: string;
+    readonly sandboxOrigin: string;
+}
+/** Layout and background of the host page, and the view's permissions. */
+export interface HostPageOptions {
+    /** The iframe `allow` value for the resource's `_meta.ui.permissions`; empty for none. */
+    allow: string;
+    background: string;
+    height: number;
+    width: number;
+}
+/** Start both origins. `csp` is sent with the sandbox page. */
+export declare function startHostPages(csp: string, options: HostPageOptions): Promise<HostPages>;
+//# sourceMappingURL=host-pages.d.ts.map

package/dist/testing/apps/host-pages.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"host-pages.d.ts","sourceRoot":"","sources":["../../../src/testing/apps/host-pages.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAKH,iDAAiD;AACjD,eAAO,MAAM,UAAU,kBAAkB,CAAC;AAC1C,2EAA2E;AAC3E,eAAO,MAAM,eAAe,yBAAyB,CAAC;AACtD,6FAA6F;AAC7F,eAAO,MAAM,aAAa,sBAAsB,CAAC;AACjD,mFAAmF;AACnF,eAAO,MAAM,eAAe,wBAAwB,CAAC;AACrD,qDAAqD;AACrD,eAAO,MAAM,gBAAgB,qBAAqB,CAAC;AAEnD,4CAA4C;AAC5C,MAAM,WAAW,SAAS;IACxB,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IACvB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,oFAAoF;IACpF,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;CAChC;AAED,0EAA0E;AAC1E,MAAM,WAAW,eAAe;IAC9B,0FAA0F;IAC1F,KAAK,EAAE,MAAM,CAAC;IACd,UAAU,EAAE,MAAM,CAAC;IACnB,MAAM,EAAE,MAAM,CAAC;IACf,KAAK,EAAE,MAAM,CAAC;CACf;AAED,+DAA+D;AAC/D,wBAAsB,cAAc,CAAC,GAAG,EAAE,MAAM,EAAE,OAAO,EAAE,eAAe,GAAG,OAAO,CAAC,SAAS,CAAC,CAqB9F"}

package/dist/testing/apps/host-pages.js

@@ -0,0 +1,138 @@
+/**
+ * @fileoverview The two loopback origins of the headless MCP Apps host. The host origin
+ * serves a page holding the sandbox iframe; the sandbox origin serves the sandbox proxy
+ * page with the view's CSP as an HTTP header. The proxy announces
+ * `ui/notifications/sandbox-proxy-ready`; on `ui/notifications/sandbox-resource-ready` it
+ * creates the inner view iframe and writes the view HTML into it (an about:blank child
+ * inherits the proxy's origin and CSP); it relays every other message both ways except a
+ * `ui/notifications/sandbox-*` one, a name the spec reserves for host and proxy.
+ *
+ * Both iframes carry the view's permissions-policy `allow` value, set before each frame
+ * loads: a frame can only delegate a feature its own frame was granted, and writing the
+ * view into the inner frame is not a navigation, so its policy is fixed when it is created.
+ *
+ * The host-side relay is not part of the host page: it runs in an isolated world
+ * ({@link HOST_WORLD}) installed over CDP, and reports through a binding only that world
+ * can see, so the view cannot reach the channel to Node.
+ * @module src/testing/apps/host-pages
+ */
+import http from 'node:http';
+/** The isolated world the host relay runs in. */
+export const HOST_WORLD = '__mcpAppsHost';
+/** Binding the relay calls with each message from the sandbox, as JSON. */
+export const RECEIVE_BINDING = '__mcpAppsHostReceive';
+/** Function the relay defines in its world; Node calls it with each message for the view. */
+export const SEND_FUNCTION = '__mcpAppsHostSend';
+/** Function the relay defines to set the sandbox iframe's height in CSS pixels. */
+export const RESIZE_FUNCTION = '__mcpAppsHostResize';
+/** The id of the sandbox iframe in the host page. */
+export const SANDBOX_FRAME_ID = 'mcp-apps-sandbox';
+/** Start both origins. `csp` is sent with the sandbox page. */
+export async function startHostPages(csp, options) {
+    let sandboxOrigin = '';
+    let hostOrigin = '';
+    const host = await listen((req, res) => {
+        if (req.url !== '/')
+            return notFound(res);
+        send(res, hostPage(sandboxOrigin, options), {});
+    });
+    const sandbox = await listen((req, res) => {
+        if (req.url !== '/sandbox.html')
+            return notFound(res);
+        send(res, sandboxPage(hostOrigin, options.allow), { 'content-security-policy': csp });
+    });
+    hostOrigin = `http://127.0.0.1:${host.address().port}`;
+    sandboxOrigin = `http://127.0.0.1:${sandbox.address().port}`;
+    return {
+        hostUrl: `${hostOrigin}/`,
+        sandboxOrigin,
+        relayScript: relayScript(sandboxOrigin),
+        close: async () => {
+            await Promise.all([stop(host), stop(sandbox)]);
+        },
+    };
+}
+function listen(handler) {
+    return new Promise((resolve, reject) => {
+        const server = http.createServer(handler);
+        server.once('error', reject);
+        server.listen(0, '127.0.0.1', () => resolve(server));
+    });
+}
+function stop(server) {
+    server.closeAllConnections();
+    return new Promise((resolve) => server.close(() => resolve()));
+}
+function send(res, body, headers) {
+    res.writeHead(200, {
+        'content-type': 'text/html; charset=utf-8',
+        'cache-control': 'no-store',
+        ...headers,
+    });
+    res.end(body);
+}
+function notFound(res) {
+    res.writeHead(404, { 'content-type': 'text/plain' });
+    res.end('not found');
+}
+function hostPage(sandboxOrigin, { allow, background, height, width }) {
+    return `<!doctype html>
+<html><head><meta charset="utf-8"><title>MCP Apps host</title>
+<style>html,body{margin:0;padding:0;background:${background}}iframe{display:block;border:0}</style>
+</head><body>
+<iframe id="${SANDBOX_FRAME_ID}" src="${sandboxOrigin}/sandbox.html" sandbox="allow-scripts allow-same-origin allow-forms"${allow ? ` allow="${allow}"` : ''} style="width:${width}px;height:${height}px"></iframe>
+</body></html>`;
+}
+function sandboxPage(hostOrigin, allow) {
+    return `<!doctype html>
+<html><head><meta charset="utf-8"><style>html,body{margin:0;padding:0;height:100%;overflow:hidden}iframe{display:block;border:0;width:100%;height:100%}</style></head>
+<body><script>
+(() => {
+  const HOST_ORIGIN = ${JSON.stringify(hostOrigin)};
+  const ALLOW = ${JSON.stringify(allow)};
+  const reserved = (data) => typeof data?.method === 'string' && data.method.startsWith('ui/notifications/sandbox-');
+  let inner;
+  window.addEventListener('message', (event) => {
+    const data = event.data;
+    if (event.source === window.parent) {
+      if (event.origin !== HOST_ORIGIN) return;
+      if (data?.method === 'ui/notifications/sandbox-resource-ready') {
+        inner = document.createElement('iframe');
+        inner.setAttribute('sandbox', 'allow-scripts allow-same-origin allow-forms');
+        if (ALLOW) inner.setAttribute('allow', ALLOW);
+        document.body.appendChild(inner);
+        const doc = inner.contentDocument;
+        doc.open();
+        doc.write(String(data.params.html));
+        doc.close();
+        return;
+      }
+      if (!reserved(data) && inner?.contentWindow) inner.contentWindow.postMessage(data, '*');
+    } else if (inner && event.source === inner.contentWindow) {
+      if (event.origin !== location.origin || reserved(data)) return;
+      window.parent.postMessage(data, HOST_ORIGIN);
+    }
+  });
+  window.parent.postMessage({ jsonrpc: '2.0', method: 'ui/notifications/sandbox-proxy-ready', params: {} }, HOST_ORIGIN);
+})();
+</script></body></html>`;
+}
+function relayScript(sandboxOrigin) {
+    return `(() => {
+  if (window.top !== window) return;
+  const SANDBOX_ORIGIN = ${JSON.stringify(sandboxOrigin)};
+  const frame = () => document.getElementById(${JSON.stringify(SANDBOX_FRAME_ID)});
+  window.addEventListener('message', (event) => {
+    const sandbox = frame();
+    if (!sandbox || event.source !== sandbox.contentWindow || event.origin !== SANDBOX_ORIGIN) return;
+    globalThis[${JSON.stringify(RECEIVE_BINDING)}](JSON.stringify(event.data));
+  });
+  globalThis[${JSON.stringify(SEND_FUNCTION)}] = (json) => {
+    frame().contentWindow.postMessage(JSON.parse(json), SANDBOX_ORIGIN);
+  };
+  globalThis[${JSON.stringify(RESIZE_FUNCTION)}] = (height) => {
+    frame().style.height = height + 'px';
+  };
+})();`;
+}
+//# sourceMappingURL=host-pages.js.map

package/dist/testing/apps/host-pages.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"host-pages.js","sourceRoot":"","sources":["../../../src/testing/apps/host-pages.ts"],"names":[],"mappings":"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"}

package/dist/testing/apps/index.d.ts

@@ -0,0 +1,167 @@
+/**
+ * @fileoverview Headless MCP Apps host. `renderAppTool` connects to a server as a client
+ * advertising `io.modelcontextprotocol/ui`, calls a tool, loads its `ui://` resource into
+ * headless `chrome-headless-shell` inside the double-iframe sandbox and CSP the MCP Apps
+ * specification prescribes, plays the host half of the protocol through the official
+ * `AppBridge`, runs scripted steps against the view, and returns a report.
+ *
+ * Import from `@cyanheads/mcp-ts-core/testing/apps`. The optional peers
+ * `@modelcontextprotocol/client` and `@modelcontextprotocol/ext-apps` are loaded on first
+ * use; importing this subpath without them succeeds.
+ *
+ * @example
+ * ```ts
+ * import { renderAppTool } from '@cyanheads/mcp-ts-core/testing/apps';
+ *
+ * const run = await renderAppTool({
+ *   server: { command: 'bun', args: ['run', 'dist/index.js'] },
+ *   tool: 'my_app_tool',
+ *   arguments: { query: 'probe' },
+ *   steps: [{ click: '#action-btn' }, { screenshot: 'after-click' }],
+ * });
+ * ```
+ * @module src/testing/apps
+ */
+/** How to reach the server: a stdio command, or a Streamable HTTP endpoint. */
+export type AppServerTarget = {
+    args?: string[];
+    command: string;
+    cwd?: string;
+    /** The server's environment. Default: the MCP client's inherited-variable allowlist. */
+    env?: Record<string, string>;
+} | {
+    headers?: Record<string, string>;
+    url: string;
+};
+/** One scripted action against the view, run after the tool result is delivered. */
+export type AppRenderStep = {
+    click: string;
+} | {
+    fill: string;
+    value: string;
+} | {
+    timeoutMs?: number;
+    waitFor: string;
+} | {
+    evaluate: string;
+} | {
+    screenshot: string;
+};
+/** Display modes a host can offer a view. */
+export type AppDisplayMode = 'inline' | 'fullscreen' | 'pip';
+/** The host the view sees. */
+export interface AppHostOptions {
+    /** Display modes the host accepts on `ui/request-display-mode`. Default: `['inline']`. */
+    availableDisplayModes?: AppDisplayMode[];
+    /** The initial display mode. Default: `'inline'`. */
+    displayMode?: AppDisplayMode;
+    /** Fixed container height in CSS pixels. Default: follows the view's size-changed reports. */
+    height?: number;
+    locale?: string;
+    /** Send `tool-input-partial` notifications (growing prefixes of the arguments) before `tool-input`. */
+    streamInput?: boolean;
+    /** CSS custom properties passed as `styles.variables`. */
+    styles?: Record<string, string>;
+    /** Default: `'light'`. */
+    theme?: 'light' | 'dark';
+    timeZone?: string;
+    /** Container width in CSS pixels. Default: 720. */
+    width?: number;
+}
+/** Options for one render. */
+export interface RenderAppToolOptions {
+    arguments?: Record<string, unknown>;
+    /** Path to a `chrome-headless-shell` executable; overrides `MCP_APPS_BROWSER_PATH` and the cache. */
+    browserPath?: string;
+    host?: AppHostOptions;
+    /** Where screenshots are written. Default: a new directory under the OS temp dir. */
+    outDir?: string;
+    server: AppServerTarget;
+    steps?: AppRenderStep[];
+    /** How long to wait for the view's `initialized` and for each step. Default: 15000 ms. */
+    timeoutMs?: number;
+    tool: string;
+}
+/** A message between the view and the host, as it crossed the sandbox. */
+export interface AppRenderMessage {
+    /** Milliseconds since the run started. */
+    at: number;
+    direction: 'view-to-host' | 'host-to-view';
+    message: Record<string, unknown>;
+}
+/** An uncaught exception or console error. */
+export interface AppRenderError {
+    column?: number;
+    /** The frame it came from: the view, the sandbox proxy, or the host page. */
+    frame: 'view' | 'sandbox' | 'host' | 'unknown';
+    line?: number;
+    message: string;
+    source: 'exception' | 'console';
+    url?: string;
+}
+/** A Content Security Policy violation in the sandbox or the view. */
+export interface AppCspViolation {
+    /** The blocked URL, or `eval` / `inline` / `wasm-eval` for a blocked script evaluation. */
+    blockedURI: string;
+    directive: string;
+    line?: number;
+    sourceURL?: string;
+    violationType: string;
+}
+/** The outcome of one step. */
+export interface AppRenderStepResult {
+    error?: string;
+    ok: boolean;
+    /** Path of the PNG a screenshot step wrote. */
+    screenshot?: string;
+    step: AppRenderStep;
+    /** The value an evaluate step returned. */
+    value?: unknown;
+}
+/** What one render observed. */
+export interface AppRenderReport {
+    /** The view's `appInfo` from `ui/initialize`. */
+    appInfo?: {
+        name: string;
+        version: string;
+    };
+    arguments: Record<string, unknown>;
+    browser: {
+        executable: string;
+        pid: number;
+        profileDir: string;
+    };
+    /** The CSP header the sandbox applied to the view. */
+    csp: string;
+    cspViolations: AppCspViolation[];
+    durationMs: number;
+    errors: AppRenderError[];
+    /** A failure after the browser was reached, such as the view never initializing. */
+    failure?: string;
+    /** The view completed `ui/initialize`. */
+    initialized: boolean;
+    messages: AppRenderMessage[];
+    resourceUri: string;
+    screenshots: string[];
+    /** The last `ui/notifications/size-changed`. */
+    size?: {
+        height?: number;
+        width?: number;
+    };
+    steps: AppRenderStepResult[];
+    /** The view's rendered text after the steps. */
+    text: string;
+    tool: string;
+    /** Why the tool call failed at the protocol level; the view then received `tool-cancelled`. */
+    toolError?: string;
+    toolResult?: Record<string, unknown>;
+}
+/**
+ * Render an app tool's view in a headless MCP Apps host and report what happened.
+ * Resolves with the report whenever the run reached the browser, even when the view
+ * failed. Throws only on setup failures: a missing optional peer, no browser, the server
+ * unreachable, the tool missing, or its UI resource absent, unreadable, or declaring a
+ * `_meta.ui.csp` entry that is not a plain origin.
+ */
+export declare function renderAppTool(options: RenderAppToolOptions): Promise<AppRenderReport>;
+//# sourceMappingURL=index.d.ts.map