@pyreon/zero 0.21.0 → 0.23.0

package/lib/types/server.d.ts

@@ -72,6 +72,126 @@ interface ApiRouteEntry {
   module: ApiRouteModule;
 }
 //#endregion
+//#region src/isr.d.ts
+/** Serialized SSR response cached by the ISR layer (one per cache key). */
+interface ISRCacheEntry {
+  html: string;
+  headers: Record<string, string>;
+  timestamp: number;
+}
+/**
+ * Pluggable backing store for the ISR cache. The default in-memory
+ * implementation (`createMemoryStore`) is per-process — fine for
+ * single-instance deploys, but multi-instance / horizontally-scaled
+ * apps need a SHARED store (Redis, Vercel KV, Cloudflare KV, Upstash,
+ * etc.) so revalidation in one instance is visible to all instances.
+ *
+ * The interface accepts BOTH sync and async returns: the in-memory
+ * default stays cheap (sync `Map` ops, no `Promise` allocation per
+ * request), while external stores return promises naturally. The
+ * handler awaits the result either way (`await` on a non-promise just
+ * returns the value).
+ *
+ * `get` is responsible for any LRU bookkeeping — external stores
+ * typically rely on their own TTL/eviction policy and can `return
+ * this.map.get(key)` directly; the in-memory store does a
+ * delete + re-insert to keep the Map's insertion-order LRU correct.
+ *
+ * `delete` is optional. It's only used when a future on-demand
+ * revalidation pathway needs to evict a specific key (the current
+ * stale-while-revalidate flow does not call it). External stores that
+ * don't support per-key invalidation can omit it.
+ */
+interface ISRStore<E = ISRCacheEntry> {
+  get(key: string): Promise<E | undefined> | E | undefined;
+  set(key: string, entry: E): Promise<void> | void;
+  delete?(key: string): Promise<void> | void;
+  /**
+   * Drop EVERY entry. Optional — external stores (Redis with TTL-only,
+   * Vercel KV with per-key invalidation, etc.) may not support a
+   * blanket purge. When omitted, `ISRHandler.revalidateAll()` throws a
+   * clear error pointing at the missing method. The default
+   * `createMemoryStore` implements it.
+   */
+  clear?(): Promise<void> | void;
+}
+/**
+ * The default in-memory ISR store: a `Map` with insertion-order LRU
+ * eviction, capped at `maxEntries` (default `1000`). Drop in as
+ * `config.store` if you want to tweak the cap or wrap the store with
+ * instrumentation; pass a different `ISRStore` impl for Redis / KV /
+ * etc. backings.
+ *
+ * `get` does the LRU bump (re-inserts the touched entry at the
+ * newest position) so hot paths survive eviction even when the cap is
+ * small. Without that, `Map.get(...)` wouldn't update ordering and
+ * frequently-read entries could be evicted by occasional writes.
+ */
+declare function createMemoryStore<E = ISRCacheEntry>(opts?: {
+  maxEntries?: number;
+}): ISRStore<E>;
+/**
+ * ISR handler with stale-while-revalidate semantics.
+ *
+ * Wraps an SSR handler and caches responses per URL path. Serves stale
+ * content immediately while revalidating in the background. The cache
+ * backing is **pluggable** via `config.store` (default:
+ * `createMemoryStore({ maxEntries: 1000 })`) — pass a custom `ISRStore`
+ * implementation backed by Redis / Vercel KV / Cloudflare KV / Upstash
+ * etc. to share state across horizontally-scaled instances. Without an
+ * external store, each instance has its own per-process cache (which
+ * is fine for single-instance deploys; behaviour-identical to the
+ * pre-pluggable-store implementation).
+ *
+ * Default in-memory store: bounded by `config.maxEntries` (default
+ * `1000`) with insertion-order LRU eviction. Without the cap, unbounded
+ * URL spaces like `/user/:id` would grow cache memory without limit
+ * over the server's lifetime — a real leak in long-running deployments.
+ * `config.maxEntries` is ignored when a custom `config.store` is supplied
+ * (the custom store owns its own eviction policy).
+ */
+/**
+ * The fetch handler `createISRHandler` returns is also a callable
+ * carrying imperative invalidation methods. Webhooks, CMS notifications,
+ * admin endpoints etc. call these methods to drop one or all cached
+ * entries on demand — strictly more responsive than waiting for the
+ * TTL-based stale-while-revalidate cycle.
+ *
+ * The shape is `(req) => Promise<Response>` PLUS the methods, so
+ * existing consumers (`Bun.serve({ fetch: handler })`) keep working
+ * byte-identically.
+ */
+interface ISRHandler {
+  (req: Request): Promise<Response>;
+  /**
+   * Drop the cache entry for a single path (or `cacheKey`-derived key).
+   * The next request for that key will MISS and re-render fresh. Returns
+   * `{ dropped: true }` if an entry was found and deleted, `{ dropped: false }`
+   * if no entry existed.
+   *
+   * Useful for webhook-driven invalidation: a CMS notifies that a post
+   * was updated, the webhook handler calls `isrHandler.revalidateNow('/posts/123')`,
+   * and the very next visitor gets the fresh content — no stale window.
+   *
+   * Idempotent. Safe to call against keys that don't exist (returns
+   * `dropped: false` cleanly).
+   */
+  revalidateNow(key: string): Promise<{
+    dropped: boolean;
+  }>;
+  /**
+   * Drop ALL cached entries. Useful for "purge cache" admin actions or
+   * deploy-completion hooks that want a clean slate.
+   *
+   * The default in-memory store supports this via repeated `delete`
+   * calls under the hood; custom stores that omit `delete` (Redis with
+   * TTL-only, etc.) throw a clear error pointing at the missing method
+   * so the caller knows their store implementation can't honor the call.
+   */
+  revalidateAll(): Promise<void>;
+}
+declare function createISRHandler(handler: (req: Request) => Promise<Response>, config: ISRConfig): ISRHandler;
+//#endregion
 //#region src/i18n-routing.d.ts
 interface I18nRoutingConfig {
   /** Supported locales. e.g. ["en", "de", "cs"] */
@@ -189,6 +309,77 @@ interface ISRConfig {
    * }
    */
   cacheKey?: (req: Request) => string;
+  /**
+   * Pluggable cache backing for multi-instance / horizontally-scaled
+   * production. Default: in-memory `Map` per-process (capped by
+   * `maxEntries`). Pass a Redis / Vercel KV / Cloudflare KV / Upstash
+   * adapter (anything matching the `ISRStore` interface from
+   * `@pyreon/zero/server`) for state shared across instances — a
+   * revalidation in one pod is visible to all pods.
+   *
+   * The store interface accepts BOTH sync and async returns; the
+   * handler `await`s the result either way, so an in-memory store
+   * stays cheap (no Promise allocation per request) while a Redis
+   * store can return its native promises directly.
+   *
+   * When set, `maxEntries` is ignored — the custom store owns its own
+   * eviction / TTL policy.
+   *
+   * @example
+   * // Redis adapter (uses `ioredis` or `@upstash/redis`):
+   * const redis = new Redis(...)
+   * const store: ISRStore = {
+   *   async get(key) {
+   *     const v = await redis.get(`isr:${key}`)
+   *     return v ? JSON.parse(v) : undefined
+   *   },
+   *   async set(key, entry) {
+   *     await redis.set(`isr:${key}`, JSON.stringify(entry), 'EX', 86400)
+   *   },
+   *   async delete(key) {
+   *     await redis.del(`isr:${key}`)
+   *   },
+   * }
+   *
+   * isr: { revalidate: 60, store }
+   */
+  store?: ISRStore<any>;
+  /**
+   * Construct the `Request` used for background revalidation. Default:
+   * the ORIGINAL user's request (headers, method, URL) — which means a
+   * `cacheKey`-bearing entry triggered by user A is revalidated against
+   * A's cookies / auth headers. For auth-gated `cacheKey` setups this
+   * is risky: if A's session expires before the revalidation runs, the
+   * new render may misbehave (auth-gate hits redirect path, or worse,
+   * still emits A's personalized HTML because the server hasn't yet
+   * invalidated the session token).
+   *
+   * Supply `revalidateRequest` to construct a request scoped to the
+   * cache key — e.g. anonymous for anonymous entries, service-account
+   * for shared entries. Returning `null` SKIPS revalidation entirely
+   * for this entry (stale stays stale until the next live request).
+   *
+   * Compatible with `store`: the revalidate path still reads/writes
+   * the configured store; this hook only controls what request the
+   * re-render runs against.
+   *
+   * @example
+   * isr: {
+   *   revalidate: 60,
+   *   cacheKey: (req) => {
+   *     const session = req.headers.get('cookie')?.match(/session=([^;]+)/)?.[1] ?? 'anon'
+   *     return `${new URL(req.url).pathname}::${session}`
+   *   },
+   *   revalidateRequest: (req) => {
+   *     // Anonymous entries re-revalidate as anonymous (safe default).
+   *     // Authenticated entries skip revalidation — the user's next
+   *     // hit will re-render with their current cookies on cache miss.
+   *     const hasAuth = /session=(?!anon)/.test(req.headers.get('cookie') ?? '')
+   *     return hasAuth ? null : new Request(req.url, { method: 'GET' })
+   *   },
+   * }
+   */
+  revalidateRequest?: (req: Request) => Request | null;
 }
 interface ZeroConfig {
   /** Default rendering mode. Default: "ssr" */
@@ -731,22 +922,6 @@ declare function generateMiddlewareModule(files: string[], routesDir: string): s
  */
 declare function scanRouteFiles(routesDir: string): Promise<string[]>;
 //#endregion
-//#region src/isr.d.ts
-/**
- * In-memory ISR cache with stale-while-revalidate semantics.
- *
- * Wraps an SSR handler and caches responses per URL path.
- * Serves stale content immediately while revalidating in the background.
- *
- * Bounded by `config.maxEntries` (default: 1000) with LRU eviction. The
- * `Map` preserves insertion order, so re-inserting an entry on every
- * serve (touching it) keeps the LRU order correct. Without the cap,
- * unbounded URL spaces like `/user/:id` would grow cache memory without
- * limit over the server's lifetime — a real leak in long-running
- * deployments.
- */
-declare function createISRHandler(handler: (req: Request) => Promise<Response>, config: ISRConfig): (req: Request) => Promise<Response>;
-//#endregion
 //#region src/vercel-revalidate-handler.d.ts
 /**
  * M3.1 — Drop-in Vercel revalidate webhook handler.
@@ -1597,5 +1772,5 @@ declare function inferJsonLd(options: InferJsonLdOptions): Record<string, unknow
  */
 declare function aiPlugin(config: AiPluginConfig): Plugin;
 //#endregion
-export { type AiPluginConfig, type CreateAppOptions, type CreateServerOptions, type FaviconLocaleConfig, type FaviconPluginConfig, type GenerateRouteModuleOptions, type GetStaticPaths, type IconSetConfig, type IconsPluginConfig, type InferJsonLdOptions, type NamedSetInput, type OgImageLayer, type OgImagePluginConfig, type OgImageTemplate, type RobotsConfig, type SeoPluginConfig, type SitemapConfig, type VercelRevalidateHandlerOptions, _resetVercelRevalidateHandlerCache, aiPlugin, bunAdapter, cloudflareAdapter, componentNameFromSetKey, compose, createApp, createISRHandler, createLocaleContext, createServer, zeroPlugin as default, defineConfig, detectLocaleFromHeader, faviconLinks, faviconPlugin, filePathToUrlPath, generateIconSetSource, generateLlmsFullTxt, generateLlmsTxt, generateMiddlewareModule, generateNamedIconSetsSource, generateRobots, generateRouteModule, generateSitemap, getContext, getZeroPluginConfig, i18nRouting, iconNameFromFile, iconsPlugin, inferJsonLd, jsonLd, netlifyAdapter, nodeAdapter, ogImagePath, ogImagePlugin, parseFileRoutes, render404Page, resolveAdapter, resolveConfig, scanIconDir, scanRouteFiles, seoMiddleware, seoPlugin, staticAdapter, vercelAdapter, vercelRevalidateHandler };
+export { type AiPluginConfig, type CreateAppOptions, type CreateServerOptions, type FaviconLocaleConfig, type FaviconPluginConfig, type GenerateRouteModuleOptions, type GetStaticPaths, type ISRCacheEntry, type ISRStore, type IconSetConfig, type IconsPluginConfig, type InferJsonLdOptions, type NamedSetInput, type OgImageLayer, type OgImagePluginConfig, type OgImageTemplate, type RobotsConfig, type SeoPluginConfig, type SitemapConfig, type VercelRevalidateHandlerOptions, _resetVercelRevalidateHandlerCache, aiPlugin, bunAdapter, cloudflareAdapter, componentNameFromSetKey, compose, createApp, createISRHandler, createLocaleContext, createMemoryStore, createServer, zeroPlugin as default, defineConfig, detectLocaleFromHeader, faviconLinks, faviconPlugin, filePathToUrlPath, generateIconSetSource, generateLlmsFullTxt, generateLlmsTxt, generateMiddlewareModule, generateNamedIconSetsSource, generateRobots, generateRouteModule, generateSitemap, getContext, getZeroPluginConfig, i18nRouting, iconNameFromFile, iconsPlugin, inferJsonLd, jsonLd, netlifyAdapter, nodeAdapter, ogImagePath, ogImagePlugin, parseFileRoutes, render404Page, resolveAdapter, resolveConfig, scanIconDir, scanRouteFiles, seoMiddleware, seoPlugin, staticAdapter, vercelAdapter, vercelRevalidateHandler };
 //# sourceMappingURL=server2.d.ts.map

package/lib/types/theme.d.ts

@@ -21,7 +21,16 @@ declare function toggleTheme(): void;
 /** Set theme explicitly. */
 declare function setTheme(t: Theme): void;
 /**
- * Initialize the theme system. Call once in your app entry or layout.
+ * Reset the refcount + shared teardown. Useful for tests.
+ * @internal
+ */
+declare function _resetInitThemeForTests(): void;
+/**
+ * Initialize the theme system. Safe to call multiple times — uses a
+ * mount-based refcount so multiple `<ThemeToggle>` instances (or
+ * `<ThemeToggle>` plus an explicit `initTheme()` in your layout) share
+ * a SINGLE matchMedia listener + effect.
+ *
  * Reads from localStorage, listens for system preference changes.
  */
 declare function initTheme(): void;
@@ -49,5 +58,5 @@ declare function ThemeToggle(props: {
  */
 declare const themeScript = "(function(){try{var t=localStorage.getItem(\"zero-theme\");var r=t===\"light\"?\"light\":t===\"dark\"?\"dark\":window.matchMedia(\"(prefers-color-scheme:dark)\").matches?\"dark\":\"light\";document.documentElement.dataset.theme=r;document.querySelectorAll(\"[data-favicon-theme]\").forEach(function(l){l.media=l.dataset.faviconTheme===r?\"\":\"not all\"})}catch(e){}})()";
 //#endregion
-export { Theme, ThemeToggle, initTheme, resolvedTheme, setSSRThemeDefault, setTheme, theme, themeScript, toggleTheme };
+export { Theme, ThemeToggle, _resetInitThemeForTests, initTheme, resolvedTheme, setSSRThemeDefault, setTheme, theme, themeScript, toggleTheme };
 //# sourceMappingURL=theme2.d.ts.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pyreon/zero",
-  "version": "0.21.0",
+  "version": "0.23.0",
   "description": "Pyreon Zero — zero-config full-stack framework powered by Pyreon and Vite",
   "license": "MIT",
   "author": "Vit Bokisch",
@@ -173,15 +173,15 @@
     "lint": "oxlint ."
   },
   "dependencies": {
-    "@pyreon/core": "^0.21.0",
-    "@pyreon/head": "^0.21.0",
-    "@pyreon/meta": "^0.21.0",
-    "@pyreon/reactivity": "^0.21.0",
-    "@pyreon/router": "^0.21.0",
-    "@pyreon/runtime-dom": "^0.21.0",
-    "@pyreon/runtime-server": "^0.21.0",
-    "@pyreon/server": "^0.21.0",
-    "@pyreon/vite-plugin": "^0.21.0",
+    "@pyreon/core": "^0.23.0",
+    "@pyreon/head": "^0.23.0",
+    "@pyreon/meta": "^0.23.0",
+    "@pyreon/reactivity": "^0.23.0",
+    "@pyreon/router": "^0.23.0",
+    "@pyreon/runtime-dom": "^0.23.0",
+    "@pyreon/runtime-server": "^0.23.0",
+    "@pyreon/server": "^0.23.0",
+    "@pyreon/vite-plugin": "^0.23.0",
     "vite": "^8.0.0"
   },
   "devDependencies": {

package/src/actions.ts

@@ -33,6 +33,21 @@ export interface Action<T = unknown> {
 
 // ─── Registry ────────────────────────────────────────────────────────────────
 
+/**
+ * Module-level registry of every `defineAction()` call. Lookup is by the
+ * `action_<uuid>` string the client sends in `POST /_zero/actions/<id>`.
+ *
+ * **HMR caveat (dev-only):** the registry uses fresh `crypto.randomUUID()`
+ * per `defineAction()` invocation. When Vite hot-replaces a module that
+ * calls `defineAction()`, the module re-runs and a NEW entry is inserted
+ * — the OLD entry stays in the Map until the dev process exits. Each
+ * entry holds `{ id, handler }` (~80 bytes). Bounded by the count of
+ * distinct UUIDs minted in the session; a realistic dev session sees
+ * <50 entries, so total dev-memory cost stays under ~5KB. Production
+ * registers each module exactly once at startup — no leak. A
+ * FinalizationRegistry-based purge is tracked as a follow-up; the
+ * current cost is too small to justify the WeakRef/finalizer complexity.
+ */
 const actionRegistry = new Map<string, RegisteredAction>()
 
 /**
@@ -129,11 +144,16 @@ export function createActionMiddleware(): (
 }
 
 async function executeAction(action: RegisteredAction, req: Request): Promise<Response> {
+  // Parse the request payload separately so a malformed body returns
+  // 400 (Bad Request) instead of being conflated with a runtime 500.
+  // `req.json()` / `req.formData()` throw on syntactically invalid
+  // payloads (truncated JSON, malformed multipart, invalid UTF-8, etc.)
+  // — that's a client problem, not a server problem, and the HTTP
+  // status code should reflect that.
+  const contentType = req.headers.get('content-type') ?? ''
+  let formData: FormData | null = null
+  let json: unknown = null
   try {
-    const contentType = req.headers.get('content-type') ?? ''
-    let formData: FormData | null = null
-    let json: unknown = null
-
     if (contentType.includes('application/json')) {
       json = await req.json()
     } else if (
@@ -142,16 +162,34 @@ async function executeAction(action: RegisteredAction, req: Request): Promise<Re
     ) {
       formData = await req.formData()
     }
+  } catch (err) {
+    // Malformed request body — log for ops diagnostics but return 400
+    // (not 500) so the client sees the right status code. Don't leak
+    // the parser's internal error message; surface only the shape.
+    console.error('[Pyreon Action] failed to parse request body:', err)
+    return Response.json(
+      { error: 'Invalid request body' },
+      { status: 400 },
+    )
+  }
 
+  // Execute the user-supplied action handler. Surface errors to server
+  // logs via `console.error` — the cloud adapter audit (PR #755) found
+  // this same swallow-error pattern hiding production crashes from
+  // operators. Without it, a CMS-triggered action that crashed inside
+  // the user's handler returned a generic 500 to the client AND
+  // logged nothing on the server side, so the operator couldn't
+  // diagnose the failure.
+  try {
     const result = await action.handler({
       request: req,
       formData,
       json,
       headers: req.headers,
     })
-
     return Response.json(result ?? null)
   } catch (err) {
+    console.error('[Pyreon Action] handler failed:', err)
     const message = err instanceof Error ? err.message : 'Internal server error'
     return Response.json({ error: message }, { status: 500 })
   }

package/src/adapters/bun.ts

@@ -34,6 +34,8 @@ export function bunAdapter(): Adapter {
 
       const port = options.config.port ?? 3000
       const serverEntry = `
+import { normalize } from "node:path"
+
 const handler = (await import("./server/entry-server.js")).default
 const clientDir = new URL("./client/", import.meta.url).pathname
 
@@ -42,19 +44,45 @@ Bun.serve({
   async fetch(req) {
     const url = new URL(req.url)
 
-    // Try static files first
+    // Try static files first (GET only).
+    //
+    // Path safety: decode percent-encoding, normalize \`..\` segments,
+    // then assert the resulting path doesn't escape the clientDir
+    // prefix. The previous implementation used \`Bun.resolveSync\`,
+    // which is MODULE resolution — it throws on any non-existent
+    // path, so it crashed every SSR route (URLs without a matching
+    // static file) with a 500 before the SSR handler ran.
+    // \`node:path.normalize\` is pure-string path arithmetic and
+    // doesn't touch the filesystem — safe for arbitrary input.
     if (req.method === "GET") {
-      const filePath = clientDir + (url.pathname === "/" ? "index.html" : url.pathname)
-      // Prevent path traversal — ensure resolved path stays within clientDir
-      const resolved = Bun.resolveSync(filePath, ".")
-      if (!resolved.startsWith(Bun.resolveSync(clientDir, "."))) {
+      let decoded
+      try {
+        decoded = decodeURIComponent(url.pathname)
+      } catch {
+        // Malformed %-encoding → reject (don't fall through to SSR
+        // with a corrupt URL).
+        return new Response("Bad Request", { status: 400 })
+      }
+      // Reject null bytes outright — no legitimate use in a URL,
+      // and they can confuse downstream filesystem code.
+      if (decoded.includes("\\0")) {
+        return new Response("Forbidden", { status: 403 })
+      }
+      const reqPath = decoded === "/" ? "/index.html" : decoded
+      // Prepend clientDir then normalize. If the normalized result
+      // no longer starts with clientDir, a \`..\` segment escaped —
+      // reject. Using string-startsWith with clientDir (which ends
+      // in "/") prevents the "/clientdir-evil/" sibling-prefix
+      // bypass.
+      const candidate = normalize(clientDir + reqPath)
+      if (!candidate.startsWith(clientDir)) {
         return new Response("Forbidden", { status: 403 })
       }
-      const file = Bun.file(filePath)
+      const file = Bun.file(candidate)
       if (await file.exists()) {
         return new Response(file, {
           headers: {
-            "cache-control": filePath.endsWith(".js") || filePath.endsWith(".css")
+            "cache-control": candidate.endsWith(".js") || candidate.endsWith(".css")
               ? "public, max-age=31536000, immutable"
               : "public, max-age=3600",
           },

package/src/adapters/cloudflare.ts

@@ -72,26 +72,31 @@ export function cloudflareAdapter(): Adapter {
         recursive: true,
       })
 
-      // Generate Cloudflare Pages _worker.js (ES module format)
+      // Generate Cloudflare Pages _worker.js (ES module format).
+      //
+      // Static assets are handled by Cloudflare Pages itself via the
+      // asset binding (Cloudflare's CDN serves files from the dist
+      // root before invoking the worker). The pre-fix harness had an
+      // \`if (ext && ...) { /* comment */ }\` block here computing an
+      // \`ext\` variable and checking a condition with an EMPTY body —
+      // pure dead code that did nothing at runtime. Removed for
+      // clarity.
       const workerEntry = `
 import handler from "./_server/entry-server.js"
 
 export default {
   async fetch(request, env, ctx) {
-    const url = new URL(request.url)
-
-    // Let Cloudflare serve static assets (files with extensions)
-    // This check is a fallback — Pages routes static files automatically
-    const ext = url.pathname.split(".").pop()
-    if (ext && ext !== url.pathname && !url.pathname.endsWith("/")) {
-      // Cloudflare Pages handles static assets automatically via its asset binding
-      // Only reach here if the file doesn't exist — fall through to SSR
-    }
-
-    // SSR handler
     try {
       return await handler(request)
     } catch (err) {
+      // Surface the error to Cloudflare Tail logs so production
+      // crashes give real diagnostic info — pre-fix the catch
+      // swallowed \`err\` entirely and the operator saw only a
+      // bare "Internal Server Error" with no stack, no message,
+      // no path. Logging via \`console.error\` is the standard
+      // Workers logging surface (lands in \`wrangler tail\` + the
+      // Cloudflare dashboard log stream).
+      console.error("[Pyreon SSR] handler failed:", err)
       return new Response("Internal Server Error", { status: 500 })
     }
   },

package/src/adapters/netlify.ts

@@ -68,7 +68,7 @@ export function netlifyAdapter(): Adapter {
         recursive: true,
       })
 
-      // Generate Netlify Function (v2 format — ESM, Web-standard Request/Response)
+      // Generate Netlify Function (v2 format — ESM, Web-standard Request/Response).
       const funcEntry = `
 import handler from "./_server/entry-server.js"
 
@@ -76,6 +76,12 @@ export default async function(req, context) {
   try {
     return await handler(req)
   } catch (err) {
+    // Surface the error to Netlify Function logs so production
+    // crashes give real diagnostic info — pre-fix the catch
+    // swallowed \`err\` entirely and the operator saw only a
+    // bare "Internal Server Error". \`console.error\` lands in
+    // Netlify's function runtime logs panel + \`netlify functions:log\`.
+    console.error("[Pyreon SSR] handler failed:", err)
     return new Response("Internal Server Error", { status: 500 })
   }
 }

package/src/adapters/node.ts

@@ -60,11 +60,11 @@ const MIME_TYPES = {
 const server = createServer(async (req, res) => {
   const url = new URL(req.url ?? "/", "http://localhost")
 
-  // Try to serve static files first
+  // Try to serve static files first (GET only).
   if (req.method === "GET") {
     try {
       const filePath = join(clientDir, url.pathname === "/" ? "index.html" : url.pathname)
-      // Prevent path traversal — ensure resolved path stays within clientDir
+      // Prevent path traversal — ensure resolved path stays within clientDir.
       const { resolve } = await import("node:path")
       const resolved = resolve(filePath)
       if (!resolved.startsWith(resolve(clientDir))) {
@@ -73,7 +73,14 @@ const server = createServer(async (req, res) => {
         return
       }
       const ext = extname(filePath)
-      if (ext && ext !== ".html") {
+      // Pre-fix shape was \`if (ext && ext !== ".html")\` which made the
+      // static branch silently refuse to serve .html files — INCLUDING
+      // the root \`/\` → \`index.html\` mapping the line above explicitly
+      // sets up. Result: GET / always fell through to SSR, even when an
+      // \`index.html\` shell existed in clientDir. Matches the bun
+      // adapter's behavior (which serves index.html at /) and the
+      // standard static + dynamic deployment pattern.
+      if (ext) {
         const data = await readFile(filePath)
         const mime = MIME_TYPES[ext] || "application/octet-stream"
         res.writeHead(200, {
@@ -88,7 +95,7 @@ const server = createServer(async (req, res) => {
     } catch {}
   }
 
-  // Fall through to SSR handler
+  // Fall through to SSR handler.
   const headers = {}
   for (const [key, value] of Object.entries(req.headers)) {
     if (value) headers[key] = Array.isArray(value) ? value.join(", ") : value
@@ -100,13 +107,33 @@ const server = createServer(async (req, res) => {
   })
 
   const response = await handler(request)
-  const body = await response.text()
 
   const responseHeaders = {}
   response.headers.forEach((v, k) => { responseHeaders[k] = v })
 
   res.writeHead(response.status, responseHeaders)
-  res.end(body)
+
+  // Pipe the Response body stream directly to res instead of buffering
+  // the whole body via response.text(). For mode: 'stream' SSR (Suspense
+  // out-of-order streaming) the pre-fix \`await response.text()\` drained
+  // every Suspense chunk server-side and arrived at the client all at
+  // once at the end — silently defeating streaming. For mode: 'string'
+  // the body is a single chunk and this loop runs once with identical
+  // observable behaviour.
+  if (response.body) {
+    const reader = response.body.getReader()
+    try {
+      while (true) {
+        const { value, done } = await reader.read()
+        if (done) break
+        res.write(value)
+      }
+    } finally {
+      res.end()
+    }
+  } else {
+    res.end()
+  }
 })
 
 server.listen(${port}, () => {

package/src/adapters/vercel.ts

@@ -71,11 +71,32 @@ export function vercelAdapter(): Adapter {
       // Copy server build to function directory
       await cp(join(options.serverEntry, '..'), funcDir, { recursive: true })
 
-      // Generate serverless function entry
+      // Generate serverless function entry.
+      //
+      // Pre-fix the handler dynamically imported \`./entry-server.js\` on
+      // EVERY invocation. Node's module cache makes calls after the
+      // first one near-free, but the FIRST request on every fresh
+      // serverless instance (i.e. every cold start) paid the full
+      // module evaluation cost inside the request budget — observable
+      // as a TTFB spike on cold starts. Hoisting the import to module
+      // scope evaluates the SSR module once at function-init time,
+      // before the first request lands.
+      //
+      // Also surface SSR errors to Vercel function logs via
+      // \`console.error\` (mirrors the cloudflare + netlify fix). Pre-fix
+      // an unhandled SSR throw propagated to Vercel's launcher (which
+      // logs it generically); adding our own prefix makes the cause
+      // trivially greppable in the dashboard log stream.
       const funcEntry = `
-export default async function handler(req) {
-  const handler = (await import("./entry-server.js")).default
-  return handler(req)
+import handler from "./entry-server.js"
+
+export default async function vercelHandler(req) {
+  try {
+    return await handler(req)
+  } catch (err) {
+    console.error("[Pyreon SSR] handler failed:", err)
+    return new Response("Internal Server Error", { status: 500 })
+  }
 }
 `.trimStart()
 

package/src/csp.ts

@@ -24,15 +24,20 @@
 import type { Middleware, MiddlewareContext } from '@pyreon/server'
 import { useRequestLocals } from '@pyreon/server'
 
-/** Client-side fallback nonce (dev server, SPA). */
-let _clientNonce = ''
-
 /**
  * Read the current CSP nonce in a component.
  *
  * SSR: reads from per-request `ctx.locals.cspNonce` via Pyreon's context
  * system — fully isolated between concurrent requests via AsyncLocalStorage.
- * Client/dev: falls back to module-level variable set by middleware.
+ *
+ * Returns `''` outside an active request context (client-side after
+ * hydration, dev preview, or any render path that bypassed the CSP
+ * middleware). Nonces are SSR-only by design: a client-side nonce
+ * mirrored from the last SSR request is a cross-request bleed waiting
+ * to happen, and a build-time-baked nonce would defeat the entire CSP
+ * mechanism. If you need a script-tag nonce, render the script during
+ * SSR through `useNonce()` so the value the browser sees IS the value
+ * the response's `Content-Security-Policy` header authorized.
  *
  * @example
  * ```tsx
@@ -47,7 +52,7 @@ let _clientNonce = ''
 export function useNonce(): string {
   const locals = useRequestLocals()
   if (locals.cspNonce) return locals.cspNonce as string
-  return _clientNonce
+  return ''
 }
 
 export interface CspDirectives {
@@ -211,11 +216,9 @@ export function cspMiddleware(config: CspConfig): Middleware {
 
   return (ctx: MiddlewareContext) => {
     if (staticHeader) {
-      _clientNonce = ''
       ctx.headers.set(headerName, staticHeader)
     } else {
       const nonce = generateNonce()
-      _clientNonce = nonce
       ;(ctx.locals as Record<string, unknown>).cspNonce = nonce
       ctx.headers.set(headerName, buildCspHeader(config.directives, nonce))
     }