@pyreon/zero 0.15.0 → 0.18.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pyreon/zero",
-  "version": "0.15.0",
+  "version": "0.18.0",
   "description": "Pyreon Zero — zero-config full-stack framework powered by Pyreon and Vite",
   "license": "MIT",
   "author": "Vit Bokisch",
@@ -168,21 +168,22 @@
     "lint": "oxlint ."
   },
   "dependencies": {
-    "@pyreon/core": "^0.15.0",
-    "@pyreon/head": "^0.15.0",
-    "@pyreon/meta": "^0.15.0",
-    "@pyreon/router": "^0.15.0",
-    "@pyreon/runtime-dom": "^0.15.0",
-    "@pyreon/runtime-server": "^0.15.0",
-    "@pyreon/server": "^0.15.0",
-    "@pyreon/vite-plugin": "^0.15.0",
+    "@pyreon/core": "^0.18.0",
+    "@pyreon/head": "^0.18.0",
+    "@pyreon/meta": "^0.18.0",
+    "@pyreon/reactivity": "^0.18.0",
+    "@pyreon/router": "^0.18.0",
+    "@pyreon/runtime-dom": "^0.18.0",
+    "@pyreon/runtime-server": "^0.18.0",
+    "@pyreon/server": "^0.18.0",
+    "@pyreon/vite-plugin": "^0.18.0",
     "vite": "^8.0.0"
   },
   "devDependencies": {
+    "@pyreon/manifest": "0.13.1",
     "sharp": "^0.33.0"
   },
   "peerDependencies": {
-    "@pyreon/reactivity": "^0.15.0",
     "sharp": "^0.33.0"
   },
   "peerDependenciesMeta": {

package/src/adapters/bun.ts

@@ -1,13 +1,22 @@
-import type { Adapter, AdapterBuildOptions } from '../types'
+import type { Adapter, AdapterBuildOptions, AdapterRevalidateResult } from '../types'
 import { validateBuildInputs } from './validate'
 
 /**
  * Bun adapter — generates a standalone Bun.serve() entry.
+ *
+ * **SSG mode (PR J)**: no-op. Bun adapter exists for serving the SSR
+ * runtime; SSG output is already complete static HTML — serve it with
+ * any static-file server (`bun preview` / `bunx serve` / nginx / Caddy).
+ * Use `staticAdapter()` if you want explicit SSG semantics.
  */
 export function bunAdapter(): Adapter {
   return {
     name: 'bun',
     async build(options: AdapterBuildOptions) {
+      if (options.kind === 'ssg') {
+        // Bun runner has nothing to add for prerendered SSG dist.
+        return
+      }
       await validateBuildInputs(options)
       const { writeFile, cp, mkdir } = await import('node:fs/promises')
       const { join } = await import('node:path')
@@ -63,5 +72,15 @@ console.log("\\n  ⚡ Zero production server running on http://localhost:${port}
 
       await writeFile(join(outDir, 'index.ts'), serverEntry)
     },
+    async revalidate(_path: string): Promise<AdapterRevalidateResult> {
+      // Self-hosted Bun has no platform-driven ISR — same shape as
+      // nodeAdapter. See nodeAdapter.revalidate for full rationale.
+      if (process.env.NODE_ENV !== 'production') {
+        console.warn(
+          '[Pyreon] bunAdapter.revalidate() is a no-op — self-hosted Bun has no platform-driven ISR. Use mode: "isr" for runtime LRU caching, or vercelAdapter / cloudflareAdapter / netlifyAdapter for platform-driven build-time ISR.',
+        )
+      }
+      return { regenerated: false }
+    },
   }
 }

package/src/adapters/cloudflare.ts

@@ -1,5 +1,6 @@
-import type { Adapter, AdapterBuildOptions } from '../types'
+import type { Adapter, AdapterBuildOptions, AdapterRevalidateResult } from '../types'
 import { validateBuildInputs } from './validate'
+import { warnMissingEnv } from './warn-missing-env'
 
 /**
  * Cloudflare Pages adapter — generates output for Cloudflare Pages with Functions.
@@ -28,6 +29,34 @@ export function cloudflareAdapter(): Adapter {
   return {
     name: 'cloudflare',
     async build(options: AdapterBuildOptions) {
+      if (options.kind === 'ssg') {
+        // PR J — SSG branch. Emit Cloudflare Pages `_routes.json` with
+        // `include: []` + `exclude: ['/*']` — i.e. "every URL is a
+        // static asset, never invoke a Pages Function". Without this
+        // file, Pages defaults to running the worker on every request,
+        // which is wasteful for prerendered SSG output (and incurs
+        // function-invocation costs on paid plans).
+        //
+        // Reference: https://developers.cloudflare.com/pages/functions/routing/
+        // — `version: 1`, `include` lists URL globs that DO invoke the
+        // function, `exclude` lists globs that bypass it. Setting
+        // `include: []` makes the function unreachable; the result is
+        // a pure-static deploy.
+        //
+        // Deploy with: `npx wrangler pages deploy ./dist`
+        const { writeFile } = await import('node:fs/promises')
+        const { join } = await import('node:path')
+        const routesConfig = {
+          version: 1,
+          include: [] as string[],
+          exclude: ['/*'],
+        }
+        await writeFile(
+          join(options.outDir, '_routes.json'),
+          JSON.stringify(routesConfig, null, 2),
+        )
+        return
+      }
       await validateBuildInputs(options)
       const { writeFile, cp, mkdir } = await import('node:fs/promises')
       const { join } = await import('node:path')
@@ -80,5 +109,53 @@ export default {
 
       await writeFile(join(outDir, '_routes.json'), JSON.stringify(routesConfig, null, 2))
     },
+    async revalidate(path: string): Promise<AdapterRevalidateResult> {
+      // Cloudflare Pages ISR via Cache API delete + zone purge.
+      // Reads `CLOUDFLARE_ZONE_ID` and `CLOUDFLARE_API_TOKEN` from env
+      // (set in Workers / Pages dashboard → Variables). The zone
+      // purge endpoint accepts a list of URLs and removes them from
+      // every PoP's edge cache; the next visitor triggers a fresh
+      // origin fetch which rebuilds the prerendered page.
+      //
+      // Reference: https://developers.cloudflare.com/api/operations/zone-purge
+      const zoneId = process.env.CLOUDFLARE_ZONE_ID
+      const apiToken = process.env.CLOUDFLARE_API_TOKEN
+      const siteUrl = process.env.CLOUDFLARE_SITE_URL
+      if (!zoneId || !apiToken || !siteUrl) {
+        // M2.4 — warn even in production (dedupe per process). See vercel.ts
+        // for the rationale.
+        const missing: string[] = []
+        if (!zoneId) missing.push('CLOUDFLARE_ZONE_ID')
+        if (!apiToken) missing.push('CLOUDFLARE_API_TOKEN')
+        if (!siteUrl) missing.push('CLOUDFLARE_SITE_URL')
+        return warnMissingEnv(
+          'cloudflare',
+          missing,
+          'Set them in Cloudflare Pages dashboard → Settings → Environment Variables. Note: Cloudflare imposes a 1000-purge-per-24h rate limit per zone — high-frequency revalidation will hit it.',
+        )
+      }
+      const fullUrl = `${siteUrl.replace(/\/$/, '')}${path.startsWith('/') ? path : `/${path}`}`
+      try {
+        const res = await fetch(
+          `https://api.cloudflare.com/client/v4/zones/${zoneId}/purge_cache`,
+          {
+            method: 'POST',
+            headers: {
+              'Authorization': `Bearer ${apiToken}`,
+              'Content-Type': 'application/json',
+            },
+            body: JSON.stringify({ files: [fullUrl] }),
+          },
+        )
+        return { regenerated: res.ok }
+      } catch (err) {
+        if (process.env.NODE_ENV !== 'production') {
+          console.warn(
+            `[Pyreon] cloudflareAdapter.revalidate(${path}) failed: ${err instanceof Error ? err.message : String(err)}`,
+          )
+        }
+        return { regenerated: false }
+      }
+    },
   }
 }

package/src/adapters/index.ts

@@ -16,11 +16,33 @@ import { vercelAdapter } from './vercel'
 /**
  * Resolve the adapter from config.
  * Returns a built-in adapter or throws if unknown.
+ *
+ * Accepts BOTH forms — the `ZeroConfig.adapter` type advertises string
+ * names (`'vercel'` / `'cloudflare'` / …) but the scaffolded templates
+ * historically emit `adapter: vercelAdapter()` (an Adapter instance via
+ * the named factory). Both work: a string goes through the switch lookup;
+ * an Adapter object (duck-typed via `name` + `build` fields) passes
+ * through. Pre-PR-J `resolveAdapter` was never called from production
+ * code so the string-vs-object mismatch was invisible; PR J wires the
+ * call into `ssgPlugin.closeBundle`, surfacing the contract divergence.
+ * The passthrough preserves both shapes without a breaking type change.
  */
 export function resolveAdapter(config: ZeroConfig): Adapter {
-  const name = config.adapter ?? 'node'
+  const value = config.adapter ?? 'node'
 
-  switch (name) {
+  // Passthrough for already-constructed Adapter instances. Scaffolded
+  // templates emit `adapter: vercelAdapter()` — detect by duck-typing
+  // the two required Adapter fields (`name: string` + `build: function`).
+  if (
+    typeof value === 'object'
+    && value !== null
+    && typeof (value as Adapter).name === 'string'
+    && typeof (value as Adapter).build === 'function'
+  ) {
+    return value as Adapter
+  }
+
+  switch (value) {
     case 'node':
       return nodeAdapter()
     case 'bun':
@@ -34,6 +56,6 @@ export function resolveAdapter(config: ZeroConfig): Adapter {
     case 'netlify':
       return netlifyAdapter()
     default:
-      throw new Error(`[Pyreon] Unknown adapter: "${name}". Use "node", "bun", "static", "vercel", "cloudflare", or "netlify".`)
+      throw new Error(`[Pyreon] Unknown adapter: "${String(value)}". Use "node", "bun", "static", "vercel", "cloudflare", or "netlify".`)
   }
 }

package/src/adapters/netlify.ts

@@ -1,5 +1,6 @@
-import type { Adapter, AdapterBuildOptions } from '../types'
+import type { Adapter, AdapterBuildOptions, AdapterRevalidateResult } from '../types'
 import { validateBuildInputs } from './validate'
+import { warnMissingEnv } from './warn-missing-env'
 
 /**
  * Netlify adapter — generates output for Netlify Functions (v2).
@@ -23,6 +24,31 @@ export function netlifyAdapter(): Adapter {
   return {
     name: 'netlify',
     async build(options: AdapterBuildOptions) {
+      if (options.kind === 'ssg') {
+        // PR J — SSG branch. Emit `netlify.toml` with `publish = "."`
+        // (the dist root) and asset-cache headers — no functions. Tells
+        // Netlify "this dist directory IS the publishable output, serve
+        // it as a static site". Without this file, Netlify falls back
+        // to whatever the user has at the repo root (might miss the
+        // dist/ direct-upload shape).
+        //
+        // PR B's `dist/_redirects` (loader-redirect manifest) is
+        // emitted by ssgPlugin BEFORE the adapter runs, so this branch
+        // doesn't need to write it. The two files coexist cleanly —
+        // Netlify reads both.
+        const { writeFile } = await import('node:fs/promises')
+        const { join } = await import('node:path')
+        const toml = `[build]
+  publish = "."
+
+[[headers]]
+  for = "/assets/*"
+  [headers.values]
+    Cache-Control = "public, max-age=31536000, immutable"
+`
+        await writeFile(join(options.outDir, 'netlify.toml'), toml)
+        return
+      }
       await validateBuildInputs(options)
       const { writeFile, cp, mkdir } = await import('node:fs/promises')
       const { join } = await import('node:path')
@@ -82,5 +108,41 @@ export const config = {
 
       await writeFile(join(outDir, 'netlify.toml'), toml)
     },
+    async revalidate(path: string): Promise<AdapterRevalidateResult> {
+      // Netlify ISR via Build Hook trigger. Reads
+      // `NETLIFY_BUILD_HOOK_URL` from env (created in Site settings →
+      // Build hooks). Posting to the hook triggers a partial rebuild
+      // — Netlify rebuilds only the pages whose source has changed
+      // since last deploy. The path arg is included as a `trigger_title`
+      // for audit traceability in the Netlify deploy log; Netlify
+      // doesn't accept per-path revalidation natively (the hook
+      // re-runs the full build).
+      //
+      // Reference: https://docs.netlify.com/configure-builds/build-hooks/
+      const hookUrl = process.env.NETLIFY_BUILD_HOOK_URL
+      if (!hookUrl) {
+        // M2.4 — warn even in production (dedupe per process). See vercel.ts
+        // for the rationale.
+        return warnMissingEnv(
+          'netlify',
+          ['NETLIFY_BUILD_HOOK_URL'],
+          'Create a build hook in Site settings → Build & deploy → Build hooks → Add build hook. Note: Netlify Build Hooks trigger a FULL site rebuild — the path arg is recorded as `trigger_title` for audit traceability but Netlify doesn\'t support per-page ISR natively.',
+        )
+      }
+      try {
+        const triggerTitle = `revalidate:${path}`
+        const res = await fetch(`${hookUrl}?trigger_title=${encodeURIComponent(triggerTitle)}`, {
+          method: 'POST',
+        })
+        return { regenerated: res.ok }
+      } catch (err) {
+        if (process.env.NODE_ENV !== 'production') {
+          console.warn(
+            `[Pyreon] netlifyAdapter.revalidate(${path}) failed: ${err instanceof Error ? err.message : String(err)}`,
+          )
+        }
+        return { regenerated: false }
+      }
+    },
   }
 }

package/src/adapters/node.ts

@@ -1,13 +1,22 @@
-import type { Adapter, AdapterBuildOptions } from '../types'
+import type { Adapter, AdapterBuildOptions, AdapterRevalidateResult } from '../types'
 import { validateBuildInputs } from './validate'
 
 /**
  * Node.js adapter — generates a standalone server entry using node:http.
+ *
+ * **SSG mode (PR J)**: no-op. Node adapter exists for serving the SSR
+ * runtime; SSG output is already complete static HTML — serve it with
+ * any static-file server (`bun preview` / nginx / Caddy / `npx serve`).
+ * Use `staticAdapter()` if you want explicit SSG semantics.
  */
 export function nodeAdapter(): Adapter {
   return {
     name: 'node',
     async build(options: AdapterBuildOptions) {
+      if (options.kind === 'ssg') {
+        // Node runner has nothing to add for prerendered SSG dist.
+        return
+      }
       await validateBuildInputs(options)
       const { writeFile, cp, mkdir } = await import('node:fs/promises')
       const { join } = await import('node:path')
@@ -108,5 +117,20 @@ server.listen(${port}, () => {
       await writeFile(join(outDir, 'index.js'), serverEntry)
       await writeFile(join(outDir, 'package.json'), JSON.stringify({ type: 'module' }, null, 2))
     },
+    async revalidate(_path: string): Promise<AdapterRevalidateResult> {
+      // Self-hosted Node has no platform-driven ISR. Real ISR support
+      // requires a reverse-proxy cache (nginx/varnish) + your own
+      // cache-purge wiring, OR mode: 'isr' for runtime LRU caching.
+      // This no-op preserves the Adapter API contract; user code that
+      // calls `adapter.revalidate(path)` against a self-hosted Node
+      // deploy gets the same `regenerated: false` shape as the static
+      // adapter, so migrating between adapters doesn't surprise.
+      if (process.env.NODE_ENV !== 'production') {
+        console.warn(
+          '[Pyreon] nodeAdapter.revalidate() is a no-op — self-hosted Node has no platform-driven ISR. Use mode: "isr" for runtime LRU caching, or vercelAdapter / cloudflareAdapter / netlifyAdapter for platform-driven build-time ISR.',
+        )
+      }
+      return { regenerated: false }
+    },
   }
 }

package/src/adapters/static.ts

@@ -1,17 +1,42 @@
-import type { Adapter, AdapterBuildOptions } from '../types'
+import type { Adapter, AdapterBuildOptions, AdapterRevalidateResult } from '../types'
 
 /**
  * Static adapter — just copies the client build output.
  * Used with SSG mode where all pages are pre-rendered at build time.
+ *
+ * **SSG mode (PR J)**: no-op — `outDir` already IS the dist directory
+ * the SSG plugin produced. Copying it onto itself would only fail. The
+ * static adapter is the canonical zero-overhead deploy target for
+ * pure-static sites.
+ *
+ * **SSR mode**: copies clientOutDir → outDir. Calling `static` with SSR
+ * mode is unusual — the static adapter doesn't support server-side
+ * execution — but preserved as a "client-only output packager".
  */
 export function staticAdapter(): Adapter {
   return {
     name: 'static',
     async build(options: AdapterBuildOptions) {
+      if (options.kind === 'ssg') {
+        // SSG dist is already at outDir — nothing to copy or rewrite.
+        return
+      }
       const { cp, mkdir } = await import('node:fs/promises')
 
       await mkdir(options.outDir, { recursive: true })
       await cp(options.clientOutDir, options.outDir, { recursive: true })
     },
+    async revalidate(_path: string): Promise<AdapterRevalidateResult> {
+      // Static hosts have no platform-driven ISR. Revalidation requires
+      // a full rebuild + redeploy. Returns `regenerated: false` so user
+      // code can branch on the no-op shape and degrade gracefully when
+      // migrating between adapters.
+      if (process.env.NODE_ENV !== 'production') {
+        console.warn(
+          '[Pyreon] staticAdapter.revalidate() is a no-op — static hosts require a full rebuild + redeploy to refresh prerendered pages. Use vercelAdapter / cloudflareAdapter / netlifyAdapter for platform-driven ISR.',
+        )
+      }
+      return { regenerated: false }
+    },
   }
 }

package/src/adapters/validate.ts

@@ -1,11 +1,18 @@
 import type { AdapterBuildOptions } from '../types'
 
 /**
- * Validate that adapter build inputs exist before copying.
+ * Validate that SSR-mode adapter build inputs exist before copying.
  * Throws with a clear error message if directories are missing.
+ *
+ * SSG-mode passes through unchanged — the SSG branch doesn't need a
+ * server entry (every page is prerendered) and `outDir` IS the dist
+ * directory the SSG plugin already populated. Validating it here would
+ * be redundant.
+ *
  * @internal
  */
 export async function validateBuildInputs(options: AdapterBuildOptions): Promise<void> {
+  if (options.kind !== 'ssr') return
   const { existsSync } = await import('node:fs')
   if (!existsSync(options.clientOutDir)) {
     throw new Error(`[Pyreon] Client build output not found: ${options.clientOutDir}. Run "vite build" first.`)

package/src/adapters/vercel.ts

@@ -1,5 +1,6 @@
-import type { Adapter, AdapterBuildOptions } from '../types'
+import type { Adapter, AdapterBuildOptions, AdapterRevalidateResult } from '../types'
 import { validateBuildInputs } from './validate'
+import { warnMissingEnv } from './warn-missing-env'
 
 /**
  * Vercel adapter — generates output for Vercel's Build Output API v3.
@@ -23,6 +24,36 @@ export function vercelAdapter(): Adapter {
   return {
     name: 'vercel',
     async build(options: AdapterBuildOptions) {
+      if (options.kind === 'ssg') {
+        // PR J — SSG branch. Emit Vercel Build Output API v3 STATIC
+        // variant: `.vercel/output/config.json` listing routes config
+        // for the prerendered dist; no functions (every page is
+        // already static). Vercel's deployer reads this config + the
+        // built dist content as the static asset root — no runtime SSR.
+        //
+        // We do NOT copy files into `.vercel/output/static/` — the
+        // standard Vercel CLI deploy flow detects the dist root
+        // automatically. Adapters that move files break user-side
+        // post-build steps (sourcemap upload, perf scripts, custom
+        // asset handling). Writing config.json alone is the
+        // minimum-impact signal "this is a prerendered site".
+        const { writeFile, mkdir } = await import('node:fs/promises')
+        const { join } = await import('node:path')
+        const vercelDir = join(options.outDir, '.vercel', 'output')
+        await mkdir(vercelDir, { recursive: true })
+        const config = {
+          version: 3,
+          routes: [
+            // Long-cache hashed assets; mirrors the SSR config above.
+            {
+              src: '/assets/(.*)',
+              headers: { 'Cache-Control': 'public, max-age=31536000, immutable' },
+            },
+          ],
+        }
+        await writeFile(join(vercelDir, 'config.json'), JSON.stringify(config, null, 2))
+        return
+      }
       await validateBuildInputs(options)
       const { writeFile, cp, mkdir } = await import('node:fs/promises')
       const { join } = await import('node:path')
@@ -82,5 +113,49 @@ export default async function handler(req) {
 
       await writeFile(join(vercelDir, 'config.json'), JSON.stringify(config, null, 2))
     },
+    async revalidate(path: string): Promise<AdapterRevalidateResult> {
+      // Vercel ISR API — POST to a deployment-relative
+      // revalidation endpoint with a secret token. Reads
+      // `VERCEL_DEPLOYMENT_URL` (auto-injected by Vercel runtime) and
+      // `VERCEL_REVALIDATE_TOKEN` (user-set in dashboard) from env.
+      // Mirrors Next.js's `res.revalidate()` shape — a HEAD request
+      // with the path + token, Vercel rebuilds the page in the
+      // background and serves stale-while-revalidate to subsequent
+      // visitors until the rebuild lands.
+      //
+      // No `regenerated: true` until Vercel acks 200 — partial-purge
+      // behaviour (the platform queues the regenerate but doesn't
+      // confirm it landed) is documented as a "false-positive
+      // possible" caveat in the Adapter.revalidate JSDoc.
+      const deploymentUrl = process.env.VERCEL_DEPLOYMENT_URL ?? process.env.VERCEL_URL
+      const token = process.env.VERCEL_REVALIDATE_TOKEN
+      if (!deploymentUrl || !token) {
+        // M2.4 — warn even in production (dedupe per process). Pre-fix the
+        // warn was DEV-gated, but production is exactly where missing env
+        // vars surface — CMS triggers revalidate, nothing happens, no
+        // signal. Now the FIRST call always warns; subsequent calls dedupe.
+        const missing: string[] = []
+        if (!deploymentUrl) missing.push('VERCEL_DEPLOYMENT_URL (or VERCEL_URL)')
+        if (!token) missing.push('VERCEL_REVALIDATE_TOKEN')
+        return warnMissingEnv(
+          'vercel',
+          missing,
+          'Set the token in Vercel project settings → Environment Variables. VERCEL_DEPLOYMENT_URL / VERCEL_URL is auto-injected by the Vercel runtime.',
+        )
+      }
+      const protocol = deploymentUrl.startsWith('http') ? '' : 'https://'
+      const url = `${protocol}${deploymentUrl}/api/_pyreon-revalidate?path=${encodeURIComponent(path)}&secret=${encodeURIComponent(token)}`
+      try {
+        const res = await fetch(url, { method: 'POST' })
+        return { regenerated: res.ok }
+      } catch (err) {
+        if (process.env.NODE_ENV !== 'production') {
+          console.warn(
+            `[Pyreon] vercelAdapter.revalidate(${path}) failed: ${err instanceof Error ? err.message : String(err)}`,
+          )
+        }
+        return { regenerated: false }
+      }
+    },
   }
 }

package/src/adapters/warn-missing-env.ts

@@ -0,0 +1,49 @@
+import type { AdapterRevalidateResult } from '../types'
+
+/**
+ * M2.4 — Loud first-call warning for missing adapter env vars.
+ *
+ * Pre-M2.4 the adapter `revalidate()` methods returned `{ regenerated: false }`
+ * silently in production when required env vars were missing. The dev-mode
+ * warning was gated on `process.env.NODE_ENV !== 'production'` — exactly the
+ * env condition that DEPLOYED apps run under, where users would most need
+ * the signal. Symptom: CMS triggers `adapter.revalidate(path)`, nothing
+ * happens, no console output, no failure mode reported back to the
+ * triggering webhook handler. The bug only surfaces when someone notices
+ * stale content.
+ *
+ * Fix: warn ALWAYS (regardless of NODE_ENV) on the FIRST invocation per
+ * `(adapterName + varSet)` combination. Dedupe via a module-level Set so
+ * a busy revalidation handler doesn't spam logs — one warn per process
+ * per missing-env-set is enough to expose the misconfiguration.
+ *
+ * Returns the canonical `{ regenerated: false }` so adapters can write
+ * `return warnMissingEnv(...)` as a one-liner.
+ *
+ * @internal Exposed for unit tests via `_internal.warnMissingEnv` (not yet wired) + `_warnedKeys` reset.
+ */
+const _warnedKeys = new Set<string>()
+
+export function warnMissingEnv(
+  adapterName: string,
+  missingVars: readonly string[],
+  hint: string,
+): AdapterRevalidateResult {
+  const key = `${adapterName}:${missingVars.join(',')}`
+  if (!_warnedKeys.has(key)) {
+    _warnedKeys.add(key)
+    // oxlint-disable-next-line no-console
+    console.warn(
+      `[Pyreon] ${adapterName}Adapter.revalidate() needs ${missingVars.join(' + ')} env var(s). ${hint}`,
+    )
+  }
+  return { regenerated: false }
+}
+
+/**
+ * Reset the dedup Set. Test-only — production code never reaches this.
+ * @internal
+ */
+export function _resetWarnedKeys(): void {
+  _warnedKeys.clear()
+}

package/src/app.ts

@@ -21,6 +21,19 @@ export interface CreateAppOptions {
 
   /** Global error component. */
   errorComponent?: ComponentFn
+
+  /**
+   * Base URL prefix for the deployed app (e.g. `/blog/`). Forwarded to
+   * `createRouter({ base })` so RouterLinks render correctly prefixed
+   * hrefs (`<a href="/blog/about">` instead of `<a href="/about">`) and
+   * the router strips the prefix from incoming URLs before matching.
+   *
+   * Default: `'/'`. Pre-fix this was disconnected from `zero({ base })`
+   * — RouterLinks rendered un-prefixed hrefs even when Vite's asset URL
+   * rewriting was correctly using the prefix, causing client-side
+   * navigation to break against subpath deploys.
+   */
+  base?: string
 }
 
 /**
@@ -33,6 +46,7 @@ export function createApp(options: CreateAppOptions) {
     routes: options.routes,
     mode: options.routerMode ?? 'history',
     ...(options.url ? { url: options.url } : {}),
+    ...(options.base && options.base !== '/' ? { base: options.base } : {}),
     scrollBehavior: 'top',
   })
 

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) ───────────────────────────────────────