fix(linux): guard cursor overlay when portal embeds cursor

[meiiie]

Summary

• stop reporting non-Windows OS cursor hiding as successful when there is no native cursor hider
• make Linux portal/browser capture policy explicit and inspect MediaTrackSettings.cursor after capture
• when Linux capture does not confirm cursor: never, persist the session as cursor-overlay unavailable and prevent enabling the overlay to avoid double cursors

Verification

• npx vitest run src/hooks/useScreenRecorder.test.ts
• npx tsc --noEmit
• npx biome lint src/hooks/useScreenRecorder.ts src/hooks/useScreenRecorder.test.ts src/components/video-editor/VideoEditor.tsx src/components/video-editor/SettingsPanel.tsx electron/ipc/register/settings.ts electron/ipc/register/project.ts electron/ipc/types.ts electron/preload.ts electron/electron-env.d.ts
• git diff --check

Notes

• npx biome check on the same scoped files still reports pre-existing formatter/import-order churn in large repo files, so this PR avoids applying a broad format rewrite.
• Linux Wayland/PipeWire cursor hiding depends on the portal/compositor honoring cursor-hidden capture. This patch keeps Recordly from rendering a second cursor when that cannot be confirmed.

Summary by CodeRabbit

• Bug Fixes

  • Cursor overlay controls are disabled when captured video already contains the system cursor; an informational message explains why.
  • Platform detection for cursor capture improved; cursor-hide requests on unsupported platforms now return explicit unsupported info (with platform).
  • Recording/session state now carries a flag indicating native-capture availability so the editor reflects actual capture capabilities.

• Tests

  • Expanded test coverage for cursor handling across browser, native, and Linux portal capture scenarios.

[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: 4e8f6a52-c3d8-4989-a962-547fe207b28e

📥 Commits

Reviewing files that changed from the base of the PR and between 32bb6e4 and 107139b.

📒 Files selected for processing (1)

• electron/ipc/register/project.ts

🚧 Files skipped from review as they are similar to previous changes (1)

• electron/ipc/register/project.ts

---

📝 Walkthrough

Walkthrough

Tracks when native capture cannot hide the OS cursor by computing a nativeCaptureUnavailable flag, persisting it through IPC/session updates, and using it to disable UI cursor-overlay controls and surface explanatory feedback.

Changes

Native Capture Unavailability Tracking

Layer / File(s)	Summary
Type and IPC contracts electron/electron-env.d.ts, electron/preload.ts, electron/ipc/types.ts, electron/ipc/register/project.ts	Extended renderer API types (setCurrentVideoPath, setCurrentRecordingSession, getCurrentRecordingSession) and IPC handler signatures with optional nativeCaptureUnavailable?: boolean. Expanded hideOsCursor return type to include unsupported?: boolean and platform?: string.
Cursor availability detection and helpers src/hooks/useScreenRecorder.ts, src/hooks/useScreenRecorder.test.ts	Added nativeCaptureUnavailable to BrowserCaptureCursorPolicy, implemented platform-aware cursor policy resolution, exported getScreenCaptureCursorSetting and resolveLinuxPortalCursorPresentation, and added tests for Windows failure, Linux portal behavior, and normalization.
Recording session lifecycle persistence src/hooks/useScreenRecorder.ts, electron/ipc/register/project.ts	Introduced nativeCaptureUnavailableForCursorOverlay ref, reset at recording start, set from computed policy, and persisted in both immediate and background finalization via setCurrentRecordingSession / setCurrentVideoPath.
UI gating and user feedback src/components/video-editor/SettingsPanel.tsx, src/components/video-editor/VideoEditor.tsx, electron/ipc/register/settings.ts	Disabled cursor overlay toggles when nativeCaptureUnavailableSession is true, show informational alert, and prevent enabling overlay (opens modal). Updated hide-cursor IPC handler to return { success: false, unsupported: true, platform } on non-Windows platforms.

Estimated Code Review Effort

🎯 4 (Complex) | ⏱️ ~40 minutes

Possibly Related PRs

• webadderallorg/Recordly#583: Related cursor-policy changes and handling of native Windows capture failures.
• webadderallorg/Recordly#254: Prior changes introducing electron/ipc/types.ts (shared RecordingSessionData) that this PR extends.

Suggested Labels

Checked

🐰 I hopped through tracks and frame by frame,
native capture whispered it couldn't tame,
So I tucked the overlay snug and tight,
and left a breadcrumb of cursor-light. ✨

🚥 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 pull request title accurately describes the main objective: guarding cursor overlay specifically when the Linux portal embeds the cursor.
Description check	✅ Passed	The PR description provides a clear summary of changes, motivation, verification steps, and notes explaining the rationale, covering most template sections despite not following the exact template format.
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.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch fix/linux-cursor-control-appimage

Warning

There were issues while running some tools. Please review the errors and either fix the tool's configuration or disable the tool if it's a critical failure.

🔧 ESLint

If the error stems from missing dependencies, add them to the package.json file. For unrecoverable errors (e.g., due to private dependencies), disable the tool in the CodeRabbit configuration.

ESLint skipped: no ESLint configuration detected in root package.json. To enable, add eslint to devDependencies.

---

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 and usage tips.}

[meiiie]

@coderabbitai review

[coderabbitai]

✅ Actions performed

Review triggered.

Note: CodeRabbit is an incremental review system and does not re-review already reviewed commits. This command is applicable only when automatic reviews are paused.

[meiiie]

@coderabbitai review

[coderabbitai]

✅ Actions performed

Review triggered.

Note: CodeRabbit is an incremental review system and does not re-review already reviewed commits. This command is applicable only when automatic reviews are paused.

[coderabbitai]

Actionable comments posted: 1

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@electron/ipc/register/project.ts`:
- Around line 551-553: The merge logic for nativeCaptureUnavailable currently
uses logical OR which treats an explicit false in options as unset and can leave
a stale true from resolvedSession; change the selection to prefer options when
it is present (including explicit false) by using nullish coalescing or an
explicit undefined check so that normalizeBoolean receives
(options?.nativeCaptureUnavailable ?? resolvedSession.nativeCaptureUnavailable)
instead of normalizeBoolean(options?.nativeCaptureUnavailable) ||
normalizeBoolean(resolvedSession.nativeCaptureUnavailable); update the code
where nativeCaptureUnavailable is assigned and keep using normalizeBoolean,
referencing the existing symbols options, resolvedSession, and normalizeBoolean.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro Plus

Run ID: 429afefa-c55d-45d6-ae2f-2c96a3ec003e

📥 Commits

Reviewing files that changed from the base of the PR and between 338d658 and 32bb6e4.

📒 Files selected for processing (9)

• electron/electron-env.d.ts
• electron/ipc/register/project.ts
• electron/ipc/register/settings.ts
• electron/ipc/types.ts
• electron/preload.ts
• src/components/video-editor/SettingsPanel.tsx
• src/components/video-editor/VideoEditor.tsx
• src/hooks/useScreenRecorder.test.ts
• src/hooks/useScreenRecorder.ts