ptywright 0.5.0 → 0.6.0

package/dist/agent.mjs

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

package/dist/bin/ptywright.mjs

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

package/dist/{cli-PnG6UR43.mjs → cli-IXmvK56U.mjs}

@@ -1,16 +1,16 @@
 import { n as loadPtywrightConfig } from "./config-bGg636EW.mjs";
-import { C as writeAgentManifestPath, D as escapeHtml, E as escapeAttribute, O as normalizeAgentFlowSpec, S as validateAgentManifestFiles, T as readAgentCassettePath, _ as formatArgv, b as isAgentManifestLike, c as launchAgentBrowser, d as AGENT_RUN_RECORD_SCHEMA_URL, f as agentRunModeSchema, g as writeAgentRunRecordPath, h as readAgentRunRecordPath, i as runAgentSpecPath, k as sanitizeArtifactName, l as createAgentTemplateSpec, m as isAgentRunRecordLike, n as replayAgentRecordPath, o as resolveAgentLaunchTarget, p as formatAgentArgv, s as normalizeAgentFlowSpecWithConfig, u as loadAgentSpec, v as AGENT_MANIFEST_FILE_NAME, w as isAgentCassetteLike, x as readAgentManifestPath, y as agentManifestPath } from "./runner-C1gPRyCM.mjs";
+import { C as writeAgentManifestPath, D as escapeHtml, E as escapeAttribute, O as normalizeAgentFlowSpec, S as validateAgentManifestFiles, T as readAgentCassettePath, _ as formatArgv, b as isAgentManifestLike, c as launchAgentBrowser, d as AGENT_RUN_RECORD_SCHEMA_URL, f as agentRunModeSchema, g as writeAgentRunRecordPath, h as readAgentRunRecordPath, i as runAgentSpecPath, k as sanitizeArtifactName, l as createAgentTemplateSpec, m as isAgentRunRecordLike, n as replayAgentRecordPath, o as resolveAgentLaunchTarget, p as formatAgentArgv, s as normalizeAgentFlowSpecWithConfig, u as loadAgentSpec, v as AGENT_MANIFEST_FILE_NAME, w as isAgentCassetteLike, x as readAgentManifestPath, y as agentManifestPath } from "./runner-GIEf0C6d.mjs";
 import { a as sameArgv, i as diffCommandMaps, r as formatZodIssues } from "./manifest_files-DW80c1H7.mjs";
 import { i as portableCliPath, n as mergeProcessEnv, o as relativeHref, s as samePath } from "./env-DPYHo-zH.mjs";
-import { d as resolvePtyBackend, u as createDefaultPtyAdapter } from "./runner-wW_DCBX7.mjs";
-import { a as resolveScriptManifestPath, c as relocateScriptManifestCommands, d as resolveScriptRunSummaryPath, f as runScriptPath, i as readScriptManifestPath, l as resolveManifestPrimaryPath$1, n as runAllScripts, o as validateScriptManifest, r as findScriptSummaryManifest, t as createPtywrightServer, u as readScriptRunSummaryPath } from "./server-DMnnXjWv.mjs";
-import { c as createPtyCassetteReplay, i as formatPtyCassetteInspectLines, l as readPtyCassettePath, o as inspectPtyCassettePath, r as createPtyCassetteRecorder, t as wrapPtyLike, v as validatePtyCassette } from "./pty_like-BjeBibSL.mjs";
+import { d as resolvePtyBackend, u as createDefaultPtyAdapter } from "./runner-BHXXwxYp.mjs";
+import { a as resolveScriptManifestPath, c as relocateScriptManifestCommands, d as resolveScriptRunSummaryPath, f as runScriptPath, i as readScriptManifestPath, l as resolveManifestPrimaryPath$1, n as runAllScripts, o as validateScriptManifest, r as findScriptSummaryManifest, t as createPtywrightServer, u as readScriptRunSummaryPath } from "./server-ceZ1-s_J.mjs";
+import { c as createPtyCassetteReplay, i as formatPtyCassetteInspectLines, l as readPtyCassettePath, o as inspectPtyCassettePath, r as createPtyCassetteRecorder, t as wrapPtyLike, v as validatePtyCassette } from "./pty_like-DWIlWGgA.mjs";
 import { existsSync, mkdirSync, readFileSync, readdirSync, statSync, writeFileSync } from "node:fs";
 import { basename, dirname, extname, isAbsolute, join, relative, resolve } from "node:path";
 import { z } from "zod";
