fix(windows): report supported preview surface as live

[TheOrcDev]

Problem

Windows intentionally presents preview through Videorc's Electron proof surface, but the main process unconditionally reported that presenter to the lifecycle supervisor as a fallback. Studio therefore showed Preview Is Using Fallback Rendering even after the supported Windows presenter was live.

The inverse edge matters too: a pending, never-first-frame, or stalled proof presenter must not be promoted to healthy merely because its BrowserWindow exists.

Plan and implementation

• Centralize the mapping from PreviewSurfaceStatus to the user-facing supervisor lifecycle.
• Treat the Windows Electron proof surface as surface-live only after its first-frame contract is met.
• Preserve starting-surface while the first source frame/poller is pending.
• Keep the Electron proof path a truthful fallback on macOS, where production preview promises CAMetalLayer.
• Document the platform contract explicitly in AGENTS.md and ADR 0001: macOS remains CAMetalLayer-native, while Windows' currently supported production presenter is the uncompressed latest-wins BMP proof surface and must never be described as native.
• Add a Windows proof-surface watchdog independent of the macOS Metal watchdog:
  • compositor-only/no-source scenes may become healthy after proof presentation;
  • scenes that expect screen, window, or camera pixels remain pending for the full 15-second startup budget until every active source poller has delivered once;
  • only previously-live source pollers use the 1.5-second stall budget, and missing-first-frame versus retained-last-frame failures show different truthful diagnoses;
  • hidden/suppressed proof surfaces are paused, and renderer metric reads are bounded and single-flight so a hung proof renderer cannot wedge health reporting or accumulate abandoned reads;
  • watchdog run/tick ownership prevents a deferred close/reopen tick from mutating or clearing the replacement window's health check.
• Strengthen the maintained preview-window gate so Windows readiness requires a live supervisor and a met first-frame contract, not merely a visible BrowserWindow.

Acceptance criteria

• A healthy Windows proof presenter transitions the supervisor to surface-live and clears the false fallback warning.
• Pending/undefined first-frame state remains starting-surface.
• A source scene with no poller/first frame eventually reports a real fallback instead of false health.
• A previously healthy source that stalls reports the source-frame diagnosis, not healthy compositor copy.
• A compositor-only scene has an explicit healthy outcome.
• macOS proof-surface fallback semantics remain unchanged.
• Preview-window smoke evidence requires both supervisor and first-frame proof.

Verification

• Desktop unit suite, Node script suite, TypeScript typecheck/lint/format, and desktop build.
• Native preview lifecycle, preview-window, strict preview-surface, scene-commit, pump-diagnostics, click/focus, and interaction-stress probes.
• Device-backed preview interaction recording and real ScreenCaptureKit live-layout record/stream artifact analysis.
• pnpm smoke:recording-studio was run; see Known gate blockers below.

Known gate blockers

• The maintained vertical-layout source-loop test currently leaves the Metal target at 960x540 instead of adopting portrait 540x960. The identical failure reproduces from an untouched comparison branch and is outside this Windows supervisor-status change.
• The comment-highlight split record/stream artifact scenario reports zero highlight frames on the untouched path while its stream-only scenario passes.
• This macOS desktop session intermittently cannot expose the foreground stimulus/native display to the standalone real-screen gate. The separate device interaction and real ScreenCaptureKit record/stream gates passed.

Non-goals and follow-up

• This does not add a native DirectComposition/D3D Windows presenter or claim a rendering-performance improvement. It makes the existing supported presenter truthful and keeps genuine stalls visible.
• Final acceptance still needs the Windows CI job plus a physical Windows alpha run that opens, closes, and reopens Preview with real screen/camera sources.
• PR feat: green screen / chroma key for the camera layer #116 also edits apps/desktop/src/main/index.ts; whichever lands second may need a focused rebase.

Closes #115

Summary by CodeRabbit

• Bug Fixes
  • Improved preview startup reliability by preventing stale checks from affecting restarted or closed previews.
  • Windows previews now verify that frames are actively presented before reporting readiness.
  • Preview windows no longer appear ready while still pending, stalled, or in fallback.
  • Added clearer fallback details when native preview transport is unavailable or presentation stalls.
• Documentation
  • Clarified platform-specific native preview behavior and Windows proof-surface expectations.

[coderabbitai]

Caution

Review failed

The pull request is closed.

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: b893ede9-1b52-45ac-948c-55b028391b4b

📥 Commits

Reviewing files that changed from the base of the PR and between 4dabc59 and 9965dd9.

📒 Files selected for processing (11)

• AGENTS.md
• apps/desktop/src/main/index.ts
• apps/desktop/src/main/native-preview-first-frame.test.ts
• apps/desktop/src/main/native-preview-first-frame.ts
• apps/desktop/src/main/native-preview-host-policy.test.ts
• apps/desktop/src/main/native-preview-host-policy.ts
• apps/desktop/src/main/native-preview-proof-poller-runtime.test.ts
• apps/desktop/src/main/native-preview-proof-poller-runtime.ts
• docs/adr/0001-obs-parity-native-capture-architecture.md
• scripts/lib/native-preview-window-gates.mjs
• scripts/lib/native-preview-window-gates.test.mjs

---

📝 Walkthrough

Walkthrough

Windows preview now uses a proof-frame watchdog with tokenized ownership, bounded renderer reads, frame-history checks, and explicit pending/live/fallback supervisor states. Preview readiness gates and platform documentation now reflect first-frame and proof-surface requirements.

Changes

Preview proof supervision

Layer / File(s)	Summary
Supervisor policy and frame-history contracts apps/desktop/src/main/native-preview-host-policy.ts, apps/desktop/src/main/native-preview-proof-poller-runtime.ts, apps/desktop/src/main/*test.ts	Supervisor lifecycle states and complete poller frame history are classified and tested.
Proof assessment and concurrency primitives apps/desktop/src/main/native-preview-first-frame.ts, apps/desktop/src/main/native-preview-first-frame.test.ts	Proof readiness, fallback reasons, bounded reads, single-flight behavior, and watchdog tick ownership are implemented and covered by tests.
Main-process watchdog integration apps/desktop/src/main/index.ts	Windows proof watchdog startup, renderer metric reads, stalled-pump retirement, and supervisor surface synchronization are wired into the main process.
Readiness gates and platform documentation scripts/lib/native-preview-window-gates.*, AGENTS.md, docs/adr/0001-obs-parity-native-capture-architecture.md	Window readiness requires supervisor and first-frame readiness, and platform presenter contracts are documented and tested.

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

Possibly related PRs

• TheOrcDev/videorc#66: Both changes modify native-preview first-frame and watchdog logic.
• TheOrcDev/videorc#79: Both changes update Windows proof polling and first-frame contract decisions.

✨ 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-115-windows-preview-status

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