Feature: Playwright 1.59-style agentic primitives (annotated screencast, browser bind, CLI debugger, CLI trace viewer)

[rodion-m]

Context

Playwright 1.59 (Nov 2025) shipped a set of primitives explicitly aimed at AI-driven / agentic workflows. A few of them overlap with existing agent-browser features, but most are still missing. This umbrella issue catalogs the gaps and proposes a direction. I'm happy to break it into separate tickets if preferred.

Reference: Playwright 1.59 release notes and community write-ups.

Status matrix (against agent-browser 0.26.0)

Playwright 1.59 primitive	agent-browser today	Gap
page.screencast API (start/stop, showActions, showChapter, onFrame, HTML overlays)	record start/stop (WebM, no annotations) + stream enable (runtime WS) + PR #1224 adds screencast <duration_ms> --gif	No action annotations, no chapters/overlays, no per-frame callback for vision models
browser.bind({ name, workspaceDir }) — one running browser exposed to multiple clients simultaneously (CLI, MCP, API consumers)	--auto-connect / --cdp <port> can attach to a pre-existing Chrome; --session <name> sessions are isolated	No named, multi-client endpoint. Can't currently have playwright-mcp and agent-browser CLI and the dashboard all attached to the same logical session by name
Dashboard (playwright-cli show, PLAYWRIGHT_DASHBOARD=1)	agent-browser dashboard start (embedded since 0.25.1)	Covered. ✅
CLI debugger for agents (npx playwright test --debug=cli, attach <id>, step-over, step-into)	inspect opens Chrome DevTools GUI; get cdp-url exposes the WS URL for external debuggers	No first-class CLI stepping primitives an AI agent can drive head-lessly
CLI trace analysis (npx playwright trace to explore traces without the GUI)	trace start/stop and profiler start/stop capture Chrome tracing JSON	No CLI viewer / summarizer. Agents can't read/query a captured trace without the chrome://tracing or Perfetto GUI

Proposed gaps to close

1. Annotated screencast (builds on PR #1224)

The WIP in #1224 adds raw CDP screencast + GIF. To reach parity with Playwright 1.59 the API needs:

• screencast start [--path x.webm] [--actions top-right] [--size WxH] [--chapter-overlay]
• screencast showActions [on|off] — highlight each interacted element as actions land
• screencast showChapter <title> [--description ...] [--duration ms] — burned-in overlay, also recorded in stream metadata
• screencast showOverlay <html> / screencast hideOverlay — arbitrary HTML chrome for 'agentic receipts'
• onFrame equivalent: continuous JPEG frame stream to stdout / WS, so a vision model can subscribe (different intent from record — this is for live validation, not archival)
• screencast stop

These map cleanly onto CDP Page.startScreencast/screencastFrame plus a small DOM overlay layer, so no new deps should be needed beyond what #1224 already pulls in.

2. Named browser bind / multi-client attach

Today, two clients pointed at the same session either step on each other (daemon socket races) or have to go through --cdp <port>. Playwright 1.59's browser.bind('my-session', { workspaceDir }) exposes a stable, named endpoint over WS that multiple clients can open simultaneously.

Concretely:

• agent-browser bind <name> [--host 127.0.0.1] [--port 0] [--workspace-dir .] returns a stable WS endpoint and prints it as JSON
• agent-browser attach <name> / --endpoint <url> for additional clients (CLI, MCP, custom API users) joining the same session
• Cooperative concurrency (CDP already supports multiple attached clients per target, so the work is on the daemon side)
• Integrates with the dashboard so a bound session shows up alongside launched ones

Use case: an AI agent runs a long flow; a developer attaches from another terminal to snapshot / screenshot / intervene without killing the agent's browser.

3. CLI debugger for agents (--debug=cli equivalent)

inspect is GUI-only, which works for humans but not for a headless AI loop. Playwright's --debug=cli pauses a test and exposes step-over / step-into / continue / resume over playwright-cli. An agent-browser analogue:

• agent-browser debug start — pauses command dispatch, returns a session id
• agent-browser debug step / step-into / continue / break <selector>
• Works with batch so an agent can step through a scripted flow
• Composes with diff snapshot after each step for 'what changed' reasoning

4. CLI trace viewer / summarizer

trace start/stop already produces Chrome Trace Event JSON. What's missing is a way for an agent to actually read that trace without a GUI:

• agent-browser trace show <path> — structured JSON or text summary: timeline of actions, network requests, console events, frame timings
• agent-browser trace query <path> --filter 'category:network status:>=400' — filter/select from CLI
• agent-browser trace diff <a.json> <b.json> — what changed between two runs (composes with the existing diff snapshot / diff screenshot commands)

Priority suggestion

Going from highest leverage down:

1. Annotated screencast — continues momentum from feat: animation inspection, burst capture, and screencast commands #1224, largest delta vs Playwright 1.59, directly enables 'agentic video receipts' in CI
2. CLI trace viewer — unlocks headless debugging for agents, small surface
3. Named browser bind — unlocks hybrid human/agent workflows via dashboard + MCP + CLI all on one session
4. CLI debugger — highest complexity, smallest blast radius (most users today rely on inspect + logs)

Related existing issues / PRs

• feat: animation inspection, burst capture, and screencast commands #1224 — screencast + GIF PR (foundation for gap 1)
• Feature idea: animation inspection + capture commands #1223 — animation inspection feature request
• Feature request: Video recording support #66 — original video recording feature request (closed but foundational)
• Support for Multi Session #86 — multi-session support (adjacent to gap 2)
• Support for CDP operation recording function #81 — CDP operation recording (adjacent to gap 4)
• docs: Advantages over playwright-mcp? #134 — docs: advantages over playwright-mcp (relevant framing for gap 2)

[dajulia3]

This is the only thing stopping me from ditching playwright-cli for my agentic qa workflows and agentic demo video creation workflows. I'd love this feature