hadars 0.2.0 → 0.2.2-rc.0

package/src/static.ts

@@ -0,0 +1,106 @@
+/**
+ * Static site export core — rendering and file I/O.
+ *
+ * Imported by cli-lib.ts (bundled into dist/cli.js via esbuild) and by tests.
+ * Has no dependency on the rspack build pipeline — only SSR utilities.
+ */
+
+import { cp, mkdir, writeFile } from 'node:fs/promises';
+import { join, dirname, basename } from 'node:path';
+import { parseRequest } from './utils/request';
+import { getReactResponse, buildHeadHtml } from './utils/response';
+import { buildSsrHtml, makePrecontentHtmlGetter } from './utils/ssrHandler';
+import type { HadarsEntryModule, HadarsStaticContext, GraphQLExecutor } from './types/hadars';
+
+export interface StaticRenderResult {
+    /** URL paths that were successfully rendered. */
+    rendered: string[];
+    /** Paths that failed, with the caught error. */
+    errors: Array<{ path: string; error: Error }>;
+}
+
+/**
+ * Pre-renders a list of URL paths to HTML files and copies static assets.
+ *
+ * Pages are rendered serially — `getReactResponse` writes to
+ * `globalThis.__hadarsUnsuspend / __hadarsContext` which are not re-entrant-safe.
+ */
+export async function renderStaticSite(opts: {
+    ssrModule:   HadarsEntryModule<any>;
+    htmlSource:  string;
+    staticSrc:   string;
+    paths:       string[];
+    outputDir:   string;
+    graphql?:    GraphQLExecutor;
+}): Promise<StaticRenderResult> {
+    const { ssrModule, htmlSource, staticSrc, paths, outputDir } = opts;
+
+    const staticCtx: HadarsStaticContext = {
+        graphql: opts.graphql ?? (() => Promise.reject(
+            new Error('[hadars] No graphql executor configured. Add a `graphql` function to your hadars.config.'),
+        )),
+    };
+    const getPrecontentHtml = makePrecontentHtmlGetter(Promise.resolve(htmlSource));
+
+    await mkdir(outputDir, { recursive: true });
+
+    const rendered: string[] = [];
+    const errors: Array<{ path: string; error: Error }> = [];
+
+    for (const urlPath of paths) {
+        try {
+            const req = parseRequest(new Request('http://localhost' + urlPath));
+
+            const { head, getAppBody, finalize } = await getReactResponse(req, {
+                document: {
+                    body:          ssrModule.default as any,
+                    getInitProps:  ssrModule.getInitProps,
+                    getFinalProps: ssrModule.getFinalProps,
+                },
+                staticCtx,
+            });
+
+            const bodyHtml        = await getAppBody();
+            const { clientProps } = await finalize();
+            const headHtml        = buildHeadHtml(head);
+            // Inject a flag so the client knows it's a static export and should
+            // fetch index.json sidecars directly instead of hitting a live server.
+            const staticClientProps = { ...clientProps, __hadarsStatic: true };
+            const html = await buildSsrHtml(bodyHtml, staticClientProps, headHtml, getPrecontentHtml);
+
+            // '/'      → <outputDir>/index.html
+            // '/about' → <outputDir>/about/index.html
+            const cleanPath = urlPath.replace(/\/$/, '');
+            const pageDir   = cleanPath === '' ? outputDir : join(outputDir, cleanPath);
+            await mkdir(pageDir, { recursive: true });
+            await writeFile(join(pageDir, 'index.html'), html, 'utf-8');
+
+            // Write a JSON sidecar so useServerData can hydrate on client-side
+            // navigation without a live server. The format matches the live
+            // server's Accept: application/json response: { serverData: {...} }.
+            const serverData = (staticClientProps as any).__serverData ?? {};
+            await writeFile(
+                join(pageDir, 'index.json'),
+                JSON.stringify({ serverData }),
+                'utf-8',
+            );
+
+            rendered.push(urlPath);
+        } catch (err: any) {
+            errors.push({
+                path:  urlPath,
+                error: err instanceof Error ? err : new Error(String(err)),
+            });
+        }
+    }
+
+    // Copy .hadars/static/ → <outputDir>/static/, excluding the SSR template.
+    const staticDest = join(outputDir, 'static');
+    await mkdir(staticDest, { recursive: true });
+    await cp(staticSrc, staticDest, {
+        recursive: true,
+        filter: (src: string) => basename(src) !== 'out.html',
+    });
+
+    return { rendered, errors };
+}

