ptywright 0.1.0 → 0.2.0

package/README.md

@@ -1,188 +1,531 @@
 # ptywright
 
-一个通用的“终端版 DevTools / Playwright driver”原型：通过 PTY 启动任意 CLI/TUI，把 ANSI/VT 输出喂给 `@xterm/headless` 重建屏幕网格，并以 MCP（stdio）暴露工具接口。
+[中文文档](./README_ZH.md)
 
-## Run
+A universal "Terminal DevTools / Playwright driver": Launch any CLI/TUI via PTY, feed ANSI/VT output to `@xterm/headless` to rebuild the screen grid, and expose it as MCP (stdio) tools.
 
-```bash
-bun install
-
-# 默认：启动 MCP server（等价 `ptywright mcp`）
-bun run bin/ptywright
+## Installation
 
-# 显式写法：
-# bun run bin/ptywright mcp
+```bash
+# Recommended: Run with bunx (no install needed)
+bunx ptywright@latest --help
 
-# 可选：以 Streamable HTTP 方式启动（Web transport）
-# bun run bin/ptywright mcp-http --port 3000
+# Or install globally
+bun add -g ptywright
+ptywright --help
 
-# 可选：减少 tool 数量（降低 Agent 上下文压力）
-# bun run bin/ptywright mcp --caps core
-# 或：PTYWRIGHT_CAPS=core bun run bin/ptywright
+# Or via npm/npx
+npx -y ptywright@latest --help
+npm install -g ptywright
 ```
 
-## Tools (MVP)
+## Quick Start
 
-工具默认全量开启（等价 `PTYWRIGHT_CAPS=all`）。如需减少 tool 数量，可设置 `PTYWRIGHT_CAPS=core` 或按需组合：
+### Use as MCP Server
 
-- 默认：`PTYWRIGHT_CAPS=all`
-- 最小：`PTYWRIGHT_CAPS=core`
-- 组合：`PTYWRIGHT_CAPS=core,debug,script,recording`
+```bash
+# stdio mode (default)
+bunx ptywright@latest mcp
 
-### core
+# HTTP mode
+bunx ptywright@latest mcp-http --port 3000
 
-- `list_sessions` / `select_session`：管理与选择会话
-- `launch_session`：启动 PTY 会话（会自动成为默认会话）
-- `send_text` / `press_key`：发送输入
-- `snapshot_text`：返回可见屏幕文本（适合 Agent “看界面”与做 golden）
-- `snapshot_view`：更适合人看的快照（带元信息+行号）
-- `wait_for_text`：等待文本/正则出现
-- `wait_for_stable_screen`：等待屏幕在 quiet window 内稳定（降低 flaky）
-- `assert`：对当前屏幕做断言（text/regex/semantic）
-- `close_session`：关闭会话
+# Minimal tools (reduce Agent context pressure)
+bunx ptywright@latest mcp --caps core
+```
 
-### debug（可选）
+### Configure MCP Client
 
-- `snapshot_ansi`：返回带 ANSI/SGR 样式的可见屏幕（适合 debug/人眼验收）
-- `snapshot_view_ansi`：带 ANSI/SGR 样式的 `snapshot_view`
+**Claude Desktop / Cursor** (`~/.config/claude/claude_desktop_config.json`):
 
-### script（可选）
+```json
+{
+  "mcpServers": {
+    "ptywright": {
+      "command": "bunx",
+      "args": ["ptywright@latest", "mcp"]
+    }
+  }
+}
+```
 
-- `run_routine`：一键执行多步交互（type/key/wait/assert/snapshot）
-- `run_script`：运行 `scriptPath=file.json|file.ts` 并产出 artifacts（cast/report/失败快照）
-- `run_all_scripts`：批量运行目录内脚本（递归；支持 `includeEntries/maxEntries` 控制输出）
-- `generate_test_from_doc`：从文档（本地/URL）生成可执行脚本
-- `inspect_failure`：查看最近一次失败的屏幕与错误
+**Minimal mode** (load core tools only):
 
-### recording（可选）
+```json
+{
+  "mcpServers": {
+    "ptywright": {
+      "command": "bunx",
+      "args": ["ptywright@latest", "mcp", "--caps", "core"]
+    }
+  }
+}
+```
 
-- `start_script_recording` / `stop_script_recording`：录制 MCP 工具调用并导出可复跑脚本（JSON + goldens）
-- `mark`：在 trace 中打点（asciicast marker event）
+**HTTP mode** (for Web clients):
 
-`mask`（可选）：`snapshot_text/snapshot_ansi/snapshot_view/snapshot_view_ansi` 支持 `mask=[{regex,flags?,replacement?,preserveLength?}]`，用于把随机 id/时间戳等变成可 diff 的稳定快照
+```json
+{
+  "mcpServers": {
+    "ptywright": {
+      "command": "bunx",
+      "args": ["ptywright@latest", "mcp-http", "--port", "3000"]
+    }
+  }
+}
+```
 
-### `press_key` Key Spec
+### CLI Commands
 
-支持单键与“修饰键 + 单键”的组合写法（大小写不敏感，`+`/`-` 都可作为分隔符）：
-- 单字符：`"a"` / `"?"`（原样写入 PTY）
-- 特殊键：`Enter|Return`、`Esc|Escape`、`Backspace`、`Space`、`Tab`、`BackTab`
-- 组合键：`Ctrl+C`、`Ctrl+Shift+R`、`Alt+X`/`Meta+X`、`Shift+Tab`、`Ctrl+Up`
-- 导航键：`Up/Down/Left/Right`、`Home/End`、`PageUp/PageDown`、`Insert/Delete`、`F1..F12`
-- 兼容：`c-x`（等价 `Ctrl+X`）
+```bash
+# Run a single test script
+bunx ptywright@latest run scripts/demo.json
 
