Record UI interactions as replayable scripts, for demos and help pages

[jcschaff]

The debug bridge was already a complete replay vocabulary — /click, /menu, /setText, /selectTreeRow — with no recorder attached. This adds the missing half, and then the pieces needed to turn a recording into documentation.

Everything is dev-only, behind the existing -Dvcell.debugBridge=true, so it ships inert.

What you can do now

bridge.sh record start recordings/my-feature.json
# ... drive the feature by hand ...
bridge.sh record stop

bridge.sh replay recordings/my-feature.json                       # semantic: fast, for CI
bridge.sh replay recordings/my-feature.json --driver robot        # cursor moves: filmable
bridge.sh replay recordings/my-feature.json --shots /tmp/shots --shot-scale 0.5
doc-scaffold.py recordings/my-feature.json --shots /tmp/shots --target MyFeature --out page.xml

Semantic capture, never coordinates. Each step names its target the way the bridge already resolves one — name= first because it survives layout changes, a node path next, a registry id last. Pixel positions are never stored.

One recording, two replay drivers. semantic fires buttons through doClick() and moves no cursor — right for CI. robot glides the pointer and clicks for real — the only mode worth filming, since a click with no pointer near it reads as broken. Same artifact either way.

Acceptance test

scenarios/detach-window-recorded.sh makes the same assertions as the hand-written detach-window.sh, but every user action comes from a capture. It passes 15/15 under both drivers, and the hand-written original still passes its 18. Steps replay one at a time (--from/--to) so state is checked between clicks — playing the whole script and asserting once at the end would pass even if detach and reattach both did nothing.

Help-page generation

doc-scaffold.py turns a recording plus its captures into a <vcelldoc> skeleton for UserDocumentation/originalXML. It writes only the mechanical parts — ordered steps, image references, matching target and title — and leaves prose to a person; auto-generated help text reads like auto-generated help text.

Verified end to end: a generated page compiles through DocumentCompiler and renders with its images inline.

The SpringSaLaD help pages this was first tested against are tracked separately in #2060 — that TOC change is not part of this PR.

Things this learned against the running client

Each of these presents as "the recorder is broken":

• doClick() is invisible to the recorder — it calls listeners directly and posts no event, so a session driven with bridge.sh click records nothing. Hence rbclick (native press/release).
• MOUSE_CLICKED is unusable for menus. It is synthesized after the release, and a click that dismisses the popup it landed in destroys its own component first, so it never arrives. Capture is on press/release.
• Not everything in a menu bar is a menu. The detach toggle is a JMenuItem whose entire label is a tooltip, so /menu — which matches items by visible text — cannot address it. Text-less items fall back to a click by name.
• A modal dialog produces zero events. On a source build the version-mismatch warning appears a moment after the menus do. record status reports rawEvents precisely to separate "saw nothing" from "captured nothing".
• A screenshot taken too early silently documents the wrong screen. /idle drains the EDT, but VCell fills panels from background tasks — two different steps produced byte-identical images. Hence --shot-delay.
• Detaching replaces a window, so identity-based "new window" detection fired on a window that never left the screen. Detection compares titles.

Durability

An index is not a durable way to name a thing, and it is not documentation either:

• Rows and tabs record their displayed text alongside the index; replay resolves by text first. A biomodel holds zero or more applications of any type in any order, so a recorded row number is only true for the tree as it stood.
• /tree rows report userType and applicationType, and /findRow takes appType, so "find the SpringSaLaD application" works in any model. The four in the example file report RULE_BASED_STOCHASTIC, SPRINGSALAD, NETWORK_DETERMINISTIC, NETWORK_STOCHASTIC.
• /findRow searches the whole tree/table model — /tree caps its dump at 25 table / 100 tree rows, so a chooser in a 137-entry directory was previously undrivable.
• Each step records how durable its selector is, turning naming debt into a list you can read off a fresh recording. That is how the SpringSaLaD panels got named: they had zero setName calls, and 3 of 4 recorded steps resolved only by path. Now all four resolve by name.

Crash safety

The script is flushed after every step, written via a .part file and renamed into place, so a kill -9 mid-session leaves a valid script of everything up to that point rather than nothing. Serializing happens on the EDT where the step list is consistent; the I/O goes to one background thread so a slow filesystem cannot stutter the UI being recorded. Verified by killing the client mid-recording.

Note for reviewers

The help build profile activates only when target/classes/vcellDoc is missing, so a plain rebuild silently skips it and doc changes appear to have no effect. Remove that directory or run DocumentCompiler directly.

🤖 Generated with Claude Code

https://claude.ai/code/session_019HAnpFxkzf9LmxBayDSANf