hadars 0.2.0 → 0.2.2-rc.0

package/dist/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/dist/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') {

package/index.ts

@@ -10,5 +10,8 @@ export type {
     HadarsGetClientProps,
     HadarsEntryModule,
     HadarsApp,
+    HadarsStaticContext,
+    GraphQLExecutor,
+    HadarsSourceEntry,
 } from "./src/types/hadars";
 export { HadarsHead, HadarsContext, loadModule } from "./src/index";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "hadars",
-  "version": "0.2.0",
+  "version": "0.2.2-rc.0",
   "description": "Minimal SSR framework for React — rspack, HMR, TypeScript, Bun/Node/Deno",
   "module": "./dist/index.js",
   "type": "module",
@@ -31,10 +31,15 @@
       "types": "./dist/lambda.d.ts",
       "import": "./dist/lambda.js",
       "require": "./dist/lambda.cjs"
+    },
+    "./cloudflare": {
+      "types": "./dist/cloudflare.d.ts",
+      "import": "./dist/cloudflare.js",
+      "require": "./dist/cloudflare.cjs"
     }
   },
   "scripts": {
-    "build:lib": "tsup src/index.tsx src/lambda.ts src/slim-react/index.ts src/slim-react/jsx-runtime.ts --format esm,cjs --dts --out-dir dist --clean --external '@rspack/*' --external '@rspack/binding'",
+    "build:lib": "tsup src/index.tsx src/lambda.ts src/cloudflare.ts src/slim-react/index.ts src/slim-react/jsx-runtime.ts --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/render-compare.test.tsx && bun test test/ssr.test.ts",

package/src/build.ts

@@ -20,6 +20,9 @@ import {
     buildSsrResponse, makePrecontentHtmlGetter,
     type CacheFetchHandler, createRenderCache,
 } from './utils/ssrHandler';
+import { runSources } from './source/runner';
+import { buildSchemaExecutor } from './source/inference';
+import { createGraphiqlHandler, GRAPHQL_PATH } from './source/graphiql';
 
 /**
  * Reads an HTML template, processes any `<style>` blocks through PostCSS
@@ -295,6 +298,26 @@ export const dev = async (options: HadarsRuntimeOptions) => {
     const handleWS = upgradeHandler(options);
     const handler = options.fetch;
 
+    // Run source plugins and set up GraphiQL if config.sources is present.
+    let handleGraphiql: ((req: Request) => Promise<Response | undefined>) | null = null;
+    let devStaticCtx: { graphql: import('./types/hadars').GraphQLExecutor } | undefined;
+    if (options.sources && options.sources.length > 0) {
+        console.log(`[hadars] Running ${options.sources.length} source plugin(s)…`);
+        try {
+            const store = await runSources(options.sources);
+            const executor = await buildSchemaExecutor(store);
+            if (executor) {
+                devStaticCtx = { graphql: executor };
+                handleGraphiql = createGraphiqlHandler(executor);
+                console.log(`[hadars] GraphiQL available at http://localhost:${port}${GRAPHQL_PATH}`);
+            } else {
+                console.warn('[hadars] `graphql` package not found — GraphiQL disabled. Run: npm install graphql');
+            }
+        } catch (err) {
+            console.error('[hadars] Source plugin error:', err);
+        }
+    }
+
     const entry = pathMod.resolve(__dirname, options.entry);
     const hmrPort = options.hmrPort ?? port + 1;
 
@@ -491,6 +514,11 @@ export const dev = async (options: HadarsRuntimeOptions) => {
         }
         if (handleWS && handleWS(request, ctx)) return undefined;
 
+        if (handleGraphiql) {
+            const graphiqlRes = await handleGraphiql(req);
+            if (graphiqlRes) return graphiqlRes;
+        }
+
         const proxied = await handleProxy(request);
         if (proxied) return proxied;
 
@@ -525,6 +553,7 @@ export const dev = async (options: HadarsRuntimeOptions) => {
                     getInitProps,
                     getFinalProps,
                 },
+                staticCtx: devStaticCtx,
             });
 
             // Content negotiation: if the client only accepts JSON (client-side

package/src/cloudflare.ts

@@ -0,0 +1,139 @@
+/**
+ * Cloudflare Workers adapter for hadars.
+ *
+ * After running `hadars build`, bundle your app with:
+ *
+ *   hadars export cloudflare
+ *
+ * This produces a self-contained `cloudflare.mjs` that you deploy with:
+ *
+ *   wrangler deploy
+ *
+ * Static assets (JS, CSS, fonts) under `.hadars/static/` must be served from
+ * R2 or another CDN — the Worker only handles HTML rendering. Route requests
+ * for static file extensions to R2 and everything else to the Worker.
+ *
+ * @example wrangler.toml
+ *   name = "my-app"
+ *   main = "cloudflare.mjs"
+ *   compatibility_date = "2024-09-23"
+ *   compatibility_flags = ["nodejs_compat"]
+ */
+
+import React from 'react';
+import { parseRequest } from './utils/request';
+import { createProxyHandler } from './utils/proxyHandler';
+import { getReactResponse, buildHeadHtml } from './utils/response';
+import { buildSsrHtml, makePrecontentHtmlGetter, createRenderCache } from './utils/ssrHandler';
+import type { HadarsOptions, HadarsEntryModule, HadarsProps } from './types/hadars';
+
+// ── Public types ──────────────────────────────────────────────────────────────
+
+/**
+ * Pre-loaded SSR module and HTML template for single-file Cloudflare bundles
+ * produced by `hadars export cloudflare`. All I/O is eliminated at runtime —
+ * the Worker is fully self-contained.
+ */
+export interface CloudflareBundled {
+    /** The compiled SSR module — import it statically in your entry shim. */
+    ssrModule: HadarsEntryModule<any>;
+    /**
+     * The contents of `.hadars/static/out.html` — esbuild inlines this as a
+     * string when `hadars export cloudflare` runs.
+     */
+    outHtml: string;
+}
+
+/**
+ * The shape of a Cloudflare Workers export object.
+ * Return this as the default export of your Worker entry file.
+ */
+export interface CloudflareHandler {
+    fetch(request: Request, env: unknown, ctx: unknown): Promise<Response>;
+}
+
+// ── Handler factory ───────────────────────────────────────────────────────────
+
+/**
+ * Creates a Cloudflare Workers handler from a hadars config and a pre-bundled
+ * SSR module. Use this as the default export of your Worker entry.
+ *
+ * Unlike the Lambda adapter, Cloudflare Workers receive a standard Web
+ * `Request` and return a standard `Response` — no event format conversion is
+ * required. Static assets must be routed to R2/CDN via wrangler rules; this
+ * Worker handles only HTML rendering and API routes.
+ *
+ * @example — generated entry shim (created by `hadars export cloudflare`)
+ * import * as ssrModule from './.hadars/index.ssr.js';
+ * import outHtml from './.hadars/static/out.html';
+ * import { createCloudflareHandler } from 'hadars/cloudflare';
+ * import config from './hadars.config';
+ * export default createCloudflareHandler(config, { ssrModule, outHtml });
+ */
+export function createCloudflareHandler(
+    options: HadarsOptions,
+    bundled: CloudflareBundled,
+): CloudflareHandler {
+    const fetchHandler     = options.fetch;
+    const handleProxy      = createProxyHandler(options);
+    const getPrecontentHtml = makePrecontentHtmlGetter(Promise.resolve(bundled.outHtml));
+    const { ssrModule }    = bundled;
+
+    const runHandler = async (req: Request): Promise<Response> => {
+        const request = parseRequest(req);
+
+        if (fetchHandler) {
+            const res = await fetchHandler(request);
+            if (res) return res;
+        }
+
+        const proxied = await handleProxy(request);
+        if (proxied) return proxied;
+
+        try {
+            const { default: Component, getInitProps, getFinalProps } = ssrModule;
+
+            const { head, status, getAppBody, finalize } = await getReactResponse(request, {
+                document: {
+                    body: Component as React.FC<HadarsProps<object>>,
+                    lang: 'en',
+                    getInitProps,
+                    getFinalProps,
+                },
+            });
+
+            // Data-only requests from client-side navigation.
+            if (request.headers.get('Accept') === 'application/json') {
+                const { clientProps } = await finalize();
+                const serverData = (clientProps as any).__serverData ?? {};
+                return new Response(JSON.stringify({ serverData }), {
+                    status,
+                    headers: { 'Content-Type': 'application/json; charset=utf-8' },
+                });
+            }
+
+            const bodyHtml = await getAppBody();
+            const { clientProps } = await finalize();
+            const headHtml = buildHeadHtml(head);
+            const html = await buildSsrHtml(bodyHtml, clientProps, headHtml, getPrecontentHtml);
+
+            return new Response(html, {
+                status,
+                headers: { 'Content-Type': 'text/html; charset=utf-8' },
+            });
+        } catch (err: any) {
+            console.error('[hadars] SSR render error:', err);
+            return new Response('Internal Server Error', { status: 500 });
+        }
+    };
+
+    const finalFetch = options.cache
+        ? createRenderCache(options.cache, (req) => runHandler(req))
+        : (req: Request) => runHandler(req);
+
+    return {
+        fetch: async (request: Request, _env: unknown, ctx: unknown): Promise<Response> => {
+            return (await finalFetch(request, ctx)) ?? new Response('Not Found', { status: 404 });
+        },
+    };
+}