-## Tests
+# Run all scripts (generate HTML report)
+bunx ptywright@latest run-all --dir scripts
 
-```bash
-bun test
+# Show help
+bunx ptywright@latest --help
 ```
 
-包含：
-- PTY + xterm 解析与快照测试
-- MCP server 端到端 smoke（client 通过 stdio 启动 server 并调用 tools）
+### Raw PTY Cassette
 
-## Use With MCP Clients（可选）
+`ptywright pty` records the raw PTY stream once and replays it later without
+rerunning the original command. This is intended for browser terminal renderers
+that need deterministic regression tests for prompts or AI sessions that are
+hard to reproduce live.
 
-本仓库也提供了一个可选的 Codex skill：`skills/ptywright-testing/`，用于指导 Agent 如何用 ptywright MCP/CLI 跑回归并读取 `run.summary.json`（尽量不把超长报告塞进上下文）。
+```bash
+# Record output/input/resize/exit as base64 PTY events
+bunx ptywright@latest pty record --out tests/cassettes/codex.pty.json -- codex
 
-本项目是一个 stdio transport 的 MCP server。直接启动：
+# Replay the same raw output stream instantly
+bunx ptywright@latest pty replay tests/cassettes/codex.pty.json
 
-```bash
-# 默认等价 `ptywright mcp`
-bun run bin/ptywright
+# Validate or inspect the portable artifact
+bunx ptywright@latest pty validate tests/cassettes/codex.pty.json
+bunx ptywright@latest pty inspect tests/cassettes/codex.pty.json
 ```
 
-也可以用 Streamable HTTP 启动（默认 endpoint: `http://127.0.0.1:3000/mcp`）：
+External projects do not need to depend on aitty. Use the structural
+`wrapPtyLike` API for `node-pty`/`bun-pty` style objects:
 
