ptywright 0.3.0 → 0.4.0

package/README.md

@@ -380,6 +380,44 @@ Artifacts are split intentionally:
 - `tests/agent-snapshots/<name>/` contains stable terminal/DOM baselines.
 - `--update-snapshots` is the explicit update path for intentional UI changes.
 
+### Project Config
+
+For repeated agent regression work, put project-level defaults in
+`ptywright.config.ts` instead of repeating paths and browser defaults in every
+flow file. The CLI discovers `ptywright.config.ts|mts|cts|js|mjs|cjs` from the
+current directory upward, and `--config <file>` selects one explicitly.
+
+```ts
+import { defineConfig } from "ptywright/config";
+
+export default defineConfig({
+  agent: {
+    artifactsRoot: ".tmp/agent",
+    cassetteDir: "tests/agent-cassettes",
+    snapshotDir: "tests/agent-snapshots",
+    defaults: {
+      headless: true,
+      timeoutMs: 45_000,
+      screenshot: false,
+      viewports: [{ name: "desktop", width: 1280, height: 820 }],
+      mask: [{ regex: "session_[a-z0-9]+", replacement: "<session>" }],
+    },
+  },
+});
+```
+
+```bash
+ptywright agent run tests/agents/codex.flow.json --update-snapshots
+ptywright agent check
+ptywright agent replay-all --update-snapshots
+ptywright agent promote .tmp/agent/codex/codex.cassette.json --update-snapshots
+```
+
+Config paths are resolved relative to the config file directory. CLI arguments
+override config defaults, and fields written in a flow file override config
+defaults for that flow. The flow file remains the test case; the config file is
+only for shared project defaults and common artifact locations.
+
 `launch.mode=command` is the recommended integration contract. `command` and
 `args` are spawned directly, and ptywright reads the first URL printed to stdout
 or stderr. Use `waitForUrlMs` to tune startup timeouts and `urlRegex` when the

package/dist/agent.mjs

@@ -1,2 +1,2 @@
-import { a as runAgentSpecPath, i as runAgentSpec, n as printAgentLaunchPlan, r as replayAgentRecordPath, t as defaultSpecNameForPath } from "./runner-zi0nItvB.mjs";
+import { a as runAgentSpecPath, i as runAgentSpec, n as printAgentLaunchPlan, r as replayAgentRecordPath, t as defaultSpecNameForPath } from "./runner-CembqDgJ.mjs";
 export { defaultSpecNameForPath, printAgentLaunchPlan, replayAgentRecordPath, runAgentSpec, runAgentSpecPath };

package/dist/bin/ptywright.mjs

@@ -1,5 +1,5 @@
 #!/usr/bin/env bun
-import { t as main } from "../cli-CfvlbRoZ.mjs";
+import { t as main } from "../cli-C40H_ElC.mjs";
 //#region src/bin/ptywright.ts
 await main();
 //#endregion

package/dist/{cli-CfvlbRoZ.mjs → cli-C40H_ElC.mjs}

@@ -1,7 +1,8 @@
 import { c as createDefaultPtyAdapter, l as resolvePtyBackend } from "./runner-zApMYWZx.mjs";
-import { a as readScriptManifestPath, c as resolveScriptManifestPath, d as resolveScriptRunSummaryPath, f as runScriptPath, i as findScriptSummaryManifest, l as validateScriptManifest, n as runAllScripts, o as relocateScriptManifestCommands, s as resolveManifestPrimaryPath$1, t as createPtywrightServer, u as readScriptRunSummaryPath } from "./server-BC3yo-dq.mjs";
-import { C as isAgentManifestLike, E as writeAgentManifestPath, S as agentManifestPath, T as validateAgentManifestFiles, _ as readAgentCassettePath, a as runAgentSpecPath, b as launchAgentBrowser, c as agentRunModeSchema, d as readAgentRunRecordPath, f as writeAgentRunRecordPath, g as isAgentCassetteLike, h as resolveAgentLaunchTarget, l as formatAgentArgv, m as createAgentTemplateSpec, o as loadAgentSpec, p as formatArgv, r as replayAgentRecordPath, s as AGENT_RUN_RECORD_SCHEMA_URL, u as isAgentRunRecordLike, v as normalizeAgentFlowSpec, w as readAgentManifestPath, x as AGENT_MANIFEST_FILE_NAME, y as sanitizeArtifactName } from "./runner-zi0nItvB.mjs";
-import { c as createPtyCassetteReplay, i as formatPtyCassetteInspectLines, l as readPtyCassettePath, o as inspectPtyCassettePath, r as createPtyCassetteRecorder, t as wrapPtyLike, v as validatePtyCassette } from "./pty_like-Cpkh_O9B.mjs";
+import { a as readScriptManifestPath, c as resolveScriptManifestPath, d as resolveScriptRunSummaryPath, f as runScriptPath, i as findScriptSummaryManifest, l as validateScriptManifest, n as runAllScripts, o as relocateScriptManifestCommands, s as resolveManifestPrimaryPath$1, t as createPtywrightServer, u as readScriptRunSummaryPath } from "./server-h--2U0Ic.mjs";
+import { C as agentManifestPath, D as writeAgentManifestPath, E as validateAgentManifestFiles, S as AGENT_MANIFEST_FILE_NAME, T as readAgentManifestPath, _ as isAgentCassetteLike, a as runAgentSpecPath, b as sanitizeArtifactName, c as agentRunModeSchema, d as readAgentRunRecordPath, f as writeAgentRunRecordPath, g as normalizeAgentFlowSpecWithConfig, h as resolveAgentLaunchTarget, l as formatAgentArgv, m as createAgentTemplateSpec, o as loadAgentSpec, p as formatArgv, r as replayAgentRecordPath, s as AGENT_RUN_RECORD_SCHEMA_URL, u as isAgentRunRecordLike, v as readAgentCassettePath, w as isAgentManifestLike, x as launchAgentBrowser, y as normalizeAgentFlowSpec } from "./runner-CembqDgJ.mjs";
+import { n as loadPtywrightConfig } from "./config-B0r-JCFI.mjs";
+import { c as createPtyCassetteReplay, i as formatPtyCassetteInspectLines, l as readPtyCassettePath, o as inspectPtyCassettePath, r as createPtyCassetteRecorder, t as wrapPtyLike, v as validatePtyCassette } from "./pty_like-DqCo7XdB.mjs";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 import { z } from "zod";
 import { basename, dirname, extname, isAbsolute, join, relative, resolve } from "node:path";
