@pyreon/zero 0.14.0 → 0.16.0

package/src/client.ts

@@ -5,6 +5,13 @@ import { hydrateLoaderData } from '@pyreon/router'
 import { hydrateRoot, mount } from '@pyreon/runtime-dom'
 import { createApp } from './app'
 
+// Vite-injected build-time constant. Defined in `vite-plugin.ts`'s
+// `config()` hook from `zero({ base })`. Falls back to `'/'` for
+// non-Vite builds (test environments, etc.) so the read is always
+// safe. The fallback is documented intent — there's no Pyreon
+// deployment outside Vite that consumes this.
+declare const __ZERO_BASE__: string
+
 // ─── Client entry factory ───────────────────────────────────────────────────
 
 export interface StartClientOptions {
@@ -59,10 +66,21 @@ export function startClient(options: StartClientOptions) {
   const container = document.getElementById('app')
   if (!container) throw new Error('[Pyreon] Missing #app container element')
 
+  // Read the Vite-injected base so `createRouter({ base })` matches the
+  // value Vite used to rewrite asset URLs. `typeof` guard covers the
+  // edge case where the constant isn't defined (non-Vite test contexts);
+  // missing the constant in a real Vite build is impossible because the
+  // plugin's `config()` hook always declares it via `define`.
+  const base =
+    typeof __ZERO_BASE__ !== 'undefined' && __ZERO_BASE__ !== '/'
+      ? __ZERO_BASE__
+      : undefined
+
   const { App, router } = createApp({
     routes: options.routes,
     routerMode: 'history',
     ...(options.layout ? { layout: options.layout } : {}),
+    ...(base ? { base } : {}),
   })
 
   // ── Loader data hydration (SSR path) ───────────────────────────────────────

package/src/csp.ts

@@ -140,21 +140,37 @@ export function buildCspHeader(directives: CspDirectives, nonce?: string): strin
 }
 
 /**
- * Generate a random nonce string (base64, 16 bytes).
+ * Generate a cryptographically-random nonce string (base64, 16 bytes).
+ *
+ * Throws when `crypto.getRandomValues` is unavailable. CSP nonces protect
+ * against XSS by gating inline script execution; a predictable nonce
+ * (`Math.random` ~31 bits of entropy) bypasses CSP entirely. Silent
+ * degradation here was a security anti-pattern — we surface the
+ * misconfiguration loudly instead.
+ *
+ * Realistic deployments always have `crypto.getRandomValues`: Node 18+,
+ * Bun, Deno, browsers, edge workers (Cloudflare/Vercel/Netlify), and
+ * vitest/happy-dom all expose it via `globalThis.crypto`. If you hit
+ * this throw, your environment is unusual — fix the env, don't downgrade
+ * the security primitive.
  */
 function generateNonce(): string {
-  if (typeof crypto !== 'undefined' && crypto.getRandomValues) {
-    const bytes = new Uint8Array(16)
-    crypto.getRandomValues(bytes)
-    // Convert to base64 using btoa
-    let binary = ''
-    for (const byte of bytes) binary += String.fromCharCode(byte)
-    return typeof btoa === 'function'
-      ? btoa(binary)
-      : Buffer.from(bytes).toString('base64')
+  if (typeof crypto === 'undefined' || !crypto.getRandomValues) {
+    throw new Error(
+      '[Pyreon] CSP nonce generation requires `crypto.getRandomValues` (Web Crypto API). ' +
+        'No secure RNG is available in this environment. CSP nonces must be cryptographically ' +
+        'random — falling back to `Math.random` would silently weaken XSS protection. ' +
+        'Ensure Node 18+, Bun, Deno, an edge runtime, or a browser environment.',
+    )
   }
-  // Fallback for environments without crypto
-  return Math.random().toString(36).slice(2) + Math.random().toString(36).slice(2)
+  const bytes = new Uint8Array(16)
+  crypto.getRandomValues(bytes)
+  // Convert to base64 using btoa
+  let binary = ''
+  for (const byte of bytes) binary += String.fromCharCode(byte)
+  return typeof btoa === 'function'
+    ? btoa(binary)
+    : Buffer.from(bytes).toString('base64')
 }
 
 /**

package/src/entry-server.ts

@@ -123,6 +123,11 @@ export function createServer(options: CreateServerOptions) {
 	const { App } = createApp({
 		routes: options.routes,
 		routerMode: "history",
+		// Forward zero's `base` to createRouter so RouterLinks render
+		// correctly prefixed hrefs during SSR — must match the value
+		// the client-side `startClient` reads from `__ZERO_BASE__` so
+		// hydration doesn't mismatch.
+		...(config.base && config.base !== "/" ? { base: config.base } : {}),
 	});
 
 	const handler = createHandler({
@@ -134,18 +139,40 @@ export function createServer(options: CreateServerOptions) {
 		...(options.clientEntry ? { clientEntry: options.clientEntry } : {}),
 	});
 
-	// Wrap handler with 404 detection when a notFoundComponent is provided
+	// M1.2 — Runtime SSR 404 routes through the router (PR L5).
+	// When a URL doesn't match any leaf, @pyreon/router's resolveRoute
+	// walks up to the closest parent `notFoundComponent` and builds a
+	// synthetic chain `[...ancestorLayouts, syntheticLeaf]`. The handler
+	// renders that chain, producing 404 HTML INSIDE the layout's chrome,
+	// and reads `resolved.isNotFound` to set HTTP status 404. This
+	// replaces the pre-M1 URL-pattern wrapper that bypassed the router
+	// for unmatched URLs and rendered the not-found component standalone
+	// (no layout wrapping).
+	//
+	// `options.notFoundComponent` is a legacy fallback for apps that
+	// don't carry `_404.tsx` in their routes tree. When set AND the
+	// routes tree has no reachable `notFoundComponent`, we render the
+	// standalone shape as a final fallback. The canonical pattern is
+	// `_404.tsx` inside a `_layout.tsx` directory — that goes through
+	// PR L5's router-driven path and gets layout chrome for free.
 	if (!options.notFoundComponent) return handler;
 
 	const NotFound = options.notFoundComponent;
-	const routePatterns = flattenRoutePatterns(options.routes);
+	const hasRouteTreeNotFound = routeTreeHasNotFound(options.routes);
 
 	return async (req: Request) => {
+		// Route-tree notFoundComponent present → handler handles 404 via
+		// resolveRoute's `isNotFound` fallback (PR L5). Skip the legacy
+		// wrapper entirely — handler.ts sets status 404 + renders layout
+		// chrome correctly.
+		if (hasRouteTreeNotFound) return handler(req);
+
+		// Legacy fallback: routes tree has no notFoundComponent but the
+		// caller passed `options.notFoundComponent`. Run the URL-pattern
+		// check + standalone render for backward compat.
 		const url = new URL(req.url);
 		const pathname = url.pathname;
-
-		// Check if any defined route matches this path
-		if (!routePatterns.some((pattern) => matchPattern(pattern, pathname))) {
+		if (!routePatternsCache(options.routes).some((p) => matchPattern(p, pathname))) {
 			const fullHtml = await render404Page(NotFound, options.template);
 			return new Response(fullHtml, {
 				status: 404,
@@ -157,6 +184,29 @@ export function createServer(options: CreateServerOptions) {
 	};
 }
 
+/** Walk the route tree looking for any record with a `notFoundComponent`. */
+function routeTreeHasNotFound(routes: RouteRecord[]): boolean {
+	for (const r of routes) {
+		if (typeof (r as { notFoundComponent?: unknown }).notFoundComponent === "function") {
+			return true;
+		}
+		if (r.children && routeTreeHasNotFound(r.children as RouteRecord[])) {
+			return true;
+		}
+	}
+	return false;
+}
+
+/** Lazy cache of flattened patterns — only computed if legacy fallback fires. */
+const _routePatternsCache = new WeakMap<RouteRecord[], string[]>();
+function routePatternsCache(routes: RouteRecord[]): string[] {
+	const cached = _routePatternsCache.get(routes);
+	if (cached) return cached;
+	const out = flattenRoutePatterns(routes);
+	_routePatternsCache.set(routes, out);
+	return out;
+}
+
 /** Extract all URL patterns from a nested route tree. */
 function flattenRoutePatterns(routes: RouteRecord[], prefix = ""): string[] {
 	const patterns: string[] = [];

package/src/env.ts

@@ -244,14 +244,14 @@ type InferEnvSchema<T> = {
  * ```
  */
 export function validateEnv<T extends Record<string, SchemaEntry>>(
-  schema: T,
+  envSchema: T,
   source?: Record<string, string | undefined>,
 ): InferEnvSchema<T> {
   const env = source ?? (typeof process !== 'undefined' ? process.env : {})
   const result: Record<string, unknown> = {}
   const errors: string[] = []
 
-  for (const [key, entry] of Object.entries(schema)) {
+  for (const [key, entry] of Object.entries(envSchema)) {
     const validator = toValidator(entry)
     try {
       result[key] = validator.parse(env[key], key)
@@ -284,12 +284,12 @@ export function validateEnv<T extends Record<string, SchemaEntry>>(
  * ```
  */
 export function publicEnv(): Record<string, string>
-export function publicEnv<T extends Record<string, SchemaEntry>>(schema: T): InferEnvSchema<T>
-export function publicEnv(schema?: Record<string, SchemaEntry>): Record<string, unknown> {
+export function publicEnv<T extends Record<string, SchemaEntry>>(envSchema: T): InferEnvSchema<T>
+export function publicEnv(envSchema?: Record<string, SchemaEntry>): Record<string, unknown> {
   const prefix = 'ZERO_PUBLIC_'
   const env = typeof process !== 'undefined' ? process.env : {}
 
-  if (!schema) {
+  if (!envSchema) {
     const result: Record<string, string> = {}
     for (const [key, value] of Object.entries(env)) {
       if (key.startsWith(prefix) && value !== undefined) {
@@ -300,10 +300,10 @@ export function publicEnv(schema?: Record<string, SchemaEntry>): Record<string,
   }
 
   const prefixedSource: Record<string, string | undefined> = {}
-  for (const key of Object.keys(schema)) {
+  for (const key of Object.keys(envSchema)) {
     prefixedSource[key] = env[`${prefix}${key}`]
   }
-  return validateEnv(schema, prefixedSource)
+  return validateEnv(envSchema, prefixedSource)
 }
 
 // ─── Custom validator escape hatch ──────────────────────────────────────────

package/src/font.ts

@@ -159,11 +159,11 @@ export function parseGoogleFamily(input: string): ResolvedFont {
       for (const entry of entries) {
         if (entry.includes(',')) {
           // Tuple format: "0,300" or "1,500" — last value is the weight
-          const parts = entry.split(',')
-          const weight = Number(parts[parts.length - 1])
+          const tuple = entry.split(',')
+          const weight = Number(tuple[tuple.length - 1])
           if (weight > 0) weights.add(weight)
           // Detect italic from tuple: "1,xxx" means italic
-          if (parts[0] === '1') italic = true
+          if (tuple[0] === '1') italic = true
         } else if (entry.includes('..')) {
           // Variable range already handled above — skip
         } else {

package/src/fs-router.ts

@@ -2,6 +2,34 @@ import { readFileSync } from 'node:fs'
 import { join } from 'node:path'
 import type { FileRoute, RenderMode, RouteFileExports } from './types'
 
+/**
+ * Return type of a route file's `getStaticPaths()` export. Each entry
+ * supplies one set of concrete values for the route's dynamic segments;
+ * the SSG plugin expands the route's URL pattern with these params and
+ * renders one HTML file per entry.
+ *
+ * @example
+ * ```tsx
+ * // src/routes/posts/[id].tsx
+ * import type { GetStaticPaths } from '@pyreon/zero/server'
+ *
+ * export const getStaticPaths: GetStaticPaths<{ id: string }> = async () => {
+ *   const posts = await fetch('https://api.example.com/posts').then(r => r.json())
+ *   return posts.map((p) => ({ params: { id: p.slug } }))
+ * }
+ *
+ * export default function Post() { ... }
+ * ```
+ *
+ * For catch-all routes (`/blog/[...slug].tsx`), pass the full path through
+ * the catch-all param: `{ params: { slug: 'a/b' } }` → `/blog/a/b`.
+ */
+export type GetStaticPaths<
+  TParams extends Record<string, string> = Record<string, string>,
+> = () =>
+  | Array<{ params: TParams }>
+  | Promise<Array<{ params: TParams }>>
+
 // ─── File-system route conventions ──────────────────────────────────────────
 //
 // src/routes/
@@ -40,6 +68,10 @@ const ROUTE_EXPORT_NAMES = [
   'renderMode',
   'error',
   'middleware',
+  'loaderKey',
+  'gcTime',
+  'getStaticPaths',
+  'revalidate',
 ] as const
 
 type RouteExportName = (typeof ROUTE_EXPORT_NAMES)[number]
@@ -100,12 +132,27 @@ export function detectRouteExports(source: string): RouteFileExports {
   const rawRenderMode = found.has('renderMode')
     ? extractLiteralExport(source, 'renderMode')
     : undefined
+  // PR I — capture `revalidate` as a literal so the build-time ISR
+  // manifest (`dist/_pyreon-revalidate.json`) can be emitted from the
+  // SSG plugin without loading the route module. The route generator
+  // does NOT inline `revalidate` into the route record — it's a build-
+  // time-only concern that adapters consume via the manifest.
+  const rawRevalidate = found.has('revalidate')
+    ? extractLiteralExport(source, 'revalidate')
+    : undefined
   const cleanMeta = rawMeta !== undefined ? stripTypeAssertions(rawMeta) : undefined
   const cleanRenderMode =
     rawRenderMode !== undefined ? stripTypeAssertions(rawRenderMode) : undefined
+  const cleanRevalidate =
+    rawRevalidate !== undefined ? stripTypeAssertions(rawRevalidate) : undefined
   const metaLiteral = cleanMeta !== undefined && isPureLiteral(cleanMeta) ? cleanMeta : undefined
   const renderModeLiteral =
     cleanRenderMode !== undefined && isPureLiteral(cleanRenderMode) ? cleanRenderMode : undefined
+  // `revalidate` literals are number (`60`) or boolean (`false`) — never
+  // an object/array — so `isPureLiteral` is overkill. Keep the same
+  // safety check for defense-in-depth.
+  const revalidateLiteral =
+    cleanRevalidate !== undefined && isPureLiteral(cleanRevalidate) ? cleanRevalidate : undefined
 
   return {
     hasLoader: found.has('loader'),
@@ -114,8 +161,13 @@ export function detectRouteExports(source: string): RouteFileExports {
     hasRenderMode: found.has('renderMode'),
     hasError: found.has('error'),
     hasMiddleware: found.has('middleware'),
+    hasLoaderKey: found.has('loaderKey'),
+    hasGcTime: found.has('gcTime'),
+    hasGetStaticPaths: found.has('getStaticPaths'),
+    hasRevalidate: found.has('revalidate'),
     ...(metaLiteral !== undefined ? { metaLiteral } : {}),
     ...(renderModeLiteral !== undefined ? { renderModeLiteral } : {}),
+    ...(revalidateLiteral !== undefined ? { revalidateLiteral } : {}),
   }
 }
 
@@ -745,6 +797,10 @@ const EMPTY_EXPORTS: RouteFileExports = {
   hasRenderMode: false,
   hasError: false,
   hasMiddleware: false,
+  hasLoaderKey: false,
+  hasGcTime: false,
+  hasGetStaticPaths: false,
+  hasRevalidate: false,
 }
 
 /**
@@ -759,7 +815,10 @@ export function hasAnyMetaExport(exports: RouteFileExports): boolean {
     exports.hasMeta ||
     exports.hasRenderMode ||
     exports.hasError ||
-    exports.hasMiddleware
+    exports.hasMiddleware ||
+    exports.hasLoaderKey ||
+    exports.hasGcTime ||
+    exports.hasGetStaticPaths
   )
 }
 
@@ -1085,6 +1144,10 @@ export function generateRouteModuleFromRoutes(
         props.push(`${indent}  component: ${mod}.default`)
         if (exp.hasLoader) props.push(`${indent}  loader: ${mod}.loader`)
         if (exp.hasGuard) props.push(`${indent}  beforeEnter: ${mod}.guard`)
+        if (exp.hasLoaderKey) props.push(`${indent}  loaderKey: ${mod}.loaderKey`)
+        if (exp.hasGcTime) props.push(`${indent}  gcTime: ${mod}.gcTime`)
+        if (exp.hasGetStaticPaths)
+          props.push(`${indent}  getStaticPaths: ${mod}.getStaticPaths`)
         if (exp.hasMeta || exp.hasRenderMode) {
           const metaParts: string[] = []
           if (exp.hasMeta) metaParts.push(`...${mod}.meta`)
@@ -1122,7 +1185,13 @@ export function generateRouteModuleFromRoutes(
       const inlineableMeta =
         (!exp.hasMeta || exp.metaLiteral !== undefined) &&
         (!exp.hasRenderMode || exp.renderModeLiteral !== undefined)
-      const needsFunctionExports = exp.hasLoader || exp.hasGuard || exp.hasError
+      // getStaticPaths is a build-time export consumed by the SSG plugin's
+      // path-resolution phase. Like loader/guard/error, it can't be inlined
+      // as a literal — we need the actual function reference. Force the
+      // generator into the mixed branch (case 2) when present so a namespace
+      // import is emitted and `mod.getStaticPaths` lands on the route record.
+      const needsFunctionExports =
+        exp.hasLoader || exp.hasGuard || exp.hasError || exp.hasGetStaticPaths
 
       if (hasMeta && inlineableMeta && !needsFunctionExports) {
         // Optimal path — component lazy, metadata inlined.
@@ -1152,6 +1221,27 @@ export function generateRouteModuleFromRoutes(
             `${indent}  beforeEnter: (to, from) => import("${fullPath}").then((m) => m.guard(to, from))`,
           )
         }
+        if (exp.hasLoaderKey) {
+          // loaderKey runs SYNCHRONOUSLY during the cache-key check; can't be
+          // routed through a dynamic import. Inline a `mod.loaderKey` lookup
+          // via the same namespace-import pattern as the metadata path. Rolldown
+          // will share the chunk with the lazy() component thunk.
+          const mod = nextModuleImport(page.filePath)
+          props.push(`${indent}  loaderKey: ${mod}.loaderKey`)
+        }
+        if (exp.hasGcTime) {
+          const mod = nextModuleImport(page.filePath)
+          props.push(`${indent}  gcTime: ${mod}.gcTime`)
+        }
+        if (exp.hasGetStaticPaths) {
+          // getStaticPaths runs at SSG build time (not request time), so
+          // routing it through a dynamic import is fine — but going through
+          // a namespace import keeps it consistent with loaderKey/gcTime
+          // and avoids per-call import overhead during the SSG enumeration
+          // phase.
+          const mod = nextModuleImport(page.filePath)
+          props.push(`${indent}  getStaticPaths: ${mod}.getStaticPaths`)
+        }
         emitInlineMeta(exp, props, indent)
         if (errorName) {
           // For error components we can't easily await — pass the lazy
@@ -1171,6 +1261,10 @@ export function generateRouteModuleFromRoutes(
         props.push(`${indent}  component: ${mod}.default`)
         if (exp.hasLoader) props.push(`${indent}  loader: ${mod}.loader`)
         if (exp.hasGuard) props.push(`${indent}  beforeEnter: ${mod}.guard`)
+        if (exp.hasLoaderKey) props.push(`${indent}  loaderKey: ${mod}.loaderKey`)
+        if (exp.hasGcTime) props.push(`${indent}  gcTime: ${mod}.gcTime`)
+        if (exp.hasGetStaticPaths)
+          props.push(`${indent}  getStaticPaths: ${mod}.getStaticPaths`)
         if (exp.hasMeta || exp.hasRenderMode) {
           const metaParts: string[] = []
           if (exp.hasMeta) metaParts.push(`...${mod}.meta`)
@@ -1231,6 +1325,8 @@ export function generateRouteModuleFromRoutes(
     if (layoutMod !== undefined) {
       if (exp.hasLoader) props.push(`${indent}loader: ${layoutMod}.loader`)
       if (exp.hasGuard) props.push(`${indent}beforeEnter: ${layoutMod}.guard`)
+      if (exp.hasLoaderKey) props.push(`${indent}loaderKey: ${layoutMod}.loaderKey`)
+      if (exp.hasGcTime) props.push(`${indent}gcTime: ${layoutMod}.gcTime`)
       if (exp.hasMeta || exp.hasRenderMode) {
         const metaParts: string[] = []
         if (exp.hasMeta) metaParts.push(`...${layoutMod}.meta`)
@@ -1307,6 +1403,12 @@ export function generateRouteModuleFromRoutes(
 /**
  * Generate a virtual module that maps URL patterns to their middleware exports.
  * Used by the server entry to dispatch per-route middleware.
+ *
+ * Detects whether each route file actually exports `middleware` (via
+ * `detectRouteExports` source scanning) and only emits an import for files
+ * that do. The `lazy()` import path tolerates missing exports, but the SSG
+ * static-import path fails Rolldown's missing-export check at build time —
+ * skipping no-middleware files keeps both paths working.
  */
 export function generateMiddlewareModule(files: string[], routesDir: string): string {
   const routes = parseFileRoutes(files)
@@ -1316,6 +1418,14 @@ export function generateMiddlewareModule(files: string[], routesDir: string): st
 
   for (const route of routes) {
     if (route.isLayout || route.isError || route.isLoading || route.isNotFound) continue
+    let hasMw = false
+    try {
+      const source = readFileSync(`${routesDir}/${route.filePath}`, 'utf-8')
+      hasMw = detectRouteExports(source).hasMiddleware
+    } catch {
+      // File can't be read — skip; the SSR runtime falls back gracefully.
+    }
+    if (!hasMw) continue
     const name = `_mw${counter++}`
     const fullPath = `${routesDir}/${route.filePath}`
     imports.push(`import { middleware as ${name} } from "${fullPath}"`)
@@ -1372,8 +1482,17 @@ export async function scanRouteFilesWithExports(
   defaultMode: RenderMode = 'ssr',
 ): Promise<FileRoute[]> {
   const { readFile } = await import('node:fs/promises')
-
-  const files = await scanRouteFiles(routesDir)
+  const { isApiRoute } = await import('./api-routes')
+
+  // Api routes (`api/**/*.ts`) live in the same routes tree but are served by
+  // a separate virtual module (`virtual:zero/api-routes`). Page-route
+  // generation MUST skip them — they export named HTTP method handlers
+  // (`GET`/`POST`/...), not a default page component, so the SSG `staticImports`
+  // mode would emit `import _N from "api/posts.ts"` and fail Rolldown's
+  // missing-export check at build time. The bug only surfaced under SSG
+  // because the regular lazy()-mode `import()` doesn't fail on missing
+  // default exports.
+  const files = (await scanRouteFiles(routesDir)).filter((f) => !isApiRoute(f))
   const exportsMap = new Map<string, RouteFileExports>()
 
   await Promise.all(