castle-web-cli 0.4.78 → 0.4.79

package/dist/native/playtest-browser.js

@@ -0,0 +1,354 @@
+// Owns the ONE warm Chromium instance a serve uses for `playtest` calls.
+// Lazily launched on first use, closed after PLAYTEST_IDLE_SHUTDOWN_MS with
+// no in-flight call, and closed for good on serve shutdown. A browser that
+// died (crashed mid-call, or the OS reaped it) is simply relaunched the NEXT
+// time `withBrowser` runs -- the call that discovered it dead already failed
+// with its own capture-failure error (see playtest-executor.ts's try/catch);
+// this file never retries WITHIN a call.
+//
+// The only file in native/** that imports the `playwright-core` package, and
+// it does so with a dynamic `import()` inside loadPlaywright() -- never a
+// top-level import -- so requiring this module (transitively, via agent.ts)
+// costs nothing and cannot crash a serve that never calls playtest, even if
+// the package isn't installed at all. A missing package surfaces as a normal
+// tool-error string instead.
+//
+// Browser binaries are installed ON DEMAND, not at npm-install time: the dep
+// is playwright-core (identical API to `playwright`, same pinned Chromium
+// build per version, but NO postinstall browser download), and the first
+// call that finds the pinned build missing from the cache spawns playwright-
+// core's own install CLI inline, behind a module-level single-flight promise
+// every concurrent caller (and the task-start prewarm) shares. Detection
+// idiom, verified against playwright-core 1.61: chromium.executablePath()
+// does NOT throw when the browser is missing -- it returns the path the
+// registry WOULD use (honoring PLAYWRIGHT_BROWSERS_PATH), so existence is an
+// fs.existsSync check on that path; the try/catch is belt-and-suspenders for
+// versions where it throws instead. The install wait is deliberately not
+// tied to any caller's AbortSignal or timeout budget: the download is shared
+// state, and a per-call session timeout only applies once the session
+// actually starts (after install).
+import * as fs from "fs";
+import * as path from "path";
+import { createRequire } from "module";
+import { spawn } from "child_process";
+const PLAYTEST_IDLE_SHUTDOWN_MS = 2 * 60_000;
+// The background-throttling-disabling family: without these, a headless
+// Chromium can throttle/suspend requestAnimationFrame on a page it considers
+// backgrounded (there is no real OS window/tab focus in headless mode), which
+// would starve the very rAF-tick diagnostic playtest relies on to tell "the
+// capture wasn't rendering" apart from "the game is genuinely frozen".
+const LAUNCH_ARGS = [
+    "--disable-background-timer-throttling",
+    "--disable-backgrounding-occluded-windows",
+    "--disable-renderer-backgrounding",
+];
+const MISSING_PLAYWRIGHT_MESSAGE = "playwright-core is not installed in this CLI (run `npm install` from the repo root).";
+const MANUAL_INSTALL_HINT = "install manually with `npx playwright install chromium`";
+export const INSTALL_START_LABEL = "Downloading playtest browser (one-time, ~250MB)\u2026";
+export const INSTALL_WAIT_LABEL = "Waiting for browser download (shared)\u2026";
+// Progress labels are throttled to 20-point steps: every onProgress string
+// becomes a task-feed ROW (see runTaskAgentIn's onActivity wiring in
+// agent.ts), so per-percent updates would flood the feed with ~100 rows.
+const PROGRESS_STEP = 20;
+function launchFailureMessage(err) {
+    const message = err instanceof Error ? err.message : String(err);
+    const looksLikeMissingBrowser = /executable doesn't exist|download.*chromium/i.test(message);
+    return looksLikeMissingBrowser
+        ? `chromium is not installed for playwright -- ${MANUAL_INSTALL_HINT}. (${message})`
+        : `could not launch chromium: ${message}`;
+}
+async function loadPlaywrightReal() {
+    return (await import("playwright-core"));
+}
+// playwright-core's exports map does NOT expose ./cli.js (verified against
+// 1.61: resolving it throws ERR_PACKAGE_PATH_NOT_EXPORTED), but it DOES
+// export ./package.json -- so resolve that and join cli.js beside it.
+function resolveInstallCli() {
+    const req = createRequire(import.meta.url);
+    try {
+        return req.resolve("playwright-core/cli.js");
+    }
+    catch {
+        /* not exported -- expected; fall through */
+    }
+    try {
+        return path.join(path.dirname(req.resolve("playwright-core/package.json")), "cli.js");
+    }
+    catch {
+        return null;
+    }
+}
+function runInstallReal(onLine) {
+    return new Promise((resolve, reject) => {
+        const cliPath = resolveInstallCli();
+        if (!cliPath) {
+            reject(new Error(MISSING_PLAYWRIGHT_MESSAGE));
+            return;
+        }
+        // Inherit env so PLAYWRIGHT_BROWSERS_PATH (and proxy settings) apply --
+        // the install lands in the same cache executablePath() reads from.
+        const child = spawn(process.execPath, [cliPath, "install", "chromium"], {
+            env: process.env,
+            stdio: ["ignore", "pipe", "pipe"],
+        });
+        let buf = "";
+        const onData = (chunk) => {
+            buf += chunk.toString("utf8");
+            let nl = buf.search(/[\r\n]/);
+            while (nl >= 0) {
+                const line = buf.slice(0, nl);
+                buf = buf.slice(nl + 1);
+                if (line.trim())
+                    onLine(line);
+                nl = buf.search(/[\r\n]/);
+            }
+        };
+        child.stdout.on("data", onData);
+        child.stderr.on("data", onData);
+        child.on("error", (err) => reject(err));
+        child.on("exit", (code, signal) => {
+            if (code === 0)
+                resolve();
+            else
+                reject(new Error(`install CLI exited with ${signal ? `signal ${signal}` : `code ${code}`}`));
+        });
+    });
+}
+// MODULE-level (not per-manager): one Chromium download per process, no
+// matter how many managers/serves/prewarms race for it. Reset to null when
+// the flight settles -- on success the fs existence check gates any future
+// call, and on failure a later call must be free to retry rather than
+// forever re-awaiting a poisoned promise.
+let installFlight = null;
+// Fires exactly once per install (module-level, not per caller/waiter) --
+// the serve's stdout/stderr otherwise never mentions a prewarm-initiated
+// install at all, since prewarm() passes no hooks and no caller is watching
+// the per-run transcript. Bracket-prefix style matches the "[agent usage]"
+// lines agent.ts already prints for process-level telemetry.
+function logInstallStart() {
+    console.error("[playtest] downloading browser (~250MB compressed, one-time)...");
+}
+function logInstallFinished(elapsedMs, cachePath) {
+    const elapsedS = (elapsedMs / 1000).toFixed(1);
+    console.error(`[playtest] browser installed in ${elapsedS}s -> ${cachePath ?? "(cache path unknown)"}`);
+}
+function logInstallFailed(elapsedMs, err) {
+    const elapsedS = (elapsedMs / 1000).toFixed(1);
+    const message = err instanceof Error ? err.message : String(err);
+    console.error(`[playtest] browser install failed after ${elapsedS}s: ${message}`);
+}
+function startInstallFlight(runInstall, getCachePath) {
+    const startedAt = Date.now();
+    logInstallStart();
+    const flight = {
+        progressListeners: new Set(),
+        promise: Promise.resolve()
+            .then(() => {
+            let lastStep = -1;
+            return runInstall((line) => {
+                // The install CLI prints progress bars like
+                // "|■■■■    |  43% of 129.7 MiB" -- surface the percent, throttled
+                // to PROGRESS_STEP boundaries so the feed gets a handful of rows,
+                // not a hundred.
+                const m = /(\d{1,3})%/.exec(line);
+                if (!m)
+                    return;
+                const pct = Math.min(100, parseInt(m[1], 10));
+                const step = Math.floor(pct / PROGRESS_STEP);
+                if (step <= lastStep)
+                    return;
+                lastStep = step;
+                for (const listener of flight.progressListeners) {
+                    listener(`${INSTALL_START_LABEL} ${pct}%`);
+                }
+            });
+        })
+            .then(() => {
+            logInstallFinished(Date.now() - startedAt, getCachePath());
+            return { ok: true };
+        }, (err) => {
+            logInstallFailed(Date.now() - startedAt, err);
+            return {
+                ok: false,
+                error: `playtest browser download failed: ${err instanceof Error ? err.message : String(err)}. If this persists (offline, proxy), ${MANUAL_INSTALL_HINT}.`,
+            };
+        })
+            .finally(() => {
+            installFlight = null;
+        }),
+    };
+    return flight;
+}
+// Awaits (joining or starting) the shared install, reporting this CALLER's
+// perspective through its own hooks: the initiator sees the download label,
+// joiners see the shared-wait label, and both get their own started/
+// finished/failed transcript events with THEIR elapsed wait (which is what
+// the digest's "first-run download added ~Ns" note wants).
+async function ensureInstalled(runInstall, hooks, getCachePath) {
+    const startedAt = Date.now();
+    const shared = installFlight !== null;
+    const flight = installFlight ?? (installFlight = startInstallFlight(runInstall, getCachePath));
+    hooks?.onProgress?.(shared ? INSTALL_WAIT_LABEL : INSTALL_START_LABEL);
+    hooks?.onInstallEvent?.({ phase: "started", shared });
+    const listener = (label) => hooks?.onProgress?.(label);
+    flight.progressListeners.add(listener);
+    try {
+        const result = await flight.promise;
+        const elapsedMs = Date.now() - startedAt;
+        if (!result.ok) {
+            hooks?.onInstallEvent?.({ phase: "failed", elapsedMs, error: result.error });
+            return result;
+        }
+        hooks?.onInstallEvent?.({ phase: "finished", elapsedMs, cachePath: getCachePath() });
+        return { ok: true, waitedMs: elapsedMs };
+    }
+    finally {
+        flight.progressListeners.delete(listener);
+    }
+}
+export function createPlaytestBrowserManager(seams) {
+    const loadPlaywright = seams?.loadPlaywright ?? loadPlaywrightReal;
+    const runInstall = seams?.runInstall ?? runInstallReal;
+    let browser = null;
+    let idleTimer = null;
+    let launching = null;
+    function clearIdleTimer() {
+        if (idleTimer) {
+            clearTimeout(idleTimer);
+            idleTimer = null;
+        }
+    }
+    function armIdleTimer() {
+        clearIdleTimer();
+        idleTimer = setTimeout(() => {
+            const dying = browser;
+            browser = null;
+            if (dying)
+                void dying.close().catch(() => undefined);
+        }, PLAYTEST_IDLE_SHUTDOWN_MS);
+        // This is pure housekeeping (closes an idle browser eventually) -- it
+        // must never be the thing keeping the process alive on its own, e.g. a
+        // one-shot script that calls withBrowser once and then expects to exit
+        // as soon as its own work is done, or a test harness that never calls
+        // shutdown().
+        idleTimer.unref();
+    }
+    // Missing-browser detection -- see the module header for the verified
+    // executablePath() semantics this leans on.
+    function missingExecutable(chromium) {
+        try {
+            return !fs.existsSync(chromium.executablePath());
+        }
+        catch {
+            return true;
+        }
+    }
+    async function launchBrowser(playwright) {
+        try {
+            const launched = await playwright.chromium.launch({ args: LAUNCH_ARGS });
+            launched.on("disconnected", () => {
+                if (browser === launched)
+                    browser = null;
+            });
+            browser = launched;
+            return { ok: true, browser: launched };
+        }
+        catch (err) {
+            return { ok: false, error: launchFailureMessage(err) };
+        }
+    }
+    // Two DIFFERENT single-flights, deliberately layered: the install check
+    // runs per caller (so every concurrent caller passes its OWN hooks through
+    // ensureInstalled and gets its own labels/transcript events -- the shared
+    // thing is only the module-level download promise), while the launch that
+    // follows is manager-level single-flighted the old way (sub-second, no
+    // surfacing needed, must not spawn N Chromiums for N concurrent callers).
+    async function ensureBrowser(hooks) {
+        if (browser?.isConnected())
+            return { ok: true, browser };
+        browser = null;
+        let playwright;
+        try {
+            playwright = await loadPlaywright();
+        }
+        catch {
+            return { ok: false, error: MISSING_PLAYWRIGHT_MESSAGE };
+        }
+        let installedMs;
+        if (missingExecutable(playwright.chromium)) {
+            // Reported in the transcript's `finished` event: the concrete
+            // executable the registry resolved post-install (honors
+            // PLAYWRIGHT_BROWSERS_PATH), or undefined if it still can't say.
+            const getCachePath = () => {
+                try {
+                    return playwright.chromium.executablePath();
+                }
+                catch {
+                    return undefined;
+                }
+            };
+            const installed = await ensureInstalled(runInstall, hooks, getCachePath);
+            if (!installed.ok)
+                return installed;
+            installedMs = installed.waitedMs;
+        }
+        // Another caller may have finished launching while this one waited on
+        // the download; reuse its browser rather than racing a second launch.
+        // (Cast: TS's flow analysis still sees the `browser = null` from before
+        // the awaits -- it can't know the install/launch awaits let other
+        // callers reassign it -- and would otherwise narrow this read to null.)
+        const existing = browser;
+        if (existing?.isConnected())
+            return { ok: true, browser: existing, installedMs };
+        if (!launching) {
+            launching = launchBrowser(playwright).finally(() => {
+                launching = null;
+            });
+        }
+        const launched = await launching;
+        if (!launched.ok)
+            return launched;
+        return { ok: true, browser: launched.browser, installedMs };
+    }
+    return {
+        async withBrowser(fn, hooks) {
+            clearIdleTimer();
+            try {
+                const acquired = await ensureBrowser(hooks);
+                if (!acquired.ok)
+                    return acquired;
+                try {
+                    const value = await fn(acquired.browser);
+                    return { ok: true, value, installedMs: acquired.installedMs };
+                }
+                catch (err) {
+                    return { ok: false, error: err instanceof Error ? err.message : String(err) };
+                }
+            }
+            finally {
+                armIdleTimer();
+            }
+        },
+        prewarm() {
+            void (async () => {
+                try {
+                    const playwright = await loadPlaywright();
+                    if (missingExecutable(playwright.chromium)) {
+                        await ensureInstalled(runInstall, undefined, () => undefined);
+                    }
+                }
+                catch {
+                    /* package missing / install failed: degrade silently to the lazy
+                       path, which re-detects and surfaces a proper tool error */
+                }
+            })();
+        },
+        async shutdown() {
+            clearIdleTimer();
+            const dying = browser;
+            browser = null;
+            if (dying)
+                await dying.close().catch(() => undefined);
+        },
+    };
+}

