feat(frontend): rebuild Electron desktop UI as a React + Vite renderer

[ashish921998]

What

Rebuilds the Electron desktop frontend as a React + Vite + TypeScript renderer and implements the full intended stack boilerplate (see the layer table below). Started as a restyle of the single-file main.ts, pivoted to a real renderer architecture, then filled in every stack layer.

Stack status

Layer	Choice	Status
Shell	Electron + child_process daemon supervision	✅
UI	React 19 + TypeScript	✅
Build	vite-plugin-electron + electron-builder	✅ (auto-update scaffolded, needs signing)
Data	TanStack Query + EventTransport	✅ EventTransport subscribes to the /api/v1/events CDC SSE + daemon IPC
API types	openapi-typescript + openapi-fetch	✅
Styling	Tailwind + shadcn/ui	✅ Badge/Tabs/Button/Input/Tooltip all in use
Layout	react-resizable-panels	✅ resizable sidebar split, sizes persisted to Zustand
Terminal	@xterm/xterm	✅ per-session PTY over the /mux WebSocket + WebGL (canvas fallback)
UI state	Zustand	✅ selection, active pane, theme, layout sizes
Testing	Vitest + RTL · Playwright	✅ both

Highlights

• Per-session terminal. New terminal-mux.ts WebSocket client speaks the daemon /mux protocol (open/data/resize/close, base64 frames) matched to backend/internal/terminal/protocol.go; TerminalPane streams real PTY output, forwards keystrokes/resize, and renders via the WebGL addon. Framing is unit-tested.
• Live data. EventTransport invalidates the workspace query on CDC SSE events and daemon status (was previously dead-wired to an unused key).
• Resizable layout with sizes persisted to the Zustand store; shadcn Tabs (Terminal/Details), status Badge, Button, and free-text branch Input now used.
• Auto-update scaffold (electron-updater + publish config + release CI + signing checklist in frontend/docs/desktop-release.md).
• Playwright e2e restored against the current UI.

Verification

• tsc --noEmit ✅ · Vitest 12/12 ✅ (incl. mux framing) · Playwright discovery ✅.
• An adversarial multi-agent review ran on the implementation; all 6 confirmed findings fixed (resize/open ordering, terminal forceMount across tabs, rAF cancel, ws-url cleanup, autoUpdater rejection handling, Playwright Electron-launch suppression).

Needs interactive / live verification (wired + type-safe, not runtime-proven here)

• Terminal PTY requires a running daemon with the /mux terminal manager mounted; the WebSocket client + framing are tested but live PTY behavior is unproven in CI.
• Resizable layout + visual polish need a real Electron window.
• Auto-update is inert until an Apple signing cert + notarization + CI secrets are added (see the release doc).

🤖 Generated with Claude Code

[greptile-apps]

Greptile Summary

This PR rebuilds the Electron desktop frontend as a full React + Vite + TypeScript renderer, replacing a single-file main.ts with a layered architecture covering data fetching (TanStack Query + SSE event transport), terminal multiplexing (WebSocket mux + xterm), UI state (Zustand), routing (TanStack Router), and a custom CORS middleware on the backend daemon.

• Electron main process now supervises the daemon subprocess with dual port-discovery (log scan + running.json polling), serves the packaged renderer under a custom app://renderer scheme, and exposes IPC via a contextBridge preload.
• Terminal layer (terminal-mux.ts + useTerminalSession) implements the mux framing protocol end-to-end with frame queuing, exponential-backoff reconnect, and daemonReady-triggered reattachment; all tested with unit and Playwright suites.
• Live data pipeline (event-transport.ts + useDaemonStatus) connects SSE CDC events and daemon IPC status changes to debounced workspace-query invalidation, with correct port-rebinding on daemon restarts.

Confidence Score: 4/5

Safe to merge with one form-logic fix: the SpawnWorkerModal worker-name field gates submission via a regex validator but the value is never forwarded to the API.

The core Electron process, terminal mux, event transport, and API rebasing are all well-structured and correctly guarded. The one concrete defect is in SpawnWorkerModal where name validation silently blocks form submission for a field whose value is discarded before the API call. All previously-reviewed issues have been addressed.

frontend/src/renderer/components/SpawnWorkerModal.tsx — the worker name validation gate should be reconciled with whether the field is actually submitted.

Important Files Changed