@@ -1901,7 +1902,7 @@ async function promoteAgentCassette(options) {
 	const sourceCassette = readAgentCassettePath(resolveSourceCassettePath(resolve(process.cwd(), options.sourcePath)));
 	const name = sanitizeArtifactName(sourceCassette.name);
 	const cassetteDir = options.cassetteDir ?? "tests/agent-cassettes";
-	const snapshotDir = options.snapshotDir ?? join("tests", "agent-snapshots", name);
+	const snapshotDir = options.snapshotDir ?? join(options.snapshotRoot ?? "tests/agent-snapshots", name);
 	const artifactsRoot = options.artifactsRoot ?? join(".tmp", "agent-promote", name);
 	const targetDir = join(cassetteDir, name);
 	const targetCassettePath = join(targetDir, `${name}.cassette.json`);
@@ -2130,10 +2131,10 @@ function emptyReplayResult(dir, suiteDir, updateSnapshots) {
 //#endregion
 //#region src/agent/recorder.ts
 async function recordAgentSpecPath(specPath, options) {
-	return recordAgentSpec((await loadAgentSpec(specPath)).spec, options);
+	return recordAgentSpec((await loadAgentSpec(specPath)).raw, options);
 }
 async function recordAgentSpec(input, options) {
-	const spec = normalizeAgentFlowSpec(input);
+	const spec = normalizeAgentFlowSpecWithConfig(input, options.config);
 	const rootDir = options.rootDir ? resolve(process.cwd(), options.rootDir) : process.cwd();
 	const outPath = isAbsolute(options.outPath) ? options.outPath : resolve(process.cwd(), options.outPath);
 	const durationMs = options.durationMs ?? 3e4;
@@ -2923,6 +2924,7 @@ function usage() {
 		"  --json                   Print machine-readable script artifact output",
 		"",
 		"Agent options:",
+		"  --config <file>          Use a ptywright.config.* file",
 		"  --artifacts-dir <dir>    Override agent run artifact directory",
 		"  --cassette-dir <dir>     Committed cassette directory for promote/check",
 		"  --snapshot-dir <dir>     Snapshot directory for promoted cassettes",
@@ -3264,6 +3266,12 @@ function parseAgentArgs(argv) {
 			out.flavor = parseAgentFlavor(arg);
 			continue;
 		}
+		if (arg === "--config") {
+			if (!next) throw new Error(`missing <file> for --config`);
+			out.configPath = next;
+			i += 1;
+			continue;
+		}
 		if (arg === "--artifacts-root" && next) {
 			out.artifactsRoot = next;
 			i += 1;
@@ -3334,13 +3342,32 @@ function parseAgentArgs(argv) {
 		outPath: out.outPath,
 		durationMs: out.durationMs,
 		commandName: out.commandName,
+		configPath: out.configPath,
 		updateSnapshots: out.updateSnapshots,
 		headed: out.headed,
 		json: out.json
 	};
 }
+function shouldLoadAgentConfig(mode) {
+	return mode === "run" || mode === "record" || mode === "replay" || mode === "promote" || mode === "replay-all" || mode === "rerun" || mode === "check";
+}
+function resolveAgentHeadless(args, config) {
+	if (args.headed) return false;
+	return config?.agent?.defaults?.headless ?? true;
+}
+function resolveAgentConfigPath(config, path) {
+	if (!path) return void 0;
+	if (isAbsolute(path)) return path;
+	return resolve(config?.rootDir ?? process.cwd(), path);
+}
+function resolveCliPath(path) {
+	if (!path) return void 0;
+	return isAbsolute(path) ? path : resolve(process.cwd(), path);
+}
 async function cmdAgent(argv) {
 	const args = parseAgentArgs(argv);
+	const config = shouldLoadAgentConfig(args.mode) ? await loadPtywrightConfig({ configPath: args.configPath }) : void 0;
+	const headless = resolveAgentHeadless(args, config);
 	if (args.mode === "init") {
 		const spec = createAgentTemplateSpec(args.flavor ?? "generic");
 		const path = args.path;
@@ -3356,7 +3383,8 @@ async function cmdAgent(argv) {
 		const result = await recordAgentSpecPath(args.path, {
 			outPath: args.outPath,
 			durationMs: args.durationMs,
-			headless: !args.headed
+			headless,
+			config
 		});
 		logLines([
 			`${result.ok ? "ok" : "failed"} record=${result.outPath}`,
@@ -3420,13 +3448,17 @@ async function cmdAgent(argv) {
 		const argv = selected.command.argv;
 		validateAgentCommandArgv(argv, selected.name);
 		const [, , subcommand, ...rest] = argv;
-		return cmdAgent([subcommand ?? "", ...rest]);
+		return cmdAgent([
+			subcommand ?? "",
+			...rest,
+			...args.configPath ? ["--config", args.configPath] : []
+		]);
 	}
 	if (args.mode === "check") {
 		const result = await checkAgentRegression({
-			cassetteDir: args.path ?? args.cassetteDir,
-			artifactsRoot: args.artifactsRoot,
-			headless: !args.headed,
+			cassetteDir: args.path ?? args.cassetteDir ?? resolveAgentConfigPath(config, config?.agent?.cassetteDir),
+			artifactsRoot: args.artifactsRoot ?? resolveAgentConfigPath(config, config?.agent?.artifactsRoot),
+			headless,
 			updateSnapshots: args.updateSnapshots
 		});
 		if (args.json) logLines([JSON.stringify(formatAgentCheckJson(result), null, 2)], false);
@@ -3436,10 +3468,11 @@ async function cmdAgent(argv) {
 	if (args.mode === "promote") {
 		const result = await promoteAgentCassette({
 			sourcePath: args.path,
-			cassetteDir: args.cassetteDir,
+			cassetteDir: args.cassetteDir ?? resolveAgentConfigPath(config, config?.agent?.cassetteDir),
 			snapshotDir: args.snapshotDir,
-			artifactsRoot: args.artifactsRoot,
-			headless: !args.headed,
+			snapshotRoot: args.snapshotDir ? void 0 : resolveAgentConfigPath(config, config?.agent?.snapshotDir),
+			artifactsRoot: args.artifactsRoot ?? resolveAgentConfigPath(config, config?.agent?.artifactsRoot),
+			headless,
 			updateSnapshots: args.updateSnapshots
 		});
 		if (args.json) logLines([JSON.stringify(formatAgentPromoteSummary(result), null, 2)], false);
@@ -3449,8 +3482,8 @@ async function cmdAgent(argv) {
 	if (args.mode === "rerun") {
 		const rerun = await rerunAgentSummary({
 			path: args.path,
-			artifactsRoot: args.artifactsRoot,
-			headless: !args.headed,
+			artifactsRoot: args.artifactsRoot ?? resolveAgentConfigPath(config, config?.agent?.artifactsRoot),
+			headless,
 			updateSnapshots: args.updateSnapshots
 		});
 		if (rerun.kind === "check-summary") {
@@ -3480,9 +3513,9 @@ async function cmdAgent(argv) {
 	}
 	if (args.mode === "replay-all") {
 		const result = await replayAllAgentRecords({
-			dir: args.path,
-			artifactsRoot: args.artifactsRoot,
-			headless: !args.headed,
+			dir: args.path ?? resolveAgentConfigPath(config, config?.agent?.cassetteDir),
+			artifactsRoot: args.artifactsRoot ?? resolveAgentConfigPath(config, config?.agent?.artifactsRoot),
+			headless,
 			updateSnapshots: args.updateSnapshots
 		});
 		const failures = result.entries.filter((entry) => !entry.result.ok);
@@ -3507,9 +3540,10 @@ async function cmdAgent(argv) {
 		return 1;
 	}
 	const options = {
-		artifactsDir: args.artifactsDir,
+		artifactsDir: resolveCliPath(args.artifactsDir),
 		updateSnapshots: args.updateSnapshots,
-		headless: !args.headed
+		headless,
+		config
 	};
 	const result = args.mode === "run" ? await runAgentSpecPath(args.path, options) : await replayAgentRecordPath(args.path, options);
 	if (args.json) {

package/dist/cli.mjs

@@ -1,2 +1,2 @@
-import { t as main } from "./cli-CfvlbRoZ.mjs";
+import { t as main } from "./cli-C40H_ElC.mjs";
 export { main };

package/dist/config-B0r-JCFI.mjs

@@ -0,0 +1,52 @@
+import { dirname, isAbsolute, resolve } from "node:path";
+import { pathToFileURL } from "node:url";
+import { existsSync } from "node:fs";
+//#region src/config.ts
+const CONFIG_FILE_NAMES = [
+	"ptywright.config.ts",
+	"ptywright.config.mts",
+	"ptywright.config.cts",
+	"ptywright.config.js",
+	"ptywright.config.mjs",
+	"ptywright.config.cjs"
+];
+function defineConfig(config) {
+	return config;
+}
+async function loadPtywrightConfig(options = {}) {
+	const cwd = resolve(options.cwd ?? process.cwd());
+	const configPath = resolveConfigPath({
+		cwd,
+		configPath: options.configPath
+	});
+	if (!configPath) return { rootDir: cwd };
+	const mod = await import(`${pathToFileURL(configPath).href}?t=${Date.now()}`);
+	return {
+		...normalizePtywrightConfig(mod.default ?? mod.config, configPath),
+		configPath,
+		rootDir: dirname(configPath)
+	};
+}
+function resolveConfigPath(options) {
+	if (options.configPath) {
+		const explicitPath = isAbsolute(options.configPath) ? options.configPath : resolve(options.cwd, options.configPath);
+		if (!existsSync(explicitPath)) throw new Error(`ptywright config not found: ${options.configPath}`);
+		return explicitPath;
+	}
+	let current = options.cwd;
+	while (true) {
+		for (const fileName of CONFIG_FILE_NAMES) {
+			const candidate = resolve(current, fileName);
+			if (existsSync(candidate)) return candidate;
+		}
+		const parent = dirname(current);
+		if (parent === current) return;
+		current = parent;
+	}
+}
+function normalizePtywrightConfig(input, configPath) {
+	if (!input || typeof input !== "object" || Array.isArray(input)) throw new Error(`invalid ptywright config: expected object in ${configPath}`);
+	return input;
+}
+//#endregion
+export { loadPtywrightConfig as n, defineConfig as t };

package/dist/config.mjs

@@ -0,0 +1,2 @@
+import { n as loadPtywrightConfig, t as defineConfig } from "./config-B0r-JCFI.mjs";
+export { defineConfig, loadPtywrightConfig };

package/dist/index.mjs

@@ -1,4 +1,4 @@
-import { t as createPtywrightServer } from "./server-BC3yo-dq.mjs";
+import { t as createPtywrightServer } from "./server-h--2U0Ic.mjs";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 //#region src/index.ts
 const { server, sessions } = createPtywrightServer();

package/dist/mcp.mjs

@@ -1,2 +1,2 @@
-import { t as createPtywrightServer } from "./server-BC3yo-dq.mjs";
+import { t as createPtywrightServer } from "./server-h--2U0Ic.mjs";
 export { createPtywrightServer };

package/dist/pty-cassette.mjs

@@ -1,4 +1,4 @@
-import { S as dataToBytes, _ as ptyCassetteSchema, a as inspectPtyCassette, b as byteLength, c as createPtyCassetteReplay, d as PTY_CASSETTE_SCHEMA_URL, f as normalizePtyCassette, g as ptyCassetteResizeEventSchema, h as ptyCassetteExitEventSchema, i as formatPtyCassetteInspectLines, l as readPtyCassettePath, m as ptyCassetteEventSchema, n as PtyCassetteRecorder, o as inspectPtyCassettePath, p as ptyCassetteDataEventSchema, r as createPtyCassetteRecorder, s as PtyCassetteReplay, t as wrapPtyLike, u as writePtyCassettePath, v as validatePtyCassette, x as dataToBase64, y as base64ToBytes } from "./pty_like-Cpkh_O9B.mjs";
+import { S as dataToBytes, _ as ptyCassetteSchema, a as inspectPtyCassette, b as byteLength, c as createPtyCassetteReplay, d as PTY_CASSETTE_SCHEMA_URL, f as normalizePtyCassette, g as ptyCassetteResizeEventSchema, h as ptyCassetteExitEventSchema, i as formatPtyCassetteInspectLines, l as readPtyCassettePath, m as ptyCassetteEventSchema, n as PtyCassetteRecorder, o as inspectPtyCassettePath, p as ptyCassetteDataEventSchema, r as createPtyCassetteRecorder, s as PtyCassetteReplay, t as wrapPtyLike, u as writePtyCassettePath, v as validatePtyCassette, x as dataToBase64, y as base64ToBytes } from "./pty_like-DqCo7XdB.mjs";
 //#region src/pty-cassette/bun_terminal.ts
 function wrapBunTerminalOptions(options, recorder) {
 	const onData = options.data;

package/dist/{runner-zi0nItvB.mjs → runner-CembqDgJ.mjs}

@@ -624,6 +624,43 @@ function escapeHtml$1(input) {
 	return input.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;").replace(/"/g, "&quot;");
 }
 //#endregion
+//#region src/agent/config_defaults.ts
+function normalizeAgentFlowSpecWithConfig(input, config) {
+	return normalizeAgentFlowSpec(applyAgentConfigDefaults(agentFlowSpecSchema.parse(input), config));
+}
+function applyAgentConfigDefaults(input, config) {
+	const agent = config?.agent;
+	if (!agent) return input;
+	const name = sanitizeArtifactName(input.name ?? "agent-flow");
+	const configDefaults = agent.defaults ?? {};
+	const specDefaults = input.defaults ?? {};
+	const viewports = input.viewports ? void 0 : cloneViewports(configDefaults.viewports);
+	return {
+		...input,
+		artifactsDir: input.artifactsDir ?? resolveNamedDir(agent.artifactsRoot, name, config.rootDir),
+		snapshotDir: input.snapshotDir ?? resolveNamedDir(agent.snapshotDir, name, config.rootDir),
+		viewports: viewports ?? input.viewports,
+		defaults: {
+			...specDefaults,
+			timeoutMs: specDefaults.timeoutMs ?? configDefaults.timeoutMs,
+			screenshot: specDefaults.screenshot ?? configDefaults.screenshot,
+			mask: mergeMaskRules(configDefaults.mask, specDefaults.mask)
+		}
+	};
+}
+function resolveNamedDir(root, name, configRoot) {
+	if (!root) return void 0;
+	const namedDir = join(root, name);
+	return isAbsolute(namedDir) ? namedDir : resolve(configRoot, namedDir);
+}
+function cloneViewports(viewports) {
+	return Array.isArray(viewports) && viewports.length > 0 ? viewports.map((viewport) => ({ ...viewport })) : void 0;
+}
+function mergeMaskRules(configMask, specMask) {
+	const merged = [...configMask ?? [], ...specMask ?? []];
+	return merged.length > 0 ? merged : void 0;
+}
+//#endregion
 //#region src/agent/command_launch.ts
 const DEFAULT_URL_REGEX = /https?:\/\/[^\s"'<>]+/;
 function buildCommandLaunchCommand(launch, options = {}) {
@@ -1285,20 +1322,26 @@ function escapeAttribute(input) {
 //#region src/agent/spec_loader.ts
 async function loadAgentSpec(specPath) {
 	const resolved = resolve(process.cwd(), specPath);
-	if (resolved.endsWith(".json")) return {
-		spec: normalizeAgentFlowSpec(JSON.parse(readFileSync(resolved, "utf8"))),
-		path: resolved
-	};
+	if (resolved.endsWith(".json")) {
+		const raw = JSON.parse(readFileSync(resolved, "utf8"));
+		return {
+			spec: normalizeAgentFlowSpec(raw),
+			raw,
+			path: resolved
+		};
+	}
 	const mod = await import(`${pathToFileURL(resolved).href}?t=${Date.now()}`);
+	const raw = mod.default ?? mod.spec;
 	return {
-		spec: normalizeAgentFlowSpec(mod.default ?? mod.spec),
+		spec: normalizeAgentFlowSpec(raw),
+		raw,
 		path: resolved
 	};
 }
 //#endregion
 //#region src/agent/runner.ts
 async function runAgentSpecPath(specPath, options = {}) {
-	return runAgentSpec((await loadAgentSpec(specPath)).spec, options);
+	return runAgentSpec((await loadAgentSpec(specPath)).raw, options);
 }
 async function replayAgentRecordPath(recordPath, options = {}) {
 	const raw = JSON.parse(readFileSync(recordPath, "utf8"));
@@ -1311,14 +1354,20 @@ async function replayAgentRecordPath(recordPath, options = {}) {
 			artifactsDir: options.artifactsDir ?? join(dirname(recordPath), "replay")
 		});
 	}
-	if (record.spec) return runAgentSpec(record.spec, options);
+	if (record.spec) return runAgentSpec(record.spec, {
+		...options,
+		config: void 0
+	});
 	if (!record.flowPath) throw new Error(`invalid agent run record: missing replay source in ${recordPath}`);
-	return runAgentSpecPath(isAbsolute(record.flowPath) ? record.flowPath : resolve(dirname(recordPath), record.flowPath), options);
+	return runAgentSpecPath(isAbsolute(record.flowPath) ? record.flowPath : resolve(dirname(recordPath), record.flowPath), {
+		...options,
+		config: void 0
+	});
 }
 async function runAgentSpec(input, options = {}) {
 	const startedAt = Date.now();
 	const rootDir = options.rootDir ? resolve(process.cwd(), options.rootDir) : process.cwd();
-	const spec = normalizeAgentFlowSpec(input);
+	const spec = normalizeAgentFlowSpecWithConfig(input, options.replayCassette ? void 0 : options.config);
 	const name = sanitizeArtifactName(spec.name ?? "agent-flow");
 	const artifactsDir = resolve(rootDir, options.artifactsDir ?? spec.artifactsDir ?? join(".tmp", "agent", name));
 	const snapshotDir = resolve(rootDir, spec.snapshotDir ?? join("snapshots", name));
@@ -1871,4 +1920,4 @@ function defaultSpecNameForPath(path) {
 	return sanitizeArtifactName(basename(path, extname(path)));
 }
 //#endregion
-export { isAgentManifestLike as C, writeAgentManifestPath as E, agentManifestPath as S, validateAgentManifestFiles as T, readAgentCassettePath as _, runAgentSpecPath as a, launchAgentBrowser as b, agentRunModeSchema as c, readAgentRunRecordPath as d, writeAgentRunRecordPath as f, isAgentCassetteLike as g, resolveAgentLaunchTarget as h, runAgentSpec as i, formatAgentArgv as l, createAgentTemplateSpec as m, printAgentLaunchPlan as n, loadAgentSpec as o, formatArgv as p, replayAgentRecordPath as r, AGENT_RUN_RECORD_SCHEMA_URL as s, defaultSpecNameForPath as t, isAgentRunRecordLike as u, normalizeAgentFlowSpec as v, readAgentManifestPath as w, AGENT_MANIFEST_FILE_NAME as x, sanitizeArtifactName as y };
+export { agentManifestPath as C, writeAgentManifestPath as D, validateAgentManifestFiles as E, AGENT_MANIFEST_FILE_NAME as S, readAgentManifestPath as T, isAgentCassetteLike as _, runAgentSpecPath as a, sanitizeArtifactName as b, agentRunModeSchema as c, readAgentRunRecordPath as d, writeAgentRunRecordPath as f, normalizeAgentFlowSpecWithConfig as g, resolveAgentLaunchTarget as h, runAgentSpec as i, formatAgentArgv as l, createAgentTemplateSpec as m, printAgentLaunchPlan as n, loadAgentSpec as o, formatArgv as p, replayAgentRecordPath as r, AGENT_RUN_RECORD_SCHEMA_URL as s, defaultSpecNameForPath as t, isAgentRunRecordLike as u, readAgentCassettePath as v, isAgentManifestLike as w, launchAgentBrowser as x, normalizeAgentFlowSpec as y };

package/dist/{server-BC3yo-dq.mjs → server-h--2U0Ic.mjs}

@@ -2081,7 +2081,7 @@ function joinPosix(a, b) {
 }
 //#endregion
 //#region package.json
-var version = "0.3.0";
+var version = "0.4.0";
 //#endregion
 //#region src/mcp/server.ts
 const textMaskRuleSchema = z.object({

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ptywright",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "description": "Terminal/TUI automation driver over PTY + xterm, exposed as MCP tools",
   "keywords": [
     "agent",
@@ -37,6 +37,7 @@
   "exports": {
     ".": "./dist/cli.mjs",
     "./agent": "./dist/agent.mjs",
+    "./config": "./dist/config.mjs",
     "./mcp": "./dist/mcp.mjs",
     "./pty-cassette": "./dist/pty-cassette.mjs",
     "./session": "./dist/session.mjs",

package/skills/ptywright-testing/SKILL.md

@@ -1,122 +1,156 @@
 ---
 name: ptywright-testing
-description: Terminal/TUI automation and regression testing using ptywright (PTY + xterm) via CLI or MCP tools. Use when you need to (1) drive a CLI/TUI app (send keys/mouse, wait, snapshot), (2) run scripted regressions (run/run-all) and review the HTML report (index.html + run.summary.json), or (3) record an interactive MCP-driven session into a replayable script with golden checkpoints.
+description: Build, run, record, replay, debug, and maintain deterministic terminal, TUI, PTY cassette, and browser-terminal agent regression tests with ptywright. Use when an agent needs to drive CLI/TUI apps, create ptywright scripts, configure ptywright.config.*, record or replay PTY output, solidify browser terminal agent flows into non-AI snapshot tests, inspect generated artifacts, or diagnose ptywright CI failures.
 ---
 
 # Ptywright Testing
 
-Use ptywright to run deterministic CLI/TUI regression tests with readable "terminal screenshots" and a Playwright-like HTML report.
+Use ptywright when the task involves terminal or browser-terminal behavior that should be repeatable without manual inspection. Prefer stable text, DOM, and terminal snapshots over screenshots unless the user explicitly needs visual media.
 
-## Installation & Usage
+## First Decision
 
-```bash
-# 推荐：bunx 一次性运行
-bunx ptywright@latest <command>
+Choose one workflow before editing:
+
+- **Browser terminal agent regression**: Use when a web app renders a terminal and exposes `[data-terminal-root]`, or when testing integrations such as Codex/Claude/Droid wrappers. Read `references/agent-regression.md`.
+- **Raw PTY recording and replay**: Use when the user wants to capture terminal bytes from `node-pty`, Bun Terminal, `bun-pty`, or an arbitrary command, then replay them into another renderer. Read `references/raw-pty-cassettes.md`.
+- **Scripted TUI tests**: Use when testing a CLI/TUI directly through ptywright scripts, golden snapshots, and HTML reports. Read `references/script-runner.md`.
+- **MCP interactive driving or recording**: Use when an agent should interact through ptywright MCP tools or record an MCP-driven session into a script. Read `references/mcp-tools.md`.
+- **CI/debugging/artifact triage**: Use when a ptywright run failed, snapshots mismatch, a manifest is stale, or reusable commands need to be executed. Read `references/ci-and-debugging.md`.
+
+If more than one workflow applies, start with the highest-level workflow that preserves determinism. For example, for an evolving browser terminal renderer, record a raw PTY cassette first, then create a browser agent regression that replays the cassette into the renderer.
 
-# 或全局安装
-bun add -g ptywright
-ptywright <command>
+## Installation And Entry Points
 
-# 本仓库内开发
+Prefer the local project command when working inside a ptywright checkout:
+
+```bash
 bun run bin/ptywright <command>
 ```
 
-## Choose the interface
+Prefer published package commands in downstream projects:
 
-- **MCP tools**: best for agent-driven interactive flows (`launch_session`, `wait_for_text`, snapshots, recording).
-- **CLI**: best for local deterministic regressions and reviewing HTML reports.
+```bash
+bunx ptywright@latest <command>
+# or
+npx ptywright@latest <command>
+```
 
-## Start the MCP server
+Common commands:
 
 ```bash
-# stdio (default)
-bunx ptywright@latest mcp
-
-# 精简 tools（降低上下文压力）
-bunx ptywright@latest mcp --caps core
+ptywright mcp
+ptywright mcp --caps core
+ptywright run <file.json|file.ts>
+ptywright run-all --dir scripts
+ptywright agent run <flow.json> --update-snapshots
+ptywright agent check
+ptywright pty record --out tests/cassettes/session.pty.json -- <command> [args...]
+```
 
-# HTTP 模式
-bunx ptywright@latest mcp-http --port 3000
+## Project Config
+
+Use `ptywright.config.ts` for project defaults, not as a second test DSL. The flow file remains the test case.
+
+```ts
+import { defineConfig } from "ptywright/config";
+
+export default defineConfig({
+  agent: {
+    artifactsRoot: ".tmp/agent",
+    cassetteDir: "tests/agent-cassettes",
+    snapshotDir: "tests/agent-snapshots",
+    defaults: {
+      headless: true,
+      timeoutMs: 45_000,
+      screenshot: false,
+      viewports: [{ name: "desktop", width: 1280, height: 820 }],
+      mask: [{ regex: "session_[a-z0-9]+", replacement: "<session>" }],
+    },
+  },
+});
 ```
 
-Capabilities (`--caps`): `all|core|debug|script|recording` (comma separated)
+Priority rule: explicit CLI args override flow fields, and flow fields override config defaults. Config-relative paths resolve from the config file directory.
+
+## Core Invariants
 
-## Configure MCP Client
+- Keep tests deterministic: fixed terminal size, explicit waits, stable snapshots, masks for random text.
+- Prefer structured APIs and generated reusable commands over shell string reconstruction.
+- Treat `--update-snapshots` as the only intentional baseline update path.
+- Use generated manifests and summaries as durable reproduction bundles.
+- Do not hand-edit cassette, run-record, summary, or manifest command metadata unless a test explicitly asks for malformed fixture data.
+- Avoid app-specific assumptions. ptywright should integrate with any renderer through commands, URLs, DOM roots, and cassette data.
 
-**Claude Desktop / Cursor** (`~/.config/claude/claude_desktop_config.json`):
+## Minimal Examples
+
+Browser agent flow:
 
 ```json
 {
-  "mcpServers": {
-    "ptywright": {
-      "command": "bunx",
-      "args": ["ptywright@latest", "mcp"]
-    }
-  }
+  "name": "browser_terminal_smoke",
+  "launch": {
+    "mode": "command",
+    "agentFlavor": "generic",
+    "command": "node",
+    "args": ["scripts/start-browser-terminal.js", "--print-url"],
+    "waitForUrlMs": 15000
+  },
+  "steps": [
+    { "type": "waitForStableDom" },
+    { "type": "snapshot", "name": "ready", "targets": ["terminal", "dom"] }
+  ]
 }
 ```
 
-## Run scripts (deterministic regression)
-
-### Run the whole suite (preferred)
+Raw PTY cassette:
 
 ```bash
-bunx ptywright@latest run-all --dir scripts
+ptywright pty record --out tests/cassettes/codex.pty.json -- codex --yolo
+ptywright pty replay tests/cassettes/codex.pty.json --speed 0
+ptywright pty validate tests/cassettes/codex.pty.json
 ```
 
-Output to focus on:
-- `reportPath` (open in a browser)
-- `summaryPath` (`run.summary.json` for agents/CI)
-
-MCP equivalent:
-- `run_all_scripts` (defaults: `dir="scripts"`, suite report in `.tmp/run-all/`)
-- Keep MCP output small: `run_all_scripts(includeEntries="failures", maxEntries=20)`
+Script runner:
 
-### Run one script
-
-```bash
-bunx ptywright@latest run <file.json|file.ts> [--artifacts-dir <dir>]
+```json
+{
+  "name": "tui_smoke",
+  "command": ["bun", "tests/fixtures/tui_demo.ts"],
+  "cols": 80,
+  "rows": 24,
+  "steps": [
+    { "type": "waitForText", "text": "Ready" },
+    { "type": "snapshot", "kind": "text", "saveAs": "ready" }
+  ]
+}
 ```
 
-MCP: `run_script(scriptPath=...)`
-
-## Debug a failure
-
-Script runner artifacts to check (paths are returned by CLI/MCP):
-
-- `*.report.html` (timeline + snapshots)
-- `*.cast` (full playback)
-- `failure.last.view.txt` / `failure.last.txt` (last screen)
-- `failure.error.txt` (stack trace)
+## Verification Commands
 
-Tip: for flaky waits, prefer `scope="buffer"` when the content may have scrolled into scrollback.
-
-## Record an interactive flow (MCP)
-
-1) `start_script_recording(name=...)`
-2) Drive the app with normal tools:
-   - `launch_session` → `send_text` / `press_key` / `wait_for_text` / `snapshot_*`
-3) Add golden checkpoints: `mark(label=...)`
-4) Export: `stop_script_recording(recordingId=..., writeFiles=true)`
-
-## All-tools smoke (recommended)
-
-To verify ptywright MCP tool coverage without relying on external apps/network, run:
+Use the narrowest useful verification first, then broaden when editing shared behavior:
 
 ```bash
-bun test tests/mcp_all_tools_smoke.test.ts
+bun run format:check
+bun run lint
+bun test tests/agent_config.test.ts
+bun test tests/agent_rerun.test.ts
+bun run build
+bun run check
 ```
 
-This exercises `core + debug + script + recording` tools end-to-end.
+For downstream projects:
 
-## Determinism tips
-
-- Fix terminal size (`cols/rows`) and `TERM` (`xterm-256color`) in `launch_session`.
-- Use `wait_for_stable_screen` before assertions/snapshots to reduce flake.
-- Use `mask` to redact timestamps, random IDs, spinners, etc.
-- For live LLM apps: assert on stable markers/state transitions, not exact prose.
+```bash
+ptywright agent validate <artifact-or-dir>
+ptywright agent inspect <artifact-or-dir>
+ptywright agent commands <artifact-or-dir> --json
+ptywright agent exec <artifact-or-dir> --command rerun
+```
 
-## Environment knobs
+## Resource Map
 
-- `TUI_TEST_PTY_BACKEND=auto|bun-terminal|bun-pty`
-  - default `auto`: macOS/Linux prefers `bun-terminal`, Windows uses `bun-pty`
+- `references/agent-regression.md`: Browser terminal agent flows, cassettes, snapshots, promote/check/rerun, and renderer integration.
+- `references/raw-pty-cassettes.md`: Raw PTY cassette recording, replay, wrapper integration, and renderer handoff.
+- `references/script-runner.md`: JSON/TS script runner, MCP script recording, goldens, masks, and reports.
+- `references/mcp-tools.md`: MCP setup and tool selection.
+- `references/ci-and-debugging.md`: Failure triage, manifests, reusable commands, snapshot updates, and CI gates.

package/skills/ptywright-testing/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Ptywright Testing"
+  short_description: "Terminal and browser-agent regression testing"
+  default_prompt: "Use $ptywright-testing to create or debug deterministic terminal, PTY cassette, or browser-agent regression tests."

package/skills/ptywright-testing/references/agent-regression.md

@@ -0,0 +1,132 @@
+# Browser Agent Regression
+
+Use this workflow when ptywright drives a browser-hosted terminal renderer. The renderer must expose a terminal root as `[data-terminal-root]`.
+
+## Contract
+
+`launch.mode=command` is the preferred integration:
+
+- `command` and `args` start a wrapper or app process.
+- The process prints a browser URL to stdout or stderr.
+- ptywright opens that URL with Playwright.
+- The page renders the terminal under `[data-terminal-root]`.
+- Steps drive browser input and compare terminal/DOM snapshots.
+
+Use `launch.mode=url` only when the page is already running.
+
+## Flow Lifecycle
+
+1. Create a flow JSON or TS file.
+2. Run live once and write baselines:
+
+   ```bash
+   ptywright agent run tests/agents/name.flow.json --update-snapshots
+   ```
+
+3. Compare later without updating:
+
+   ```bash
+   ptywright agent run tests/agents/name.flow.json
+   ```
+
+4. Replay a run record or cassette without the live agent:
+
+   ```bash
+   ptywright agent replay .tmp/agent/name/name.agent-run.json
+   ptywright agent replay .tmp/agent/name/name.cassette.json
+   ```
+
+5. Promote a good live run into committed non-AI regression:
+
+   ```bash
+   ptywright agent promote .tmp/agent/name/name.cassette.json --update-snapshots
+   ```
+
+6. Run the committed suite:
+
+   ```bash
+   ptywright agent check
+   ptywright agent replay-all tests/agent-cassettes --update-snapshots
+   ```
+
+## Recommended Flow Shape
+
+```json
+{
+  "name": "agent_renderer_smoke",
+  "launch": {
+    "mode": "command",
+    "agentFlavor": "codex",
+    "command": "node",
+    "args": [
+      "tests/harness/browser-terminal.js",
+      "--",
+      "codex",
+      "--yolo",
+      "--print-url"
+    ],
+    "waitForUrlMs": 20000,
+    "urlRegex": "(https?://\\S+)"
+  },
+  "defaults": {
+    "timeoutMs": 45000,
+    "screenshot": false,
+    "mask": [{ "regex": "req_[a-zA-Z0-9]+", "replacement": "<request-id>" }]
+  },
+  "viewports": [{ "name": "desktop", "width": 1280, "height": 820 }],
+  "steps": [
+    { "type": "waitForStableDom", "quietMs": 600 },
+    { "type": "snapshot", "name": "launch", "targets": ["terminal", "dom"] }
+  ]
+}
+```
+
+Keep the flow generic. ptywright should not import app internals. The downstream app should provide a command or test harness that prints a browser URL and can consume replay data if needed.
+
+## Recording Browser Interactions
+
+Use `agent record` when manually exploring a browser-terminal flow:
+
+```bash
+ptywright agent record tests/agents/base.flow.json \
+  --out tests/agents/recorded.flow.json \
+  --duration-ms 60000 \
+  --headed
+```
+
+End recording by waiting for `duration-ms` to elapse or by stopping the process. The output is a normal flow JSON containing keyboard/click steps plus a final checkpoint.
+
+## Non-AI Regression Strategy
+
+For evolving agent UIs:
+
+1. Capture or create a stable PTY or browser-agent cassette.
+2. Replay that cassette into the renderer.
+3. Snapshot terminal text and DOM.
+4. Commit cassette and snapshots.
+5. Use `agent check` in CI.
+
+This lets renderer changes be verified without asking the live AI to reproduce the same answer.
+
+## Artifact Meanings
+
+- `.agent-run.json`: Per-run record with `commands.replay.argv` and `commands.updateSnapshots.argv`.
+- `.cassette.json`: Normalized flow spec plus captured terminal/DOM frames and hashes.
+- `agent-replay.summary.json`: Replay-all suite summary.
+- `agent-check.summary.json`: Committed cassette check summary.
+- `agent-promote.summary.json`: Promote operation summary.
+- `ptywright-agent.manifest.json`: Hash-indexed portable artifact bundle.
+- `index.html`: Human-readable report with snapshots and reusable commands.
+
+## Common Commands
+
+```bash
+ptywright agent inspect .tmp/agent-check
+ptywright agent validate .tmp/agent-check
+ptywright agent commands .tmp/agent-check --json
+ptywright agent exec .tmp/agent-check --command rerun
+ptywright agent exec .tmp/agent-check --command updateSnapshots
+ptywright agent rerun .tmp/agent-check/agent-check.summary.json
+```
+
+Prefer `agent exec` when an artifact already contains a reusable command. It avoids shell parsing and relocates copied manifest bundles safely.

package/skills/ptywright-testing/references/ci-and-debugging.md

@@ -0,0 +1,95 @@
+# CI And Debugging
+
+Use this guide when a ptywright command fails, CI times out, snapshots mismatch, or generated artifact commands need to be reused.
+
+## First Triage
+
+1. Read the failing command and exact artifact paths from the log.
+2. Open the HTML report if available.
+3. Inspect the generated summary JSON.
+4. Run validation on the artifact or directory.
+5. Use generated commands instead of reconstructing shell strings manually.
+
+Commands:
+
+```bash
+ptywright agent inspect <artifact-or-dir>
+ptywright agent validate <artifact-or-dir>
+ptywright agent commands <artifact-or-dir> --json
+ptywright agent commands <artifact-or-dir> --command rerun
+ptywright agent exec <artifact-or-dir> --command rerun
+ptywright agent exec <artifact-or-dir> --command updateSnapshots
+```
+
+## Snapshot Mismatches
+
+Default replay/check mode compares snapshots. Only update baselines intentionally:
+
+```bash
+ptywright agent replay-all tests/agent-cassettes --update-snapshots
+ptywright agent exec <artifact-or-dir> --command updateSnapshots
+```
+
+For script runner:
+
+```bash
+ptywright run-all --dir scripts --update-goldens
+ptywright script exec <summary-or-dir> --command updateGoldens
+```
+
+Always inspect diffs before committing updated baselines.
+
+## Portable Bundles
+
+Agent run/check/promote/replay-all outputs include `ptywright-agent.manifest.json`. A manifest bundle can be copied and still supports:
+
+```bash
+ptywright agent inspect <copied-dir>
+ptywright agent commands <copied-dir> --json
+ptywright agent exec <copied-dir> --command rerun
+ptywright agent validate <copied-dir>
+```
+
+If a directory has artifacts but no top-level manifest, use `agent validate <dir>` for recursive validation. `agent commands` and `agent exec` expect a manifest-backed command bundle for directory arguments.
+
+## Common Failure Causes
+
+- Missing `[data-terminal-root]` in browser terminal pages.
+- Flow waits on unstable AI prose instead of stable markers.
+- Snapshot baseline was not updated after an intentional UI change.
+- Random text was not masked.
+- Relative cassette or snapshot paths were moved without a manifest bundle.
+- Stored command metadata in summaries was hand-edited and no longer matches schema expectations.
+- CI is too slow for tests that run multiple full browser replays in one case.
+
+## Timeout Reduction
+
+When a test times out:
+
+- Avoid running setup and rerun paths that both do full browser replay in the same test.
+- Use summary fixtures to test command metadata or override behavior.
+- Keep one full end-to-end test per workflow and make surrounding tests narrower.
+- Use committed deterministic cassettes instead of live agents.
+- Keep test timeouts realistic but do not hide structural slowness by only increasing timeouts.
+
+## Repository Gates
+
+For ptywright itself:
+
+```bash
+bun run format:check
+bun run lint
+bun test tests/agent_rerun.test.ts
+bun test tests/agent_promote.test.ts tests/agent_commands.test.ts
+bun run build
+bun run check
+```
+
+For downstream projects:
+
+```bash
+ptywright agent check
+ptywright agent validate .tmp/agent-check
+```
+
+Use the narrowest failing test while iterating, then broaden before finalizing shared behavior.

package/skills/ptywright-testing/references/mcp-tools.md

@@ -0,0 +1,91 @@
+# MCP Tools
+
+Use MCP when an agent should interact with a live terminal session, inspect terminal state, or record an exploratory flow into a script.
+
+## Start Server
+
+```bash
+ptywright mcp
+ptywright mcp --caps core
+ptywright mcp --caps core,script,recording
+ptywright mcp-http --port 3000
+```
+
+Capabilities:
+
+- `core`: Launch sessions, send input, wait, snapshot.
+- `debug`: Extra inspection and traces.
+- `script`: Run script files and suites.
+- `recording`: Record MCP tool calls into scripts.
+- `all`: Everything.
+
+Use smaller capability sets to reduce agent context pressure.
+
+## Client Config
+
+Example for clients that use a JSON MCP server config:
+
+```json
+{
+  "mcpServers": {
+    "ptywright": {
+      "command": "bunx",
+      "args": ["ptywright@latest", "mcp", "--caps", "core,script,recording"]
+    }
+  }
+}
+```
+
+Inside this repository, use:
+
+```json
+{
+  "mcpServers": {
+    "ptywright": {
+      "command": "bun",
+      "args": ["run", "src/cli.ts", "mcp"]
+    }
+  }
+}
+```
+
+## Tool Selection
+
+Typical interactive sequence:
+
+1. `launch_session` with fixed `cols`, `rows`, and `env.TERM`.
+2. `wait_for_text` for stable startup markers.
+3. `send_text`, `press_key`, or mouse tools.
+4. `wait_for_stable_screen` before snapshots.
+5. `snapshot_text`, `snapshot_view`, or `snapshot_grid`.
+6. `close_session` when done.
+
+Prefer semantic terminal snapshots over screenshots. Use screenshots only if the task explicitly needs visual proof.
+
+## Recording
+
+Use recording when an exploratory interaction should become a repeatable test:
+
+```text
+start_script_recording
+launch_session
+send_text / press_key / wait_for_text / snapshot_text
+mark
+stop_script_recording(writeFiles=true)
+```
+
+After export, run the generated script from the CLI to ensure it is deterministic:
+
+```bash
+ptywright run <exported-script.json>
+ptywright run <exported-script.json> --update-goldens
+```
+
+## Context Control
+
+When using MCP from an LLM agent:
+
+- Avoid returning huge terminal text unless needed.
+- Prefer `includeText=false` or failure-only entries for suite tools when available.
+- Use report and summary paths for detailed inspection.
+- Use masks early if non-deterministic output appears.

package/skills/ptywright-testing/references/raw-pty-cassettes.md

@@ -0,0 +1,82 @@
+# Raw PTY Cassettes
+
+Use raw PTY cassettes when the goal is to capture terminal output once and replay it later without relaunching the original CLI, AI agent, or TUI.
+
+## CLI Recording
+
+```bash
+ptywright pty record --out tests/cassettes/session.pty.json -- <command> [args...]
+ptywright pty validate tests/cassettes/session.pty.json
+ptywright pty inspect tests/cassettes/session.pty.json
+ptywright pty replay tests/cassettes/session.pty.json --speed 0
+```
+
+Examples:
+
+```bash
+ptywright pty record --out tests/cassettes/codex-yolo.pty.json -- codex --yolo
+ptywright pty record --out tests/cassettes/browser-terminal-codex.pty.json -- \
+  node tests/harness/browser-terminal.js -- codex --yolo
+```
+
+Use `--cols`, `--rows`, `--term`, and `--backend` to stabilize output:
+
+```bash
+ptywright pty record \
+  --out tests/cassettes/session.pty.json \
+  --cols 120 \
+  --rows 32 \
+  --term xterm-256color \
+  --backend auto \
+  -- <command>
+```
+
+## Programmatic Integration
+
+Use `ptywright/pty-cassette` in projects that already control a PTY-like object.
+
+```ts
+import { wrapPtyLike } from "ptywright/pty-cassette";
+
+const recorder = wrapPtyLike(ptyProcess, {
+  path: "tests/cassettes/session.pty.json",
+  command: ["codex", "--yolo"],
+  cols: 120,
+  rows: 32,
+  term: "xterm-256color",
+});
+
+// Use recorder.process like the original ptyProcess.
+// Close/finalize according to the package API.
+```
+
+Prefer wrapper integration when a downstream project wants to keep using native `node-pty`, Bun Terminal, or `bun-pty` while still producing ptywright-compatible data.
+
+## Renderer Handoff Pattern
+
+For browser terminal renderers:
+
+1. Record raw PTY output as `*.pty.json`.
+2. Add a small local harness in the renderer project that loads this cassette and renders it into the browser terminal.
+3. Print the browser URL from that harness.
+4. Use a ptywright agent flow to open the URL and snapshot `[data-terminal-root]`.
+
+This separates byte-level reproduction from renderer-level DOM regression.
+
+## Updating Scenarios Without Duplicating Huge Sessions
+
+Avoid repeatedly recording long sessions just to test one rendering edge.
+
+Recommended patterns:
+
+- Keep small, named cassettes for specific UI states: `code-block.pty.json`, `spinner.pty.json`, `long-line.pty.json`.
+- Prefer fixture commands that emit deterministic terminal sequences for a targeted state.
+- Trim at the source by recording a shorter command or a purpose-built harness.
+- Use masks to normalize timestamps, ids, spinner ticks, and model names.
+- Store cassettes under `tests/cassettes/` and keep renderer snapshots under `tests/agent-snapshots/`.
+
+If an existing long cassette is useful but contains irrelevant frames, create a derived fixture in the app's harness rather than hand-editing hashes unless the project has a supported cassette transform.
+
+## When To Use Browser Agent Cassettes Instead
+
+Use browser agent cassettes when you need DOM snapshots, viewport coverage, or Playwright interactions. Use raw PTY cassettes when you only need terminal bytes and want broad compatibility with any PTY provider.

package/skills/ptywright-testing/references/script-runner.md

@@ -0,0 +1,80 @@
+# Script Runner
+
+Use scripts for deterministic CLI/TUI tests that do not need a browser terminal renderer.
+
+## JSON Script
+
+```json
+{
+  "$schema": "../schemas/ptywright-script.schema.json",
+  "name": "tui_smoke",
+  "command": ["bun", "tests/fixtures/tui_demo.ts"],
+  "cols": 80,
+  "rows": 24,
+  "env": { "TERM": "xterm-256color" },
+  "steps": [
+    { "type": "waitForText", "text": "Ready", "scope": "buffer" },
+    { "type": "snapshot", "kind": "text", "saveAs": "ready" },
+    { "type": "expectGolden", "name": "ready" }
+  ]
+}
+```
+
+Run it:
+
+```bash
+ptywright run scripts/tui_smoke.json
+ptywright run scripts/tui_smoke.json --update-goldens
+```
+
+Run a suite:
+
+```bash
+ptywright run-all --dir scripts
+ptywright run-all --dir scripts --update-goldens
+```
+
+## TypeScript Scripts
+
+Use TS scripts when the test needs custom data, helper functions, or custom steps. Keep business logic small. If the script gets complex, move deterministic behavior into a fixture program and keep the ptywright script declarative.
+
+## MCP Recording To Script
+
+When driving a TUI through MCP tools:
+
+1. `start_script_recording(name=...)`
+2. Use normal tools such as `launch_session`, `send_text`, `press_key`, `wait_for_text`, and `snapshot_text`.
+3. Add checkpoints with `mark(label=...)`.
+4. `stop_script_recording(recordingId=..., writeFiles=true)`.
+
+The exported script can be committed and replayed without the original agent interaction.
+
+## Reports And Artifacts
+
+Look for:
+
+- `index.html` or `*.report.html`: Timeline report.
+- `*.cast`: Playback stream.
+- `run.summary.json`: Suite/run summary.
+- `failure.last.view.txt`: Last visible terminal state.
+- `failure.last.txt`: Plain last screen.
+- `failure.error.txt`: Error details.
+
+## Snapshot Rules
+
+- Use `snapshot_text` or text snapshots for stable regression.
+- Use ANSI snapshots only when style information matters.
+- Use masks for random tokens, timestamps, ids, progress counters, and spinner glyphs.
+- Use `scope="buffer"` when content may scroll out of the viewport.
+- Use explicit waits before snapshots. Prefer `waitForText` or stable-screen waits over fixed sleeps.
+
+## CI Pattern
+
+```bash
+ptywright run-all --dir scripts
+ptywright script validate .tmp/run-all
+ptywright script commands .tmp/run-all --json
+ptywright script exec .tmp/run-all --command updateGoldens
+```
+
+Use update commands only for intentional baseline changes.