-```bash
-bun run bin/ptywright mcp-http --port 3000
+```ts
+import { wrapPtyLike } from "ptywright/pty-cassette";
+
+const recorded = wrapPtyLike(pty, {
+  path: "tests/cassettes/session.pty.json",
+  terminal: { cols: 120, rows: 40, term: "xterm-256color" },
+  command: { file: "codex", args: [] },
+});
+
+recorded.write("hello\r");
+// output and exit are captured from pty.onData/onExit
 ```
 
-然后在你使用的 MCP client 里把它作为一个 stdio server 配置进去即可（不同 client 的配置方式不同）。
+For Bun Terminal callback-style integration, create a recorder and call
+`recordOutput` from the terminal `data` hook, or use
+`wrapBunTerminalOptions`. The cassette can then be replayed into any renderer
+and compared by that renderer's DOM/text snapshot tests.
+
+## Tools
+
+All tools are enabled by default (`--caps all`). Use `--caps core` or combine as needed:
+
+- Default: `--caps all`
+- Minimal: `--caps core`
+- Combined: `--caps core,debug,script,recording`
+
+### core
+
+- `list_sessions` / `select_session`: Manage and select sessions
+- `launch_session`: Start a PTY session (becomes default session)
+- `send_text` / `press_key`: Send input
+- `snapshot_text`: Return visible screen text (for Agent "seeing" and golden snapshots)
+- `snapshot_view`: Human-friendly snapshot (with metadata + line numbers)
+- `wait_for_text`: Wait for text/regex to appear
+- `wait_for_stable_screen`: Wait for screen to stabilize within quiet window (reduce flaky)
+- `assert`: Assert on current screen (text/regex/semantic)
+- `close_session`: Close session
+
+### debug (optional)
+
+- `snapshot_ansi`: Return visible screen with ANSI/SGR styles (for debug/human review)
+- `snapshot_view_ansi`: `snapshot_view` with ANSI/SGR styles
+
+### script (optional)
+
+- `run_routine`: Execute multi-step interactions in one call (type/key/wait/assert/snapshot)
+- `run_script`: Run `scriptPath=file.json|file.ts` and produce artifacts (cast/report/failure snapshots)
+- `run_all_scripts`: Run scripts in directory recursively (supports `includeEntries/maxEntries`)
+- `generate_test_from_doc`: Generate executable scripts from documentation (local/URL)
+- `inspect_failure`: View last failure screen and error
+
+### recording (optional)
+
+- `start_script_recording` / `stop_script_recording`: Record MCP tool calls and export replayable scripts (JSON + goldens)
+- `mark`: Add marker to trace (asciicast marker event)
+
+### `mask` Parameter
+
+`snapshot_text/snapshot_ansi/snapshot_view/snapshot_view_ansi` support `mask=[{regex,flags?,replacement?,preserveLength?}]` to convert random IDs/timestamps into diffable stable snapshots.
+
+### `press_key` Key Spec
+
+Supports single keys and modifier combinations (case-insensitive, `+`/`-` as separator):
+- Single char: `"a"` / `"?"` (written to PTY as-is)
+- Special keys: `Enter|Return`, `Esc|Escape`, `Backspace`, `Space`, `Tab`, `BackTab`
+- Combos: `Ctrl+C`, `Ctrl+Shift+R`, `Alt+X`/`Meta+X`, `Shift+Tab`, `Ctrl+Up`
+- Navigation: `Up/Down/Left/Right`, `Home/End`, `PageUp/PageDown`, `Insert/Delete`, `F1..F12`
+- Compatible: `c-x` (equals `Ctrl+X`)
 
 ## Script Runner (JSON)
 
-把一次 TUI 测试写成 JSON：启动 → 输入 → 等待 → 快照（可 mask）→ 断言，并自动产出 `.cast` + `report.html`。
+Write TUI tests as JSON: launch → input → wait → snapshot (with mask) → assert, automatically producing `.cast` + `report.html`.
 
-可选：在 JSON 顶部加上 schema（编辑器补全/校验更友好）：
+Optional: Add schema for editor completion/validation:
 
 ```json
-{ "$schema": "../schemas/ptywright-script.schema.json" }
+{ "$schema": "node_modules/ptywright/schemas/ptywright-script.schema.json" }
 ```
 
 ```bash