Filename	Overview
frontend/src/main.ts	Rebuilt Electron main process: custom app:// protocol, daemon supervision with port discovery (log scan + run-file polling), IPC handlers, and auto-update scaffold. Process-group kill and stale-listener guard are correctly implemented.
frontend/src/renderer/lib/terminal-mux.ts	WebSocket mux client with frame queuing, connection-state dedup, and ping keepalive. Frame helpers are pure and unit-tested; dispose() cleans all maps and closes the socket.
frontend/src/renderer/hooks/useTerminalSession.ts	Terminal attachment lifecycle hook with exponential backoff, daemonReady-triggered reconnect, and stale-closure avoidance via connectRef. One redundant resize frame is sent immediately after open.
frontend/src/renderer/components/TerminalPane.tsx	XtermTerminal component with WebGL to CanvasAddon fallback, ResizeObserver-driven fit, and RAF-coordinated attach/detach lifecycle. Static preview renders correctly when Electron IPC is unavailable.
frontend/src/renderer/components/SpawnWorkerModal.tsx	New worker spawn modal. The name field is validated and gates submission via canSubmit, but is never forwarded to onCreateTask — users who enter a non-matching name are silently blocked.
backend/internal/httpd/cors.go	New CORS middleware enforcing explicit origin allowlist plus loopback passthrough. Preflight handler reflects arbitrary Access-Control-Request-Headers verbatim instead of a fixed allowlist.
frontend/src/renderer/lib/event-transport.ts	SSE + daemon IPC event transport with debounced workspace invalidation, CLOSED-state retry, and port-change rebinding. Lifecycle correctly cleans up on disconnect.
frontend/src/renderer/lib/api-client.ts	openapi-fetch client with runtime base-URL rebasing and per-request body buffering to work around Electron's missing duplex support. Early-exit path avoids unnecessary rebasing for matching URLs.
frontend/src/renderer/App.tsx	Root component wiring daemon status, workspace query, optimistic updates via useQueryClient(), keyboard shortcuts, and theme propagation. createProject and createTask correctly write to the query cache.

Sequence Diagram