package/src/types/hadars.ts

@@ -1,6 +1,35 @@
 import type { LinkHTMLAttributes, MetaHTMLAttributes, ScriptHTMLAttributes, StyleHTMLAttributes } from "react";
 
-export type HadarsGetInitialProps<T extends {}> = (req: HadarsRequest) => Promise<T> | T;
+/**
+ * In-process GraphQL executor passed to `getInitProps` and `paths` during
+ * `hadars export static`. Hadars is executor-agnostic — configure it in
+ * `hadars.config.ts` using any GraphQL library (e.g. `graphql-js`):
+ *
+ * ```ts
+ * import { graphql as gql, buildSchema } from 'graphql';
+ * const schema = buildSchema(`type Query { hello: String }`);
+ * const rootValue = { hello: () => 'world' };
+ *
+ * export default {
+ *   graphql: (query, variables) =>
+ *     gql({ schema, rootValue, source: query, variableValues: variables }),
+ * } satisfies HadarsOptions;
+ * ```
+ */
+export type GraphQLExecutor = (
+    query: string,
+    variables?: Record<string, unknown>,
+) => Promise<{ data?: any; errors?: ReadonlyArray<{ message: string }> }>;
+
+/**
+ * Context passed as the second argument to `getInitProps` and `paths`
+ * during `hadars export static`. Not present in dev/run mode.
+ */
+export interface HadarsStaticContext {
+    graphql: GraphQLExecutor;
+}
+
+export type HadarsGetInitialProps<T extends {}> = (req: HadarsRequest, ctx?: HadarsStaticContext) => Promise<T> | T;
 export type HadarsGetClientProps<T extends {}> = (props: T) => Promise<T> | T;
 export type HadarsGetFinalProps<T extends {}> = (props: HadarsProps<T>) => Promise<T> | T;
 export type HadarsApp<T extends {}> = React.FC<HadarsProps<T>>;
