feat(cv): on-demand Python CV worker lifecycle + Windows setup

[rxv801]

Summary

Connects the Electron app to the Python CV worker, and changes the worker so it only runs while something actually needs detection instead of staying up for the whole app session. Also adds the onboarding camera-check screens that use it, plus a Windows setup script.

What this PR does

On-demand CV worker lifecycle (python-bridge.ts)

• The worker is reference-counted. It starts on the first request and stops a short grace period (2s) after the last release, so nothing runs while no session or check is active. The grace period keeps it from dying and respawning on a quick pause/resume, a page change, or React StrictMode's double-mount in dev.
• If the worker crashes on its own it gets relaunched, capped at 5 rapid restarts so a broken setup can't spin forever. A worker that stays up long enough resets that counter.
• If the venv is missing it logs a plain "run setup" message instead of a cryptic ENOENT. Detection just stays off and the rest of the app keeps working.
• Removed the launch-time start from index.ts. The quit-time stop stays as a safety net.

Renderer to main wiring

• ipc-handlers, preload, and vite-env expose window.taskmaster.cv.request / release.
• useCvDetection asks for the worker before opening its WebSocket and releases it on cleanup.

Onboarding camera checks

• New OnboardingFaceCheck and OnboardingPhoneCheck pages stream the camera to the worker through useCvDetection and show live feedback. Wired into OnboardingPage.

Windows setup

• setup.ps1 is a PowerShell version of setup.sh (venv 3.11, pip deps, model downloads, npm install). The README points to both.

Testing

I ran the full app, not just the build. The worker started only once the renderer asked for it, MediaPipe gaze ran on a live camera frame over the WebSocket, and it shut down cleanly on quit. tsc -b && vite build and eslint . are both clean.

Notes

This branch already has the latest main merged in, including #16 (mini-timer). The two features don't touch each other and run side by side.

[lukitasxue]

@copilot check for possible security issues

[Copilot]

@copilot check for possible security issues

Addressed in a108806.

I reviewed the CV worker path and added hardening in python/main.py:

• reject oversized WebSocket frames (MAX_FRAME_BYTES, close with code 1009)
• guard detector execution with exception handling so malformed input can’t crash-loop the worker

Validation run: Electron lint/build, Python compile check, secret scan, and CodeQL (0 alerts).

[lukitasxue]

Hey Saatvik, this PR looks good overall and I like the direction of the on-demand CV worker. I just noticed 2 small things I think we should fix before merging.

First, setup.ps1 still tells Windows users to run python cv\detection_loop.py at the end, but this PR now uses python/main.py through Uvicorn as the worker entry point. That instruction could confuse someone setting up the project. I’d either update it to something like:

cd python
.\.venv\Scripts\Activate.ps1
python -m uvicorn main:app --port 8765

or simply say that after running setup, Electron will start the CV worker automatically when detection is needed.

Second, in useCvDetection, we call window.taskmaster.cv.request() before opening the camera. If getUserMedia() fails because the camera is denied, missing, busy, or the saved camera ID is invalid, the catch block only logs the error. That means the Python worker request may stay active while the user remains on the screen, even though no frames are being sent. Cleanup will release it on unmount, but I think we should release it immediately if startup fails.

I’d fix it by tracking whether the CV worker was requested, then calling window.taskmaster.cv.release() inside the catch path when startup fails.

Apart from that, the architecture makes sense to me.

[lukitasxue]

looking good now!