# DOX — packages/electron/src

Files in this directory. One row per source file.

| File | Purpose |
|------|---------|
| `main.ts` | Electron main: 5-state startup machine (`checking-server-health` → `attach` \| `launch-server` → `health-wait` → `done` \| `loading-page-error`). No first-run wizard; launch unconditional. See change: auto-launch-first-run-skip-welcome. First-run marker `~/.pi/dashboard/first-run-done` written on first `done` (backwards-compat; Doctor/tooling read it). `registerBundledBridgeExtension()` runs unconditionally before launch-server (formerly gated behind wizard arm). **External-link hardening** (change: harden-external-link-handling, #13): `createMainWindow` registers `webContents.setWindowOpenHandler` + `will-navigate` BEFORE `loadURL` so `target="_blank"` / `window.open` + bare-`<a>` external nav route through `shell.openExternal` (system browser) instead of replacing dashboard. `will-navigate` **OAuth-aware** via `decideWillNavigate(serverUrl, webContents.getURL(), url)` (change: fix-oauth-blocked-by-external-link-guard) — trap-guard fires only when leaving dashboard, so mid-login provider-internal nav + callback redirect land cleanly. See change: electron-server-launch-controls — loadFile(loading.html) replaces inline data:text/html. mainWindow attaches preload exposing piDashboard. Registers ipcMain handlers `dashboard:request-launch`, `dashboard:open-doctor`, `dashboard:read-server-log`. Forwards `dashboard:launch-status` push events. Tray hooks pass `requestServerLaunch` + `isManagedServerRunning`. Startup reads `dashboard-settings.json` before selectLaunchSource; remote mode attaches remoteUrl directly. See change: docker-packaging. |
| `preload.ts` | Exposes `piDashboard` namespace (`requestLaunch`, `openDoctor`, `readServerLog`, `onStatus`) + side-effect imports `doctor-preload` (`window.electron.doctor`) and `remote-connect-preload` (`window.remoteConnect`). `wizardApi` removed with the wizard. See change: auto-launch-first-run-skip-welcome, electron-server-launch-controls. |