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

package/src/cli/commands/preview-isr.ts

@@ -0,0 +1,139 @@
+/**
+ * ISR (Incremental Static Regeneration) helpers for the preview server.
+ *
+ * Extracted into their own module so they can be unit-tested independently
+ * from the HTTP server wiring in preview.ts.
+ */
+
+import { Readable } from 'node:stream'
+import type { IncomingMessage, ServerResponse } from 'node:http'
+
+// ─── Types ────────────────────────────────────────────────────────────────────
+
+export interface IsrCacheEntry {
+  html: string
+  headers: Record<string, string>
+  statusCode: number
+  builtAt: number
+  revalidate: number
+  /** True while a background re-render is in flight (stale-while-revalidate). */
+  revalidating: boolean
+}
+
+export type IsrCacheStatus = 'HIT' | 'STALE' | 'MISS'
+
+export type SsrHandlerFn = (req: IncomingMessage, res: ServerResponse) => void | Promise<void>
+
+// ─── Route pattern matching ───────────────────────────────────────────────────
+
+/**
+ * Tests whether a route path pattern matches a URL path string.
+ * Normalises trailing slashes and supports `:param` and `:param*` (catch-all)
+ * segments using a simple regex conversion — no external dependencies needed.
+ *
+ * @example
+ * matchRoutePattern('/blog/:slug', '/blog/hello') // true
+ * matchRoutePattern('/:all*', '/any/deep/path')   // true
+ * matchRoutePattern('/about', '/contact')          // false
+ */
+export function matchRoutePattern(pattern: string, urlPath: string): boolean {
+  const norm = (s: string): string => s.replace(/\/+$/, '') || '/'
+  if (norm(pattern) === norm(urlPath)) return true
+  const regexStr =
+    '^' +
+    norm(pattern)
+      .replace(/[.+?^${}()|[\]\\]/g, '\\$&') // escape regex special chars in static segments
+      .replace(/:[^/]+\*/g, '.*')
+      .replace(/:[^/]+/g, '[^/]+') +
+    '$'
+  return new RegExp(regexStr).test(norm(urlPath))
+}
+
+/**
+ * Looks up the `meta.ssg.revalidate` TTL (in seconds) for the route that best
+ * matches `urlPath`. Returns `null` when no route matches or none defines
+ * `revalidate`.
+ */
+export function findRevalidate(
+  routes: Array<{ path: string; meta?: Record<string, unknown> }>,
+  urlPath: string,
+): number | null {
+  for (const route of routes) {
+    if (matchRoutePattern(route.path, urlPath)) {
+      const ssg = route.meta?.ssg as Record<string, unknown> | undefined
+      if (typeof ssg?.revalidate === 'number') return ssg.revalidate
+    }
+  }
+  return null
+}
+
+// ─── Response capture ─────────────────────────────────────────────────────────
+
+/**
+ * Renders a URL path through `handler` using a synthetic IncomingMessage and a
+ * fake ServerResponse that captures the output in memory.
+ *
+ * Returns an `IsrCacheEntry` on success, or `null` if the handler throws.
+ */
+export async function renderForIsr(
+  urlPath: string,
+  handler: SsrHandlerFn,
+  revalidate: number,
+): Promise<IsrCacheEntry | null> {
+  const req = Object.assign(new Readable({ read() {} }), {
+    url: urlPath,
+    method: 'GET',
+    headers: {},
+    socket: null,
+  }) as unknown as IncomingMessage
+
+  return new Promise<IsrCacheEntry | null>((resolve) => {
+    const chunks: Buffer[] = []
+    const headers: Record<string, string> = {}
+    let capturedStatus = 200
+
+    const fakeRes = {
+      get statusCode() { return capturedStatus },
+      set statusCode(v: number) { capturedStatus = v },
+      headersSent: false,
+      setHeader(name: string, value: string | string[]) {
+        headers[name.toLowerCase()] = Array.isArray(value) ? value.join(', ') : String(value)
+        return this
+      },
+      getHeader(name: string) { return headers[name.toLowerCase()] },
+      write(chunk: string | Buffer) {
+        if (chunk != null) chunks.push(Buffer.isBuffer(chunk) ? chunk : Buffer.from(String(chunk)))
+        return true
+      },
+      end(chunk?: string | Buffer) {
+        if (chunk != null) chunks.push(Buffer.isBuffer(chunk) ? chunk : Buffer.from(String(chunk)))
+        const html = Buffer.concat(chunks).toString('utf-8')
+        resolve({ html, headers, statusCode: capturedStatus, builtAt: Date.now(), revalidate, revalidating: false })
+        return this
+      },
+    } as unknown as ServerResponse
+
+    // Use Promise.resolve().then() so synchronous throws in the handler are
+    // also caught by the .catch() handler.
+    Promise.resolve().then(() => handler(req, fakeRes)).catch(() => resolve(null))
+  })
+}
+
+// ─── Cache serving ────────────────────────────────────────────────────────────
+
+/**
+ * Writes a cached ISR entry to the real HTTP response, forwarding all captured
+ * headers and setting the `X-Cache` diagnostic header.
+ */
+export function serveFromIsrCache(
+  entry: IsrCacheEntry,
+  res: ServerResponse,
+  cacheStatus: IsrCacheStatus,
+): void {
+  for (const [name, value] of Object.entries(entry.headers)) {
+    res.setHeader(name, value)
+  }
+  res.setHeader('X-Cache', cacheStatus)
+  res.statusCode = entry.statusCode
+  res.end(entry.html)
+}

