Improve optional helper setup and desktop renderer browser guidance
- Dominant language
- TypeScript
- Stars
- 72.1k
- Forks
- 4.7k
- Avg merge
- 14h 54m
- Merged PRs (30d)
- 520
Description
## Problem
The desktop development workflow exposes two confusing failure modes:
1. `pnpm dev` starts successfully even when the optional macOS Computer Use helper has not been built, but setup actions fail later with `Orca Computer Use.app was not found` and no development-specific recovery path.
2. Vite prints the Electron renderer URL as a normal localhost link. Opening `/` in a browser loads the desktop application without Electron's preload bridge and shows the generic root renderer error.
## Root cause
The dev runner has no optional-helper preflight or opt-in preparation path. Computer Use actions can also race the initial helper-status request. Separately, the renderer entry statically imports the Electron application before checking whether `window.api` was installed by preload.
## Acceptance criteria
- Ordinary `pnpm dev` remains usable when the optional macOS helper or Xcode toolchain is unavailable.
- A missing or incomplete helper produces one actionable development warning.
- A valid `ORCA_COMPUTER_MACOS_HELPER_APP_PATH` override follows the same executable validation used at runtime.
- Developers can explicitly request one-time helper preparation without adding cost to every startup.
- Computer Use setup cannot invoke `openSetup` while helper status is loading, unknown, or unavailable.
- A normal browser opening the desktop renderer entry does not import `App`; it receives a clear explanation and the development `/web-index.html` route.
- Electron startup remains unchanged when the preload bridge exists.
- Focused tests cover the production runner and actual renderer-entry wiring.
Contributor guide
Assessment
This issue has not been assessed yet.