[codex] Structure browser recording failures

[juliusmarminge]

Summary

• replace generic browser recording failures with schema-tagged errors carrying stable tab, conflict, canvas, and operation context
• retain exact browser/media/bridge causes for initialization, screencast, recorder, and artifact failures
• preserve both primary and cleanup failures with an aggregate cause when shutdown fails concurrently

Verification

• vp test apps/web/src/browser (9 tests)
• vp check (passes with 20 pre-existing warnings)
• vp run typecheck

---

Note

Low Risk
Localized error-handling refactor in preview recording; behavior is clearer on failure paths with no auth or data-model changes.

Overview
Replaces generic Error throws in browserRecording.ts with Effect Schema tagged errors so callers can distinguish unavailable bridge, tab conflict, missing canvas, and per-step operation failures (with tabId, dimensions, or operation + underlying cause).

startBrowserRecording now wraps MediaRecorder setup, frame subscription, recorder start, and screencast start in separate try/catch blocks; failed screencast start runs recorder cleanup and may surface an AggregateError when both start and cleanup fail.

stopBrowserRecording runs stop screencast → stop recorder → save artifact as labeled steps, then always attempts cleanup/clear in finally; primary failures can be combined with cleanup failures via BrowserRecordingOperationError with operation: "cleanup" and AggregateError.

^{Reviewed by Cursor Bugbot for commit d9e431c. Bugbot is set up for automated code reviews on this repo. Configure here.}

Note

Add structured error classes to browser recording operations

• Introduces four typed error classes in browserRecording.ts: BrowserRecordingUnavailableError, BrowserRecordingConflictError, BrowserRecordingCanvasUnavailableError, and BrowserRecordingOperationError, all using Schema.TaggedErrorClass.
• startBrowserRecording now throws specific error types per failure stage (unavailable bridge, tab conflict, missing canvas context, recorder init, frame subscription, screencast start) and only sets the active tab atom after a successful screencast start.
• stopBrowserRecording sequences stop-screencast, stop-media-recorder, and save-artifact in separate try/catch blocks, each throwing a scoped BrowserRecordingOperationError.
• When both a primary operation and its cleanup fail, an AggregateError combining both causes is wrapped in BrowserRecordingOperationError('cleanup').
• Behavioral Change: callers previously receiving generic Error instances will now receive typed error objects; combined failure paths surface AggregateError instead of a single error.

^{Macroscope summarized d9e431c.}

[coderabbitai]

Important

Review skipped

Auto reviews are disabled on this repository. Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: Repository UI

Review profile: CHILL

Plan: Pro

Run ID: ec5375d6-c898-4b47-9555-0f1396881834

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch codex/browser-recording-errors

---

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

[macroscopeapp]

Approvability

Verdict: Approved

This PR refactors error handling in browser recording by replacing generic errors with structured, typed error classes. The core recording logic and behavior remain unchanged - only the error reporting is improved for better debugging.

^{You can customize Macroscope's approvability policy. Learn more.}