Fix macOS camera permission registration on first use

[TheOrcDev]

Summary

• use Electron's exact macOS TCC status so a fresh camera or microphone is shown as Checked on first use with an Enable action instead of the dead-end Open settings path
• route Settings, onboarding, Sources, Diagnostics, preview recovery, and the audio mixer through one user-initiated permission policy; passive microphone visuals cannot trigger a prompt
• make post-grant recovery generation-safe across prompt-time reconnects and deferred restarts, with bounded device/meter proof retries and stale-evidence invalidation
• fail packaged-app validation unless the bundle identifier is exactly dev.theorcdev.videorc and both camera/microphone usage descriptions are non-empty

Fixes #125

Root cause

The Rust backend collapses AVFoundation not-determined, denied, and restricted states into permission-required. The renderer trusted that lossy value on macOS and therefore treated a never-asked camera as denied. Every visible action opened System Settings, but opening Settings cannot create the initial TCC registration; only the existing native askForMediaAccess bridge can do that.

Verification

• focused permission/provider/media tests: 79/79
• pnpm typecheck
• pnpm lint
• pnpm format:check
• pnpm --filter @videorc/desktop test: 1,111 passed, 1 skipped
• pnpm test:scripts: 640/640
• pnpm build
• pnpm check:renderer-assets: 369,926/370,000 gzip bytes
• pnpm audit:deps
• cargo fmt --check --all
• cargo clippy -p videorc-backend -- -D warnings
• final cargo test -p videorc-backend rerun: 1,291 passed, 8 ignored, plus wire test
• real-device native-preview interaction recording, real ScreenCaptureKit layout switching, source-complete native preview, scene/pump/click-focus/placement/reattach/lifecycle behavior
• signed 0.9.41 app: codesign, Gatekeeper, stapling, exact bundle identifier, usage descriptions, capture entitlements, and native addon signing; DMG checks passed
• signed clean-TCC allow/deny/recovery/relaunch acceptance on macOS 27 (current host is macOS 26.5.1)

Acceptance record: docs/acceptance/2026-07-15-issue-125-camera-permission-registration.md

Existing gate blockers observed

• recording-studio aggregates reach the existing split record+stream comment-highlight artifact failure after their relevant permission/preview rows pass
• smoke:local-gates reaches the existing temporary ../../../shared/backend module-resolution failure in smoke:sources
• two real-source preview rows reach the existing admin-only preview.surface.create authorization failure
• full macOS artifact validation additionally requires the local X OAuth1 release environment pair; all new metadata checks pass without recording secret values

This stays draft until the macOS 27 clean-TCC checklist is run on a disposable account, VM, or device.

Summary by CodeRabbit

• New Features
  • Improved camera, microphone, and screen-recording permission onboarding with clearer “Enable” and “Open settings” actions.
  • Preview and diagnostics now provide pane-specific permission resolution guidance.
  • Microphone previews remain inactive until access is granted, reducing misleading device errors.
  • Added recovery messaging for permissions that are granted while devices are still initializing.
• Bug Fixes
  • Improved handling of stale backend connections and delayed permission updates.
  • Prevented outdated audio and device information from overriding current permission state.
• Chores
  • Strengthened macOS release validation for bundle identifiers and required privacy descriptions.

[coderabbitai]

Caution

Review failed

The pull request is closed.

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: 5de7984a-8c2f-44af-9aae-d11e7d94c6b3

📥 Commits

Reviewing files that changed from the base of the PR and between 96b35b6 and 50ef7ef.

📒 Files selected for processing (31)

