Evenfire is an intelligence layer platform for running LLM agents that take real actions, on your infrastructure
TypeScript
feat(desktop-app): add first-run onboarding questionnaire
Andy Pavia53d47ba629bb
diff --git a/desktop-app/src/__tests__/appService.onboarding.test.ts b/desktop-app/src/__tests__/appService.onboarding.test.tsnew file mode 100644index 000000000..85e9c72c8--- /dev/null+++ b/desktop-app/src/__tests__/appService.onboarding.test.ts@@ -0,0 +1,122 @@+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'++const openExternal = vi.fn(async () => undefined)++// config.ts touches the Electron `app` at module load; provide a minimal mock+// with a NON-packaged, ready app so the env-var runtime-config path is active.+vi.mock('electron', () => ({+ app: {+ getPath: vi.fn(() => '/tmp/evenfire-test-userdata'),+ isPackaged: false,+ isReady: vi.fn(() => true),+ setName: vi.fn(),+ setPath: vi.fn(),+ getName: vi.fn(() => 'Evenfire'),+ },+ shell: { openExternal },+}))++// The chat store binds to the real filesystem; stub it so importing appService+// never touches Electron userData.+vi.mock('../chatStoreBinding.js', () => ({+ bindChatStoreForUser: vi.fn(),+ unbindChatStore: vi.fn(),+}))++const LOCALHOST_EXTERNAL = 'http://127.0.0.1:8091'+const REMOTE_EXTERNAL = 'https://api.example.com'+const REMOTE_RPC = 'https://rpc.example.com'++type HealthByUrl = (baseUrl: string) => Promise<{ status: string }>++async function makeService(healthAt: HealthByUrl) {+ vi.resetModules()+ const { AppService } = await import('../appService.js')+ const service = new AppService() as unknown as {+ authClient: { healthAt: ReturnType<typeof vi.fn> }+ probeLocalhostReachable: () => Promise<boolean>+ openDeploymentDocs: () => Promise<{ opened: true }>+ }+ service.authClient = { healthAt: vi.fn(healthAt) } as never+ return service+}++function healthReachableFor(...reachableHosts: string[]): HealthByUrl {+ return async (baseUrl: string) => {+ if (reachableHosts.some(host => baseUrl.includes(host))) return { status: 'ok' }+ throw new Error('ECONNREFUSED')+ }+}++describe('onboarding main-process surface', () => {+ const saved = {+ external: process.env.EXTERNAL_REST_API_BASE_URL,+ rpc: process.env.RPC_PROXY_BASE_URL,+ docs: process.env.DEPLOYMENT_DOCS_URL,+ }++ beforeEach(() => {+ openExternal.mockClear()+ delete process.env.DEPLOYMENT_DOCS_URL+ })++ afterEach(() => {+ for (const [key, value] of [+ ['EXTERNAL_REST_API_BASE_URL', saved.external],+ ['RPC_PROXY_BASE_URL', saved.rpc],+ ['DEPLOYMENT_DOCS_URL', saved.docs],+ ] as const) {+ if (value === undefined) delete process.env[key]+ else process.env[key] = value+ }+ vi.resetModules()+ })++ describe('probeLocalhostReachable', () => {+ it('reports a reachable local cluster', async () => {+ process.env.EXTERNAL_REST_API_BASE_URL = REMOTE_EXTERNAL+ process.env.RPC_PROXY_BASE_URL = REMOTE_RPC++ const service = await makeService(healthReachableFor('127.0.0.1'))++ expect(await service.probeLocalhostReachable()).toBe(true)+ })++ it('reports false when nothing answers, rather than throwing', async () => {+ process.env.EXTERNAL_REST_API_BASE_URL = REMOTE_EXTERNAL+ process.env.RPC_PROXY_BASE_URL = REMOTE_RPC++ const service = await makeService(healthReachableFor())++ expect(await service.probeLocalhostReachable()).toBe(false)+ })++ it('only ever probes the localhost option, whatever the active environment', async () => {+ process.env.EXTERNAL_REST_API_BASE_URL = REMOTE_EXTERNAL+ process.env.RPC_PROXY_BASE_URL = REMOTE_RPC++ const service = await makeService(healthReachableFor('127.0.0.1'))+ await service.probeLocalhostReachable()++ // The renderer cannot name a URL for the main process to fetch, so the+ // remote environment must never be contacted by this call (spec §6.8).+ expect(service.authClient.healthAt).toHaveBeenCalledTimes(1)+ expect(service.authClient.healthAt.mock.calls[0]?.[0]).toBe(LOCALHOST_EXTERNAL)+ })+ })++ describe('openDeploymentDocs', () => {+ it('opens the build-time documentation URL, taking no argument', async () => {+ const service = await makeService(healthReachableFor())++ expect(await service.openDeploymentDocs()).toEqual({ opened: true })+ expect(openExternal).toHaveBeenCalledTimes(1)++ const opened = String(openExternal.mock.calls[0]?.[0] || '')+ expect(opened).toMatch(/^https:\/\//)+ // Self-hosting covers any cluster the user controls, so the link must not+ // land on the local-cluster quickstart (spec §5.4).+ expect(opened).not.toMatch(/minikube|quickstart/i)+ })+ })+})diff --git a/desktop-app/src/appService.ts b/desktop-app/src/appService.tsindex b221b8d33..72b9e17c8 100644--- a/desktop-app/src/appService.ts+++ b/desktop-app/src/appService.ts@@ -1760,6 +1760,33 @@ export class AppService {}}+ /**+ * Onboarding's path-D hint (spec §5.6): is a local Evenfire answering?+ *+ * Takes **no argument** on purpose. The renderer cannot name a URL for the+ * main process to fetch — it can only ask about the built-in Localhost+ * option, whose address is a constant in config. Best-effort and+ * time-bounded, like every other use of `probeBackendHealthy`; a negative+ * result means "show no hint", never an error.+ */+ async probeLocalhostReachable(): Promise<boolean> {+ hydrateDesktopRuntimeConfig()+ const state = getDesktopRuntimeConfigState()+ const localhostOption = state.options.find(option => option.source === 'localhost')+ if (!localhostOption?.externalRestApiBaseUrl) return false+ return this.probeBackendHealthy(localhostOption.externalRestApiBaseUrl)+ }++ /**+ * Open the deployment documentation for onboarding's self-hosted path+ * (spec §5.4). The URL is a build-time constant, not a renderer argument.+ */+ async openDeploymentDocs(): Promise<{ opened: true }> {+ const { shell } = await import('electron')+ await shell.openExternal(config.deploymentDocsUrl)+ return { opened: true }+ }+/** True iff `<baseUrl>/health` returns `{ status: 'ok' }` within the probe bound. */private async probeBackendHealthy(baseUrl: string): Promise<boolean> {if (!baseUrl?.trim()) return falsediff --git a/desktop-app/src/config.ts b/desktop-app/src/config.tsindex c5fd3b37c..37a40b95e 100644--- a/desktop-app/src/config.ts+++ b/desktop-app/src/config.ts@@ -15,6 +15,7 @@ type DesktopConfig = Omit<DesktopRuntimeConfig, 'appName' | 'rpcProxyBaseUrl'> &memberRegistrationServiceBaseUrl: stringdesktopProfileUiBaseUrl: stringdesktopProfileUiBaseUrlExplicit: boolean+ deploymentDocsUrl: stringrequestTimeoutMs: numbergfsUploadTimeoutMs: numberappName: string@@ -47,6 +48,13 @@ const DEFAULT_APP_NAME = 'Evenfire'const LOCALHOST_OPTION_ID = '__localhost__'const LOCALHOST_EXTERNAL_REST_API_BASE_URL = 'http://127.0.0.1:8091'const LOCALHOST_RPC_PROXY_BASE_URL = 'http://127.0.0.1:8094'+// Where onboarding's self-hosted path sends the user (spec §5.4). Self-hosting+// means any cluster the user controls — remote or local — so this must land on+// documentation that covers both shapes, never on the minikube quickstart+// alone. A build-time constant, overridable only where the dev env config gate+// already allows overrides, so a packaged build cannot be pointed elsewhere.+const DEFAULT_DEPLOYMENT_DOCS_URL =+ 'https://github.com/evenfire-ai/evenfire#deploying-to-a-remote-cluster'const RUNTIME_CONFIG_DIR_NAME = 'runtime-configs'const RUNTIME_CONFIG_INDEX_FILE = 'index.json'const PACKAGED_ENV_FILE = '.env.prod'@@ -556,6 +564,9 @@ export const config: DesktopConfig = {),desktopProfileUiBaseUrl: deriveProfileUiBaseUrl(initialRuntimeConfig.externalRestApiBaseUrl),desktopProfileUiBaseUrlExplicit: hasExplicitProfileUiBaseUrl(),+ deploymentDocsUrl: canUseEnvRuntimeConfig+ ? requiredOrDefault('DEPLOYMENT_DOCS_URL', DEFAULT_DEPLOYMENT_DOCS_URL)+ : DEFAULT_DEPLOYMENT_DOCS_URL,requestTimeoutMs: Number(requiredOrDefault('REQUEST_TIMEOUT_MS', '60000')),// Generous deadline for legacy JSON GFS uploads: a 16 MiB file is a ~22.4 MiB// base64 body, ~60s alone on a slow uplink. v2 streams binary indexed parts anddiff --git a/desktop-app/src/ipc.ts b/desktop-app/src/ipc.tsindex 0dcadf44c..c969bacbb 100644--- a/desktop-app/src/ipc.ts+++ b/desktop-app/src/ipc.ts@@ -251,6 +251,14 @@ export function registerIpcHandlers(service: AppService): void {assertTrustedSender(event)return service.diagnoseLoginBackend()})+ ipcMain.handle('auth:probeLocalhostReachable', async event => {+ assertTrustedSender(event)+ return service.probeLocalhostReachable()+ })+ ipcMain.handle('auth:openDeploymentDocs', async event => {+ assertTrustedSender(event)+ return service.openDeploymentDocs()+ })ipcMain.handle('auth:startDesktopSetup', async (event, payload: { email: string }) => {assertTrustedSender(event)return service.startDesktopSetup(sanitizeString(payload?.email).toLowerCase())diff --git a/desktop-app/src/preload.ts b/desktop-app/src/preload.tsindex c96eef30d..a4d62ffe4 100644--- a/desktop-app/src/preload.ts+++ b/desktop-app/src/preload.ts@@ -86,6 +86,8 @@ const clerum = Object.freeze({passwordLogin: (email: string, password: string) =>ipcRenderer.invoke('auth:passwordLogin', { email, password }),diagnoseLoginBackend: () => ipcRenderer.invoke('auth:diagnoseLoginBackend'),+ probeLocalhostReachable: () => ipcRenderer.invoke('auth:probeLocalhostReachable'),+ openDeploymentDocs: () => ipcRenderer.invoke('auth:openDeploymentDocs'),startDesktopSetup: (email: string) => ipcRenderer.invoke('auth:startDesktopSetup', { email }),openForgotPassword: (email?: string) =>ipcRenderer.invoke('auth:openForgotPassword', { email }),diff --git a/desktop-app/src/renderer.d.ts b/desktop-app/src/renderer.d.tsindex 6d17c18bc..c28f33feb 100644--- a/desktop-app/src/renderer.d.ts+++ b/desktop-app/src/renderer.d.ts@@ -75,6 +75,8 @@ declare global {googleLogin: (idToken: string) => Promise<SessionState>passwordLogin: (email: string, password: string) => Promise<PasswordLoginResult>diagnoseLoginBackend: () => Promise<LoginBackendHint | null>+ probeLocalhostReachable: () => Promise<boolean>+ openDeploymentDocs: () => Promise<{ opened: true }>startDesktopSetup: (email: string) => Promise<{ profileUiUrl: string; appName: string }>openForgotPassword: (email?: string) => Promise<{ profileUiUrl: string }>openProfileSettings: (diff --git a/desktop-app/ui/src/App.tsx b/desktop-app/ui/src/App.tsxindex df521d4b0..8d9abca07 100644--- a/desktop-app/ui/src/App.tsx+++ b/desktop-app/ui/src/App.tsx@@ -69,6 +69,7 @@ import { ContextDetailsPage } from '@pages/ContextDetailsPage'import { ContextsPage } from '@pages/ContextsPage'import { FilesPage } from '@pages/FilesPage'import { McpServersPage } from '@pages/McpServersPage'+import { OnboardingPage } from '@pages/OnboardingPage'import { SandboxUiPage } from '@pages/SandboxUiPage'import type {SandboxUiConversationOrigin,@@ -1956,7 +1957,13 @@ export function App() {</NavigationContext.Provider>) : (<>- {vm.hasDependencyOutage ? <UnavailablePage /> : <AuthPage />}+ {vm.unauthenticatedView === 'outage' ? (+ <UnavailablePage />+ ) : vm.unauthenticatedView === 'onboarding' ? (+ <OnboardingPage onboarding={vm.onboarding} />+ ) : (+ <AuthPage />+ )}{environmentSetupConfirmationDialog}{environmentSetupSuccessDialog}<ToastStack items={vm.toasts} />diff --git a/desktop-app/ui/src/components/RuntimeConfigDock/index.tsx b/desktop-app/ui/src/components/RuntimeConfigDock/index.tsxnew file mode 100644index 000000000..8b9da4996--- /dev/null+++ b/desktop-app/ui/src/components/RuntimeConfigDock/index.tsx@@ -0,0 +1,237 @@+import { useEffect, useRef, useState } from 'react'+import { useAuthContext } from '@contexts/AuthContext'+import { IconButton, MenuItem } from '@components/Common'+import { ConfirmDialog } from '@components/ConfirmDialog'+import {+ LOCALHOST_RUNTIME_CONFIG_OPTION_ID,+ createLocalhostRuntimeConfigOption,+} from '@constants/runtimeConfig'+import type { DesktopRuntimeConfigOption } from '../../../../src/types'++interface RuntimeConfigDockProps {+ /**+ * Where "Add environment" goes. AuthPage opens its inline environment form;+ * onboarding moves to its manual step. The dock itself stays identical, so+ * the Localhost escape hatch (spec §3, path E) is reachable from both — a+ * cold install renders onboarding, not AuthPage, and would otherwise have no+ * way to reach it.+ */+ onAddEnvironment: () => void+}++export function RuntimeConfigDock({ onAddEnvironment }: RuntimeConfigDockProps) {+ const {+ busy,+ authTransitioning,+ runtimeConfigState,+ handleDeleteRuntimeConfig,+ handleSelectRuntimeConfig,+ handleClearRuntimeConfigSelection,+ } = useAuthContext()++ const [runtimeMenuOpen, setRuntimeMenuOpen] = useState(false)+ const [pendingDeleteOption, setPendingDeleteOption] = useState<DesktopRuntimeConfigOption | null>(+ null+ )+ const runtimeDockRef = useRef<HTMLDivElement | null>(null)++ const runtimeConfigOptions = runtimeConfigState?.options || []+ const activeRuntimeConfigId = runtimeConfigState?.activeOptionId ?? null+ const selectedRuntimeConfig = runtimeConfigOptions.find(+ option => option.id === activeRuntimeConfigId+ )+ const savedRuntimeConfigOptions = runtimeConfigOptions.filter(option => option.source === 'file')+ const localhostRuntimeConfigOption = runtimeConfigOptions.find(+ option => option.source === 'localhost'+ )+ const displayedLocalhostRuntimeConfigOption =+ localhostRuntimeConfigOption || createLocalhostRuntimeConfigOption()++ const handleRuntimeOptionSelect = (optionId: string) => {+ setRuntimeMenuOpen(false)+ if (+ optionId === activeRuntimeConfigId &&+ (selectedRuntimeConfig?.source === 'localhost' ||+ optionId === LOCALHOST_RUNTIME_CONFIG_OPTION_ID)+ ) {+ handleClearRuntimeConfigSelection()+ return+ }+ handleSelectRuntimeConfig(optionId)+ }++ const confirmDeleteRuntimeOption = () => {+ if (!pendingDeleteOption) return+ handleDeleteRuntimeConfig(pendingDeleteOption.id)+ setPendingDeleteOption(null)+ }++ useEffect(() => {+ if (!runtimeMenuOpen) {+ return+ }++ const handleDocumentPointerDown = (event: PointerEvent) => {+ if (runtimeDockRef.current?.contains(event.target as Node)) {+ return+ }++ setRuntimeMenuOpen(false)+ }++ const handleEscape = (event: KeyboardEvent) => {+ if (event.key === 'Escape') {+ setRuntimeMenuOpen(false)+ }+ }++ document.addEventListener('pointerdown', handleDocumentPointerDown)+ document.addEventListener('keydown', handleEscape)++ return () => {+ document.removeEventListener('pointerdown', handleDocumentPointerDown)+ document.removeEventListener('keydown', handleEscape)+ }+ }, [runtimeMenuOpen])++ if (!runtimeConfigState) return null++ return (+ <>+ <aside className="auth-runtime-dock" ref={runtimeDockRef}>+ <IconButton+ className="auth-runtime-dock__toggle"+ aria-label="Open environment selector"+ aria-expanded={runtimeMenuOpen}+ aria-controls="auth-runtime-dock-panel"+ label="Open environment selector"+ onClick={() => setRuntimeMenuOpen(open => !open)}+ variant="soft"+ >+ <svg viewBox="0 0 24 24" aria-hidden="true" focusable="false">+ <path d="M19.43 12.98a7.9 7.9 0 0 0 .05-.98 7.9 7.9 0 0 0-.05-.98l2.11-1.65a.48.48 0 0 0 .12-.61l-2-3.46a.49.49 0 0 0-.58-.22l-2.49 1a7.2 7.2 0 0 0-1.7-.98l-.38-2.65A.49.49 0 0 0 14 2h-4a.49.49 0 0 0-.49.41l-.38 2.65a7.2 7.2 0 0 0-1.7.98l-2.49-1a.49.49 0 0 0-.58.22l-2 3.46a.48.48 0 0 0 .12.61l2.11 1.65a7.9 7.9 0 0 0-.05.98 7.9 7.9 0 0 0 .05.98l-2.11 1.65a.48.48 0 0 0-.12.61l2 3.46a.49.49 0 0 0 .58.22l2.49-1a7.2 7.2 0 0 0 1.7.98l.38 2.65A.49.49 0 0 0 10 22h4a.49.49 0 0 0 .49-.41l.38-2.65a7.2 7.2 0 0 0 1.7-.98l2.49 1a.49.49 0 0 0 .58-.22l2-3.46a.48.48 0 0 0-.12-.61Zm-7.43 2.52A3.5 3.5 0 1 1 15.5 12 3.5 3.5 0 0 1 12 15.5Z" />+ </svg>+ </IconButton>+ {runtimeMenuOpen ? (+ <div className="auth-runtime-dock__panel glass-card" id="auth-runtime-dock-panel">+ <div className="auth-runtime-menu__header">+ <span className="auth-runtime-menu__label">Environment</span>+ <IconButton+ aria-label="Add environment"+ disabled={busy || authTransitioning}+ label="Add environment"+ onClick={() => {+ setRuntimeMenuOpen(false)+ onAddEnvironment()+ }}+ size="sm"+ variant="ghost"+ >+ <svg viewBox="0 0 24 24" aria-hidden="true" focusable="false">+ <path d="M12 5v14" />+ <path d="M5 12h14" />+ </svg>+ </IconButton>+ </div>+ <div className="auth-runtime-menu">+ {savedRuntimeConfigOptions.length > 0 ? (+ <section className="auth-runtime-menu__section">+ {savedRuntimeConfigOptions.map(option => {+ const selected = option.id === activeRuntimeConfigId+ return (+ <div+ key={option.id}+ className={`auth-runtime-menu__row${selected ? ' selected' : ''}`}+ >+ <MenuItem+ className={`auth-runtime-menu__select${selected ? ' selected' : ''}`}+ active={selected}+ disabled={busy || authTransitioning}+ leadingIcon={+ <span className="auth-runtime-menu__check" aria-hidden="true">+ {selected ? (+ <svg viewBox="0 0 24 24" focusable="false">+ <path d="M20 6 9 17l-5-5" />+ </svg>+ ) : null}+ </span>+ }+ onClick={() => handleRuntimeOptionSelect(option.id)}+ >+ {option.label}+ </MenuItem>+ <IconButton+ className="auth-runtime-menu__delete"+ aria-label={`Delete ${option.appName} environment`}+ color="danger"+ disabled={busy || authTransitioning}+ label={`Delete ${option.appName}`}+ onClick={() => setPendingDeleteOption(option)}+ size="sm"+ title={`Delete ${option.appName}`}+ variant="ghost"+ >+ <svg viewBox="0 0 24 24" aria-hidden="true" focusable="false">+ <path d="M3 6h18" />+ <path d="M8 6V4h8v2" />+ <path d="M6 6l1 15h10l1-15" />+ <path d="M10 10v7" />+ <path d="M14 10v7" />+ </svg>+ </IconButton>+ </div>+ )+ })}+ </section>+ ) : null}+ {displayedLocalhostRuntimeConfigOption ? (+ <section className="auth-runtime-menu__section">+ {(() => {+ const option = displayedLocalhostRuntimeConfigOption+ const selected = option.id === activeRuntimeConfigId+ return (+ <MenuItem+ className={`auth-runtime-menu__select auth-runtime-menu__select--standalone${+ selected ? ' selected' : ''+ }`}+ active={selected}+ disabled={busy || authTransitioning}+ leadingIcon={+ <span className="auth-runtime-menu__check" aria-hidden="true">+ {selected ? (+ <svg viewBox="0 0 24 24" focusable="false">+ <path d="M20 6 9 17l-5-5" />+ </svg>+ ) : null}+ </span>+ }+ onClick={() => handleRuntimeOptionSelect(option.id)}+ >+ Localhost+ </MenuItem>+ )+ })()}+ </section>+ ) : null}+ </div>+ </div>+ ) : null}+ </aside>+ {pendingDeleteOption ? (+ <ConfirmDialog+ title="Delete environment?"+ body={+ <p>+ Delete <strong>{pendingDeleteOption.appName}</strong>? This only removes the local+ desktop environment configuration.+ </p>+ }+ confirmLabel="Delete"+ tone="danger"+ onCancel={() => setPendingDeleteOption(null)}+ onConfirm={confirmDeleteRuntimeOption}+ />+ ) : null}+ </>+ )+}diff --git a/desktop-app/ui/src/hooks/domain/__tests__/useOnboardingController.test.tsx b/desktop-app/ui/src/hooks/domain/__tests__/useOnboardingController.test.tsxnew file mode 100644index 000000000..f9ded9b87--- /dev/null+++ b/desktop-app/ui/src/hooks/domain/__tests__/useOnboardingController.test.tsx@@ -0,0 +1,58 @@+// @vitest-environment jsdom+import { describe, expect, it } from 'vitest'+import { act, renderHook } from '@testing-library/react'+import { useOnboardingController } from '../useOnboardingController'++describe('useOnboardingController', () => {+ it('starts on Q1 with no history', () => {+ const { result } = renderHook(() => useOnboardingController())++ expect(result.current.step).toBe('origin')+ expect(result.current.canGoBack).toBe(false)+ })++ it('ignores back at the root instead of unwinding past Q1', () => {+ const { result } = renderHook(() => useOnboardingController())++ act(() => result.current.back())++ expect(result.current.step).toBe('origin')+ expect(result.current.canGoBack).toBe(false)+ })++ it('records one history entry per transition, not two', () => {+ // Guards the StrictMode hazard that made step and history one state value:+ // a duplicated history entry would need two backs to leave a one-step path.+ const { result } = renderHook(() => useOnboardingController())++ act(() => result.current.answerOrigin('haveAddress'))+ expect(result.current.step).toBe('manual')++ act(() => result.current.back())+ expect(result.current.step).toBe('origin')+ expect(result.current.canGoBack).toBe(false)+ })++ it('skips Q2 while the hosted path is unavailable', () => {+ const { result } = renderHook(() => useOnboardingController())++ expect(result.current.hostedAvailable).toBe(false)++ act(() => result.current.answerOrigin('gettingStarted'))++ expect(result.current.step).toBe('selfHosted')+ })++ it('reset returns to Q1 and clears the history', () => {+ const { result } = renderHook(() => useOnboardingController())++ act(() => result.current.answerOrigin('gettingStarted'))+ act(() => result.current.goToManual())+ expect(result.current.canGoBack).toBe(true)++ act(() => result.current.reset())++ expect(result.current.step).toBe('origin')+ expect(result.current.canGoBack).toBe(false)+ })+})diff --git a/desktop-app/ui/src/hooks/domain/useOnboardingController.ts b/desktop-app/ui/src/hooks/domain/useOnboardingController.tsnew file mode 100644index 000000000..b381ca906--- /dev/null+++ b/desktop-app/ui/src/hooks/domain/useOnboardingController.ts@@ -0,0 +1,88 @@+import { useCallback, useMemo, useState } from 'react'+import type {+ OnboardingOriginAnswer,+ OnboardingRunStyleAnswer,+ OnboardingStep,+ OnboardingViewModel,+} from '@pages/OnboardingPage/types'++/**+ * Whether the hosted trial path (spec §5.3) is reachable in this build.+ *+ * False until the hosted signup project exists: Q2 would otherwise offer a+ * choice with one real answer. While false, Q1's "just getting started"+ * routes straight to the self-hosted step. Flipping this to true is the only+ * change this file needs when path A ships (spec §7.1).+ */+const HOSTED_SIGNUP_AVAILABLE = false++interface OnboardingState {+ step: OnboardingStep+ history: OnboardingStep[]+}++const INITIAL_STATE: OnboardingState = { step: 'origin', history: [] }++/**+ * Onboarding wizard state (spec §5.1, §5.2).+ *+ * Memory-only by design. A cold install closed mid-questionnaire comes back to+ * Q1: nothing was accomplished worth restoring, and persisting a half-answered+ * wizard can strand the user on a step whose path no longer applies.+ *+ * Step and history are one state value so a step transition is a single+ * update. Nesting `setHistory` inside a `setStep` updater would push a+ * duplicate history entry under StrictMode's double invocation.+ */+export function useOnboardingController(): OnboardingViewModel {+ const [state, setState] = useState<OnboardingState>(INITIAL_STATE)++ const goTo = useCallback((next: OnboardingStep) => {+ setState(current => ({ step: next, history: [...current.history, current.step] }))+ }, [])++ const answerOrigin = useCallback(+ (answer: OnboardingOriginAnswer) => {+ if (answer === 'invited') return goTo('invited')+ if (answer === 'haveAddress') return goTo('manual')+ return goTo(HOSTED_SIGNUP_AVAILABLE ? 'runStyle' : 'selfHosted')+ },+ [goTo]+ )++ const answerRunStyle = useCallback(+ (answer: OnboardingRunStyleAnswer) => {+ // 'hosted' gets its own waiting step in the PR that ships path A+ // (spec §5.3). Until then Q2 is never rendered, so only 'selfHosted'+ // can arrive here.+ if (answer === 'selfHosted') goTo('selfHosted')+ },+ [goTo]+ )++ const goToManual = useCallback(() => goTo('manual'), [goTo])++ const back = useCallback(() => {+ setState(current => {+ const previous = current.history[current.history.length - 1]+ if (!previous) return current+ return { step: previous, history: current.history.slice(0, -1) }+ })+ }, [])++ const reset = useCallback(() => setState(INITIAL_STATE), [])++ return useMemo(+ () => ({+ step: state.step,+ canGoBack: state.history.length > 0,+ hostedAvailable: HOSTED_SIGNUP_AVAILABLE,+ answerOrigin,+ answerRunStyle,+ goToManual,+ back,+ reset,+ }),+ [state.step, state.history.length, answerOrigin, answerRunStyle, goToManual, back, reset]+ )+}diff --git a/desktop-app/ui/src/hooks/useAppController.ts b/desktop-app/ui/src/hooks/useAppController.tsindex ffd601908..7a9172827 100644--- a/desktop-app/ui/src/hooks/useAppController.ts+++ b/desktop-app/ui/src/hooks/useAppController.ts@@ -11,6 +11,7 @@ import type {import { DESKTOP_ROUTES } from '../constants/navigation'import { pickLatestAgent } from '../lib/agents'import { toPrettyJson } from '../lib/format'+import { selectUnauthenticatedView } from '../lib/unauthenticatedView'import { summarizeWorkflowResource } from '../lib/workflows'import type {AgentApprovalNotificationTarget,@@ -39,6 +40,7 @@ import { useMcpServersDataController } from './domain/useMcpServersDataControlleimport { useNavigationController } from './domain/useNavigationController'import { useNotificationSettingsController } from './domain/useNotificationSettingsController'import { useNotificationsController } from './domain/useNotificationsController'+import { useOnboardingController } from './domain/useOnboardingController'import { useTeamsDataController } from './domain/useTeamsDataController'import { useToastController } from './domain/useToastController'import {@@ -167,6 +169,18 @@ export function useAppController() {onSessionNeedsLoad,})+ // ─── First-run onboarding ───+ const onboarding = useOnboardingController()+ // Onboarding owns the unauthenticated screen only while the app has no+ // environment at all (spec §5.1). Saving one — or selecting Localhost —+ // flips `configured`, which retires the wizard; deleting the last one brings+ // it back rather than leaving a sign-in form with nothing to sign in to.+ const unauthenticatedView = selectUnauthenticatedView({+ hasDependencyOutage: auth.hasDependencyOutage,+ runtimeConfigMissing: auth.runtimeConfigMissing,+ isAuthenticated: auth.isAuthenticated,+ })+// ─── First-screen data contexts ───const agentsData = useAgentsDataController()const contextsData = useContextsDataController()@@ -1119,6 +1133,8 @@ export function useAppController() {authTransitioning: auth.authTransitioning,runtimeConfigState: auth.runtimeConfigState,runtimeConfigMissing: auth.runtimeConfigMissing,+ onboarding,+ unauthenticatedView,desktopReleaseStatus: auth.desktopReleaseStatus,desktopEnvironmentSetupComplete: auth.desktopEnvironmentSetupComplete,pendingDesktopEnvironmentSetup: auth.pendingDesktopEnvironmentSetup,diff --git a/desktop-app/ui/src/lib/__tests__/unauthenticatedView.test.ts b/desktop-app/ui/src/lib/__tests__/unauthenticatedView.test.tsnew file mode 100644index 000000000..bcf4112f0--- /dev/null+++ b/desktop-app/ui/src/lib/__tests__/unauthenticatedView.test.ts@@ -0,0 +1,31 @@+import { describe, expect, it } from 'vitest'+import { selectUnauthenticatedView } from '../unauthenticatedView'++const input = (overrides: Partial<Parameters<typeof selectUnauthenticatedView>[0]> = {}) => ({+ hasDependencyOutage: false,+ runtimeConfigMissing: false,+ isAuthenticated: false,+ ...overrides,+})++describe('selectUnauthenticatedView', () => {+ it('renders sign-in for a configured environment', () => {+ expect(selectUnauthenticatedView(input())).toBe('auth')+ })++ it('renders onboarding when no environment is configured', () => {+ expect(selectUnauthenticatedView(input({ runtimeConfigMissing: true }))).toBe('onboarding')+ })++ it('renders the outage page ahead of onboarding', () => {+ expect(+ selectUnauthenticatedView(input({ hasDependencyOutage: true, runtimeConfigMissing: true }))+ ).toBe('outage')+ })++ it('never renders onboarding to a signed-in user', () => {+ expect(+ selectUnauthenticatedView(input({ runtimeConfigMissing: true, isAuthenticated: true }))+ ).toBe('auth')+ })+})diff --git a/desktop-app/ui/src/lib/unauthenticatedView.ts b/desktop-app/ui/src/lib/unauthenticatedView.tsnew file mode 100644index 000000000..de815f146--- /dev/null+++ b/desktop-app/ui/src/lib/unauthenticatedView.ts@@ -0,0 +1,27 @@+export type UnauthenticatedView = 'outage' | 'onboarding' | 'auth'++interface UnauthenticatedViewInput {+ hasDependencyOutage: boolean+ runtimeConfigMissing: boolean+ isAuthenticated: boolean+}++/**+ * Which screen the unauthenticated branch renders (spec §4.1).+ *+ * Order matters: an outage wins over everything, because neither signing in+ * nor onboarding can succeed while a dependency is down. Onboarding comes+ * next, so a cold install never lands on a sign-in form for an environment it+ * does not have. `isAuthenticated` is checked even though the caller only+ * renders this branch while signed out — the invariant that onboarding never+ * appears to a signed-in user is worth holding in one place.+ */+export function selectUnauthenticatedView({+ hasDependencyOutage,+ runtimeConfigMissing,+ isAuthenticated,+}: UnauthenticatedViewInput): UnauthenticatedView {+ if (hasDependencyOutage) return 'outage'+ if (runtimeConfigMissing && !isAuthenticated) return 'onboarding'+ return 'auth'+}diff --git a/desktop-app/ui/src/pages/AuthPage/index.tsx b/desktop-app/ui/src/pages/AuthPage/index.tsxindex 4fd38bb96..f0f07f2e0 100644--- a/desktop-app/ui/src/pages/AuthPage/index.tsx+++ b/desktop-app/ui/src/pages/AuthPage/index.tsx@@ -1,26 +1,27 @@import type { FormEvent } from 'react'-import { useEffect, useRef, useState } from 'react'+import { useState } from 'react'import { useAuthContext } from '@contexts/AuthContext'-import { Button, Field, IconButton, MenuItem, StatusBanner, TextInput } from '@components/Common'-import { ConfirmDialog } from '@components/ConfirmDialog'-import {- LOCALHOST_RUNTIME_CONFIG_OPTION_ID,- createLocalhostRuntimeConfigOption,-} from '@constants/runtimeConfig'+import { Button, Field, StatusBanner, TextInput } from '@components/Common'+import { RuntimeConfigDock } from '@components/RuntimeConfigDock'import { formatDesktopAppVersionTooltip, useDesktopAppInfo } from '@hooks/useDesktopAppInfo'-import type { DesktopRuntimeConfigOption } from '../../../../src/types'+/**+ * Sign-in for a configured environment.+ *+ * A cold install never reaches this page — the unauthenticated branch renders+ * onboarding instead (spec §4.1), so the invitation email form that used to+ * live here now belongs to the wizard's invited step (spec §5.5). AuthPage has+ * exactly one mode again: sign in, plus the environment dock and its inline+ * add-environment form.+ */export function AuthPage() {const {busy,email,password,- desktopSetupStarted,runtimeConfigSetupName,runtimeConfigSetupExternalRestApiBaseUrl,authTransitioning,- runtimeConfigState,- runtimeConfigMissing,backendSwitchHint,setEmail,setPassword,@@ -29,35 +30,15 @@ export function AuthPage() {setStatus,handlePasswordLogin,handleSwitchLoginBackend,- handleStartDesktopSetup,handleSaveRuntimeConfig,- handleDeleteRuntimeConfig,- handleSelectRuntimeConfig,- handleClearRuntimeConfigSelection,} = useAuthContext()- const runtimeConfigOptions = runtimeConfigState?.options || []- const activeRuntimeConfigId = runtimeConfigState?.activeOptionId ?? null- const selectedRuntimeConfig = runtimeConfigOptions.find(- option => option.id === activeRuntimeConfigId- )const hasPasswordLoginCredentials = Boolean(email.trim()) && Boolean(password)const [runtimeSetupVisible, setRuntimeSetupVisible] = useState(false)const hasRuntimeSetupValues =Boolean(runtimeConfigSetupName.trim()) &&Boolean(runtimeConfigSetupExternalRestApiBaseUrl.trim())- const [runtimeMenuOpen, setRuntimeMenuOpen] = useState(false)const [forgotPasswordBusy, setForgotPasswordBusy] = useState(false)- const [pendingDeleteOption, setPendingDeleteOption] = useState<DesktopRuntimeConfigOption | null>(- null- )- const runtimeDockRef = useRef<HTMLDivElement | null>(null)- const savedRuntimeConfigOptions = runtimeConfigOptions.filter(option => option.source === 'file')- const localhostRuntimeConfigOption = runtimeConfigOptions.find(- option => option.source === 'localhost'- )- const displayedLocalhostRuntimeConfigOption =- localhostRuntimeConfigOption || createLocalhostRuntimeConfigOption()const desktopAppInfo = useDesktopAppInfo()const desktopVersionTooltip = formatDesktopAppVersionTooltip(desktopAppInfo)@@ -68,13 +49,6 @@ export function AuthPage() {}}- const handleInvitationSetupSubmit = (event: FormEvent<HTMLFormElement>) => {- event.preventDefault()- if (!busy && email.trim()) {- handleStartDesktopSetup()- }- }-const handleForgotPasswordClick = async () => {if (busy || forgotPasswordBusy) returnsetForgotPasswordBusy(true)@@ -101,53 +75,6 @@ export function AuthPage() {setRuntimeSetupVisible(false)}- const handleRuntimeOptionSelect = (optionId: string) => {- setRuntimeMenuOpen(false)- if (- optionId === activeRuntimeConfigId &&- (selectedRuntimeConfig?.source === 'localhost' ||- optionId === LOCALHOST_RUNTIME_CONFIG_OPTION_ID)- ) {- handleClearRuntimeConfigSelection()- return- }- handleSelectRuntimeConfig(optionId)- }-- const confirmDeleteRuntimeOption = () => {- if (!pendingDeleteOption) return- handleDeleteRuntimeConfig(pendingDeleteOption.id)- setPendingDeleteOption(null)- }-- useEffect(() => {- if (!runtimeMenuOpen) {- return- }-- const handleDocumentPointerDown = (event: PointerEvent) => {- if (runtimeDockRef.current?.contains(event.target as Node)) {- return- }-- setRuntimeMenuOpen(false)- }-- const handleEscape = (event: KeyboardEvent) => {- if (event.key === 'Escape') {- setRuntimeMenuOpen(false)- }- }-- document.addEventListener('pointerdown', handleDocumentPointerDown)- document.addEventListener('keydown', handleEscape)-- return () => {- document.removeEventListener('pointerdown', handleDocumentPointerDown)- document.removeEventListener('keydown', handleEscape)- }- }, [runtimeMenuOpen])-return (<main className="auth-page"><section className="auth-card glass-card">@@ -201,9 +128,7 @@ export function AuthPage() {Go back to login</button></form>- ) : null}-- {!runtimeConfigMissing && !runtimeSetupVisible ? (+ ) : (<form className="auth-form-stack" onSubmit={handlePasswordSubmit}><Field label="Email" htmlFor="email-input" wrapperClassName="auth-form-row"><TextInput@@ -263,174 +188,9 @@ export function AuthPage() {</StatusBanner>) : null}</form>- ) : null}-- {runtimeConfigMissing && !runtimeSetupVisible ? (- <form className="auth-form-stack" onSubmit={handleInvitationSetupSubmit}>- <Field- label="Email"- htmlFor="desktop-setup-email-input"- wrapperClassName="auth-form-row"- >- <TextInput- id="desktop-setup-email-input"- type="email"- placeholder="[email protected]"- value={email}- onChange={event => setEmail(event.target.value)}- />- </Field>- <Button block disabled={!email.trim() || busy} type="submit">- {authTransitioning ? (- <span className="auth-button-loading">- <span className="auth-button-spinner" aria-hidden="true" />- Opening setup...- </span>- ) : desktopSetupStarted ? (- 'Open setup again'- ) : (- 'Continue setup'- )}- </Button>- </form>- ) : null}+ )}</section>- {runtimeConfigState ? (- <aside className="auth-runtime-dock" ref={runtimeDockRef}>- <IconButton- className="auth-runtime-dock__toggle"- aria-label="Open environment selector"- aria-expanded={runtimeMenuOpen}- aria-controls="auth-runtime-dock-panel"- label="Open environment selector"- onClick={() => setRuntimeMenuOpen(open => !open)}- variant="soft"- >- <svg viewBox="0 0 24 24" aria-hidden="true" focusable="false">- <path d="M19.43 12.98a7.9 7.9 0 0 0 .05-.98 7.9 7.9 0 0 0-.05-.98l2.11-1.65a.48.48 0 0 0 .12-.61l-2-3.46a.49.49 0 0 0-.58-.22l-2.49 1a7.2 7.2 0 0 0-1.7-.98l-.38-2.65A.49.49 0 0 0 14 2h-4a.49.49 0 0 0-.49.41l-.38 2.65a7.2 7.2 0 0 0-1.7.98l-2.49-1a.49.49 0 0 0-.58.22l-2 3.46a.48.48 0 0 0 .12.61l2.11 1.65a7.9 7.9 0 0 0-.05.98 7.9 7.9 0 0 0 .05.98l-2.11 1.65a.48.48 0 0 0-.12.61l2 3.46a.49.49 0 0 0 .58.22l2.49-1a7.2 7.2 0 0 0 1.7.98l.38 2.65A.49.49 0 0 0 10 22h4a.49.49 0 0 0 .49-.41l.38-2.65a7.2 7.2 0 0 0 1.7-.98l2.49 1a.49.49 0 0 0 .58-.22l2-3.46a.48.48 0 0 0-.12-.61Zm-7.43 2.52A3.5 3.5 0 1 1 15.5 12 3.5 3.5 0 0 1 12 15.5Z" />- </svg>- </IconButton>- {runtimeMenuOpen ? (- <div className="auth-runtime-dock__panel glass-card" id="auth-runtime-dock-panel">- <div className="auth-runtime-menu__header">- <span className="auth-runtime-menu__label">Environment</span>- <IconButton- aria-label="Add environment"- disabled={busy || authTransitioning}- label="Add environment"- onClick={() => {- setRuntimeMenuOpen(false)- setRuntimeSetupVisible(true)- }}- size="sm"- variant="ghost"- >- <svg viewBox="0 0 24 24" aria-hidden="true" focusable="false">- <path d="M12 5v14" />- <path d="M5 12h14" />- </svg>- </IconButton>- </div>- <div className="auth-runtime-menu">- {savedRuntimeConfigOptions.length > 0 ? (- <section className="auth-runtime-menu__section">- {savedRuntimeConfigOptions.map(option => {- const selected = option.id === activeRuntimeConfigId- return (- <div- key={option.id}- className={`auth-runtime-menu__row${selected ? ' selected' : ''}`}- >- <MenuItem- className={`auth-runtime-menu__select${selected ? ' selected' : ''}`}- active={selected}- disabled={busy || authTransitioning}- leadingIcon={- <span className="auth-runtime-menu__check" aria-hidden="true">- {selected ? (- <svg viewBox="0 0 24 24" focusable="false">- <path d="M20 6 9 17l-5-5" />- </svg>- ) : null}- </span>- }- onClick={() => handleRuntimeOptionSelect(option.id)}- >- {option.label}- </MenuItem>- <IconButton- className="auth-runtime-menu__delete"- aria-label={`Delete ${option.appName} environment`}- color="danger"- disabled={busy || authTransitioning}- label={`Delete ${option.appName}`}- onClick={() => setPendingDeleteOption(option)}- size="sm"- title={`Delete ${option.appName}`}- variant="ghost"- >- <svg viewBox="0 0 24 24" aria-hidden="true" focusable="false">- <path d="M3 6h18" />- <path d="M8 6V4h8v2" />- <path d="M6 6l1 15h10l1-15" />- <path d="M10 10v7" />- <path d="M14 10v7" />- </svg>- </IconButton>- </div>- )- })}- </section>- ) : null}- {displayedLocalhostRuntimeConfigOption ? (- <section className="auth-runtime-menu__section">- {(() => {- const option = displayedLocalhostRuntimeConfigOption- const selected = option.id === activeRuntimeConfigId- return (- <MenuItem- className={`auth-runtime-menu__select auth-runtime-menu__select--standalone${- selected ? ' selected' : ''- }`}- active={selected}- disabled={busy || authTransitioning}- leadingIcon={- <span className="auth-runtime-menu__check" aria-hidden="true">- {selected ? (- <svg viewBox="0 0 24 24" focusable="false">- <path d="M20 6 9 17l-5-5" />- </svg>- ) : null}- </span>- }- onClick={() => handleRuntimeOptionSelect(option.id)}- >- Localhost- </MenuItem>- )- })()}- </section>- ) : null}- </div>- </div>- ) : null}- </aside>- ) : null}- {pendingDeleteOption ? (- <ConfirmDialog- title="Delete environment?"- body={- <p>- Delete <strong>{pendingDeleteOption.appName}</strong>? This only removes the local- desktop environment configuration.- </p>- }- confirmLabel="Delete"- tone="danger"- onCancel={() => setPendingDeleteOption(null)}- onConfirm={confirmDeleteRuntimeOption}- />- ) : null}+ <RuntimeConfigDock onAddEnvironment={() => setRuntimeSetupVisible(true)} /></main>)}diff --git a/desktop-app/ui/src/pages/OnboardingPage/index.tsx b/desktop-app/ui/src/pages/OnboardingPage/index.tsxnew file mode 100644index 000000000..ca7efde3d--- /dev/null+++ b/desktop-app/ui/src/pages/OnboardingPage/index.tsx@@ -0,0 +1,54 @@+import { RuntimeConfigDock } from '@components/RuntimeConfigDock'+import { formatDesktopAppVersionTooltip, useDesktopAppInfo } from '@hooks/useDesktopAppInfo'+import { InvitedMember } from './steps/InvitedMember'+import { ManualEnvironment } from './steps/ManualEnvironment'+import { PathChoice } from './steps/PathChoice'+import { SelfHosted } from './steps/SelfHosted'+import type { OnboardingViewModel } from './types'++interface OnboardingPageProps {+ onboarding: OnboardingViewModel+}++/**+ * First-run onboarding (spec §5.2).+ *+ * Rendered instead of AuthPage when the app has no environment at all, so it+ * also carries the environment dock: the Localhost escape hatch (path E) lives+ * there, and a cold install would otherwise have no way to reach it.+ */+export function OnboardingPage({ onboarding }: OnboardingPageProps) {+ const { step, canGoBack, answerOrigin, answerRunStyle, goToManual, back } = onboarding+ const desktopAppInfo = useDesktopAppInfo()+ const desktopVersionTooltip = formatDesktopAppVersionTooltip(desktopAppInfo)++ return (+ <main className="auth-page">+ <section className="auth-card glass-card">+ <header className="auth-card__header">+ <div className="auth-brand" title={desktopVersionTooltip}>+ <img className="auth-brand-mark" src="./logo.svg" alt="" aria-hidden="true" />+ <span className="auth-brand-copy">+ <span className="auth-brand-title">Evenfire</span>+ <span className="auth-brand-subtitle">Desktop App</span>+ </span>+ </div>+ </header>++ {step === 'origin' || step === 'runStyle' ? (+ <PathChoice step={step} onAnswerOrigin={answerOrigin} onAnswerRunStyle={answerRunStyle} />+ ) : null}+ {step === 'invited' ? <InvitedMember /> : null}+ {step === 'selfHosted' ? <SelfHosted onContinue={goToManual} /> : null}+ {step === 'manual' ? <ManualEnvironment /> : null}++ {canGoBack ? (+ <button type="button" className="auth-inline-link" onClick={back}>+ Back+ </button>+ ) : null}+ </section>+ <RuntimeConfigDock onAddEnvironment={goToManual} />+ </main>+ )+}diff --git a/desktop-app/ui/src/pages/OnboardingPage/steps/InvitedMember.tsx b/desktop-app/ui/src/pages/OnboardingPage/steps/InvitedMember.tsxnew file mode 100644index 000000000..3eb10d64a--- /dev/null+++ b/desktop-app/ui/src/pages/OnboardingPage/steps/InvitedMember.tsx@@ -0,0 +1,55 @@+import type { FormEvent } from 'react'+import { useAuthContext } from '@contexts/AuthContext'+import { Button, Field, TextInput } from '@components/Common'++/**+ * Path C — invited member (spec §5.5).+ *+ * Behaviour is unchanged from the form this replaces on AuthPage: the same+ * `handleStartDesktopSetup` handler, the same single email field, the same+ * "Open setup again" affordance once setup has been started. Only its home+ * moved. Distinct copy for a missing invitation lands in the follow-up PR.+ */+export function InvitedMember() {+ const { busy, email, desktopSetupStarted, authTransitioning, setEmail, handleStartDesktopSetup } =+ useAuthContext()++ const handleSubmit = (event: FormEvent<HTMLFormElement>) => {+ event.preventDefault()+ if (!busy && email.trim()) {+ handleStartDesktopSetup()+ }+ }++ return (+ <>+ <h1>Connect to your team</h1>+ <p className="muted">+ Enter the email address your team invited. We’ll open your browser to finish setup.+ </p>+ <form className="auth-form-stack" onSubmit={handleSubmit}>+ <Field label="Email" htmlFor="desktop-setup-email-input" wrapperClassName="auth-form-row">+ <TextInput+ id="desktop-setup-email-input"+ type="email"+ placeholder="[email protected]"+ value={email}+ onChange={event => setEmail(event.target.value)}+ />+ </Field>+ <Button block disabled={!email.trim() || busy} type="submit">+ {authTransitioning ? (+ <span className="auth-button-loading">+ <span className="auth-button-spinner" aria-hidden="true" />+ Opening setup...+ </span>+ ) : desktopSetupStarted ? (+ 'Open setup again'+ ) : (+ 'Continue setup'+ )}+ </Button>+ </form>+ </>+ )+}diff --git a/desktop-app/ui/src/pages/OnboardingPage/steps/ManualEnvironment.tsx b/desktop-app/ui/src/pages/OnboardingPage/steps/ManualEnvironment.tsxnew file mode 100644index 000000000..427d72d27--- /dev/null+++ b/desktop-app/ui/src/pages/OnboardingPage/steps/ManualEnvironment.tsx@@ -0,0 +1,114 @@+import type { FormEvent } from 'react'+import { useEffect, useState } from 'react'+import { useAuthContext } from '@contexts/AuthContext'+import { Button, Field, StatusBanner, TextInput } from '@components/Common'+import { LOCALHOST_RUNTIME_CONFIG_OPTION_ID } from '@constants/runtimeConfig'++/**+ * Path D — manual environment (spec §5.6).+ *+ * The terminal step for paths B and D alike, so it carries the local-cluster+ * hint for both. It shares `handleSaveRuntimeConfig` with AuthPage's inline+ * environment form: one submit path, one validation rule.+ */+export function ManualEnvironment() {+ const {+ busy,+ runtimeConfigSetupName,+ runtimeConfigSetupExternalRestApiBaseUrl,+ setRuntimeConfigSetupName,+ setRuntimeConfigSetupExternalRestApiBaseUrl,+ handleSaveRuntimeConfig,+ handleSelectRuntimeConfig,+ } = useAuthContext()++ const [localhostReachable, setLocalhostReachable] = useState(false)++ const hasRuntimeSetupValues =+ Boolean(runtimeConfigSetupName.trim()) &&+ Boolean(runtimeConfigSetupExternalRestApiBaseUrl.trim())++ // One bounded probe on entry (spec §9.4). It takes no URL — the main process+ // only ever checks the built-in Localhost option — and a negative or failed+ // result renders nothing, so a user with no local cluster sees no trace of+ // it. The probe never fills the form or saves on its own.+ useEffect(() => {+ let cancelled = false+ const probe = window.clerum.auth.probeLocalhostReachable+ if (typeof probe !== 'function') return++ probe()+ .then(reachable => {+ if (!cancelled) setLocalhostReachable(reachable)+ })+ .catch(() => undefined)++ return () => {+ cancelled = true+ }+ }, [])++ const handleSubmit = (event: FormEvent<HTMLFormElement>) => {+ event.preventDefault()+ if (!busy && hasRuntimeSetupValues) {+ void handleSaveRuntimeConfig()+ }+ }++ return (+ <>+ <h1>Connect to a server</h1>+ <p className="muted">+ Enter the address of your Evenfire server. You can add more environments later.+ </p>+ {localhostReachable ? (+ <StatusBanner tone="info">+ <span className="auth-backend-hint">+ <span>A local Evenfire looks like it’s running on this machine.</span>+ <Button+ type="button"+ size="sm"+ variant="soft"+ block+ disabled={busy}+ onClick={() => void handleSelectRuntimeConfig(LOCALHOST_RUNTIME_CONFIG_OPTION_ID)}+ >+ Use Localhost+ </Button>+ </span>+ </StatusBanner>+ ) : null}+ <form className="auth-form-stack" onSubmit={handleSubmit}>+ <Field+ label="Environment name"+ htmlFor="runtime-config-name-input"+ wrapperClassName="auth-form-row"+ >+ <TextInput+ id="runtime-config-name-input"+ type="text"+ placeholder="Production"+ value={runtimeConfigSetupName}+ onChange={event => setRuntimeConfigSetupName(event.target.value)}+ />+ </Field>+ <Field+ label="External REST API"+ htmlFor="runtime-config-external-rest-api-input"+ wrapperClassName="auth-form-row"+ >+ <TextInput+ id="runtime-config-external-rest-api-input"+ type="url"+ placeholder="https://evenfire.example.com"+ value={runtimeConfigSetupExternalRestApiBaseUrl}+ onChange={event => setRuntimeConfigSetupExternalRestApiBaseUrl(event.target.value)}+ />+ </Field>+ <Button block disabled={!hasRuntimeSetupValues || busy} type="submit">+ Save environment+ </Button>+ </form>+ </>+ )+}diff --git a/desktop-app/ui/src/pages/OnboardingPage/steps/PathChoice.tsx b/desktop-app/ui/src/pages/OnboardingPage/steps/PathChoice.tsxnew file mode 100644index 000000000..32b75216b--- /dev/null+++ b/desktop-app/ui/src/pages/OnboardingPage/steps/PathChoice.tsx@@ -0,0 +1,83 @@+import { SelectableOption } from '@components/Common'+import type { OnboardingOriginAnswer, OnboardingRunStyleAnswer } from '../types'++interface PathChoiceProps {+ step: 'origin' | 'runStyle'+ onAnswerOrigin: (answer: OnboardingOriginAnswer) => void+ onAnswerRunStyle: (answer: OnboardingRunStyleAnswer) => void+}++/**+ * The questionnaire itself — Q1, and Q2 once the hosted path ships (spec §3).+ *+ * Q1's "I have a server address" doubles as the wizard's one-click skip, which+ * is why the first step needs no separate skip control.+ */+export function PathChoice({ step, onAnswerOrigin, onAnswerRunStyle }: PathChoiceProps) {+ if (step === 'runStyle') {+ return (+ <>+ <h1>How do you want to run Evenfire?</h1>+ <div className="onboarding-options">+ <SelectableOption+ className="onboarding-option"+ size="lg"+ onClick={() => onAnswerRunStyle('hosted')}+ >+ <span className="onboarding-option__title">Evenfire hosts it for me</span>+ <span className="onboarding-option__hint">+ Free for 1 week. Nothing to deploy or operate.+ </span>+ </SelectableOption>+ <SelectableOption+ className="onboarding-option"+ size="lg"+ onClick={() => onAnswerRunStyle('selfHosted')}+ >+ <span className="onboarding-option__title">I’ll run it myself</span>+ <span className="onboarding-option__hint">+ Deploy Evenfire to a cluster you control.+ </span>+ </SelectableOption>+ </div>+ </>+ )+ }++ return (+ <>+ <h1>Do you already have an Evenfire server?</h1>+ <p className="muted">+ The desktop app connects to an Evenfire server. Tell us which one and we’ll get you there.+ </p>+ <div className="onboarding-options">+ <SelectableOption+ className="onboarding-option"+ size="lg"+ onClick={() => onAnswerOrigin('invited')}+ >+ <span className="onboarding-option__title">My team already uses Evenfire</span>+ <span className="onboarding-option__hint">+ Finish setup with the email your team invited.+ </span>+ </SelectableOption>+ <SelectableOption+ className="onboarding-option"+ size="lg"+ onClick={() => onAnswerOrigin('haveAddress')}+ >+ <span className="onboarding-option__title">I have a server address</span>+ <span className="onboarding-option__hint">Connect to a server you already know.</span>+ </SelectableOption>+ <SelectableOption+ className="onboarding-option"+ size="lg"+ onClick={() => onAnswerOrigin('gettingStarted')}+ >+ <span className="onboarding-option__title">No, I’m just getting started</span>+ <span className="onboarding-option__hint">See what it takes to run Evenfire.</span>+ </SelectableOption>+ </div>+ </>+ )+}diff --git a/desktop-app/ui/src/pages/OnboardingPage/steps/SelfHosted.tsx b/desktop-app/ui/src/pages/OnboardingPage/steps/SelfHosted.tsxnew file mode 100644index 000000000..7036a2816--- /dev/null+++ b/desktop-app/ui/src/pages/OnboardingPage/steps/SelfHosted.tsx@@ -0,0 +1,66 @@+import { useState } from 'react'+import { useAuthContext } from '@contexts/AuthContext'+import { Button } from '@components/Common'++interface SelfHostedProps {+ /** Continue into the manual environment step, which owns the submit path. */+ onContinue: () => void+}++/**+ * Path B — self-hosted (spec §5.4).+ *+ * Documentation-first: deployment shapes differ too much for a wizard to guide+ * any of them honestly, so this step names the option, links out, and hands to+ * path D. It deliberately shows no prerequisites, no install command and no+ * default address — all three would assume a deployment shape, and+ * self-hosting means any cluster the user controls, remote or local.+ */+export function SelfHosted({ onContinue }: SelfHostedProps) {+ const { busy, setStatus } = useAuthContext()+ const [openingDocs, setOpeningDocs] = useState(false)++ const handleOpenDocs = async () => {+ if (openingDocs) return+ setOpeningDocs(true)+ try {+ // Vite can hot-reload renderer code while Electron still runs an older+ // preload script, matching the guard on the environment delete action.+ if (typeof window.clerum.auth.openDeploymentDocs !== 'function') {+ throw new Error('Restart the desktop app to finish loading the deployment guide link')+ }+ await window.clerum.auth.openDeploymentDocs()+ setStatus('Deployment guide opened in your browser.', 'success', undefined, {+ global: false,+ toast: true,+ })+ } catch (error) {+ setStatus(+ `The deployment guide could not be opened: ${+ error instanceof Error ? error.message : String(error)+ }`,+ 'error'+ )+ } finally {+ setOpeningDocs(false)+ }+ }++ return (+ <>+ <h1>Run Evenfire yourself</h1>+ <p className="muted">+ Deploy Evenfire to a Kubernetes cluster you control — your own infrastructure or a local+ one. The deployment guide covers both, including what each shape needs.+ </p>+ <div className="auth-flow-card__actions">+ <Button block disabled={busy || openingDocs} onClick={() => void handleOpenDocs()}>+ Open the deployment guide+ </Button>+ <Button block disabled={busy} onClick={onContinue} variant="soft">+ I have a server — enter its address+ </Button>+ </div>+ </>+ )+}diff --git a/desktop-app/ui/src/pages/OnboardingPage/types.ts b/desktop-app/ui/src/pages/OnboardingPage/types.tsnew file mode 100644index 000000000..79c85de3a--- /dev/null+++ b/desktop-app/ui/src/pages/OnboardingPage/types.ts@@ -0,0 +1,33 @@+/**+ * First-run onboarding types (spec §5.2).+ *+ * The wizard is one page with a step model and an explicit history stack, not+ * a set of routes. Answers live in the controller; only a path's terminal+ * action touches disk.+ */++export type OnboardingStep = 'origin' | 'runStyle' | 'invited' | 'selfHosted' | 'manual'++/** Q1 — "Do you already have an Evenfire server?" */+export type OnboardingOriginAnswer = 'invited' | 'haveAddress' | 'gettingStarted'++/**+ * Q2 — "How do you want to run Evenfire?"+ *+ * Only reachable once the hosted trial path ships; until then Q1's+ * "just getting started" goes straight to the self-hosted step (spec §7.1).+ */+export type OnboardingRunStyleAnswer = 'hosted' | 'selfHosted'++export interface OnboardingViewModel {+ step: OnboardingStep+ /** False on the first step, which uses Q1's "I have a server address" as its skip. */+ canGoBack: boolean+ /** Whether Q2 is part of the flow. False until the hosted project exists. */+ hostedAvailable: boolean+ answerOrigin: (answer: OnboardingOriginAnswer) => void+ answerRunStyle: (answer: OnboardingRunStyleAnswer) => void+ goToManual: () => void+ back: () => void+ reset: () => void+}diff --git a/desktop-app/ui/src/pages/__tests__/AuthPage.test.tsx b/desktop-app/ui/src/pages/__tests__/AuthPage.test.tsxindex f209728ce..6552befce 100644--- a/desktop-app/ui/src/pages/__tests__/AuthPage.test.tsx+++ b/desktop-app/ui/src/pages/__tests__/AuthPage.test.tsx@@ -78,10 +78,12 @@ function renderAuthPage(auth?: Partial<AuthContextValue>) {}describe('AuthPage', () => {- it('asks for invitation email when no environment is configured', async () => {- const user = userEvent.setup()+ // The invitation email form moved to onboarding's invited step (spec §5.5).+ // AuthPage has one mode again, and must keep it even if it is somehow+ // rendered without an environment — the unauthenticated branch routes that+ // case to OnboardingPage instead.+ it('renders sign-in only, never the invitation form, when no environment is configured', () => {const handleStartDesktopSetup = vi.fn()- const setEmail = vi.fn()renderAuthPage({runtimeConfigMissing: true,@@ -95,16 +97,13 @@ describe('AuthPage', () => {options: [],},email: '[email protected]',- setEmail,handleStartDesktopSetup,})expect(screen.getByLabelText('Email')).toBeTruthy()- expect(screen.queryByLabelText('Password')).toBeNull()-- await user.click(screen.getByRole('button', { name: 'Continue setup' }))-- expect(handleStartDesktopSetup).toHaveBeenCalledTimes(1)+ expect(screen.getByLabelText('Password')).toBeTruthy()+ expect(screen.queryByRole('button', { name: 'Continue setup' })).toBeNull()+ expect(handleStartDesktopSetup).not.toHaveBeenCalled()})it('hides login while adding an environment and can return to login', async () => {diff --git a/desktop-app/ui/src/pages/__tests__/OnboardingPage.test.tsx b/desktop-app/ui/src/pages/__tests__/OnboardingPage.test.tsxnew file mode 100644index 000000000..a43d967aa--- /dev/null+++ b/desktop-app/ui/src/pages/__tests__/OnboardingPage.test.tsx@@ -0,0 +1,258 @@+// @vitest-environment jsdom+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'+import { cleanup, render, screen } from '@testing-library/react'+import userEvent from '@testing-library/user-event'+import { LOCALHOST_RUNTIME_CONFIG_OPTION_ID } from '../../constants/runtimeConfig'+import { AuthContext } from '../../contexts/AuthContext'+import type { AuthContextValue } from '../../contexts/AuthContext'+import { useOnboardingController } from '../../hooks/domain/useOnboardingController'+import { OnboardingPage } from '../OnboardingPage'++afterEach(() => {+ cleanup()+})++let probeLocalhostReachable = vi.fn()+let openDeploymentDocs = vi.fn()++beforeEach(() => {+ probeLocalhostReachable = vi.fn().mockResolvedValue(false)+ openDeploymentDocs = vi.fn().mockResolvedValue({ opened: true })+ ;(window as unknown as { clerum: unknown }).clerum = {+ auth: { probeLocalhostReachable, openDeploymentDocs },+ }+})++const makeAuthValue = (overrides: Partial<AuthContextValue> = {}): AuthContextValue => ({+ booting: false,+ busy: false,+ statusText: 'Ready.',+ statusTone: 'info',+ isAuthenticated: false,+ me: null,+ email: '',+ password: '',+ desktopSetupAuthorizationToken: '',+ desktopSetupStarted: false,+ desktopEnvironmentSetupComplete: false,+ runtimeConfigSetupName: '',+ runtimeConfigSetupExternalRestApiBaseUrl: '',+ runtimeConfigSetupRpcProxyBaseUrl: '',+ authTransitioning: false,+ runtimeConfigState: {+ configured: false,+ isLocalhost: false,+ selectorVisible: true,+ activeOptionId: null,+ envKey: 'env-test-key',+ storagePath: '/tmp/evenfire-runtime-config',+ options: [],+ },+ desktopReleaseStatus: null,+ pendingDesktopEnvironmentSetup: null,+ backendSwitchHint: null,+ runtimeConfigMissing: true,+ showRuntimeConfigSelector: false,+ dependencyHealth: null,+ hasDependencyOutage: false,+ setBooting: vi.fn(),+ setEmail: vi.fn(),+ setPassword: vi.fn(),+ setDesktopSetupAuthorizationToken: vi.fn(),+ setDesktopEnvironmentSetupComplete: vi.fn(),+ setPendingDesktopEnvironmentSetup: vi.fn(),+ setRuntimeConfigSetupName: vi.fn(),+ setRuntimeConfigSetupExternalRestApiBaseUrl: vi.fn(),+ setRuntimeConfigSetupRpcProxyBaseUrl: vi.fn(),+ setStatus: vi.fn(),+ loadSession: vi.fn(),+ handlePasswordLogin: vi.fn(),+ handleSwitchLoginBackend: vi.fn(),+ handleStartDesktopSetup: vi.fn(),+ handleCompleteDesktopSetup: vi.fn(),+ handleSaveRuntimeConfig: vi.fn(),+ handleDeleteRuntimeConfig: vi.fn(),+ handleSelectRuntimeConfig: vi.fn(),+ handleClearRuntimeConfigSelection: vi.fn(),+ handleCancelDesktopEnvironmentSetup: vi.fn(),+ handleConfirmDesktopEnvironmentSetup: vi.fn(),+ handleOpenDesktopRelease: vi.fn(),+ handleLogout: vi.fn(),+ ...overrides,+})++/** Drives the page with the real controller, so routing is exercised end to end. */+function OnboardingHarness() {+ const onboarding = useOnboardingController()+ return <OnboardingPage onboarding={onboarding} />+}++function renderOnboarding(auth?: Partial<AuthContextValue>) {+ return render(+ <AuthContext.Provider value={makeAuthValue(auth)}>+ <OnboardingHarness />+ </AuthContext.Provider>+ )+}++describe('OnboardingPage', () => {+ it('opens on Q1 with the three origin answers', () => {+ renderOnboarding()++ expect(screen.getByText('Do you already have an Evenfire server?')).toBeTruthy()+ expect(screen.getByRole('button', { name: /My team already uses Evenfire/ })).toBeTruthy()+ expect(screen.getByRole('button', { name: /I have a server address/ })).toBeTruthy()+ expect(screen.getByRole('button', { name: /No, I’m just getting started/ })).toBeTruthy()+ // The first step is the one with no way back; Q1's second answer is its skip.+ expect(screen.queryByRole('button', { name: 'Back' })).toBeNull()+ })++ it('routes the invited answer to the invitation step with its existing handler', async () => {+ const user = userEvent.setup()+ const handleStartDesktopSetup = vi.fn()++ renderOnboarding({ email: '[email protected]', handleStartDesktopSetup })++ await user.click(screen.getByRole('button', { name: /My team already uses Evenfire/ }))++ expect(screen.getByLabelText('Email')).toBeTruthy()+ await user.click(screen.getByRole('button', { name: 'Continue setup' }))++ expect(handleStartDesktopSetup).toHaveBeenCalledTimes(1)+ })++ it('routes the have-an-address answer straight to the manual environment form', async () => {+ const user = userEvent.setup()++ renderOnboarding()++ await user.click(screen.getByRole('button', { name: /I have a server address/ }))++ expect(screen.getByLabelText('Environment name')).toBeTruthy()+ expect(screen.getByLabelText('External REST API')).toBeTruthy()+ })++ it('sends the getting-started answer to the self-hosted step while path A is unavailable', async () => {+ const user = userEvent.setup()++ renderOnboarding()++ await user.click(screen.getByRole('button', { name: /No, I’m just getting started/ }))++ // Q2 is skipped entirely rather than offering a choice with one real answer.+ expect(screen.queryByText('How do you want to run Evenfire?')).toBeNull()+ expect(screen.getByText('Run Evenfire yourself')).toBeTruthy()+ })++ it('keeps the self-hosted step neutral about where the server runs', async () => {+ const user = userEvent.setup()++ renderOnboarding()+ await user.click(screen.getByRole('button', { name: /No, I’m just getting started/ }))++ const step = screen.getByText('Run Evenfire yourself').closest('section')+ const copy = step?.textContent || ''+ // Self-hosting means any cluster the user controls (spec §5.4). No install+ // command, no RAM figure, no loopback default, no single deployment shape.+ expect(copy).not.toMatch(/minikube|docker|127\.0\.0\.1|localhost|GB|RAM|your machine/i)+ })++ it('opens the deployment guide without writing an environment', async () => {+ const user = userEvent.setup()+ const handleSaveRuntimeConfig = vi.fn()++ renderOnboarding({ handleSaveRuntimeConfig })+ await user.click(screen.getByRole('button', { name: /No, I’m just getting started/ }))+ await user.click(screen.getByRole('button', { name: 'Open the deployment guide' }))++ expect(openDeploymentDocs).toHaveBeenCalledTimes(1)+ // No argument: the renderer never names a URL for the main process (spec §6.8).+ expect(openDeploymentDocs).toHaveBeenCalledWith()+ expect(handleSaveRuntimeConfig).not.toHaveBeenCalled()+ })++ it('hands the self-hosted path to the manual environment form', async () => {+ const user = userEvent.setup()++ renderOnboarding()+ await user.click(screen.getByRole('button', { name: /No, I’m just getting started/ }))+ await user.click(screen.getByRole('button', { name: /I have a server — enter its address/ }))++ expect(screen.getByLabelText('Environment name')).toBeTruthy()+ })++ it('walks back to the previous step, and to Q1 from a two-step path', async () => {+ const user = userEvent.setup()++ renderOnboarding()+ await user.click(screen.getByRole('button', { name: /No, I’m just getting started/ }))+ await user.click(screen.getByRole('button', { name: /I have a server — enter its address/ }))++ expect(screen.getByLabelText('Environment name')).toBeTruthy()++ await user.click(screen.getByRole('button', { name: 'Back' }))+ expect(screen.getByText('Run Evenfire yourself')).toBeTruthy()++ await user.click(screen.getByRole('button', { name: 'Back' }))+ expect(screen.getByText('Do you already have an Evenfire server?')).toBeTruthy()+ expect(screen.queryByRole('button', { name: 'Back' })).toBeNull()+ })++ it('offers the local cluster when one answers, and selects the existing option', async () => {+ const user = userEvent.setup()+ const handleSelectRuntimeConfig = vi.fn()+ probeLocalhostReachable.mockResolvedValue(true)++ renderOnboarding({ handleSelectRuntimeConfig })+ await user.click(screen.getByRole('button', { name: /I have a server address/ }))++ const hint = await screen.findByRole('button', { name: 'Use Localhost' })+ // The probe takes no URL argument (spec §5.6).+ expect(probeLocalhostReachable).toHaveBeenCalledWith()++ await user.click(hint)++ // Reuses the built-in Localhost option rather than saving a duplicate+ // environment that points at the same address.+ expect(handleSelectRuntimeConfig).toHaveBeenCalledWith(LOCALHOST_RUNTIME_CONFIG_OPTION_ID)+ })++ it('shows no local-cluster hint when nothing answers', async () => {+ const user = userEvent.setup()++ renderOnboarding()+ await user.click(screen.getByRole('button', { name: /I have a server address/ }))++ await screen.findByLabelText('Environment name')+ expect(probeLocalhostReachable).toHaveBeenCalledTimes(1)+ expect(screen.queryByRole('button', { name: 'Use Localhost' })).toBeNull()+ })++ it('keeps the Localhost escape hatch reachable from onboarding', async () => {+ const user = userEvent.setup()+ const handleSelectRuntimeConfig = vi.fn()++ renderOnboarding({ handleSelectRuntimeConfig })++ await user.click(screen.getByLabelText('Open environment selector'))+ await user.click(screen.getByRole('button', { name: 'Localhost' }))++ expect(handleSelectRuntimeConfig).toHaveBeenCalledWith(LOCALHOST_RUNTIME_CONFIG_OPTION_ID)+ })++ it('saves through the same submit path as the AuthPage environment form', async () => {+ const user = userEvent.setup()+ const handleSaveRuntimeConfig = vi.fn().mockResolvedValue(null)++ renderOnboarding({+ handleSaveRuntimeConfig,+ runtimeConfigSetupName: 'Production',+ runtimeConfigSetupExternalRestApiBaseUrl: 'https://evenfire.example.com',+ })++ await user.click(screen.getByRole('button', { name: /I have a server address/ }))+ await user.click(screen.getByRole('button', { name: 'Save environment' }))++ expect(handleSaveRuntimeConfig).toHaveBeenCalledTimes(1)+ })+})diff --git a/desktop-app/ui/src/styles.css b/desktop-app/ui/src/styles.cssindex 93199659b..46364ebfc 100644--- a/desktop-app/ui/src/styles.css+++ b/desktop-app/ui/src/styles.css@@ -10261,6 +10261,35 @@ button.page-breadcrumb-link--plain-action:hover:enabled {align-items: stretch;}+/* First-run onboarding (spec §5.2). The wizard reuses the auth card shell and+ the auth form/link primitives; only the answer list is new. */+.onboarding-options {+ display: grid;+ gap: var(--space-2);+}++.onboarding-option {+ display: grid;+ gap: var(--space-1);+ justify-items: start;+ text-align: left;+ white-space: normal;+}++.onboarding-option__title {+ font-size: var(--font-size-sm);+ font-weight: var(--font-weight-semibold);+ line-height: var(--line-height-tight);+ color: var(--text);+}++.onboarding-option__hint {+ font-size: var(--font-size-xs);+ font-weight: var(--font-weight-regular);+ line-height: 1.4;+ color: var(--text-muted);+}+.auth-button-loading {display: inline-flex;align-items: center;