package/dist/native/playtest-executor.d.ts

@@ -0,0 +1,3 @@
+import type { PlaytestBrowserManager } from "./playtest-browser.js";
+import { type PlaytestExecutor } from "./playtest.js";
+export declare function createPlaywrightPlaytestExecutor(browserManager: PlaytestBrowserManager): PlaytestExecutor;

package/dist/native/playtest-executor.js

@@ -0,0 +1,156 @@
+// The real (Playwright-backed) PlaytestExecutor: navigates a fresh
+// browser context + page to the served deck, settles, replays a timeline of
+// mouse/keyboard primitives and screenshot captures on one wall clock, and
+// reports console/pageerror output plus rAF-tick capture-health diagnostics.
+// See native/playtest.ts for the browser-free types this implements and
+// native/playtest-browser.ts for the warm-Chromium lifecycle this borrows a
+// browser from. Only type-only Playwright imports here (erased at compile
+// time) -- the actual `playwright-core` package is loaded lazily by
+// playtest-browser.ts, never by this file directly.
+import { PLAYTEST_SETTLE_MS, PLAYTEST_VIEWPORT, } from "./playtest.js";
+const NAV_TIMEOUT_MS = 20_000;
+export function createPlaywrightPlaytestExecutor(browserManager) {
+    return {
+        async runSession(input) {
+            const outcome = await browserManager.withBrowser((browser) => runSessionOnBrowser(browser, input), {
+                onProgress: input.onProgress,
+                onInstallEvent: input.onInstallEvent,
+            });
+            if (outcome.ok) {
+                // Surface how long THIS call sat waiting on the one-time browser
+                // download (if it did) -- buildDigest turns it into a "first-run
+                // download added ~Ns" note.
+                if (outcome.installedMs && outcome.installedMs > 0) {
+                    return { ...outcome.value, browserInstallMs: outcome.installedMs };
+                }
+                return outcome.value;
+            }
+            return emptyResult(outcome.error, input);
+        },
+    };
+}
+function emptyResult(error, input) {
+    return {
+        ok: false,
+        error,
+        viewport: PLAYTEST_VIEWPORT,
+        frames: [],
+        console: [],
+        diagnostics: {
+            rafTicks: 0,
+            wallMs: 0,
+            framesRequested: input.timeline.filter((e) => e.kind === "screenshot").length,
+            framesCaptured: 0,
+            hidden: false,
+        },
+    };
+}
+function phaseFor(relMs, b) {
+    if (b.settleStartRel === null || relMs < b.settleStartRel)
+        return "load";
+    if (b.sessionStartRel === null || relMs < b.sessionStartRel)
+        return "settle";
+    return "session";
+}
+function attachConsoleCapture(page, navStart, boundaries) {
+    const log = [];
+    const push = (level, text) => {
+        const relMs = Date.now() - navStart;
+        log.push({ t: relMs, phase: phaseFor(relMs, boundaries), level, text });
+    };
+    page.on("console", (msg) => {
+        const type = msg.type();
+        push(type === "warning" ? "warn" : type === "error" ? "error" : "log", msg.text());
+    });
+    page.on("pageerror", (err) => push("pageerror", err.message));
+    return log;
+}
+async function runTimeline(page, input) {
+    const sessionStart = Date.now();
+    const frames = [];
+    let framesRequested = 0;
+    for (const event of input.timeline) {
+        if (input.signal?.aborted)
+            throw new Error("playtest aborted mid-session");
+        const waitMs = event.t - (Date.now() - sessionStart);
+        if (waitMs > 0)
+            await page.waitForTimeout(waitMs);
+        switch (event.kind) {
+            case "mousemove":
+                await page.mouse.move(event.x, event.y);
+                break;
+            case "mousedown":
+                await page.mouse.move(event.x, event.y);
+                await page.mouse.down();
+                break;
+            case "mouseup":
+                await page.mouse.move(event.x, event.y);
+                await page.mouse.up();
+                break;
+            case "keydown":
+                await page.keyboard.down(event.key);
+                break;
+            case "keyup":
+                await page.keyboard.up(event.key);
+                break;
+            case "screenshot": {
+                framesRequested++;
+                const png = await page.screenshot({ type: "png" });
+                frames.push({ t: event.t, png });
+                break;
+            }
+        }
+    }
+    const remaining = input.durationMs - (Date.now() - sessionStart);
+    if (remaining > 0)
+        await page.waitForTimeout(remaining);
+    return { frames, framesRequested, wallMs: Date.now() - sessionStart };
+}
+async function measureDiagnostics(page, wallMs) {
+    const rafTicks = await page.evaluate(() => window.__castleRafTicks ?? 0);
+    const hidden = await page.evaluate(() => document.hidden);
+    return { rafTicks, wallMs, framesRequested: 0, framesCaptured: 0, hidden };
+}
+async function runSessionOnBrowser(browser, input) {
+    const navStart = Date.now();
+    const boundaries = { settleStartRel: null, sessionStartRel: null };
+    const context = await browser.newContext({ viewport: PLAYTEST_VIEWPORT });
+    let consoleLog = [];
+    try {
+        const page = await context.newPage();
+        consoleLog = attachConsoleCapture(page, navStart, boundaries);
+        if (input.signal?.aborted)
+            throw new Error("playtest aborted before navigation");
+        await page.goto(input.url, { waitUntil: "load", timeout: NAV_TIMEOUT_MS });
+        boundaries.settleStartRel = Date.now() - navStart;
+        await page.waitForTimeout(PLAYTEST_SETTLE_MS);
+        boundaries.sessionStartRel = Date.now() - navStart;
+        await page.evaluate(() => {
+            const win = window;
+            win.__castleRafTicks = 0;
+            const tick = () => {
+                win.__castleRafTicks = (win.__castleRafTicks ?? 0) + 1;
+                requestAnimationFrame(tick);
+            };
+            requestAnimationFrame(tick);
+        });
+        const { frames, framesRequested, wallMs } = await runTimeline(page, input);
+        const diagnostics = await measureDiagnostics(page, wallMs);
+        diagnostics.framesRequested = framesRequested;
+        diagnostics.framesCaptured = frames.length;
+        return { ok: true, viewport: PLAYTEST_VIEWPORT, frames, console: consoleLog, diagnostics };
+    }
+    catch (err) {
+        return {
+            ok: false,
+            error: err instanceof Error ? err.message : String(err),
+            viewport: PLAYTEST_VIEWPORT,
+            frames: [],
+            console: consoleLog,
+            diagnostics: { rafTicks: 0, wallMs: 0, framesRequested: 0, framesCaptured: 0, hidden: false },
+        };
+    }
+    finally {
+        await context.close().catch(() => undefined);
+    }
+}

