@jasonshimmy/vite-plugin-cer-app 0.6.0 → 0.7.0

package/dist/runtime/entry-server-template.js.map

@@ -1 +1 @@
-{"version":3,"file":"entry-server-template.js","sourceRoot":"","sources":["../../src/runtime/entry-server-template.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AACH,MAAM,CAAC,MAAM,qBAAqB,GAAG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAmOpC,CAAA"}
+{"version":3,"file":"entry-server-template.js","sourceRoot":"","sources":["../../src/runtime/entry-server-template.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AACH,MAAM,CAAC,MAAM,qBAAqB,GAAG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAoPpC,CAAA"}

package/dist/runtime/isr-handler.d.ts

@@ -0,0 +1,40 @@
+/**
+ * createIsrHandler — portable stale-while-revalidate ISR factory.
+ *
+ * Wraps any Express-compatible SSR handler with an in-memory ISR cache.
+ * Routes that export `meta.ssg.revalidate` get cached for the declared TTL.
+ *
+ * Usage (Express):
+ *   import { createIsrHandler } from '@jasonshimmy/vite-plugin-cer-app/isr'
+ *   import { handler, routes } from './dist/server/server.js'
+ *   app.use(createIsrHandler(routes, handler))
+ *
+ * Usage (Hono):
+ *   import { createIsrHandler } from '@jasonshimmy/vite-plugin-cer-app/isr'
+ *   import { handler, routes } from './dist/server/server.js'
+ *   app.use('*', createIsrHandler(routes, handler))
+ */
+import type { IncomingMessage, ServerResponse } from 'node:http';
+export interface IsrCacheEntry {
+    html: string;
+    headers: Record<string, string>;
+    statusCode: number;
+    builtAt: number;
+    revalidate: number;
+    revalidating: boolean;
+}
+export type SsrHandlerFn = (req: IncomingMessage, res: ServerResponse) => unknown;
+/**
+ * Wraps an SSR handler with stale-while-revalidate ISR caching.
+ *
+ * Routes that declare `meta.ssg.revalidate` in the `routes` array are cached
+ * in memory. After the TTL expires the stale response is served immediately
+ * while a fresh render runs in the background (stale-while-revalidate).
+ *
+ * Routes without a `revalidate` value are passed through to the handler directly.
+ */
+export declare function createIsrHandler(routes: Array<{
+    path: string;
+    meta?: Record<string, unknown>;
+}>, handler: SsrHandlerFn): SsrHandlerFn;
+//# sourceMappingURL=isr-handler.d.ts.map

package/dist/runtime/isr-handler.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"isr-handler.d.ts","sourceRoot":"","sources":["../../src/runtime/isr-handler.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,OAAO,KAAK,EAAE,eAAe,EAAE,cAAc,EAAE,MAAM,WAAW,CAAA;AAEhE,MAAM,WAAW,aAAa;IAC5B,IAAI,EAAE,MAAM,CAAA;IACZ,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;IAC/B,UAAU,EAAE,MAAM,CAAA;IAClB,OAAO,EAAE,MAAM,CAAA;IACf,UAAU,EAAE,MAAM,CAAA;IAClB,YAAY,EAAE,OAAO,CAAA;CACtB;AAED,MAAM,MAAM,YAAY,GAAG,CAAC,GAAG,EAAE,eAAe,EAAE,GAAG,EAAE,cAAc,KAAK,OAAO,CAAA;AA+FjF;;;;;;;;GAQG;AACH,wBAAgB,gBAAgB,CAC9B,MAAM,EAAE,KAAK,CAAC;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;CAAE,CAAC,EAC/D,OAAO,EAAE,YAAY,GACpB,YAAY,CA+Cd"}

package/dist/runtime/isr-handler.js

@@ -0,0 +1,152 @@
+/**
+ * createIsrHandler — portable stale-while-revalidate ISR factory.
+ *
+ * Wraps any Express-compatible SSR handler with an in-memory ISR cache.
+ * Routes that export `meta.ssg.revalidate` get cached for the declared TTL.
+ *
+ * Usage (Express):
+ *   import { createIsrHandler } from '@jasonshimmy/vite-plugin-cer-app/isr'
+ *   import { handler, routes } from './dist/server/server.js'
+ *   app.use(createIsrHandler(routes, handler))
+ *
+ * Usage (Hono):
+ *   import { createIsrHandler } from '@jasonshimmy/vite-plugin-cer-app/isr'
+ *   import { handler, routes } from './dist/server/server.js'
+ *   app.use('*', createIsrHandler(routes, handler))
+ */
+// ─── Internal helpers ─────────────────────────────────────────────────────────
+function _matchPattern(pattern, urlPath) {
+    const norm = (s) => s.replace(/\/+$/, '') || '/';
+    if (norm(pattern) === norm(urlPath))
+        return true;
+    const regexStr = '^' +
+        norm(pattern)
+            .replace(/[.+?^${}()|[\]\\]/g, '\\$&')
+            .replace(/:[^/]+\*/g, '.*')
+            .replace(/:[^/]+/g, '[^/]+') +
+        '$';
+    return new RegExp(regexStr).test(norm(urlPath));
+}
+function _findRevalidate(routes, urlPath) {
+    for (const route of routes) {
+        if (_matchPattern(route.path, urlPath)) {
+            const ssg = route.meta?.ssg;
+            if (typeof ssg?.revalidate === 'number')
+                return ssg.revalidate;
+            return null;
+        }
+    }
+    return null;
+}
+async function _renderForCache(urlPath, handler, revalidate) {
+    return new Promise((resolve) => {
+        const chunks = [];
+        const capturedHeaders = {};
+        let capturedStatus = 200;
+        const fakeRes = {
+            get statusCode() { return capturedStatus; },
+            set statusCode(v) { capturedStatus = v; },
+            setHeader(name, value) {
+                capturedHeaders[name.toLowerCase()] = value;
+            },
+            write(chunk) {
+                chunks.push(Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk, 'utf-8'));
+            },
+            end(body) {
+                if (body !== undefined) {
+                    chunks.push(Buffer.isBuffer(body) ? body : Buffer.from(String(body), 'utf-8'));
+                }
+                resolve({
+                    html: Buffer.concat(chunks).toString('utf-8'),
+                    headers: Object.fromEntries(Object.entries(capturedHeaders).map(([k, v]) => [k, Array.isArray(v) ? v.join(', ') : v])),
+                    statusCode: capturedStatus,
+                    builtAt: Date.now(),
+                    revalidate,
+                    revalidating: false,
+                });
+            },
+        };
+        const fakeReq = {
+            url: urlPath,
+            method: 'GET',
+            headers: { accept: 'text/html' },
+        };
+        try {
+            const result = handler(fakeReq, fakeRes);
+            if (result && typeof result.catch === 'function') {
+                ;
+                result.catch(() => resolve(null));
+            }
+        }
+        catch {
+            resolve(null);
+        }
+    });
+}
+function _serveFromCache(entry, res, status) {
+    res.statusCode = entry.statusCode;
+    for (const [name, value] of Object.entries(entry.headers)) {
+        res.setHeader(name, value);
+    }
+    res.setHeader('X-Cache', status);
+    res.end(entry.html);
+}
+// ─── Public API ───────────────────────────────────────────────────────────────
+/**
+ * Wraps an SSR handler with stale-while-revalidate ISR caching.
+ *
+ * Routes that declare `meta.ssg.revalidate` in the `routes` array are cached
+ * in memory. After the TTL expires the stale response is served immediately
+ * while a fresh render runs in the background (stale-while-revalidate).
+ *
+ * Routes without a `revalidate` value are passed through to the handler directly.
+ */
+export function createIsrHandler(routes, handler) {
+    const cache = new Map();
+    return async (req, res) => {
+        const urlPath = (req.url ?? '/').split('?')[0];
+        const revalidate = _findRevalidate(routes, urlPath);
+        if (revalidate === null) {
+            return handler(req, res);
+        }
+        const cached = cache.get(urlPath);
+        const now = Date.now();
+        if (cached) {
+            const ageSeconds = (now - cached.builtAt) / 1000;
+            if (ageSeconds < cached.revalidate) {
+                _serveFromCache(cached, res, 'HIT');
+                return;
+            }
+            if (!cached.revalidating) {
+                cached.revalidating = true;
+                _serveFromCache(cached, res, 'STALE');
+                const timeout = setTimeout(() => { if (cached)
+                    cached.revalidating = false; }, 30_000);
+                _renderForCache(urlPath, handler, revalidate).then((entry) => {
+                    clearTimeout(timeout);
+                    if (entry)
+                        cache.set(urlPath, entry);
+                    else if (cached)
+                        cached.revalidating = false;
+                }).catch(() => {
+                    clearTimeout(timeout);
+                    if (cached)
+                        cached.revalidating = false;
+                });
+                return;
+            }
+            _serveFromCache(cached, res, 'STALE');
+            return;
+        }
+        // Cache miss — render, cache, then serve.
+        const entry = await _renderForCache(urlPath, handler, revalidate);
+        if (entry) {
+            cache.set(urlPath, entry);
+            _serveFromCache(entry, res, 'HIT');
+        }
+        else {
+            await handler(req, res);
+        }
+    };
+}
+//# sourceMappingURL=isr-handler.js.map

package/dist/runtime/isr-handler.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"isr-handler.js","sourceRoot":"","sources":["../../src/runtime/isr-handler.ts"],"names":[],"mappings":"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"}

