#34

feat: add cursorSpeed to control how fast the cursor travels

Openrileyjshawwants to merge intofrom

Summary

Cursor travel is timed from the distance covered (moveDuration in cursor-motion.ts, and computeDragTiming for drags), tuned to feel like a human hand. There is no way to adjust it. On a dense config the cursor spends a lot of the runtime gliding, and the only lever today is speeding up the finished file in post, which speeds up typing and deliberate pauses along with it.

cursorSpeed scales the travel duration and nothing else:

{
  "cursorSpeed": 1.75,
  "videos": {
    "hero": {
      "url": "/",
      "cursorSpeed": 1,
      "steps": [{ "action": "click", "text": "Get Started" }]
    }
  }
}

2 covers the same ground in half the time, 0.5 takes twice as long. Typing speed (charDelay), click dwell (clickDwell) and step delays (delay / defaultDelay) are unaffected, so the pacing of the demo itself is preserved while dead travel time shrinks. It sits alongside clickDwell: settable at the top level, per video, and inherited the same way.

The multiplier lives on RecordingContext, so both plain moves and drags pick it up, and the eased path and jitter are unchanged: only the duration scales.

Test plan

  • pnpm test (106 core, 112 webreel), pnpm type-check, pnpm lint, pnpm format:check
  • New tests: context default and clamping of nonsense values, and drag timing halving at cursorSpeed: 2
  • Recorded the same 22-step config at three speeds, everything else held constant:
cursorSpeedoutput duration
1 (default)56.9s
1.7538.5s
329.9s

Typing, click dwell and step delays are identical across all three; only travel time changes.

No changeset here, per the release process in AGENTS.md; happy to send one in a follow-up PR.

Generated with Claude Code

Activity

5
vercel[bot]2mo ago

@rileyjshaw is attempting to deploy a commit to the Vercel Labs Team on Vercel.

A member of the Team first needs to authorize it.

vercel[bot]reviewed2mo ago
vercel[bot]2mo ago

Additional Suggestions:

  1. Published JSON schema v1.json omits the cursorSpeed option, so editors reject valid configs using it due to additionalProperties: false
  1. The exported InputWebreelConfig type is missing the top-level cursorSpeed? option, causing a TS compile error for defineConfig users who set it.

rileyjshaw2mo ago

Both good catches, fixed in dd1e365.

  1. cursorSpeed is now in apps/docs/public/schema/v1.json at the top level and on the video definition. With additionalProperties: false a valid config was being flagged in editors, which is worse than the option simply not being documented.
  2. InputWebreelConfig now carries the top-level cursorSpeed?. The per-video side was already covered, since InputVideoConfig derives from VideoConfig.

I also added packages/webreel/src/lib/__tests__/schema.test.ts, which walks the validator's known-key sets and asserts the published schema documents each one, for top-level options, video options and every step field. It fails on the pre-fix schema, so this class of drift cannot come back silently. That required exporting the three KNOWN_*_KEYS sets from config.ts.

Running it against main as-is passes, so nothing else has drifted today.