@cyanheads/mcp-ts-core 0.13.10 → 0.13.11

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

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

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

package/dist/testing/apps/index.js

@@ -0,0 +1,36 @@
+/**
+ * @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
+ */
+/**
+ * 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 async function renderAppTool(options) {
+    const { runAppRender } = await import('./run.js');
+    return runAppRender(options);
+}
+//# sourceMappingURL=index.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/testing/apps/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAmIH;;;;;;GAMG;AACH,MAAM,CAAC,KAAK,UAAU,aAAa,CAAC,OAA6B;IAC/D,MAAM,EAAE,YAAY,EAAE,GAAG,MAAM,MAAM,CAAC,UAAU,CAAC,CAAC;IAClD,OAAO,YAAY,CAAC,OAAO,CAAC,CAAC;AAC/B,CAAC"}

package/dist/testing/apps/partial-json.d.ts

@@ -0,0 +1,14 @@
+/**
+ * @fileoverview Growing prefixes of a tool's argument JSON for `ui/notifications/tool-input-partial`
+ * streaming. Each prefix of the serialized arguments is closed into a valid JSON object:
+ * an open string is terminated, open containers are closed, and a trailing token that
+ * cannot be completed (a dangling key, a partial literal) is backed off.
+ * @module src/testing/apps/partial-json
+ */
+/**
+ * Partial argument objects for growing prefixes of `JSON.stringify(args)`, in order. Every
+ * entry is a plain object; consecutive duplicates are dropped and the complete arguments
+ * are never included (those go out as `tool-input`).
+ */
+export declare function partialArguments(args: Record<string, unknown>): Record<string, unknown>[];
+//# sourceMappingURL=partial-json.d.ts.map

package/dist/testing/apps/partial-json.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"partial-json.d.ts","sourceRoot":"","sources":["../../../src/testing/apps/partial-json.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAKH;;;;GAIG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,CAazF"}

package/dist/testing/apps/partial-json.js

@@ -0,0 +1,71 @@
+/**
+ * @fileoverview Growing prefixes of a tool's argument JSON for `ui/notifications/tool-input-partial`
+ * streaming. Each prefix of the serialized arguments is closed into a valid JSON object:
+ * an open string is terminated, open containers are closed, and a trailing token that
+ * cannot be completed (a dangling key, a partial literal) is backed off.
+ * @module src/testing/apps/partial-json
+ */
+/** At most this many partials are produced for one argument object. */
+const MAX_PARTIALS = 8;
+/**
+ * Partial argument objects for growing prefixes of `JSON.stringify(args)`, in order. Every
+ * entry is a plain object; consecutive duplicates are dropped and the complete arguments
+ * are never included (those go out as `tool-input`).
+ */
+export function partialArguments(args) {
+    const json = JSON.stringify(args);
+    const count = Math.min(MAX_PARTIALS, json.length - 1);
+    const partials = [];
+    let previous = '';
+    for (let i = 1; i <= count; i++) {
+        const cut = Math.max(1, Math.floor((json.length * i) / (count + 1)));
+        const closed = closePrefix(json.slice(0, cut));
+        if (closed === undefined || closed === previous || closed === json)
+            continue;
+        previous = closed;
+        partials.push(JSON.parse(closed));
+    }
+    return partials;
+}
+/** The longest closing of `prefix` (backing off one character at a time) that parses as an object. */
+function closePrefix(prefix) {
+    for (let end = prefix.length; end > 0; end--) {
+        const candidate = close(prefix.slice(0, end));
+        try {
+            const value = JSON.parse(candidate);
+            if (value !== null && typeof value === 'object' && !Array.isArray(value)) {
+                return JSON.stringify(value);
+            }
+        }
+        catch {
+            // Not closable at this length; back off.
+        }
+    }
+    return undefined;
+}
+/** `text` with its open string and open containers closed. */
+function close(text) {
+    const closers = [];
+    let inString = false;
+    let escaped = false;
+    for (const ch of text) {
+        if (inString) {
+            if (escaped)
+                escaped = false;
+            else if (ch === '\\')
+                escaped = true;
+            else if (ch === '"')
+                inString = false;
+        }
+        else if (ch === '"')
+            inString = true;
+        else if (ch === '{')
+            closers.push('}');
+        else if (ch === '[')
+            closers.push(']');
+        else if (ch === '}' || ch === ']')
+            closers.pop();
+    }
+    return `${text}${inString ? '"' : ''}${closers.reverse().join('')}`;
+}
+//# sourceMappingURL=partial-json.js.map