package/dist/types/page.d.ts

@@ -28,6 +28,20 @@ export interface PageMeta {
      * @example export const meta = { transition: 'fade' }
      */
     transition?: string | boolean;
+    /**
+     * Per-route rendering strategy. Overrides the global `mode` for this route.
+     *
+     * - `'server'` — always render server-side, never pre-render. In SSG mode
+     *   the route is skipped during the static build.
+     * - `'static'` — always serve pre-rendered static HTML. In the SSR preview
+     *   server the pre-rendered file is served from disk; falls back to SSR if
+     *   not found.
+     * - `'spa'`    — client-only. In SSR mode the server returns the SPA shell
+     *   (index.html) without rendering. In SSG mode the route is skipped.
+     *
+     * @example export const meta = { render: 'server' }
+     */
+    render?: 'static' | 'server' | 'spa';
 }
 export interface PageLoaderContext<P extends Record<string, string> = Record<string, string>> {
     params: P;

package/dist/types/page.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"page.d.ts","sourceRoot":"","sources":["../../src/types/page.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,WAAW,CAAA;AAEhD,MAAM,MAAM,eAAe,GAAG,MAAM,GAAG,MAAM,GAAG,SAAS,GAAG,MAAM,CAAA;AAElE,MAAM,WAAW,eAAe;IAC9B,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;CAC/B;AAED,MAAM,WAAW,aAAa;IAC5B,KAAK,CAAC,EAAE,MAAM,OAAO,CAAC,eAAe,EAAE,CAAC,GAAG,eAAe,EAAE,CAAA;IAC5D;;;;;;OAMG;IACH,UAAU,CAAC,EAAE,MAAM,CAAA;CACpB;AAED,MAAM,WAAW,QAAQ;IACvB,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,UAAU,CAAC,EAAE,MAAM,EAAE,CAAA;IACrB,OAAO,CAAC,EAAE,eAAe,CAAA;IACzB,GAAG,CAAC,EAAE,aAAa,CAAA;IACnB;;;;;;;OAOG;IACH,UAAU,CAAC,EAAE,MAAM,GAAG,OAAO,CAAA;CAC9B;AAED,MAAM,WAAW,iBAAiB,CAAC,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC;IAC1F,MAAM,EAAE,CAAC,CAAA;IACT,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;IAC7B,GAAG,EAAE,eAAe,CAAA;CACrB;AAED,MAAM,MAAM,UAAU,CACpB,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,EACzD,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,IACzB,CAAC,GAAG,EAAE,iBAAiB,CAAC,CAAC,CAAC,KAAK,OAAO,CAAC,CAAC,CAAC,GAAG,CAAC,CAAA"}
+{"version":3,"file":"page.d.ts","sourceRoot":"","sources":["../../src/types/page.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,WAAW,CAAA;AAEhD,MAAM,MAAM,eAAe,GAAG,MAAM,GAAG,MAAM,GAAG,SAAS,GAAG,MAAM,CAAA;AAElE,MAAM,WAAW,eAAe;IAC9B,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;CAC/B;AAED,MAAM,WAAW,aAAa;IAC5B,KAAK,CAAC,EAAE,MAAM,OAAO,CAAC,eAAe,EAAE,CAAC,GAAG,eAAe,EAAE,CAAA;IAC5D;;;;;;OAMG;IACH,UAAU,CAAC,EAAE,MAAM,CAAA;CACpB;AAED,MAAM,WAAW,QAAQ;IACvB,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,UAAU,CAAC,EAAE,MAAM,EAAE,CAAA;IACrB,OAAO,CAAC,EAAE,eAAe,CAAA;IACzB,GAAG,CAAC,EAAE,aAAa,CAAA;IACnB;;;;;;;OAOG;IACH,UAAU,CAAC,EAAE,MAAM,GAAG,OAAO,CAAA;IAC7B;;;;;;;;;;;;OAYG;IACH,MAAM,CAAC,EAAE,QAAQ,GAAG,QAAQ,GAAG,KAAK,CAAA;CACrC;AAED,MAAM,WAAW,iBAAiB,CAAC,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC;IAC1F,MAAM,EAAE,CAAC,CAAA;IACT,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;IAC7B,GAAG,EAAE,eAAe,CAAA;CACrB;AAED,MAAM,MAAM,UAAU,CACpB,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,EACzD,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,IACzB,CAAC,GAAG,EAAE,iBAAiB,CAAC,CAAC,CAAC,KAAK,OAAO,CAAC,CAAC,CAAC,GAAG,CAAC,CAAA"}

package/docs/data-loading.md

@@ -123,18 +123,85 @@ export const loader: PageLoader<{ slug: string }> = async ({ params }) => {
 
 ## Error handling in loaders
 
-Unhandled errors in `loader` propagate to the SSR error handler and return a 500 response. Handle expected failures explicitly:
+When a `loader` throws, the SSR error boundary intercepts it:
+
+- If `app/error.ts` exists, the server renders the `page-error` component instead of the normal page and returns the appropriate HTTP status.
+- If `app/error.ts` does not exist, the error is logged to the server console and a blank 500 response is returned.
+
+To send a specific HTTP status code from a loader, attach a `status` property to the thrown error:
 
 ```ts
 export const loader: PageLoader<{ id: string }> = async ({ params }) => {
   const item = await db.item.findById(params.id)
   if (!item) {
-    throw new Response('Not Found', { status: 404 })
+    const err = Object.assign(new Error('Not Found'), { status: 404 })
+    throw err
   }
   return { item }
 }
 ```
 
+You can also throw a standard `Response` — the framework reads its `.status` property:
+
+```ts
+throw new Response('Not Found', { status: 404 })
+```
+
+Unhandled errors without a `status` property default to HTTP 500.
+
+---
+
+## Error boundary — `app/error.ts`
+
+Create `app/error.ts` to define a custom error page shown when navigation fails. The file must export a custom element named `page-error`:
+
+```ts
+// app/error.ts
+component('page-error', () => {
+  const props = useProps<{ error: string; status: string }>({
+    error: 'An unexpected error occurred.',
+    status: '500',
+  })
+
+  return html`
+    <div style="padding:2rem">
+      <h2 style="color:#c00">Error ${props.status}</h2>
+      <p>${props.error}</p>
+      <button @click="${() => (globalThis as any).resetError?.()}">
+        Try again
+      </button>
+    </div>
+  `
+})
+```
+
+### Props received by `page-error`
+
+| Prop | Type | Source |
+|------|------|--------|
+| `error` | `string` | Error message from the thrown value |
+| `status` | `string` | HTTP status code as a string (`"404"`, `"500"`, etc.) — **SSR only** |
+
+### `resetError()`
+
+The framework exposes `globalThis.resetError()` as a global function. Calling it clears the error state and re-navigates to the current path, giving the user a way to recover without a full page reload.
+
+```ts
+// Call from a button click handler inside page-error
+(globalThis as any).resetError?.()
+```
+
+### SSR vs. client-side behavior
+
+| Scenario | Behavior |
+|----------|----------|
+| **Loader throws during SSR** | Server renders `page-error` with `error` and `status` props; response uses the thrown status code |
+| **Navigation throws on the client** | `cer-layout-view` renders `page-error` with `error` prop only (no HTTP status in the browser) |
+| **No `app/error.ts` defined (SSR)** | Error is logged to the server console; blank 500 response |
+| **No `app/error.ts` defined (client)** | Raw error message rendered in a `<div>` |
+
+> **SPA mode:** There is no server-side error boundary in SPA mode. The `loader` function is never called server-side, so `page-error` is only rendered for client-side navigation errors. To handle loading failures in SPA, catch errors inside `useOnConnected` and render an error state manually.
+
 ---
 
 ## Loader vs. client-side fetching

package/docs/rendering-modes.md

@@ -106,6 +106,8 @@ Any request that:
 
 …is treated as an HTML request and rendered server-side.
 
+Per-route `meta.render` overrides are respected in the dev server: a route with `render: 'spa'` skips SSR and falls through to Vite's own asset handler (returning the SPA shell), exactly as it would in production.
+
 ### Integrating with Express / Fastify / Hono
 
 In production, wire the server bundle's handler into your web framework:
@@ -232,7 +234,7 @@ ISR is a per-route cache layer in the SSR preview server. Pages with `meta.ssg.r
 1. **First request (HIT after fresh render):** Cache miss — render via SSR, store in memory cache with TTL, then serve from the newly-populated cache. `X-Cache: HIT` is set.
 2. **Within TTL (HIT):** Serve directly from cache. `X-Cache: HIT` header is set.
 3. **After TTL expires (STALE):** Serve the stale cached HTML immediately with `X-Cache: STALE`. Kick off a background re-render. When the re-render completes, update the cache.
-4. **While revalidating:** Continue serving stale HTML to new requests.
+4. **While revalidating:** Continue serving stale HTML to new requests. If the background render takes longer than **30 seconds**, the revalidating lock is automatically released so the next request can trigger a fresh attempt.
 
 ### Configuration
 
@@ -260,9 +262,68 @@ export const meta = {
 | `revalidate: 3600` | Product pages, documentation |
 | `revalidate: 86400` | Marketing pages, rarely-changing content |
 
+### Query string handling
+
+ISR caches by **path only** — query strings are stripped from the cache key. Requests to `/blog/post?preview=true` and `/blog/post` share the same cache entry. Use `render: 'server'` (no `revalidate`) for routes where query parameters affect the rendered output.
+
+### Decision order in the preview server
+
+The built-in preview server resolves each request using this precedence:
+
+1. Static asset (`dist/client/**.*`) — served directly
+2. `render: 'spa'` — returns `dist/client/index.html` (SPA shell)
+3. `render: 'static'` — returns `dist/<path>/index.html`; falls back to SSR if file not found
+4. `render: 'server'` — always SSR, bypasses ISR cache
+5. ISR — if `meta.ssg.revalidate` is set, apply stale-while-revalidate caching
+6. Regular SSR
+
+### Compatibility with per-route render modes
+
+ISR is controlled solely by `meta.ssg.revalidate`. The `meta.render` override is independent:
+
+| `meta.render` | `meta.ssg.revalidate` | ISR behavior |
+|---|---|---|
+| _(not set)_ | set | ISR active |
+| `'server'` | set | ISR active — SSR output is cached |
+| `'server'` | not set | Pass-through; no caching |
+| `'static'` | — | Not applicable — `render: 'static'` serves pre-rendered files, not a live SSR render |
+| `'spa'` | — | Not applicable — `render: 'spa'` returns the SPA shell, not an SSR render |
+
+> **Production note:** The `isrHandler` export in the server bundle is a pure ISR-caching wrapper around the SSR handler. It does **not** implement `render: 'spa'` or `render: 'static'` behavior — those are handled by the preview server and the SSG build pipeline. In a custom production Express setup, `render: 'spa'` routes will be SSR-rendered unless you add your own middleware to intercept them before `isrHandler`. For most SSR apps, `render: 'spa'` routes are rare; if you need them in production, serve your SPA shell explicitly for those paths.
+
 ### Availability
 
-ISR is currently active in the built-in **preview server** (`cer-app preview`). When integrating the server bundle into Express / Hono / Fastify in production, implement the same stale-while-revalidate pattern using `route.meta?.ssg?.revalidate` from the exported `routes` array.
+ISR is active in the built-in **preview server** (`cer-app preview`) and in production via the `isrHandler` export from the server bundle.
+
+**Production (Express):**
+```ts
+import express from 'express'
+import sirv from 'sirv'
+import { isrHandler } from './dist/server/server.js'
+
+const app = express()
+app.use(sirv('dist/client', { dev: false }))
+app.use(isrHandler)   // ISR-aware; routes without revalidate pass straight through
+app.listen(3000)
+```
+
+**Production (Hono):**
+```ts
+import { Hono } from 'hono'
+import { isrHandler } from './dist/server/server.js'
+
+const app = new Hono()
+app.use('*', isrHandler)
+```
+
+If you need to build the cache yourself, use the `createIsrHandler` utility:
+
+```ts
+import { createIsrHandler } from '@jasonshimmy/vite-plugin-cer-app/isr'
+import { handler, routes } from './dist/server/server.js'
+
+const isrHandler = createIsrHandler(routes, handler)
+```
 
 ---
 

package/docs/routing.md

@@ -238,6 +238,39 @@ export default {
 
 Set to `false` to explicitly mark a page as having no transition (useful when a catch-all or default would otherwise apply one).
 
+### `meta.render`
+
+**Type:** `'static' | 'server' | 'spa'`
+
+Overrides the global rendering mode for a single route. Useful in mixed apps where most pages share one strategy but a few need different treatment.
+
+| Value | Behavior |
+|---|---|
+| `'server'` | Always renders server-side. In SSG mode the route is **skipped** during the static build — it is never pre-rendered. |
+| `'static'` | Always serves pre-rendered HTML from disk. In the SSR **preview server**, the framework looks for `dist/<path>/index.html`; falls back to SSR if the file is not found. In SSG mode the route is still pre-rendered at build time as normal. |
+| `'spa'`    | Client-only. In SSR mode the server returns the SPA shell (`index.html`) without rendering. In SSG mode the route is skipped. |
+
+```ts
+// app/pages/dashboard.ts — always SSR even in an otherwise SSG app
+export const meta = {
+  render: 'server',
+}
+```
+
+```ts
+// app/pages/profile.ts — client-only (auth wall, no crawlable content)
+export const meta = {
+  render: 'spa',
+}
+```
+
+```ts
+// app/pages/legal/privacy.ts — force static even in SSR mode
+export const meta = {
+  render: 'static',
+}
+```
+
 ---
 
 ## Route sorting

package/e2e/cypress/e2e/error-boundary.cy.ts

@@ -0,0 +1,43 @@
+/**
+ * Tests for the SSR error boundary.
+ *
+ * When a page loader throws, the server renders `page-error` (from app/error.ts)
+ * instead of crashing, and returns the correct HTTP status code.
+ */
+
+const mode = Cypress.env('mode') as 'spa' | 'ssr' | 'ssg'
+
+// SSR loader error boundary — only meaningful when a server render happens
+if (mode === 'ssr') {
+  describe('SSR error boundary — loader throws', () => {
+    it('returns the status code from the thrown error (503)', () => {
+      cy.request({ url: '/loader-error-test', failOnStatusCode: false }).then((response) => {
+        expect(response.status).to.eq(503)
+      })
+    })
+
+    it('renders page-error element in the server response', () => {
+      cy.request({ url: '/loader-error-test', failOnStatusCode: false }).then((response) => {
+        expect(response.body).to.include('page-error')
+      })
+    })
+
+    it('does not render the normal page heading when loader throws', () => {
+      cy.request({ url: '/loader-error-test', failOnStatusCode: false }).then((response) => {
+        expect(response.body).not.to.include('loader-error-heading')
+      })
+    })
+
+    it('shows the error boundary UI in the browser', () => {
+      cy.visit('/loader-error-test', { failOnStatusCode: false })
+      cy.get('[data-cy=error-boundary]').should('exist')
+      cy.get('[data-cy=error-heading]').should('contain', '503')
+      cy.get('[data-cy=error-message]').should('contain', 'Loader intentionally failed')
+    })
+
+    it('exposes a retry button that calls resetError()', () => {
+      cy.visit('/loader-error-test', { failOnStatusCode: false })
+      cy.get('[data-cy=error-retry]').should('exist')
+    })
+  })
+}

package/e2e/cypress/e2e/isr-nested-runtime.cy.ts

@@ -33,11 +33,13 @@ if (mode === 'ssr') {
       })
     })
 
