Skip to content

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.ts
new file mode 100644
index 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.ts
index 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 false
diff --git a/desktop-app/src/config.ts b/desktop-app/src/config.ts
index 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: string
desktopProfileUiBaseUrl: string
desktopProfileUiBaseUrlExplicit: boolean
+ deploymentDocsUrl: string
requestTimeoutMs: number
gfsUploadTimeoutMs: number
appName: 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 and
diff --git a/desktop-app/src/ipc.ts b/desktop-app/src/ipc.ts
index 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.ts
index 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.ts
index 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.tsx
index 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.tsx
new file mode 100644
index 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.tsx
new file mode 100644
index 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.ts
new file mode 100644
index 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.ts
index 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/useMcpServersDataControlle
import { 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.ts
new file mode 100644
index 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.ts
new file mode 100644
index 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.tsx
index 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) return
setForgotPasswordBusy(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.tsx
new file mode 100644
index 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.tsx
new file mode 100644
index 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.tsx
new file mode 100644
index 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.tsx
new file mode 100644
index 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.tsx
new file mode 100644
index 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.ts
new file mode 100644
index 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.tsx
index 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: [],
},
- 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.tsx
new file mode 100644
index 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.css
index 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;