hadars 0.1.9 → 0.1.11

package/dist/loader.cjs

@@ -21,14 +21,135 @@ __export(loader_exports, {
   default: () => loader
 });
 module.exports = __toCommonJS(loader_exports);
-const LOAD_MODULE_RE = /\bloadModule\s*(?:<.*?>\s*)?\(\s*(['"`])((?:\\.|(?!\1)[^\\])*)\1\s*\)/gs;
 function loader(source) {
   const isServer = this.target === "node" || this.target === "async-node";
-  return source.replace(LOAD_MODULE_RE, (_match, quote, modulePath) => {
-    if (isServer) {
-      return `Promise.resolve(require(${quote}${modulePath}${quote}))`;
+  const resourcePath = this.resourcePath ?? this.resource ?? "(unknown)";
+  let swc;
+  try {
+    swc = require("@swc/core");
+  } catch {
+    return regexTransform.call(this, source, isServer, resourcePath);
+  }
+  return swcTransform.call(this, swc, source, isServer, resourcePath);
+}
+function swcTransform(swc, source, isServer, resourcePath) {
+  const isTs = /\.[mc]?tsx?$/.test(resourcePath);
+  const isTsx = /\.(tsx|jsx)$/.test(resourcePath);
+  let ast;
+  try {
+    ast = swc.parseSync(source, {
+      syntax: isTs ? "typescript" : "ecmascript",
+      tsx: isTsx
+    });
+  } catch {
+    return regexTransform.call(this, source, isServer, resourcePath);
+  }
+  const srcBytes = Buffer.from(source, "utf8");
+  const fileOffset = ast.span.start - countLeadingNonCodeBytes(source);
+  const replacements = [];
+  walkAst(ast, (node) => {
+    if (node.type !== "CallExpression")
+      return;
+    const callee = node.callee;
+    if (!callee || callee.type !== "Identifier" || callee.value !== "loadModule")
+      return;
+    const args = node.arguments;
+    if (!args || args.length === 0)
+      return;
+    const firstArg = args[0].expression ?? args[0];
+    let modulePath;
+    let quoteChar;
+    if (firstArg.type === "StringLiteral") {
+      modulePath = firstArg.value;
+      const quoteByteIdx = firstArg.span.start - fileOffset;
+      quoteChar = String.fromCharCode(srcBytes[quoteByteIdx]);
+    } else if (firstArg.type === "TemplateLiteral" && firstArg.expressions.length === 0 && firstArg.quasis.length === 1) {
+      modulePath = firstArg.quasis[0].raw;
+      quoteChar = "`";
     } else {
-      return `import(${quote}${modulePath}${quote})`;
+      const start0 = node.span.start - fileOffset;
+      const bytesBefore = srcBytes.slice(0, start0);
+      const line = bytesBefore.toString("utf8").split("\n").length;
+      this.emitWarning(
+        new Error(
+          `[hadars] loadModule() called with a dynamic (non-literal) path at ${resourcePath}:${line}. Only string-literal paths are transformed by the loader; dynamic calls fall back to runtime import().`
+        )
+      );
+      return;
     }
+    const replacement = isServer ? `Promise.resolve(require(${quoteChar}${modulePath}${quoteChar}))` : `import(${quoteChar}${modulePath}${quoteChar})`;
+    replacements.push({ start: node.span.start - fileOffset, end: node.span.end - fileOffset, replacement });
   });
+  if (replacements.length === 0)
+    return source;
+  replacements.sort((a, b) => b.start - a.start);
+  let result = srcBytes;
+  for (const { start, end, replacement } of replacements) {
+    result = Buffer.concat([result.slice(0, start), Buffer.from(replacement, "utf8"), result.slice(end)]);
+  }
+  return result.toString("utf8");
+}
+function walkAst(node, visit) {
+  if (!node || typeof node !== "object")
+    return;
+  visit(node);
+  for (const key of Object.keys(node)) {
+    if (key === "span" || key === "type" || key === "ctxt")
+      continue;
+    const val = node[key];
+    if (Array.isArray(val)) {
+      for (const child of val)
+        walkAst(child, visit);
+    } else if (val && typeof val === "object") {
+      walkAst(val, visit);
+    }
+  }
+}
+function countLeadingNonCodeBytes(source) {
+  let i = 0;
+  while (i < source.length) {
+    if (source[i] === " " || source[i] === "	" || source[i] === "\r" || source[i] === "\n") {
+      i++;
+      continue;
+    }
+    if (source[i] === "/" && source[i + 1] === "/") {
+      while (i < source.length && source[i] !== "\n")
+        i++;
+      continue;
+    }
+    if (source[i] === "/" && source[i + 1] === "*") {
+      i += 2;
+      while (i + 1 < source.length && !(source[i] === "*" && source[i + 1] === "/"))
+        i++;
+      if (i + 1 < source.length)
+        i += 2;
+      continue;
+    }
+    if (i === 0 && source[i] === "#" && source[i + 1] === "!") {
+      while (i < source.length && source[i] !== "\n")
+        i++;
+      continue;
+    }
+    break;
+  }
+  return Buffer.byteLength(source.slice(0, i), "utf8");
+}
+const LOAD_MODULE_RE = /\bloadModule\s*(?:<(?:[^<>]|<[^<>]*>)*>\s*)?\(\s*(['"`])((?:\\.|(?!\1)[^\\])*)\1\s*\)/gs;
+const DYNAMIC_LOAD_MODULE_RE = /\bloadModule\s*(?:<(?:[^<>]|<[^<>]*>)*>\s*)?\(/g;
+function regexTransform(source, isServer, resourcePath) {
+  const transformed = source.replace(
+    LOAD_MODULE_RE,
+    (_match, quote, modulePath) => isServer ? `Promise.resolve(require(${quote}${modulePath}${quote}))` : `import(${quote}${modulePath}${quote})`
+  );
+  let match;
+  DYNAMIC_LOAD_MODULE_RE.lastIndex = 0;
+  while ((match = DYNAMIC_LOAD_MODULE_RE.exec(transformed)) !== null) {
+    const line = transformed.slice(0, match.index).split("\n").length;
+    this.emitWarning(
+      new Error(
+        `[hadars] loadModule() called with a dynamic (non-literal) path at ${resourcePath}:${line}. Only string-literal paths are transformed by the loader; dynamic calls fall back to runtime import().`
+      )
+    );
+  }
+  return transformed;
 }

package/dist/ssr-render-worker.js

@@ -108,6 +108,9 @@ async function runFullLifecycle(serialReq) {
       await Promise.all(pending);
     }
   } while (unsuspend.hasPending && ++iters < 25);
+  if (unsuspend.hasPending) {
+    console.warn("[hadars] SSR render loop hit the 25-iteration cap \u2014 some useServerData values may not be resolved. Check for data dependencies that are never fulfilled.");
+  }
   props = getAfterRenderProps ? await getAfterRenderProps(props, html) : props;
   try {
     globalThis.__hadarsUnsuspend = unsuspend;

package/dist/utils/Head.tsx

@@ -175,8 +175,10 @@ export const useApp = () => React.useContext(AppContext);
 const clientServerDataCache = new Map<string, unknown>();
 
 /** Call this before hydrating to seed the client cache from the server's data.
- *  Invoked automatically by the hadars client bootstrap. */
+ *  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();
     for (const [k, v] of Object.entries(data)) {
         clientServerDataCache.set(k, v);
     }
@@ -208,7 +210,7 @@ export function initServerDataCache(data: Record<string, unknown>) {
  * if (!user) return null; // undefined while pending on the first SSR pass
  */
 export function useServerData<T>(key: string | string[], fn: () => Promise<T> | T): T | undefined {
-    const cacheKey = Array.isArray(key) ? key.join('\x00') : key;
+    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

package/dist/utils/clientScript.tsx

@@ -32,8 +32,12 @@ const main = async () => {
 
     const { location } = props;
 
-    if ( appMod.getClientProps ) {
-        props = await appMod.getClientProps(props);
+    if (appMod.getClientProps) {
+        try {
+            props = await appMod.getClientProps(props);
+        } catch (err) {
+            console.error('[hadars] getClientProps threw an error:', err);
+        }
     }
 
     props = {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "hadars",
-  "version": "0.1.9",
+  "version": "0.1.11",
   "description": "Minimal SSR framework for React — rspack, HMR, TypeScript, Bun/Node/Deno",
   "module": "./dist/index.js",
   "type": "module",
@@ -32,6 +32,7 @@
     "build:lib": "tsup src/index.tsx --format esm,cjs --dts --out-dir dist --clean --external '@rspack/*' --external '@rspack/binding'",
     "build:cli": "node build-scripts/build-cli.mjs",
     "build:all": "npm run build:lib && npm run build:cli",
+    "test": "bun test test/ssr.test.ts",
     "prepare": "npm run build:all",
     "prepublishOnly": "npm run build:all"
   },
@@ -51,8 +52,8 @@
     "node": ">=18.0.0"
   },
   "peerDependencies": {
-    "react": "^19.0.0",
-    "react-dom": "^19.0.0",
+    "react": "^19.1.1",
+    "react-dom": "^19.1.1",
     "typescript": "^5"
   },
   "peerDependenciesMeta": {
@@ -62,28 +63,28 @@
   },
   "optionalDependencies": {
     "@rspack/core": "1.4.9",
-    "@rspack/dev-server": "^1.1.4",
-    "@rspack/plugin-react-refresh": "^1.5.0",
+    "@rspack/dev-server": "^1.2.1",
+    "@rspack/plugin-react-refresh": "^1.6.1",
+    "@swc/core": "^1.15.18",
     "@types/bun": "latest",
-    "@types/react-dom": "^19.1.9",
+    "@types/react-dom": "^19.2.3",
     "react-refresh": "^0.17.0",
-    "typescript": "^5"
+    "typescript": "^5.9.3"
   },
   "devDependencies": {
-    "@types/react": "^19.0.0",
+    "@types/react": "^19.2.14",
     "@types/react-dom": "^19.0.0",
-    "esbuild": "^0.19.0",
-    "tsup": "^6.6.0",
-    "@swc/core": "^1.4.0"
+    "esbuild": "^0.19.12",
+    "tsup": "^6.7.0"
   },
   "dependencies": {
     "@mdx-js/loader": "^3.1.1",
     "@mdx-js/react": "^3.1.1",
     "@svgr/webpack": "^8.1.0",
-    "@tailwindcss/postcss": "^4.1.12",
-    "postcss": "^8.5.6",
-    "postcss-loader": "^8.2.0",
-    "tailwindcss": "^4.1.12"
+    "@tailwindcss/postcss": "^4.2.1",
+    "postcss": "^8.5.8",
+    "postcss-loader": "^8.2.1",
+    "tailwindcss": "^4.2.1"
   },
   "license": "MIT",
   "repository": {

package/src/build.ts

@@ -10,6 +10,7 @@ import { RspackDevServer } from "@rspack/dev-server";
 import pathMod from "node:path";
 import { fileURLToPath, pathToFileURL } from 'node:url';
 import { createRequire } from 'node:module';
+import crypto from 'node:crypto';
 import fs from 'node:fs/promises';
 import { existsSync } from 'node:fs';
 import os from 'node:os';
@@ -53,6 +54,9 @@ class RenderWorkerPool {
     private workerPending = new Map<any, Set<number>>();
     private nextId = 0;
     private rrIndex = 0;
+    private _Worker: any = null;
+    private _workerPath = '';
+    private _ssrBundlePath = '';
 
     constructor(workerPath: string, size: number, ssrBundlePath: string) {
         // Dynamically import Worker so this class can be defined at module load
@@ -61,36 +65,42 @@ class RenderWorkerPool {
     }
 
     private _init(workerPath: string, size: number, ssrBundlePath: string) {
+        this._workerPath = workerPath;
+        this._ssrBundlePath = ssrBundlePath;
         import('node:worker_threads').then(({ Worker }) => {
-            for (let i = 0; i < size; i++) {
-                const w = new Worker(workerPath, { workerData: { ssrBundlePath } });
-                this.workerPending.set(w, new Set());
-                w.on('message', (msg: any) => {
-                    const { id, html, headHtml, status, error } = msg;
-                    const p = this.pending.get(id);
-                    if (!p) return;
-                    this.pending.delete(id);
-                    this.workerPending.get(w)?.delete(id);
-                    if (error) p.reject(new Error(error));
-                    else p.resolve({ html, headHtml, status });
-                });
-                w.on('error', (err: Error) => {
-                    console.error('[hadars] Render worker error:', err);
-                    this._handleWorkerDeath(w, err);
-                });
-                w.on('exit', (code: number) => {
-                    if (code !== 0) {
-                        console.error(`[hadars] Render worker exited with code ${code}`);
-                        this._handleWorkerDeath(w, new Error(`Render worker exited with code ${code}`));
-                    }
-                });
-                this.workers.push(w);
-            }
+            this._Worker = Worker;
+            for (let i = 0; i < size; i++) this._spawnWorker();
         }).catch(err => {
             console.error('[hadars] Failed to initialise render worker pool:', err);
         });
     }
 
+    private _spawnWorker() {
+        if (!this._Worker) return;
+        const w = new this._Worker(this._workerPath, { workerData: { ssrBundlePath: this._ssrBundlePath } });
+        this.workerPending.set(w, new Set());
+        w.on('message', (msg: any) => {
+            const { id, html, headHtml, status, error } = msg;
+            const p = this.pending.get(id);
+            if (!p) return;
+            this.pending.delete(id);
+            this.workerPending.get(w)?.delete(id);
+            if (error) p.reject(new Error(error));
+            else p.resolve({ html, headHtml, status });
+        });
+        w.on('error', (err: Error) => {
+            console.error('[hadars] Render worker error:', err);
+            this._handleWorkerDeath(w, err);
+        });
+        w.on('exit', (code: number) => {
+            if (code !== 0) {
+                console.error(`[hadars] Render worker exited with code ${code}`);
+                this._handleWorkerDeath(w, new Error(`Render worker exited with code ${code}`));
+            }
+        });
+        this.workers.push(w);
+    }
+
     private _handleWorkerDeath(w: any, err: Error) {
         const idx = this.workers.indexOf(w);
         if (idx !== -1) this.workers.splice(idx, 1);
@@ -106,6 +116,10 @@ class RenderWorkerPool {
             }
             this.workerPending.delete(w);
         }
+
+        // Spawn a replacement to keep the pool at full capacity.
+        console.log('[hadars] Spawning replacement render worker');
+        this._spawnWorker();
     }
 
     private nextWorker(): any | undefined {
@@ -216,6 +230,96 @@ const makePrecontentHtmlGetter = (htmlFilePromise: Promise<string>) => {
     };
 };
 
+// ── SSR response cache ────────────────────────────────────────────────────────
+
+interface CacheEntry {
+    /** Gzip-compressed response body — much cheaper to keep in RAM than raw HTML. */
+    body: Uint8Array;
+    status: number;
+    /** Headers with Content-Encoding: gzip already set. */
+    headers: [string, string][];
+    expiresAt: number | null;
+}
+
+type CacheFetchHandler = (req: Request, ctx: any) => Promise<Response | undefined>;
+
+async function transformStream(data: Uint8Array, stream: { writable: WritableStream; readable: ReadableStream<Uint8Array> }): Promise<Uint8Array> {
+    const writer = stream.writable.getWriter();
+    writer.write(data);
+    writer.close();
+    const chunks: Uint8Array[] = [];
+    const reader = stream.readable.getReader();
+    while (true) {
+        const { done, value } = await reader.read();
+        if (done) break;
+        chunks.push(value);
+    }
+    const total = chunks.reduce((n, c) => n + c.length, 0);
+    const out = new Uint8Array(total);
+    let offset = 0;
+    for (const c of chunks) { out.set(c, offset); offset += c.length; }
+    return out;
+}
+
+const gzipCompress   = (d: Uint8Array) => transformStream(d, new (globalThis as any).CompressionStream('gzip'));
+const gzipDecompress = (d: Uint8Array) => transformStream(d, new (globalThis as any).DecompressionStream('gzip'));
+
+function createRenderCache(
+    opts: NonNullable<HadarsOptions['cache']>,
+    handler: CacheFetchHandler,
+): CacheFetchHandler {
+    const store = new Map<string, CacheEntry>();
+
+    return async (req, ctx) => {
+        const hadarsReq = parseRequest(req);
+        const cacheOpts = await opts(hadarsReq);
+        const key = cacheOpts?.key ?? null;
+
+        if (key != null) {
+            const entry = store.get(key);
+            if (entry) {
+                if (entry.expiresAt == null || Date.now() < entry.expiresAt) {
+                    const accept = req.headers.get('Accept-Encoding') ?? '';
+                    if (accept.includes('gzip')) {
+                        return new Response(entry.body.buffer as ArrayBuffer, { status: entry.status, headers: entry.headers });
+                    }
+                    // Client doesn't support gzip — decompress before serving
+                    const plain = await gzipDecompress(entry.body);
+                    const headers = entry.headers.filter(([k]) => k.toLowerCase() !== 'content-encoding');
+                    return new Response(plain.buffer as ArrayBuffer, { status: entry.status, headers });
+                }
+                store.delete(key);
+            }
+        }
+
+        const res = await handler(req, ctx);
+
+        // Compress and cache in the background via clone() so the original
+        // stream is returned to the client immediately.
+        if (key != null && res) {
+            const ttl = cacheOpts?.ttl;
+            res.clone().arrayBuffer().then(async (buf) => {
+                const body = await gzipCompress(new Uint8Array(buf));
+                const headers: [string, string][] = [];
+                res.headers.forEach((v, k) => {
+                    if (k.toLowerCase() !== 'content-encoding' && k.toLowerCase() !== 'content-length') {
+                        headers.push([k, v]);
+                    }
+                });
+                headers.push(['content-encoding', 'gzip']);
+                store.set(key, {
+                    body,
+                    status: res.status,
+                    headers,
+                    expiresAt: ttl != null ? Date.now() + ttl : null,
+                });
+            }).catch(() => { /* ignore read errors on clone */ });
+        }
+
+        return res;
+    };
+}
+
 interface HadarsRuntimeOptions extends HadarsOptions {
     mode: "development" | "production";
 }
@@ -319,7 +423,7 @@ export const dev = async (options: HadarsRuntimeOptions) => {
     await fs.writeFile(tmpFilePath, clientScript);
 
     // SSR live-reload id to force re-import
-    let ssrBuildId = Date.now();
+    let ssrBuildId = crypto.randomBytes(4).toString('hex');
 
     // Start rspack-dev-server for the client bundle. It provides true React
     // Fast Refresh HMR: the browser's HMR runtime connects directly to the
@@ -435,7 +539,7 @@ export const dev = async (options: HadarsRuntimeOptions) => {
                     const chunk = decoder.decode(value, { stream: true });
                     try { process.stdout.write(chunk); } catch (e) { }
                     if (chunk.includes(rebuildMarker)) {
-                        ssrBuildId = Date.now();
+                        ssrBuildId = crypto.randomBytes(4).toString('hex');
                         console.log('[hadars] SSR bundle updated, build id:', ssrBuildId);
                     }
                 }
@@ -491,25 +595,34 @@ export const dev = async (options: HadarsRuntimeOptions) => {
         // (cache-busting key) rather than a literal filename character on Linux.
         const importPath = pathToFileURL(ssrComponentPath).href + `?t=${ssrBuildId}`;
 
-        const {
-            default: Component,
-            getInitProps,
-            getAfterRenderProps,
-            getFinalProps,
-        } = (await import(importPath)) as HadarsEntryModule<any>;
-
-        const { ReactPage, status, headHtml, renderPayload } = await getReactResponse(request, {
-            document: {
-                body: Component as React.FC<HadarsProps<object>>,
-                lang: 'en',
+        try {
+            const {
+                default: Component,
                 getInitProps,
                 getAfterRenderProps,
                 getFinalProps,
-            },
-        });
+            } = (await import(importPath)) as HadarsEntryModule<any>;
+
+            const { ReactPage, status, headHtml, renderPayload } = await getReactResponse(request, {
+                document: {
+                    body: Component as React.FC<HadarsProps<object>>,
+                    lang: 'en',
+                    getInitProps,
+                    getAfterRenderProps,
+                    getFinalProps,
+                },
+            });
 
-        const unsuspend = (renderPayload.appProps.context as any)?._unsuspend ?? null;
-        return buildSsrResponse(ReactPage, headHtml, status, getPrecontentHtml, unsuspend);
+            const unsuspend = (renderPayload.appProps.context as any)?._unsuspend ?? null;
+            return buildSsrResponse(ReactPage, headHtml, status, getPrecontentHtml, unsuspend);
+        } catch (err: any) {
+            console.error('[hadars] SSR render error:', err);
+            const msg = (err?.stack ?? err?.message ?? String(err)).replace(/</g, '&lt;');
+            return new Response(`<!doctype html><pre style="white-space:pre-wrap">${msg}</pre>`, {
+                status: 500,
+                headers: { 'Content-Type': 'text/html; charset=utf-8' },
+            });
+        }
     }, options.websocket);
 };
 
@@ -616,7 +729,7 @@ export const run = async (options: HadarsRuntimeOptions) => {
         fs.readFile(pathMod.join(__dirname, StaticPath, 'out.html'), 'utf-8')
     );
 
-    await serve(port, async (req, ctx) => {
+    const runHandler: CacheFetchHandler = async (req, ctx) => {
         const request = parseRequest(req);
         if (handler) {
             const res = await handler(request);
@@ -656,35 +769,47 @@ export const run = async (options: HadarsRuntimeOptions) => {
         const componentPath = pathToFileURL(
             pathMod.resolve(__dirname, HadarsFolder, SSR_FILENAME)
         ).href;
-        const {
-            default: Component,
-            getInitProps,
-            getAfterRenderProps,
-            getFinalProps,
-        } = (await import(componentPath)) as HadarsEntryModule<any>;
-
-        if (renderPool) {
-            // 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);
-            const [precontentHtml, postContent] = await getPrecontentHtml(wHead);
-            return new Response(precontentHtml + html + postContent, {
-                headers: { 'Content-Type': 'text/html; charset=utf-8' },
-                status: wStatus,
-            });
-        }
 
-        const { ReactPage, status, headHtml, renderPayload } = await getReactResponse(request, {
-            document: {
-                body: Component as React.FC<HadarsProps<object>>,
-                lang: 'en',
+        try {
+            const {
+                default: Component,
                 getInitProps,
                 getAfterRenderProps,
                 getFinalProps,
-            },
-        });
+            } = (await import(componentPath)) as HadarsEntryModule<any>;
+
+            if (renderPool) {
+                // 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);
+                const [precontentHtml, postContent] = await getPrecontentHtml(wHead);
+                return new Response(precontentHtml + html + postContent, {
+                    headers: { 'Content-Type': 'text/html; charset=utf-8' },
+                    status: wStatus,
+                });
+            }
 
-        const unsuspend = (renderPayload.appProps.context as any)?._unsuspend ?? null;
-        return buildSsrResponse(ReactPage, headHtml, status, getPrecontentHtml, unsuspend);
-    }, options.websocket);
+            const { ReactPage, status, headHtml, renderPayload } = await getReactResponse(request, {
+                document: {
+                    body: Component as React.FC<HadarsProps<object>>,
+                    lang: 'en',
+                    getInitProps,
+                    getAfterRenderProps,
+                    getFinalProps,
+                },
+            });
+
+            const unsuspend = (renderPayload.appProps.context as any)?._unsuspend ?? null;
+            return buildSsrResponse(ReactPage, headHtml, status, getPrecontentHtml, unsuspend);
+        } catch (err: any) {
+            console.error('[hadars] SSR render error:', err);
+            return new Response('Internal Server Error', { status: 500 });
+        }
+    };
+
+    await serve(
+        port,
+        options.cache ? createRenderCache(options.cache, runHandler) : runHandler,
+        options.websocket,
+    );
 };

package/src/ssr-render-worker.ts

@@ -146,6 +146,9 @@ async function runFullLifecycle(serialReq: SerializableRequest) {
             await Promise.all(pending);
         }
     } while (unsuspend.hasPending && ++iters < 25);
+    if (unsuspend.hasPending) {
+        console.warn('[hadars] SSR render loop hit the 25-iteration cap — some useServerData values may not be resolved. Check for data dependencies that are never fulfilled.');
+    }
 
     props = getAfterRenderProps ? await getAfterRenderProps(props, html) : props;
 

package/src/types/ninety.ts

@@ -93,6 +93,24 @@ export interface HadarsOptions {
      * Has no effect on the SSR bundle or dev mode.
      */
     optimization?: Record<string, unknown>;
+    /**
+     * SSR response cache for `run()` mode. Has no effect in `dev()` mode.
+     *
+     * Receives the incoming request and should return `{ key, ttl? }` to cache
+     * the response, or `null`/`undefined` to skip caching for that request.
+     * `ttl` is the time-to-live in milliseconds; omit for entries that never expire.
+     * The function may be async.
+     *
+     * @example
+     * // Cache every page by pathname (no per-user personalisation):
+     * cache: (req) => ({ key: req.pathname })
+     *
+     * @example
+     * // Cache with a per-route TTL, skip authenticated requests:
+     * cache: (req) => req.cookies.session ? null : { key: req.pathname, ttl: 60_000 }
+     */
+    cache?: (req: HadarsRequest) => { key: string; ttl?: number } | null | undefined
+                                  | Promise<{ key: string; ttl?: number } | null | undefined>;
 }
 
 

package/src/utils/Head.tsx

@@ -175,8 +175,10 @@ export const useApp = () => React.useContext(AppContext);
 const clientServerDataCache = new Map<string, unknown>();
 
 /** Call this before hydrating to seed the client cache from the server's data.
- *  Invoked automatically by the hadars client bootstrap. */
+ *  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();
     for (const [k, v] of Object.entries(data)) {
         clientServerDataCache.set(k, v);
     }
@@ -208,7 +210,7 @@ export function initServerDataCache(data: Record<string, unknown>) {
  * if (!user) return null; // undefined while pending on the first SSR pass
  */
 export function useServerData<T>(key: string | string[], fn: () => Promise<T> | T): T | undefined {
-    const cacheKey = Array.isArray(key) ? key.join('\x00') : key;
+    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

package/src/utils/clientScript.tsx

@@ -32,8 +32,12 @@ const main = async () => {
 
     const { location } = props;
 
-    if ( appMod.getClientProps ) {
-        props = await appMod.getClientProps(props);
+    if (appMod.getClientProps) {
+        try {
+            props = await appMod.getClientProps(props);
+        } catch (err) {
+            console.error('[hadars] getClientProps threw an error:', err);
+        }
     }
 
     props = {