npm - @jasonshimmy/vite-plugin-cer-app - Versions diffs - 0.5.0 → 0.7.0 - Mend

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

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (61) hide show

package/CHANGELOG.md +8 -0
package/IMPLEMENTATION_PLAN.md +2 -2
package/commits.txt +1 -1
package/dist/cli/commands/preview-isr.d.ts +9 -0
package/dist/cli/commands/preview-isr.d.ts.map +1 -1
package/dist/cli/commands/preview-isr.js +16 -0
package/dist/cli/commands/preview-isr.js.map +1 -1
package/dist/cli/commands/preview.d.ts.map +1 -1
package/dist/cli/commands/preview.js +44 -1
package/dist/cli/commands/preview.js.map +1 -1
package/dist/cli/create/templates/spa/package.json.tpl +2 -2
package/dist/cli/create/templates/ssg/package.json.tpl +2 -2
package/dist/cli/create/templates/ssr/package.json.tpl +2 -2
package/dist/plugin/build-ssg.d.ts.map +1 -1
package/dist/plugin/build-ssg.js +17 -3
package/dist/plugin/build-ssg.js.map +1 -1
package/dist/plugin/dev-server.d.ts.map +1 -1
package/dist/plugin/dev-server.js +33 -0
package/dist/plugin/dev-server.js.map +1 -1
package/dist/plugin/virtual/routes.d.ts.map +1 -1
package/dist/plugin/virtual/routes.js +24 -2
package/dist/plugin/virtual/routes.js.map +1 -1
package/dist/runtime/entry-server-template.d.ts +2 -2
package/dist/runtime/entry-server-template.d.ts.map +1 -1
package/dist/runtime/entry-server-template.js +57 -19
package/dist/runtime/entry-server-template.js.map +1 -1
package/dist/runtime/isr-handler.d.ts +40 -0
package/dist/runtime/isr-handler.d.ts.map +1 -0
package/dist/runtime/isr-handler.js +152 -0
package/dist/runtime/isr-handler.js.map +1 -0
package/dist/types/page.d.ts +14 -0
package/dist/types/page.d.ts.map +1 -1
package/docs/data-loading.md +69 -2
package/docs/rendering-modes.md +66 -5
package/docs/routing.md +33 -0
package/e2e/cypress/e2e/error-boundary.cy.ts +43 -0
package/e2e/cypress/e2e/isr-nested-runtime.cy.ts +6 -4
package/e2e/cypress/e2e/per-route-render.cy.ts +70 -0
package/e2e/kitchen-sink/app/error.ts +7 -2
package/e2e/kitchen-sink/app/pages/loader-error-test.ts +13 -0
package/e2e/kitchen-sink/app/pages/render-server-test.ts +12 -0
package/e2e/kitchen-sink/app/pages/render-spa-test.ts +12 -0
package/package.json +7 -3
package/src/__tests__/cli/preview-isr.test.ts +44 -0
package/src/__tests__/plugin/build-ssg-render.test.ts +46 -0
package/src/__tests__/plugin/build-ssg.test.ts +126 -1
package/src/__tests__/plugin/dev-server.test.ts +91 -0
package/src/__tests__/plugin/entry-server-template.test.ts +76 -5
package/src/__tests__/plugin/virtual/routes.test.ts +65 -0
package/src/__tests__/runtime/isr-handler.test.ts +331 -0
package/src/cli/commands/preview-isr.ts +19 -0
package/src/cli/commands/preview.ts +46 -0
package/src/cli/create/templates/spa/package.json.tpl +2 -2
package/src/cli/create/templates/ssg/package.json.tpl +2 -2
package/src/cli/create/templates/ssr/package.json.tpl +2 -2
package/src/plugin/build-ssg.ts +15 -3
package/src/plugin/dev-server.ts +33 -0
package/src/plugin/virtual/routes.ts +24 -2
package/src/runtime/entry-server-template.ts +57 -19
package/src/runtime/isr-handler.ts +183 -0
package/src/types/page.ts +14 -0

package/dist/runtime/entry-server-template.d.ts.map CHANGED Viewed

	@@ -1 +1 @@