sequenceDiagram
    participant M as Electron Main
    participant P as Preload (contextBridge)
    participant R as Renderer (React)
    participant T as EventTransport
    participant MX as TerminalMux (WS)
    participant D as Daemon (loopback)

    M->>M: spawn daemon (AO_DAEMON_COMMAND)
    M->>M: scan stdout/stderr for listen port
    M-->>R: "daemon:status { state:ready, port }"
    R->>P: daemon.getStatus() via IPC
    P-->>R: DaemonStatus
    R->>T: createEventTransport.connect()
    T->>D: EventSource /api/v1/events (SSE)
    D-->>T: CDC events (session_created, etc.)
    T->>R: invalidateQueries([workspaces])
    R->>D: GET /api/v1/projects + /api/v1/sessions
    D-->>R: workspace data

    R->>MX: createTerminalMux(ws://127.0.0.1:PORT/mux)
    MX->>D: "open{id, cols, rows}"
    D-->>MX: "opened{id}"
    MX-->>R: onOpened - state:attached
    D-->>MX: "data{id, base64}"
    MX-->>R: onData - xterm.write(bytes)

Loading

_{Reviews (7): Last reviewed commit: "Merge origin/main into feat/electron-ui-..." | Re-trigger Greptile}

[ashish921998]

Greptile triage (all four resolved):

• api-client.ts:8 — double /api/v1 (P1): Confirmed and fixed in 43183ac. baseUrl is now apiBaseUrl (host only), since the schema paths already carry /api/v1. Matches the suggested fix exactly.
• main.ts:838 — unquittable app on before-quit rejection (P1): No longer applicable. That async confirmStopSessions() / dialog.showMessageBox path lived in the old inline-HTML main.ts (e2e86bd), which was replaced by the React renderer. The current before-quit (main.ts:171) is a synchronous daemonProcess.kill() with no preventDefault.
• main.ts:823 — dead app:confirm-stop-sessions IPC (P2): No longer applicable. That handler was removed in the React pivot, and a preload.ts bridge now exists (the "no preload configured" premise is outdated).
• main.ts:726 — String(Date.now()).slice(-4) ID collisions (P2): No longer applicable. showWorker/renderWorkspaceList were removed; session ids now come from the daemon API, with a base36 timestamp only as an offline fallback.

main.ts is now 181 lines (was ~900); the three stale comments reviewed the pre-pivot file.

[AgentWrapper]

✅ Matches the locked design (docs/designs/desktop-app-design.html §4.2): TanStack Router is exactly the chosen router, paired with the TanStack Query you're already using. Flagging explicitly because this is a real @tanstack/react-router setup (hash history + typed Register), not a hand-rolled router — so there's no routing divergence to reconcile here. The RootLayout→App param-wrapper pattern is clean.

[AgentWrapper]

⚠️ Steering, not a nitpick — status spectrum. This 4-value SessionStatus (running|needs_input|stopped|failed) is a third status vocabulary: it's neither the daemon's 12-value derived set (docs/architecture.md:40-49 — terminated/merged/needs_input/ci_failed/draft/changes_requested/mergeable/approved/review_pending/pr_open/working/idle) nor the legacy StatusTone spectrum. The agreed plan (design doc §7 status-spectrum audit) keeps the Go set authoritative and maps Go→StatusTone via a client-side shim. useWorkspaceQuery.ts:sessionStatus() already hand-collapses Go statuses, so every PR/review state (ci_failed, changes_requested, approved, …) is silently lost here. Recommend aligning to the Go set + a shim rather than a new 4-value enum.

[AgentWrapper]

✅ Strong, and a borrow-back for our plan. I verified this against the backend: /api/v1/events is a real SSE endpoint (backend/internal/httpd/events.go:74-80 — text/event-stream, emits id:/event:/data: and honors Last-Event-ID), and all 8 CDC_EVENT_TYPES here match backend/internal/cdc/event.go:23-30 exactly. The named-event + auto-reconnect approach is correctly matched to the contract.

This is cleaner than the 'CDC over the /mux sessions channel' route our design doc assumed (§7 mux audit) — separate transports, free EventSource resume. We should adopt this SSE pattern in the doc and retire the sessions-channel-for-CDC idea.

One caveat: events.go:40-43 returns 501 when the controller deps aren't wired — worth confirming Source/Live are mounted on this PR's base main (they're stubbed in the worktree I reviewed against).

[AgentWrapper]

⚠️ Three coupled gaps vs the connection model (design doc §4.5/§5), all latent today because the daemon is loopback-no-auth:

1. Port discovery — apiBaseUrl hardcodes :3001, but the daemon binds whatever port it's given (and may use 0→OS-assigned). The supervisor should read the actual port from running.json (backend/internal/runfile/runfile.go:20-26) and hand it to the renderer rather than assume the default.
2. Token — the remote model (§5) needs a bearer token; on the WS it must ride the Sec-WebSocket-Protocol subprotocol since browsers can't set headers on a WS handshake.
3. CORS — packaged renderer origin is file:// but it fetches http://127.0.0.1:PORT directly, and the daemon has no CORS (confirmed: no CORS middleware in backend/internal/httpd; README.md:94), so those requests will be blocked.

Your own frontend-shell-decision.html landmines flag (1) and (3) too. None block this PR — they're the next real work, and mostly daemon-side.

[AgentWrapper]

📄 Doc reconciliation — for the team, not a change to this file. This decision record lands on Electron, same as our design doc (docs/designs/desktop-app-design.html) — good, we agree on the conclusion. But the bases differ in ways that matter:

• It drops Linux ('macOS + Windows'); our doc commits to Linux binaries as a hard requirement → 'is Linux a target?' is now an open conflict.
• Its deciding axis is language count, and it never mentions the agent-controllable in-app browser (multi-tab, CDP-driven) that our doc treats as the reason Electron wins and as a locked Phase-3 feature. If that requirement still holds, Electron is locked for a stronger reason and Linux likely has to stay.
• Two decision docs at two paths (this one at repo root, ours under docs/designs/) = no single source of truth.

The '~0% renderer built' landmine in this doc is also now superseded by this very PR. Suggest the orchestrator merges the two into one record.

[AgentWrapper]

Architectural review — alignment with the locked frontend design doc

Reviewing for architectural alignment with docs/designs/desktop-app-design.html, not generic correctness (Greptile's two correctness bugs stand — see the bottom). Backend claims verified against the daemon source; inline notes are on the specific lines. Net: comment-only — the stack is right and cleanly built, but the PR answers two questions the team had already answered differently, and those need a ruling rather than a code change forced on the author.

✅ Strong alignment (validates the design doc)

Electron · React 19 + Vite + TS · TanStack Query and Router · Tailwind · xterm.js + WebGL (probe → canvas fallback) · electron-updater · Zustand — all exactly the locked stack, implemented cleanly. Electron security posture is right (contextIsolation/sandbox/nodeIntegration:false, contextBridge with unsubscribe, navigation hardening). The /mux client (terminal-mux.ts) matches protocol.go and is framing-tested.

Notably good: the SSE event wiring is precisely matched to the real backend — /api/v1/events is a genuine SSE stream (events.go:74-80) and the 8 hardcoded CDC event names match cdc/event.go:23-30 exactly. Real backend research, not guesswork.

⤴️ Borrow back into our plan

1. Promote OpenAPI codegen from phase-2 to phase-0 — openapi-typescript + openapi-fetch off openapi.yaml is strictly better than hand-porting types for bootstrap.
2. Adopt the SSE EventTransport split (terminal=/mux, CDC=SSE, refetch-on-event) and retire the doc's "CDC over the mux sessions channel" idea — theirs is cleaner.
3. react-resizable-panels, the WebGL-probe terminal renderer, and the electron-updater release CI + signing checklist are all worth keeping.

⚠️ Divergences (calls in the report)

• D1 — this is a stack scaffold, not the 1:1 legacy port (team decision). New mock-data components, a new light-default design system (Sidebar even hardcodes light hex, ignoring the dark theme), and a new 4-value status enum — vs the locked dark-only Mission Control + 12-status-via-shim. Legitimate as a scaffold; doesn't fulfil the 1:1-port mandate.
• D2 — single npm app, not the packages/core+packages/runtime pnpm workspace (defer). Seam is clean, mobile is OPEN, so extraction later is cheap — but track it.
• D3 — daemon supervisor is a stub (we align): spawns AO_DAEMON_COMMAND, no running.json discovery, no /readyz poll, no token, no /shutdown. Your own decision doc specifies all of these.
• D4 — no CORS/token for direct renderer→daemon (daemon-side, latent): file://→127.0.0.1 is cross-origin and the daemon has no CORS/token. Next real work.
• D5 — second decision doc (frontend-shell-decision.html) lands on Electron too 👍 but drops Linux (our doc requires it) and never mentions the agent-controllable in-app browser that our doc treats as the deciding factor + a Phase-3 feature. Two docs, two paths → reconcile to one.

Mux parity

Our audit found the legacy mux can't port 1:1; this PR sidesteps it well — sessions channel unused, CDC via SSE. Two residual gaps: no terminal reconnect (the backend supports reconnect-resubscribe; a blip kills the pane) and one-WS-per-pane forgoes multiplexing (fine for the single-pane tab UI now).

Deferred to Greptile (correctness, not this lens)

useWorkspaceQuery maps path to the wrong field (every project shows its UUID); createTask swallows the API error and closes the composer silently; global.d.ts types window.ao as non-optional. Worth fixing before merge.

Full write-up with file:line and per-divergence resolutions: docs/reviews/pr-156-review.md (in the ao-15 worktree). The two team decisions (D1, D5) are headed to the orchestrator.

[github-actions]

React Doctor found no issues. 🎉

_{Reviewed by React Doctor for commit c01cf7a.}

[yyovil]

Review note: please split formatter setup from feature changes

The PR bundles three distinct concerns and it's making review harder than it needs to be:

1. Prettier tooling setup — .prettierrc, .prettierignore, .lintstagedrc, .husky/pre-commit. These are a chore: concern and unrelated to the renderer.
2. Mass reformat of existing files — all frontend/src/landing/ components (~20 files), globals.css, etc. These are 100% Prettier-driven reflowing (JSX attribute wrapping, CSS transition expansion) with zero logic changes. They're drowning out the real diff.
3. The actual feature — the React renderer, CORS middleware, daemon discovery, OpenAPI updates, terminal mux. This is the meat, and it's buried.

Suggested split:

• chore: add prettier config and format existing files — items 1 + 2, reviewable in seconds
• feat(frontend): rebuild Electron desktop UI as a React + Vite renderer — item 3 only, focused and reviewable

Either a rebase to separate the formatting commit, or extracting items 1+2 into their own PR first works. The formatting-only files can be reviewed with git diff -w in the meantime if you need to unblock.

[yyovil]

@ashish921998 plz keep the PRs tightly scoped with the PR title.

[greptile-apps]

Worker name blocks submission but is silently discarded

canSubmit gates on nameValid, so a user who types something like "My Worker" (spaces or uppercase letters violate NAME_RULE = /^[a-z0-9-]+$/) cannot submit the form. But the name value is never passed to onCreateTask — it only drives the worktree-path preview in the "Workspace" tab and is reset after a successful submit. The default "" is valid, so a user who doesn't touch the field is unaffected, but anyone who types an entry that doesn't satisfy the regex is silently blocked from spawning a worker for no functional reason.

Either remove nameValid from canSubmit (and keep the visual hint as a non-blocking style signal), or thread name through onCreateTask and the createTask API call so the validation actually enforces a real constraint.