fix(linux): sync Hyprland cursor telemetry

[eivindjonassen]

Summary

• add a Hyprland cursor-position provider using the compositor request socket
• reuse one Linux window-system resolver and the existing cursor telemetry sampler
• keep provider selection and timing compensation in the main process behind the existing recording-state IPC
• align browser cursor capture with the actual MediaRecorder timeline start

Problem

On native Wayland under Hyprland, Electron and uiohook cannot reliably report the global cursor position outside Recordly windows. This leaves cursor-follow telemetry frozen or intermittent and prevents the editor overlay from tracking the recorded cursor.

Implementation

• validate native Wayland/Ozone mode and the environment-derived Hyprland socket path
• require a successful initial cursor query before enabling the overlay
• cache logical compositor coordinates while retaining the existing sampler as the sole telemetry writer
• fall back to existing Linux cursor sources if Hyprland polling becomes unhealthy
• apply the measured 300 ms Hyprland portal timing correction in the main process
• remove the unused renderer-facing Linux window-system bridge

Verification

• npx tsc --noEmit
• npm run lint (existing repository warnings only)
• npm test (109 files, 1023 tests)
• npx vite build --config vite.config.ts
• live Hyprland portal recording with cursor movement, clicks, editor overlay, and timing verification

Related to #34 and #638.

Summary by CodeRabbit

• New Features

  • Added cursor-overlay support for Linux Wayland sessions using Hyprland.
  • Recording now reports whether cursor-overlay capture is available.
  • Cursor timing is aligned more accurately with the recording timeline.

• Bug Fixes

  • Improved cursor positioning across logical and physical display coordinates.
  • Improved recording startup reliability, including handling of errors and timeouts.
  • Added more consistent Linux display-environment detection.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro Plus

Run ID: 8f44c284-68dc-4e1f-aabd-9d1fb509866e

📥 Commits

Reviewing files that changed from the base of the PR and between 2a81da9 and 44756e0.

📒 Files selected for processing (14)

• electron/electron-env.d.ts
• electron/gpuSwitches.ts
• electron/ipc/cursor/hyprland.test.ts
• electron/ipc/cursor/hyprland.ts
• electron/ipc/cursor/interaction.ts
• electron/ipc/cursor/telemetry.ts
• electron/ipc/register/recording.ts
• electron/ipc/register/sourceMapping.ts
• electron/ipc/state.ts
• electron/linuxWindowSystem.test.ts
• electron/linuxWindowSystem.ts
• electron/preload.ts
• src/hooks/useScreenRecorder.test.ts
• src/hooks/useScreenRecorder.ts

---

📝 Walkthrough

Walkthrough

The change adds shared Linux window-system detection, a Hyprland cursor provider, enriched Linux cursor state, and recording timeline alignment. Browser recording now starts at the actual MediaRecorder boundary and receives cursor-overlay availability from the main process.

Changes

Hyprland cursor capture

Layer / File(s)	Summary
Linux window-system resolution electron/linuxWindowSystem.ts, electron/linuxWindowSystem.test.ts, electron/gpuSwitches.ts, electron/ipc/register/sourceMapping.ts	A shared resolver identifies Wayland and X11 with ordered environment fallbacks. Existing Linux detection callers use the resolver.
Hyprland cursor provider electron/ipc/cursor/hyprland.ts, electron/ipc/cursor/hyprland.test.ts	The provider resolves the Hyprland socket, queries finite cursor coordinates, polls with cancellation, clears failed state, and reports health.
Cursor state integration electron/ipc/state.ts, electron/ipc/cursor/interaction.ts, electron/ipc/cursor/telemetry.ts	Linux cursor state now records coordinate space and source. Native mouse updates pause during Hyprland capture. Logical coordinates avoid display scaling.
Recording timeline integration electron/ipc/register/recording.ts, electron/preload.ts, electron/electron-env.d.ts, src/hooks/useScreenRecorder.ts, src/hooks/useScreenRecorder.test.ts	Recording IPC accepts media-timeline timing and returns cursor-overlay availability. Browser recording starts at the recorder start event and passes the shared timestamp to the main process.

Estimated code review effort: 4 (Complex) | ~45 minutes

Possibly related PRs

• webadderallorg/Recordly#472: Modifies recording and cursor timing integration across the same IPC and recorder files.
• webadderallorg/Recordly#399: Modifies cursor timing behavior in telemetry, recording IPC, and screen recording.
• webadderallorg/Recordly#583: Modifies screen recorder cursor-capture behavior and related tests.

Suggested reviewers: webadderall, meiiie

Sequence Diagram(s)

sequenceDiagram
  participant Renderer
  participant MediaRecorder
  participant RecordingIPC
  participant HyprlandCursorProvider
  Renderer->>MediaRecorder: Start recording
  MediaRecorder-->>Renderer: Emit actual start timestamp
  Renderer->>RecordingIPC: Set recording state with timeline timestamp
  RecordingIPC->>HyprlandCursorProvider: Start cursor polling
  HyprlandCursorProvider-->>RecordingIPC: Report overlay availability
  RecordingIPC-->>Renderer: Return cursor overlay state

Loading

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 0.00% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title clearly identifies the main change: synchronizing Hyprland cursor telemetry on Linux.
Description check	✅ Passed	The description explains the problem, implementation, motivation, verification steps, and related issues, but omits template checkboxes and screenshots.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[AlexSilva-dev]

Great work on the Hyprland position provider, tested on AMD Lucienne + Hyprland 0.56.2 (XDPH 1.4.1) and cursor position via the IPC socket works perfectly (@AlexSilva-dev here).

One gap I hit while building on top of this: button events (clicks) aren't captured, the uiohook X11 path can't see them on native Wayland windows.

I've opened #904 which adds evdev button capture with non-blocking reads on top of this provider's lifecycle, so clicks and position come from the same Hyprland-aware source. Details on the blocking-read libuv threadpool starvation that motivated O_NONBLOCK are in the PR description, worth checking if your branch is affected too.