feat(pace): command pacing for recorded runs - #316

Lets a recorded twd-cli run space out its own commands, so the video is watchable instead of a blur.

This is the twd-js half. It does nothing on its own until twd-cli drives it, which is a separate PR in that repo.

Why not just slow the video down

twd-cli already has record.speed, an ffmpeg setpts filter applied after recording. It stretches the same frames over a longer timeline, so the effective frame rate falls in proportion. Measured on identical page activity:

It also slows the dead air exactly as much as the interesting moments. TWD owns its own in-page command loop, so it can pace the execution instead and keep full frame rate.

How it is enabled

window.__twdSetPace(ms), registered alongside the existing __TWD_STATE__ and __testRunner globals.

Deliberately not a public twd.setPace(). A documented API method can be left behind in a spec file, and every future CI run would then be slower with no obvious cause. There is a test asserting it never leaks out of src/index.ts or onto the twd object.

One number, two scales

The caller passes one number. The keystroke delay is derived from it and clamped at 60ms, because user-event applies delay uniformly and reusing the pace itself would put half a second between every character.

What is paced, and what is not

Paced: userEvent.* interactions and twd.visit. Both are already async, so nothing became async that was not.

Not paced, on purpose: should() and twd.setInputValue() are synchronous chainables and pacing them would be a breaking change; the screenDom proxy is a pass-through with no uniform hook; queries do not change the page, so a pause after one is dead air with no highlight to show.

Keystroke spacing

user-event applies delay at config level, in wrapAndBindImpl after every API method as well as between keystrokes, pointer actions and option selections. So when paced the proxy routes through a cached setup({ delay }) instance rather than merging options per call. That covers every method uniformly and sidesteps clear(element) being the one direct API method that takes no options.

The cache is keyed on a pace generation counter, not on the delay, so setting the same value twice still invalidates.

Behavior note: the direct API builds a fresh System per call while a setup instance shares pointer state across calls. That is the library's recommended usage and arguably more realistic, and it only applies when pacing is on, which only happens inside a recorded run.

Normal runs are untouched

pace() returns undefined synchronously when disabled: no promise allocated, no timer scheduled, no setup instance built. There is a test pinning that it returns undefined and not a Promise, which fails loudly if anyone later makes it an async function.

Verification

439 tests passing, up from 406. tsc unchanged at its 4 pre-existing errors, none in the touched files.

Driven end to end against examples/twd-test-app with Puppeteer:

window.__twdSetPace is a function
pace 0   -> applied=0    run took 120ms
pace 600 -> applied=600  run took 718ms   (6.0x slower)

120 + 600 = 720 against a measured 718, so the hold lands exactly once per action and setPace(0) restores full speed. Manually confirmed at 200 and 500, which both read well.

Included docs

specs/2026-07-28-twd-js-command-pacing-design.md is the design and specs/2026-07-28-twd-js-command-pacing-plan.md is the plan. The earlier overlay draft is kept but marked superseded: overlays are dropped for v1, since the only reason to pause after a query is to highlight what it found.

No public documentation is added, because __twdSetPace is deliberately not public API.

Next

twd-cli gains a record.pace key and a --record-pace <ms> flag that calls this. That needs a twd-js release first, since the global does not exist until then.