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

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

@@ -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
  */
@@ -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 { 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 } 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 &mdash; 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 }
 }
@@ -172,38 +180,59 @@ export const handler = async (req, res) => {
     const { vnode, router, head } = await _prepareRequest(req)
 
     // 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)
   })
 }
 

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'

package/src/types/page.ts

@@ -8,6 +8,14 @@ export interface SsgPathsContext {
 
 export interface PageSsgConfig {
   paths?: () => Promise<SsgPathsContext[]> | SsgPathsContext[]
+  /**
+   * Seconds before a cached SSR response is stale and should be re-rendered.
+   * Enables Incremental Static Regeneration (ISR) in the preview server and
+   * any production adapter that reads `meta.ssg.revalidate`.
+   *
+   * @example export const meta = { ssg: { revalidate: 60 } }
+   */
+  revalidate?: number
 }
 
 export interface PageMeta {
@@ -15,6 +23,15 @@ export interface PageMeta {
   middleware?: string[] // named middleware files from app/middleware/
   hydrate?: HydrateStrategy
   ssg?: PageSsgConfig
+  /**
+   * CSS transition name applied to the page during route changes.
+   * Set to `true` to use the default 'page' transition name.
+   * The framework adds/removes `[data-transition="<name>"]` on the root element
+   * so you can target it with CSS animations.
+   *
+   * @example export const meta = { transition: 'fade' }
+   */
+  transition?: string | boolean
 }
 
 export interface PageLoaderContext<P extends Record<string, string> = Record<string, string>> {