Skip to content

armgit / mso

Public Imported from GitHub
0

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.

fix(hydration): render the shell after mount — zero mismatches anywhere

Rahman615ebdd54247
diff --git a/docs/PROGRESS.md b/docs/PROGRESS.md
index 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 hydration
diff --git a/frontend/slices/appshell/components/desktop.tsx b/frontend/slices/appshell/components/desktop.tsx
index 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">