package/dist/native/playtest.d.ts

@@ -0,0 +1,131 @@
+export declare const PLAYTEST_MAX_DURATION_MS = 15000;
+export declare const PLAYTEST_MAX_ACTIONS = 20;
+export declare const PLAYTEST_MAX_SHOTS = 6;
+export declare const PLAYTEST_MAX_CALLS_PER_RUN = 4;
+export declare const PLAYTEST_VIEWPORT: {
+    readonly width: 500;
+    readonly height: 700;
+};
+export declare const PLAYTEST_SETTLE_MS = 1500;
+export type PlaytestActionType = "down" | "move" | "up" | "tap" | "key";
+export interface PlaytestActionRaw {
+    t: number;
+    type: PlaytestActionType;
+    x?: number;
+    y?: number;
+    key?: string;
+    durationMs?: number;
+}
+export interface PlaytestArgs {
+    durationMs: number;
+    actions: PlaytestActionRaw[];
+    screenshots: number[];
+}
+export type TimelineEvent = {
+    t: number;
+    kind: "mousemove" | "mousedown" | "mouseup";
+    x: number;
+    y: number;
+} | {
+    t: number;
+    kind: "keydown" | "keyup";
+    key: string;
+} | {
+    t: number;
+    kind: "screenshot";
+};
+export declare function validatePlaytestArgs(args: Record<string, unknown>): {
+    ok: true;
+    value: PlaytestArgs;
+} | {
+    ok: false;
+    error: string;
+};
+export declare function buildTimeline(args: PlaytestArgs): TimelineEvent[];
+export interface PlaytestDiagnostics {
+    rafTicks: number;
+    wallMs: number;
+    framesRequested: number;
+    framesCaptured: number;
+    hidden: boolean;
+}
+export declare function diagnoseCapture(d: PlaytestDiagnostics): {
+    expectedTicks: number;
+    starved: boolean;
+};
+export interface PlaytestFrame {
+    t: number;
+    png: Buffer;
+}
+export declare function countDistinctFrames(frames: PlaytestFrame[]): number;
+export declare function captureReport(frames: PlaytestFrame[], d: PlaytestDiagnostics): {
+    distinct: number;
+    starved: boolean;
+    expectedTicks: number;
+    lines: string[];
+};
+export declare function playtestDeckUrl(serveOrigin: string): string;
+export interface PlaytestConsoleEntry {
+    t: number;
+    phase: "load" | "settle" | "session";
+    level: "log" | "warn" | "error" | "pageerror";
+    text: string;
+}
+export type PlaytestInstallEvent = {
+    phase: "started";
+    shared: boolean;
+} | {
+    phase: "finished";
+    elapsedMs: number;
+    cachePath?: string;
+} | {
+    phase: "failed";
+    elapsedMs: number;
+    error: string;
+};
+export interface PlaytestSessionInput {
+    url: string;
+    durationMs: number;
+    timeline: TimelineEvent[];
+    signal?: AbortSignal;
+    onProgress?: (label: string) => void;
+    onInstallEvent?: (evt: PlaytestInstallEvent) => void;
+}
+export interface PlaytestSessionResult {
+    ok: boolean;
+    error?: string;
+    viewport: {
+        width: number;
+        height: number;
+    };
+    frames: PlaytestFrame[];
+    console: PlaytestConsoleEntry[];
+    diagnostics: PlaytestDiagnostics;
+    browserInstallMs?: number;
+}
+export interface PlaytestExecutor {
+    runSession(input: PlaytestSessionInput): Promise<PlaytestSessionResult>;
+}
+export interface PlaytestToolContext {
+    executor: PlaytestExecutor;
+    serveUrl: string;
+    framesDir: string;
+    callCount: {
+        value: number;
+    };
+    onProgress?: (label: string) => void;
+    onInstallEvent?: (evt: PlaytestInstallEvent) => void;
+}
+export interface PlaytestToolResult {
+    ok: boolean;
+    output: string;
+    images?: Array<{
+        label: string;
+        dataUrl: string;
+    }>;
+    playtestFrames?: string[];
+    activitySummary?: string;
+}
+export declare function runPlaytest(args: Record<string, unknown>, deckDir: string, ctx: PlaytestToolContext | undefined, signal: AbortSignal | undefined): Promise<PlaytestToolResult>;
+export declare const PLAYTEST_TOOL_DESCRIPTION: string;
+export declare const PLAYTEST_TOOL_PARAMETERS: Record<string, unknown>;