Module cursor_capture 

Cursor telemetry capture (ED.17 / M-EDIT).

Records where the cursor was during a recording so the editor can drive the cursor overlay (ED.19) and auto-zoom (ED.17’s already-tested auto_zoom_segments) consumer.

What this captures, and what it doesn’t

The cursor position track is captured by polling the global cursor location — CGEventCreate(NULL) + CGEventGetLocation, which read the current pointer position with no Input-Monitoring permission and no event tap. A background thread samples at ~60 Hz; at stop the timestamped samples are resampled onto the project frame grid (samples_to_track).

The click log (for click ripples + auto-zoom) needs a CGEventTap, which does require Input-Monitoring permission and a CFRunLoop callback — that is its sibling module click_capture (ISS-16, resolved). This module ships the no-permission position half.

The pure parts (normalize_cursor_to_frame, samples_to_track) are exhaustively unit-tested; the macOS poller thread is runtime-only.

Modules

imp 🔒

Structs

CursorPoller

Non-macOS stub: cursor capture is macOS-first (ED.17). The editor simply gets no cursor track on other platforms.

Functions

display_bounds_for_source

Bounds (CG points) of the captured display, from the recording’s screen-source id (ISS-17). "display-<id>" → that display’s main_display_bounds-style rect; primary / window / malformed → the main display (window-source framing is a further refinement). Non-macOS: the 1080p placeholder.

main_display_bounds

The main display’s bounds in CG points ((origin_x, origin_y, width, height)) — the rect CursorPoller normalizes the global cursor against. On non-macOS (no capture) returns a 1080p placeholder. The captured display is assumed to be the main one (multi-display targeting is a refinement — see ISS-17).

normalize_cursor_to_frame

Normalize a global cursor point to [0, 1]² within the captured display rect ((origin_x, origin_y, width, height)), top-left origin — the [CursorSample] convention. Points outside the rect clamp to the edge; a zero-size axis maps to 0.0. Pure.

parse_display_id

Parse a CGDirectDisplayID out of a recording’s screen-source id ("display-<id>"). Returns None for the primary display (None / ""), a window source ("window-..."), or a malformed id. Pure.

samples_to_track

Resample timestamped cursor samples ((elapsed_since_start, x, y), sorted by time) onto the project frame grid: each sample’s frame is floor(elapsed_secs · project_fps), and the latest sample at a frame wins (one [CursorSample] per frame). Pure.