• apps/desktop/src/main/index.ts
• apps/desktop/src/main/media-access.test.ts
• apps/desktop/src/main/media-access.ts
• apps/desktop/src/renderer/src/backendClient.ts
• apps/desktop/src/renderer/src/components/app-shell.tsx
• apps/desktop/src/renderer/src/components/permissions-onboarding-dialog.tsx
• apps/desktop/src/renderer/src/components/preview-stage.test.ts
• apps/desktop/src/renderer/src/components/preview-stage.tsx
• apps/desktop/src/renderer/src/components/studio/audio-mixer.test.ts
• apps/desktop/src/renderer/src/components/studio/audio-mixer.tsx
• apps/desktop/src/renderer/src/components/studio/mic-picker-preview.tsx
• apps/desktop/src/renderer/src/components/studio/quick-settings.tsx
• apps/desktop/src/renderer/src/components/studio/session-mic-sliver.tsx
• apps/desktop/src/renderer/src/components/tabs/diagnostics-tab.tsx
• apps/desktop/src/renderer/src/components/tabs/settings-tab.tsx
• apps/desktop/src/renderer/src/components/tabs/sources-tab.tsx
• apps/desktop/src/renderer/src/components/tabs/studio-tab.tsx
• apps/desktop/src/renderer/src/hooks/studio-provider.integration.test.ts
• apps/desktop/src/renderer/src/hooks/use-mic-stream.ts
• apps/desktop/src/renderer/src/hooks/use-studio.tsx
• apps/desktop/src/renderer/src/lib/mic-stream.test.ts
• apps/desktop/src/renderer/src/lib/mic-stream.ts
• apps/desktop/src/renderer/src/lib/system-access.test.ts
• apps/desktop/src/renderer/src/lib/system-access.ts
• apps/desktop/src/renderer/src/lib/system-permission-orchestration.test.ts
• apps/desktop/src/renderer/src/lib/system-permission-orchestration.ts
• apps/desktop/src/shared/backend.ts
• docs/acceptance/2026-07-15-issue-125-camera-permission-registration.md
• scripts/lib/macos-release-artifact-validation.mjs
• scripts/lib/macos-release-artifact-validation.test.mjs
• scripts/validate-macos-release-artifact.mjs

---

📝 Walkthrough

Walkthrough

This PR centralizes platform-specific permission decisions, adds backend restart metadata and stale-client handling, updates onboarding and studio UI flows, gates microphone capture on exact grants, expands lifecycle tests, documents acceptance results, and strengthens macOS artifact metadata validation.

Changes

System permission flow

Layer / File(s)	Summary
Permission state and action contracts apps/desktop/src/shared/backend.ts, apps/desktop/src/renderer/src/lib/system-access.ts, apps/desktop/src/renderer/src/lib/system-access.test.ts	Adds structured media-access results, readiness checks, platform-specific state mapping, and action selection for prompts versus settings.
Backend restart and permission orchestration apps/desktop/src/main/*, apps/desktop/src/renderer/src/lib/system-permission-orchestration.ts, apps/desktop/src/renderer/src/hooks/use-studio.tsx	Propagates stale backend boundaries, coordinates permission actions, refreshes media access, waits for replacement clients, and validates microphone grants.
Permission-aware renderer UI apps/desktop/src/renderer/src/components/{app-shell.tsx,permissions-onboarding-dialog.tsx,preview-stage.tsx}, apps/desktop/src/renderer/src/components/tabs/*	Uses actionable permission rows and pane-specific handlers across onboarding, preview, diagnostics, settings, sources, and studio views.
Microphone capture and lifecycle validation apps/desktop/src/renderer/src/hooks/use-mic-stream.ts, apps/desktop/src/renderer/src/lib/mic-stream.ts, apps/desktop/src/renderer/src/components/studio/*, apps/desktop/src/renderer/src/hooks/studio-provider.integration.test.ts	Requires exact microphone grants for acquisition, consolidates mixer notices, forwards permission status to previews, and tests backend-generation and deferred-proof flows.
Acceptance record docs/acceptance/2026-07-15-issue-125-camera-permission-registration.md	Records permission behavior, deterministic checks, runtime evidence, signed artifact results, and blocked macOS 27 validation.

macOS release artifact validation

Layer / File(s)	Summary
Info.plist and stdout validation scripts/lib/macos-release-artifact-validation.mjs, scripts/lib/macos-release-artifact-validation.test.mjs, scripts/validate-macos-release-artifact.mjs	Validates the expected bundle identifier and non-empty camera/microphone usage descriptions, and fails checks when stdout expectations are unmet.

Estimated code review effort: 5 (Critical) | ~120 minutes

Possibly related PRs

• TheOrcDev/videorc#49: Overlaps in renderer permission and onboarding state derivation.
• TheOrcDev/videorc#69: Overlaps in preview-stage permission controls.
• TheOrcDev/videorc#78: Overlaps in preview-stage footer and permission UI behavior.

✨ 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 codex/issue-125-camera-permissions

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 install failed: private package registry requires authentication. Disable ESLint in CodeRabbit settings or use public packages.

---

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.}