hadars 0.1.34 → 0.1.35

package/README.md

@@ -116,8 +116,9 @@ const UserCard = ({ userId }: { userId: string }) => {
 ```
 
 - **`key`** - string or string array; must be stable and unique within the page
-- **Server** - calls `fn()`, awaits the result across render iterations, returns `undefined` until resolved
-- **Client** - reads the pre-resolved value from the hydration cache serialised by the server; `fn()` is never called in the browser
+- **Server (SSR)** - calls `fn()`, awaits the result across render iterations, returns `undefined` until resolved
+- **Client (hydration)** - reads the pre-resolved value from the hydration cache serialised by the server; `fn()` is never called in the browser
+- **Client (navigation)** - when a component mounts during client-side navigation and its key is not in the cache, hadars fires a single `GET <current-url>` with `Accept: application/json`; all `useServerData` calls within the same render are batched into one request and suspended via React Suspense until the server returns the JSON data map
 
 ## Data lifecycle hooks
 

package/dist/cli.js

@@ -2208,6 +2208,13 @@ var dev = async (options) => {
           getFinalProps
         }
       });
+      if (request.headers.get("Accept") === "application/json") {
+        const serverData = clientProps.__serverData ?? {};
+        return new Response(JSON.stringify({ serverData }), {
+          status,
+          headers: { "Content-Type": "application/json; charset=utf-8" }
+        });
+      }
       return buildSsrResponse(bodyHtml, clientProps, headHtml, status, getPrecontentHtml);
     } catch (err) {
       console.error("[hadars] SSR render error:", err);
@@ -2344,7 +2351,7 @@ var run = async (options) => {
         getAfterRenderProps,
         getFinalProps
       } = await import(componentPath);
-      if (renderPool) {
+      if (renderPool && request.headers.get("Accept") !== "application/json") {
         const serialReq = await serializeRequest(request);
         const { html, headHtml: wHead, status: wStatus } = await renderPool.renderFull(serialReq);
         const [precontentHtml, postContent] = await getPrecontentHtml(wHead);
@@ -2362,6 +2369,13 @@ var run = async (options) => {
           getFinalProps
         }
       });
+      if (request.headers.get("Accept") === "application/json") {
+        const serverData = clientProps.__serverData ?? {};
+        return new Response(JSON.stringify({ serverData }), {
+          status,
+          headers: { "Content-Type": "application/json; charset=utf-8" }
+        });
+      }
       return buildSsrResponse(bodyHtml, clientProps, headHtml, status, getPrecontentHtml);
     } catch (err) {
       console.error("[hadars] SSR render error:", err);

package/dist/index.cjs

@@ -174,22 +174,98 @@ var AppProviderCSR = import_react.default.memo(({ children }) => {
 });
 var useApp = () => import_react.default.useContext(AppContext);
 var clientServerDataCache = /* @__PURE__ */ new Map();
+var pendingDataFetch = /* @__PURE__ */ new Map();
+var fetchedPaths = /* @__PURE__ */ new Set();
+var ssrInitialKeys = null;
+var unclaimedKeyCheckScheduled = false;
+function scheduleUnclaimedKeyCheck() {
+  if (unclaimedKeyCheckScheduled)
+    return;
+  unclaimedKeyCheckScheduled = true;
+  setTimeout(() => {
+    unclaimedKeyCheckScheduled = false;
+    if (ssrInitialKeys && ssrInitialKeys.size > 0) {
+      console.warn(
+        `[hadars] useServerData: ${ssrInitialKeys.size} server-resolved key(s) were never claimed during client hydration: ${[...ssrInitialKeys].map((k) => JSON.stringify(k)).join(", ")}. This usually means the key passed to useServerData was different on the server than on the client (e.g. it contains Date.now(), Math.random(), or another value that changes between renders). Keys must be stable and deterministic.`
+      );
+    }
+    ssrInitialKeys = null;
+  }, 0);
+}
 function initServerDataCache(data) {
   clientServerDataCache.clear();
+  ssrInitialKeys = /* @__PURE__ */ new Set();
   for (const [k, v] of Object.entries(data)) {
     clientServerDataCache.set(k, v);
+    ssrInitialKeys.add(k);
   }
 }
 function useServerData(key, fn) {
   const cacheKey = Array.isArray(key) ? JSON.stringify(key) : key;
   if (typeof window !== "undefined") {
-    return clientServerDataCache.get(cacheKey);
+    if (clientServerDataCache.has(cacheKey)) {
+      ssrInitialKeys?.delete(cacheKey);
+      return clientServerDataCache.get(cacheKey);
+    }
+    if (ssrInitialKeys !== null && ssrInitialKeys.size > 0) {
+      scheduleUnclaimedKeyCheck();
+    }
+    const pathKey = window.location.pathname + window.location.search;
+    if (fetchedPaths.has(pathKey)) {
+      return void 0;
+    }
+    if (!pendingDataFetch.has(pathKey)) {
+      let resolve;
+      const p = new Promise((res) => {
+        resolve = res;
+      });
+      pendingDataFetch.set(pathKey, p);
+      queueMicrotask(async () => {
+        try {
+          const res = await fetch(pathKey, {
+            headers: { "Accept": "application/json" }
+          });
+          if (res.ok) {
+            const json = await res.json();
+            for (const [k, v] of Object.entries(json.serverData ?? {})) {
+              clientServerDataCache.set(k, v);
+            }
+          }
+        } finally {
+          fetchedPaths.add(pathKey);
+          pendingDataFetch.delete(pathKey);
+          resolve();
+        }
+      });
+    }
+    throw pendingDataFetch.get(pathKey);
   }
   const unsuspend = globalThis.__hadarsUnsuspend;
   if (!unsuspend)
     return void 0;
+  const _u = unsuspend;
+  if (!_u.seenThisPass)
+    _u.seenThisPass = /* @__PURE__ */ new Set();
+  if (!_u.seenLastPass)
+    _u.seenLastPass = /* @__PURE__ */ new Set();
+  if (_u.newPassStarting) {
+    _u.seenLastPass = new Set(_u.seenThisPass);
+    _u.seenThisPass.clear();
+    _u.newPassStarting = false;
+  }
+  _u.seenThisPass.add(cacheKey);
   const existing = unsuspend.cache.get(cacheKey);
   if (!existing) {
+    if (_u.seenLastPass.size > 0) {
+      const hasVanishedKey = [..._u.seenLastPass].some(
+        (k) => !_u.seenThisPass.has(k)
+      );
+      if (hasVanishedKey) {
+        throw new Error(
+          `[hadars] useServerData: key ${JSON.stringify(cacheKey)} appeared in this pass but a key that was present in the previous pass is now missing. This means the key is not stable across render passes (e.g. it contains Date.now(), Math.random(), or a value that changes on every render). Keys must be deterministic.`
+        );
+      }
+    }
     const result = fn();
     const isThenable = result !== null && typeof result === "object" && typeof result.then === "function";
     if (!isThenable) {
@@ -206,9 +282,11 @@ function useServerData(key, fn) {
       }
     );
     unsuspend.cache.set(cacheKey, { status: "pending", promise });
+    _u.newPassStarting = true;
     throw promise;
   }
   if (existing.status === "pending") {
+    _u.newPassStarting = true;
     throw existing.promise;
   }
   if (existing.status === "rejected")

package/dist/index.d.ts

@@ -195,7 +195,10 @@ declare function initServerDataCache(data: Record<string, unknown>): void;
  * The resolved value is serialised into `__serverData` and returned from cache
  * during hydration.
  *
- * `fn` is **server-only**: it is never called in the browser.
+ * `fn` is **server-only**: it is never called in the browser. On client-side
+ * navigation (after the initial SSR load), hadars automatically fires a
+ * data-only request to the current URL (`X-Hadars-Data: 1`) and suspends via
+ * React Suspense until the server returns the JSON map of resolved values.
  *
  * @example
  * const user = useServerData('current_user', () => db.getUser(id));

package/dist/index.js

@@ -131,22 +131,98 @@ var AppProviderCSR = React.memo(({ children }) => {
 });
 var useApp = () => React.useContext(AppContext);
 var clientServerDataCache = /* @__PURE__ */ new Map();
+var pendingDataFetch = /* @__PURE__ */ new Map();
+var fetchedPaths = /* @__PURE__ */ new Set();
+var ssrInitialKeys = null;
+var unclaimedKeyCheckScheduled = false;
+function scheduleUnclaimedKeyCheck() {
+  if (unclaimedKeyCheckScheduled)
+    return;
+  unclaimedKeyCheckScheduled = true;
+  setTimeout(() => {
+    unclaimedKeyCheckScheduled = false;
+    if (ssrInitialKeys && ssrInitialKeys.size > 0) {
+      console.warn(
+        `[hadars] useServerData: ${ssrInitialKeys.size} server-resolved key(s) were never claimed during client hydration: ${[...ssrInitialKeys].map((k) => JSON.stringify(k)).join(", ")}. This usually means the key passed to useServerData was different on the server than on the client (e.g. it contains Date.now(), Math.random(), or another value that changes between renders). Keys must be stable and deterministic.`
+      );
+    }
+    ssrInitialKeys = null;
+  }, 0);
+}
 function initServerDataCache(data) {
   clientServerDataCache.clear();
+  ssrInitialKeys = /* @__PURE__ */ new Set();
   for (const [k, v] of Object.entries(data)) {
     clientServerDataCache.set(k, v);
+    ssrInitialKeys.add(k);
   }
 }
 function useServerData(key, fn) {
   const cacheKey = Array.isArray(key) ? JSON.stringify(key) : key;
   if (typeof window !== "undefined") {
-    return clientServerDataCache.get(cacheKey);
+    if (clientServerDataCache.has(cacheKey)) {
+      ssrInitialKeys?.delete(cacheKey);
+      return clientServerDataCache.get(cacheKey);
+    }
+    if (ssrInitialKeys !== null && ssrInitialKeys.size > 0) {
+      scheduleUnclaimedKeyCheck();
+    }
+    const pathKey = window.location.pathname + window.location.search;
+    if (fetchedPaths.has(pathKey)) {
+      return void 0;
+    }
+    if (!pendingDataFetch.has(pathKey)) {
+      let resolve;
+      const p = new Promise((res) => {
+        resolve = res;
+      });
+      pendingDataFetch.set(pathKey, p);
+      queueMicrotask(async () => {
+        try {
+          const res = await fetch(pathKey, {
+            headers: { "Accept": "application/json" }
+          });
+          if (res.ok) {
+            const json = await res.json();
+            for (const [k, v] of Object.entries(json.serverData ?? {})) {
+              clientServerDataCache.set(k, v);
+            }
+          }
+        } finally {
+          fetchedPaths.add(pathKey);
+          pendingDataFetch.delete(pathKey);
+          resolve();
+        }
+      });
+    }
+    throw pendingDataFetch.get(pathKey);
   }
   const unsuspend = globalThis.__hadarsUnsuspend;
   if (!unsuspend)
     return void 0;
+  const _u = unsuspend;
+  if (!_u.seenThisPass)
+    _u.seenThisPass = /* @__PURE__ */ new Set();
+  if (!_u.seenLastPass)
+    _u.seenLastPass = /* @__PURE__ */ new Set();
+  if (_u.newPassStarting) {
+    _u.seenLastPass = new Set(_u.seenThisPass);
+    _u.seenThisPass.clear();
+    _u.newPassStarting = false;
+  }
+  _u.seenThisPass.add(cacheKey);
   const existing = unsuspend.cache.get(cacheKey);
   if (!existing) {
+    if (_u.seenLastPass.size > 0) {
+      const hasVanishedKey = [..._u.seenLastPass].some(
+        (k) => !_u.seenThisPass.has(k)
+      );
+      if (hasVanishedKey) {
+        throw new Error(
+          `[hadars] useServerData: key ${JSON.stringify(cacheKey)} appeared in this pass but a key that was present in the previous pass is now missing. This means the key is not stable across render passes (e.g. it contains Date.now(), Math.random(), or a value that changes on every render). Keys must be deterministic.`
+        );
+      }
+    }
     const result = fn();
     const isThenable = result !== null && typeof result === "object" && typeof result.then === "function";
     if (!isThenable) {
@@ -163,9 +239,11 @@ function useServerData(key, fn) {
       }
     );
     unsuspend.cache.set(cacheKey, { status: "pending", promise });
+    _u.newPassStarting = true;
     throw promise;
   }
   if (existing.status === "pending") {
+    _u.newPassStarting = true;
     throw existing.promise;
   }
   if (existing.status === "rejected")

package/dist/utils/Head.tsx

@@ -174,13 +174,46 @@ export const useApp = () => React.useContext(AppContext);
 // hydration. Keyed by the same React useId() values that the server used.
 const clientServerDataCache = new Map<string, unknown>();
 
+// Tracks in-flight data-only requests keyed by pathname+search so that all
+// useServerData calls within a single Suspense pass share one network request.
+const pendingDataFetch = new Map<string, Promise<void>>();
+// Paths for which a client data fetch has already completed. Prevents re-fetching
+// when a key is genuinely absent from the server response for this path.
+const fetchedPaths = new Set<string>();
+
+// Keys that were seeded from SSR data and not yet claimed by any useServerData
+// call on the client. Used to detect server↔client key mismatches.
+let ssrInitialKeys: Set<string> | null = null;
+let unclaimedKeyCheckScheduled = false;
+
+function scheduleUnclaimedKeyCheck() {
+    if (unclaimedKeyCheckScheduled) return;
+    unclaimedKeyCheckScheduled = true;
+    // Wait for the current synchronous hydration pass to finish, then check.
+    setTimeout(() => {
+        unclaimedKeyCheckScheduled = false;
+        if (ssrInitialKeys && ssrInitialKeys.size > 0) {
+            console.warn(
+                `[hadars] useServerData: ${ssrInitialKeys.size} server-resolved key(s) were ` +
+                `never claimed during client hydration: ${[...ssrInitialKeys].map(k => JSON.stringify(k)).join(', ')}. ` +
+                `This usually means the key passed to useServerData was different on the server ` +
+                `than on the client (e.g. it contains Date.now(), Math.random(), or another ` +
+                `value that changes between renders). Keys must be stable and deterministic.`,
+            );
+        }
+        ssrInitialKeys = null;
+    }, 0);
+}
+
 /** Call this before hydrating to seed the client cache from the server's data.
  *  Invoked automatically by the hadars client bootstrap.
  *  Always clears the existing cache before populating — call with `{}` to just clear. */
 export function initServerDataCache(data: Record<string, unknown>) {
     clientServerDataCache.clear();
+    ssrInitialKeys = new Set<string>();
     for (const [k, v] of Object.entries(data)) {
         clientServerDataCache.set(k, v);
+        ssrInitialKeys.add(k);
     }
 }
 
@@ -200,7 +233,10 @@ export function initServerDataCache(data: Record<string, unknown>) {
  * The resolved value is serialised into `__serverData` and returned from cache
  * during hydration.
  *
- * `fn` is **server-only**: it is never called in the browser.
+ * `fn` is **server-only**: it is never called in the browser. On client-side
+ * navigation (after the initial SSR load), hadars automatically fires a
+ * data-only request to the current URL (`X-Hadars-Data: 1`) and suspends via
+ * React Suspense until the server returns the JSON map of resolved values.
  *
  * @example
  * const user = useServerData('current_user', () => db.getUser(id));
@@ -211,9 +247,59 @@ export function useServerData<T>(key: string | string[], fn: () => Promise<T> |
     const cacheKey = Array.isArray(key) ? JSON.stringify(key) : key;
 
     if (typeof window !== 'undefined') {
-        // Client: if the server serialised a value for this key, return it directly.
-        // fn() is a server-only operation and must never run in the browser.
-        return clientServerDataCache.get(cacheKey) as T | undefined;
+        // Cache hit — return the server-resolved value directly (covers both initial
+        // SSR hydration and values fetched during client-side navigation).
+        if (clientServerDataCache.has(cacheKey)) {
+            // Mark this SSR key as claimed so the unclaimed-key check doesn't warn about it.
+            ssrInitialKeys?.delete(cacheKey);
+            return clientServerDataCache.get(cacheKey) as T;
+        }
+
+        // Cache miss during the initial hydration pass (SSR data is present but
+        // this key wasn't in it) — schedule a deferred check for orphaned SSR keys
+        // which would signal a server↔client key mismatch.
+        if (ssrInitialKeys !== null && ssrInitialKeys.size > 0) {
+            scheduleUnclaimedKeyCheck();
+        }
+
+        // Cache miss — this component is mounting during client-side navigation
+        // (the server hasn't sent data for this path yet). Fire a data-only
+        // request to the server at the current URL and suspend via React Suspense
+        // until it completes. All useServerData calls within the same React render
+        // share one Promise so only one network request is made per navigation.
+        const pathKey = window.location.pathname + window.location.search;
+
+        // If we already fetched this path and the key is still missing, the server
+        // doesn't produce a value for it — return undefined rather than looping.
+        if (fetchedPaths.has(pathKey)) {
+            return undefined;
+        }
+
+        if (!pendingDataFetch.has(pathKey)) {
+            let resolve!: () => void;
+            const p = new Promise<void>(res => { resolve = res; });
+            pendingDataFetch.set(pathKey, p);
+            // Fire in a microtask so that every useServerData call in this React
+            // render is registered against the same deferred before the fetch starts.
+            queueMicrotask(async () => {
+                try {
+                    const res = await fetch(pathKey, {
+                        headers: { 'Accept': 'application/json' },
+                    });
+                    if (res.ok) {
+                        const json = await res.json() as { serverData: Record<string, unknown> };
+                        for (const [k, v] of Object.entries(json.serverData ?? {})) {
+                            clientServerDataCache.set(k, v);
+                        }
+                    }
+                } finally {
+                    fetchedPaths.add(pathKey);
+                    pendingDataFetch.delete(pathKey);
+                    resolve();
+                }
+            });
+        }
+        throw pendingDataFetch.get(pathKey)!;
     }
 
     // Server: communicate via globalThis.__hadarsUnsuspend which is set by the
@@ -223,9 +309,54 @@ export function useServerData<T>(key: string | string[], fn: () => Promise<T> |
     const unsuspend: AppUnsuspend | undefined = (globalThis as any).__hadarsUnsuspend;
     if (!unsuspend) return undefined;
 
+    // ── per-pass key tracking ────────────────────────────────────────────────
+    // We keep two sets: keys seen in the current pass and keys seen in the
+    // previous pass.  When a pass throws a promise, the *next* call to
+    // useServerData marks the start of a new pass and rotates the sets.
+    //
+    // A key is unstable when a key that WAS seen in the previous pass is now
+    // absent from the current pass while a new key appears instead.  This means
+    // a component produced a different key string between passes (e.g. Date.now()
+    // in the key).  We fire immediately — there is no need to wait for other
+    // entries to settle first, because a legitimately-new component always extends
+    // seenLastPass (all previous keys remain present in seenThisPass).
+    const _u = unsuspend as any;
+    if (!_u.seenThisPass) _u.seenThisPass = new Set<string>();
+    if (!_u.seenLastPass) _u.seenLastPass = new Set<string>();
+
+    if (_u.newPassStarting) {
+        // This is the first useServerData call after a thrown promise — rotate.
+        _u.seenLastPass = new Set(_u.seenThisPass);
+        _u.seenThisPass.clear();
+        _u.newPassStarting = false;
+    }
+    _u.seenThisPass.add(cacheKey);
+    // ────────────────────────────────────────────────────────────────────────
+
     const existing = unsuspend.cache.get(cacheKey);
 
     if (!existing) {
+        // Detect an unstable key: a key that was called in the previous pass is
+        // now absent while a new key has appeared.  This means a component
+        // generated a different key between passes — it will loop forever.
+        //
+        // We intentionally do NOT fire when seenLastPass is empty (first pass
+        // ever) or when all previous keys are still present (legitimate
+        // "new component reached for the first time" scenario).
+        if (_u.seenLastPass.size > 0) {
+            const hasVanishedKey = [..._u.seenLastPass as Set<string>].some(
+                (k: string) => !(_u.seenThisPass as Set<string>).has(k),
+            );
+            if (hasVanishedKey) {
+                throw new Error(
+                    `[hadars] useServerData: key ${JSON.stringify(cacheKey)} appeared in this pass ` +
+                    `but a key that was present in the previous pass is now missing. This means ` +
+                    `the key is not stable across render passes (e.g. it contains Date.now(), ` +
+                    `Math.random(), or a value that changes on every render). Keys must be deterministic.`,
+                );
+            }
+        }
+
         // First encounter — call fn(), which may:
         //   (a) return a Promise<T>  — async usage (serialised for the client)
         //   (b) return T synchronously — e.g. a sync data source
@@ -246,9 +377,11 @@ export function useServerData<T>(key: string | string[], fn: () => Promise<T> |
             reason => { unsuspend.cache.set(cacheKey, { status: 'rejected', reason }); },
         );
         unsuspend.cache.set(cacheKey, { status: 'pending', promise });
+        _u.newPassStarting = true; // next useServerData call opens a new pass
         throw promise; // slim-react will await and retry
     }
     if (existing.status === 'pending') {
+        _u.newPassStarting = true;
         throw existing.promise; // slim-react will await and retry
     }
     if (existing.status === 'rejected') throw existing.reason;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "hadars",
-  "version": "0.1.34",
+  "version": "0.1.35",
   "description": "Minimal SSR framework for React — rspack, HMR, TypeScript, Bun/Node/Deno",
   "module": "./dist/index.js",
   "type": "module",

package/src/build.ts

@@ -689,6 +689,18 @@ export const dev = async (options: HadarsRuntimeOptions) => {
                 },
             });
 
+            // Content negotiation: if the client only accepts JSON (client-side
+            // navigation via useServerData), return the resolved data map as JSON
+            // instead of a full HTML page. The same auth context applies — cookies
+            // and headers are forwarded unchanged, so no new attack surface is created.
+            if (request.headers.get('Accept') === 'application/json') {
+                const serverData = (clientProps as any).__serverData ?? {};
+                return new Response(JSON.stringify({ serverData }), {
+                    status,
+                    headers: { 'Content-Type': 'application/json; charset=utf-8' },
+                });
+            }
+
             return buildSsrResponse(bodyHtml, clientProps, headHtml, status, getPrecontentHtml);
         } catch (err: any) {
             console.error('[hadars] SSR render error:', err);
@@ -858,7 +870,7 @@ export const run = async (options: HadarsRuntimeOptions) => {
                 getFinalProps,
             } = (await import(componentPath)) as HadarsEntryModule<any>;
 
-            if (renderPool) {
+            if (renderPool && request.headers.get('Accept') !== 'application/json') {
                 // Worker runs the full lifecycle — no non-serializable objects cross the thread boundary.
                 const serialReq = await serializeRequest(request);
                 const { html, headHtml: wHead, status: wStatus } = await renderPool.renderFull(serialReq);
@@ -879,6 +891,17 @@ export const run = async (options: HadarsRuntimeOptions) => {
                 },
             });
 
+            // Content negotiation: if the client only accepts JSON (client-side
+            // navigation via useServerData), return the resolved data map as JSON
+            // instead of a full HTML page.
+            if (request.headers.get('Accept') === 'application/json') {
+                const serverData = (clientProps as any).__serverData ?? {};
+                return new Response(JSON.stringify({ serverData }), {
+                    status,
+                    headers: { 'Content-Type': 'application/json; charset=utf-8' },
+                });
+            }
+
             return buildSsrResponse(bodyHtml, clientProps, headHtml, status, getPrecontentHtml);
         } catch (err: any) {
             console.error('[hadars] SSR render error:', err);

package/src/utils/Head.tsx

@@ -174,13 +174,46 @@ export const useApp = () => React.useContext(AppContext);
 // hydration. Keyed by the same React useId() values that the server used.
 const clientServerDataCache = new Map<string, unknown>();
 
+// Tracks in-flight data-only requests keyed by pathname+search so that all
+// useServerData calls within a single Suspense pass share one network request.
+const pendingDataFetch = new Map<string, Promise<void>>();
+// Paths for which a client data fetch has already completed. Prevents re-fetching
+// when a key is genuinely absent from the server response for this path.
+const fetchedPaths = new Set<string>();
+
+// Keys that were seeded from SSR data and not yet claimed by any useServerData
+// call on the client. Used to detect server↔client key mismatches.
+let ssrInitialKeys: Set<string> | null = null;
+let unclaimedKeyCheckScheduled = false;
+
+function scheduleUnclaimedKeyCheck() {
+    if (unclaimedKeyCheckScheduled) return;
+    unclaimedKeyCheckScheduled = true;
+    // Wait for the current synchronous hydration pass to finish, then check.
+    setTimeout(() => {
+        unclaimedKeyCheckScheduled = false;
+        if (ssrInitialKeys && ssrInitialKeys.size > 0) {
+            console.warn(
+                `[hadars] useServerData: ${ssrInitialKeys.size} server-resolved key(s) were ` +
+                `never claimed during client hydration: ${[...ssrInitialKeys].map(k => JSON.stringify(k)).join(', ')}. ` +
+                `This usually means the key passed to useServerData was different on the server ` +
+                `than on the client (e.g. it contains Date.now(), Math.random(), or another ` +
+                `value that changes between renders). Keys must be stable and deterministic.`,
+            );
+        }
+        ssrInitialKeys = null;
+    }, 0);
+}
+
 /** Call this before hydrating to seed the client cache from the server's data.
  *  Invoked automatically by the hadars client bootstrap.
  *  Always clears the existing cache before populating — call with `{}` to just clear. */
 export function initServerDataCache(data: Record<string, unknown>) {
     clientServerDataCache.clear();
+    ssrInitialKeys = new Set<string>();
     for (const [k, v] of Object.entries(data)) {
         clientServerDataCache.set(k, v);
+        ssrInitialKeys.add(k);
     }
 }
 
@@ -200,7 +233,10 @@ export function initServerDataCache(data: Record<string, unknown>) {
  * The resolved value is serialised into `__serverData` and returned from cache
  * during hydration.
  *
- * `fn` is **server-only**: it is never called in the browser.
+ * `fn` is **server-only**: it is never called in the browser. On client-side
+ * navigation (after the initial SSR load), hadars automatically fires a
+ * data-only request to the current URL (`X-Hadars-Data: 1`) and suspends via
+ * React Suspense until the server returns the JSON map of resolved values.
  *
  * @example
  * const user = useServerData('current_user', () => db.getUser(id));
@@ -211,9 +247,59 @@ export function useServerData<T>(key: string | string[], fn: () => Promise<T> |
     const cacheKey = Array.isArray(key) ? JSON.stringify(key) : key;
 
     if (typeof window !== 'undefined') {
-        // Client: if the server serialised a value for this key, return it directly.
-        // fn() is a server-only operation and must never run in the browser.
-        return clientServerDataCache.get(cacheKey) as T | undefined;
+        // Cache hit — return the server-resolved value directly (covers both initial
+        // SSR hydration and values fetched during client-side navigation).
+        if (clientServerDataCache.has(cacheKey)) {
+            // Mark this SSR key as claimed so the unclaimed-key check doesn't warn about it.
+            ssrInitialKeys?.delete(cacheKey);
+            return clientServerDataCache.get(cacheKey) as T;
+        }
+
+        // Cache miss during the initial hydration pass (SSR data is present but
+        // this key wasn't in it) — schedule a deferred check for orphaned SSR keys
+        // which would signal a server↔client key mismatch.
+        if (ssrInitialKeys !== null && ssrInitialKeys.size > 0) {
+            scheduleUnclaimedKeyCheck();
+        }
+
+        // Cache miss — this component is mounting during client-side navigation
+        // (the server hasn't sent data for this path yet). Fire a data-only
+        // request to the server at the current URL and suspend via React Suspense
+        // until it completes. All useServerData calls within the same React render
+        // share one Promise so only one network request is made per navigation.
+        const pathKey = window.location.pathname + window.location.search;
+
+        // If we already fetched this path and the key is still missing, the server
+        // doesn't produce a value for it — return undefined rather than looping.
+        if (fetchedPaths.has(pathKey)) {
+            return undefined;
+        }
+
+        if (!pendingDataFetch.has(pathKey)) {
+            let resolve!: () => void;
+            const p = new Promise<void>(res => { resolve = res; });
+            pendingDataFetch.set(pathKey, p);
+            // Fire in a microtask so that every useServerData call in this React
+            // render is registered against the same deferred before the fetch starts.
+            queueMicrotask(async () => {
+                try {
+                    const res = await fetch(pathKey, {
+                        headers: { 'Accept': 'application/json' },
+                    });
+                    if (res.ok) {
+                        const json = await res.json() as { serverData: Record<string, unknown> };
+                        for (const [k, v] of Object.entries(json.serverData ?? {})) {
+                            clientServerDataCache.set(k, v);
+                        }
+                    }
+                } finally {
+                    fetchedPaths.add(pathKey);
+                    pendingDataFetch.delete(pathKey);
+                    resolve();
+                }
+            });
+        }
+        throw pendingDataFetch.get(pathKey)!;
     }
 
     // Server: communicate via globalThis.__hadarsUnsuspend which is set by the
@@ -223,9 +309,54 @@ export function useServerData<T>(key: string | string[], fn: () => Promise<T> |
     const unsuspend: AppUnsuspend | undefined = (globalThis as any).__hadarsUnsuspend;
     if (!unsuspend) return undefined;
 
+    // ── per-pass key tracking ────────────────────────────────────────────────
+    // We keep two sets: keys seen in the current pass and keys seen in the
+    // previous pass.  When a pass throws a promise, the *next* call to
+    // useServerData marks the start of a new pass and rotates the sets.
+    //
+    // A key is unstable when a key that WAS seen in the previous pass is now
+    // absent from the current pass while a new key appears instead.  This means
+    // a component produced a different key string between passes (e.g. Date.now()
+    // in the key).  We fire immediately — there is no need to wait for other
+    // entries to settle first, because a legitimately-new component always extends
+    // seenLastPass (all previous keys remain present in seenThisPass).
+    const _u = unsuspend as any;
+    if (!_u.seenThisPass) _u.seenThisPass = new Set<string>();
+    if (!_u.seenLastPass) _u.seenLastPass = new Set<string>();
+
+    if (_u.newPassStarting) {
+        // This is the first useServerData call after a thrown promise — rotate.
+        _u.seenLastPass = new Set(_u.seenThisPass);
+        _u.seenThisPass.clear();
+        _u.newPassStarting = false;
+    }
+    _u.seenThisPass.add(cacheKey);
+    // ────────────────────────────────────────────────────────────────────────
+
     const existing = unsuspend.cache.get(cacheKey);
 
     if (!existing) {
+        // Detect an unstable key: a key that was called in the previous pass is
+        // now absent while a new key has appeared.  This means a component
+        // generated a different key between passes — it will loop forever.
+        //
+        // We intentionally do NOT fire when seenLastPass is empty (first pass
+        // ever) or when all previous keys are still present (legitimate
+        // "new component reached for the first time" scenario).
+        if (_u.seenLastPass.size > 0) {
+            const hasVanishedKey = [..._u.seenLastPass as Set<string>].some(
+                (k: string) => !(_u.seenThisPass as Set<string>).has(k),
+            );
+            if (hasVanishedKey) {
+                throw new Error(
+                    `[hadars] useServerData: key ${JSON.stringify(cacheKey)} appeared in this pass ` +
+                    `but a key that was present in the previous pass is now missing. This means ` +
+                    `the key is not stable across render passes (e.g. it contains Date.now(), ` +
+                    `Math.random(), or a value that changes on every render). Keys must be deterministic.`,
+                );
+            }
+        }
+
         // First encounter — call fn(), which may:
         //   (a) return a Promise<T>  — async usage (serialised for the client)
         //   (b) return T synchronously — e.g. a sync data source
@@ -246,9 +377,11 @@ export function useServerData<T>(key: string | string[], fn: () => Promise<T> |
             reason => { unsuspend.cache.set(cacheKey, { status: 'rejected', reason }); },
         );
         unsuspend.cache.set(cacheKey, { status: 'pending', promise });
+        _u.newPassStarting = true; // next useServerData call opens a new pass
         throw promise; // slim-react will await and retry
     }
     if (existing.status === 'pending') {
+        _u.newPassStarting = true;
         throw existing.promise; // slim-react will await and retry
     }
     if (existing.status === 'rejected') throw existing.reason;