ptywright 0.1.1 → 0.3.0

package/dist/server-BC3yo-dq.mjs

@@ -0,0 +1,3068 @@
+import { a as ensureAsciinemaPlayerAssets, i as generateTraceReportHtml, o as formatSnapshotView, r as scriptSchema, s as SessionManager, t as runScript } from "./runner-zApMYWZx.mjs";
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { z } from "zod";
+import { basename, dirname, extname, isAbsolute, join, relative, resolve } from "node:path";
+import { pathToFileURL } from "node:url";
+import { existsSync, mkdirSync, readFileSync, readdirSync, statSync, writeFileSync } from "node:fs";
+import { createHash } from "node:crypto";
+import { tmpdir } from "node:os";
+//#region src/script/module.ts
+function extractStepHandlers(mod) {
+	return mod.steps ?? mod.customSteps ?? mod.stepHandlers;
+}
+async function loadScriptModule(modulePath) {
+	const mod = await import(pathToFileURL(resolve(process.cwd(), modulePath)).href);
+	const script = mod.default ?? mod.script;
+	if (!script) throw new Error(`script module must export default or 'script': ${modulePath}`);
+	return {
+		script,
+		steps: extractStepHandlers(mod)
+	};
+}
+async function loadStepHandlersModule(modulePath) {
+	const steps = extractStepHandlers(await import(pathToFileURL(resolve(process.cwd(), modulePath)).href));
+	if (!steps) throw new Error(`steps module must export 'steps' (or customSteps/stepHandlers): ${modulePath}`);
+	return { steps };
+}
+//#endregion
+//#region src/script/path.ts
+async function runScriptPath(scriptPath, options) {
+	let scriptName;
+	let artifactsDir;
+	let castPath;
+	let reportPath;
+	try {
+		const ext = extname(scriptPath).toLowerCase();
+		const baseName = basename(scriptPath, extname(scriptPath));
+		const extraSteps = options?.stepsPath ? (await loadStepHandlersModule(options.stepsPath)).steps : void 0;
+		const loaded = await loadScriptInput(scriptPath, ext);
+		const stepsFromModule = loaded.steps;
+		const mergedSteps = stepsFromModule && extraSteps ? {
+			...stepsFromModule,
+			...extraSteps
+		} : stepsFromModule ?? extraSteps;
+		const built = loaded.script;
+		const withName = built && typeof built === "object" && !Array.isArray(built) && !("name" in built) ? {
+			...built,
+			name: baseName
+		} : built;
+		const parsed = scriptSchema.parse(withName);
+		scriptName = parsed.name ?? baseName;
+		artifactsDir = resolveArtifactsDir(parsed, scriptName, options?.artifactsDir);
+		const trace = parsed.trace ?? {};
+		const saveCast = trace.saveCast ?? true;
+		const saveReport = trace.saveReport ?? true;
+		castPath = saveCast ? resolveArtifactPath(artifactsDir, trace.castPath ?? `${scriptName}.cast`) : void 0;
+		reportPath = saveReport ? resolveArtifactPath(artifactsDir, trace.reportPath ?? `${scriptName}.report.html`) : void 0;
+		try {
+			await runScript(parsed, {
+				artifactsDir,
+				updateGoldens: options?.updateGoldens,
+				steps: mergedSteps
+			});
+			return {
+				ok: true,
+				scriptName,
+				artifactsDir,
+				castPath,
+				reportPath
+			};
+		} catch (error) {
+			return {
+				ok: false,
+				error: error.message,
+				scriptName,
+				artifactsDir,
+				castPath,
+				reportPath,
+				failureArtifacts: {
+					lastTextPath: resolveArtifactPath(artifactsDir, "failure.last.txt"),
+					lastViewPath: resolveArtifactPath(artifactsDir, "failure.last.view.txt"),
+					stepPath: resolveArtifactPath(artifactsDir, "failure.step.json"),
+					errorPath: resolveArtifactPath(artifactsDir, "failure.error.txt")
+				}
+			};
+		}
+	} catch (error) {
+		return {
+			ok: false,
+			error: error.message,
+			scriptName,
+			artifactsDir,
+			castPath,
+			reportPath
+		};
+	}
+}
+async function loadScriptInput(scriptPath, ext) {
+	if (ext === ".json") {
+		const raw = await Bun.file(scriptPath).text();
+		return { script: JSON.parse(raw) };
+	}
+	const loaded = await loadScriptModule(scriptPath);
+	const script = loaded.script;
+	if (script && typeof script === "object" && "build" in script && typeof script.build === "function") return {
+		script: script.build(),
+		steps: loaded.steps
+	};
+	return {
+		script,
+		steps: loaded.steps
+	};
+}
+function resolveArtifactsDir(script, scriptName, override) {
+	if (override?.trim()) return resolve(override.trim());
+	if (script.artifactsDir?.trim()) return resolve(script.artifactsDir.trim());
+	return resolve(".tmp", "runs", scriptName);
+}
+function resolveArtifactPath(artifactsDir, path) {
+	if (isAbsolute(path)) return path;
+	return resolve(artifactsDir, path);
+}
+const SCRIPT_RUN_SUMMARY_FILE_NAME = "run.summary.json";
+const scriptCommandSchema = z.object({ argv: z.array(z.string().min(1)).min(1) }).strict();
+const scriptRunSummaryCommandsSchema = z.object({
+	runAll: scriptCommandSchema,
+	updateGoldens: scriptCommandSchema
+}).strict();
+const scriptRunFailureArtifactsSchema = z.object({
+	lastTextPath: z.string().min(1),
+	lastViewPath: z.string().min(1),
+	stepPath: z.string().min(1),
+	errorPath: z.string().min(1)
+}).strict();
+const scriptRunSummaryEntrySchema = z.object({
+	filePath: z.string().min(1),
+	filePathRel: z.string().min(1),
+	scriptName: z.string().min(1),
+	ok: z.boolean(),
+	durationMs: z.number().int().nonnegative(),
+	artifactsDir: z.string().min(1).optional(),
+	reportPath: z.string().min(1).optional(),
+	castPath: z.string().min(1).optional(),
+	error: z.string().optional(),
+	failureArtifacts: scriptRunFailureArtifactsSchema.optional()
+}).strict();
+const scriptRunSummarySchema = z.object({
+	$schema: z.string().optional(),
+	version: z.literal(1),
+	ok: z.boolean(),
+	dir: z.string().min(1),
+	suiteDir: z.string().min(1),
+	commands: scriptRunSummaryCommandsSchema,
+	totalCount: z.number().int().nonnegative(),
+	failureCount: z.number().int().nonnegative(),
+	durationMs: z.number().int().nonnegative(),
+	reportPath: z.string().min(1),
+	summaryPath: z.string().min(1),
+	entries: z.array(scriptRunSummaryEntrySchema)
+}).strict().superRefine((summary, ctx) => {
+	if (summary.totalCount !== summary.entries.length) ctx.addIssue({
+		code: z.ZodIssueCode.custom,
+		path: ["totalCount"],
+		message: "totalCount must equal entries.length"
+	});
+	const failureCount = summary.entries.filter((entry) => !entry.ok).length;
+	if (summary.failureCount !== failureCount) ctx.addIssue({
+		code: z.ZodIssueCode.custom,
+		path: ["failureCount"],
+		message: "failureCount must equal failed entries"
+	});
+	if (summary.ok !== (failureCount === 0)) ctx.addIssue({
+		code: z.ZodIssueCode.custom,
+		path: ["ok"],
+		message: "ok must be true only when failureCount is zero"
+	});
+	validateRunAllCommand(summary.commands.runAll.argv, summary, ctx);
+	if (!sameArgv$1(summary.commands.updateGoldens.argv, [...summary.commands.runAll.argv, "--update-goldens"])) ctx.addIssue({
+		code: z.ZodIssueCode.custom,
+		path: [
+			"commands",
+			"updateGoldens",
+			"argv"
+		],
+		message: "updateGoldens argv must match runAll argv plus --update-goldens"
+	});
+});
+function makeScriptRunSummaryCommands(args) {
+	const runAll = [
+		"ptywright",
+		"run-all",
+		args.dir,
+		"--artifacts-root",
+		args.suiteDir,
+		...args.stepsPath ? ["--steps", args.stepsPath] : []
+	];
+	return {
+		runAll: { argv: runAll },
+		updateGoldens: { argv: [...runAll, "--update-goldens"] }
+	};
+}
+function normalizeScriptRunSummary(input) {
+	try {
+		const parsed = scriptRunSummarySchema.parse(input);
+		return {
+			...parsed,
+			$schema: parsed.$schema ?? "https://ptywright.local/schemas/ptywright-script-run-summary.schema.json"
+		};
+	} catch (error) {
+		if (error instanceof z.ZodError) throw new Error(`invalid script run summary: ${formatZodIssues$1(error)}`);
+		throw error;
+	}
+}
+function readScriptRunSummaryPath(path) {
+	return normalizeScriptRunSummary(JSON.parse(readFileSync(resolveScriptRunSummaryPath(path), "utf8")));
+}
+function writeScriptRunSummaryPath(path, summary) {
+	mkdirSync(dirname(path), { recursive: true });
+	writeFileSync(path, JSON.stringify(normalizeScriptRunSummary(summary), null, 2) + "\n", "utf8");
+}
+function resolveScriptRunSummaryPath(path) {
+	const resolved = resolve(process.cwd(), path);
+	if (statSync(resolved, { throwIfNoEntry: false })?.isDirectory()) return join(resolved, SCRIPT_RUN_SUMMARY_FILE_NAME);
+	return resolved;
+}
+function validateRunAllCommand(argv, summary, ctx) {
+	if (argv[0] !== "ptywright" || argv[1] !== "run-all") {
+		ctx.addIssue({
+			code: z.ZodIssueCode.custom,
+			path: [
+				"commands",
+				"runAll",
+				"argv"
+			],
+			message: "runAll argv must start with ptywright run-all"
+		});
+		return;
+	}
+	if (argv[2] !== summary.dir) ctx.addIssue({
+		code: z.ZodIssueCode.custom,
+		path: [
+			"commands",
+			"runAll",
+			"argv"
+		],
+		message: "runAll argv must target summary dir"
+	});
+	const artifactsRootIndex = argv.indexOf("--artifacts-root");
+	if (artifactsRootIndex < 0 || argv[artifactsRootIndex + 1] !== summary.suiteDir) ctx.addIssue({
+		code: z.ZodIssueCode.custom,
+		path: [
+			"commands",
+			"runAll",
+			"argv"
+		],
+		message: "runAll argv must target summary suiteDir"
+	});
+}
+function sameArgv$1(left, right) {
+	return left.length === right.length && left.every((value, index) => value === right[index]);
+}
+function formatZodIssues$1(error) {
+	return error.issues.map((issue) => {
+		return `${issue.path.length ? issue.path.join(".") : "<root>"}: ${issue.message}`;
+	}).join("; ");
+}
+//#endregion
+//#region src/script/manifest.ts
+const SCRIPT_MANIFEST_SCHEMA_URL = "https://ptywright.local/schemas/ptywright-script-manifest.schema.json";
+const SCRIPT_MANIFEST_FILE_NAME = "ptywright-script.manifest.json";
+const scriptManifestFileKindSchema = z.enum([
+	"run-summary",
+	"report",
+	"cast",
+	"data",
+	"failure"
+]);
+const scriptManifestCommandSchema = z.object({ argv: z.array(z.string().min(1)).min(1) }).strict();
+const scriptManifestFileSchema = z.object({
+	path: z.string().min(1),
+	kind: scriptManifestFileKindSchema,
+	role: z.string().min(1).optional(),
+	ok: z.boolean().optional(),
+	bytes: z.number().int().nonnegative(),
+	sha256: z.string().regex(/^[a-f0-9]{64}$/)
+}).strict();
+const scriptManifestSchema = z.object({
+	$schema: z.string().optional(),
+	version: z.literal(1),
+	kind: z.literal("run-suite"),
+	ok: z.boolean(),
+	generatedAt: z.string().min(1),
+	rootDir: z.string().min(1),
+	primaryPath: z.string().min(1),
+	commands: z.record(scriptManifestCommandSchema),
+	totalCount: z.number().int().nonnegative(),
+	failureCount: z.number().int().nonnegative(),
+	files: z.array(scriptManifestFileSchema)
+}).strict().superRefine((manifest, ctx) => {
+	const seen = /* @__PURE__ */ new Set();
+	for (const file of manifest.files) {
+		if (seen.has(file.path)) ctx.addIssue({
+			code: z.ZodIssueCode.custom,
+			path: ["files"],
+			message: `duplicate manifest file path: ${file.path}`
+		});
+		seen.add(file.path);
+	}
+});
+function scriptManifestPath(rootDir) {
+	return join(rootDir, SCRIPT_MANIFEST_FILE_NAME);
+}
+function resolveScriptManifestPath(path) {
+	const resolved = resolve(process.cwd(), path);
+	if (statSync(resolved, { throwIfNoEntry: false })?.isDirectory()) return scriptManifestPath(resolved);
+	return resolved;
+}
+function createScriptManifest(options) {
+	return normalizeScriptManifest({
+		$schema: SCRIPT_MANIFEST_SCHEMA_URL,
+		version: 1,
+		kind: "run-suite",
+		ok: options.ok,
+		generatedAt: (/* @__PURE__ */ new Date()).toISOString(),
+		rootDir: options.rootDir,
+		primaryPath: options.primaryPath,
+		commands: options.commands,
+		totalCount: options.totalCount,
+		failureCount: options.failureCount,
+		files: collectManifestFiles(options.files, options.rootDir)
+	});
+}
+function writeScriptManifestPath(path, options) {
+	const manifest = createScriptManifest(options);
+	mkdirSync(dirname(path), { recursive: true });
+	writeFileSync(path, JSON.stringify(manifest, null, 2) + "\n", "utf8");
+	return manifest;
+}
+function readScriptManifestPath(path) {
+	return normalizeScriptManifest(JSON.parse(readFileSync(path, "utf8")));
+}
+function normalizeScriptManifest(input) {
+	try {
+		const parsed = scriptManifestSchema.parse(input);
+		return {
+			...parsed,
+			$schema: parsed.$schema ?? "https://ptywright.local/schemas/ptywright-script-manifest.schema.json"
+		};
+	} catch (error) {
+		if (error instanceof z.ZodError) throw new Error(`invalid script manifest: ${formatZodIssues(error)}`);
+		throw error;
+	}
+}
+function validateScriptManifest(manifest, manifestPath) {
+	validateScriptManifestFiles(manifest, manifestPath);
+	validateScriptManifestCommands(manifest, manifestPath);
+}
+function validateScriptManifestFiles(manifest, manifestPath) {
+	const failures = [];
+	const baseDir = manifestPath ? dirname(resolve(process.cwd(), manifestPath)) : resolve(process.cwd(), manifest.rootDir);
+	for (const file of manifest.files) {
+		let current = null;
+		try {
+			current = readManifestFile(file, baseDir);
+		} catch (error) {
+			failures.push(`${file.path}: ${error instanceof Error ? error.message : String(error)}`);
+			continue;
+		}
+		if (current.bytes !== file.bytes) failures.push(`${file.path}: bytes ${current.bytes} !== ${file.bytes}`);
+		if (current.sha256 !== file.sha256) failures.push(`${file.path}: sha256 ${current.sha256} !== ${file.sha256}`);
+	}
+	if (failures.length > 0) throw new Error(`invalid script manifest files: ${failures.join("; ")}`);
+}
+function validateScriptManifestCommands(manifest, manifestPath) {
+	const failures = [];
+	const summaryPath = resolveManifestPrimaryPath(manifest, manifestPath);
+	try {
+		const summary = readScriptRunSummaryPath(summaryPath);
+		compareCommandMaps(manifest.commands, summary.commands, failures);
+	} catch (error) {
+		failures.push(`unable to read manifest primary summary ${summaryPath}: ${error instanceof Error ? error.message : String(error)}`);
+	}
+	if (failures.length > 0) throw new Error(`invalid script manifest commands: ${failures.join("; ")}`);
+}
+function findScriptSummaryManifest(summaryPath) {
+	const resolvedSummaryPath = resolve(process.cwd(), summaryPath);
+	const manifestPath = scriptManifestPath(dirname(resolvedSummaryPath));
+	if (!existsSync(manifestPath)) return null;
+	let manifest;
+	try {
+		manifest = readScriptManifestPath(manifestPath);
+	} catch {
+		return null;
+	}
+	if (samePath(resolveManifestPrimaryPath(manifest, manifestPath), resolvedSummaryPath)) return {
+		manifest,
+		manifestPath
+	};
+	return null;
+}
+function relocateScriptManifestCommands(manifest, manifestPath) {
+	return Object.fromEntries(Object.entries(manifest.commands).map(([name, command]) => [name, { argv: relocateScriptCommandArgv(command.argv, dirname(resolve(process.cwd(), manifestPath))) }]));
+}
+function resolveManifestPrimaryPath(manifest, manifestPath) {
+	const baseDir = manifestPath ? dirname(resolve(process.cwd(), manifestPath)) : resolve(process.cwd(), manifest.rootDir);
+	const primaryFile = manifest.files.find((file) => file.kind === "run-summary" && file.role === "summary") ?? manifest.files.find((file) => file.kind === "run-summary");
+	if (primaryFile) return isAbsolute(primaryFile.path) ? primaryFile.path : join(baseDir, primaryFile.path);
+	return isAbsolute(manifest.primaryPath) ? manifest.primaryPath : resolve(process.cwd(), manifest.primaryPath);
+}
+function collectManifestFiles(files, rootDir) {
+	const out = [];
+	const seen = /* @__PURE__ */ new Set();
+	const rootAbs = resolve(process.cwd(), rootDir);
+	for (const file of files) {
+		if (!file.path || seen.has(file.path)) continue;
+		seen.add(file.path);
+		try {
+			out.push(readManifestFile(file, rootAbs, { portableRoot: true }));
+		} catch {}
+	}
+	return out.sort((a, b) => a.path.localeCompare(b.path));
+}
+function readManifestFile(file, baseDir, options = {}) {
+	if (!file.path) throw new Error("missing file path");
+	const absPath = isAbsolute(file.path) ? file.path : resolve(options.portableRoot ? process.cwd() : baseDir, file.path);
+	if (!statSync(absPath).isFile()) throw new Error("not a file");
+	const bytes = readFileSync(absPath);
+	return {
+		path: options.portableRoot ? portableManifestPath(absPath, baseDir) : file.path,
+		kind: file.kind,
+		role: file.role,
+		ok: file.ok,
+		bytes: bytes.byteLength,
+		sha256: createHash("sha256").update(bytes).digest("hex")
+	};
+}
+function relocateScriptCommandArgv(argv, rootDir) {
+	if (argv[0] !== "ptywright" || argv[1] !== "run-all") return [...argv];
+	return setArgvFlag([...argv], "--artifacts-root", portableCliPath(rootDir));
+}
+function setArgvFlag(argv, flag, value) {
+	const index = argv.indexOf(flag);
+	if (index >= 0) return [
+		...argv.slice(0, index + 1),
+		value,
+		...argv.slice(index + 2)
+	];
+	return [
+		...argv,
+		flag,
+		value
+	];
+}
+function compareCommandMaps(actual, expected, failures) {
+	const actualNames = Object.keys(actual).sort();
+	const expectedNames = Object.keys(expected).sort();
+	if (!sameStringList(actualNames, expectedNames)) failures.push(`manifest command names must match primary summary commands: ${expectedNames.join(",")}`);
+	for (const [name, command] of Object.entries(expected)) {
+		const actualCommand = actual[name];
+		if (!actualCommand) continue;
+		if (!sameArgv(actualCommand.argv, command.argv)) failures.push(`command ${name} argv must match primary summary`);
+	}
+}
+function portableManifestPath(absPath, rootAbs) {
+	const rel = relative(rootAbs, absPath);
+	if (rel && !rel.startsWith("..") && !isAbsolute(rel)) return rel;
+	return absPath;
+}
+function portableCliPath(path) {
+	const abs = resolve(process.cwd(), path);
+	const rel = relative(process.cwd(), abs);
+	if (rel && !rel.startsWith("..") && !isAbsolute(rel)) return rel;
+	return abs;
+}
+function sameArgv(left, right) {
+	return left.length === right.length && left.every((value, index) => value === right[index]);
+}
+function sameStringList(left, right) {
+	return left.length === right.length && left.every((value, index) => value === right[index]);
+}
+function samePath(left, right) {
+	return resolve(process.cwd(), left) === resolve(process.cwd(), right);
+}
+function formatZodIssues(error) {
+	return error.issues.map((issue) => {
+		return `${issue.path.length ? issue.path.join(".") : "<root>"}: ${issue.message}`;
+	}).join("; ");
+}
+//#endregion
+//#region src/script/suite_report.ts
+function writeSuiteReportArtifacts(args) {
+	mkdirSync(args.suiteDir, { recursive: true });
+	const reportPath = join(args.suiteDir, "index.html");
+	const summaryPath = join(args.suiteDir, "run.summary.json");
+	const failures = args.entries.filter((e) => !e.result.ok);
+	const summary = {
+		version: 1,
+		ok: failures.length === 0,
+		dir: args.dir,
+		suiteDir: args.suiteDir,
+		commands: makeScriptRunSummaryCommands(args),
+		totalCount: args.entries.length,
+		failureCount: failures.length,
+		durationMs: args.durationMs,
+		reportPath,
+		summaryPath,
+		entries: args.entries.map((entry) => {
+			const filePathRel = normalizePath(relative(process.cwd(), entry.filePath));
+			const scriptName = entry.result.scriptName ?? basename(entry.filePath).replace(/\.(json|ts)$/i, "");
+			const common = {
+				filePath: entry.filePath,
+				filePathRel,
+				scriptName,
+				ok: entry.result.ok,
+				durationMs: entry.durationMs,
+				artifactsDir: entry.result.artifactsDir,
+				reportPath: entry.result.reportPath,
+				castPath: entry.result.castPath
+			};
+			if (entry.result.ok) return common;
+			return {
+				...common,
+				ok: false,
+				error: entry.result.error,
+				failureArtifacts: entry.result.failureArtifacts
+			};
+		})
+	};
+	writeScriptRunSummaryPath(summaryPath, summary);
+	writeFileSync(reportPath, renderSuiteReportHtml({
+		reportPath,
+		summaryPath,
+		summary
+	}), "utf8");
+	writeSuiteManifest({
+		suiteDir: args.suiteDir,
+		summary
+	});
+	return {
+		reportPath,
+		summaryPath
+	};
+}
+function writeSuiteManifest(args) {
+	writeScriptManifestPath(scriptManifestPath(args.suiteDir), {
+		ok: args.summary.ok,
+		rootDir: args.suiteDir,
+		primaryPath: args.summary.summaryPath,
+		commands: args.summary.commands,
+		totalCount: args.summary.totalCount,
+		failureCount: args.summary.failureCount,
+		files: [
+			{
+				path: args.summary.summaryPath,
+				kind: "run-summary",
+				role: "summary",
+				ok: args.summary.ok
+			},
+			{
+				path: args.summary.reportPath,
+				kind: "report",
+				role: "suite-report",
+				ok: args.summary.ok
+			},
+			...args.summary.entries.flatMap((entry) => [
+				{
+					path: entry.reportPath,
+					kind: "report",
+					role: "entry-report",
+					ok: entry.ok
+				},
+				{
+					path: entry.castPath,
+					kind: "cast",
+					role: "cast",
+					ok: entry.ok
+				},
+				{
+					path: entry.artifactsDir ? join(entry.artifactsDir, "test.data.js") : void 0,
+					kind: "data",
+					role: "test-data",
+					ok: entry.ok
+				},
+				...!entry.ok && entry.failureArtifacts ? [
+					{
+						path: entry.failureArtifacts.lastTextPath,
+						kind: "failure",
+						role: "last-text",
+						ok: false
+					},
+					{
+						path: entry.failureArtifacts.lastViewPath,
+						kind: "failure",
+						role: "last-view",
+						ok: false
+					},
+					{
+						path: entry.failureArtifacts.stepPath,
+						kind: "failure",
+						role: "step",
+						ok: false
+					},
+					{
+						path: entry.failureArtifacts.errorPath,
+						kind: "failure",
+						role: "error",
+						ok: false
+					}
+				] : []
+			])
+		]
+	});
+}
+function renderSuiteReportHtml(args) {
+	const title = "ptywright script report";
+	const resultLabel = args.summary.ok ? "PASS" : "FAIL";
+	const resultClass = args.summary.ok ? "pass" : "fail";
+	const summaryHref = relativeHref(args.reportPath, args.summaryPath);
+	const uiData = {
+		version: 1,
+		summary: {
+			ok: args.summary.ok,
+			dir: args.summary.dir,
+			suiteDir: args.summary.suiteDir,
+			totalCount: args.summary.totalCount,
+			failureCount: args.summary.failureCount,
+			durationMs: args.summary.durationMs,
+			summaryHref
+		},
+		entries: args.summary.entries.map((entry) => {
+			const reportHref = entry.reportPath ? relativeHref(args.reportPath, entry.reportPath) : null;
+			const castHref = entry.castPath ? relativeHref(args.reportPath, entry.castPath) : null;
+			const playHref = reportHref ? `${reportHref}#cast-playback` : null;
+			const lastHref = !entry.ok && entry.failureArtifacts?.lastViewPath ? relativeHref(args.reportPath, entry.failureArtifacts.lastViewPath) : null;
+			const errorHref = !entry.ok && entry.failureArtifacts?.errorPath ? relativeHref(args.reportPath, entry.failureArtifacts.errorPath) : null;
+			const dataKey = entry.artifactsDir ? basename(entry.artifactsDir) : null;
+			const dataHref = entry.artifactsDir && dataKey ? relativeHref(args.reportPath, join(entry.artifactsDir, "test.data.js")) : null;
+			return {
+				id: entry.filePathRel,
+				ok: entry.ok,
+				scriptName: entry.scriptName,
+				filePathRel: entry.filePathRel,
+				durationMs: entry.durationMs,
+				error: entry.ok ? null : entry.error ?? null,
+				artifactsDir: entry.artifactsDir ?? null,
+				dataKey,
+				hrefs: {
+					report: reportHref,
+					play: playHref,
+					cast: castHref,
+					last: lastHref,
+					error: errorHref,
+					data: dataHref
+				}
+			};
+		})
+	};
+	return `<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="utf-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1" />
+    <title>${escapeHtml(title)}</title>
+    <style>
+      :root {
+        color-scheme: light dark;
+      }
+      body {
+        margin: 0;
+        font-family: ui-sans-serif, system-ui, -apple-system, Segoe UI, Roboto,
+          Helvetica, Arial, "Apple Color Emoji", "Segoe UI Emoji";
+        line-height: 1.4;
+      }
+      a {
+        color: inherit;
+      }
+      header {
+        padding: 16px;
+        border-bottom: 1px solid color-mix(in oklab, currentColor 20%, transparent);
+      }
+      header h1 {
+        margin: 0 0 8px 0;
+        font-size: 18px;
+      }
+      header .badges {
+        display: flex;
+        gap: 8px;
+        flex-wrap: wrap;
+        margin: 6px 0 10px 0;
+      }
+      .badge {
+        display: inline-flex;
+        align-items: center;
+        border-radius: 999px;
+        padding: 2px 10px;
+        font-size: 12px;
+        border: 1px solid color-mix(in oklab, currentColor 16%, transparent);
+        background: color-mix(in oklab, currentColor 6%, transparent);
+      }
+      .badge.pass {
+        background: color-mix(in oklab, #16a34a 18%, transparent);
+        border-color: color-mix(in oklab, #16a34a 45%, transparent);
+      }
+      .badge.fail {
+        background: color-mix(in oklab, #ef4444 18%, transparent);
+        border-color: color-mix(in oklab, #ef4444 45%, transparent);
+      }
+      header .meta {
+        font-family: ui-monospace, SFMono-Regular, Menlo, Monaco, Consolas,
+          "Liberation Mono", "Courier New", monospace;
+        font-size: 12px;
+        opacity: 0.8;
+        white-space: pre-wrap;
+      }
+      main {
+        display: grid;
+        grid-template-columns: 360px 1fr;
+        min-height: calc(100vh - 110px);
+      }
+      aside {
+        border-right: 1px solid color-mix(in oklab, currentColor 14%, transparent);
+        padding: 12px;
+      }
+      section {
+        padding: 16px;
+      }
+      .controls {
+        display: flex;
+        gap: 8px;
+        flex-wrap: wrap;
+        align-items: center;
+        margin-bottom: 10px;
+      }
+      .input {
+        width: 100%;
+        box-sizing: border-box;
+        padding: 8px 10px;
+        border-radius: 10px;
+        border: 1px solid color-mix(in oklab, currentColor 16%, transparent);
+        background: color-mix(in oklab, currentColor 4%, transparent);
+        color: inherit;
+      }
+      .chip {
+        cursor: pointer;
+        user-select: none;
+      }
+      .chip[aria-pressed="true"] {
+        background: color-mix(in oklab, #0ea5e9 18%, transparent);
+        border-color: color-mix(in oklab, #0ea5e9 45%, transparent);
+      }
+      .list {
+        list-style: none;
+        padding: 0;
+        margin: 0;
+        display: flex;
+        flex-direction: column;
+        gap: 6px;
+      }
+      .item {
+        border: 1px solid color-mix(in oklab, currentColor 14%, transparent);
+        border-radius: 12px;
+        padding: 10px;
+        cursor: pointer;
+        background: color-mix(in oklab, currentColor 2%, transparent);
+      }
+      .item:hover {
+        background: color-mix(in oklab, currentColor 6%, transparent);
+      }
+      .item[aria-selected="true"] {
+        border-color: color-mix(in oklab, #0ea5e9 55%, transparent);
+        background: color-mix(in oklab, #0ea5e9 10%, transparent);
+      }
+      .item .top {
+        display: flex;
+        gap: 8px;
+        align-items: center;
+      }
+      .item .name {
+        font-weight: 600;
+        overflow: hidden;
+        text-overflow: ellipsis;
+        white-space: nowrap;
+      }
+      .item .sub {
+        margin-top: 6px;
+        display: flex;
+        gap: 8px;
+        flex-wrap: wrap;
+        font-family: ui-monospace, SFMono-Regular, Menlo, Monaco, Consolas,
+          "Liberation Mono", "Courier New", monospace;
+        font-size: 12px;
+        opacity: 0.8;
+      }
+      .mono {
+        font-family: ui-monospace, SFMono-Regular, Menlo, Monaco, Consolas,
+          "Liberation Mono", "Courier New", monospace;
+        font-size: 12px;
+      }
+      .error {
+        color: color-mix(in oklab, #ef4444 70%, currentColor);
+      }
+      .kv {
+        display: grid;
+        grid-template-columns: 110px 1fr;
+        gap: 8px 12px;
+        margin-top: 12px;
+      }
+      .kv .k {
+        opacity: 0.75;
+      }
+      .links {
+        display: flex;
+        gap: 10px;
+        flex-wrap: wrap;
+        margin-top: 10px;
+      }
+      .muted {
+        opacity: 0.75;
+      }
+      @media (max-width: 920px) {
+        main {
+          grid-template-columns: 1fr;
+        }
+        aside {
+          border-right: none;
+          border-bottom: 1px solid color-mix(in oklab, currentColor 14%, transparent);
+        }
+      }
+    </style>
+  </head>
+  <body>
+    <header>
+      <h1>${escapeHtml(title)}</h1>
+      <div class="badges">
+        <span class="badge ${resultClass}">result=${escapeHtml(resultLabel)}</span>
+        <span class="badge">count=${args.summary.totalCount}</span>
+        <span class="badge">failures=${args.summary.failureCount}</span>
+        <span class="badge">duration=${escapeHtml(formatDuration(args.summary.durationMs))}</span>
+      </div>
+      <div class="meta">dir=${escapeHtml(args.summary.dir)}
+summary=<a href="${escapeHtml(summaryHref)}">run.summary.json</a></div>
+    </header>
+    <main>
+      <aside>
+        <div class="controls">
+          <input id="search" class="input mono" placeholder="Search…" autocomplete="off" />
+          <button id="filterAll" class="badge chip" type="button" aria-pressed="true">all</button>
+          <button id="filterPass" class="badge chip pass" type="button" aria-pressed="false">pass</button>
+          <button id="filterFail" class="badge chip fail" type="button" aria-pressed="false">fail</button>
+          <span id="visibleCount" class="badge">visible=0</span>
+        </div>
+        <ol id="list" class="list"></ol>
+      </aside>
+      <section>
+        <div id="details">
+          <div class="muted">Select a test from the left.</div>
+        </div>
+      </section>
+    </main>
+    <script id="suiteData" type="application/json">${jsonForHtml(uiData)}<\/script>
+    <script>
+      (function () {
+        const dataEl = document.getElementById("suiteData");
+        const listEl = document.getElementById("list");
+        const detailsEl = document.getElementById("details");
+        const searchEl = document.getElementById("search");
+        const visibleCountEl = document.getElementById("visibleCount");
+        const filterAllEl = document.getElementById("filterAll");
+        const filterPassEl = document.getElementById("filterPass");
+        const filterFailEl = document.getElementById("filterFail");
+        if (!dataEl || !listEl || !detailsEl || !searchEl) return;
+
+        /** @type {{entries: any[]}} */
+        const raw = JSON.parse(dataEl.textContent || "{}");
+        const entries = Array.isArray(raw.entries) ? raw.entries : [];
+        let filter = "all";
+        let selectedId = null;
+        const dataLoaders = Object.create(null);
+
+        function setPressed(el, on) {
+          el.setAttribute("aria-pressed", on ? "true" : "false");
+        }
+
+        function applyFilter() {
+          const q = (searchEl.value || "").trim().toLowerCase();
+          const out = [];
+          for (const e of entries) {
+            if (!e) continue;
+            if (filter === "pass" && !e.ok) continue;
+            if (filter === "fail" && e.ok) continue;
+            if (q) {
+              const hay = (e.scriptName + " " + e.filePathRel).toLowerCase();
+              if (!hay.includes(q)) continue;
+            }
+            out.push(e);
+          }
+          renderList(out);
+          if (visibleCountEl) visibleCountEl.textContent = "visible=" + out.length;
+        }
+
+        function renderList(items) {
+          listEl.textContent = "";
+          for (const e of items) {
+            const li = document.createElement("li");
+            li.className = "item";
+            li.setAttribute("role", "option");
+            li.dataset.id = e.id;
+            li.setAttribute("aria-selected", e.id === selectedId ? "true" : "false");
+
+            const top = document.createElement("div");
+            top.className = "top";
+            const badge = document.createElement("span");
+            badge.className = "badge " + (e.ok ? "pass" : "fail");
+            badge.textContent = e.ok ? "PASS" : "FAIL";
+            const name = document.createElement("div");
+            name.className = "name";
+            name.textContent = e.scriptName;
+            top.appendChild(badge);
+            top.appendChild(name);
+
+            const sub = document.createElement("div");
+            sub.className = "sub";
+            const file = document.createElement("span");
+            file.textContent = e.filePathRel;
+            const dur = document.createElement("span");
+            dur.textContent = "dur=" + (e.durationMs < 1000 ? e.durationMs + "ms" : (e.durationMs / 1000).toFixed(2) + "s");
+            sub.appendChild(file);
+            sub.appendChild(dur);
+
+            li.appendChild(top);
+            li.appendChild(sub);
+            li.addEventListener("click", function () {
+              selectedId = e.id;
+              applyFilter();
+              renderDetails(e);
+            });
+            listEl.appendChild(li);
+          }
+        }
+
+        function linkHtml(href, label) {
+          if (!href) return "";
+          return '<a class="mono" href="' + href.replaceAll('"', "&quot;") + '">' + label + "</a>";
+        }
+
+        function escapeText(s) {
+          return (s || "")
+            .replaceAll("&", "&amp;")
+            .replaceAll("<", "&lt;")
+            .replaceAll(">", "&gt;");
+        }
+
+        function getTestData(e) {
+          const store = globalThis.__ptywright && globalThis.__ptywright.tests;
+          if (!store || !e || !e.dataKey) return null;
+          return store[e.dataKey] || null;
+        }
+
+        function ensureTestDataLoaded(e, cb) {
+          if (!e || !e.hrefs || !e.hrefs.data || !e.dataKey) return cb(null);
+          const existing = getTestData(e);
+          if (existing) return cb(existing);
+
+          if (dataLoaders[e.dataKey]) {
+            dataLoaders[e.dataKey].push(cb);
+            return;
+          }
+          dataLoaders[e.dataKey] = [cb];
+
+          const script = document.createElement("script");
+          script.src = e.hrefs.data;
+          script.async = true;
+          script.onload = function () {
+            const loaded = getTestData(e);
+            const cbs = dataLoaders[e.dataKey] || [];
+            delete dataLoaders[e.dataKey];
+            for (const fn of cbs) fn(loaded);
+          };
+          script.onerror = function () {
+            const cbs = dataLoaders[e.dataKey] || [];
+            delete dataLoaders[e.dataKey];
+            for (const fn of cbs) fn(null);
+          };
+          document.head.appendChild(script);
+        }
+
+        function renderDetails(e) {
+          const links = [
+            linkHtml(e.hrefs && e.hrefs.report, "report"),
+            linkHtml(e.hrefs && e.hrefs.play, "play"),
+            linkHtml(e.hrefs && e.hrefs.cast, "cast"),
+            linkHtml(e.hrefs && e.hrefs.last, "last"),
+            linkHtml(e.hrefs && e.hrefs.error, "error"),
+          ].filter(Boolean);
+
+          const data = getTestData(e);
+          const stepsHtml = (() => {
+            if (data && Array.isArray(data.steps)) {
+              const rows = data.steps
+                .map(function (s) {
+                  const badge = '<span class="badge ' + (s.ok ? "pass" : "fail") + '">' + (s.ok ? "PASS" : "FAIL") + "</span>";
+                  const dur = typeof s.durationMs === "number"
+                    ? (s.durationMs < 1000 ? s.durationMs + "ms" : (s.durationMs / 1000).toFixed(2) + "s")
+                    : "";
+                  const err = !s.ok && s.error ? '<div class="mono error" style="margin-top: 4px;">' + escapeText(s.error) + "</div>" : "";
+                  return '<div class="item" style="cursor: default;">' +
+                    '<div class="top">' + badge +
+                    '<div class="name mono" style="font-weight: 600;">' + escapeText(s.label || s.type || "") + "</div>" +
+                    "</div>" +
+                    '<div class="sub"><span>step=' + escapeText(String(s.index)) + "</span><span>dur=" + escapeText(dur) + "</span></div>" +
+                    err +
+                    "</div>";
+                })
+                .join("");
+              return '<h3 style="margin: 16px 0 8px 0;">Steps</h3>' +
+                '<div class="muted mono">count=' + escapeText(String(data.stepCount || data.steps.length)) + "</div>" +
+                '<div style="margin-top: 10px; display: flex; flex-direction: column; gap: 8px;">' + rows + "</div>";
+            }
+
+            if (e.hrefs && e.hrefs.data && e.dataKey) {
+              return '<h3 style="margin: 16px 0 8px 0;">Steps</h3>' +
+                '<div class="muted">Step details are available. Click to load.</div>' +
+                '<div style="margin-top: 10px;">' +
+                  '<button id="loadSteps" class="badge chip" type="button">load steps</button>' +
+                "</div>";
+            }
+
+            return "";
+          })();
+
+          detailsEl.innerHTML =
+            '<div class="badges">' +
+              '<span class="badge ' + (e.ok ? "pass" : "fail") + '">status=' + (e.ok ? "PASS" : "FAIL") + "</span>" +
+              '<span class="badge">duration=' + (e.durationMs < 1000 ? e.durationMs + "ms" : (e.durationMs / 1000).toFixed(2) + "s") + "</span>" +
+            "</div>" +
+            '<h2 style="margin: 10px 0 6px 0;">' + escapeText(e.scriptName) + "</h2>" +
+            '<div class="kv mono">' +
+              '<div class="k">file</div><div class="v">' + escapeText(e.filePathRel) + "</div>" +
+              '<div class="k">artifacts</div><div class="v">' +
+                (e.artifactsDir
+                  ? escapeText(e.artifactsDir)
+                  : '<span class="muted">(none)</span>') +
+              "</div>" +
+            "</div>" +
+            (links.length ? '<div class="links">' + links.join(" ") + "</div>" : "") +
+            (!e.ok && e.error ? '<pre class="mono error" style="margin-top: 12px; white-space: pre-wrap;">' + escapeText(e.error) + "</pre>" : "") +
+            stepsHtml;
+
+          const loadBtn = document.getElementById("loadSteps");
+          if (loadBtn) {
+            loadBtn.addEventListener("click", function () {
+              ensureTestDataLoaded(e, function () {
+                renderDetails(e);
+              });
+            });
+          }
+        }
+
+        filterAllEl.addEventListener("click", function () {
+          filter = "all";
+          setPressed(filterAllEl, true);
+          setPressed(filterPassEl, false);
+          setPressed(filterFailEl, false);
+          applyFilter();
+        });
+        filterPassEl.addEventListener("click", function () {
+          filter = "pass";
+          setPressed(filterAllEl, false);
+          setPressed(filterPassEl, true);
+          setPressed(filterFailEl, false);
+          applyFilter();
+        });
+        filterFailEl.addEventListener("click", function () {
+          filter = "fail";
+          setPressed(filterAllEl, false);
+          setPressed(filterPassEl, false);
+          setPressed(filterFailEl, true);
+          applyFilter();
+        });
+        searchEl.addEventListener("input", applyFilter);
+
+        applyFilter();
+        if (entries[0]) {
+          selectedId = entries[0].id;
+          renderDetails(entries[0]);
+          applyFilter();
+        }
+      })();
+    <\/script>
+  </body>
+</html>`;
+}
+function jsonForHtml(data) {
+	return JSON.stringify(data).replaceAll("<", "\\u003c");
+}
+function formatDuration(ms) {
+	const safe = Math.max(0, Math.trunc(ms));
+	if (safe < 1e3) return `${safe}ms`;
+	return `${(safe / 1e3).toFixed(2)}s`;
+}
+function relativeHref(fromFile, toFile) {
+	const normalized = normalizePath(relative(dirname(fromFile), toFile));
+	return normalized.startsWith(".") ? normalized : `./${normalized}`;
+}
+function normalizePath(path) {
+	return path.replace(/\\/g, "/");
+}
+function escapeHtml(text) {
+	return text.replaceAll("&", "&amp;").replaceAll("<", "&lt;").replaceAll(">", "&gt;").replaceAll("\"", "&quot;").replaceAll("'", "&#39;");
+}
+//#endregion
+//#region src/script/run_all.ts
+async function runAllScripts(options) {
+	const dir = resolve(options?.dir?.trim() ? options.dir.trim() : "scripts");
+	const artifactsRoot = options?.artifactsRoot?.trim() ? resolve(options.artifactsRoot.trim()) : null;
+	const stepsPath = options?.stepsPath?.trim() ? options.stepsPath.trim() : void 0;
+	const suiteDir = artifactsRoot ?? resolve(".tmp", "run-all");
+	const filePaths = listScriptFiles(dir);
+	const entries = [];
+	const startedAt = Date.now();
+	for (const filePath of filePaths) {
+		const artifactsDir = join(suiteDir, "tests", safeArtifactsDirName(relative(dir, filePath)));
+		const entryStartedAt = Date.now();
+		const result = await runScriptPath(filePath, {
+			artifactsDir,
+			stepsPath,
+			updateGoldens: options?.updateGoldens
+		});
+		const durationMs = Date.now() - entryStartedAt;
+		entries.push({
+			filePath,
+			durationMs,
+			result
+		});
+	}
+	const durationMs = Date.now() - startedAt;
+	const { reportPath, summaryPath } = writeSuiteReportArtifacts({
+		dir,
+		suiteDir,
+		stepsPath,
+		durationMs,
+		entries
+	});
+	return {
+		ok: entries.every((e) => e.result.ok),
+		dir,
+		suiteDir,
+		durationMs,
+		reportPath,
+		summaryPath,
+		entries
+	};
+}
+function safeArtifactsDirName(relPath) {
+	return relPath.replace(/[/\\]/g, "__");
+}
+function shouldIncludeJsonScript(filePath) {
+	try {
+		const raw = readFileSync(filePath, "utf8");
+		const parsed = JSON.parse(raw);
+		if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) return false;
+		const obj = parsed;
+		if (!obj.launch || typeof obj.launch !== "object" || Array.isArray(obj.launch)) return false;
+		const launch = obj.launch;
+		if (typeof launch.command !== "string" || !launch.command.trim()) return false;
+		return Array.isArray(obj.steps) && obj.steps.length > 0;
+	} catch {
+		return true;
+	}
+}
+function listScriptFiles(dir) {
+	const out = [];
+	for (const entry of readdirSync(dir)) {
+		const abs = join(dir, entry);
+		if (statSync(abs).isDirectory()) {
+			out.push(...listScriptFiles(abs));
+			continue;
+		}
+		if (entry.endsWith(".json")) {
+			if (shouldIncludeJsonScript(abs)) out.push(abs);
+			continue;
+		}
+		if (!entry.endsWith(".ts")) continue;
+		if (entry.endsWith(".d.ts")) continue;
+		if (entry.endsWith("_steps.ts") || entry.endsWith(".steps.ts")) continue;
+		out.push(abs);
+	}
+	return out.sort((a, b) => a.localeCompare(b));
+}
+function parseArgs(argv) {
+	const out = { updateGoldens: false };
+	for (let i = 0; i < argv.length; i += 1) {
+		const arg = argv[i];
+		const next = argv[i + 1];
+		if (!out.dir && arg && !arg.startsWith("-")) {
+			out.dir = arg;
+			continue;
+		}
+		if (arg === "--dir" && next) {
+			out.dir = next;
+			i += 1;
+			continue;
+		}
+		if (arg === "--artifacts-root" && next) {
+			out.artifactsRoot = next;
+			i += 1;
+			continue;
+		}
+		if (arg === "--steps" && next) {
+			out.stepsPath = next;
+			i += 1;
+			continue;
+		}
+		if (arg === "--update-goldens") {
+			out.updateGoldens = true;
+			continue;
+		}
+		throw new Error(`unknown arg: ${arg ?? ""}`);
+	}
+	return out;
+}
+if (import.meta.main) try {
+	const args = parseArgs(process.argv.slice(2));
+	const result = await runAllScripts({
+		dir: args.dir,
+		artifactsRoot: args.artifactsRoot,
+		stepsPath: args.stepsPath,
+		updateGoldens: args.updateGoldens
+	});
+	const failures = result.entries.filter((e) => !e.result.ok);
+	if (failures.length === 0) {
+		console.log(`ok count=${result.entries.length} dir=${result.dir}\nreport=${result.reportPath}\nsummary=${result.summaryPath}`);
+		process.exitCode = 0;
+	} else {
+		console.error(`failed count=${failures.length}/${result.entries.length} dir=${result.dir}\nreport=${result.reportPath}\nsummary=${result.summaryPath}`);
+		for (const f of failures) {
+			if (f.result.ok) continue;
+			console.error(`- ${f.filePath}: ${f.result.error}`);
+			if (f.result.failureArtifacts) {
+				console.error(`  artifacts=${f.result.artifactsDir ?? ""}`);
+				console.error(`  last=${f.result.failureArtifacts.lastViewPath}`);
+				console.error(`  error=${f.result.failureArtifacts.errorPath}`);
+			}
+		}
+		process.exitCode = 1;
+	}
+} catch (error) {
+	console.error(error.message);
+	process.exitCode = 1;
+}
+//#endregion
+//#region src/generator/doc_parser.ts
+async function parseDocument(source) {
+	const content = await fetchContent(source);
+	switch (detectFormat(source, content)) {
+		case "markdown": return parseMarkdown(content);
+		case "json": return parseJson(content);
+		case "yaml": return parseYaml(content);
+		case "html": return parseHtml(content);
+		default: return parsePlainText(content);
+	}
+}
+async function fetchContent(source) {
+	if (source.content) return source.content;
+	if (source.type === "local" && source.path) {
+		if (!existsSync(source.path)) throw new Error(`File not found: ${source.path}`);
+		return readFileSync(source.path, "utf8");
+	}
+	if (source.type === "url" && source.url) {
+		const response = await fetch(source.url);
+		if (!response.ok) throw new Error(`Failed to fetch URL: ${source.url} (${response.status})`);
+		return response.text();
+	}
+	throw new Error("Invalid document source: must provide path, url, or content");
+}
+function detectFormat(source, content) {
+	if (source.path) {
+		const ext = extname(source.path).toLowerCase();
+		if (ext === ".md" || ext === ".markdown") return "markdown";
+		if (ext === ".html" || ext === ".htm") return "html";
+		if (ext === ".json") return "json";
+		if (ext === ".yaml" || ext === ".yml") return "yaml";
+	}
+	const trimmed = content.trim();
+	if (trimmed.startsWith("{") || trimmed.startsWith("[")) return "json";
+	if (trimmed.startsWith("<!DOCTYPE") || trimmed.startsWith("<html")) return "html";
+	if (/^#\s/.test(trimmed) || /\n##\s/.test(content) || /```/.test(content)) return "markdown";
+	return "text";
+}
+function parseMarkdown(content) {
+	const lines = content.split("\n");
+	const codeBlocks = [];
+	const steps = [];
+	let title;
+	let description;
+	let inCodeBlock = false;
+	let currentLang = "";
+	let currentCode = [];
+	let codeBlockStart = 0;
+	for (let i = 0; i < lines.length; i++) {
+		const line = lines[i] ?? "";
+		if (!title && /^#\s+(.+)$/.test(line)) {
+			title = line.replace(/^#\s+/, "").trim();
+			continue;
+		}
+		if (title && !description && !inCodeBlock && line.trim() && !/^[#-]/.test(line)) description = line.trim();
+		if (line.startsWith("```")) {
+			if (!inCodeBlock) {
+				inCodeBlock = true;
+				currentLang = line.slice(3).trim().toLowerCase();
+				currentCode = [];
+				codeBlockStart = i + 1;
+			} else {
+				inCodeBlock = false;
+				if (currentCode.length > 0) codeBlocks.push({
+					language: currentLang || "text",
+					code: currentCode.join("\n"),
+					lineNumber: codeBlockStart
+				});
+			}
+			continue;
+		}
+		if (inCodeBlock) {
+			currentCode.push(line);
+			continue;
+		}
+		const stepMatch = line.match(/^\s*(\d+)\.\s+(.+)$/);
+		if (stepMatch && stepMatch[2]) steps.push(stepMatch[2].trim());
+		const bulletMatch = line.match(/^\s*[-*]\s+(.+)$/);
+		if (bulletMatch && bulletMatch[1]) {
+			const text = bulletMatch[1].trim();
+			if (isLikelyStep(text)) steps.push(text);
+		}
+	}
+	return {
+		title,
+		description,
+		codeBlocks,
+		steps,
+		rawContent: content,
+		format: "markdown"
+	};
+}
+function parseJson(content) {
+	const parsed = JSON.parse(content);
+	const codeBlocks = [];
+	const steps = [];
+	if (typeof parsed === "object" && parsed !== null) {
+		const obj = parsed;
+		if ("launch" in obj && "steps" in obj) return {
+			title: obj.name ?? "Imported Script",
+			description: "Parsed from JSON script",
+			codeBlocks: [],
+			steps: [],
+			rawContent: content,
+			format: "json"
+		};
+		if (Array.isArray(obj.commands)) {
+			for (const cmd of obj.commands) if (typeof cmd === "string") steps.push(cmd);
+			else if (typeof cmd === "object" && cmd && "command" in cmd) steps.push(String(cmd.command));
+		}
+		if (Array.isArray(obj.steps)) {
+			for (const step of obj.steps) if (typeof step === "string") steps.push(step);
+			else if (typeof step === "object" && step) {
+				const s = step;
+				if (typeof s.description === "string") steps.push(s.description);
+				else if (typeof s.command === "string") steps.push(s.command);
+			}
+		}
+	}
+	return {
+		codeBlocks,
+		steps,
+		rawContent: content,
+		format: "json"
+	};
+}
+function parseYaml(content) {
+	const steps = [];
+	const lines = content.split("\n");
+	for (const line of lines) {
+		const match = line.match(/^\s*-\s+(.+)$/);
+		if (match && match[1]) {
+			const value = match[1].trim();
+			if (!value.startsWith("{") && !value.includes(":")) steps.push(value);
+		}
+	}
+	return {
+		codeBlocks: [],
+		steps,
+		rawContent: content,
+		format: "yaml"
+	};
+}
+function parseHtml(content) {
+	const codeBlocks = [];
+	const steps = [];
+	let title;
+	const titleMatch = content.match(/<title>([^<]+)<\/title>/i);
+	if (titleMatch && titleMatch[1]) title = titleMatch[1].trim();
+	const codeRegex = /<code[^>]*(?:class="[^"]*language-(\w+)[^"]*")?[^>]*>([\s\S]*?)<\/code>/gi;
+	let match;
+	while ((match = codeRegex.exec(content)) !== null) {
+		const lang = match[1] ?? "text";
+		const code = decodeHtmlEntities(match[2] ?? "");
+		if (code.trim()) codeBlocks.push({
+			language: lang,
+			code: code.trim(),
+			lineNumber: 0
+		});
+	}
+	const liRegex = /<li[^>]*>([\s\S]*?)<\/li>/gi;
+	while ((match = liRegex.exec(content)) !== null) {
+		const text = stripHtmlTags(match[1] ?? "").trim();
+		if (text && isLikelyStep(text)) steps.push(text);
+	}
+	return {
+		title,
+		codeBlocks,
+		steps,
+		rawContent: content,
+		format: "html"
+	};
+}
+function parsePlainText(content) {
+	const lines = content.split("\n");
+	const steps = [];
+	for (const line of lines) {
+		const trimmed = line.trim();
+		if (!trimmed) continue;
+		const numberedMatch = trimmed.match(/^\d+\.\s+(.+)$/);
+		if (numberedMatch && numberedMatch[1]) {
+			steps.push(numberedMatch[1].trim());
+			continue;
+		}
+		const bulletMatch = trimmed.match(/^[-*]\s+(.+)$/);
+		if (bulletMatch && bulletMatch[1]) {
+			steps.push(bulletMatch[1].trim());
+			continue;
+		}
+		if (isLikelyStep(trimmed)) steps.push(trimmed);
+	}
+	return {
+		codeBlocks: [],
+		steps,
+		rawContent: content,
+		format: "text"
+	};
+}
+function isLikelyStep(text) {
+	return [
+		/^(run|execute|type|enter|press|click|open|start|stop|wait|check|verify|assert)/i,
+		/^(输入|执行|运行|点击|打开|启动|停止|等待|检查|验证)/,
+		/\$\s+\w+/,
+		/^>\s+\w+/
+	].some((pattern) => pattern.test(text));
+}
+function decodeHtmlEntities(text) {
+	return text.replace(/&lt;/g, "<").replace(/&gt;/g, ">").replace(/&amp;/g, "&").replace(/&quot;/g, "\"").replace(/&#39;/g, "'").replace(/&nbsp;/g, " ");
+}
+function stripHtmlTags(html) {
+	return html.replace(/<[^>]+>/g, "");
+}
+//#endregion
+//#region src/generator/step_extractor.ts
+function extractSteps(doc) {
+	const warnings = [];
+	const steps = [];
+	let launch;
+	for (const block of doc.codeBlocks) if (isShellLanguage(block.language)) {
+		const extracted = extractFromShellBlock(block);
+		if (!launch && extracted.launch) launch = extracted.launch;
+		steps.push(...extracted.steps);
+	}
+	if (steps.length === 0 && doc.steps.length > 0) for (const textStep of doc.steps) {
+		const extracted = extractFromTextStep(textStep);
+		if (extracted) steps.push(extracted);
+	}
+	if (steps.length === 0) {
+		for (const block of doc.codeBlocks) if (!isShellLanguage(block.language)) {
+			const extracted = extractFromGenericCodeBlock(block);
+			steps.push(...extracted);
+		}
+	}
+	const stepsWithWaits = insertDefaultWaits(steps);
+	if (!launch && stepsWithWaits.length > 0) warnings.push("No launch command detected. You may need to specify targetCommand.");
+	if (stepsWithWaits.length === 0) warnings.push("No test steps could be extracted from the document.");
+	return {
+		launch,
+		steps: stepsWithWaits,
+		warnings
+	};
+}
+function isShellLanguage(lang) {
+	return [
+		"bash",
+		"sh",
+		"shell",
+		"zsh",
+		"fish",
+		"console",
+		"terminal",
+		"cmd",
+		"powershell"
+	].includes(lang.toLowerCase());
+}
+function extractFromShellBlock(block) {
+	const lines = block.code.split("\n").filter((l) => l.trim());
+	const steps = [];
+	let launch;
+	for (const line of lines) {
+		const trimmed = line.trim();
+		if (trimmed.startsWith("#") || trimmed.startsWith("//")) continue;
+		const command = trimmed.replace(/^\$\s+/, "").replace(/^>\s+/, "").replace(/^%\s+/, "");
+		if (!command) continue;
+		if (!launch && isLaunchCandidate(command)) {
+			launch = parseLaunchCommand(command);
+			continue;
+		}
+		const step = parseCommandAsStep(command);
+		if (step) steps.push(step);
+	}
+	return {
+		launch,
+		steps
+	};
+}
+function extractFromTextStep(text) {
+	const normalized = text.toLowerCase();
+	const typeMatch = text.match(/^(?:type|enter|input)\s+["`']?(.+?)["`']?$/i);
+	if (typeMatch && typeMatch[1]) return {
+		type: "sendText",
+		params: {
+			text: typeMatch[1],
+			enter: true
+		},
+		source: "text_step",
+		confidence: "medium",
+		rawText: text
+	};
+	const pressMatch = text.match(/^press\s+(.+)$/i);
+	if (pressMatch && pressMatch[1]) return {
+		type: "pressKey",
+		params: { key: normalizeKeyName(pressMatch[1]) },
+		source: "text_step",
+		confidence: "medium",
+		rawText: text
+	};
+	const waitMatch = text.match(/^wait\s+(?:for\s+)?["`']?(.+?)["`']?$/i);
+	if (waitMatch && waitMatch[1]) return {
+		type: "waitForText",
+		params: {
+			text: waitMatch[1],
+			timeoutMs: 1e4
+		},
+		source: "text_step",
+		confidence: "medium",
+		rawText: text
+	};
+	const assertMatch = text.match(/^(?:check|verify|assert|expect)\s+(?:that\s+)?["`']?(.+?)["`']?$/i);
+	if (assertMatch && assertMatch[1]) return {
+		type: "assert",
+		params: {
+			text: assertMatch[1],
+			description: text
+		},
+		source: "text_step",
+		confidence: "medium",
+		rawText: text
+	};
+	const runMatch = text.match(/^(?:run|execute)\s+(.+)$/i);
+	if (runMatch && runMatch[1]) return {
+		type: "sendText",
+		params: {
+			text: runMatch[1],
+			enter: true
+		},
+		source: "text_step",
+		confidence: "low",
+		rawText: text
+	};
+	if (/^输入\s+/.test(text)) return {
+		type: "sendText",
+		params: {
+			text: text.replace(/^输入\s+/, "").trim(),
+			enter: true
+		},
+		source: "text_step",
+		confidence: "medium",
+		rawText: text
+	};
+	if (/^等待\s+/.test(text)) return {
+		type: "waitForText",
+		params: {
+			text: text.replace(/^等待\s+/, "").trim(),
+			timeoutMs: 1e4
+		},
+		source: "text_step",
+		confidence: "medium",
+		rawText: text
+	};
+	if (/^[a-z_][a-z0-9_-]*\s/i.test(normalized) || text.startsWith("./")) return {
+		type: "sendText",
+		params: {
+			text: text.trim(),
+			enter: true
+		},
+		source: "text_step",
+		confidence: "low",
+		rawText: text
+	};
+	return null;
+}
+function extractFromGenericCodeBlock(block) {
+	const steps = [];
+	const lines = block.code.split("\n").filter((l) => l.trim());
+	for (const line of lines) if (/^[a-z_][a-z0-9_-]*(\s|$)/i.test(line.trim())) steps.push({
+		type: "sendText",
+		params: {
+			text: line.trim(),
+			enter: true
+		},
+		source: "code_block",
+		confidence: "low",
+		rawText: line
+	});
+	return steps;
+}
+function isLaunchCandidate(command) {
+	return [
+		/^(node|bun|deno|python|python3|ruby|perl)\s+/i,
+		/^(npm|yarn|pnpm|bun)\s+(run|start|test)/i,
+		/^(cargo|go|rust)\s+run/i,
+		/^\.\//,
+		/^[a-z_][a-z0-9_-]*$/i
+	].some((p) => p.test(command));
+}
+function parseLaunchCommand(command) {
+	const [cmd, ...args] = parseCommandLine(command);
+	return {
+		command: cmd ?? command,
+		args: args.length > 0 ? args : void 0,
+		confidence: "high"
+	};
+}
+function parseCommandLine(command) {
+	const parts = [];
+	let current = "";
+	let inQuote = null;
+	let escape = false;
+	for (const char of command) {
+		if (escape) {
+			current += char;
+			escape = false;
+			continue;
+		}
+		if (char === "\\") {
+			escape = true;
+			continue;
+		}
+		if ((char === "\"" || char === "'") && !inQuote) {
+			inQuote = char;
+			continue;
+		}
+		if (char === inQuote) {
+			inQuote = null;
+			continue;
+		}
+		if (char === " " && !inQuote) {
+			if (current) {
+				parts.push(current);
+				current = "";
+			}
+			continue;
+		}
+		current += char;
+	}
+	if (current) parts.push(current);
+	return parts;
+}
+function parseCommandAsStep(command) {
+	if (/^(error|warning|info|debug|note):/i.test(command)) return null;
+	return {
+		type: "sendText",
+		params: {
+			text: command,
+			enter: true
+		},
+		source: "code_block",
+		confidence: "high",
+		rawText: command
+	};
+}
+function normalizeKeyName(key) {
+	return {
+		enter: "Enter",
+		return: "Enter",
+		tab: "Tab",
+		escape: "Escape",
+		esc: "Escape",
+		space: "Space",
+		backspace: "Backspace",
+		delete: "Delete",
+		up: "ArrowUp",
+		down: "ArrowDown",
+		left: "ArrowLeft",
+		right: "ArrowRight",
+		home: "Home",
+		end: "End",
+		pageup: "PageUp",
+		pagedown: "PageDown",
+		"ctrl+c": "Ctrl+C",
+		"ctrl+d": "Ctrl+D",
+		"ctrl+z": "Ctrl+Z"
+	}[key.toLowerCase().trim()] ?? key;
+}
+function insertDefaultWaits(steps) {
+	const result = [];
+	for (let i = 0; i < steps.length; i++) {
+		const step = steps[i];
+		if (!step) continue;
+		result.push(step);
+		const nextStep = steps[i + 1];
+		const isInputStep = step.type === "sendText" || step.type === "pressKey";
+		const nextIsWait = nextStep?.type === "waitForText" || nextStep?.type === "waitForStableScreen" || nextStep?.type === "sleep";
+		if (isInputStep && !nextIsWait && i < steps.length - 1) result.push({
+			type: "waitForStableScreen",
+			params: {
+				timeoutMs: 5e3,
+				quietMs: 300
+			},
+			source: "inferred",
+			confidence: "low"
+		});
+	}
+	return result;
+}
+//#endregion
+//#region src/generator/script_generator.ts
+function generateScript(steps, options) {
+	const script = buildScript(steps, options);
+	mkdirSync(options.outputDir, { recursive: true });
+	let jsonPath;
+	let tsPath;
+	if (options.format === "json" || options.format === "both") {
+		jsonPath = join(options.outputDir, `${options.name}.json`);
+		const jsonContent = generateJsonScript(script, { schemaPath: resolveJsonSchemaPath(options.outputDir) });
+		writeFileSync(jsonPath, jsonContent, "utf8");
+	}
+	if (options.format === "ts" || options.format === "both") {
+		tsPath = join(options.outputDir, `${options.name}.ts`);
+		const tsContent = generateTypeScriptScript(script);
+		writeFileSync(tsPath, tsContent, "utf8");
+	}
+	return {
+		name: options.name,
+		jsonPath,
+		tsPath,
+		script,
+		stepCount: script.steps.length
+	};
+}
+function buildScript(steps, options) {
+	const launch = resolveLaunch(options);
+	const scriptSteps = steps.map(convertToScriptStep);
+	if (!scriptSteps.some((s) => s.type === "snapshot" || s.type === "expect" || s.type === "expectGolden") && scriptSteps.length > 0) scriptSteps.push({
+		type: "snapshot",
+		kind: "view",
+		scope: "visible",
+		trimRight: true,
+		trimBottom: true
+	});
+	return {
+		name: options.name,
+		launch,
+		trace: options.trace ?? {
+			saveCast: true,
+			saveReport: true
+		},
+		steps: scriptSteps
+	};
+}
+function resolveLaunch(options) {
+	if (options.targetCommand) return {
+		command: options.targetCommand,
+		args: options.targetArgs,
+		cols: options.cols ?? 80,
+		rows: options.rows ?? 24,
+		env: options.env
+	};
+	if (options.launch) return {
+		command: options.launch.command,
+		args: options.launch.args,
+		cwd: options.launch.cwd,
+		cols: options.cols ?? 80,
+		rows: options.rows ?? 24,
+		env: options.env ?? options.launch.env
+	};
+	return {
+		command: "bash",
+		cols: options.cols ?? 80,
+		rows: options.rows ?? 24
+	};
+}
+function convertToScriptStep(extracted) {
+	const { type, params } = extracted;
+	switch (type) {
+		case "sendText": return {
+			type: "sendText",
+			text: typeof params.text === "string" ? params.text : "",
+			enter: params.enter
+		};
+		case "pressKey": return {
+			type: "pressKey",
+			key: typeof params.key === "string" ? params.key : "Enter"
+		};
+		case "waitForText": return {
+			type: "waitForText",
+			text: params.text,
+			regex: params.regex,
+			scope: params.scope ?? "visible",
+			timeoutMs: params.timeoutMs ?? 1e4
+		};
+		case "waitForStableScreen": return {
+			type: "waitForStableScreen",
+			timeoutMs: params.timeoutMs ?? 5e3,
+			quietMs: params.quietMs ?? 300
+		};
+		case "assert": return {
+			type: "assert",
+			text: params.text,
+			regex: params.regex,
+			description: params.description
+		};
+		case "sleep": return {
+			type: "sleep",
+			ms: params.ms ?? 1e3
+		};
+		case "snapshot": return {
+			type: "snapshot",
+			kind: params.kind ?? "view",
+			scope: params.scope ?? "visible",
+			trimRight: true,
+			trimBottom: true
+		};
+		default: return {
+			type: "sendText",
+			text: typeof params.text === "string" ? params.text : extracted.rawText ?? "",
+			enter: true
+		};
+	}
+}
+function generateJsonScript(script, options) {
+	const output = {
+		$schema: options?.schemaPath ?? "../schemas/ptywright-script.schema.json",
+		...script
+	};
+	return JSON.stringify(output, null, 2) + "\n";
+}
+function generateTypeScriptScript(script) {
+	return `export default ${JSON.stringify(script, null, 2)};\n`;
+}
+function resolveJsonSchemaPath(outputDir) {
+	let schemaPath = relative(resolve(process.cwd(), outputDir), resolve(process.cwd(), "schemas", "ptywright-script.schema.json"));
+	if (!schemaPath.startsWith(".")) schemaPath = `./${schemaPath}`;
+	return schemaPath.replaceAll("\\", "/");
+}
+//#endregion
+//#region src/generator/generate.ts
+async function generateTestFromDoc(options) {
+	const warnings = [];
+	try {
+		const parsed = await parseDocument(resolveDocumentSource(options.source, options.sourceType));
+		const extraction = extractSteps(parsed);
+		warnings.push(...extraction.warnings);
+		if (extraction.steps.length === 0) return {
+			ok: false,
+			name: options.name ?? "unknown",
+			stepCount: 0,
+			warnings,
+			error: "No test steps could be extracted from the document",
+			parsed: {
+				title: parsed.title,
+				format: parsed.format,
+				codeBlockCount: parsed.codeBlocks.length,
+				textStepCount: parsed.steps.length
+			}
+		};
+		const scriptName = resolveScriptName(options.name, options.source, parsed);
+		const outputDir = options.outputDir ?? resolve(".tmp", "generated");
+		const generated = generateScript(extraction.steps, {
+			name: scriptName,
+			launch: extraction.launch,
+			targetCommand: options.targetCommand,
+			targetArgs: options.targetArgs,
+			outputDir,
+			format: options.outputFormat ?? "both",
+			cols: options.cols,
+			rows: options.rows,
+			env: options.env,
+			trace: options.trace
+		});
+		return {
+			ok: true,
+			name: generated.name,
+			jsonPath: generated.jsonPath,
+			tsPath: generated.tsPath,
+			stepCount: generated.stepCount,
+			warnings,
+			parsed: {
+				title: parsed.title,
+				format: parsed.format,
+				codeBlockCount: parsed.codeBlocks.length,
+				textStepCount: parsed.steps.length
+			}
+		};
+	} catch (error) {
+		return {
+			ok: false,
+			name: options.name ?? "unknown",
+			stepCount: 0,
+			warnings,
+			error: error instanceof Error ? error.message : String(error)
+		};
+	}
+}
+function resolveDocumentSource(source, sourceType) {
+	if ((!sourceType || sourceType === "auto" ? detectSourceType(source) : sourceType) === "url") return {
+		type: "url",
+		url: source
+	};
+	return {
+		type: "local",
+		path: resolve(source)
+	};
+}
+function detectSourceType(source) {
+	if (source.startsWith("http://") || source.startsWith("https://")) return "url";
+	return "local";
+}
+function resolveScriptName(explicitName, source, parsed) {
+	if (explicitName) return sanitizeName(explicitName);
+	if (parsed.title) return sanitizeName(parsed.title);
+	return sanitizeName(basename(source, extname(source)));
+}
+function sanitizeName(name) {
+	return name.toLowerCase().replace(/[^a-z0-9_-]/g, "_").replace(/_+/g, "_").replace(/^_|_$/g, "").slice(0, 64) || "generated_test";
+}
+//#endregion
+//#region src/mcp/script_recording.ts
+var ScriptRecordingManager = class {
+	active = null;
+	start(args) {
+		if (this.active) throw new Error(`recording already active: ${this.active.id}`);
+		const name = args.name.trim();
+		if (!name) throw new Error("name is required");
+		const outPath = (args.outPath?.trim() ? args.outPath.trim() : `scripts/${name}.json`).trim();
+		const goldenDir = (args.goldenDir?.trim() ? args.goldenDir.trim() : `tests/golden/scripts/${name}`).trim();
+		this.active = {
+			id: crypto.randomUUID(),
+			name,
+			outPath,
+			goldenDir,
+			overwrite: args.overwrite ?? false,
+			checkpoint: {
+				scope: args.checkpoint?.scope ?? "visible",
+				trimRight: args.checkpoint?.trimRight ?? true,
+				trimBottom: args.checkpoint?.trimBottom ?? true,
+				mask: args.checkpoint?.mask
+			},
+			launch: null,
+			sessionId: null,
+			steps: [],
+			checkpointIndex: 0,
+			goldenWrites: []
+		};
+		return this.status();
+	}
+	stop(args) {
+		if (!this.active) throw new Error("no active recording");
+		if (args.recordingId !== this.active.id) throw new Error(`recording not found: ${args.recordingId}`);
+		const writeFiles = args.writeFiles ?? true;
+		const recording = this.active;
+		this.active = null;
+		if (!recording.launch) throw new Error("recording has no launch_session");
+		const schemaAbs = resolve("schemas/ptywright-script.schema.json");
+		const built = {
+			$schema: toPosixPath(relative(dirname(resolve(recording.outPath)), schemaAbs)),
+			name: recording.name,
+			launch: recording.launch,
+			steps: recording.steps
+		};
+		const script = {
+			...scriptSchema.parse(built),
+			$schema: built.$schema
+		};
+		const goldenPaths = recording.goldenWrites.map((w) => w.path);
+		if (writeFiles) {
+			writeOrThrow(recording.outPath, `${JSON.stringify(script, null, 2)}\n`, recording.overwrite);
+			for (const w of recording.goldenWrites) writeOrThrow(w.path, `${w.text}\n`, recording.overwrite);
+		}
+		return {
+			scriptPath: writeFiles ? recording.outPath : void 0,
+			goldenPaths,
+			script
+		};
+	}
+	status() {
+		if (!this.active) throw new Error("no active recording");
+		return {
+			recordingId: this.active.id,
+			name: this.active.name,
+			outPath: this.active.outPath,
+			goldenDir: this.active.goldenDir,
+			hasLaunch: this.active.launch !== null,
+			stepCount: this.active.steps.length,
+			checkpointCount: this.active.checkpointIndex
+		};
+	}
+	recordLaunch(args, sessionId) {
+		const rec = this.active;
+		if (!rec) return;
+		if (rec.launch) return;
+		rec.launch = args;
+		rec.sessionId = sessionId;
+	}
+	recordStep(step) {
+		const rec = this.active;
+		if (!rec) return;
+		rec.steps.push(step);
+	}
+	async recordCheckpoint(args) {
+		const rec = this.active;
+		if (!rec) return;
+		if (!rec.sessionId || rec.sessionId !== args.session.id) return;
+		const safe = sanitizeLabel((args.label ?? "").trim() || `checkpoint_${rec.checkpointIndex + 1}`);
+		rec.checkpointIndex += 1;
+		const snapshot = await args.session.snapshotText({
+			scope: rec.checkpoint.scope,
+			trimRight: rec.checkpoint.trimRight,
+			trimBottom: rec.checkpoint.trimBottom,
+			captureFrame: true,
+			mask: rec.checkpoint.mask
+		});
+		const goldenPath = toPosixPath(resolvePathLike(joinPosix(rec.goldenDir, `${safe}.txt`), false));
+		rec.goldenWrites.push({
+			path: goldenPath,
+			text: snapshot.text
+		});
+		rec.steps.push({
+			type: "snapshot",
+			kind: "text",
+			scope: rec.checkpoint.scope,
+			trimRight: rec.checkpoint.trimRight,
+			trimBottom: rec.checkpoint.trimBottom,
+			mask: rec.checkpoint.mask
+		});
+		rec.steps.push({
+			type: "expectGolden",
+			path: goldenPath
+		});
+	}
+};
+function writeOrThrow(path, text, overwrite) {
+	const abs = resolvePathLike(path, true);
+	if (!overwrite && existsSync(abs)) throw new Error(`refusing to overwrite: ${path}`);
+	mkdirSync(dirname(abs), { recursive: true });
+	writeFileSync(abs, text, "utf8");
+}
+function resolvePathLike(path, absolute) {
+	if (!absolute) return toPosixPath(path);
+	return resolve(process.cwd(), path);
+}
+function sanitizeLabel(label) {
+	return label.replace(/[^a-z0-9._-]+/gi, "_").replace(/^_+|_+$/g, "") || "checkpoint";
+}
+function toPosixPath(path) {
+	return path.replace(/\\/g, "/");
+}
+function joinPosix(a, b) {
+	return `${a.replace(/\\/g, "/").replace(/\/+$/g, "")}/${b.replace(/\\/g, "/").replace(/^\/+/g, "")}`;
+}
+//#endregion
+//#region package.json
+var version = "0.3.0";
+//#endregion
+//#region src/mcp/server.ts
+const textMaskRuleSchema = z.object({
+	regex: z.string().min(1),
+	flags: z.string().optional(),
+	replacement: z.string().optional(),
+	preserveLength: z.boolean().optional()
+});
+function createPtywrightServer(options) {
+	const sessions = options?.sessionManager ?? new SessionManager();
+	const recordings = new ScriptRecordingManager();
+	const server = new McpServer({
+		name: "ptywright",
+		version
+	});
+	const caps = resolveCapabilities(options?.capabilities, process.env.PTYWRIGHT_CAPS);
+	const selectedSessionByTransport = /* @__PURE__ */ new Map();
+	function transportKey(extra) {
+		return extra.sessionId ?? "default";
+	}
+	function getSelectedSessionId(extra) {
+		return selectedSessionByTransport.get(transportKey(extra));
+	}
+	function setSelectedSessionId(extra, sessionId) {
+		selectedSessionByTransport.set(transportKey(extra), sessionId);
+	}
+	function clearSelectedSessionId(extra) {
+		selectedSessionByTransport.delete(transportKey(extra));
+	}
+	function isEnabled(category) {
+		return caps.all || caps.enabled.has(category);
+	}
+	function tool(category, name, description, schema, annotations, handler) {
+		if (!isEnabled(category)) return;
+		const { title, ...rest } = annotations ?? {};
+		const cleanedAnnotations = Object.keys(rest).length ? rest : void 0;
+		server.registerTool(name, {
+			title,
+			description,
+			inputSchema: schema,
+			annotations: cleanedAnnotations,
+			_meta: { category }
+		}, handler);
+	}
+	tool("core", "select_session", "Select the default session for subsequent tool calls (so other tools can omit sessionId).", { sessionId: z.string().min(1) }, { title: "Select Session" }, async (args, extra) => {
+		if (!sessions.getSession(args.sessionId)) return toolError(`session not found: ${args.sessionId}`);
+		setSelectedSessionId(extra, args.sessionId);
+		return {
+			content: [{
+				type: "text",
+				text: `selected ${args.sessionId}`
+			}],
+			structuredContent: { sessionId: args.sessionId }
+		};
+	});
+	tool("core", "launch_session", "Start here! Launch a CLI/TUI command to begin testing (e.g., 'vim', 'top', 'npm start'). Returns a sessionId required for other tools.", {
+		command: z.string().min(1),
+		args: z.array(z.string()).optional(),
+		cwd: z.string().optional(),
+		env: z.record(z.string()).optional(),
+		cols: z.number().int().optional(),
+		rows: z.number().int().optional(),
+		name: z.string().optional()
+	}, {
+		title: "Launch Session",
+		openWorldHint: true
+	}, async (args, extra) => {
+		const session = sessions.launchSession(args);
+		setSelectedSessionId(extra, session.id);
+		recordings.recordLaunch({
+			command: args.command,
+			args: args.args,
+			cwd: args.cwd,
+			env: args.env,
+			cols: args.cols,
+			rows: args.rows,
+			name: args.name
+		}, session.id);
+		return {
+			content: [{
+				type: "text",
+				text: `launched ${session.id}`
+			}],
+			structuredContent: { sessionId: session.id }
+		};
+	});
+	tool("core", "send_text", "Send text input to a session (optionally press Enter).", {
+		sessionId: z.string().min(1).optional(),
+		text: z.string(),
+		enter: z.boolean().optional()
+	}, { title: "Send Text" }, async (args, extra) => {
+		const sessionId = args.sessionId ?? getSelectedSessionId(extra);
+		if (!sessionId) return toolError("sessionId is required (provide sessionId or call select_session)");
+		const session = sessions.getSession(sessionId);
+		if (!session) return toolError(`session not found: ${sessionId}`);
+		session.sendText(args.text, { enter: args.enter });
+		recordings.recordStep({
+			type: "sendText",
+			text: args.text,
+			enter: args.enter
+		});
+		return { content: [{
+			type: "text",
+			text: "ok"
+		}] };
+	});
+	tool("core", "press_key", "Send a key or key chord to a session (e.g. Enter, Ctrl+C, Shift+Tab).", {
+		sessionId: z.string().min(1).optional(),
+		key: z.string().min(1)
+	}, { title: "Press Key" }, async (args, extra) => {
+		const sessionId = args.sessionId ?? getSelectedSessionId(extra);
+		if (!sessionId) return toolError("sessionId is required (provide sessionId or call select_session)");
+		const session = sessions.getSession(sessionId);
+		if (!session) return toolError(`session not found: ${sessionId}`);
+		try {
+			session.pressKey(args.key);
+			recordings.recordStep({
+				type: "pressKey",
+				key: args.key
+			});
+			return { content: [{
+				type: "text",
+				text: "ok"
+			}] };
+		} catch (error) {
+			return toolError(error.message);
+		}
+	});
+	tool("core", "snapshot_text", "Capture plain text from the visible screen or full buffer (best for stable assertions/goldens).", {
+		sessionId: z.string().min(1).optional(),
+		scope: z.enum(["visible", "buffer"]).optional(),
+		trimRight: z.boolean().optional(),
+		trimBottom: z.boolean().optional(),
+		maxLines: z.number().int().positive().optional(),
+		tailLines: z.number().int().positive().optional(),
+		mask: z.array(textMaskRuleSchema).optional()
+	}, {
+		title: "Snapshot Text",
+		readOnlyHint: true,
+		idempotentHint: true
+	}, async (args, extra) => {
+		const sessionId = args.sessionId ?? getSelectedSessionId(extra);
+		if (!sessionId) return toolError("sessionId is required (provide sessionId or call select_session)");
+		const session = sessions.getSession(sessionId);
+		if (!session) return toolError(`session not found: ${sessionId}`);
+		if (args.maxLines !== void 0 && args.tailLines !== void 0) return toolError("snapshot_text: maxLines and tailLines are mutually exclusive");
+		let text;
+		let hash;
+		try {
+			({text, hash} = await session.snapshotText({
+				scope: args.scope,
+				trimRight: args.trimRight ?? true,
+				trimBottom: args.trimBottom ?? true,
+				maxLines: args.maxLines,
+				tailLines: args.tailLines,
+				mask: args.mask
+			}));
+		} catch (error) {
+			return toolError(error.message);
+		}
+		return {
+			content: [{
+				type: "text",
+				text
+			}],
+			structuredContent: {
+				sessionId,
+				hash
+			}
+		};
+	});
+	tool("debug", "snapshot_ansi", "Capture ANSI-rendered snapshot (debug/human inspection; less stable than plain text).", {
+		sessionId: z.string().min(1).optional(),
+		scope: z.enum(["visible", "buffer"]).optional(),
+		trimRight: z.boolean().optional(),
+		trimBottom: z.boolean().optional(),
+		maxLines: z.number().int().positive().optional(),
+		tailLines: z.number().int().positive().optional(),
+		mask: z.array(textMaskRuleSchema).optional()
+	}, {
+		title: "Snapshot ANSI",
+		readOnlyHint: true,
+		idempotentHint: true
+	}, async (args, extra) => {
+		const sessionId = args.sessionId ?? getSelectedSessionId(extra);
+		if (!sessionId) return toolError("sessionId is required (provide sessionId or call select_session)");
+		const session = sessions.getSession(sessionId);
+		if (!session) return toolError(`session not found: ${sessionId}`);
+		if (args.maxLines !== void 0 && args.tailLines !== void 0) return toolError("snapshot_ansi: maxLines and tailLines are mutually exclusive");
+		let ansi;
+		let plain;
+		let hash;
+		try {
+			({ansi, plain, hash} = await session.snapshotAnsi({
+				scope: args.scope,
+				trimRight: args.trimRight ?? true,
+				trimBottom: args.trimBottom ?? true,
+				maxLines: args.maxLines,
+				tailLines: args.tailLines,
+				mask: args.mask
+			}));
+		} catch (error) {
+			return toolError(error.message);
+		}
+		return {
+			content: [{
+				type: "text",
+				text: ansi
+			}],
+			structuredContent: {
+				sessionId,
+				hash,
+				plain
+			}
+		};
+	});
+	tool("recording", "mark", "Add a marker to the session trace (used for recording/checkpoints).", {
+		sessionId: z.string().min(1).optional(),
+		label: z.string().optional()
+	}, { title: "Mark Trace" }, async (args, extra) => {
+		const sessionId = args.sessionId ?? getSelectedSessionId(extra);
+		if (!sessionId) return toolError("sessionId is required (provide sessionId or call select_session)");
+		const session = sessions.getSession(sessionId);
+		if (!session) return toolError(`session not found: ${sessionId}`);
+		session.mark(args.label);
+		recordings.recordStep({
+			type: "mark",
+			label: args.label
+		});
+		await recordings.recordCheckpoint({
+			session,
+			label: args.label
+		});
+		return { content: [{
+			type: "text",
+			text: "ok"
+		}] };
+	});
+	tool("core", "wait_for_text", "Wait until a text/regex appears in the session (polling).", {
+		sessionId: z.string().min(1).optional(),
+		scope: z.enum(["visible", "buffer"]).optional(),
+		text: z.string().optional(),
+		regex: z.string().optional(),
+		timeoutMs: z.number().int().optional(),
+		intervalMs: z.number().int().optional(),
+		includeText: z.boolean().optional()
+	}, {
+		title: "Wait For Text",
+		readOnlyHint: true,
+		idempotentHint: true
+	}, async (args, extra) => {
+		const sessionId = args.sessionId ?? getSelectedSessionId(extra);
+		if (!sessionId) return toolError("sessionId is required (provide sessionId or call select_session)");
+		const session = sessions.getSession(sessionId);
+		if (!session) return toolError(`session not found: ${sessionId}`);
+		if (!args.text && !args.regex) return toolError("either text or regex must be provided");
+		const regex = args.regex ? new RegExp(args.regex) : void 0;
+		const result = await session.waitForText({
+			scope: args.scope,
+			text: args.text,
+			regex,
+			timeoutMs: args.timeoutMs ?? 1e4,
+			intervalMs: args.intervalMs ?? 100
+		});
+		recordings.recordStep({
+			type: "waitForText",
+			scope: args.scope,
+			text: args.text,
+			regex: args.regex,
+			timeoutMs: args.timeoutMs,
+			intervalMs: args.intervalMs
+		});
+		const structuredContent = {
+			sessionId,
+			found: result.found,
+			hash: result.hash
+		};
+		if (args.includeText ?? false) structuredContent.text = result.text;
+		return {
+			content: [{
+				type: "text",
+				text: result.found ? "found" : "not_found"
+			}],
+			structuredContent
+		};
+	});
+	tool("core", "wait_for_stable_screen", "Wait until consecutive text snapshots remain unchanged for a quiet window (reduce flakiness).", {
+		sessionId: z.string().min(1).optional(),
+		timeoutMs: z.number().int().optional(),
+		quietMs: z.number().int().optional(),
+		intervalMs: z.number().int().optional(),
+		includeText: z.boolean().optional()
+	}, {
+		title: "Wait For Stable Screen",
+		readOnlyHint: true,
+		idempotentHint: true
+	}, async (args, extra) => {
+		const sessionId = args.sessionId ?? getSelectedSessionId(extra);
+		if (!sessionId) return toolError("sessionId is required (provide sessionId or call select_session)");
+		const session = sessions.getSession(sessionId);
+		if (!session) return toolError(`session not found: ${sessionId}`);
+		const result = await session.waitForStableScreen({
+			timeoutMs: args.timeoutMs ?? 1e4,
+			quietMs: args.quietMs ?? 400,
+			intervalMs: args.intervalMs ?? 80
+		});
+		recordings.recordStep({
+			type: "waitForStableScreen",
+			...args
+		});
+		const structuredContent = {
+			sessionId,
+			stable: result.stable,
+			hash: result.hash
+		};
+		if (args.includeText ?? false) structuredContent.text = result.text;
+		return {
+			content: [{
+				type: "text",
+				text: result.stable ? "stable" : "unstable"
+			}],
+			structuredContent
+		};
+	});
+	tool("core", "assert", "Verify screen content. Use this to check if a test passed or failed (e.g., 'check if X is visible'). Supports exact text, regex, or semantic AI verification.", {
+		sessionId: z.string().min(1).optional(),
+		scope: z.enum(["visible", "buffer"]).optional(),
+		description: z.string().optional(),
+		text: z.string().optional(),
+		regex: z.string().optional(),
+		useAI: z.boolean().optional()
+	}, {
+		title: "Assert",
+		readOnlyHint: true,
+		idempotentHint: true
+	}, async (args, extra) => {
+		const sessionId = args.sessionId ?? getSelectedSessionId(extra);
+		if (!sessionId) return toolError("sessionId is required (provide sessionId or call select_session)");
+		const session = sessions.getSession(sessionId);
+		if (!session) return toolError(`session not found: ${sessionId}`);
+		if (!args.text && !args.regex && !args.useAI) return toolError("must provide text, regex, or useAI: true");
+		const snapshot = await session.snapshotText({
+			scope: args.scope ?? "visible",
+			captureFrame: true
+		});
+		let found = true;
+		if (args.text || args.regex) {
+			found = false;
+			if (args.text && snapshot.text.includes(args.text)) found = true;
+			if (args.regex) {
+				let re;
+				try {
+					re = new RegExp(args.regex);
+				} catch {
+					return toolError(`invalid regex: ${args.regex}`);
+				}
+				if (re.test(snapshot.text)) found = true;
+			}
+		}
+		if (args.text || args.regex) recordings.recordStep({
+			type: "assert",
+			scope: args.scope,
+			text: args.text,
+			regex: args.regex,
+			description: args.description
+		});
+		if (args.useAI) recordings.recordStep({
+			type: "assertSemantic",
+			prompt: args.description || "Check screen content",
+			description: args.description
+		});
+		if (!found) return toolError(`assertion failed: ${args.description || "pattern match"}`, {
+			sessionId,
+			text: snapshot.text
+		});
+		return {
+			content: [{
+				type: "text",
+				text: "ok"
+			}],
+			structuredContent: {
+				sessionId,
+				found
+			}
+		};
+	});
+	tool("core", "snapshot_view", "Capture a formatted, human-readable snapshot view (includes meta + optional line numbers).", {
+		sessionId: z.string().min(1).optional(),
+		scope: z.enum(["visible", "buffer"]).optional(),
+		trimRight: z.boolean().optional(),
+		trimBottom: z.boolean().optional(),
+		maxLines: z.number().int().positive().optional(),
+		tailLines: z.number().int().positive().optional(),
+		lineNumbers: z.boolean().optional(),
+		mask: z.array(textMaskRuleSchema).optional()
+	}, {
+		title: "Snapshot View",
+		readOnlyHint: true,
+		idempotentHint: true
+	}, async (args, extra) => {
+		const sessionId = args.sessionId ?? getSelectedSessionId(extra);
+		if (!sessionId) return toolError("sessionId is required (provide sessionId or call select_session)");
+		const session = sessions.getSession(sessionId);
+		if (!session) return toolError(`session not found: ${sessionId}`);
+		if (args.maxLines !== void 0 && args.tailLines !== void 0) return toolError("snapshot_view: maxLines and tailLines are mutually exclusive");
+		let text;
+		let hash;
+		try {
+			({text, hash} = await session.snapshotText({
+				scope: args.scope,
+				trimRight: args.trimRight,
+				trimBottom: args.trimBottom ?? true,
+				maxLines: args.maxLines,
+				tailLines: args.tailLines,
+				mask: args.mask
+			}));
+		} catch (error) {
+			return toolError(error.message);
+		}
+		return {
+			content: [{
+				type: "text",
+				text: formatSnapshotView({
+					sessionId,
+					scope: args.scope ?? "visible",
+					hash,
+					lines: text.split("\n"),
+					meta: session.getMeta(),
+					lineNumbers: args.lineNumbers
+				})
+			}],
+			structuredContent: {
+				sessionId,
+				hash
+			}
+		};
+	});
+	tool("debug", "snapshot_view_ansi", "Capture a formatted ANSI snapshot view (includes meta + optional line numbers).", {
+		sessionId: z.string().min(1).optional(),
+		scope: z.enum(["visible", "buffer"]).optional(),
+		trimRight: z.boolean().optional(),
+		trimBottom: z.boolean().optional(),
+		maxLines: z.number().int().positive().optional(),
+		tailLines: z.number().int().positive().optional(),
+		lineNumbers: z.boolean().optional(),
+		mask: z.array(textMaskRuleSchema).optional()
+	}, {
+		title: "Snapshot View (ANSI)",
+		readOnlyHint: true,
+		idempotentHint: true
+	}, async (args, extra) => {
+		const sessionId = args.sessionId ?? getSelectedSessionId(extra);
+		if (!sessionId) return toolError("sessionId is required (provide sessionId or call select_session)");
+		const session = sessions.getSession(sessionId);
+		if (!session) return toolError(`session not found: ${sessionId}`);
+		if (args.maxLines !== void 0 && args.tailLines !== void 0) return toolError("snapshot_view_ansi: maxLines and tailLines are mutually exclusive");
+		let ansi;
+		let hash;
+		try {
+			({ansi, hash} = await session.snapshotAnsi({
+				scope: args.scope,
+				trimRight: args.trimRight,
+				trimBottom: args.trimBottom ?? true,
+				maxLines: args.maxLines,
+				tailLines: args.tailLines,
+				mask: args.mask
+			}));
+		} catch (error) {
+			return toolError(error.message);
+		}
+		return {
+			content: [{
+				type: "text",
+				text: formatSnapshotView({
+					sessionId,
+					scope: args.scope ?? "visible",
+					hash,
+					lines: ansi.split("\n"),
+					meta: session.getMeta(),
+					lineNumbers: args.lineNumbers
+				})
+			}],
+			structuredContent: {
+				sessionId,
+				hash
+			}
+		};
+	});
+	tool("script", "run_script", "Run a JSON/TS script via the runner and return artifact paths (prefer this for regression runs).", {
+		scriptPath: z.string().min(1),
+		artifactsDir: z.string().optional(),
+		stepsPath: z.string().optional(),
+		updateGoldens: z.boolean().optional()
+	}, {
+		title: "Run Script",
+		openWorldHint: true,
+		destructiveHint: true
+	}, async (args) => {
+		const result = await runScriptPath(args.scriptPath, {
+			artifactsDir: args.artifactsDir,
+			stepsPath: args.stepsPath,
+			updateGoldens: args.updateGoldens
+		});
+		if (!result.ok) return toolError(result.error, {
+			scriptName: result.scriptName,
+			artifactsDir: result.artifactsDir,
+			castPath: result.castPath,
+			reportPath: result.reportPath,
+			failureArtifacts: result.failureArtifacts
+		});
+		return {
+			content: [{
+				type: "text",
+				text: `ok artifacts=${result.artifactsDir}`
+			}],
+			structuredContent: result
+		};
+	});
+	tool("script", "run_all_scripts", "Run all ptywright scripts (JSON/TS) recursively and generate a Playwright-like suite report: index.html + run.summary.json. 用于：一键批量回归 / 生成总览报告 / CI。Call with no args to use defaults (dir='scripts', suite report in .tmp/run-all/). Returns reportPath+summaryPath; open reportPath in a browser to view. Tip: keep includeEntries='failures' (default) and maxEntries to avoid context bloat.", {
+		dir: z.string().optional(),
+		artifactsRoot: z.string().optional(),
+		stepsPath: z.string().optional(),
+		updateGoldens: z.boolean().optional(),
+		includeEntries: z.enum([
+			"none",
+			"failures",
+			"all"
+		]).optional(),
+		maxEntries: z.number().int().nonnegative().optional()
+	}, {
+		title: "Run All Scripts (Suite Report)",
+		openWorldHint: true,
+		destructiveHint: true
+	}, async (args) => {
+		try {
+			const includeEntries = args.includeEntries ?? "failures";
+			const maxEntries = args.maxEntries ?? 20;
+			const result = await runAllScripts({
+				dir: args.dir,
+				artifactsRoot: args.artifactsRoot,
+				stepsPath: args.stepsPath,
+				updateGoldens: args.updateGoldens
+			});
+			const failures = result.entries.filter((e) => !e.result.ok);
+			let entries = [];
+			if (includeEntries === "all") entries = result.entries;
+			else if (includeEntries === "failures") entries = failures;
+			let truncatedCount = 0;
+			if (entries.length > maxEntries) {
+				truncatedCount = entries.length - maxEntries;
+				entries = entries.slice(0, maxEntries);
+			}
+			const summaryLines = [
+				result.ok ? "ok" : "failed",
+				`count=${result.entries.length}`,
+				`failures=${failures.length}`,
+				`dir=${result.dir}`,
+				`entries=${entries.length}`,
+				`report=${result.reportPath}`,
+				`summary=${result.summaryPath}`,
+				truncatedCount > 0 ? `truncated=${truncatedCount}` : null
+			];
+			if (entries.length > 0 && failures.length > 0) for (const f of entries) {
+				if (f.result.ok) continue;
+				summaryLines.push(`- ${f.filePath}: ${f.result.error}`);
+			}
+			return {
+				content: [{
+					type: "text",
+					text: summaryLines.filter(Boolean).join("\n")
+				}],
+				structuredContent: {
+					ok: result.ok,
+					dir: result.dir,
+					suiteDir: result.suiteDir,
+					reportPath: result.reportPath,
+					summaryPath: result.summaryPath,
+					totalCount: result.entries.length,
+					failureCount: failures.length,
+					includeEntries,
+					maxEntries,
+					truncatedCount,
+					entries
+				}
+			};
+		} catch (error) {
+			return toolError(error.message);
+		}
+	});
+	tool("script", "generate_test_from_doc", "Generate test script from documentation (local file or URL). Parses Markdown/HTML/JSON docs to extract test steps and generates executable ptywright scripts.", {
+		source: z.string().min(1).describe("Document path (local file) or URL"),
+		sourceType: z.enum([
+			"local",
+			"url",
+			"auto"
+		]).optional().describe("Source type (auto-detected if not specified)"),
+		outputDir: z.string().optional().describe("Output directory for generated scripts"),
+		outputFormat: z.enum([
+			"json",
+			"ts",
+			"both"
+		]).optional().describe("Output format (default: both)"),
+		targetCommand: z.string().optional().describe("Command to test (overrides auto-detected command)"),
+		targetArgs: z.array(z.string()).optional().describe("Arguments for target command"),
+		name: z.string().optional().describe("Test name (auto-generated from doc title if not specified)"),
+		cols: z.number().int().positive().optional().describe("Terminal columns (default: 80)"),
+		rows: z.number().int().positive().optional().describe("Terminal rows (default: 24)")
+	}, {
+		title: "Generate Test from Documentation",
+		openWorldHint: true,
+		destructiveHint: true
+	}, async (args) => {
+		try {
+			const result = await generateTestFromDoc({
+				source: args.source,
+				sourceType: args.sourceType,
+				outputDir: args.outputDir,
+				outputFormat: args.outputFormat,
+				targetCommand: args.targetCommand,
+				targetArgs: args.targetArgs,
+				name: args.name,
+				cols: args.cols,
+				rows: args.rows
+			});
+			if (!result.ok) return toolError(result.error ?? "Failed to generate test", {
+				warnings: result.warnings,
+				parsed: result.parsed
+			});
+			return {
+				content: [{
+					type: "text",
+					text: [
+						`Generated test: ${result.name}`,
+						`Steps: ${result.stepCount}`,
+						result.jsonPath ? `JSON: ${result.jsonPath}` : null,
+						result.tsPath ? `TypeScript: ${result.tsPath}` : null,
+						result.warnings.length > 0 ? `Warnings: ${result.warnings.join("; ")}` : null
+					].filter(Boolean).join("\n")
+				}],
+				structuredContent: result
+			};
+		} catch (error) {
+			return toolError(error.message);
+		}
+	});
+	tool("recording", "start_script_recording", "Start recording MCP tool calls into a replayable script (with optional golden checkpoints via mark()).", {
+		name: z.string().min(1),
+		outPath: z.string().optional(),
+		goldenDir: z.string().optional(),
+		overwrite: z.boolean().optional(),
+		scope: z.enum(["visible", "buffer"]).optional(),
+		trimRight: z.boolean().optional(),
+		trimBottom: z.boolean().optional(),
+		mask: z.array(textMaskRuleSchema).optional()
+	}, {
+		title: "Start Script Recording",
+		openWorldHint: true
+	}, async (args) => {
+		try {
+			const status = recordings.start({
+				name: args.name,
+				outPath: args.outPath,
+				goldenDir: args.goldenDir,
+				overwrite: args.overwrite,
+				checkpoint: {
+					scope: args.scope ?? "visible",
+					trimRight: args.trimRight ?? true,
+					trimBottom: args.trimBottom ?? true,
+					mask: args.mask
+				}
+			});
+			return {
+				content: [{
+					type: "text",
+					text: `recording ${status.recordingId}`
+				}],
+				structuredContent: status
+			};
+		} catch (error) {
+			return toolError(error.message);
+		}
+	});
+	tool("recording", "stop_script_recording", "Stop recording and optionally write the script + goldens to disk.", {
+		recordingId: z.string().min(1),
+		writeFiles: z.boolean().optional()
+	}, {
+		title: "Stop Script Recording",
+		destructiveHint: true
+	}, async (args) => {
+		try {
+			const result = recordings.stop({
+				recordingId: args.recordingId,
+				writeFiles: args.writeFiles
+			});
+			return {
+				content: [{
+					type: "text",
+					text: `ok script=${result.scriptPath ?? ""}`
+				}],
+				structuredContent: {
+					scriptPath: result.scriptPath,
+					goldenPaths: result.goldenPaths
+				}
+			};
+		} catch (error) {
+			return toolError(error.message);
+		}
+	});
+	tool("core", "close_session", "Close a running session.", { sessionId: z.string().min(1).optional() }, {
+		title: "Close Session",
+		destructiveHint: true
+	}, async (args, extra) => {
+		const sessionId = args.sessionId ?? getSelectedSessionId(extra);
+		if (!sessionId) return toolError("sessionId is required (provide sessionId or call select_session)");
+		if (!sessions.closeSession(sessionId)) return toolError(`session not found: ${sessionId}`);
+		if (getSelectedSessionId(extra) === sessionId) clearSelectedSessionId(extra);
+		return { content: [{
+			type: "text",
+			text: "closed"
+		}] };
+	});
+	tool("core", "list_sessions", "List all active sessions.", {}, { title: "List Sessions" }, async (_args, _extra) => {
+		const all = sessions.listSessions().map((s) => ({
+			id: s.id,
+			cols: s.cols,
+			rows: s.rows,
+			meta: s.getMeta()
+		}));
+		return {
+			content: [{
+				type: "text",
+				text: JSON.stringify(all, null, 2)
+			}],
+			structuredContent: { sessions: all }
+		};
+	});
+	const routineStepSchema = z.object({
+		action: z.enum([
+			"sendText",
+			"pressKey",
+			"wait",
+			"assert",
+			"snapshot"
+		]),
+		text: z.string().optional(),
+		enter: z.boolean().optional(),
+		key: z.string().optional(),
+		waitFor: z.string().optional(),
+		regex: z.string().optional(),
+		timeoutMs: z.number().int().optional(),
+		description: z.string().optional()
+	});
+	tool("script", "run_routine", "PRIMARY INTERACTION TOOL. Execute a multi-step test scenario (type, key, wait, assert) in one go. Use this whenever asked to 'test', 'verify', 'do', or 'check' a workflow. It handles delays and snapshots automatically.", {
+		sessionId: z.string().min(1).optional(),
+		steps: z.array(routineStepSchema).min(1),
+		saveReport: z.boolean().optional(),
+		reportPath: z.string().optional()
+	}, {
+		title: "Run Routine",
+		openWorldHint: true
+	}, async (args, extra) => {
+		const sessionId = args.sessionId ?? getSelectedSessionId(extra);
+		if (!sessionId) return toolError("sessionId is required (provide sessionId or call select_session)");
+		const session = sessions.getSession(sessionId);
+		if (!session) return toolError(`session not found: ${sessionId}`);
+		const results = [];
+		let failed = false;
+		let failedStep = null;
+		for (let i = 0; i < args.steps.length; i++) {
+			const step = args.steps[i];
+			if (!step) continue;
+			const result = {
+				index: i + 1,
+				action: step.action,
+				description: step.description,
+				ok: true
+			};
+			try {
+				if (step.action === "sendText" && step.text !== void 0) session.sendText(step.text, { enter: step.enter });
+				else if (step.action === "pressKey" && step.key) session.pressKey(step.key);
+				else if (step.action === "wait") if (step.waitFor || step.regex) {
+					const regex = step.regex ? new RegExp(step.regex) : void 0;
+					if (!(await session.waitForText({
+						text: step.waitFor,
+						regex,
+						timeoutMs: step.timeoutMs ?? 1e4,
+						intervalMs: 100
+					})).found) throw new Error(`wait failed: ${step.waitFor || step.regex}`);
+				} else await session.waitForStableScreen({
+					timeoutMs: step.timeoutMs ?? 5e3,
+					quietMs: 300,
+					intervalMs: 80
+				});
+				else if (step.action === "assert") {
+					const regex = step.regex ? new RegExp(step.regex) : void 0;
+					if (!(await session.waitForText({
+						text: step.waitFor,
+						regex,
+						timeoutMs: 0,
+						intervalMs: 0
+					})).found) throw new Error(`assert failed: ${step.description || step.waitFor || step.regex}`);
+				}
+				const snapshot = await session.snapshotText({
+					scope: "visible",
+					trimRight: true,
+					trimBottom: true,
+					captureFrame: true
+				});
+				result.snapshot = snapshot.text;
+				result.hash = snapshot.hash;
+			} catch (error) {
+				result.ok = false;
+				result.error = error.message;
+				failed = true;
+				failedStep = i + 1;
+				try {
+					const snapshot = await session.snapshotText({
+						scope: "visible",
+						trimRight: true,
+						trimBottom: true,
+						captureFrame: true
+					});
+					result.snapshot = snapshot.text;
+					result.hash = snapshot.hash;
+				} catch {}
+			}
+			results.push(result);
+			if (failed) break;
+		}
+		const summary = failed ? `failed at step ${failedStep}: ${results[results.length - 1]?.error}` : `ok, ${results.length} steps completed`;
+		let reportPath = args.reportPath;
+		if (args.saveReport ?? true) try {
+			const html = await generateTraceReportHtml((await session.snapshotCast()).cast, {
+				scriptName: "routine",
+				result: {
+					ok: !failed,
+					error: results[results.length - 1]?.error
+				},
+				steps: results.map((r) => ({
+					index: r.index,
+					step: {
+						type: r.action,
+						description: r.description
+					},
+					ok: r.ok,
+					error: r.error,
+					after: r.snapshot ? {
+						text: r.snapshot,
+						hash: r.hash ?? "",
+						kind: "view"
+					} : void 0
+				}))
+			});
+			if (!reportPath) {
+				const tmpDir = join(tmpdir(), "ptywright-routines");
+				mkdirSync(tmpDir, { recursive: true });
+				reportPath = join(tmpDir, `routine-${sessionId}-${Date.now()}.html`);
+			}
+			writeFileSync(reportPath, html);
+			ensureAsciinemaPlayerAssets(reportPath);
+		} catch {}
+		return {
+			content: [{
+				type: "text",
+				text: reportPath ? `${summary}
+
+Report generated: ${reportPath}
+Open in browser to view step-by-step timeline.` : summary
+			}],
+			structuredContent: {
+				sessionId,
+				ok: !failed,
+				stepCount: results.length,
+				failedStep,
+				reportPath,
+				results
+			}
+		};
+	});
+	tool("core", "inspect_failure", "Inspect the last failure state of a session. Returns the last screen snapshot and any error information captured.", {
+		sessionId: z.string().min(1).optional(),
+		includeFrames: z.boolean().optional(),
+		maxFrames: z.number().int().positive().optional()
+	}, {
+		title: "Inspect Failure",
+		readOnlyHint: true,
+		idempotentHint: true
+	}, async (args, extra) => {
+		const sessionId = args.sessionId ?? getSelectedSessionId(extra);
+		if (!sessionId) return toolError("sessionId is required (provide sessionId or call select_session)");
+		const session = sessions.getSession(sessionId);
+		if (!session) return toolError(`session not found: ${sessionId}`);
+		const closeReason = session.getCloseReason();
+		const meta = session.getMeta();
+		let currentSnapshot = null;
+		try {
+			currentSnapshot = await session.snapshotText({
+				scope: "visible",
+				trimRight: true,
+				trimBottom: true,
+				captureFrame: true
+			});
+		} catch {}
+		const frames = session.getSnapshotFrames();
+		const includeFrames = args.includeFrames ?? false;
+		const maxFrames = args.maxFrames ?? 5;
+		const recentFrames = includeFrames ? frames.slice(-maxFrames) : [];
+		return {
+			content: [{
+				type: "text",
+				text: currentSnapshot ? formatSnapshotView({
+					sessionId,
+					scope: "visible",
+					hash: currentSnapshot.hash,
+					lines: currentSnapshot.text.split("\n"),
+					meta,
+					lineNumbers: true
+				}) : "(no snapshot available)"
+			}],
+			structuredContent: {
+				sessionId,
+				closeReason,
+				meta,
+				currentSnapshot: currentSnapshot ? {
+					text: currentSnapshot.text,
+					hash: currentSnapshot.hash
+				} : null,
+				recentFrames: recentFrames.map((f) => ({
+					atMs: f.atMs,
+					hash: f.hash
+				})),
+				isClosed: session.isClosed()
+			}
+		};
+	});
+	return {
+		server,
+		sessions
+	};
+}
+function resolveCapabilities(capabilities, envValue) {
+	const requested = capabilities?.length ? capabilities : parseCapabilitiesEnv(envValue);
+	const normalized = /* @__PURE__ */ new Set();
+	let all = false;
+	for (const cap of requested) {
+		if (cap === "all") {
+			all = true;
+			continue;
+		}
+		normalized.add(cap);
+	}
+	if (!all && normalized.size === 0) all = true;
+	return {
+		all,
+		enabled: normalized
+	};
+}
+function parseCapabilitiesEnv(envValue) {
+	if (!envValue?.trim()) return [];
+	const parts = envValue.split(/[,\s]+/g).map((p) => p.trim().toLowerCase()).filter(Boolean);
+	const out = [];
+	for (const p of parts) if (p === "all") out.push("all");
+	else if (p === "core") out.push("core");
+	else if (p === "debug") out.push("debug");
+	else if (p === "script" || p === "scripts" || p === "runner" || p === "run") out.push("script");
+	else if (p === "recording" || p === "record" || p === "rec") out.push("recording");
+	else throw new Error(`unknown PTYWRIGHT_CAPS capability: ${p}`);
+	return out;
+}
+function toolError(message, extra = {}) {
+	return {
+		isError: true,
+		content: [{
+			type: "text",
+			text: message
+		}],
+		structuredContent: {
+			error: message,
+			...extra
+		}
+	};
+}
+//#endregion
+export { readScriptManifestPath as a, resolveScriptManifestPath as c, resolveScriptRunSummaryPath as d, runScriptPath as f, findScriptSummaryManifest as i, validateScriptManifest as l, runAllScripts as n, relocateScriptManifestCommands as o, SCRIPT_MANIFEST_FILE_NAME as r, resolveManifestPrimaryPath as s, createPtywrightServer as t, readScriptRunSummaryPath as u };