hadars 0.3.2 → 0.4.0

package/dist/utils/Head.tsx

@@ -134,7 +134,12 @@ function getCtx(): InnerContext | null {
 // ── useServerData ─────────────────────────────────────────────────────────────
 //
 // Client-side cache pre-populated from the server's resolved data before
-// hydration. Keyed by the same React useId() values that the server used.
+// hydration. During the initial SSR load, keyed by the server's useId() values
+// (which match React's hydrateRoot IDs). During client-side navigation the
+// server keys are _R_..._  (slim-react format) but the client is NOT in
+// hydration mode so useId() returns _r_..._  — a completely different format.
+// We bridge this by storing navigation results as an ordered array and consuming
+// them sequentially on the retry, then caching by the client's own useId() key.
 const clientServerDataCache = new Map<string, unknown>();
 
 // Tracks in-flight data-only requests keyed by pathname+search so that all
@@ -144,39 +149,21 @@ const pendingDataFetch = new Map<string, Promise<void>>();
 // 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);
-}
+// Ordered values from the most recent navigation fetch.
+// React retries suspended components in tree order (same order as SSR), so
+// consuming these positionally is safe and avoids the server/client key mismatch.
+let _navValues: unknown[] = [];
+let _navIdx = 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>();
+    _navValues = [];
+    _navIdx = 0;
     for (const [k, v] of Object.entries(data)) {
         clientServerDataCache.set(k, v);
-        ssrInitialKeys.add(k);
     }
 }
 
