OS Startup Flow

This document explains how the Próx OS Shell boots in the browser: appearance, loading overlay, session gates, workspace hydration, and the first apps users see.

Entry And Providers

1. apps/os-shell/src/index.tsx calls applyBootShellAppearance() before createRoot so gradient tokens are available immediately.
2. enableReactScanIfRequested() may attach React Scan in development when the feature flag is enabled.
3. AppProviders wires i18n, TanStack Query, and shell settings.
4. RouterProvider mounts the shell router (apps/os-shell/src/router.tsx).

Boot Appearance

applyBootShellAppearance (apps/os-shell/src/browser-local/applyBootShellAppearance.ts) reads stored values synchronously. useApplyShellSettings keeps the document element in sync after React mounts.

The global loading overlay (ShellLoadingScreen) uses var(--os-desktop-background) so it matches the desktop scene instead of a flat page color.

Remote profile sync for appearance is not wired yet; future API work should reuse the same keys and broadcast a settings-changed event.

Loading Overlay

• useBootingState (apps/os-shell/src/shell/state/useShellEnvironment.ts) holds isBooting for ~820ms on first mount.
• DesktopSystemOverlayLayer renders ShellLoadingScreen while isBooting is true.
• Copy defaults to Starting Próx OS with a lightweight shell/registry/workspace subtitle.

This overlay is intentionally short: it covers registry and workspace setup, not remote data fetching.

Session And Welcome

After boot:

1. Signed-in gate — local prox-os.os.signed-in (see session overlays) decides whether login UI appears.
2. Hola — when signed in and welcome state is open, useDesktopShellController opens the Hola app (/app-os/hola) after workspace bounds are ready.
3. Desktop — registry-driven folders and dock become interactive; window layouts hydrate from prox-os.os.window-sizes.

Website mode (/app/*/website) skips Hola auto-open and uses different navigation guards. True fullscreen app Spaces use /spaces/:spaceId and fall back to the default desktop after refresh if the in-memory Space no longer exists.

Registry And Apps

• apps/os-shell/src/apps/registry.ts composes iframe templates, @prox-os/os-apps manifests, and shell-only local modules.
• Only registered manifests can open windows; App Store rows with runtimeAppId must match a registry entry.
• Lazy loading: local renderers in localAppComponents.tsx; iframes load on demand per window.

Boot Sequence (ASCII)

index.tsx
  └─ applyBootShellAppearance()     # gradient + theme from localStorage
  └─ React root
       └─ AppProviders / Router
            └─ DesktopShell
                 ├─ isBooting → ShellLoadingScreen (gradient background)
                 ├─ session.loginOpen → login overlay
                 ├─ workspaceReady → hydrate window layouts
                 └─ welcomeOpen → open Hola (/app-os/hola)

Related Docs

• docs/ai/context-pack.md — agent routing index
• docs/architecture/app-registry.md — manifest and route groups
• docs/architecture/state-model.md — shell vs app state
• docs/architecture/window-manager.md — window lifecycle

Agent Checklist

When changing startup behavior, update this file and verify:

• Boot loading uses --os-desktop-background, not --os-color-desktop alone.
• New localStorage keys are listed in proxOsLocalStorageKeys.ts.
• Hola, login, and website-mode guards stay consistent in useDesktopShellController.