Merge pull request #6934 from shin-core/fix/install-tab-ssr-hydration-6814-v3

fix(ui): defer homepage install-tab localStorage read past hydration

Author: JSONbored

apps/loopover-ui/src/routes/index.test.tsx

@@ -1,4 +1,5 @@
-import { render, screen, fireEvent } from "@testing-library/react";
+import { render, screen, fireEvent, waitFor } from "@testing-library/react";
+import { renderToString } from "react-dom/server";
 import { beforeEach, describe, expect, it } from "vitest";
 
 import { ClientSetupTabs } from "./index";
@@ -8,9 +9,9 @@ import { ClientSetupTabs } from "./index";
 // the shared Radix-backed Tabs primitive. This is the regression test for that gap.
 
 describe("ClientSetupTabs keyboard navigation (#6813)", () => {
-  // ClientSetupTabs persists the active tab to localStorage ("gt:install-tab") and reads it back as the
-  // initial state on mount -- without clearing it, a later test's initial "miners" tab assumption breaks
-  // because an earlier test in this file left a different tab persisted.
+  // ClientSetupTabs persists the active tab to localStorage ("gt:install-tab") and reads it back on mount
+  // -- without clearing it, a later test's initial "miners" tab assumption breaks because an earlier test
+  // in this file left a different tab persisted.
   beforeEach(() => {
     window.localStorage.clear();
   });
@@ -100,3 +101,69 @@ describe("ClientSetupTabs keyboard navigation (#6813)", () => {
     expect(codexTab.getAttribute("aria-selected")).toBe("true");
   });
 });
+
+const STORAGE_KEY = "gt:install-tab";
+
+function selectedTabName(): string | null {
+  return screen.getByRole("tab", { selected: true }).textContent;
+}
+
+describe("ClientSetupTabs SSR-safe hydration (#6814)", () => {
+  beforeEach(() => {
+    window.localStorage.clear();
+  });
+
+  it("renders the same markup with or without a saved tab, so hydration cannot mismatch", () => {
+    // The invariant. The server has no `window` and always emits "miners"; the client's first render must
+    // agree. Reading localStorage in a useState initializer broke that for a returning visitor, because the
+    // initializer ran during the very first render. renderToString is the only way to observe that first
+    // paint -- testing-library's render() wraps in act(), which flushes the mount effect before any
+    // assertion can see the pre-effect markup.
+    const withoutSaved = renderToString(<ClientSetupTabs />);
+    window.localStorage.setItem(STORAGE_KEY, JSON.stringify("cursor"));
+    const withSaved = renderToString(<ClientSetupTabs />);
+
+    expect(withSaved).toBe(withoutSaved);
+    expect(withSaved).toContain('aria-selected="true"');
+  });
+
+  it("applies the saved tab after mount, once hydration is safely past", async () => {
+    window.localStorage.setItem(STORAGE_KEY, JSON.stringify("cursor"));
+    render(<ClientSetupTabs />);
+
+    await waitFor(() => expect(selectedTabName()).toContain("Cursor"));
+  });
+
+  it("stays on the default tab when nothing is saved", async () => {
+    render(<ClientSetupTabs />);
+
+    expect(selectedTabName()).toContain("Miner CLI");
+    // Give the mount-time read a chance to land before asserting it changed nothing.
+    await waitFor(() => expect(selectedTabName()).toContain("Miner CLI"));
+  });
+
+  it("persists a clicked tab so the next visit restores it", async () => {
+    render(<ClientSetupTabs />);
+
+    fireEvent.click(screen.getByRole("tab", { name: /Claude Desktop/i }));
+
+    await waitFor(() => expect(selectedTabName()).toContain("Claude Desktop"));
+    expect(window.localStorage.getItem(STORAGE_KEY)).toBe(JSON.stringify("claude"));
+  });
+
+  it("falls back to the default when the stored value is unreadable", async () => {
+    // Pre-#6814 the tab was written as a bare string. "cursor" is not valid JSON, so the hook's read throws
+    // and the component degrades to the default -- a one-time reset for a returning visitor rather than a
+    // broken tab. Deliberately a NON-default value: storing "miners" here would pass even if the fallback
+    // were broken.
+    window.localStorage.setItem(STORAGE_KEY, "cursor");
+    render(<ClientSetupTabs />);
+
+    await waitFor(() => expect(selectedTabName()).toContain("Miner CLI"));
+    // And the reset is self-healing: the next write lands in the hook's JSON format.
+    fireEvent.click(screen.getByRole("tab", { name: /Codex/i }));
+    await waitFor(() =>
+      expect(window.localStorage.getItem(STORAGE_KEY)).toBe(JSON.stringify("codex")),
+    );
+  });
+});

apps/loopover-ui/src/routes/index.tsx

@@ -3,6 +3,7 @@ import { useEffect, useRef, useState, type KeyboardEvent } from "react";
 import { Check, Copy } from "lucide-react";
 import { toast } from "sonner";
 
+import { useLocalStorage } from "@/lib/use-local-storage";
 import { cn } from "@/lib/utils";
 
 import { AnimatedTerminal } from "@/components/site/animated-terminal";
@@ -442,6 +443,8 @@ loopover-mcp analyze-branch --login your-login --json`}
 
 type ClientTabId = "miners" | "codex" | "claude" | "cursor" | "remote";
 
+const INSTALL_TAB_STORAGE_KEY = "gt:install-tab";
+
 const CLIENT_TABS: Array<{
   id: ClientTabId;
   label: string;
@@ -511,10 +514,11 @@ args = ["-y", "@loopover/mcp@latest", "--stdio"]`,
 ];
 
 export function ClientSetupTabs() {
-  const [active, setActive] = useState<ClientTabId>(() => {
-    if (typeof window === "undefined") return "miners";
-    return (window.localStorage.getItem("gt:install-tab") as ClientTabId) ?? "miners";
-  });
+  // Deferred read via useLocalStorage (#6814): a useState initializer runs during the FIRST render, but the
+  // server render has no `window` and always yields "miners", so a returning visitor with a saved tab
+  // hydrated into markup the server never produced. The hook reads on mount instead and persists on write,
+  // which also replaces the write-back effect this component used to run.
+  const [active, setActive] = useLocalStorage<ClientTabId>(INSTALL_TAB_STORAGE_KEY, "miners");
   const [copied, setCopied] = useState(false);
   const current = CLIENT_TABS.find((t) => t.id === active) ?? CLIENT_TABS[0];
   const tabRefs = useRef<Map<string, HTMLButtonElement>>(new Map());
@@ -543,14 +547,6 @@ export function ClientSetupTabs() {
     }
   };
 
-  useEffect(() => {
-    try {
-      window.localStorage.setItem("gt:install-tab", active);
-    } catch {
-      /* noop */
-    }
-  }, [active]);
-
   const onCopy = async () => {
     try {
       await navigator.clipboard.writeText(current.snippet);