-    // /isr-test uses revalidate: 0 — the TTL is always expired after the first
-    // render, so the second request is always served stale-while-revalidate.
-    it('first request to a revalidate:0 route returns X-Cache: HIT', () => {
+    // /isr-test uses revalidate: 0 — ISR is always engaged. The first request
+    // returns HIT (cold cache) or STALE (warm cache from a previous test run),
+    // but x-cache is always present. Exact HIT/STALE distinction for a cold
+    // cache is covered by unit tests (createIsrHandler).
+    it('revalidate:0 route always has X-Cache header (ISR engaged)', () => {
       cy.request('/isr-test').then((response) => {
-        expect(response.headers['x-cache']).to.equal('HIT')
+        expect(['HIT', 'STALE']).to.include(response.headers['x-cache'])
       })
     })
 

package/e2e/cypress/e2e/per-route-render.cy.ts

@@ -0,0 +1,70 @@
+/**
+ * Tests for per-route render strategy (meta.render).
+ *
+ * render: 'server' — route is always SSR'd, skipped during SSG pre-rendering.
+ * render: 'spa'    — route is served as SPA shell in SSR mode, skipped in SSG.
+ * render: 'static' — serve pre-rendered HTML from disk; fall back to SSR.
+ */
+
+const mode = Cypress.env('mode') as 'spa' | 'ssr' | 'ssg'
+
+// ─── render: 'server' ─────────────────────────────────────────────────────────
+
+describe('render: server — always SSR', () => {
+  it('renders the page in SSR mode', () => {
+    if (mode !== 'ssr') return
+    cy.visit('/render-server-test')
+    cy.get('[data-cy=render-server-heading]').should('contain', 'Render Server Test')
+  })
+
+  it('renders the page in SPA mode (client-side navigation)', () => {
+    if (mode !== 'spa') return
+    cy.visit('/render-server-test')
+    cy.get('[data-cy=render-server-heading]').should('contain', 'Render Server Test')
+  })
+
+  if (mode === 'ssr') {
+    it('pre-renders the page in the initial HTML (SSR)', () => {
+      cy.request('/render-server-test').then((response) => {
+        expect(response.body).to.include('render-server-heading')
+        expect(response.body).to.include('Render Server Test')
+      })
+    })
+  }
+
+  if (mode === 'ssg') {
+    it('route with render:server is not pre-rendered — not found in ssg dist', () => {
+      // The route was skipped during SSG. The static preview falls back to
+      // dist/index.html (SPA shell) rather than a pre-rendered page, so the
+      // server-rendered heading is absent from the raw HTML response.
+      cy.request('/render-server-test').then((response) => {
+        expect(response.body).not.to.include('render-server-heading')
+      })
+    })
+  }
+})
+
+// ─── render: 'spa' ────────────────────────────────────────────────────────────
+
+describe('render: spa — client-only', () => {
+  it('renders the page heading after JS boots', () => {
+    cy.visit('/render-spa-test')
+    cy.get('[data-cy=render-spa-heading]').should('contain', 'Render SPA Test')
+  })
+
+  if (mode === 'ssr') {
+    it('raw HTML response is the SPA shell (no SSR content)', () => {
+      cy.request('/render-spa-test').then((response) => {
+        expect(response.body).not.to.include('render-spa-heading')
+      })
+    })
+  }
+
+  if (mode === 'ssg') {
+    it('route with render:spa is not pre-rendered — not found in ssg dist', () => {
+      cy.request('/render-spa-test').then((response) => {
+        expect(response.body).not.to.include('render-spa-heading')
+      })
+    })
+  }
+})

package/e2e/kitchen-sink/app/error.ts

@@ -1,9 +1,14 @@
 component('page-error', () => {
-  const props = useProps<{ error: string }>({ error: 'An unexpected error occurred.' })
+  const props = useProps<{ error: string; status: string }>({
+    error: 'An unexpected error occurred.',
+    status: '500',
+  })
 
   return html`
     <div data-cy="error-boundary" style="padding:2rem;font-family:sans-serif">
-      <h2 data-cy="error-heading" style="color:#c00;margin-top:0">Something went wrong</h2>
+      <h2 data-cy="error-heading" style="color:#c00;margin-top:0">
+        Error ${props.status}
+      </h2>
       <pre data-cy="error-message" style="background:#fff0f0;border:1px solid #fcc;padding:1rem;border-radius:4px">${props.error}</pre>
       <button data-cy="error-retry" @click="${() => (globalThis as any).resetError?.()}">
         Try again

package/e2e/kitchen-sink/app/pages/loader-error-test.ts

@@ -0,0 +1,13 @@
+component('page-loader-error-test', () => {
+  return html`
+    <div>
+      <h1 data-cy="loader-error-heading">Loader Error Test</h1>
+    </div>
+  `
+})
+
+export async function loader() {
+  const err = new Error('Loader intentionally failed') as Error & { status?: number }
+  err.status = 503
+  throw err
+}

package/e2e/kitchen-sink/app/pages/render-server-test.ts

@@ -0,0 +1,12 @@
+component('page-render-server-test', () => {
+  return html`
+    <div>
+      <h1 data-cy="render-server-heading">Render Server Test</h1>
+      <p>This page always renders server-side.</p>
+    </div>
+  `
+})
+
+export const meta = {
+  render: 'server',
+}

package/e2e/kitchen-sink/app/pages/render-spa-test.ts

@@ -0,0 +1,12 @@
+component('page-render-spa-test', () => {
+  return html`
+    <div>
+      <h1 data-cy="render-spa-heading">Render SPA Test</h1>
+      <p>This page is client-only.</p>
+    </div>
+  `
+})
+
+export const meta = {
+  render: 'spa',
+}