@pyreon/zero 0.22.0 → 0.24.0

package/lib/testing.js

@@ -1,73 +1,5 @@
-//#region src/api-routes.ts
-/**
-* Match a URL path against an API route pattern.
-* Returns extracted params or null if no match.
-*/
-function matchApiRoute(pattern, path) {
-	const patternParts = pattern.split("/").filter(Boolean);
-	const pathParts = path.split("/").filter(Boolean);
-	const params = {};
-	const isUnsafeParam = (name) => name === "__proto__" || name === "constructor" || name === "prototype";
-	for (let i = 0; i < patternParts.length; i++) {
-		const pp = patternParts[i];
-		if (!pp) continue;
-		if (pp.endsWith("*")) {
-			const paramName = pp.slice(1, -1);
-			if (!isUnsafeParam(paramName)) params[paramName] = pathParts.slice(i).join("/");
-			return params;
-		}
-		if (i >= pathParts.length) return null;
-		if (pp.startsWith(":")) {
-			const paramName = pp.slice(1);
-			if (!isUnsafeParam(paramName)) params[paramName] = pathParts[i];
-			continue;
-		}
-		if (pp !== pathParts[i]) return null;
-	}
-	return patternParts.length === pathParts.length ? params : null;
-}
-const HTTP_METHODS = [
-	"GET",
-	"POST",
-	"PUT",
-	"PATCH",
-	"DELETE",
-	"HEAD",
-	"OPTIONS"
-];
-/**
-* Create a middleware that dispatches API route requests.
-* API routes are matched by URL pattern and HTTP method.
-*/
-function createApiMiddleware(routes) {
-	return async (ctx) => {
-		for (const route of routes) {
-			const params = matchApiRoute(route.pattern, ctx.path);
-			if (!params) continue;
-			const method = ctx.req.method.toUpperCase();
-			const handler = route.module[method];
-			if (!handler) {
-				const allowed = HTTP_METHODS.filter((m) => route.module[m]).join(", ");
-				return new Response(null, {
-					status: 405,
-					headers: {
-						Allow: allowed,
-						"Content-Type": "application/json"
-					}
-				});
-			}
-			return handler({
-				request: ctx.req,
-				url: ctx.url,
-				path: ctx.path,
-				params,
-				headers: ctx.req.headers
-			});
-		}
-	};
-}
+import { createApiMiddleware } from "./api-routes.js";
 
-//#endregion
 //#region src/testing.ts
 /**
 * Create a mock MiddlewareContext for testing middleware.

package/lib/theme.js

@@ -1,8 +1,10 @@
 import { onMount } from "@pyreon/core";
-import { effect, signal } from "@pyreon/reactivity";
 import { jsx, jsxs } from "@pyreon/core/jsx-runtime";
+import { effect, signal } from "@pyreon/reactivity";
 
 //#region src/theme.tsx
+const __DEV__ = typeof process !== "undefined" && process.env.NODE_ENV !== "production";
+const _countSink = globalThis;
 const STORAGE_KEY = "zero-theme";
 /** Reactive theme signal. */
 const theme = signal("system");
@@ -55,32 +57,60 @@ function setTheme(t) {
 		} catch {}
 	}
 }
+let _initRefCount = 0;
+let _disposeShared = null;
+function _setupShared() {
+	try {
+		const stored = localStorage.getItem(STORAGE_KEY);
+		if (stored === "light" || stored === "dark" || stored === "system") theme.set(stored);
+	} catch {}
+	document.documentElement.dataset.theme = resolvedTheme();
+	const mq = window.matchMedia("(prefers-color-scheme: dark)");
+	_osPrefersDark.set(mq.matches);
+	function onChange(e) {
+		_osPrefersDark.set(e.matches);
+	}
+	mq.addEventListener("change", onChange);
+	const dispose = effect(() => {
+		const mode = resolvedTheme();
+		document.documentElement.dataset.theme = mode;
+		const faviconLinks = document.querySelectorAll("[data-favicon-theme]");
+		for (const link of faviconLinks) link.media = link.dataset.faviconTheme === mode ? "" : "not all";
+	});
+	return () => {
+		mq.removeEventListener("change", onChange);
+		dispose?.dispose();
+	};
+}
+/**
+* Reset the refcount + shared teardown. Useful for tests.
+* @internal
+*/
+function _resetInitThemeForTests() {
+	if (_disposeShared) _disposeShared();
+	_initRefCount = 0;
+	_disposeShared = null;
+}
 /**
-* Initialize the theme system. Call once in your app entry or layout.
+* 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.
 */
 function initTheme() {
 	onMount(() => {
-		try {
-			const stored = localStorage.getItem(STORAGE_KEY);
-			if (stored === "light" || stored === "dark" || stored === "system") theme.set(stored);
-		} catch {}
-		document.documentElement.dataset.theme = resolvedTheme();
-		const mq = window.matchMedia("(prefers-color-scheme: dark)");
-		_osPrefersDark.set(mq.matches);
-		function onChange(e) {
-			_osPrefersDark.set(e.matches);
-		}
-		mq.addEventListener("change", onChange);
-		const dispose = effect(() => {
-			const mode = resolvedTheme();
-			document.documentElement.dataset.theme = mode;
-			const faviconLinks = document.querySelectorAll("[data-favicon-theme]");
-			for (const link of faviconLinks) link.media = link.dataset.faviconTheme === mode ? "" : "not all";
-		});
+		if (_initRefCount === 0) _disposeShared = _setupShared();
+		_initRefCount++;
+		if (__DEV__) _countSink.__pyreon_count__?.("theme.initRefAcquire");
 		return () => {
-			mq.removeEventListener("change", onChange);
-			dispose?.dispose();
+			_initRefCount--;
+			if (__DEV__) _countSink.__pyreon_count__?.("theme.initRefRelease");
+			if (_initRefCount === 0 && _disposeShared) {
+				_disposeShared();
+				_disposeShared = null;
+			}
 		};
 	});
 }
@@ -193,5 +223,5 @@ function ThemeToggle(props) {
 const themeScript = `(function(){try{var t=localStorage.getItem("${STORAGE_KEY}");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 { ThemeToggle, initTheme, resolvedTheme, setSSRThemeDefault, setTheme, theme, themeScript, toggleTheme };
+export { ThemeToggle, _resetInitThemeForTests, initTheme, resolvedTheme, setSSRThemeDefault, setTheme, theme, themeScript, toggleTheme };
 //# sourceMappingURL=theme.js.map

package/lib/types/config.d.ts

@@ -1,4 +1,48 @@
 import { Middleware } from "@pyreon/server";
+//#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;
+}
+//#endregion
 //#region src/i18n-routing.d.ts
 interface I18nRoutingConfig {
   /** Supported locales. e.g. ["en", "de", "cs"] */
@@ -70,6 +114,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" */

package/lib/types/csp.d.ts

@@ -6,7 +6,15 @@ import { Middleware } from "@pyreon/server";
  *
  * 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

package/lib/types/index.d.ts

@@ -479,6 +479,50 @@ declare function createScript(Component: (p: ScriptRenderProps) => any): (props:
  */
 declare const Script: (props: ScriptProps) => VNodeChild;
 //#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;
+}
+//#endregion
 //#region src/types.d.ts
 /** What a route file (e.g. `src/routes/index.tsx`) can export. */
 interface RouteModule {
@@ -563,6 +607,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" */
@@ -1207,7 +1322,11 @@ 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.
+ * 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;