package/dist/testing/apps/partial-json.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"partial-json.js","sourceRoot":"","sources":["../../../src/testing/apps/partial-json.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,uEAAuE;AACvE,MAAM,YAAY,GAAG,CAAC,CAAC;AAEvB;;;;GAIG;AACH,MAAM,UAAU,gBAAgB,CAAC,IAA6B;IAC5D,MAAM,IAAI,GAAG,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,CAAC;IAClC,MAAM,KAAK,GAAG,IAAI,CAAC,GAAG,CAAC,YAAY,EAAE,IAAI,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC;IACtD,MAAM,QAAQ,GAA8B,EAAE,CAAC;IAC/C,IAAI,QAAQ,GAAG,EAAE,CAAC;IAClB,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,IAAI,KAAK,EAAE,CAAC,EAAE,EAAE,CAAC;QAChC,MAAM,GAAG,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,IAAI,CAAC,KAAK,CAAC,CAAC,IAAI,CAAC,MAAM,GAAG,CAAC,CAAC,GAAG,CAAC,KAAK,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC;QACrE,MAAM,MAAM,GAAG,WAAW,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,EAAE,GAAG,CAAC,CAAC,CAAC;QAC/C,IAAI,MAAM,KAAK,SAAS,IAAI,MAAM,KAAK,QAAQ,IAAI,MAAM,KAAK,IAAI;YAAE,SAAS;QAC7E,QAAQ,GAAG,MAAM,CAAC;QAClB,QAAQ,CAAC,IAAI,CAAC,IAAI,CAAC,KAAK,CAAC,MAAM,CAA4B,CAAC,CAAC;IAC/D,CAAC;IACD,OAAO,QAAQ,CAAC;AAClB,CAAC;AAED,sGAAsG;AACtG,SAAS,WAAW,CAAC,MAAc;IACjC,KAAK,IAAI,GAAG,GAAG,MAAM,CAAC,MAAM,EAAE,GAAG,GAAG,CAAC,EAAE,GAAG,EAAE,EAAE,CAAC;QAC7C,MAAM,SAAS,GAAG,KAAK,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,EAAE,GAAG,CAAC,CAAC,CAAC;QAC9C,IAAI,CAAC;YACH,MAAM,KAAK,GAAY,IAAI,CAAC,KAAK,CAAC,SAAS,CAAC,CAAC;YAC7C,IAAI,KAAK,KAAK,IAAI,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,EAAE,CAAC;gBACzE,OAAO,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,CAAC;YAC/B,CAAC;QACH,CAAC;QAAC,MAAM,CAAC;YACP,yCAAyC;QAC3C,CAAC;IACH,CAAC;IACD,OAAO,SAAS,CAAC;AACnB,CAAC;AAED,8DAA8D;AAC9D,SAAS,KAAK,CAAC,IAAY;IACzB,MAAM,OAAO,GAAa,EAAE,CAAC;IAC7B,IAAI,QAAQ,GAAG,KAAK,CAAC;IACrB,IAAI,OAAO,GAAG,KAAK,CAAC;IACpB,KAAK,MAAM,EAAE,IAAI,IAAI,EAAE,CAAC;QACtB,IAAI,QAAQ,EAAE,CAAC;YACb,IAAI,OAAO;gBAAE,OAAO,GAAG,KAAK,CAAC;iBACxB,IAAI,EAAE,KAAK,IAAI;gBAAE,OAAO,GAAG,IAAI,CAAC;iBAChC,IAAI,EAAE,KAAK,GAAG;gBAAE,QAAQ,GAAG,KAAK,CAAC;QACxC,CAAC;aAAM,IAAI,EAAE,KAAK,GAAG;YAAE,QAAQ,GAAG,IAAI,CAAC;aAClC,IAAI,EAAE,KAAK,GAAG;YAAE,OAAO,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;aAClC,IAAI,EAAE,KAAK,GAAG;YAAE,OAAO,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;aAClC,IAAI,EAAE,KAAK,GAAG,IAAI,EAAE,KAAK,GAAG;YAAE,OAAO,CAAC,GAAG,EAAE,CAAC;IACnD,CAAC;IACD,OAAO,GAAG,IAAI,GAAG,QAAQ,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,GAAG,OAAO,CAAC,OAAO,EAAE,CAAC,IAAI,CAAC,EAAE,CAAC,EAAE,CAAC;AACtE,CAAC"}

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

@@ -0,0 +1,13 @@
+/**
+ * @fileoverview One headless MCP Apps host run, loaded on demand by `renderAppTool`.
+ * Node holds the MCP client and the official `AppBridge`; the bridge's transport relays
+ * JSON-RPC through the host page's isolated-world relay into the sandbox proxy and the
+ * view. CDP supplies the instrumentation: exceptions and console errors from
+ * `Runtime`, CSP violations from `Audits` issues, frames from `Page`. The optional peers
+ * are imported here, inside the run, never at module load.
+ * @module src/testing/apps/run
+ */
+import type { AppRenderReport, RenderAppToolOptions } from './index.js';
+/** Run one render. See `renderAppTool`. */
+export declare function runAppRender(options: RenderAppToolOptions): Promise<AppRenderReport>;
+//# sourceMappingURL=run.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"run.d.ts","sourceRoot":"","sources":["../../../src/testing/apps/run.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AA2CH,OAAO,KAAK,EAGV,eAAe,EAIf,oBAAoB,EACrB,MAAM,YAAY,CAAC;AAsBpB,2CAA2C;AAC3C,wBAAsB,YAAY,CAAC,OAAO,EAAE,oBAAoB,GAAG,OAAO,CAAC,eAAe,CAAC,CA6F1F"}