Browser-based graphical shell and control plane for a Linux server you own — real terminal, file manager, live metrics and BYOK AI in one mobile-first workspace. Next.js 16 · React 19 · node-pty · Tailwind v4 · shadcn/ui. Public alpha, self-hosted.
TypeScript browser-shellcontrol-planefile-managerhomelabmobile-firstnextjsptyreactself-hostedserver-managementshadcn-uisysadmintailwindcssterminaltypescriptvpsweb-desktopweb-terminal
fix(hydration): render the shell after mount — zero mismatches anywhere
Rahman615ebdd54247
diff --git a/docs/PROGRESS.md b/docs/PROGRESS.mdindex 593f53dc..0475de19 100644--- a/docs/PROGRESS.md+++ b/docs/PROGRESS.md@@ -8,6 +8,42 @@ Running log of what shipped each phase. Newest at top.> Read those phases as history. **This file is the source of truth for what exists** —> `ARCHITECTURE.md` is no longer maintained and carries a stale-warning banner.+## 2026-08-04 (hydration, final) — the fourth cause closed; zero mismatches anywhere (DONE)++The architectural one the previous entry deliberately left open.++**The shell now renders only after mount.** Which shell to draw depends on three things+the server cannot know — the viewport (`useResponsive` measures `window.innerWidth`), the+persisted per-surface choice (`localStorage` `sv:shell`) and the wallpaper preference — so+SSR always guessed desktop/macOS and a phone client then rendered iOS. Two different trees+is a guaranteed mismatch, and React answered by discarding the hydrated tree and+re-rendering the entire shell client-side. Because Radix derives ids from `useId`, the+divergence surfaced in the dev overlay as mismatched `DropdownMenuTrigger` ids — a symptom+that sent the first look at it in the wrong direction.++`Surface` now returns a skeleton (`#main-content` + sizing + `bg-background`) until a+one-shot post-hydration flag flips, so the server HTML and the tree React hydrates are+identical by construction.++**This is an improvement, not a trade-off, on the UX side.** The old behaviour PAINTED the+macOS desktop on a phone and then swapped it for iOS — a flash of the wrong operating+system. A brief flash of the themed background is strictly better, and `bg-background` is+already the right light/dark value because the pre-hydration script in `app/layout.tsx`+sets `data-theme` before first paint. Nothing is lost to SEO: the catch-all is fully+dynamic and auth-gated, and the shell was never usable without JS.++**The measured cost, stated plainly: mobile LCP 160 ms → 320 ms**, because the shell is no+longer painted from SSR. Desktop LCP 380 → 420 ms. Both remain far under the 2500 ms+"good" threshold, and desktop CLS improved 0.008 → 0.001. The old 160 ms was painting a+shell that was then thrown away and rebuilt, so it was never a real 160 ms to the content+the user wanted.++**Verified end to end on the production build:** hydration clean on desktop and mobile,+**0 JS errors across all 17 apps in both mobile shells** (was 17/17 erroring), 17/17 still+render, shell resolution still correct (390 → ios, 412 → ios, 1280 → macos), no horizontal+overflow, skip link and its `#main-content` target both intact, smoke 4/4. Mobile+sub-24 px touch targets are down to one — the `sr-only` skip link, which is 1×1 by design.+## 2026-08-04 (hydration + mobile polish) — three of four hydration mismatches killed (DONE)Chasing React #418, which had been firing on every page load and every app. A hydrationdiff --git a/frontend/slices/appshell/components/desktop.tsx b/frontend/slices/appshell/components/desktop.tsxindex a38f3d72..8a36ff52 100644--- a/frontend/slices/appshell/components/desktop.tsx+++ b/frontend/slices/appshell/components/desktop.tsx@@ -46,6 +46,12 @@ export function OsDesktop() {function Surface() {const r = useResponsive();const prefs = useShellPrefs();+ // False on the server AND on the first client render, true from the first effect+ // onwards — so the server HTML and the tree React hydrates are identical by+ // construction. See the note above the early return below.+ const [mounted, setMounted] = useState(false);+ // eslint-disable-next-line react-hooks/set-state-in-effect -- one-shot post-hydration flip, the same pattern lib/appearance/store.tsx and lib/quicklinks/store.tsx use. A lazy initializer cannot work here: the whole point is that the FIRST render must match the server, and only the effect (which never runs on the server) may flip it.+ useEffect(() => setMounted(true), []);// The live form factor picks the surface; the user's per-surface preference// picks WHICH shell renders there (desktop look vs mobile look, chosen@@ -64,6 +70,30 @@ function Surface() {useWindowSnapKeys(!!desc.windowed);const framed = surface === "mobile" && r.vw >= 768;+ // The shell renders ONLY after mount, and this is a correctness fix, not caution.+ // Which shell to draw depends on three things the server cannot know: the viewport+ // (`useResponsive` measures `window.innerWidth`), the persisted per-surface shell+ // choice (localStorage `sv:shell`) and the wallpaper preference. So SSR always+ // guessed desktop/macOS, and on a phone the client then rendered iOS instead — two+ // different trees, which is a guaranteed hydration mismatch. React responded by+ // throwing away the hydrated tree and re-rendering the whole shell on the client,+ // and because Radix derives ids from `useId`, the divergence surfaced as mismatched+ // DropdownMenuTrigger ids in the dev overlay.+ //+ // This is also a UX improvement, not a trade: the old behaviour PAINTED the macOS+ // desktop on a phone and then swapped it for iOS. A brief flash of the themed+ // background is strictly better than a flash of the wrong operating system.+ // Nothing is lost to SEO — the catch-all is fully dynamic and auth-gated, and the+ // shell was never usable without JS anyway.+ //+ // #main-content and the sizing stay in the skeleton so the skip link keeps a target+ // and the layout does not jump. `bg-background` is already the correct light/dark+ // value here: the pre-hydration script in app/layout.tsx sets data-theme before+ // first paint.+ if (!mounted) {+ return <div id="main-content" className="relative h-dvh w-screen overflow-hidden bg-background" />;+ }+return (<ActiveShellProvider id={desc.id} surface={surface}><div id="main-content" data-shell={desc.id} className="relative h-dvh w-screen overflow-hidden">