-bun run script:run scripts/m5_mask_demo.json
-# 或（CLI）
-bun run bin/ptywright run scripts/m5_mask_demo.json
-# 或
-bun run script:m5-mask-demo
+# Run single script
+bunx ptywright@latest run scripts/m5_mask_demo.json
+
+# Run all scripts
+bunx ptywright@latest run-all --dir scripts
 ```
 
-批量执行（本地/CI）：
+Artifacts go to `.tmp/runs/<name>/` by default (override with `--artifacts-dir`).
+
+Batch runs generate an overview report:
+- Default: `.tmp/run-all/index.html` + `.tmp/run-all/run.summary.json`
+- With `--artifacts-root <dir>`: `<dir>/index.html` + `<dir>/run.summary.json`
+- `run.summary.json` stores `commands.runAll.argv` and
+  `commands.updateGoldens.argv` so automation can replay the suite or update
+  goldens without reconstructing CLI arguments.
+
+You can read or execute those commands directly from the generated artifact:
 
 ```bash
-bun run script:run-all
-# 或（CLI）
-bun run bin/ptywright run-all
+bunx ptywright@latest script commands .tmp/run-all --json
+bunx ptywright@latest script commands .tmp/run-all/run.summary.json --command runAll
+bunx ptywright@latest script inspect .tmp/run-all
+bunx ptywright@latest script validate .tmp/run-all
+bunx ptywright@latest script exec .tmp/run-all --command updateGoldens
 ```
 
-会生成一个总览报告（类似 Playwright report 首页）：
-- 默认：`.tmp/run-all/index.html` + `.tmp/run-all/run.summary.json`
-- 若传入 `--artifacts-root <dir>`：写到 `<dir>/index.html` + `<dir>/run.summary.json`
+Suite directories also include `ptywright-script.manifest.json`, which indexes
+the generated summary, reports, casts, data, and failure artifacts with
+`bytes`/`sha256`. `script validate`, `script inspect`, `script commands`, and
+`script exec` verify that manifest before using a directory bundle, so copied
+script run artifacts can be replayed or updated without trusting stale files.
 
-如果 JSON 里用到了 `type:"custom"`，用 `--steps <module.ts>` 注入 handlers（模块导出 `steps` 对象即可）：
+On failure, additional files are saved:
+- `failure.error.txt` (error stack)
+- `failure.step.json` (failed step info)
+- `failure.last.txt` / `failure.last.view.txt` (last frame snapshot)
 
-```bash
-bun run script:run examples/json_custom_steps_demo.json --steps scripts/m6_json_custom_steps.ts
-```
+`report.html` includes **Timeline View** showing screen snapshots after each step. Click the `debug` badge to switch to debug view.
 
-产物默认写到 `.tmp/runs/<name>/`（可用 `--artifacts-dir` 覆盖）。
+Built-in steps (no `--steps` needed):
+- `assert`: Assert text/regex (`text`/`regex`)
+- `assertSemantic`: Semantic assertion placeholder (`prompt`)
+- `sleep`: Fixed wait
+- `expectMeta`: Assert terminal meta
+- `waitForExit`: Wait for process exit
+- `sendMouse`: Send SGR mouse events
 
-失败时会额外落盘：
-- `failure.error.txt`（错误堆栈）
-- `failure.step.json`（失败的 step 信息）
-- `failure.last.txt` / `failure.last.view.txt`（最后一帧快照）
+### Framework Backends
 
-`report.html` 现在包含 **Timeline View**，展示每一步操作后的屏幕快照（不仅是失败时）。点击顶部 `debug` badge 可切换到调试视图。
+`launch.backend` defaults to `pty`. For faster framework-level checks, use
+`frames`, `ratatui`, or `ink` to run the same script steps against deterministic
+frames without starting a PTY:
 
-Cast Playback（完整录屏）会优先加载 report 同目录的 `asciinema-player.min.js` / `asciinema-player.css`（生成 report 时自动复制），因此离线打开 report 也可播放；若本地资源缺失则会 fallback 到 CDN。
+```json
+{
+  "$schema": "../schemas/ptywright-script.schema.json",
+  "name": "ratatui_snapshot",
+  "launch": {
+    "backend": "ratatui",
+    "cols": 60,
+    "rows": 12,
+    "frames": [
+      "Screen: Dashboard\nMode: HIGH",
+      "Screen: Permissions\nMode: LOW"
+    ]
+  },
+  "steps": [
+    { "type": "waitForText", "text": "Dashboard" },
+    { "type": "pressKey", "key": "Enter" },
+    { "type": "snapshot", "kind": "text", "saveAs": "final" },
+    { "type": "expect", "from": "final", "contains": ["Mode: LOW"] }
+  ]
+}
+```
 
-内置 steps（无需 `--steps`）：
-- `assert`：**[NEW]** 断言文本/正则（`text`/`regex`）
-- `assertSemantic`：**[NEW]** 语义断言占位符（`prompt`）
-- `sleep`：固定等待
-- `expectMeta`：断言终端 meta
-- `waitForExit`：等待进程退出
-- `sendMouse`：发送 SGR 鼠标事件
+`ratatui` is intended for text emitted by `TestBackend`/insta-style snapshots.
+`ink` can load a module via `frameModule` that exports `frames`, `frame`,
+`snapshot`, or `lastFrame`. Input steps such as `pressKey` and `sendText`
+advance to the next frame by default, so the assertion path stays identical to
+the PTY end-to-end script.
 
-## Script Recording (MCP)
+For `type:"custom"` steps, inject handlers with `--steps <module.ts>`:
 
-如果你设置了 `PTYWRIGHT_CAPS` 且未包含 `recording`，需要开启 `recording`（例如 `PTYWRIGHT_CAPS=core,recording`）。
+```bash
+bunx ptywright@latest run demo.json --steps custom_steps.ts
+```
+
+## Script Recording (MCP)
 
-在任意 MCP client/Agent 通过 MCP tools 驱动时，可以一键把工具调用“录成脚本”，并在 `mark` 处自动落盘 golden：
+Record tool calls into replayable scripts from any MCP client/Agent:
 
 1) `start_script_recording(name="my_flow")`
-2) 正常执行：`launch_session/send_text/press_key/wait_for_*`
-3) 关键节点打点：`mark(label="checkpoint")`（会自动生成 `snapshot + expectGolden`）
-4) `stop_script_recording(recordingId=...)`（写入 `scripts/my_flow.json` + `tests/golden/scripts/my_flow/*.txt`）
+2) Execute normally: `launch_session/send_text/press_key/wait_for_*`
+3) Add checkpoints: `mark(label="checkpoint")` (auto-generates `snapshot + expectGolden`)
+4) `stop_script_recording(recordingId=...)` (writes `scripts/my_flow.json` + `tests/golden/scripts/my_flow/*.txt`)
 
 ## Script DSL (TypeScript)
 
-用 TS builder 写 script（类型安全，可组合，支持自定义 step），底层仍复用同一个 runner：
+Write scripts with TS builder (type-safe, composable, custom steps):
 
 ```bash
-bun run script:run scripts/m6_dsl_demo.ts
+bunx ptywright@latest run scripts/demo.ts
+```
+
+Conventions:
+- Module default export (`export default`), or export `script`.
+- Optional `steps` export (custom step handlers) for `type:"custom"` steps.
+- Use `pasteText("...", { bracketed: true })` for bracketed paste testing.
+
+## Cast -> SVG/GIF (Optional)
+
+Recording artifacts are best for failure diagnosis or manual review; prefer `snapshot_grid` diff for stable regression.
+
+- SVG: `bunx svg-term --in <castPath> --out <outSvg>`
+- GIF: `agg --fps 30 <castPath> <outGif>` (requires [asciinema/agg](https://github.com/asciinema/agg))
+
+## Browser Agent Regression
+
+The new destructive path is browser-first: ptywright can launch an agent through
+`@aitty/cli`, drive the browser-hosted wterm DOM with Playwright, and persist a
+replayable run artifact plus terminal/DOM snapshots.
+
+```bash
+# First run records snapshots, screenshots, replay metadata, and report.
+bun run bin/ptywright agent run examples/agent_deterministic.json --update-snapshots
+
+# Later runs compare terminal + DOM snapshots like a test snapshot.
+bun run bin/ptywright agent run examples/agent_deterministic.json
+
+# Replay does not need AI; it uses the recorded flow artifact.
+bun run bin/ptywright agent replay .tmp/agent/agent_deterministic/agent_deterministic.agent-run.json
+
+# Cassette files are also directly replayable.
+bun run bin/ptywright agent replay .tmp/agent/agent_deterministic/agent_deterministic.cassette.json
+
+# Promote a live run/cassette into the committed non-AI regression suite.
+bun run bin/ptywright agent promote \
+  .tmp/agent/agent_deterministic/agent_deterministic.cassette.json \
+  --update-snapshots
+
+# Batch replay committed cassettes/run records as a regression suite.
+bun run bin/ptywright agent replay-all .tmp/agent --artifacts-root .tmp/agent-replay-all
+
+# Rerun directly from a generated summary artifact.
+bun run bin/ptywright agent rerun .tmp/agent-promote/agent_deterministic/agent-promote.summary.json
+bun run bin/ptywright agent rerun .tmp/agent-check/agent-check.summary.json
+bun run bin/ptywright agent rerun .tmp/agent-check/agent-replay.summary.json --update-snapshots
+
+# Read reusable commands from any supported agent artifact.
+bun run bin/ptywright agent commands .tmp/agent-check/agent-check.summary.json --json
+bun run bin/ptywright agent commands .tmp/agent-check/agent-check.summary.json --command rerun
+bun run bin/ptywright agent commands .tmp/agent-check --json
+bun run bin/ptywright agent inspect .tmp/agent-check
+bun run bin/ptywright agent inspect .tmp/agent-check --json
+bun run bin/ptywright agent validate .tmp/agent-check
+bun run bin/ptywright agent exec .tmp/agent-check --command rerun
+bun run bin/ptywright agent exec .tmp/agent-check --command updateSnapshots
+bun run bin/ptywright agent exec .tmp/agent-check/agent-check.summary.json --command rerun
+bun run bin/ptywright agent exec .tmp/agent-check/agent-check.summary.json --command updateSnapshots
+
+# Validate flow/cassette/run-record/summary artifacts before committing.
+bun run bin/ptywright agent validate .tmp/agent-replay-all
+
+# Run committed cassette replay regression without launching live agents.
+bun run bin/ptywright agent check
+bun run bin/ptywright agent check --json
+
+# Update terminal/DOM baselines from committed cassettes intentionally.
+bun run bin/ptywright agent replay-all tests/agent-cassettes --update-snapshots
+
+# Record browser interactions into a replayable flow spec.
+bun run bin/ptywright agent record examples/agents/codex_browser_smoke.json \
+  --out scripts/agents/codex_recorded.flow.json \
+  --duration-ms 60000 \
+  --headed
+
+# Generate starter specs for real agents.
+bun run bin/ptywright agent init codex examples/agents/codex_browser_smoke.json
+bun run bin/ptywright agent init claude examples/agents/claude_browser_smoke.json
+bun run bin/ptywright agent init droidx examples/agents/droidx_browser_smoke.json
+```
+
+Artifacts are split intentionally:
+- `.tmp/agent/<name>/` contains run output, screenshots, `*.flow.json`,
+  `*.agent-run.json`, `*.cassette.json`, `index.html`, and
+  `ptywright-agent.manifest.json`.
+- `tests/agent-snapshots/<name>/` contains stable terminal/DOM baselines.
+- `--update-snapshots` is the explicit update path for intentional UI changes.
+
+`launch.mode=aitty` runs `aitty exec --launch print -- <agent>`. By default
+ptywright resolves the sibling `../aitty/packages/cli/dist/cli.js`; set
+`PTYWRIGHT_AITTY_CLI` or `launch.aitty.command` to override it.
+
+Set `launch.agentFlavor` to `codex`, `claude`, `droid`, or `generic` to opt
+into built-in mask presets for timestamps, generated ids, model names, token
+counts, and other non-deterministic terminal text. Explicit
+`defaults.mask=[...]` rules are appended after the preset, so project-specific
+noise can be hidden without rewriting the runner.
+
+`agent record` opens the same browser-hosted terminal and writes the captured
+keyboard/click steps back to a normal flow JSON. The output can be committed and
+run later with `agent run`, while `.agent-run.json` remains the per-run replay
+record generated by the runner. Run records must include
+`commands.replay.argv` and `commands.updateSnapshots.argv`, so automation can
+replay or intentionally update the captured flow without parsing shell strings.
+
+`agent run` is the live path: it launches the configured process and updates or
+compares terminal/DOM snapshots. `agent promote <run|cassette>` is the
+intentional solidify step after a good live run: it copies the cassette into
+`tests/agent-cassettes/<name>/`, rewrites its `snapshotDir`, optionally updates
+terminal/DOM baselines, replays the promoted cassette, and writes
+`agent-promote.summary.json` with direct commands for future non-AI checks. HTML
+reports also surface replay/update/inspect commands so failed runs can be
+reproduced directly from the report page.
+`agent replay` is the single-case cassette regression path: it accepts either
+`.agent-run.json` or `.cassette.json`, serves a local replay page, and reproduces
+the previously captured terminal DOM without launching Codex, Claude, Droid, or
+any other live agent process. `agent replay-all` recursively scans a directory
+for `.agent-run.json` and `.cassette.json` files, then writes
+`agent-replay.summary.json` and an HTML suite report so committed cassettes can
+be run like a snapshot regression suite.
+`--update-snapshots` works on `agent replay-all`, so intentional DOM/terminal
+baseline changes can be updated from committed cassettes without a live agent.
+Cassette files embed the normalized flow spec plus frame hashes, so they remain
+self-contained replay artifacts when copied away from the original run
+directory. Replay runs also copy the source cassette into the replay artifact
+directory and write run records that point at that local copy, so the replay
+directory can be moved as a durable reproduction bundle. Run/check/promote and
+replay-all outputs also include `ptywright-agent.manifest.json`, which indexes
+produced files with artifact-root-relative paths plus `bytes` and `sha256`,
+stores reusable `commands.*.argv`, and can be passed to `agent commands`,
+`agent inspect`, `agent exec`, or `agent validate`. `agent inspect
+<artifact|dir>` is the self-describing bundle check: when pointed at an artifact
+directory it prefers `ptywright-agent.manifest.json`, validates indexed file
+hashes, summarizes manifest file kinds/validation stages, and prints the
+relocated reusable commands. Because file entries are relative to the manifest
+directory and manifest commands are relocated when read, copying the whole
+artifact directory preserves both manifest validation and direct
+`agent inspect <copied>` /
+`agent commands <copied>` /
+`agent exec <copied> --command rerun` workflows.
+When inspecting a moved summary file that is the manifest primary artifact,
+`agent inspect` also prints `commandsManifest=<path>` and includes
+`commands.manifestPath` in JSON output, making it explicit which manifest bundle
+will validate and relocate the stored commands before execution.
+The same directory entrypoint works for copied live-run bundles too, so
+`agent exec <copied-run> --command replay` and `--command updateSnapshots`
+remain usable after the original run directory is deleted.
+Copied replay-suite bundles are rerun from the run records stored under the
+bundle's own `tests/` directory, so they do not need the original cassette input
+directory. Promote bundles can move their artifact root and still rerun from the
+copied manifest, while continuing to target the promoted cassette suite.
+If `agent inspect <dir>` sees agent artifacts but no top-level manifest, it
+still reports recursive validation results and prints a `directoryManifest`
+diagnostic so the directory is not confused with a portable commands/exec
+bundle.
+For `agent commands` and `agent exec`, a directory argument means a manifest
+bundle directory and must contain `ptywright-agent.manifest.json`; use
+`agent validate <dir>` when you want recursive artifact discovery.
+The generated agent flow, cassette, run-record, manifest, promote-summary,
+replay-summary, and check-summary JSON files each carry a `$schema` URL under
+`schemas/` so editors and CI tooling can validate the replay contract directly.
+Run-record and summary schemas also encode the expected stored command prefixes,
+for example `ptywright agent replay`, `ptywright agent replay-all`, and
+`ptywright agent rerun`, so malformed commands can be caught before execution.
+Run records and summaries reject missing or stale `commands.*.argv` metadata,
+because those argv arrays are the non-AI replay/update contract for the artifact.
+Promote, replay, and check summaries include `commands.*.argv` arrays for direct
+non-AI reruns and snapshot updates. Each summary also includes
+`commands.rerun.argv`, so downstream automation can re-execute the exact summary
+artifact without reconstructing CLI arguments. `agent commands <artifact>
+--command <name>` prints one shell-safe command line for scripts that want to
+execute a specific replay/update/rerun path directly; with `--json`, the same
+command includes `cwd`, `command.argv`, and `shell` so automation can choose
+structured spawn or shell execution. When a moved summary/run-record is backed
+by a sibling manifest bundle, `agent commands` also reports the manifest path in
+plain output and JSON so automation can see which bundle is responsible for
+relocation and integrity checks; manifest-backed command discovery validates
+stored command targets and indexed file hashes before printing commands.
+`agent exec <artifact> --command <name>`
+executes a stored agent command through ptywright's own CLI dispatcher, so it
+does not depend on shell parsing or a global `ptywright` binary. This includes
+stored `updateSnapshots` commands, which provide the non-AI equivalent of a
+snapshot update run from an existing summary artifact. `agent validate
+<artifact>` also checks that every stored argv starts with a supported
+`ptywright agent <subcommand>` shape before accepting the artifact. If validation
+fails on `commands.*.argv`, regenerate the run/summary with `agent run`,
+`agent replay-all`, `agent promote`, or `agent check`; do not hand-edit shell
+strings as a recovery path, because the argv arrays are the replay contract.
+`agent rerun <summary>` reads `agent-promote.summary.json`,
+`agent-check.summary.json`, or
+`agent-replay.summary.json` and replays the stored cassette directory/artifact
+root without launching a live agent. `agent commands <artifact>` reads
+flow/cassette/run-record/summary artifacts and prints the reusable argv commands
+without executing them. `agent validate <path>` accepts a single artifact or a
+directory and returns a non-zero exit code when any known agent replay artifact
+is malformed. `agent check [dir]` validates committed cassettes under
+`tests/agent-cassettes` by default, replays them into `.tmp/agent-check`, writes
+`agent-check.summary.json`, then validates the generated suite output. Add
+`--json` for a CI-friendly summary with input/replay/output counts and failure
+details.
+
+## Development
+
+```bash
+bun install
+
+# Start MCP server
+bun run bin/ptywright mcp
+
+# Run tests
+bun run test
+bun run agent:check
+bun run check
+
+# CI installs Chromium, runs bun run check, and uploads .tmp/agent-check.
+
+# Lint & Format
+bun run lint
+bun run format:check
+
+# Run scripts
+bun run bin/ptywright run scripts/m5_mask_demo.json
+bun run bin/ptywright run-all
+
+# Run browser agent regression
+bun run bin/ptywright agent run examples/agent_deterministic.json --update-snapshots
 ```
 
-约定：
-- module 默认导出（`export default`），或导出 `script`。
-- 可选导出 `steps`（custom step handlers），用于执行 `type:"custom"` 的步骤。
-- 常用 handlers 可复用：`src/script/steps/*`。
-- 需要测试“粘贴”时可用 `pasteText("...", { bracketed: true })`（bracketed paste）。
+## Environment Variables
 
-## Cast -> SVG/GIF (可选)
+- `TUI_TEST_PTY_BACKEND=auto|bun-terminal|bun-pty`
+  - default `auto`: macOS/Linux prefers `bun-terminal`, Windows uses `bun-pty`
+- `PTYWRIGHT_CAPS=all|core|debug|script|recording`
+  - Equivalent to `--caps` parameter
 
-录像类产物建议只用于失败诊断或人工验收；稳定回归优先用 `snapshot_grid` 做 diff。
+## License
 
-- SVG: `svg-term`（例如：`bunx svg-term --in <castPath> --out <outSvg>`）
-- TXT: `bun run src/trace/cast_to_txt.ts --in <castPath> --out <outTxt>`
-- GIF: `asciinema/agg`（例如：`agg --fps 30 <castPath> <outGif>`）
+Apache-2.0

package/dist/agent.mjs

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

package/dist/bin/ptywright.mjs

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