@@ -188,9 +175,8 @@ export function initServerDataCache(data: Record<string, unknown>) {
  * On the client the pre-resolved value is read from the hydration cache
  * serialised into the page by the server, so no fetch is issued in the browser.
  *
- * The `key` (string or array of strings) uniquely identifies the cached value
- * across all SSR render passes and client hydration — it must be stable and
- * unique within the page.
+ * The cache key is derived automatically from the call-site's position in the
+ * component tree via `useId()` — no manual key is required.
  *
  * `fn` may return a `Promise<T>` (async usage) or return `T` synchronously.
  * The resolved value is serialised into `__serverData` and returned from cache
@@ -202,29 +188,42 @@ export function initServerDataCache(data: Record<string, unknown>) {
  * React Suspense until the server returns the JSON map of resolved values.
  *
  * @example
- * const user = useServerData('current_user', () => db.getUser(id));
- * const post = useServerData(['post', postId], () => db.getPost(postId));
+ * const user = useServerData(() => db.getUser(id));
+ * const post = useServerData(() => db.getPost(postId));
  * if (!user) return null; // undefined while pending on the first SSR pass
+ *
+ * // cache: false — evicts the entry on unmount so the next mount fetches fresh data
+ * const stats = useServerData(() => getServerStats(), { cache: false });
  */
-export function useServerData<T>(key: string | string[], fn: () => Promise<T> | T): T | undefined {
-    const cacheKey = Array.isArray(key) ? JSON.stringify(key) : key;
+export function useServerData<T>(fn: () => Promise<T> | T, options?: { cache?: boolean }): T | undefined {
+    const cacheKey = React.useId();
+
+    // When cache: false, evict the entry on unmount so the next mount fetches
+    // fresh data from the server. The eviction is deferred via setTimeout so
+    // that React Strict Mode's synchronous fake-unmount/remount cycle can cancel
+    // it before it fires — a real unmount has no follow-up effect to cancel it.
+    const evictTimerRef = React.useRef<ReturnType<typeof setTimeout> | null>(null);
+    React.useEffect(() => {
+        if (options?.cache !== false) return;
+        // Cancel any timer left over from a Strict Mode fake unmount.
+        if (evictTimerRef.current !== null) {
+            clearTimeout(evictTimerRef.current);
+            evictTimerRef.current = null;
+        }
+        return () => {
+            evictTimerRef.current = setTimeout(() => {
+                clientServerDataCache.delete(cacheKey);
+                evictTimerRef.current = null;
+            }, 0);
+        };
+    }, []);
 
     if (typeof window !== 'undefined') {
-        // Cache hit — return the server-resolved value directly (covers both initial
-        // SSR hydration and values fetched during client-side navigation).
+        // Cache hit — return the server-resolved value directly.
         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
@@ -232,10 +231,23 @@ export function useServerData<T>(key: string | string[], fn: () => Promise<T> |
         // 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.
+        // After a navigation fetch has completed, consume values positionally.
+        // The server returns keys in slim-react (_R_..._) format, but the client
+        // is not in hydration mode so useId() returns _r_..._  — they never match.
+        // We store the ordered values from the fetch and hand them out in tree
+        // order (which is identical on server and client for a given route).
         if (fetchedPaths.has(pathKey)) {
-            return undefined;
+            if (_navIdx < _navValues.length) {
+                const value = _navValues[_navIdx++] as T;
+                clientServerDataCache.set(cacheKey, value);
+                return value;
+            }
+            // Positional data exhausted — cache:false eviction or remount with new
+            // useId() keys. Remove the path so a fresh fetch fires below.
+            fetchedPaths.delete(pathKey);
+            _navValues = [];
+            _navIdx = 0;
+            // fall through to trigger a new fetch
         }
 
         if (!pendingDataFetch.has(pathKey)) {
@@ -261,9 +273,14 @@ export function useServerData<T>(key: string | string[], fn: () => Promise<T> |
                         if (res.ok) json = await res.json();
                     }
 
-                    for (const [k, v] of Object.entries(json?.serverData ?? {})) {
-                        clientServerDataCache.set(k, v);
-                    }
+                    // Store as ordered array — consumed positionally on retry to
+                    // avoid the server (_R_..._) vs client (_r_..._) key mismatch.
+                    _navValues = Object.values(json?.serverData ?? {});
+                    _navIdx = 0;
+                    // Only keep the freshly-fetched path in fetchedPaths — clear
+                    // others so stale positional data from a previous page cannot
+                    // be served if the user navigates back to it.
+                    fetchedPaths.clear();
                 } finally {
                     fetchedPaths.add(pathKey);
                     pendingDataFetch.delete(pathKey);
@@ -281,22 +298,8 @@ export function useServerData<T>(key: string | string[], fn: () => Promise<T> |
     const unsuspend: AppUnsuspend | undefined = (globalThis as any).__hadarsUnsuspend;
     if (!unsuspend) return undefined;
 
-    // ── unstable-key detection ───────────────────────────────────────────────
-    // Track the last key thrown as a pending promise and whether it was accessed
-    // as a cache hit in the current pass. If a new pending entry appears while
-    // the previous pending key resolved but was never requested, the key is
-    // changing between passes (e.g. Date.now() or Math.random() in the key).
-    const _u = unsuspend as any;
-    if (!_u.pendingCreated) _u.pendingCreated = 0;
-    // ────────────────────────────────────────────────────────────────────────
-
     const existing = unsuspend.cache.get(cacheKey);
 
-    // Mark the previous pending key as accessed when it appears as a cache hit.
-    if (existing?.status === 'fulfilled' && _u.lastPendingKey === cacheKey) {
-        _u.lastPendingKeyAccessed = true;
-    }
-
     if (!existing) {
         // First encounter — call fn(), which may:
         //   (a) return a Promise<T>  — async usage (serialised for the client)
@@ -313,35 +316,6 @@ export function useServerData<T>(key: string | string[], fn: () => Promise<T> |
         }
 
         // (a) Async Promise — standard useServerData usage.
-
-        // Unstable-key detection: the previous pending key resolved but was never
-        // requested in the current pass — a new key replaced it, which means the
-        // key is not stable between render passes.
-        if (_u.lastPendingKey != null && !_u.lastPendingKeyAccessed) {
-            const prev = unsuspend.cache.get(_u.lastPendingKey);
-            if (prev?.status === 'fulfilled') {
-                throw new Error(
-                    `[hadars] useServerData: key ${JSON.stringify(cacheKey)} is not stable between render passes. ` +
-                    `The previous pass resolved ${JSON.stringify(_u.lastPendingKey)} but it was not ` +
-                    `requested in this pass — the key is changing between renders. ` +
-                    `Avoid dynamic values in keys (e.g. Date.now() or Math.random()); ` +
-                    `use stable, deterministic identifiers instead.`,
-                );
-            }
-        }
-
-        _u.pendingCreated++;
-        if (_u.pendingCreated > 100) {
-            throw new Error(
-                `[hadars] useServerData: more than 100 async keys created in a single render. ` +
-                `This usually means a key is not stable between renders (e.g. it contains ` +
-                `Date.now() or Math.random()). Currently offending key: ${JSON.stringify(cacheKey)}.`,
-            );
-        }
-
-        _u.lastPendingKey = cacheKey;
-        _u.lastPendingKeyAccessed = false;
-
         const promise = (result as Promise<T>).then(
             value => { unsuspend.cache.set(cacheKey, { status: 'fulfilled', value }); },
             reason => { unsuspend.cache.set(cacheKey, { status: 'rejected', reason }); },
@@ -363,26 +337,6 @@ export function useServerData<T>(key: string | string[], fn: () => Promise<T> |
 // is stored in globalThis.__hadarsGraphQL by the framework before each render.
 // On the client, useServerData handles hydration + client-side navigation.
 
-/**
- * Derive a stable cache key string from a query argument.
- * For string queries the key is the trimmed query string.
- * For document nodes we use the operation name when available (fast, concise)
- * and fall back to stringifying the definitions (always stable).
- * The key is ONLY used for cache lookup — the original document is passed to
- * the executor so it can call print() itself.
- */
-function toCacheKey(doc: any): string {
-    if (typeof doc === 'string') return doc.trim();
-    // Use the operation name for named operations — compact and stable.
-    for (const def of doc?.definitions ?? []) {
-        if (def.kind === 'OperationDefinition' && def.name?.value) {
-            return `op:${def.name.value}`;
-        }
-    }
-    // Anonymous operation — fall back to stringifying definitions.
-    return JSON.stringify(doc?.definitions ?? doc);
-}
-
 /**
  * Execute a GraphQL query server-side and return the result.
  *
@@ -421,9 +375,7 @@ export function useGraphQL(
     query: string | HadarsDocumentNode<unknown, Record<string, unknown>>,
     variables?: Record<string, unknown>,
 ): { data?: unknown } | undefined {
-    const key = ['__gql', toCacheKey(query), JSON.stringify(variables ?? {})];
-
-    return useServerData(key, async () => {
+    return useServerData(async () => {
         const executor: ((q: any, v?: Record<string, unknown>) => Promise<any>) | undefined =
             (globalThis as any).__hadarsGraphQL;
 

package/package.json

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

package/src/build.ts

@@ -575,6 +575,7 @@ export const dev = async (options: HadarsRuntimeOptions) => {
             return buildSsrResponse(head, status, getAppBody, finalize, getPrecontentHtml);
         } catch (err: any) {
             console.error('[hadars] SSR render error:', err);
+            options.onError?.(err, request)?.catch?.(() => {});
             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,
@@ -783,6 +784,7 @@ export const run = async (options: HadarsRuntimeOptions) => {
             return buildSsrResponse(head, status, getAppBody, finalize, getPrecontentHtml);
         } catch (err: any) {
             console.error('[hadars] SSR render error:', err);
+            options.onError?.(err, request)?.catch?.(() => {});
             return new Response('Internal Server Error', { status: 500 });
         }
     };

package/src/cloudflare.ts

@@ -123,6 +123,7 @@ export function createCloudflareHandler(
             });
         } catch (err: any) {
             console.error('[hadars] SSR render error:', err);
+            options.onError?.(err, request)?.catch?.(() => {});
             return new Response('Internal Server Error', { status: 500 });
         }
     };

package/src/lambda.ts

@@ -270,6 +270,7 @@ export function createLambdaHandler(options: HadarsOptions, bundled?: LambdaBund
             });
         } catch (err: any) {
             console.error('[hadars] SSR render error:', err);
+            options.onError?.(err, request)?.catch?.(() => {});
             return new Response('Internal Server Error', { status: 500 });
         }
     };

package/src/types/hadars.ts

@@ -294,6 +294,23 @@ export interface HadarsOptions {
      * ]
      */
     sources?: HadarsSourceEntry[];
+    /**
+     * Called whenever an SSR render error is caught, in both `dev()` and `run()` mode
+     * as well as the Lambda and Cloudflare adapters.
+     *
+     * Use this to forward errors to your monitoring service (Sentry, Datadog, etc.)
+     * without affecting the response sent to the browser.
+     * The handler may be async — hadars fires it and does not await the result,
+     * so it never delays the error response.
+     *
+     * @example
+     * import * as Sentry from '@sentry/node';
+     * onError: (err, req) => Sentry.captureException(err, { extra: { url: req.url } })
+     *
+     * @example
+     * onError: (err, req) => console.error('[myapp]', req.method, req.url, err)
+     */
+    onError?: (err: Error, req: Request) => void | Promise<void>;
 }
 
 /**

package/src/utils/Head.tsx

@@ -134,7 +134,12 @@ function getCtx(): InnerContext | null {
 // ── useServerData ─────────────────────────────────────────────────────────────
 //
 // Client-side cache pre-populated from the server's resolved data before
-// hydration. Keyed by the same React useId() values that the server used.
+// hydration. During the initial SSR load, keyed by the server's useId() values
+// (which match React's hydrateRoot IDs). During client-side navigation the
+// server keys are _R_..._  (slim-react format) but the client is NOT in
+// hydration mode so useId() returns _r_..._  — a completely different format.
+// We bridge this by storing navigation results as an ordered array and consuming
+// them sequentially on the retry, then caching by the client's own useId() key.
 const clientServerDataCache = new Map<string, unknown>();
 
 // Tracks in-flight data-only requests keyed by pathname+search so that all
@@ -144,39 +149,21 @@ const pendingDataFetch = new Map<string, Promise<void>>();
 // 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);
-}
+// Ordered values from the most recent navigation fetch.
+// React retries suspended components in tree order (same order as SSR), so
+// consuming these positionally is safe and avoids the server/client key mismatch.
+let _navValues: unknown[] = [];
+let _navIdx = 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>();
+    _navValues = [];
+    _navIdx = 0;
     for (const [k, v] of Object.entries(data)) {
         clientServerDataCache.set(k, v);
-        ssrInitialKeys.add(k);
     }
 }
 
@@ -188,9 +175,8 @@ export function initServerDataCache(data: Record<string, unknown>) {
  * On the client the pre-resolved value is read from the hydration cache
  * serialised into the page by the server, so no fetch is issued in the browser.
  *
- * The `key` (string or array of strings) uniquely identifies the cached value
- * across all SSR render passes and client hydration — it must be stable and
- * unique within the page.
+ * The cache key is derived automatically from the call-site's position in the
+ * component tree via `useId()` — no manual key is required.
  *
  * `fn` may return a `Promise<T>` (async usage) or return `T` synchronously.
  * The resolved value is serialised into `__serverData` and returned from cache
@@ -202,29 +188,42 @@ export function initServerDataCache(data: Record<string, unknown>) {
  * React Suspense until the server returns the JSON map of resolved values.
  *
  * @example
- * const user = useServerData('current_user', () => db.getUser(id));
- * const post = useServerData(['post', postId], () => db.getPost(postId));
+ * const user = useServerData(() => db.getUser(id));
+ * const post = useServerData(() => db.getPost(postId));
  * if (!user) return null; // undefined while pending on the first SSR pass
+ *
+ * // cache: false — evicts the entry on unmount so the next mount fetches fresh data
+ * const stats = useServerData(() => getServerStats(), { cache: false });
  */
-export function useServerData<T>(key: string | string[], fn: () => Promise<T> | T): T | undefined {
-    const cacheKey = Array.isArray(key) ? JSON.stringify(key) : key;
+export function useServerData<T>(fn: () => Promise<T> | T, options?: { cache?: boolean }): T | undefined {
+    const cacheKey = React.useId();
+
+    // When cache: false, evict the entry on unmount so the next mount fetches
+    // fresh data from the server. The eviction is deferred via setTimeout so
+    // that React Strict Mode's synchronous fake-unmount/remount cycle can cancel
+    // it before it fires — a real unmount has no follow-up effect to cancel it.
+    const evictTimerRef = React.useRef<ReturnType<typeof setTimeout> | null>(null);
+    React.useEffect(() => {
+        if (options?.cache !== false) return;
+        // Cancel any timer left over from a Strict Mode fake unmount.
+        if (evictTimerRef.current !== null) {
+            clearTimeout(evictTimerRef.current);
+            evictTimerRef.current = null;
+        }
+        return () => {
+            evictTimerRef.current = setTimeout(() => {
+                clientServerDataCache.delete(cacheKey);
+                evictTimerRef.current = null;
+            }, 0);
+        };
+    }, []);
 
     if (typeof window !== 'undefined') {
-        // Cache hit — return the server-resolved value directly (covers both initial
-        // SSR hydration and values fetched during client-side navigation).
+        // Cache hit — return the server-resolved value directly.
         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
@@ -232,10 +231,23 @@ export function useServerData<T>(key: string | string[], fn: () => Promise<T> |
         // 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.
+        // After a navigation fetch has completed, consume values positionally.
+        // The server returns keys in slim-react (_R_..._) format, but the client
+        // is not in hydration mode so useId() returns _r_..._  — they never match.
+        // We store the ordered values from the fetch and hand them out in tree
+        // order (which is identical on server and client for a given route).
         if (fetchedPaths.has(pathKey)) {
-            return undefined;
+            if (_navIdx < _navValues.length) {
+                const value = _navValues[_navIdx++] as T;
+                clientServerDataCache.set(cacheKey, value);
+                return value;
+            }
+            // Positional data exhausted — cache:false eviction or remount with new
+            // useId() keys. Remove the path so a fresh fetch fires below.
+            fetchedPaths.delete(pathKey);
+            _navValues = [];
+            _navIdx = 0;
+            // fall through to trigger a new fetch
         }
 
         if (!pendingDataFetch.has(pathKey)) {
@@ -261,9 +273,14 @@ export function useServerData<T>(key: string | string[], fn: () => Promise<T> |
                         if (res.ok) json = await res.json();
                     }
 
-                    for (const [k, v] of Object.entries(json?.serverData ?? {})) {
-                        clientServerDataCache.set(k, v);
-                    }
+                    // Store as ordered array — consumed positionally on retry to
+                    // avoid the server (_R_..._) vs client (_r_..._) key mismatch.
+                    _navValues = Object.values(json?.serverData ?? {});
+                    _navIdx = 0;
+                    // Only keep the freshly-fetched path in fetchedPaths — clear
+                    // others so stale positional data from a previous page cannot
+                    // be served if the user navigates back to it.
+                    fetchedPaths.clear();
                 } finally {
                     fetchedPaths.add(pathKey);
                     pendingDataFetch.delete(pathKey);
@@ -281,22 +298,8 @@ export function useServerData<T>(key: string | string[], fn: () => Promise<T> |
     const unsuspend: AppUnsuspend | undefined = (globalThis as any).__hadarsUnsuspend;
     if (!unsuspend) return undefined;
 
-    // ── unstable-key detection ───────────────────────────────────────────────
-    // Track the last key thrown as a pending promise and whether it was accessed
-    // as a cache hit in the current pass. If a new pending entry appears while
-    // the previous pending key resolved but was never requested, the key is
-    // changing between passes (e.g. Date.now() or Math.random() in the key).
-    const _u = unsuspend as any;
-    if (!_u.pendingCreated) _u.pendingCreated = 0;
-    // ────────────────────────────────────────────────────────────────────────
-
     const existing = unsuspend.cache.get(cacheKey);
 
-    // Mark the previous pending key as accessed when it appears as a cache hit.
-    if (existing?.status === 'fulfilled' && _u.lastPendingKey === cacheKey) {
-        _u.lastPendingKeyAccessed = true;
-    }
-
     if (!existing) {
         // First encounter — call fn(), which may:
         //   (a) return a Promise<T>  — async usage (serialised for the client)
@@ -313,35 +316,6 @@ export function useServerData<T>(key: string | string[], fn: () => Promise<T> |
         }
 
         // (a) Async Promise — standard useServerData usage.
-
-        // Unstable-key detection: the previous pending key resolved but was never
-        // requested in the current pass — a new key replaced it, which means the
-        // key is not stable between render passes.
-        if (_u.lastPendingKey != null && !_u.lastPendingKeyAccessed) {
-            const prev = unsuspend.cache.get(_u.lastPendingKey);
-            if (prev?.status === 'fulfilled') {
-                throw new Error(
-                    `[hadars] useServerData: key ${JSON.stringify(cacheKey)} is not stable between render passes. ` +
-                    `The previous pass resolved ${JSON.stringify(_u.lastPendingKey)} but it was not ` +
-                    `requested in this pass — the key is changing between renders. ` +
-                    `Avoid dynamic values in keys (e.g. Date.now() or Math.random()); ` +
-                    `use stable, deterministic identifiers instead.`,
-                );
-            }
-        }
-
-        _u.pendingCreated++;
-        if (_u.pendingCreated > 100) {
-            throw new Error(
-                `[hadars] useServerData: more than 100 async keys created in a single render. ` +
-                `This usually means a key is not stable between renders (e.g. it contains ` +
-                `Date.now() or Math.random()). Currently offending key: ${JSON.stringify(cacheKey)}.`,
-            );
-        }
-
-        _u.lastPendingKey = cacheKey;
-        _u.lastPendingKeyAccessed = false;
-
         const promise = (result as Promise<T>).then(
             value => { unsuspend.cache.set(cacheKey, { status: 'fulfilled', value }); },
             reason => { unsuspend.cache.set(cacheKey, { status: 'rejected', reason }); },
@@ -363,26 +337,6 @@ export function useServerData<T>(key: string | string[], fn: () => Promise<T> |
 // is stored in globalThis.__hadarsGraphQL by the framework before each render.
 // On the client, useServerData handles hydration + client-side navigation.
 
-/**
- * Derive a stable cache key string from a query argument.
- * For string queries the key is the trimmed query string.
- * For document nodes we use the operation name when available (fast, concise)
- * and fall back to stringifying the definitions (always stable).
- * The key is ONLY used for cache lookup — the original document is passed to
- * the executor so it can call print() itself.
- */
-function toCacheKey(doc: any): string {
-    if (typeof doc === 'string') return doc.trim();
-    // Use the operation name for named operations — compact and stable.
-    for (const def of doc?.definitions ?? []) {
-        if (def.kind === 'OperationDefinition' && def.name?.value) {
-            return `op:${def.name.value}`;
-        }
-    }
-    // Anonymous operation — fall back to stringifying definitions.
-    return JSON.stringify(doc?.definitions ?? doc);
-}
-
 /**
  * Execute a GraphQL query server-side and return the result.
  *
@@ -421,9 +375,7 @@ export function useGraphQL(
     query: string | HadarsDocumentNode<unknown, Record<string, unknown>>,
     variables?: Record<string, unknown>,
 ): { data?: unknown } | undefined {
-    const key = ['__gql', toCacheKey(query), JSON.stringify(variables ?? {})];
-
-    return useServerData(key, async () => {
+    return useServerData(async () => {
         const executor: ((q: any, v?: Record<string, unknown>) => Promise<any>) | undefined =
             (globalThis as any).__hadarsGraphQL;
 

package/src/utils/loader.ts

@@ -99,11 +99,11 @@ function swcTransform(this: any, swc: any, source: string, isServer: boolean, re
 
         const name: string = callee.value;
 
-        // ── useServerData(key, fn) — strip fn on client builds ────────────────
+        // ── useServerData(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];
+            if (!args || args.length < 1) return;
+            const fnArg = args[0].expression ?? args[0];
             // Normalise to 0-based local byte offsets and replace with stub.
             replacements.push({
                 start: fnArg.span.start - fileOffset,
@@ -278,7 +278,7 @@ function scanExpressionEnd(source: string, pos: number): number {
 }
 
 /**
- * Strip the `fn` argument from `useServerData(key, fn)` calls in client builds.
+ * Strip the `fn` argument from `useServerData(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.).
  */
@@ -290,16 +290,8 @@ function stripUseServerDataFns(source: string): string {
     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
+        // Skip whitespace before fn arg
         while (i < source.length && /\s/.test(source[i]!)) i++;
         const fnStart = i;
         // Scan to end of fn argument