[kalwei]

What Scott will see

In a take filmed by scripts/record-scene.py:

• A drawn arrow cursor. It glides for half a second to each field, button and drop-down a scene uses. A ring ripples out at the moment of the real click. The cursor stays under the caption bar and the badge, and is not drawn on slides.
• A box round the thing a line is about. A say can now point at a selector. The recorder scrolls the thing into view, clear of the page's sticky header and the caption bar. It then draws a cyan outline with a short label tab. The box stays for the line's hold, and through any mark straight after it, so that still shows the box. It is gone before the next step. With style = "spotlight", the rest of the page is dimmed too. If the thing is not on the page, the take is refused and the message names the step number.
• Typing you can read. About 12 keys a second (0.085 s a key) instead of 25. A scene can slow it further with type_delay_seconds. For a choose, the cursor goes to the drop-down, clicks it, and the value changes. A page script cannot open a native <select> list, so the list itself is not shown.

A say without at behaves exactly as before. Its marks.json entry has the same keys as before. The five class scenes are not edited, and no product page or CSS is changed.

Four stills from a 23 s proof take on a scratch cutlery plant (loopback, 10×). They are local files, listed in the handoff's Result:

• a box with its label round the routings count, scrolled out from under the sticky header;
• the spotlight still a mark took right after its line, with the rest of the page dimmed;
• the routing code half typed, with the cursor on the field;
• the ripple on "Add operation" as it is pressed.

Scene file: new settings

where	key	meaning
scene	type_delay_seconds	seconds between typed keys; default 0.085, at least 0.05
say	at	selector of the thing the line is about
say	label	a few words on the box's tab (needs at)
say	style	box (default) or spotlight (needs at)

marks.json: new keys (additive only)

• say with at:
  • box {x, y, w, h}: the drawn box in frame pixels, clipped to the frame
  • label, selector, style
• click, fill, choose:
  • cursor_from {x, y}: where the cursor started its glide
  • ripple_at: seconds into the take when the ripple began, just before the press
• fill, choose: x, y, where the press landed (click already had these)
• fill: typed_seconds, how long the typing took

No existing key is changed or removed.

How it was checked

• New fast tests in tests/test_a_scene_points_at_what_each_line_is_about.py. They cover:
  • which keys the scene file accepts and refuses
  • what play hands the stage, and that a stage written for the old two-argument say still plays
  • the typing pace and the glide counted in the plan
  • that every scene in the repo still loads
• New browser tests in tests/test_the_recorder_draws_a_cursor_and_a_box_a_viewer_can_follow.py, on the shared live_server demo plant. They check:
  • the box is in frame pixels
  • a plain say mark has exactly its old keys
  • press marks carry cursor_from and ripple_at
  • the cursor sits on the button after a click
  • z-order: cursor below the caption, caption below the badge
  • typing takes at least a twelfth of a second a key
  • a refused take names its step number
  • the box stays through a mark after its line, and is gone when the next step begins
  • a target that starts under the sticky header is scrolled out; the label is not drawn on the header (this test fails with the fix taken out)
  • a frame-filling box keeps its label on screen
• Full -m browser tier, the fast suite and ruff check . all pass (the browser tier and the recorder and scene fast tests run again after the last commit).
• namegrep over the diff, the commit messages, the branch name and this body: 0 hits.
• The proof take: the badge is present in 223 of 223 GIF frames and 466 of 466 mp4 frames, and the corner check is clean.

Notes for scene authors

• Point at at something smaller than the frame. A box round a section taller than the screen is clipped, and its label goes inside its top-left corner.
• The ripple is drawn where the press landed. If the page moves as a result (a new row pushes the button down), the ripple stays where the click happened and the cursor follows the button.
• No nav element resisted a click in the proof, so nothing needed fixing there.

🤖 Generated with Claude Code

[github-actions]

Thanks for the first pull request. Checks: every commit signed off (git commit -s), ruff and pytest green, and the house-rules checklist in the template. The maintainer reviews within a few days.