package/src/cli/commands/preview.ts

@@ -3,6 +3,15 @@ import { createServer as createHttpServer, type IncomingMessage, type ServerResp
 import { createReadStream, existsSync, statSync } from 'node:fs'
 import { resolve, join, extname } from 'pathe'
 import { pathToFileURL } from 'node:url'
+import {
+  type IsrCacheEntry,
+  type SsrHandlerFn,
+  findRevalidate,
+  renderForIsr,
+  serveFromIsrCache,
+} from './preview-isr.js'
+
+// ─── API route matching ───────────────────────────────────────────────────────
 
 /**
  * Matches an API route pattern (e.g. '/api/items/:id') against a URL path.
@@ -107,7 +116,6 @@ export function previewCommand(): Command {
         console.log('[cer-app] Starting SSR preview server...')
 
         // Load the server bundle
-        type SsrHandlerFn = (req: IncomingMessage, res: ServerResponse) => void | Promise<void>
         let serverMod: {
           handler?: SsrHandlerFn
           default?: SsrHandlerFn
@@ -130,6 +138,15 @@ export function previewCommand(): Command {
         const apiRoutes: Array<{ path: string; handlers: Record<string, unknown> }> =
           Array.isArray(serverMod.apiRoutes) ? serverMod.apiRoutes : []
 
+        // Page routes exported by the server bundle (used for ISR revalidate lookup).
+        const pageRoutes: Array<{ path: string; meta?: Record<string, unknown> }> =
+          Array.isArray((serverMod as { routes?: unknown }).routes)
+            ? (serverMod as { routes: Array<{ path: string; meta?: Record<string, unknown> }> }).routes
+            : []
+
+        // ISR cache: path → cached render entry.
+        const isrCache = new Map<string, IsrCacheEntry>()
+
         const server = createHttpServer(async (req: IncomingMessage, res: ServerResponse) => {
           const url = req.url ?? '/'
           const urlPath = url.split('?')[0]
@@ -183,7 +200,59 @@ export function previewCommand(): Command {
             if (served) return
           }
 
-          // Fall through to SSR handler
+          // ISR: check whether this route has a revalidate TTL.
+          const revalidate = findRevalidate(pageRoutes, urlPath)
+          if (revalidate !== null) {
+            const cached = isrCache.get(urlPath)
+            const now = Date.now()
+
+            if (cached) {
+              const ageSeconds = (now - cached.builtAt) / 1000
+              if (ageSeconds < cached.revalidate) {
+                // Fresh — serve from cache.
+                serveFromIsrCache(cached, res, 'HIT')
+                return
+              }
+              // Stale — serve stale immediately, revalidate in background.
+              if (!cached.revalidating) {
+                cached.revalidating = true
+                serveFromIsrCache(cached, res, 'STALE')
+                const revalidateTimeout = setTimeout(() => {
+                  if (cached) cached.revalidating = false
+                }, 30_000)
+                renderForIsr(urlPath, handler, revalidate).then((entry) => {
+                  clearTimeout(revalidateTimeout)
+                  if (entry) isrCache.set(urlPath, entry)
+                  else if (cached) cached.revalidating = false
+                }).catch(() => {
+                  clearTimeout(revalidateTimeout)
+                  if (cached) cached.revalidating = false
+                })
+                return
+              }
+              // Already revalidating — serve stale without spawning another render.
+              serveFromIsrCache(cached, res, 'STALE')
+              return
+            }
+
+            // Cache miss — render, cache, then serve.
+            try {
+              const entry = await renderForIsr(urlPath, handler, revalidate)
+              if (entry) {
+                isrCache.set(urlPath, entry)
+                serveFromIsrCache(entry, res, 'HIT')
+              } else {
+                await handler(req, res)
+              }
+            } catch (err) {
+              console.error('[cer-app] ISR render error:', err)
+              res.statusCode = 500
+              res.end('Internal Server Error')
+            }
+            return
+          }
+
+          // Non-ISR: fall through to SSR handler directly.
           try {
             await handler(req, res)
           } catch (err) {

package/src/plugin/dev-server.ts

@@ -19,6 +19,7 @@ export interface ResolvedCerConfig {
   router: { base?: string; scrollToFragment?: boolean | object }
   jitCss: { content: string[]; extendedColors: boolean }
   autoImports: { components: boolean; composables: boolean; directives: boolean; runtime: boolean }
+  runtimeConfig: { public: Record<string, unknown> }
 }
 
 /**

package/src/plugin/dts-generator.ts

@@ -76,7 +76,7 @@ const RUNTIME_GLOBALS = [
 
 const DIRECTIVE_GLOBALS = ['when', 'each', 'match', 'anchorBlock']
 
-const FRAMEWORK_GLOBALS = ['useHead', 'usePageData', 'useInject']
+const FRAMEWORK_GLOBALS = ['useHead', 'usePageData', 'useInject', 'useRuntimeConfig']
 
 /**
  * Scans a composables directory and returns a map of export name → file path.
@@ -213,6 +213,13 @@ export async function generateVirtualModuleDts(
   lines.push(`  export const errorTag: string | null`)
   lines.push(`}`)
   lines.push('')
+  lines.push(`declare module 'virtual:cer-app-config' {`)
+  lines.push(`  import type { RuntimePublicConfig } from '@jasonshimmy/vite-plugin-cer-app/types'`)
+  lines.push(`  export const appConfig: { mode: string; router: Record<string, unknown>; ssg: Record<string, unknown> }`)
+  lines.push(`  export const runtimeConfig: { public: RuntimePublicConfig }`)
+  lines.push(`  export default appConfig`)
+  lines.push(`}`)
+  lines.push('')
 
   return lines.join('\n')
 }

package/src/plugin/index.ts

@@ -92,6 +92,9 @@ export function resolveConfig(userConfig: CerAppConfig, root: string = process.c
       directives: userConfig.autoImports?.directives ?? true,
       runtime: userConfig.autoImports?.runtime ?? true,
     },
+    runtimeConfig: {
+      public: userConfig.runtimeConfig?.public ?? {},
+    },
   }
 }
 
@@ -139,7 +142,14 @@ function generateAppConfigModule(config: ResolvedCerConfig): string {
     router: config.router,
     ssg: config.ssg,
   }
-  return `// AUTO-GENERATED by @jasonshimmy/vite-plugin-cer-app\nexport const appConfig = ${JSON.stringify(exportedConfig, null, 2)}\nexport default appConfig\n`
+  const publicConfig = config.runtimeConfig.public
+  return (
+    `// AUTO-GENERATED by @jasonshimmy/vite-plugin-cer-app\n` +
+    `export const appConfig = ${JSON.stringify(exportedConfig, null, 2)}\n` +
+    `export default appConfig\n` +
+    `\n` +
+    `export const runtimeConfig = { public: ${JSON.stringify(publicConfig, null, 2)} }\n`
+  )
 }
 
 /**

package/src/plugin/transforms/auto-import.ts

@@ -11,9 +11,9 @@ const RUNTIME_IMPORTS = `import { component, html, css, ref, computed, watch, wa
 
 const DIRECTIVE_IMPORTS = `import { when, each, match, anchorBlock } from '@jasonshimmy/custom-elements-runtime/directives';`
 
-const FRAMEWORK_IMPORTS = `import { useHead, usePageData, useInject } from '@jasonshimmy/vite-plugin-cer-app/composables';`
+const FRAMEWORK_IMPORTS = `import { useHead, usePageData, useInject, useRuntimeConfig } from '@jasonshimmy/vite-plugin-cer-app/composables';`
 
-const FRAMEWORK_IDENTIFIERS = ['useHead', 'usePageData', 'useInject']
+const FRAMEWORK_IDENTIFIERS = ['useHead', 'usePageData', 'useInject', 'useRuntimeConfig']
 
 const RUNTIME_IDENTIFIERS = [
   'component',

package/src/plugin/virtual/routes.ts

@@ -1,5 +1,5 @@
 import { existsSync } from 'node:fs'
-import { basename } from 'node:path'
+import { basename, join, relative } from 'node:path'
 import { readFile } from 'node:fs/promises'
 import { scanDirectory } from '../scanner.js'
 import { buildRouteEntry, sortRoutes } from '../path-utils.js'
@@ -35,6 +35,77 @@ function extractLayout(source: string): string | null {
   return match ? match[1] : null
 }
 
+/**
+ * Extracts the `ssg.revalidate` number from a page file's source.
+ * Returns null when not declared.
+ *
+ * Matches patterns like:
+ *   revalidate: 60
+ *   revalidate: 3600
+ */
+function extractRevalidate(source: string): number | null {
+  const match = source.match(/revalidate\s*:\s*(\d+)/)
+  return match ? parseInt(match[1], 10) : null
+}
+
+/**
+ * Extracts the `transition` value from a page file's source.
+ * Returns the transition name string, true (boolean), or null if absent.
+ *
+ * Matches patterns like:
+ *   transition: 'fade'
+ *   transition: true
+ */
+function extractTransition(source: string): string | boolean | null {
+  const strMatch = source.match(/transition\s*:\s*['"]([^'"]+)['"]/)
+  if (strMatch) return strMatch[1]
+  const boolMatch = source.match(/transition\s*:\s*(true|false)/)
+  if (boolMatch) return boolMatch[1] === 'true'
+  return null
+}
+
+/**
+ * Resolves the layout chain for a page by walking its ancestor directories
+ * inside pagesDir looking for `_layout.ts` files. Each `_layout.ts` must
+ * export a default string naming a layout in `app/layouts/`.
+ *
+ * Returns null when no nested layouts are found (single-layout path is used).
+ *
+ * Example:
+ *   app/pages/admin/_layout.ts  →  export default 'minimal'
+ *   app/pages/admin/users.ts    →  meta.layout: 'default' (or omitted)
+ *   → layoutChain = ['default', 'minimal']
+ */
+async function resolveLayoutChain(
+  filePath: string,
+  pagesDir: string,
+  outerLayout: string | null,
+): Promise<string[] | null> {
+  const rel = relative(pagesDir, filePath)
+  const parts = rel.split('/').slice(0, -1) // directory segments only
+
+  if (parts.length === 0) return null
+
+  const extras: string[] = []
+  let currentDir = pagesDir
+  for (const part of parts) {
+    currentDir = join(currentDir, part)
+    const layoutFile = join(currentDir, '_layout.ts')
+    if (existsSync(layoutFile)) {
+      try {
+        const src = await readFile(layoutFile, 'utf-8')
+        const match = src.match(/export\s+default\s+['"]([^'"]+)['"]/)
+        if (match) extras.push(match[1])
+      } catch (err) {
+        console.warn(`[cer-app] Could not read layout file "${layoutFile}":`, err)
+      }
+    }
+  }
+
+  if (extras.length === 0) return null
+  return [outerLayout ?? 'default', ...extras]
+}
+
 /**
  * Generates the virtual:cer-routes module code.
  *
@@ -54,7 +125,9 @@ export async function generateRoutesCode(pagesDir: string): Promise<string> {
     return `// AUTO-GENERATED by @jasonshimmy/vite-plugin-cer-app\nconst routes = []\nexport default routes\n`
   }
 
-  const files = await scanDirectory('**/*.ts', pagesDir)
+  const allFiles = await scanDirectory('**/*.ts', pagesDir)
+  // Exclude _layout.ts files — they are directory-level layout config, not pages.
+  const files = allFiles.filter((f) => basename(f) !== '_layout.ts')
 
   if (files.length === 0) {
     return `// AUTO-GENERATED by @jasonshimmy/vite-plugin-cer-app\nconst routes = []\nexport default routes\n`
@@ -81,15 +154,29 @@ export async function generateRoutesCode(pagesDir: string): Promise<string> {
 
   const sorted = sortRoutes(entries)
 
-  // Read each file's source once to extract static metadata (middleware + layout)
-  // without eagerly importing the module.
-  const metaPerEntry: Array<{ middleware: string[]; layout: string | null }> = await Promise.all(
+  // Read each file's source once to extract static metadata without eagerly
+  // importing the module, then resolve any nested layout chains.
+  const metaPerEntry: Array<{
+    middleware: string[]
+    layout: string | null
+    layoutChain: string[] | null
+    revalidate: number | null
+    transition: string | boolean | null
+  }> = await Promise.all(
     sorted.map(async (entry) => {
       try {
         const src = await readFile(entry.filePath, 'utf-8')
-        return { middleware: extractMiddleware(src), layout: extractLayout(src) }
+        const layout = extractLayout(src)
+        const layoutChain = await resolveLayoutChain(entry.filePath, pagesDir, layout)
+        return {
+          middleware: extractMiddleware(src),
+          layout,
+          layoutChain,
+          revalidate: extractRevalidate(src),
+          transition: extractTransition(src),
+        }
       } catch {
-        return { middleware: [], layout: null }
+        return { middleware: [], layout: null, layoutChain: null, revalidate: null, transition: null }
       }
     }),
   )
@@ -98,7 +185,7 @@ export async function generateRoutesCode(pagesDir: string): Promise<string> {
 
   // Build routes array with lazy load() functions for code splitting.
   const routeItems = sorted.map((entry, i) => {
-    const { middleware: mw, layout } = metaPerEntry[i]
+    const { middleware: mw, layout, layoutChain, revalidate, transition } = metaPerEntry[i]
     const filePath = JSON.stringify(entry.filePath)
     const tagName = JSON.stringify(entry.tagName)
     const routePath = JSON.stringify(entry.routePath)
@@ -111,7 +198,17 @@ export async function generateRoutesCode(pagesDir: string): Promise<string> {
 
     // Build meta object — only emit fields that are set
     const metaFields: string[] = []
-    if (layout !== null) metaFields.push(`layout: ${JSON.stringify(layout)}`)
+    if (layoutChain !== null) {
+      metaFields.push(`layoutChain: ${JSON.stringify(layoutChain)}`)
+    } else if (layout !== null) {
+      metaFields.push(`layout: ${JSON.stringify(layout)}`)
+    }
+    if (revalidate !== null) {
+      metaFields.push(`ssg: { revalidate: ${revalidate} }`)
+    }
+    if (transition !== null) {
+      metaFields.push(`transition: ${JSON.stringify(transition)}`)
+    }
     const metaStr = metaFields.length > 0 ? `    meta: { ${metaFields.join(', ')} },\n` : ''
 
     if (mw.length === 0) {

package/src/runtime/app-template.ts

@@ -16,6 +16,7 @@ import layouts from 'virtual:cer-layouts'
 import plugins from 'virtual:cer-plugins'
 import { hasLoading, loadingTag } from 'virtual:cer-loading'
 import { hasError, errorTag } from 'virtual:cer-error'
+import { runtimeConfig } from 'virtual:cer-app-config'
 import {
   component,
   ref,
@@ -26,9 +27,11 @@ import {
 } from '@jasonshimmy/custom-elements-runtime'
 import { initRouter } from '@jasonshimmy/custom-elements-runtime/router'
 import { enableJITCSS } from '@jasonshimmy/custom-elements-runtime/jit-css'
+import { initRuntimeConfig } from '@jasonshimmy/vite-plugin-cer-app/composables'
 
 registerBuiltinComponents()
 enableJITCSS()
+initRuntimeConfig(runtimeConfig)
 
 const router = initRouter({ routes })
 
@@ -112,12 +115,21 @@ component('cer-layout-view', () => {
 
   const matched = router.matchRoute(current.value.path)
   const routeMeta = matched?.route?.meta
-  const layoutName = routeMeta?.layout ?? 'default'
-  const layoutTag = layouts[layoutName]
   const routerView = { tag: 'router-view', props: {}, children: [] }
 
-  if (layoutTag) return { tag: layoutTag, props: {}, children: [routerView] }
-  return routerView
+  // Support nested layout chains: meta.layoutChain = ['default', 'admin']
+  // renders <layout-default><layout-admin><router-view/></layout-admin></layout-default>
+  const chain = routeMeta?.layoutChain
+    ? routeMeta.layoutChain
+    : [routeMeta?.layout ?? 'default']
+
+  // Build nested vnodes from innermost to outermost.
+  let vnode = routerView
+  for (let i = chain.length - 1; i >= 0; i--) {
+    const tag = layouts[chain[i]]
+    if (tag) vnode = { tag, props: {}, children: [vnode] }
+  }
+  return vnode
 })
 
 for (const plugin of plugins) {

package/src/runtime/composables/index.ts

@@ -2,3 +2,4 @@ export { useHead, beginHeadCollection, endHeadCollection, serializeHeadTags } fr
 export type { HeadInput } from './use-head.js'
 export { usePageData } from './use-page-data.js'
 export { useInject } from './use-inject.js'
+export { useRuntimeConfig, initRuntimeConfig } from './use-runtime-config.js'

package/src/runtime/composables/use-runtime-config.ts

@@ -0,0 +1,40 @@
+/**
+ * Returns the public runtime configuration set in `cer.config.ts` under
+ * `runtimeConfig.public`. Available on both server and client.
+ *
+ * Values are baked in at build time from `virtual:cer-app-config`, so only
+ * static/env-var values should be placed here. For truly dynamic config,
+ * use a loader or API route.
+ *
+ * @example
+ * // cer.config.ts
+ * export default defineConfig({
+ *   runtimeConfig: {
+ *     public: { apiBase: process.env.VITE_API_BASE ?? '/api' },
+ *   },
+ * })
+ *
+ * // app/pages/index.ts
+ * const config = useRuntimeConfig()
+ * fetch(config.public.apiBase + '/posts')
+ */
+export function useRuntimeConfig(): { public: Record<string, unknown> } {
+  // Dynamic import resolved at runtime — avoids a static circular dependency
+  // between the composable and the virtual module.
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  const mod = (globalThis as any).__cerRuntimeConfig
+  if (mod) return mod as { public: Record<string, unknown> }
+
+  // Fallback: empty config (e.g. in test environments without the virtual module).
+  return { public: {} }
+}
+
+/**
+ * Called once during app bootstrap to store the resolved runtimeConfig on
+ * globalThis so useRuntimeConfig() can access it synchronously in any context
+ * (component render, composable, server handler).
+ */
+export function initRuntimeConfig(config: { public: Record<string, unknown> }): void {
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  ;(globalThis as any).__cerRuntimeConfig = config
+}

package/src/runtime/entry-server-template.ts

@@ -21,13 +21,15 @@ import routes from 'virtual:cer-routes'
 import layouts from 'virtual:cer-layouts'
 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 entitiesJson from '@jasonshimmy/custom-elements-runtime/entities.json'
 import { initRouter } from '@jasonshimmy/custom-elements-runtime/router'
-import { beginHeadCollection, endHeadCollection, serializeHeadTags } from '@jasonshimmy/vite-plugin-cer-app/composables'
+import { beginHeadCollection, endHeadCollection, serializeHeadTags, initRuntimeConfig } from '@jasonshimmy/vite-plugin-cer-app/composables'
 
 registerBuiltinComponents()
+initRuntimeConfig(runtimeConfig)
 
 // Pre-load the full HTML entity map so named entities like — decode
 // correctly during SSR. Without this the bundled runtime falls back to a
@@ -130,8 +132,6 @@ const _prepareRequest = async (req) => {
   const router = initRouter({ routes, initialUrl: req.url ?? '/' })
   const current = router.getCurrent()
   const { route, params } = router.matchRoute(current.path)
-  const layoutName = route?.meta?.layout ?? 'default'
-  const layoutTag = layouts[layoutName]
 
   // Pre-load the page module so we can embed the component tag directly.
   // This avoids the async router-view (which injects content via script tags
@@ -160,9 +160,17 @@ const _prepareRequest = async (req) => {
     }
   }
 
-  const vnode = layoutTag
-    ? { tag: layoutTag, props: {}, children: [pageVnode] }
-    : pageVnode
+  // Resolve layout chain: nested layouts (meta.layoutChain) or single layout.
+  const chain = route?.meta?.layoutChain
+    ? route.meta.layoutChain
+    : [route?.meta?.layout ?? 'default']
+
+  // Wrap pageVnode in the layout chain from innermost to outermost.
+  let vnode = pageVnode
+  for (let i = chain.length - 1; i >= 0; i--) {
+    const tag = layouts[chain[i]]
+    if (tag) vnode = { tag, props: {}, children: [vnode] }
+  }
 
   return { vnode, router, head }
 }

package/src/types/config.ts

@@ -18,6 +18,26 @@ export interface AutoImportsConfig {
   runtime?: boolean
 }
 
+export interface RuntimePublicConfig {
+  [key: string]: unknown
+}
+
+export interface RuntimeConfig {
+  /**
+   * Public runtime config — available on both server and client via
+   * `useRuntimeConfig().public`. Values are serialized into the virtual module
+   * at build time, so only use static/env-var values here.
+   *
+   * @example
+   * runtimeConfig: {
+   *   public: {
+   *     apiBase: process.env.VITE_API_BASE ?? 'https://api.example.com',
+   *   }
+   * }
+   */
+  public?: RuntimePublicConfig
+}
+
 export interface CerAppConfig {
   mode?: 'spa' | 'ssr' | 'ssg'
   srcDir?: string // defaults to 'app'
@@ -26,6 +46,12 @@ export interface CerAppConfig {
   jitCss?: JitCssConfig
   autoImports?: AutoImportsConfig
   port?: number
+  /**
+   * Runtime configuration accessible via `useRuntimeConfig()`.
+   * Only `public` values are exposed to the client; keep secrets
+   * out of `public`.
+   */
+  runtimeConfig?: RuntimeConfig
 }
 
 export function defineConfig(config: CerAppConfig): CerAppConfig {

package/src/types/index.ts

@@ -1,4 +1,4 @@
-export type { CerAppConfig, SsgConfig, JitCssConfig, AutoImportsConfig } from './config.js'
+export type { CerAppConfig, SsgConfig, JitCssConfig, AutoImportsConfig, RuntimeConfig, RuntimePublicConfig } from './config.js'
 export { defineConfig } from './config.js'
 export type { HydrateStrategy, SsgPathsContext, PageSsgConfig, PageMeta, PageLoaderContext, PageLoader } from './page.js'
 export type { ApiRequest, ApiResponse, ApiHandler, ApiContext } from './api.js'