fix: reject stale generation-tagged refs

[kunchenguid]

Summary

• Stamp snapshot element refs with a persisted generation so CLI interactions can detect and reject stale refs instead of silently no-oping after page changes.
• Update click, fill, hover, drag, upload, screenshot, and run-helper ref handling to accept generation-tagged refs consistently.
• Document the new ref format and persisted snapshot-generation state, with tests covering stale and tagged ref behavior.

Risk Assessment

⚠️ Medium: The change is reasonably bounded and previous stale-ref issues appear addressed, but it touches most browser interaction commands and adds page-level mutation tracking plus persisted generation state, so integration behavior still warrants pipeline coverage.

Testing

• Summary: Exercised the generation-stamped snapshot ref parsing, stale-ref validation, affected CLI interactions, and the full Vitest suite; all completed successfully.
• npm test -- test/snapshot.test.ts test/interaction.test.ts test/run.test.ts test/main.test.ts
• npm test
• Outcome: ✅ passed across 1 run (31.1s)

Pipeline

Updates from git push no-mistakes

✅ **Rebase** - passed

Round 1 - passed ✅

🔧 **Review** - 2 issues found → auto-fixed

Round 1 - found 2 issues (1 error, 1 warning)

• 🚨 src/cli.ts:962 - The stale-ref check only compares against the last generation written by this CLI, so refs from the latest snapshot are still accepted after the page changes without another stamped snapshot, such as a timer-driven re-render, wait, or mutating eval. That leaves the original silent no-op failure mode in place for a common stale-ref path despite the new STALE_REF contract.
• ⚠️ src/snapshot.ts:57 - Stamping printed refs as g<N>:<uid> changes the public ref format, but the run helper still only treats numeric refs as uids, so page.click("@g1:1") or page.fill("@g1:1", ...) will be handled as CSS selectors instead of DevTools refs.

Round 2 (auto-fix) - passed ✅

✅ **Test** - passed

Round 1 - passed ✅

• npm test -- test/snapshot.test.ts test/interaction.test.ts test/run.test.ts test/main.test.ts
• npm test

🔧 **Document** - 7 issues found → auto-fixed

Round 1 - found 7 warnings

• ⚠️ src/cli.ts:112 - The screenshot --uid command help still documents/examples untagged refs (@3) and does not explain that element refs in current snapshots are generation-tagged and may raise STALE_REF. Update this help section to match the new ref format and stale-ref behavior, like the updated click help.
• ⚠️ src/cli.ts:153 - The fill command help still documents/examples untagged refs (@3) and does not mention passing generation-tagged refs back exactly as printed or the STALE_REF failure mode introduced for stale refs.
• ⚠️ src/cli.ts:349 - The hover command help still documents/examples untagged refs (@5) and omits the new generation-tagged ref and STALE_REF behavior now applied before invoking the MCP hover action.
• ⚠️ src/cli.ts:361 - The drag command help still documents/examples untagged refs (@3 @7) and omits that both refs should be generation-tagged refs from the latest snapshot or the command can fail with STALE_REF.
• ⚠️ src/cli.ts:374 - The fillform command help still documents/examples untagged refs (@1, @2, etc.) and does not describe generation-tagged field refs or stale-ref errors for multi-field form fills.
• ⚠️ src/cli.ts:399 - The upload command help still documents/examples an untagged file-input ref (@5) and omits that refs from snapshot output are now generation-tagged and stale refs raise STALE_REF.
• ⚠️ README.md:209 - The state-file documentation lists only bridge.pid, but the change adds persistent snapshot generation state at ~/.chrome-devtools-axi/snapshot-generation. Add this file to the state table so users understand the new persisted state used for stale-ref detection.

Round 2 (auto-fix) - passed ✅

✅ **Lint** - passed

Round 1 - passed ✅

✅ **Push** - passed

Round 1 - passed ✅

[github-actions]

Released in https://github.com/kunchenguid/chrome-devtools-axi/releases/tag/chrome-devtools-axi-v0.1.21.