refactor: migrate filter persistence from localStorage to cookies

Fixes hydration timing issue where sidebar Issues link had stale href.

Changes:
- Add cookie utilities (src/lib/cookies/preferences.ts, client.ts)
- MainLayout reads cookies server-side and passes to Sidebar as props
- Sidebar accepts issuesPath and initialCollapsed as props
- BackToIssuesLink accepts href prop instead of using hook
- use-search-filters sets cookie client-side (synchronous)
- Remove use-issue-link.ts hook (replaced by cookie approach)

Benefits:
- No hydration mismatch (server and client render same values)
- No race conditions (client-side cookie set is synchronous)
- Sidebar collapsed state also migrated to cookies

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

Author: timothyfroehlich

e2e/smoke/issue-list.spec.ts

@@ -297,7 +297,7 @@ test.describe("Issue List Features", () => {
       await page.getByTestId("mobile-menu-trigger").click();
     }
 
-    // The sidebar link uses useIssueLink which reads from localStorage
+    // The sidebar link uses issuesPath prop read from cookie on the server
     await page.getByRole("link", { name: "Issues", exact: true }).click();
     await expect(page).toHaveURL(/q=Thing/);
 

src/app/(app)/m/[initials]/i/[issueNumber]/page.tsx

@@ -14,6 +14,7 @@ import { formatIssueId } from "~/lib/issues/utils";
 import { ImageGallery } from "~/components/images/ImageGallery";
 import type { Issue, IssueWithAllRelations } from "~/lib/types";
 import { BackToIssuesLink } from "~/components/issues/BackToIssuesLink";
+import { getLastIssuesPath } from "~/lib/cookies/preferences";
 
 /**
  * Issue Detail Page (Protected Route)
@@ -28,6 +29,9 @@ export default async function IssueDetailPage({
   // Get params (Next.js 16: params is a Promise)
   const { initials, issueNumber } = await params;
 
+  // Read user preferences from cookies
+  const issuesPath = await getLastIssuesPath();
+
   // Auth guard
   const supabase = await createClient();
   const {
@@ -160,7 +164,7 @@ export default async function IssueDetailPage({
   return (
     <PageShell className="space-y-8" size="wide">
       {/* Back button */}
-      <BackToIssuesLink />
+      <BackToIssuesLink href={issuesPath} />
 
       {/* Header */}
       <div className="space-y-3">

src/components/issues/BackToIssuesLink.tsx

@@ -1,13 +1,15 @@
-"use client";
-
 import type React from "react";
 import Link from "next/link";
 import { ArrowLeft } from "lucide-react";
-import { useIssueLink } from "~/hooks/use-issue-link";
 
