feat(m3.2): page snapshots and ref actions

[ralyodio]

Implements M3.2 — snapshots and refs from the M3 PRD. Stacked on #28 (M3.1) — review/merge that first; the base will retarget to main once #28 lands.

tron snapshot [--json] [--include-hidden]
tron click @e3
tron fill @e4 "hi@example.com"

Runtime pivot (design note)

M3.1's session lifecycle fit in shell+python. Snapshots/actions need programmatic CDP over a WebSocket, which the PRD's TS package layout (browser-core, sdk) and later deliverables (@tronbrowser/sdk, tron run *.ts, MCP) already assume is Node. So from M3.2 these subcommands are TypeScript/Node, delegated to by the shell dispatcher, attaching to the session via the descriptor's webSocketDebuggerUrl — the exact attach point M3.1 was built around.

What's here (packages/browser-core/src/automation/)

• cdp-client.ts — CDP JSON-RPC over Node's global WebSocket (Node ≥22, no dependency).
• snapshot-script.ts / action-script.ts — the in-page scripts. Snapshot tags each element with data-tron-ref, so a later tron click @e3 (a separate process) resolves the ref by attribute selector; a vanished element → recoverable STALE_REF (exit 5). Password values are never echoed.
• page.ts — evaluate + StaleRefError + compact text formatting.
• page-target.ts — selects the session's current page target.
• automate-cli.ts + automate-bin.ts — the tron-automate Node entry; deps injectable for testing.

Packaging + wiring

• build-release.sh ships browser-core's self-contained dist tree as automate/ (source has no runtime deps) with a {"type":"module"} marker; the tron dispatcher runs it via node.
• install.sh dispatcher routes snapshot|click|fill|type to the Node runtime, with clear errors if Node or the runtime is absent.

Acceptance criteria (PRD §22)

• ✅ Stable refs for visible interactive elements (document order, @eN).
• ✅ Click/fill by ref work on test pages.
• ✅ Stale refs → recoverable error.
• ✅ Snapshot output compact enough for LLM use (text + --json).

Verification — 37 new tests (95 across the two packages)

• CDP client over a real WebSocket (dependency-free mock WS server): id-matching, CdpError, event dispatch, close-rejects-pending.
• In-page scripts against a real DOM (happy-dom): refs/roles/names, password redaction, visibility filtering, focus, click, fill+events, stale ref.
• Orchestration + CLI with injected fakes; exit codes (no-session=4, stale=5, usage=2).
• End-to-end: the CLI's real fetch + CdpClient transport against a mock DevTools server (this caught a CDP double-nesting detail — the source was correct, the mock wasn't).
• Shipped entry smoke-tested standalone; dispatcher routing verified via the extracted tron CLI. browser-core typecheck/lint clean; desktop suite still green.

Scope

Requires Node ≥22 + a running managed session. Shadow DOM / cross-origin iframes deferred. See docs/snapshots-and-refs.md.

🤖 Generated with Claude Code

[github-actions]

vu1nz Security Review

0 finding(s) in PR #?

No security issues found.

[socket-security]

Review the following changes in direct dependencies. Learn more about Socket for GitHub.

Diff	Package	Supply Chain Security	Vulnerability	Quality	Maintenance	License
	happy-dom@​20.10.6

View full report

[socket-security]

Warning

Review the following alerts detected in dependencies.

According to your organization's Security Policy, it is recommended to resolve "Warn" alerts. Learn more about Socket for GitHub.

Action	Severity	Alert  (click "▶" to expand/collapse)
Warn		Obfuscated code: npm happy-dom is 90.0% likely obfuscated Confidence: 0.90 Location: Package overview From: packages/browser-core/package.json → npm/happy-dom@20.10.6 ℹ Read more on: This package | This alert | What is obfuscated code? Next steps: Take a moment to review the security alert above. Review the linked package source code to understand the potential risk. Ensure the package is not malicious before proceeding. If you're unsure how to proceed, reach out to your security team or ask the Socket team for help at support@socket.dev. Suggestion: Packages should not obfuscate their code. Consider not using packages with obfuscated code. Mark the package as acceptable risk. To ignore this alert only in this pull request, reply with the comment @SocketSecurity ignore npm/happy-dom@20.10.6. You can also ignore all packages with @SocketSecurity ignore-all. To ignore an alert for all future pull requests, use Socket's Dashboard to change the triage state of this alert.

View full report