+import { Buffer } from "node:buffer";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 import { WebStandardStreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/webStandardStreamableHttp.js";
-import { Buffer } from "node:buffer";
 //#region src/agent/check_summary_schema.ts
 const AGENT_CHECK_SCHEMA_URL = "https://ptywright.local/schemas/ptywright-agent-check.schema.json";
 const countSummarySchema$1 = z.object({

package/dist/cli.mjs

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

package/dist/data-sdbf3IDh.mjs

@@ -0,0 +1,18 @@
+import { Buffer } from "node:buffer";
+//#region src/pty-cassette/data.ts
+function dataToBytes(data) {
+	if (typeof data === "string") return Buffer.from(data, "utf8");
+	if (data instanceof ArrayBuffer) return new Uint8Array(data);
+	return data;
+}
+function dataToBase64(data) {
+	return Buffer.from(dataToBytes(data)).toString("base64");
+}
+function base64ToBytes(dataBase64) {
+	return Buffer.from(dataBase64, "base64");
+}
+function byteLength(data) {
+	return dataToBytes(data).byteLength;
+}
+//#endregion
+export { dataToBytes as i, byteLength as n, dataToBase64 as r, base64ToBytes as t };

package/dist/index.mjs

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

package/dist/mcp.mjs

@@ -1,2 +1,2 @@
-import { t as createPtywrightServer } from "./server-DMnnXjWv.mjs";
+import { t as createPtywrightServer } from "./server-ceZ1-s_J.mjs";
 export { createPtywrightServer };

package/dist/pty-cassette.mjs

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

package/dist/{pty_like-BjeBibSL.mjs → pty_like-DWIlWGgA.mjs}

@@ -1,23 +1,7 @@
+import { n as byteLength, r as dataToBase64, t as base64ToBytes } from "./data-sdbf3IDh.mjs";
 import { mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import { dirname } from "node:path";
 import { z } from "zod";
-import { Buffer } from "node:buffer";
-//#region src/pty-cassette/data.ts
-function dataToBytes(data) {
-	if (typeof data === "string") return Buffer.from(data, "utf8");
-	if (data instanceof ArrayBuffer) return new Uint8Array(data);
-	return data;
-}
-function dataToBase64(data) {
-	return Buffer.from(dataToBytes(data)).toString("base64");
-}
-function base64ToBytes(dataBase64) {
-	return Buffer.from(dataBase64, "base64");
-}
-function byteLength(data) {
-	return dataToBytes(data).byteLength;
-}
-//#endregion
 //#region src/pty-cassette/schema.ts
 const PTY_CASSETTE_SCHEMA_URL = "https://ptywright.local/schemas/ptywright-pty-cassette.schema.json";
 const base64Schema = z.string().refine((value) => value.length % 4 === 0 && /^[A-Za-z0-9+/]*={0,2}$/.test(value), { message: "expected base64-encoded data" });
@@ -401,4 +385,4 @@ function dispose(disposable) {
 	disposable.dispose();
 }
 //#endregion
-export { dataToBytes as S, ptyCassetteSchema as _, inspectPtyCassette as a, byteLength as b, createPtyCassetteReplay as c, PTY_CASSETTE_SCHEMA_URL as d, normalizePtyCassette as f, ptyCassetteResizeEventSchema as g, ptyCassetteExitEventSchema as h, formatPtyCassetteInspectLines as i, readPtyCassettePath as l, ptyCassetteEventSchema as m, PtyCassetteRecorder as n, inspectPtyCassettePath as o, ptyCassetteDataEventSchema as p, createPtyCassetteRecorder as r, PtyCassetteReplay as s, wrapPtyLike as t, writePtyCassettePath as u, validatePtyCassette as v, dataToBase64 as x, base64ToBytes as y };
+export { ptyCassetteSchema as _, inspectPtyCassette as a, createPtyCassetteReplay as c, PTY_CASSETTE_SCHEMA_URL as d, normalizePtyCassette as f, ptyCassetteResizeEventSchema as g, ptyCassetteExitEventSchema as h, formatPtyCassetteInspectLines as i, readPtyCassettePath as l, ptyCassetteEventSchema as m, PtyCassetteRecorder as n, inspectPtyCassettePath as o, ptyCassetteDataEventSchema as p, createPtyCassetteRecorder as r, PtyCassetteReplay as s, wrapPtyLike as t, writePtyCassettePath as u, validatePtyCassette as v };

package/dist/{runner-wW_DCBX7.mjs → runner-BHXXwxYp.mjs}

@@ -1,12 +1,13 @@
 import { n as mergeProcessEnv, o as relativeHref, t as envTruthy } from "./env-DPYHo-zH.mjs";
-import { a as fnv1a32, c as extractStyle, d as styleKey, f as encodeSgrMouse, i as TraceRecorder, l as findMeaningfulEndCol, n as sleep, o as snapshotGrid, p as encodeKey, r as applyTextMaskRules, s as snapshotLines, t as TerminalSession, u as isDefaultStyle } from "./terminal_session-DJKr-O3X.mjs";
+import { a as styleKey, i as isDefaultStyle, n as extractStyle, r as findMeaningfulEndCol } from "./style-BtIUv5H0.mjs";
+import { a as fnv1a32, c as encodeSgrMouse, i as TraceRecorder, l as encodeKey, n as sleep, o as snapshotGrid, r as applyTextMaskRules, s as snapshotLines, t as TerminalSession } from "./terminal_session-MX_vWpRG.mjs";
 import { createRequire } from "node:module";
 import { copyFileSync, existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import { basename, dirname, extname, isAbsolute, join, resolve } from "node:path";
 import { pathToFileURL } from "node:url";
 import { z } from "zod";
-import { spawn } from "bun-pty";
 import { Terminal } from "@xterm/headless";
+import { spawn } from "bun-pty";
 //#region src/pty/bun_pty_adapter.ts
 function toForkOptions(options) {
 	return {

package/dist/{runner-C1gPRyCM.mjs → runner-GIEf0C6d.mjs}

@@ -1,5 +1,7 @@
 import { a as sameArgv, n as validateManifestFiles, r as formatZodIssues, t as collectManifestFiles } from "./manifest_files-DW80c1H7.mjs";
 import { t as envTruthy } from "./env-DPYHo-zH.mjs";
+import { t as base64ToBytes } from "./data-sdbf3IDh.mjs";
+import { a as styleKey, i as isDefaultStyle, n as extractStyle, r as findMeaningfulEndCol, t as DEFAULT_STYLE } from "./style-BtIUv5H0.mjs";
 import { createRequire } from "node:module";
 import { copyFileSync, existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import { basename, dirname, extname, isAbsolute, join, relative, resolve } from "node:path";
@@ -7,6 +9,7 @@ import { pathToFileURL } from "node:url";
 import { z } from "zod";
 import { createServer } from "node:http";
 import { chromium } from "playwright";
+import { Terminal } from "@xterm/headless";
 import { spawn } from "node:child_process";
 //#region src/agent/normalize.ts
 function applyAgentMasks(input, rules = [], options = {}) {
@@ -1390,23 +1393,23 @@ function renderArtifactViewerShellCss() {
       }
       .viewer-stage {
         display: grid;
-        grid-template-columns: max-content;
-        grid-template-rows: max-content;
+        grid-template-columns: minmax(0, 1fr);
+        grid-template-rows: minmax(0, 1fr);
         min-width: 0;
         min-height: 0;
-        justify-content: start;
+        justify-items: center;
         align-content: start;
-        overflow: auto;
+        overflow: hidden;
         background:
           radial-gradient(circle at top left, rgba(121, 192, 255, 0.1), transparent 32%),
           #060a13;
         padding: 14px;
       }
       .viewer-viewport {
-        width: var(--config-viewport-width);
-        height: var(--config-viewport-height);
-        max-width: none;
-        max-height: none;
+        width: min(var(--config-viewport-width), 100%);
+        height: min(var(--config-viewport-height), 100%);
+        max-width: 100%;
+        max-height: 100%;
         overflow: auto;
         overscroll-behavior: contain;
         border: 0;
@@ -1416,7 +1419,7 @@ function renderArtifactViewerShellCss() {
         box-shadow: 0 18px 52px rgba(0, 0, 0, 0.34);
       }
       .viewer-viewport[data-mobile="true"] {
-        width: var(--config-viewport-width);
+        width: min(var(--config-viewport-width), 100%);
       }
       .dom-viewport {
         overflow: hidden;
@@ -1455,8 +1458,8 @@ function renderArtifactViewerShellCss() {
           padding: 0;
         }
         .viewer-viewport {
-          width: var(--config-viewport-width);
-          height: var(--config-viewport-height);
+          width: min(var(--config-viewport-width), 100%);
+          height: min(var(--config-viewport-height), 100%);
           border-radius: 0;
         }
       }`;
@@ -1511,22 +1514,19 @@ function renderConfiguredViewportStyle(viewport) {
 	return `--config-viewport-width: ${viewport.width}px; --config-viewport-height: ${viewport.height}px;`;
 }
 //#endregion
-//#region src/agent/report_view_options.ts
-function isMobileViewport(viewport) {
-	return Boolean(viewport?.isMobile || viewport?.hasTouch || (viewport?.width ?? 9999) <= 720);
+//#region src/agent/report_launch_args.ts
+function readReportLaunchArgSets(result) {
+	return [readFlowLaunchArgs(result.flowPath), readCassetteLaunchArgs(result.replaySourceCassettePath ?? result.cassettePath)];
 }
-function resolveReportViewOptions(result) {
-	const launchArgSets = [readFlowLaunchArgs(result.flowPath), readCassetteLaunchArgs(result.replaySourceCassettePath ?? result.cassettePath)];
-	const screenModeArg = readFlagValueFromArgSets(launchArgSets, "--experimental-screen-mode");
-	const themeArg = readFlagValueFromArgSets(launchArgSets, "--theme");
-	const fontSizeArg = readFlagValueFromArgSets(launchArgSets, "--font-size");
-	const lineHeightArg = readFlagValueFromArgSets(launchArgSets, "--line-height");
-	return {
-		fontSize: parsePositiveNumber(fontSizeArg) ?? 15,
-		lineHeight: parsePositiveNumber(lineHeightArg) ?? 1.6,
-		screenMode: screenModeArg && screenModeArg !== "termvision" ? "plain" : "termvision",
-		theme: themeArg === "light" ? "light" : "dark"
-	};
+function readFlagValueFromArgSets(argSets, flag) {
+	for (const args of argSets) {
+		const value = readFlagValue(args, flag);
+		if (value !== void 0) return value;
+	}
+}
+function readFlagValue(args, flag) {
+	const index = args.indexOf(flag);
+	return index >= 0 ? args[index + 1] : void 0;
 }
 function readCassetteLaunchArgs(cassettePath) {
 	try {
@@ -1545,21 +1545,41 @@ function readFlowLaunchArgs(flowPath) {
 function normalizeStringArray(value) {
 	return Array.isArray(value) ? value.filter((item) => typeof item === "string") : [];
 }
-function readFlagValueFromArgSets(argSets, flag) {
-	for (const args of argSets) {
-		const value = readFlagValue(args, flag);
-		if (value !== void 0) return value;
-	}
+//#endregion
+//#region src/agent/report_view_options.ts
+function isMobileViewport(viewport) {
+	return Boolean(viewport?.isMobile || viewport?.hasTouch || (viewport?.width ?? 9999) <= 720);
 }
-function readFlagValue(args, flag) {
-	const index = args.indexOf(flag);
-	return index >= 0 ? args[index + 1] : void 0;
+function resolveReportViewOptions(result, config) {
+	const launchArgSets = readReportLaunchArgSets(result);
+	const ptyReplayArg = readFlagValueFromArgSets(launchArgSets, "--pty-replay");
+	const screenModeArg = readFlagValueFromArgSets(launchArgSets, "--experimental-screen-mode");
+	const themeArg = readFlagValueFromArgSets(launchArgSets, "--theme");
+	const fontSizeArg = readFlagValueFromArgSets(launchArgSets, "--font-size");
+	const lineHeightArg = readFlagValueFromArgSets(launchArgSets, "--line-height");
+	const stableFrameConfig = resolveStableFrameConfig$1(config, result.name);
+	const themeOverride = ptyReplayArg && stableFrameConfig.enabled !== false && !stableFrameConfig.skip ? stableFrameConfig.theme : void 0;
+	return {
+		fontSize: parsePositiveNumber(fontSizeArg) ?? 15,
+		lineHeight: parsePositiveNumber(lineHeightArg) ?? 1.6,
+		screenMode: screenModeArg && screenModeArg !== "termvision" ? "plain" : "termvision",
+		theme: themeOverride ?? (themeArg === "light" ? "light" : "dark")
+	};
 }
 function parsePositiveNumber(value) {
 	if (value === void 0) return void 0;
 	const parsed = Number(value);
 	return Number.isFinite(parsed) && parsed > 0 ? parsed : void 0;
 }
+function resolveStableFrameConfig$1(config, flowName) {
+	const stableFrames = config?.agent?.report?.stableFrames;
+	const flowConfig = stableFrames?.flows?.[flowName];
+	return {
+		enabled: flowConfig?.enabled ?? stableFrames?.enabled,
+		skip: flowConfig?.skip ?? stableFrames?.skip,
+		theme: flowConfig?.theme ?? stableFrames?.theme ?? "dark"
+	};
+}
 //#endregion
 //#region src/agent/report_artifact_viewer.ts
 function renderArtifactViewerHtml(args) {
@@ -1584,6 +1604,358 @@ function renderArtifactViewerHtml(args) {
 	});
 }
 //#endregion
+//#region src/agent/report_pty_stable_frame.ts
+async function extractPtyReplayStableFrameForReport(args) {
+	const replayPathArg = readFlagValueFromArgSets(readReportLaunchArgSets(args.result), "--pty-replay");
+	if (!replayPathArg) return null;
+	const config = resolveStableFrameConfig(args.config, args.result.name);
+	if (config.enabled === false || config.skip) return null;
+	const replayPath = resolvePtyReplayPath(replayPathArg, args.config);
+	if (!existsSync(replayPath)) return null;
+	const recording = JSON.parse(readFileSync(replayPath, "utf8"));
+	const events = Array.isArray(recording.events) ? recording.events : [];
+	const firstResize = events.find((event) => event.type === "resize");
+	const terminal = new Terminal({
+		allowProposedApi: true,
+		cols: config.cols ?? recording.terminal?.cols ?? recording.command?.cols ?? recording.cols ?? firstResize?.cols ?? 80,
+		convertEol: true,
+		rows: config.rows ?? recording.terminal?.rows ?? recording.command?.rows ?? recording.rows ?? firstResize?.rows ?? 24,
+		scrollback: 2e4
+	});
+	try {
+		return await extractStableFrame({
+			config,
+			events,
+			terminal
+		});
+	} finally {
+		terminal.dispose();
+	}
+}
+function renderPtyReplayStableFramePreviewDocument(args) {
+	const targetCols = resolveTargetCols({
+		config: resolveStableFrameConfig(args.config, args.flowName),
+		fontSize: args.viewOptions.fontSize,
+		frameCols: args.frame.cols,
+		viewport: args.viewport
+	});
+	const body = renderAittyPreviewBody({
+		snapshot: renderStableFrameDom(args.frame, targetCols),
+		snapshotLayout: {
+			cols: targetCols,
+			fontSize: args.viewOptions.fontSize,
+			lineHeight: args.viewOptions.lineHeight,
+			paddingInline: isMobileViewport(args.viewport) ? 16 : 32,
+			rows: args.frame.rows
+		},
+		viewOptions: args.viewOptions
+	});
+	const style = renderAittyPreviewCss(args.viewOptions);
+	const assetTags = renderAittyPreviewAssetTags(args.aittyAssets);
+	return `<!doctype html>
+<html lang="en" data-theme="${escapeAttribute(args.viewOptions.theme)}">
+  <head>
+    <meta charset="utf-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1, viewport-fit=cover" />
+    <title>stable-frame preview (atMs=${args.frame.atMs})</title>
+${assetTags}    <style>
+${style}
+    </style>
+  </head>
+  <body>
+${body}
+  </body>
+</html>`;
+}
+function resolveStableFrameConfig(config, flowName) {
+	const stableFrames = config?.agent?.report?.stableFrames;
+	const flowConfig = stableFrames?.flows?.[flowName];
+	return {
+		...stableFrames,
+		...flowConfig,
+		stableMs: flowConfig?.stableMs ?? stableFrames?.stableMs ?? 200,
+		theme: flowConfig?.theme ?? stableFrames?.theme ?? "dark",
+		viewportOnly: flowConfig?.viewportOnly ?? stableFrames?.viewportOnly ?? false,
+		viewportTargets: {
+			...stableFrames?.viewportTargets,
+			...flowConfig?.viewportTargets
+		}
+	};
+}
+function resolvePtyReplayPath(replayPathArg, config) {
+	if (isAbsolute(replayPathArg)) return replayPathArg;
+	return resolve(config?.rootDir ?? process.cwd(), replayPathArg);
+}
+async function extractStableFrame(args) {
+	const { config, events, terminal } = args;
+	const targetFrameIndex = config.frameIndex;
+	const matcher = createStableFrameMatcher(config);
+	let matchedFrame = null;
+	const retainedFrames = [];
+	const retainCount = targetFrameIndex === void 0 ? 24 : targetFrameIndex < 0 ? -targetFrameIndex : 1;
+	let totalFrames = 0;
+	let pendingDirtySinceMs = null;
+	let lastEventAtMs = 0;
+	const captureFrame = (atMs, reason) => {
+		const shouldRetain = targetFrameIndex === void 0 || targetFrameIndex >= 0 && totalFrames === targetFrameIndex || targetFrameIndex < 0;
+		if (shouldRetain || matcher) {
+			const frame = {
+				...snapshotTerminalFrame(terminal, {
+					atMs,
+					index: totalFrames,
+					reason,
+					viewportOnly: config.viewportOnly
+				}),
+				score: scoreTerminalFrame(terminal)
+			};
+			if (matcher?.matches(stableFrameText(frame))) {
+				if (matcher.mode === "last" || !matchedFrame) matchedFrame = frame;
+			}
+			if (shouldRetain) retainedFrames.push(frame);
+			if (retainedFrames.length > retainCount) retainedFrames.splice(0, retainedFrames.length - retainCount);
+		}
+		totalFrames += 1;
+		pendingDirtySinceMs = null;
+	};
+	const flushIfStable = (nowMs) => {
+		if (pendingDirtySinceMs === null) return;
+		if (nowMs - pendingDirtySinceMs >= config.stableMs) captureFrame(pendingDirtySinceMs, "stable");
+	};
+	for (const event of events) {
+		const atMs = event.atMs ?? lastEventAtMs;
+		flushIfStable(atMs);
+		lastEventAtMs = atMs;
+		if (event.type === "output" && event.dataBase64) {
+			await writeTerminal(terminal, base64ToBytes(event.dataBase64));
+			pendingDirtySinceMs = pendingDirtySinceMs ?? atMs;
+			continue;
+		}
+		if (event.type === "resize" && event.cols && event.rows) {
+			terminal.resize(event.cols, event.rows);
+			pendingDirtySinceMs = pendingDirtySinceMs ?? atMs;
+			continue;
+		}
+		if (event.type === "exit") flushIfStable(atMs);
+	}
+	flushIfStable(lastEventAtMs + config.stableMs);
+	if (totalFrames === 0) captureFrame(lastEventAtMs, "final");
+	if (targetFrameIndex !== void 0 && targetFrameIndex >= 0) {
+		const exact = retainedFrames.find((frame) => frame.index === targetFrameIndex);
+		if (exact) return exact;
+		return null;
+	}
+	if (targetFrameIndex !== void 0 && targetFrameIndex < 0) {
+		const resolved = totalFrames + targetFrameIndex;
+		const exact = retainedFrames.find((frame) => frame.index === resolved);
+		if (exact) return exact;
+	}
+	if (matchedFrame) return matchedFrame;
+	return chooseBestStableFrame(retainedFrames);
+}
+function writeTerminal(terminal, data) {
+	return new Promise((resolveWrite) => {
+		terminal.write(data, resolveWrite);
+	});
+}
+function snapshotTerminalFrame(terminal, options) {
+	const buffer = terminal.buffer.active;
+	const startY = options.viewportOnly ? buffer.viewportY : 0;
+	const count = options.viewportOnly ? terminal.rows : buffer.length;
+	const logicalLines = [];
+	for (let offset = 0; offset < count; offset += 1) {
+		const y = startY + offset;
+		const line = buffer.getLine(y);
+		const cells = readStableLineCells(terminal, y);
+		const live = options.viewportOnly || y >= buffer.viewportY;
+		const previous = logicalLines.at(-1);
+		if (line?.isWrapped && previous) {
+			previous.cells.push(...cells);
+			previous.live = previous.live || live;
+			previous.physicalRows += 1;
+			continue;
+		}
+		logicalLines.push({
+			cells,
+			live,
+			physicalRows: 1
+		});
+	}
+	return {
+		atMs: options.atMs,
+		cols: terminal.cols,
+		index: options.index,
+		lines: logicalLines,
+		reason: options.reason,
+		rows: terminal.rows
+	};
+}
+function readStableLineCells(terminal, y) {
+	const buffer = terminal.buffer.active;
+	const nullCell = buffer.getNullCell();
+	const line = buffer.getLine(y);
+	const endCol = findMeaningfulEndCol(line, terminal.cols, nullCell);
+	const cells = [];
+	for (let x = 0; x < endCol; x += 1) {
+		const cell = line?.getCell(x, nullCell);
+		if (!cell) {
+			cells.push({
+				style: DEFAULT_STYLE,
+				text: " ",
+				width: 1
+			});
+			continue;
+		}
+		const width = cell.getWidth();
+		if (width === 0) continue;
+		cells.push({
+			style: extractStyle(cell),
+			text: cell.getChars() || " ",
+			width
+		});
+	}
+	return cells;
+}
+function scoreTerminalFrame(terminal) {
+	const buffer = terminal.buffer.active;
+	const nullCell = buffer.getNullCell();
+	let score = 0;
+	for (let y = 0; y < buffer.length; y += 1) {
+		const endCol = findMeaningfulEndCol(buffer.getLine(y), terminal.cols, nullCell);
+		score += endCol;
+	}
+	return score;
+}
+function chooseBestStableFrame(frames) {
+	return frames.filter((frame) => frame.score > 0).at(-1) ?? frames.at(-1) ?? null;
+}
+function createStableFrameMatcher(config) {
+	const matchText = toStringArray(config.matchText);
+	const matchRegex = toStringArray(config.matchRegex).map((pattern) => {
+		try {
+			return new RegExp(pattern);
+		} catch (error) {
+			throw new Error(`invalid agent.report.stableFrames.matchRegex pattern ${JSON.stringify(pattern)}: ${String(error)}`);
+		}
+	});
+	if (matchText.length === 0 && matchRegex.length === 0) return null;
+	return {
+		mode: config.matchMode ?? "last",
+		matches: (text) => matchText.some((needle) => text.includes(needle)) || matchRegex.some((regex) => regex.test(text))
+	};
+}
+function stableFrameText(frame) {
+	return frame.lines.map((line) => line.cells.map((cell) => cell.text).join("").trimEnd()).join("\n");
+}
+function toStringArray(value) {
+	if (value === void 0) return [];
+	return Array.isArray(value) ? value : [value];
+}
+function resolveTargetCols(args) {
+	const explicit = args.viewport ? args.config.viewportTargets?.[args.viewport.name] : void 0;
+	if (typeof explicit === "number" && Number.isFinite(explicit) && explicit > 0) return Math.trunc(explicit);
+	if (explicit === null) return args.frameCols;
+	if (isMobileViewport(args.viewport)) {
+		const width = args.viewport?.width ?? 390;
+		const cellWidth = Math.max(1, args.fontSize * .6);
+		return Math.max(20, Math.floor(width / cellWidth));
+	}
+	return args.frameCols;
+}
+function renderStableFrameDom(frame, targetCols) {
+	let html = "";
+	let totalRows = 0;
+	let wideBlockId = 0;
+	for (const line of frame.lines) {
+		const lineCols = Math.max(targetCols, cellsDisplayWidth(line.cells));
+		if (lineCols > targetCols || line.physicalRows > 1) {
+			wideBlockId += 1;
+			html += `<div class="term-wide-row-block" data-aitty-wide-block="true" data-aitty-wide-block-id="${wideBlockId}" data-aitty-wide-block-kind="viewport-pan" style="--aitty-wide-block-cols: ${lineCols}">`;
+			html += renderStableFrameRow(line, lineCols, totalRows);
+			html += "</div>";
+		} else html += renderStableFrameRow(line, targetCols, totalRows);
+		totalRows += 1;
+	}
+	return `<div class="term-grid" data-cols="${targetCols}" data-rows="${totalRows}" style="--term-cols: ${targetCols}; --term-rows: ${totalRows};">${html}</div>`;
+}
+function renderStableFrameRow(line, lineCols, lineIndex) {
+	return `<div class="${line.live ? "term-row" : "term-row term-scrollback-row"}"${line.live ? ` data-aitty-live-grid-row="${lineIndex + 1}"` : ""} data-aitty-line-cols="${lineCols}">${renderStableFrameCells(line.cells, lineCols)}</div>`;
+}
+function renderStableFrameCells(cells, lineCols) {
+	const out = [];
+	let usedCols = 0;
+	let runText = "";
+	let runWidth = 0;
+	let runStyle = null;
+	let runKey = null;
+	const flush = () => {
+		if (runText === "" && runWidth === 0) return;
+		out.push(renderSpan(runText, runWidth, runStyle ?? DEFAULT_STYLE));
+		runText = "";
+		runWidth = 0;
+		runStyle = null;
+		runKey = null;
+	};
+	for (const cell of cells) {
+		const key = styleKey(cell.style);
+		const wide = cell.width !== 1;
+		if (!wide && runKey === key) {
+			runText += cell.text;
+			runWidth += cell.width;
+			usedCols += cell.width;
+			continue;
+		}
+		flush();
+		if (wide) {
+			out.push(renderSpan(cell.text, cell.width, cell.style, "term-wide"));
+			usedCols += cell.width;
+			continue;
+		}
+		runText = cell.text;
+		runWidth = cell.width;
+		runStyle = cell.style;
+		runKey = key;
+		usedCols += cell.width;
+	}
+	flush();
+	const remaining = lineCols - usedCols;
+	if (remaining > 0) out.push(renderSpan("", remaining, DEFAULT_STYLE));
+	return out.join("");
+}
+function renderSpan(text, width, style, className) {
+	const declarations = styleDeclarations(style);
+	declarations.push(widthDeclaration(width));
+	if (className === "term-wide") declarations.push("overflow: hidden");
+	return `<span${className ? ` class="${escapeAttribute(className)}"` : ""} style="${escapeAttribute(declarations.join("; "))}">${escapeHtml(text)}</span>`;
+}
+function styleDeclarations(style) {
+	if (isDefaultStyle(style)) return [];
+	const declarations = [];
+	const fg = colorToCss(style.fg);
+	const bg = colorToCss(style.bg);
+	if (fg) declarations.push(`color: ${fg}`);
+	if (bg) declarations.push(`background-color: ${bg}`);
+	if (style.bold) declarations.push("font-weight: 700");
+	if (style.dim) declarations.push("opacity: 0.72");
+	if (style.italic) declarations.push("font-style: italic");
+	const decorations = [style.underline ? "underline" : "", style.strikethrough ? "line-through" : ""].filter(Boolean);
+	if (decorations.length > 0) declarations.push(`text-decoration: ${decorations.join(" ")}`);
+	if (style.inverse) declarations.push("filter: invert(1)");
+	return declarations;
+}
+function colorToCss(color) {
+	if (color.mode === "default") return null;
+	if (color.mode === "palette") return `var(--term-color-${color.value})`;
+	const value = color.value;
+	return `rgb(${value >> 16 & 255},${value >> 8 & 255},${value & 255})`;
+}
+function widthDeclaration(width) {
+	if (width <= 1) return "width: var(--term-cell-width, 1ch)";
+	return `width: calc(var(--term-cell-width, 1ch) * ${width})`;
+}
+function cellsDisplayWidth(cells) {
+	return cells.reduce((sum, cell) => sum + cell.width, 0);
+}
+//#endregion
 //#region src/agent/report_terminal_layout.ts
 function resolveTerminalSnapshotLayout(snapshot, viewport, viewOptions) {
 	const cols = inferTerminalCols(snapshot);
@@ -1635,9 +2007,9 @@ ${body}
 }
 //#endregion
 //#region src/agent/report_artifact_writer.ts
-function writeArtifactViewerPages(result) {
+async function writeArtifactViewerPages(result, options = {}) {
 	const viewportsByName = new Map(result.viewports.map((viewport) => [viewport.name, viewport]));
-	const viewOptions = resolveReportViewOptions(result);
+	const viewOptions = resolveReportViewOptions(result, options.config);
 	const readableArtifacts = [];
 	for (const artifact of result.artifacts) {
 		const viewerPath = artifactViewerPath(artifact);
@@ -1657,12 +2029,25 @@ function writeArtifactViewerPages(result) {
 		reportPath: result.reportPath
 	}) : null;
 	const writtenDomPreviewPaths = /* @__PURE__ */ new Set();
+	const ptyReplayStableFrame = aittyAssets ? await extractPtyReplayStableFrameForReport({
+		config: options.config,
+		result
+	}) : null;
 	if (aittyAssets) for (const { artifact, content } of readableArtifacts) {
 		if (artifact.kind !== "dom") continue;
 		const viewport = viewportsByName.get(artifact.viewport);
 		const domPreviewPath = artifactDomPreviewPath(artifact);
+		const aittyPreviewAssets = resolveAittyPreviewAssets(domPreviewPath, aittyAssets, result.artifactsDir);
+		const previewDocument = ptyReplayStableFrame ? renderPtyReplayStableFramePreviewDocument({
+			aittyAssets: aittyPreviewAssets,
+			config: options.config,
+			flowName: result.name,
+			frame: ptyReplayStableFrame,
+			viewOptions,
+			viewport
+		}) : renderDomPreviewDocument(content, viewport, viewOptions, aittyPreviewAssets);
 		mkdirSync(dirname(domPreviewPath), { recursive: true });
-		writeFileSync(domPreviewPath, renderDomPreviewDocument(content, viewport, viewOptions, resolveAittyPreviewAssets(domPreviewPath, aittyAssets, result.artifactsDir)), "utf8");
+		writeFileSync(domPreviewPath, previewDocument, "utf8");
 		writtenDomPreviewPaths.add(domPreviewPath);
 	}
 	for (const { artifact, content, viewerPath } of readableArtifacts) {
@@ -2045,9 +2430,9 @@ ${renderAgentReportCss()}
 }
 //#endregion
 //#region src/agent/report.ts
-function writeAgentReport(path, result) {
+async function writeAgentReport(path, result, options = {}) {
 	mkdirSync(dirname(path), { recursive: true });
-	writeArtifactViewerPages(result);
+	await writeArtifactViewerPages(result, options);
 	writeFileSync(path, renderAgentReportHtml(result), "utf8");
 }
 //#endregion
@@ -2797,7 +3182,7 @@ async function runAgentSpec(input, options = {}) {
 		else writeFileSync(cassettePath, JSON.stringify(cassette, null, 2) + "\n", "utf8");
 		result.cassetteFrameCount = cassette.frames.length;
 		writeRunRecord(result, spec);
-		writeAgentReport(reportPath, result);
+		await writeAgentReport(reportPath, result, { config: options.config });
 		writeRunManifest(result);
 	}
 	return result;

package/dist/script.mjs

@@ -1,2 +1,2 @@
-import { n as runScriptFile, t as runScript } from "./runner-wW_DCBX7.mjs";
+import { n as runScriptFile, t as runScript } from "./runner-BHXXwxYp.mjs";
 export { runScript, runScriptFile };

package/dist/{server-DMnnXjWv.mjs → server-ceZ1-s_J.mjs}

@@ -1,6 +1,6 @@
 import { a as sameArgv, i as diffCommandMaps, n as validateManifestFiles, r as formatZodIssues, t as collectManifestFiles } from "./manifest_files-DW80c1H7.mjs";
 import { i as portableCliPath, o as relativeHref, r as normalizePath, s as samePath } from "./env-DPYHo-zH.mjs";
-import { a as jsonForHtml, c as scriptSchema, i as escapeHtml, l as SessionManager, o as ensureAsciinemaPlayerAssets, r as generateTraceReportHtml, s as formatSnapshotView, t as runScript } from "./runner-wW_DCBX7.mjs";
+import { a as jsonForHtml, c as scriptSchema, i as escapeHtml, l as SessionManager, o as ensureAsciinemaPlayerAssets, r as generateTraceReportHtml, s as formatSnapshotView, t as runScript } from "./runner-BHXXwxYp.mjs";
 import { existsSync, mkdirSync, readFileSync, readdirSync, statSync, writeFileSync } from "node:fs";
 import { basename, dirname, extname, isAbsolute, join, relative, resolve } from "node:path";
 import { pathToFileURL } from "node:url";
@@ -144,7 +144,7 @@ var ScriptRecordingManager = class {
 };
 //#endregion
 //#region package.json
-var version = "0.5.0";
+var version = "0.6.0";
 //#endregion
 //#region src/mcp/tool_result.ts
 function toolError(message, extra = {}) {

package/dist/session.mjs

@@ -1,2 +1,2 @@
-import { t as TerminalSession } from "./terminal_session-DJKr-O3X.mjs";
+import { t as TerminalSession } from "./terminal_session-MX_vWpRG.mjs";
 export { TerminalSession };

package/dist/style-BtIUv5H0.mjs

@@ -0,0 +1,65 @@
+//#region src/terminal/style.ts
+const DEFAULT_STYLE = {
+	fg: { mode: "default" },
+	bg: { mode: "default" },
+	bold: false,
+	dim: false,
+	italic: false,
+	underline: false,
+	inverse: false,
+	strikethrough: false
+};
+function extractStyle(cell) {
+	const style = {
+		fg: extractColor(cell.isFgDefault(), cell.isFgPalette(), cell.isFgRGB(), cell.getFgColor()),
+		bg: extractColor(cell.isBgDefault(), cell.isBgPalette(), cell.isBgRGB(), cell.getBgColor()),
+		bold: cell.isBold() !== 0,
+		dim: cell.isDim() !== 0,
+		italic: cell.isItalic() !== 0,
+		underline: cell.isUnderline() !== 0,
+		inverse: cell.isInverse() !== 0,
+		strikethrough: cell.isStrikethrough() !== 0
+	};
+	return isDefaultStyle(style) ? DEFAULT_STYLE : style;
+}
+function isDefaultStyle(style) {
+	return style.fg.mode === "default" && style.bg.mode === "default" && !style.bold && !style.dim && !style.italic && !style.underline && !style.inverse && !style.strikethrough;
+}
+function styleKey(style) {
+	return [
+		style.fg.mode === "default" ? "d" : `${style.fg.mode}:${style.fg.value}`,
+		style.bg.mode === "default" ? "d" : `${style.bg.mode}:${style.bg.value}`,
+		style.bold ? "b" : "",
+		style.dim ? "d" : "",
+		style.italic ? "i" : "",
+		style.underline ? "u" : "",
+		style.inverse ? "r" : "",
+		style.strikethrough ? "s" : ""
+	].join("|");
+}
+function findMeaningfulEndCol(line, cols, nullCell) {
+	if (!line) return 0;
+	for (let x = cols - 1; x >= 0; x -= 1) {
+		const cell = line.getCell(x, nullCell);
+		if (!cell) continue;
+		if (cell.getWidth() === 0) continue;
+		const chars = cell.getChars();
+		const style = extractStyle(cell);
+		if (chars !== "" && chars !== " " || !isDefaultStyle(style)) return x + 1;
+	}
+	return 0;
+}
+function extractColor(isDefault, isPalette, isRgb, value) {
+	if (isDefault) return { mode: "default" };
+	if (isRgb) return {
+		mode: "rgb",
+		value
+	};
+	if (isPalette) return {
+		mode: "palette",
+		value
+	};
+	return { mode: "default" };
+}
+//#endregion
+export { styleKey as a, isDefaultStyle as i, extractStyle as n, findMeaningfulEndCol as r, DEFAULT_STYLE as t };

package/dist/{terminal_session-DJKr-O3X.mjs → terminal_session-MX_vWpRG.mjs}

@@ -1,3 +1,4 @@
+import { a as styleKey, i as isDefaultStyle, n as extractStyle, r as findMeaningfulEndCol, t as DEFAULT_STYLE } from "./style-BtIUv5H0.mjs";
 import { Terminal } from "@xterm/headless";
 //#region src/terminal/keys.ts
 const CSI = "\x1B[";
@@ -180,70 +181,6 @@ function clampInt(value, min, max) {
 	return int;
 }
 //#endregion
-//#region src/terminal/style.ts
-const DEFAULT_STYLE = {
-	fg: { mode: "default" },
-	bg: { mode: "default" },
-	bold: false,
-	dim: false,
-	italic: false,
-	underline: false,
-	inverse: false,
-	strikethrough: false
-};
-function extractStyle(cell) {
-	const style = {
-		fg: extractColor(cell.isFgDefault(), cell.isFgPalette(), cell.isFgRGB(), cell.getFgColor()),
-		bg: extractColor(cell.isBgDefault(), cell.isBgPalette(), cell.isBgRGB(), cell.getBgColor()),
-		bold: cell.isBold() !== 0,
-		dim: cell.isDim() !== 0,
-		italic: cell.isItalic() !== 0,
-		underline: cell.isUnderline() !== 0,
-		inverse: cell.isInverse() !== 0,
-		strikethrough: cell.isStrikethrough() !== 0
-	};
-	return isDefaultStyle(style) ? DEFAULT_STYLE : style;
-}
-function isDefaultStyle(style) {
-	return style.fg.mode === "default" && style.bg.mode === "default" && !style.bold && !style.dim && !style.italic && !style.underline && !style.inverse && !style.strikethrough;
-}
-function styleKey(style) {
-	return [
-		style.fg.mode === "default" ? "d" : `${style.fg.mode}:${style.fg.value}`,
-		style.bg.mode === "default" ? "d" : `${style.bg.mode}:${style.bg.value}`,
-		style.bold ? "b" : "",
-		style.dim ? "d" : "",
-		style.italic ? "i" : "",
-		style.underline ? "u" : "",
-		style.inverse ? "r" : "",
-		style.strikethrough ? "s" : ""
-	].join("|");
-}
-function findMeaningfulEndCol(line, cols, nullCell) {
-	if (!line) return 0;
-	for (let x = cols - 1; x >= 0; x -= 1) {
-		const cell = line.getCell(x, nullCell);
-		if (!cell) continue;
-		if (cell.getWidth() === 0) continue;
-		const chars = cell.getChars();
-		const style = extractStyle(cell);
-		if (chars !== "" && chars !== " " || !isDefaultStyle(style)) return x + 1;
-	}
-	return 0;
-}
-function extractColor(isDefault, isPalette, isRgb, value) {
-	if (isDefault) return { mode: "default" };
-	if (isRgb) return {
-		mode: "rgb",
-		value
-	};
-	if (isPalette) return {
-		mode: "palette",
-		value
-	};
-	return { mode: "default" };
-}
-//#endregion
 //#region src/terminal/snapshot_rows.ts
 function snapshotPlainLine(line, cols, nullCell, trimRight) {
 	let endCol = cols;
@@ -911,4 +848,4 @@ var TerminalSession = class {
 	}
 };
 //#endregion
-export { fnv1a32 as a, extractStyle as c, styleKey as d, encodeSgrMouse as f, TraceRecorder as i, findMeaningfulEndCol as l, sleep as n, snapshotGrid as o, encodeKey as p, applyTextMaskRules as r, snapshotLines as s, TerminalSession as t, isDefaultStyle as u };
+export { fnv1a32 as a, encodeSgrMouse as c, TraceRecorder as i, encodeKey as l, sleep as n, snapshotGrid as o, applyTextMaskRules as r, snapshotLines as s, TerminalSession as t };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ptywright",
-  "version": "0.5.0",
+  "version": "0.6.0",
   "description": "Terminal/TUI automation driver over PTY + xterm, exposed as MCP tools",
   "keywords": [
     "agent",