fix!: remove useLocationSSR hook

packages/docs/src/pages/ApiHooksPage.tsx

@@ -48,44 +48,6 @@ function MyComponent() {
 }`}</CodeBlock>
       </article>
 
-      <article className="api-item">
-        <h3>
-          <code>useLocationSSR()</code>
-        </h3>
-        <p>
-          Returns the current location object, or <code>null</code> when the URL
-          is not available (e.g. during SSR). This is the SSR-safe alternative
-          to <code>useLocation()</code>.
-        </p>
-        <CodeBlock language="tsx">{`import { useLocationSSR } from "@funstack/router";
-
-function AppShell() {
-  const location = useLocationSSR();
-
-  // location is null during SSR, Location object after hydration
-  const isActive = (path: string) => {
-    if (location === null) return false;
-    return location.pathname === path;
-  };
-
-  return (
-    <nav>
-      <a className={isActive("/") ? "active" : ""} href="/">Home</a>
-      <a className={isActive("/about") ? "active" : ""} href="/about">About</a>
-    </nav>
-  );
-}`}</CodeBlock>
-        <h4>Return Value</h4>
-        <ul>
-          <li>
-            <code>Location | null</code> &mdash; The current location object
-            with <code>pathname</code>, <code>search</code>, and{" "}
-            <code>hash</code> properties, or <code>null</code> during SSR when
-            no URL is available.
-          </li>
-        </ul>
-      </article>
-
       <article className="api-item">
         <h3>
           <code>useSearchParams()</code>

packages/docs/src/pages/ApiReferenceIndexPage.tsx

@@ -37,10 +37,6 @@ export function ApiReferenceIndexPage() {
           <li>
             <code>useLocation()</code> — Current location object
           </li>
-          <li>
-            <code>useLocationSSR()</code> — SSR-safe current location (returns{" "}
-            <code>null</code> during SSR)
-          </li>
           <li>
             <code>useSearchParams()</code> — Search query management
           </li>

packages/docs/src/pages/LearnSsrPage.tsx

@@ -91,23 +91,31 @@ useSearchParams();
 // Error: "useSearchParams: URL is not available during SSR."`}</CodeBlock>
         <p>
           To avoid these errors, either use URL-dependent hooks only in
-          components rendered by path-based routes, or use the SSR-safe{" "}
-          <code>useLocationSSR()</code> hook which returns <code>null</code>{" "}
-          instead of throwing when the URL is unavailable:
+          components rendered by path-based routes, or read the current path
+          inside a client-side effect (e.g., <code>useLayoutEffect</code> +{" "}
+          <code>navigation.currentEntry</code>) so the value is only accessed
+          after hydration:
         </p>
         <CodeBlock language="tsx">{`// ✗ Bad: AppShell renders during SSR, useLocation will throw
 function AppShell() {
   const location = useLocation(); // Throws during SSR!
   return <div>{/* ... */}</div>;
 }
 
-// ✓ Good: Use useLocationSSR in components that render during SSR
+// ✓ Good: Read the path in a client-side effect
+function useCurrentPath() {
+  const [path, setPath] = useState<string | undefined>(undefined);
+  useLayoutEffect(() => {
+    setPath(navigation.currentEntry?.url
+      ? new URL(navigation.currentEntry.url).pathname
+      : undefined);
+  }, []);
+  return path;
+}
+
 function AppShell() {
-  const location = useLocationSSR(); // Returns null during SSR
-  const isActive = (path: string) => {
-    if (location === null) return false;
-    return location.pathname === path;
-  };
+  const path = useCurrentPath(); // undefined during SSR, string after hydration
+  const isActive = (p: string) => path === p;
   return <nav>{/* ... */}</nav>;
 }
 
@@ -159,8 +167,9 @@ function HomePage() {
           </li>
           <li>
             Avoid <code>useLocation</code> and <code>useSearchParams</code> in
-            components that render during SSR; use <code>useLocationSSR</code>{" "}
-            instead when you need location information in the app shell
+            components that render during SSR; use a client-side effect (e.g.,{" "}
+            <code>useLayoutEffect</code>) to read location information in the
+            app shell
           </li>
           <li>
             This two-stage model keeps SSR output lightweight while enabling

packages/router/src/__tests__/hooks.test.tsx

@@ -4,11 +4,9 @@ import { Suspense, type ReactNode } from "react";
 import { Router } from "../Router.js";
 import { useNavigate } from "../hooks/useNavigate.js";
 import { useLocation } from "../hooks/useLocation.js";
-import { useLocationSSR } from "../hooks/useLocationSSR.js";
 import { useSearchParams } from "../hooks/useSearchParams.js";
 import { useIsPending } from "../hooks/useIsPending.js";
 import { setupNavigationMock, cleanupNavigationMock } from "./setup.js";
-import { RouterContext } from "../context/RouterContext.js";
 import type { RouteDefinition } from "../route.js";
 
 describe("hooks", () => {
@@ -133,72 +131,6 @@ describe("hooks", () => {
     });
   });
 
-  describe("useLocationSSR", () => {
-    it("returns current location when URL is available", () => {
-      mockNavigation = setupNavigationMock(
-        "http://localhost/page?foo=bar#section",
-      );
-
-      function TestComponent() {
-        const location = useLocationSSR();
-        return (
-          <div>
-            <span data-testid="pathname">{location?.pathname}</span>
-            <span data-testid="search">{location?.search}</span>
-            <span data-testid="hash">{location?.hash}</span>
-          </div>
-        );
-      }
-
-      const routes: RouteDefinition[] = [
-        { path: "/page", component: TestComponent },
-      ];
-
-      render(<Router routes={routes} />);
-
-      expect(screen.getByTestId("pathname").textContent).toBe("/page");
-      expect(screen.getByTestId("search").textContent).toBe("?foo=bar");
-      expect(screen.getByTestId("hash").textContent).toBe("#section");
-    });
-
-    it("returns null during SSR (url is null)", () => {
-      let capturedLocation: ReturnType<typeof useLocationSSR> | undefined;
-
-      function TestComponent() {
-        capturedLocation = useLocationSSR();
-        return <div>test</div>;
-      }
-
-      const ssrContextValue = {
-        locationEntry: null,
-        url: null,
-        isPending: false,
-        navigate: () => {},
-        navigateAsync: async () => {},
-        updateCurrentEntryState: () => {},
-      };
-
-      render(
-        <RouterContext.Provider value={ssrContextValue}>
-          <TestComponent />
-        </RouterContext.Provider>,
-      );
-
-      expect(capturedLocation).toBeNull();
-    });
-
-    it("throws when used outside Router", () => {
-      function TestComponent() {
-        useLocationSSR();
-        return null;
-      }
-
-      expect(() => render(<TestComponent />)).toThrow(
-        "useLocationSSR must be used within a Router",
-      );
-    });
-  });
-
   describe("useSearchParams", () => {
     it("returns current search params", () => {
       mockNavigation = setupNavigationMock(

packages/router/src/index.ts

@@ -9,7 +9,6 @@ export { Outlet } from "./Outlet.js";
 // Hooks
 export { useNavigate } from "./hooks/useNavigate.js";
 export { useLocation } from "./hooks/useLocation.js";
-export { useLocationSSR } from "./hooks/useLocationSSR.js";
 export { useSearchParams } from "./hooks/useSearchParams.js";
 export { useBlocker, type UseBlockerOptions } from "./hooks/useBlocker.js";
 export { useRouteParams } from "./hooks/useRouteParams.js";