hadars 0.1.33 → 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

@@ -1181,7 +1181,8 @@ var getConfigBase = (mode, isServerBuild = false) => {
             // Transforms loadModule('./path') based on build target.
             // Runs before swc-loader (loaders execute right-to-left).
             {
-              loader: loaderPath
+              loader: loaderPath,
+              options: { server: isServerBuild }
             },
             {
               loader: "builtin:swc-loader",
@@ -1212,7 +1213,8 @@ var getConfigBase = (mode, isServerBuild = false) => {
           exclude: [loaderPath],
           use: [
             {
-              loader: loaderPath
+              loader: loaderPath,
+              options: { server: isServerBuild }
             },
             {
               loader: "builtin:swc-loader",
@@ -2206,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);
@@ -2342,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);
@@ -2360,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/loader.cjs

@@ -22,7 +22,8 @@ __export(loader_exports, {
 });
 module.exports = __toCommonJS(loader_exports);
 function loader(source) {
-  const isServer = this.target === "node" || this.target === "async-node";
+  const opts = this.getOptions?.() ?? {};
+  const isServer = typeof opts.server === "boolean" ? opts.server : this.target === "node" || this.target === "async-node";
   const resourcePath = this.resourcePath ?? this.resource ?? "(unknown)";
   let swc;
   try {
@@ -51,7 +52,22 @@ function swcTransform(swc, source, isServer, resourcePath) {
     if (node.type !== "CallExpression")
       return;
     const callee = node.callee;
-    if (!callee || callee.type !== "Identifier" || callee.value !== "loadModule")
+    if (!callee || callee.type !== "Identifier")
+      return;
+    const name = callee.value;
+    if (!isServer && name === "useServerData") {
+      const args2 = node.arguments;
+      if (!args2 || args2.length < 2)
+        return;
+      const fnArg = args2[1].expression ?? args2[1];
+      replacements.push({
+        start: fnArg.span.start - fileOffset,
+        end: fnArg.span.end - fileOffset,
+        replacement: "()=>undefined"
+      });
+      return;
+    }
+    if (name !== "loadModule")
       return;
     const args = node.arguments;
     if (!args || args.length === 0)
@@ -136,11 +152,87 @@ function countLeadingNonCodeBytes(source) {
 }
 const LOAD_MODULE_RE = /\bloadModule\s*(?:<(?:[^<>]|<[^<>]*>)*>\s*)?\(\s*(['"`])((?:\\.|(?!\1)[^\\])*)\1\s*\)/gs;
 const DYNAMIC_LOAD_MODULE_RE = /\bloadModule\s*(?:<(?:[^<>]|<[^<>]*>)*>\s*)?\(/g;
+function scanExpressionEnd(source, pos) {
+  let depth = 0;
+  let i = pos;
+  while (i < source.length) {
+    const ch = source[i];
+    if (ch === "(" || ch === "[" || ch === "{") {
+      depth++;
+      i++;
+      continue;
+    }
+    if (ch === ")" || ch === "]" || ch === "}") {
+      if (depth === 0)
+        break;
+      depth--;
+      i++;
+      continue;
+    }
+    if (ch === "," && depth === 0)
+      break;
+    if (ch === '"' || ch === "'" || ch === "`") {
+      const q = ch;
+      i++;
+      while (i < source.length && source[i] !== q) {
+        if (source[i] === "\\")
+          i++;
+        i++;
+      }
+      i++;
+      continue;
+    }
+    if (ch === "/" && source[i + 1] === "/") {
+      while (i < source.length && source[i] !== "\n")
+        i++;
+      continue;
+    }
+    if (ch === "/" && source[i + 1] === "*") {
+      i += 2;
+      while (i + 1 < source.length && !(source[i] === "*" && source[i + 1] === "/"))
+        i++;
+      i += 2;
+      continue;
+    }
+    i++;
+  }
+  return i;
+}
+function stripUseServerDataFns(source) {
+  const CALL_RE = /\buseServerData\s*(?:<(?:[^<>]|<[^<>]*>)*>\s*)?\(/g;
+  let result = "";
+  let lastIndex = 0;
+  let match;
+  CALL_RE.lastIndex = 0;
+  while ((match = CALL_RE.exec(source)) !== null) {
+    const callStart = match.index;
+    let i = match.index + match[0].length;
+    while (i < source.length && /\s/.test(source[i]))
+      i++;
+    i = scanExpressionEnd(source, i);
+    if (i >= source.length || source[i] !== ",")
+      continue;
+    i++;
+    while (i < source.length && /\s/.test(source[i]))
+      i++;
+    const fnStart = i;
+    const fnEnd = scanExpressionEnd(source, i);
+    if (fnEnd <= fnStart)
+      continue;
+    result += source.slice(lastIndex, fnStart) + "()=>undefined";
+    lastIndex = fnEnd;
+    CALL_RE.lastIndex = fnEnd;
+  }
+  return lastIndex === 0 ? source : result + source.slice(lastIndex);
+}
 function regexTransform(source, isServer, resourcePath) {
-  const transformed = source.replace(
+  let transformed = source.replace(
     LOAD_MODULE_RE,
     (_match, quote, modulePath) => isServer ? `Promise.resolve(require(${quote}${modulePath}${quote}))` : `import(${quote}${modulePath}${quote})`
   );
+  if (!isServer) {
+    transformed = stripUseServerDataFns(transformed);
+  }
   let match;
   DYNAMIC_LOAD_MODULE_RE.lastIndex = 0;
   while ((match = DYNAMIC_LOAD_MODULE_RE.exec(transformed)) !== null) {

package/dist/ssr-watch.js

@@ -52,7 +52,8 @@ var getConfigBase = (mode, isServerBuild = false) => {
             // Transforms loadModule('./path') based on build target.
             // Runs before swc-loader (loaders execute right-to-left).
             {
-              loader: loaderPath
+              loader: loaderPath,
+              options: { server: isServerBuild }
             },
             {
               loader: "builtin:swc-loader",
@@ -83,7 +84,8 @@ var getConfigBase = (mode, isServerBuild = false) => {
           exclude: [loaderPath],
           use: [
             {
-              loader: loaderPath
+              loader: loaderPath,
+              options: { server: isServerBuild }
             },
             {
               loader: "builtin:swc-loader",

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.33",
+  "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;

package/src/utils/loader.ts

@@ -1,34 +1,49 @@
 /**
- * Rspack/webpack loader that transforms `loadModule('path')` calls based on
- * the compilation target:
+ * Rspack/webpack loader that applies two source-level transforms based on the
+ * compilation target (web vs node):
  *
+ * ── loadModule('path') ────────────────────────────────────────────────────────
  *  - web  (browser): replaced with `import('./path')` — rspack treats this as
  *    a true dynamic import and splits the module into a separate chunk.
- *
  *  - node (SSR):     replaced with `Promise.resolve(require('./path'))` —
- *    rspack bundles the module statically so it is always available
- *    synchronously on the server, wrapped in Promise.resolve to keep the
- *    API shape identical to the client side.
+ *    bundled statically, wrapped in Promise.resolve to keep the API shape.
+ *
+ * ── useServerData(key, fn) ───────────────────────────────────────────────────
+ *  - web  (browser): the second argument `fn` is replaced with `()=>undefined`.
+ *    `fn` is a server-only callback that may reference internal endpoints,
+ *    credentials, or other sensitive information. It is never called in the
+ *    browser (the hook returns the SSR-cached value immediately), but without
+ *    this transform it would still be compiled into the client bundle — exposing
+ *    those details to anyone who inspects the JS. Stripping it at bundle time
+ *    prevents the leak entirely.
+ *  - node (SSR): kept as-is — the real fn is needed to fetch data.
  *
  * Transformation strategy:
  *   Primary  — SWC AST parsing via @swc/core. Handles any valid TS/JS syntax
  *              including arbitrarily-nested generics, comments, and string
- *              literals that contain the text "loadModule".
- *   Fallback — Regex transform used when @swc/core is unavailable.
+ *              literals that contain the function names.
+ *   Fallback — Scanner-based transform used when @swc/core is unavailable.
  *
- * Example usage:
+ * Example:
  *
- *   import { loadModule } from 'hadars';
+ *   // Source (shared component):
+ *   const user = useServerData('user', () => db.getUser(req.userId));
  *
- *   // Code-split React component (wrap with React.lazy + Suspense):
- *   const MyComp = React.lazy(() => loadModule('./MyComp'));
+ *   // Client bundle after transform:
+ *   const user = useServerData('user', ()=>undefined);
  *
- *   // Dynamic module load:
- *   const { default: fn } = await loadModule('./heavyUtil');
+ *   // Server bundle (unchanged):
+ *   const user = useServerData('user', () => db.getUser(req.userId));
  */
 
 export default function loader(this: any, source: string): string {
-    const isServer = this.target === 'node' || this.target === 'async-node';
+    // Prefer the explicit `server` option injected by rspack.ts over the legacy
+    // `this.target` heuristic (which is unreliable when `target` is not set in
+    // the rspack config — rspack then reports 'web' for every build).
+    const opts = this.getOptions?.() ?? {};
+    const isServer: boolean = (typeof opts.server === 'boolean')
+        ? opts.server
+        : (this.target === 'node' || this.target === 'async-node');
     const resourcePath: string = this.resourcePath ?? this.resource ?? '(unknown)';
 
     let swc: any;
@@ -80,7 +95,26 @@ function swcTransform(this: any, swc: any, source: string, isServer: boolean, re
         if (node.type !== 'CallExpression') return;
 
         const callee = node.callee;
-        if (!callee || callee.type !== 'Identifier' || callee.value !== 'loadModule') return;
+        if (!callee || callee.type !== 'Identifier') return;
+
+        const name: string = callee.value;
+
+        // ── useServerData(key, fn) — strip fn on client builds ────────────────
+        if (!isServer && name === 'useServerData') {
+            const args: any[] = node.arguments;
+            if (!args || args.length < 2) return;
+            const fnArg = args[1].expression ?? args[1];
+            // Normalise to 0-based local byte offsets and replace with stub.
+            replacements.push({
+                start: fnArg.span.start - fileOffset,
+                end: fnArg.span.end - fileOffset,
+                replacement: '()=>undefined',
+            });
+            return;
+        }
+
+        // ── loadModule(path) ─────────────────────────────────────────────────
+        if (name !== 'loadModule') return;
 
         const args: any[] = node.arguments;
         if (!args || args.length === 0) return;
@@ -199,13 +233,99 @@ const LOAD_MODULE_RE =
 // (i.e. a dynamic / non-literal path argument).
 const DYNAMIC_LOAD_MODULE_RE = /\bloadModule\s*(?:<(?:[^<>]|<[^<>]*>)*>\s*)?\(/g;
 
+/**
+ * Scan forward from `pos` in `source`, skipping over a balanced JS expression
+ * (handles nested parens/brackets/braces and string literals).
+ * Returns the index of the first character AFTER the expression
+ * (i.e. the position of the trailing `,` or `)` at depth 0).
+ */
+function scanExpressionEnd(source: string, pos: number): number {
+    let depth = 0;
+    let i = pos;
+    while (i < source.length) {
+        const ch = source[i]!;
+        if (ch === '(' || ch === '[' || ch === '{') { depth++; i++; continue; }
+        if (ch === ')' || ch === ']' || ch === '}') {
+            if (depth === 0) break; // end of expression — closing delimiter of outer call
+            depth--; i++; continue;
+        }
+        if (ch === ',' && depth === 0) break; // end of expression — next argument
+        // String / template literals
+        if (ch === '"' || ch === "'" || ch === '`') {
+            const q = ch; i++;
+            while (i < source.length && source[i] !== q) {
+                if (source[i] === '\\') i++; // escape sequence
+                i++;
+            }
+            i++; // closing quote
+            continue;
+        }
+        // Line comment
+        if (ch === '/' && source[i + 1] === '/') {
+            while (i < source.length && source[i] !== '\n') i++;
+            continue;
+        }
+        // Block comment
+        if (ch === '/' && source[i + 1] === '*') {
+            i += 2;
+            while (i + 1 < source.length && !(source[i] === '*' && source[i + 1] === '/')) i++;
+            i += 2;
+            continue;
+        }
+        i++;
+    }
+    return i;
+}
+
+/**
+ * Strip the `fn` argument from `useServerData(key, fn)` calls in client builds.
+ * Uses a character-level scanner to handle arbitrary fn expressions (arrow
+ * functions with nested calls, async functions, object literals, etc.).
+ */
+function stripUseServerDataFns(source: string): string {
+    // Match `useServerData` + optional generic + opening paren
+    const CALL_RE = /\buseServerData\s*(?:<(?:[^<>]|<[^<>]*>)*>\s*)?\(/g;
+    let result = '';
+    let lastIndex = 0;
+    let match: RegExpExecArray | null;
+    CALL_RE.lastIndex = 0;
+    while ((match = CALL_RE.exec(source)) !== null) {
+        const callStart = match.index;
+        let i = match.index + match[0].length;
+        // Skip whitespace before first arg
+        while (i < source.length && /\s/.test(source[i]!)) i++;
+        // Skip first argument (key: string or array)
+        i = scanExpressionEnd(source, i);
+        // Expect comma separator
+        if (i >= source.length || source[i] !== ',') continue;
+        i++; // skip comma
+        // Skip whitespace before fn
+        while (i < source.length && /\s/.test(source[i]!)) i++;
+        const fnStart = i;
+        // Scan to end of fn argument
+        const fnEnd = scanExpressionEnd(source, i);
+        if (fnEnd <= fnStart) continue;
+        // Emit everything up to fn, then the stub, skip the original fn
+        result += source.slice(lastIndex, fnStart) + '()=>undefined';
+        lastIndex = fnEnd;
+        // Advance regex past this call to avoid re-matching
+        CALL_RE.lastIndex = fnEnd;
+    }
+    return lastIndex === 0 ? source : result + source.slice(lastIndex);
+}
+
 function regexTransform(this: any, source: string, isServer: boolean, resourcePath: string): string {
-    const transformed = source.replace(LOAD_MODULE_RE, (_match, quote, modulePath) =>
+    let transformed = source.replace(LOAD_MODULE_RE, (_match, quote, modulePath) =>
         isServer
             ? `Promise.resolve(require(${quote}${modulePath}${quote}))`
             : `import(${quote}${modulePath}${quote})`
     );
 
+    // Strip server-only fn arguments from useServerData on client builds.
+    if (!isServer) {
+        transformed = stripUseServerDataFns(transformed);
+    }
+
     // Warn for any remaining dynamic calls
     let match: RegExpExecArray | null;
     DYNAMIC_LOAD_MODULE_RE.lastIndex = 0;

package/src/utils/rspack.ts

@@ -59,6 +59,7 @@ const getConfigBase = (mode: "development" | "production", isServerBuild = false
                         // Runs before swc-loader (loaders execute right-to-left).
                         {
                             loader: loaderPath,
+                            options: { server: isServerBuild },
                         },
                         {
                             loader: 'builtin:swc-loader',
@@ -90,6 +91,7 @@ const getConfigBase = (mode: "development" | "production", isServerBuild = false
                     use: [
                         {
                             loader: loaderPath,
+                            options: { server: isServerBuild },
                         },
                         {
                             loader: 'builtin:swc-loader',