@@ -40,7 +69,6 @@ export interface AppContext {
 
 export type HadarsEntryBase = {
     location: string;
-    context: AppContext;
 }
 
 export type HadarsProps<T extends {}> = T & HadarsEntryBase;
@@ -181,6 +209,67 @@ export interface HadarsOptions {
      */
     cache?: (req: HadarsRequest) => { key: string; ttl?: number } | null | undefined
                                   | Promise<{ key: string; ttl?: number } | null | undefined>;
+    /**
+     * Static export path list. Required for `hadars export static`.
+     *
+     * Return an array of URL paths (e.g. `['/', '/about', '/blog/hello']`) that
+     * should be pre-rendered to HTML files. May be async.
+     *
+     * @example
+     * paths: () => ['/', '/about', '/contact']
+     *
+     * @example
+     * paths: async () => {
+     *   const posts = await fetchBlogPosts();
+     *   return ['/', ...posts.map(p => `/blog/${p.slug}`)];
+     * }
+     */
+    /**
+     * In-process GraphQL executor. Supply this to use the GraphQL data layer
+     * in `paths` and `getInitProps` during `hadars export static`.
+     * Has no effect in `dev` / `run` mode.
+     */
+    graphql?: GraphQLExecutor;
+    paths?: (ctx: HadarsStaticContext) => Promise<string[]> | string[];
+    /**
+     * Gatsby-compatible source plugins to run before `hadars export static`.
+     *
+     * Each entry mirrors Gatsby's `gatsby-config.js` plugin object format:
+     * `{ resolve: 'gatsby-source-contentful', options: { spaceId: '...', accessToken: '...' } }`
+     *
+     * The plugin must export a `sourceNodes` function with the standard Gatsby API.
+     * Hadars provides a thin shim covering the most-used surface:
+     * `actions.createNode`, `createNodeId`, `createContentDigest`, `cache`, `reporter`,
+     * `getNode`, `getNodes`, `getNodesByType`.
+     *
+     * After all sources have run, hadars auto-generates a GraphQL schema from the
+     * collected nodes and makes it available via `config.graphql` in `getInitProps`
+     * and `paths`. Requires `graphql` to be installed in the project.
+     *
+     * @example
+     * sources: [
+     *   {
+     *     resolve: 'gatsby-source-filesystem',
+     *     options: { name: 'posts', path: './content/posts' },
+     *   },
+     * ]
+     */
+    sources?: HadarsSourceEntry[];
+}
+
+/**
+ * A Gatsby-compatible source plugin entry, matching the format used in
+ * `gatsby-config.js` / `gatsby-config.ts`.
+ */
+export interface HadarsSourceEntry {
+    /**
+     * Package name (e.g. `'gatsby-source-contentful'`) or a pre-imported module
+     * object that exports `sourceNodes`. Using a module object lets you pass
+     * local source plugins without publishing them to npm.
+     */
+    resolve: string | { sourceNodes?: (ctx: any, opts?: any) => Promise<void> | void };
+    /** Plugin options forwarded as the second argument to `sourceNodes`. */
+    options?: Record<string, unknown>;
 }
 
 

package/src/utils/Head.tsx

@@ -1,5 +1,5 @@
 import React from 'react';
-import type { AppContext as HadarsAppContext, AppUnsuspend, LinkProps, MetaProps, ScriptProps, StyleProps } from '../types/hadars'
+import type { AppHead, AppUnsuspend, LinkProps, MetaProps, ScriptProps, StyleProps } from '../types/hadars'
 
 interface InnerContext {
     setTitle: (title: string) => void;
@@ -41,142 +41,95 @@ function deriveKey(tag: string, props: Record<string, any>): string {
     }
 }
 
-const AppContext = React.createContext<InnerContext>({
-    setTitle: () => {
-        console.warn('AppContext: setTitle called outside of provider');
-    },
-    addMeta: () => {
-        console.warn('AppContext: addMeta called outside of provider');
-    },
-    addLink: () => {
-        console.warn('AppContext: addLink called outside of provider');
-    },
-    addStyle: () => {
-        console.warn('AppContext: addStyle called outside of provider');
-    },
-    addScript: () => {
-        console.warn('AppContext: addScript called outside of provider');
-    },
-    setStatus: () => { },
-});
-
-export const AppProviderSSR: React.FC<{
-    children: React.ReactNode,
-    context: HadarsAppContext,
-}> = React.memo( ({ children, context }) => {
-
-    const { head } = context;
-
-    // mutate seoData
-    const setTitle = React.useCallback((title: string) => {
-        head.title = title;
-    }, [head]);
-    const addMeta = React.useCallback((props: MetaProps) => {
-        head.meta[deriveKey('meta', props as any)] = props;
-    }, [head]);
-    const addLink = React.useCallback((props: LinkProps) => {
-        head.link[deriveKey('link', props as any)] = props;
-    }, [head]);
-    const addStyle = React.useCallback((props: StyleProps) => {
-        head.style[deriveKey('style', props as any)] = props;
-    }, [head]);
-    const addScript = React.useCallback((props: ScriptProps) => {
-        head.script[deriveKey('script', props as any)] = props;
-    }, [head]);
-
-    const setStatus = React.useCallback((status: number) => {
-        head.status = status;
-    }, [head]);
-
-    const contextValue: InnerContext = React.useMemo(() => ({
-        setTitle,
-        addMeta,
-        addLink,
-        addStyle,
-        addScript,
-        setStatus,
-    }), [ setTitle, addMeta, addLink, addStyle, addScript, setStatus]);
-    return (
-        <AppContext.Provider value={contextValue}>
-            {children}
-        </AppContext.Provider>
-    );
-} );
+// ── Head context resolution ──────────────────────────────────────────────────
+//
+// On the server, HadarsHead reads from globalThis.__hadarsContext.head which
+// the SSR render worker populates before every renderToString call.
+// On the client, HadarsHead directly manipulates the DOM.
+// This approach means users do NOT need to wrap their App with HadarsContext.
+
+const LINK_ATTR: Record<string, string> = {
+    crossOrigin: 'crossorigin',
+    referrerPolicy: 'referrerpolicy',
+    fetchPriority: 'fetchpriority',
+    hrefLang: 'hreflang',
+};
+
+function makeServerCtx(head: AppHead): InnerContext {
+    return {
+        setTitle:  (t) => { head.title = t; },
+        addMeta:   (p) => { head.meta[deriveKey('meta', p as any)]     = p; },
+        addLink:   (p) => { head.link[deriveKey('link', p as any)]     = p; },
+        addStyle:  (p) => { head.style[deriveKey('style', p as any)]   = p; },
+        addScript: (p) => { head.script[deriveKey('script', p as any)] = p; },
+        setStatus: (s) => { head.status = s; },
+    };
+}
 
-export const AppProviderCSR: React.FC<{
-    children: React.ReactNode
-}> = React.memo( ({ children }) => {
-
-    const setTitle = React.useCallback((title: string) => {
-        document.title = title;
-    }, []);
-
-    const addMeta = React.useCallback((props: MetaProps) => {
-        const p = props as Record<string, any>;
-        let meta: HTMLMetaElement | null = null;
-        if (p.name) meta = document.querySelector(`meta[name="${CSS.escape(p.name)}"]`);
-        else if (p.property) meta = document.querySelector(`meta[property="${CSS.escape(p.property)}"]`);
-        else if (p.httpEquiv ?? p['http-equiv']) meta = document.querySelector(`meta[http-equiv="${CSS.escape(p.httpEquiv ?? p['http-equiv'])}"]`);
-        else if ('charSet' in p || 'charset' in p) meta = document.querySelector('meta[charset]');
-        if (!meta) { meta = document.createElement('meta'); document.head.appendChild(meta); }
-        for (const [k, v] of Object.entries(p)) {
-            if (v != null && v !== false) meta.setAttribute(k === 'charSet' ? 'charset' : k === 'httpEquiv' ? 'http-equiv' : k, String(v));
-        }
-    }, []);
-
-    const addLink = React.useCallback((props: LinkProps) => {
-        const p = props as Record<string, any>;
-        let link: HTMLLinkElement | null = null;
-        const asSel = p.as ? `[as="${CSS.escape(p.as)}"]` : '';
-        if (p.rel && p.href) link = document.querySelector(`link[rel="${CSS.escape(p.rel)}"][href="${CSS.escape(p.href)}"]${asSel}`);
-        else if (p.rel) link = document.querySelector(`link[rel="${CSS.escape(p.rel)}"]${asSel}`);
-        if (!link) { link = document.createElement('link'); document.head.appendChild(link); }
-        const LINK_ATTR: Record<string, string> = { crossOrigin: 'crossorigin', referrerPolicy: 'referrerpolicy', fetchPriority: 'fetchpriority', hrefLang: 'hreflang' };
-        for (const [k, v] of Object.entries(p)) {
-            if (v != null && v !== false) link.setAttribute(LINK_ATTR[k] ?? k, String(v));
-        }
-    }, []);
-
-    const addStyle = React.useCallback((props: StyleProps) => {
-        const p = props as Record<string, any>;
-        let style: HTMLStyleElement | null = null;
-        if (p['data-id']) style = document.querySelector(`style[data-id="${CSS.escape(p['data-id'])}"]`);
-        if (!style) { style = document.createElement('style'); document.head.appendChild(style); }
-        for (const [k, v] of Object.entries(p)) {
-            if (k === 'dangerouslySetInnerHTML') { style.innerHTML = (v as any).__html ?? ''; continue; }
-            if (v != null && v !== false) style.setAttribute(k, String(v));
-        }
-    }, []);
-
-    const addScript = React.useCallback((props: ScriptProps) => {
-        const p = props as Record<string, any>;
-        let script: HTMLScriptElement | null = null;
-        if (p.src) script = document.querySelector(`script[src="${CSS.escape(p.src)}"]`);
-        else if (p['data-id']) script = document.querySelector(`script[data-id="${CSS.escape(p['data-id'])}"]`);
-        if (!script) { script = document.createElement('script'); document.body.appendChild(script); }
-        for (const [k, v] of Object.entries(p)) {
-            if (k === 'dangerouslySetInnerHTML') { script.innerHTML = (v as any).__html ?? ''; continue; }
-            if (v != null && v !== false) script.setAttribute(k, String(v));
-        }
-    }, []);
-
-    const contextValue: InnerContext = React.useMemo(() => ({
-        setTitle,
-        addMeta,
-        addLink,
-        addStyle,
-        addScript,
-        setStatus: () => { },
-    }), [setTitle, addMeta, addLink, addStyle, addScript]);
-
-    return (
-        <AppContext.Provider value={contextValue}>
-            {children}
-        </AppContext.Provider>
-    );
-} );
+// Lazy singleton for the client-side DOM context.
+let _cliCtx: InnerContext | null = null;
+
+function makeClientCtx(): InnerContext {
+    if (_cliCtx) return _cliCtx;
+    _cliCtx = {
+        setTitle: (title) => { document.title = title; },
+        setStatus: () => { /* no-op on client */ },
+        addMeta: (props) => {
+            const p = props as Record<string, any>;
+            let meta: HTMLMetaElement | null = null;
+            if (p.name) meta = document.querySelector(`meta[name="${CSS.escape(p.name)}"]`);
+            else if (p.property) meta = document.querySelector(`meta[property="${CSS.escape(p.property)}"]`);
+            else if (p.httpEquiv ?? p['http-equiv']) meta = document.querySelector(`meta[http-equiv="${CSS.escape(p.httpEquiv ?? p['http-equiv'])}"]`);
+            else if ('charSet' in p || 'charset' in p) meta = document.querySelector('meta[charset]');
+            if (!meta) { meta = document.createElement('meta'); document.head.appendChild(meta); }
+            for (const [k, v] of Object.entries(p)) {
+                if (v != null && v !== false) meta.setAttribute(k === 'charSet' ? 'charset' : k === 'httpEquiv' ? 'http-equiv' : k, String(v));
+            }
+        },
+        addLink: (props) => {
+            const p = props as Record<string, any>;
+            let link: HTMLLinkElement | null = null;
+            const asSel = p.as ? `[as="${CSS.escape(p.as)}"]` : '';
+            if (p.rel && p.href) link = document.querySelector(`link[rel="${CSS.escape(p.rel)}"][href="${CSS.escape(p.href)}"]${asSel}`);
+            else if (p.rel) link = document.querySelector(`link[rel="${CSS.escape(p.rel)}"]${asSel}`);
+            if (!link) { link = document.createElement('link'); document.head.appendChild(link); }
+            for (const [k, v] of Object.entries(p)) {
+                if (v != null && v !== false) link.setAttribute(LINK_ATTR[k] ?? k, String(v));
+            }
+        },
+        addStyle: (props) => {
+            const p = props as Record<string, any>;
+            let style: HTMLStyleElement | null = null;
+            if (p['data-id']) style = document.querySelector(`style[data-id="${CSS.escape(p['data-id'])}"]`);
+            if (!style) { style = document.createElement('style'); document.head.appendChild(style); }
+            for (const [k, v] of Object.entries(p)) {
+                if (k === 'dangerouslySetInnerHTML') { style.innerHTML = (v as any).__html ?? ''; continue; }
+                if (v != null && v !== false) style.setAttribute(k, String(v));
+            }
+        },
+        addScript: (props) => {
+            const p = props as Record<string, any>;
+            let script: HTMLScriptElement | null = null;
+            if (p.src) script = document.querySelector(`script[src="${CSS.escape(p.src)}"]`);
+            else if (p['data-id']) script = document.querySelector(`script[data-id="${CSS.escape(p['data-id'])}"]`);
+            if (!script) { script = document.createElement('script'); document.body.appendChild(script); }
+            for (const [k, v] of Object.entries(p)) {
+                if (k === 'dangerouslySetInnerHTML') { script.innerHTML = (v as any).__html ?? ''; continue; }
+                if (v != null && v !== false) script.setAttribute(k, String(v));
+            }
+        },
+    };
+    return _cliCtx;
+}
 
-export const useApp = () => React.useContext(AppContext);
+function getCtx(): InnerContext | null {
+    if (typeof window === 'undefined') {
+        const head: AppHead | undefined = (globalThis as any).__hadarsContext?.head;
+        if (!head) return null;
+        return makeServerCtx(head);
+    }
+    return makeClientCtx();
+}
 
 // ── useServerData ─────────────────────────────────────────────────────────────
 //
@@ -293,14 +246,23 @@ export function useServerData<T>(key: string | string[], fn: () => Promise<T> |
             // 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);
-                        }
+                    let json: { serverData: Record<string, unknown> } | null = null;
+
+                    if ((globalThis as any).__hadarsStatic) {
+                        // Static export: the __hadarsStatic flag was embedded in the
+                        // page by `hadars export static`. Fetch the pre-generated
+                        // index.json sidecar directly — no live SSR server exists.
+                        const sidecarUrl = pathKey.replace(/\/$/, '') + '/index.json';
+                        const res = await fetch(sidecarUrl).catch(() => null);
+                        if (res?.ok) json = await res.json().catch(() => null);
+                    } else {
+                        // Live server: request the current URL with Accept: application/json.
+                        const res = await fetch(pathKey, { headers: { 'Accept': 'application/json' } });
+                        if (res.ok) json = await res.json();
+                    }
+
+                    for (const [k, v] of Object.entries(json?.serverData ?? {})) {
+                        clientServerDataCache.set(k, v);
                     }
                 } finally {
                     fetchedPaths.add(pathKey);
@@ -319,54 +281,23 @@ 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).
+    // ── 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.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);
+    if (!_u.pendingCreated) _u.pendingCreated = 0;
     // ────────────────────────────────────────────────────────────────────────
 
     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.`,
-                );
-            }
-        }
+    // 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)
         //   (b) return T synchronously — e.g. a sync data source
@@ -382,16 +313,43 @@ 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 }); },
         );
         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;
@@ -404,14 +362,10 @@ export const Head: React.FC<{
     status?: number;
 }> = React.memo( ({ children, status }) => {
 
-    const {
-        setStatus,
-        setTitle,
-        addMeta,
-        addLink,
-        addStyle,
-        addScript,
-    } = useApp();
+    const ctx = getCtx();
+    if (!ctx) return null;
+
+    const { setStatus, setTitle, addMeta, addLink, addStyle, addScript } = ctx;
 
     if ( status ) {
         setStatus(status);

package/src/utils/clientScript.tsx

@@ -22,6 +22,15 @@ const getProps = () => {
 const main = async () => {
     let props = getProps();
 
+    // Extract the static-export flag before it reaches user code. When set,
+    // useServerData fetches index.json sidecars directly on client navigation
+    // instead of requesting the live SSR server with Accept: application/json.
+    if ((props as any).__hadarsStatic) {
+        (globalThis as any).__hadarsStatic = true;
+        const { __hadarsStatic: _, ...rest } = props as any;
+        props = rest;
+    }
+
     // Seed the useServerData client cache from server-resolved values before
     // hydration so that hooks return the same data on the first render.
     if (props.__serverData && typeof props.__serverData === 'object') {