1	- {"version":3,"file":"entry-server-template.d.ts","sourceRoot":"","sources":["../../src/runtime/entry-server-template.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,qBAAqB,~~63SA8MjC~~,CAAA"}
1	+ {"version":3,"file":"entry-server-template.d.ts","sourceRoot":"","sources":["../../src/runtime/entry-server-template.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,qBAAqB,6/WAoPjC,CAAA"}

package/dist/runtime/entry-server-template.js CHANGED Viewed

@@ -7,7 +7,7 @@
  *
  * Key features:
  * - AsyncLocalStorage for race-condition-free concurrent renders (SSG concurrency > 1)
- * - Declarative Shadow DOM via renderToStringWithJITCSSDSD (always on)
+ * - Declarative Shadow DOM via renderToStreamWithJITCSSDSD (always on, streamed)
  * - useHead() support via beginHeadCollection / endHeadCollection
  * - DSD polyfill injected at end of <body> after client-template merge
  */
@@ -23,10 +23,12 @@ import plugins from 'virtual:cer-plugins'
 import apiRoutes from 'virtual:cer-server-api'
 import { runtimeConfig } from 'virtual:cer-app-config'
 import { registerBuiltinComponents } from '@jasonshimmy/custom-elements-runtime'
-import { registerEntityMap, renderToStringWithJITCSSDSD, DSD_POLYFILL_SCRIPT } from '@jasonshimmy/custom-elements-runtime/ssr'
+import { registerEntityMap, renderToStreamWithJITCSSDSD, DSD_POLYFILL_SCRIPT } from '@jasonshimmy/custom-elements-runtime/ssr'
 import entitiesJson from '@jasonshimmy/custom-elements-runtime/entities.json'
 import { initRouter } from '@jasonshimmy/custom-elements-runtime/router'
 import { beginHeadCollection, endHeadCollection, serializeHeadTags, initRuntimeConfig } from '@jasonshimmy/vite-plugin-cer-app/composables'
+import { errorTag } from 'virtual:cer-error'
+import { createIsrHandler } from '@jasonshimmy/vite-plugin-cer-app/isr'
 registerBuiltinComponents()
 initRuntimeConfig(runtimeConfig)
@@ -155,8 +157,18 @@ const _prepareRequest = async (req) => {
           head = \`<script>window.__CER_DATA__ = \${JSON.stringify(data)}</script>\`
         }
       }
-    } catch {
-      // Non-fatal: loader errors fall back to an empty page; client will refetch.
+    } catch (err) {
+      // Loader threw — render the error page server-side if app/error.ts exists.
+      const status = (err && typeof err === 'object' && 'status' in err && typeof err.status === 'number')
+        ? err.status : 500
+      const message = (err instanceof Error) ? err.message : String(err)
+      if (!errorTag) {
+        console.error('[cer-app] Loader error (no app/error.ts defined):', err)
+      }
+      const errVnode = errorTag
+        ? { tag: errorTag, props: { attrs: { error: message, status: String(status) } }, children: [] }
+        : { tag: 'div', props: {}, children: [] }
+      return { vnode: errVnode, router, head: undefined, status }
     }
   }
@@ -172,49 +184,75 @@ const _prepareRequest = async (req) => {
     if (tag) vnode = { tag, props: {}, children: [vnode] }
   }
-  return { vnode, router, head }
+  return { vnode, router, head, status: null }
 }
 export const handler = async (req, res) => {
   await _cerDataStore.run(null, async () => {
-    const { vnode, router, head } = await _prepareRequest(req)
+    const { vnode, router, head, status } = await _prepareRequest(req)
+    if (status != null) res.statusCode = status
     // Begin collecting useHead() calls made during the synchronous render pass.
+    // IMPORTANT: the stream's start() function runs synchronously on construction,
+    // so ALL useHead() calls happen before the stream object is returned. We must
+    // call endHeadCollection() immediately — before any await — to avoid a race
+    // window where a concurrent request (e.g. SSG concurrency > 1) resets the
+    // shared globalThis collector while this handler is suspended at an await.
     beginHeadCollection()
     // dsdPolyfill: false — we inject the polyfill manually after merging so it
     // lands at the end of <body>, not inside <cer-layout-view> light DOM where
     // scripts may not execute.
-    const { htmlWithStyles } = renderToStringWithJITCSSDSD(vnode, {
-      dsdPolyfill: false,
-      router,
-    })
+    // The first chunk from the stream is the full synchronous render. Subsequent
+    // chunks are async component swap scripts streamed as they resolve.
+    const stream = renderToStreamWithJITCSSDSD(vnode, { dsdPolyfill: false, router })
-    // Collect and serialize any useHead() calls from the rendered components.
+    // Collect head tags synchronously — all useHead() calls have already fired
+    // inside the stream constructor's start() before it returned.
     const headTags = serializeHeadTags(endHeadCollection())
+    const reader = stream.getReader()
+    // Read the first (synchronous) chunk.
+    const { value: firstChunk = '' } = await reader.read()
     // Merge loader data script + useHead() tags into the document head.
     const headContent = [head, headTags].filter(Boolean).join('\\n')
     // Wrap the rendered body in a full HTML document and inject the head additions
     // (loader data script, useHead() tags, JIT styles). No polyfill in body yet.
-    const ssrHtml = \`<!DOCTYPE html><html><head>\${headContent}</head><body>\${htmlWithStyles}</body></html>\`
+    const ssrHtml = \`<!DOCTYPE html><html><head>\${headContent}</head><body>\${firstChunk}</body></html>\`
-    let finalHtml = _clientTemplate
+    const merged = _clientTemplate
       ? _mergeWithClientTemplate(ssrHtml, _clientTemplate)
       : ssrHtml
-    // Inject DSD polyfill at end of <body>, outside <cer-layout-view>, so the
-    // browser runs it after parsing the declarative shadow roots.
-    finalHtml = finalHtml.includes('</body>')
-      ? finalHtml.replace('</body>', DSD_POLYFILL_SCRIPT + '</body>')
-      : finalHtml + DSD_POLYFILL_SCRIPT
+    // Split at </body> so async swap scripts and the DSD polyfill can be streamed
+    // in before the document is closed.
+    const bodyCloseIdx = merged.lastIndexOf('</body>')
+    const beforeBodyClose = bodyCloseIdx >= 0 ? merged.slice(0, bodyCloseIdx) : merged
+    const fromBodyClose  = bodyCloseIdx >= 0 ? merged.slice(bodyCloseIdx) : ''
     res.setHeader('Content-Type', 'text/html; charset=utf-8')
-    res.end(finalHtml)
+    res.setHeader('Transfer-Encoding', 'chunked')
+    res.write(beforeBodyClose)
+    // Stream async component swap scripts through as-is.
+    while (true) {
+      const { value, done } = await reader.read()
+      if (done) break
+      res.write(value)
+    }
+    // Inject DSD polyfill immediately before </body>, then close the document.
+    res.end(DSD_POLYFILL_SCRIPT + fromBodyClose)
   })
 }
+// ISR-wrapped handler for production integrations (Express, Hono, Fastify).
+// Routes with meta.ssg.revalidate are served stale-while-revalidate.
+export const isrHandler = createIsrHandler(routes, handler)
 export { apiRoutes, plugins, layouts, routes }
 export default handler
 `;

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

	@@ -1 +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;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CA8MpC,CAAA"}
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;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAoPpC,CAAA"}

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

@@ -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 ADDED Viewed

@@ -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 ADDED Viewed

@@ -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 ADDED Viewed

@@ -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 CHANGED Viewed

@@ -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 CHANGED Viewed

	@@ -1 +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"}
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;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 CHANGED Viewed

@@ -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 CHANGED Viewed

@@ -63,9 +63,9 @@ The server renders HTML for each request. Uses Declarative Shadow DOM (DSD) to e
 3. API route handlers run if the URL matches `/api/`
 4. For HTML requests, the router matches the URL to a page
 5. The page's `loader` is called (if present)
-6. The component tree is rendered to HTML with Declarative Shadow DOM via `renderToStringWithJITCSSDSD`
-7. `useHead()` calls are collected and injected before `</head>`
-8. The rendered HTML is merged with the Vite client bundle shell and sent as a full response
+6. The component tree is rendered to HTML with Declarative Shadow DOM via `renderToStreamWithJITCSSDSD`; the synchronous first chunk is flushed immediately, then async component swap scripts follow as they resolve
+7. `useHead()` calls are collected from the synchronous render and injected before `</head>`
+8. The rendered HTML is merged with the Vite client bundle shell and streamed as a chunked response
 ### Build output
@@ -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 CHANGED Viewed

@@ -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 ADDED Viewed

@@ -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')
+    })
+  })
+}