-export function BackToIssuesLink(): React.JSX.Element {
-  const href = useIssueLink();
+interface BackToIssuesLinkProps {
+  /** The href to navigate to, typically read from cookie on the server */
+  href?: string;
+}
 
+export function BackToIssuesLink({
+  href = "/issues",
+}: BackToIssuesLinkProps): React.JSX.Element {
   return (
     <Link
       href={href}

src/components/layout/MainLayout.tsx

@@ -19,12 +19,22 @@ import Link from "next/link";
 import { Button } from "~/components/ui/button";
 import { MobileNav } from "./MobileNav";
 import { FeedbackWidget } from "~/components/feedback/FeedbackWidget";
+import {
+  getLastIssuesPath,
+  getSidebarCollapsed,
+} from "~/lib/cookies/preferences";
 
 export async function MainLayout({
   children,
 }: {
   children: React.ReactNode;
 }): Promise<React.JSX.Element> {
+  // Read user preferences from cookies (server-side)
+  const [issuesPath, sidebarCollapsed] = await Promise.all([
+    getLastIssuesPath(),
+    getSidebarCollapsed(),
+  ]);
+
   const supabase = await createClient();
   const {
     data: { user },
@@ -109,7 +119,11 @@ export async function MainLayout({
     <div className="flex h-full bg-background text-foreground">
       {/* Sidebar - Hidden on mobile */}
       <aside className="hidden md:block h-full">
-        <Sidebar role={userProfile?.role} />
+        <Sidebar
+          role={userProfile?.role}
+          issuesPath={issuesPath}
+          initialCollapsed={sidebarCollapsed}
+        />
       </aside>
 
       {/* Main Content */}
@@ -119,7 +133,7 @@ export async function MainLayout({
           {/* Mobile Menu Trigger & Left Spacer */}
           <div className="flex-1 flex items-center">
             <div className="md:hidden mr-4">
-              <MobileNav role={userProfile?.role} />
+              <MobileNav role={userProfile?.role} issuesPath={issuesPath} />
             </div>
           </div>
 

src/components/layout/MobileNav.tsx

@@ -15,8 +15,10 @@ import {
 
 export function MobileNav({
   role,
+  issuesPath,
 }: {
   role?: "guest" | "member" | "admin" | undefined;
+  issuesPath?: string;
 }): React.JSX.Element {
   const [open, setOpen] = useState(false);
 
@@ -44,6 +46,7 @@ export function MobileNav({
           role={role}
           onNavigate={() => setOpen(false)}
           isMobile={true}
+          issuesPath={issuesPath}
         />
       </SheetContent>
     </Sheet>

src/components/layout/Sidebar.test.tsx

@@ -1,7 +1,7 @@
 import React from "react";
 import { render, screen } from "@testing-library/react";
 import userEvent from "@testing-library/user-event";
-import { describe, it, expect, vi, beforeEach } from "vitest";
+import { describe, it, expect, vi } from "vitest";
 import { Sidebar } from "./Sidebar";
 
 // Mock dependencies
@@ -23,11 +23,12 @@ vi.mock("next/image", () => ({
   ),
 }));
 
-describe("Sidebar Accessibility", () => {
-  beforeEach(() => {
-    window.localStorage.clear();
-  });
+// Mock client-side cookie storage
+vi.mock("~/lib/cookies/client", () => ({
+  storeSidebarCollapsed: vi.fn(),
+}));
 
+describe("Sidebar Accessibility", () => {
   it("provides accessible names for links when collapsed", async () => {
     const user = userEvent.setup();
     render(<Sidebar />);

src/components/layout/Sidebar.tsx

@@ -1,11 +1,11 @@
 "use client";
 
 import type React from "react";
-import { useState, useEffect } from "react";
+import { useState } from "react";
 import Link from "next/link";
 import Image from "next/image";
-import { useIssueLink } from "~/hooks/use-issue-link";
 import { usePathname } from "next/navigation";
+import { storeSidebarCollapsed } from "~/lib/cookies/client";
 import {
   LayoutDashboard,
   Gamepad2,
@@ -47,27 +47,27 @@ export function Sidebar({
   role,
   onNavigate,
   isMobile = false,
+  issuesPath,
+  initialCollapsed = false,
 }: {
   role?: "guest" | "member" | "admin" | undefined;
   onNavigate?: () => void;
   isMobile?: boolean;
+  /** The issues link path, read from cookie on the server */
+  issuesPath?: string | undefined;
+  /** Initial collapsed state, read from cookie on the server */
+  initialCollapsed?: boolean;
 }): React.JSX.Element {
-  const [collapsed, setCollapsed] = useState(false);
+  const [collapsed, setCollapsed] = useState(initialCollapsed);
   const pathname = usePathname();
-  const issuesLink = useIssueLink();
-  // Load state from localStorage on mount
-  useEffect(() => {
-    if (isMobile) return; // Don't load/save collapse state on mobile
-    const savedState = window.localStorage.getItem("sidebar-collapsed");
-    if (savedState) {
-      setCollapsed(JSON.parse(savedState) as boolean);
-    }
-  }, [isMobile]);
+  // Default to /issues if no path provided
+  const resolvedIssuesPath = issuesPath ?? "/issues";
 
   const toggleSidebar = (): void => {
     const newState = !collapsed;
     setCollapsed(newState);
-    window.localStorage.setItem("sidebar-collapsed", JSON.stringify(newState));
+    // Persist to cookie synchronously
+    storeSidebarCollapsed(newState);
   };
 
   const NavItem = ({
@@ -80,7 +80,7 @@ export function Sidebar({
       variant?: string;
     };
   }): React.JSX.Element => {
-    const href = item.href === "/issues" ? issuesLink : item.href;
+    const href = item.href === "/issues" ? resolvedIssuesPath : item.href;
     const hrefPath = href.split("?")[0];
     const isActive = pathname === hrefPath;
     const isReport = item.variant === "accent";

src/hooks/use-issue-link.ts

@@ -4,7 +4,7 @@ import { useRouter, usePathname } from "next/navigation";
 import { useCallback, useRef, useEffect } from "react";
 import type { IssueFilters } from "~/lib/issues/filters";
 import type { MachineFilters } from "~/lib/machines/filters";
-import { storeLastIssuesPath } from "~/hooks/use-issue-link";
+import { storeLastIssuesPath } from "~/lib/cookies/client";
 
 type GenericFilters = IssueFilters | MachineFilters;
 
@@ -156,6 +156,7 @@ export function useSearchFilters<T extends GenericFilters>(
 
       const newPath = `${pathname}?${params.toString()}`;
       if (pathname.startsWith("/issues")) {
+        // Set cookie synchronously so it's available on next navigation
         storeLastIssuesPath(newPath);
       }
       router.push(newPath);

src/hooks/use-search-filters.ts

@@ -0,0 +1,32 @@
+"use client";
+
+const LAST_ISSUES_PATH_KEY = "lastIssuesPath";
+const SIDEBAR_COLLAPSED_KEY = "sidebarCollapsed";
+
+/**
+ * Sets a cookie on the client side (synchronous).
+ * The cookie will be immediately available for the next server request.
+ */
+function setClientCookie(name: string, value: string, maxAge: number): void {
+  const secure =
+    typeof window !== "undefined" && window.location.protocol === "https:";
+  document.cookie = `${name}=${encodeURIComponent(value)}; path=/; max-age=${maxAge}; SameSite=Lax${secure ? "; Secure" : ""}`;
+}
+
+/**
+ * Stores the last issues path in a cookie (client-side, synchronous).
+ * This is faster than a server action and ensures the cookie is
+ * available immediately for the next navigation.
+ */
+export function storeLastIssuesPath(path: string): void {
+  const maxAge = 60 * 60 * 24 * 365; // 1 year
+  setClientCookie(LAST_ISSUES_PATH_KEY, path, maxAge);
+}
+
+/**
+ * Stores the sidebar collapsed state in a cookie (client-side, synchronous).
+ */
+export function storeSidebarCollapsed(collapsed: boolean): void {
+  const maxAge = 60 * 60 * 24 * 365; // 1 year
+  setClientCookie(SIDEBAR_COLLAPSED_KEY, collapsed.toString(), maxAge);
+}