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

package/dist/types/config.d.ts

@@ -14,6 +14,24 @@ export interface AutoImportsConfig {
     directives?: boolean;
     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;
@@ -22,6 +40,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 declare function defineConfig(config: CerAppConfig): CerAppConfig;
 //# sourceMappingURL=config.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../../src/types/config.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,6CAA6C,CAAA;AAE/E,MAAM,WAAW,SAAS;IACxB,MAAM,CAAC,EAAE,MAAM,GAAG,MAAM,EAAE,CAAA;IAC1B,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB,QAAQ,CAAC,EAAE,OAAO,CAAA;CACnB;AAED,MAAM,WAAW,YAAY;IAC3B,OAAO,CAAC,EAAE,MAAM,EAAE,CAAA;IAClB,cAAc,CAAC,EAAE,OAAO,CAAA;CACzB;AAED,MAAM,WAAW,iBAAiB;IAChC,UAAU,CAAC,EAAE,OAAO,CAAA;IACpB,WAAW,CAAC,EAAE,OAAO,CAAA;IACrB,UAAU,CAAC,EAAE,OAAO,CAAA;IACpB,OAAO,CAAC,EAAE,OAAO,CAAA;CAClB;AAED,MAAM,WAAW,YAAY;IAC3B,IAAI,CAAC,EAAE,KAAK,GAAG,KAAK,GAAG,KAAK,CAAA;IAC5B,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,GAAG,CAAC,EAAE,SAAS,CAAA;IACf,MAAM,CAAC,EAAE,IAAI,CAAC,YAAY,EAAE,MAAM,GAAG,kBAAkB,CAAC,CAAA;IACxD,MAAM,CAAC,EAAE,YAAY,CAAA;IACrB,WAAW,CAAC,EAAE,iBAAiB,CAAA;IAC/B,IAAI,CAAC,EAAE,MAAM,CAAA;CACd;AAED,wBAAgB,YAAY,CAAC,MAAM,EAAE,YAAY,GAAG,YAAY,CAE/D"}
+{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../../src/types/config.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,6CAA6C,CAAA;AAE/E,MAAM,WAAW,SAAS;IACxB,MAAM,CAAC,EAAE,MAAM,GAAG,MAAM,EAAE,CAAA;IAC1B,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB,QAAQ,CAAC,EAAE,OAAO,CAAA;CACnB;AAED,MAAM,WAAW,YAAY;IAC3B,OAAO,CAAC,EAAE,MAAM,EAAE,CAAA;IAClB,cAAc,CAAC,EAAE,OAAO,CAAA;CACzB;AAED,MAAM,WAAW,iBAAiB;IAChC,UAAU,CAAC,EAAE,OAAO,CAAA;IACpB,WAAW,CAAC,EAAE,OAAO,CAAA;IACrB,UAAU,CAAC,EAAE,OAAO,CAAA;IACpB,OAAO,CAAC,EAAE,OAAO,CAAA;CAClB;AAED,MAAM,WAAW,mBAAmB;IAClC,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAA;CACvB;AAED,MAAM,WAAW,aAAa;IAC5B;;;;;;;;;;;OAWG;IACH,MAAM,CAAC,EAAE,mBAAmB,CAAA;CAC7B;AAED,MAAM,WAAW,YAAY;IAC3B,IAAI,CAAC,EAAE,KAAK,GAAG,KAAK,GAAG,KAAK,CAAA;IAC5B,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,GAAG,CAAC,EAAE,SAAS,CAAA;IACf,MAAM,CAAC,EAAE,IAAI,CAAC,YAAY,EAAE,MAAM,GAAG,kBAAkB,CAAC,CAAA;IACxD,MAAM,CAAC,EAAE,YAAY,CAAA;IACrB,WAAW,CAAC,EAAE,iBAAiB,CAAA;IAC/B,IAAI,CAAC,EAAE,MAAM,CAAA;IACb;;;;OAIG;IACH,aAAa,CAAC,EAAE,aAAa,CAAA;CAC9B;AAED,wBAAgB,YAAY,CAAC,MAAM,EAAE,YAAY,GAAG,YAAY,CAE/D"}

package/dist/types/config.js.map

@@ -1 +1 @@
-{"version":3,"file":"config.js","sourceRoot":"","sources":["../../src/types/config.ts"],"names":[],"mappings":"AA8BA,MAAM,UAAU,YAAY,CAAC,MAAoB;IAC/C,OAAO,MAAM,CAAA;AACf,CAAC"}
+{"version":3,"file":"config.js","sourceRoot":"","sources":["../../src/types/config.ts"],"names":[],"mappings":"AAwDA,MAAM,UAAU,YAAY,CAAC,MAAoB;IAC/C,OAAO,MAAM,CAAA;AACf,CAAC"}

package/dist/types/index.d.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/dist/types/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/types/index.ts"],"names":[],"mappings":"AAAA,YAAY,EAAE,YAAY,EAAE,SAAS,EAAE,YAAY,EAAE,iBAAiB,EAAE,MAAM,aAAa,CAAA;AAC3F,OAAO,EAAE,YAAY,EAAE,MAAM,aAAa,CAAA;AAC1C,YAAY,EAAE,eAAe,EAAE,eAAe,EAAE,aAAa,EAAE,QAAQ,EAAE,iBAAiB,EAAE,UAAU,EAAE,MAAM,WAAW,CAAA;AACzH,YAAY,EAAE,UAAU,EAAE,WAAW,EAAE,UAAU,EAAE,UAAU,EAAE,MAAM,UAAU,CAAA;AAC/E,YAAY,EAAE,UAAU,EAAE,SAAS,EAAE,MAAM,aAAa,CAAA;AACxD,YAAY,EAAE,YAAY,EAAE,eAAe,EAAE,gBAAgB,EAAE,MAAM,iBAAiB,CAAA"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/types/index.ts"],"names":[],"mappings":"AAAA,YAAY,EAAE,YAAY,EAAE,SAAS,EAAE,YAAY,EAAE,iBAAiB,EAAE,aAAa,EAAE,mBAAmB,EAAE,MAAM,aAAa,CAAA;AAC/H,OAAO,EAAE,YAAY,EAAE,MAAM,aAAa,CAAA;AAC1C,YAAY,EAAE,eAAe,EAAE,eAAe,EAAE,aAAa,EAAE,QAAQ,EAAE,iBAAiB,EAAE,UAAU,EAAE,MAAM,WAAW,CAAA;AACzH,YAAY,EAAE,UAAU,EAAE,WAAW,EAAE,UAAU,EAAE,UAAU,EAAE,MAAM,UAAU,CAAA;AAC/E,YAAY,EAAE,UAAU,EAAE,SAAS,EAAE,MAAM,aAAa,CAAA;AACxD,YAAY,EAAE,YAAY,EAAE,eAAe,EAAE,gBAAgB,EAAE,MAAM,iBAAiB,CAAA"}

package/dist/types/page.d.ts

@@ -5,12 +5,29 @@ 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 {
     layout?: string;
     middleware?: string[];
     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>> {
     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;CAC7D;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;CACpB;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;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"}

package/docs/composables.md

@@ -141,3 +141,39 @@ import { useInject } from '@jasonshimmy/vite-plugin-cer-app/composables'
 ```
 
 > **Note:** Prefer `useInject` over the raw `inject()` primitive whenever reading plugin-provided values. Raw `inject()` works in SPA mode but returns `undefined` in SSR and SSG because the server renders components without `<cer-layout-view>`'s provide context.
+
+### `useRuntimeConfig()`
+
+Returns the `public` runtime configuration object set in `cer.config.ts` under `runtimeConfig.public`. Available in all rendering modes (SPA, SSR, SSG) and on both server and client.
+
+```ts
+// cer.config.ts
+export default defineConfig({
+  runtimeConfig: {
+    public: {
+      apiBase: process.env.VITE_API_BASE ?? '/api',
+      featureFlags: { darkMode: true },
+    },
+  },
+})
+```
+
+```ts
+// app/pages/index.ts — auto-imported, no import statement needed
+component('page-index', () => {
+  const { public: cfg } = useRuntimeConfig()
+  // cfg.apiBase → '/api'
+
+  return html`<p>API base: ${cfg.apiBase}</p>`
+})
+```
+
+The config is initialized at app boot (both client and server) by calling `initRuntimeConfig(runtimeConfig)` with the value from `virtual:cer-app-config`. You only need `useRuntimeConfig()` to read it.
+
+**Only use `runtimeConfig.public` for values safe to expose to the browser.** Secrets, tokens, and private keys must stay in server-only code (loaders, API handlers, server middleware).
+
+If you need it outside auto-imported directories:
+
+```ts
+import { useRuntimeConfig } from '@jasonshimmy/vite-plugin-cer-app/composables'
+```

package/docs/configuration.md

@@ -198,10 +198,60 @@ When `directives: true`, the following are injected if used and not already impo
 import { when, each, match, anchorBlock } from '@jasonshimmy/custom-elements-runtime/directives'
 ```
 
+The following framework composables are **always** auto-imported when used, regardless of the `runtime` flag — they come from the plugin package:
+
+```ts
+import { useHead, usePageData, useInject, useRuntimeConfig } from '@jasonshimmy/vite-plugin-cer-app/composables'
+```
+
 Set any flag to `false` to opt out and manage imports manually.
 
 ---
 
+## `runtimeConfig` options
+
+Expose typed, centralized public configuration to both server and client code via `useRuntimeConfig()`.
+
+```ts
+export default defineConfig({
+  runtimeConfig: {
+    public: {
+      apiBase: process.env.VITE_API_BASE ?? 'https://api.example.com',
+      appVersion: '1.0.0',
+    },
+  },
+})
+```
+
+### `runtimeConfig.public`
+
+**Type:** `Record<string, unknown>`
+**Default:** `{}`
+
+Values placed here are serialized into `virtual:cer-app-config` at build time and accessible on both server and client via `useRuntimeConfig().public`.
+
+> **Security:** Only put values here that are safe to expose to the browser. Do not put secrets, tokens, or private keys in `public`. Those should be read directly from `process.env` inside server-only code (loaders, server middleware, API handlers).
+
+> **Serialization:** Values must be JSON-serializable (strings, numbers, booleans, plain objects, arrays). Functions, class instances, `undefined`, and circular references are not supported and will be lost or throw during the build.
+
+```ts
+// Any page, layout, component, or composable
+component('page-index', () => {
+  const config = useRuntimeConfig()
+  // config.public.apiBase → 'https://api.example.com'
+
+  return html`<p>API: ${config.public.apiBase}</p>`
+})
+```
+
+**TypeScript:** Import `RuntimePublicConfig` to type your public config if needed:
+
+```ts
+import type { RuntimePublicConfig } from '@jasonshimmy/vite-plugin-cer-app/types'
+```
+
+---
+
 ## Passing config to the Vite plugin directly
 
 When using `vite.config.ts` instead of (or alongside) `cer.config.ts`:
@@ -234,5 +284,7 @@ import type {
   SsgConfig,
   JitCssConfig,
   AutoImportsConfig,
+  RuntimeConfig,
+  RuntimePublicConfig,
 } from '@jasonshimmy/vite-plugin-cer-app/types'
 ```

package/docs/layouts.md

@@ -110,3 +110,85 @@ import layouts from 'virtual:cer-layouts'
 ## Layout switching and DOM preservation
 
 When navigating between pages with different layouts, the framework uses `<cer-keep-alive>` to preserve the layout DOM and avoid unnecessary teardown/remount cycles. This means transitions between pages sharing the same layout are smooth with no layout flash.
+
+---
+
+## 🪆 Nested layouts
+
+Place a `_layout.ts` file inside any page subdirectory to add an inner layout that wraps pages in that subtree. The outer layout (from `meta.layout` or the default) wraps the inner layout, which wraps `<router-view>`.
+
+### File convention
+
+```
+app/
+  layouts/
+    default.ts      # outer layout — full shell (header, footer)
+    minimal.ts      # outer layout — bare minimum
+    sidebar.ts      # inner layout — adds a sidebar panel
+  pages/
+    index.ts        # uses 'default' layout only
+    admin/
+      _layout.ts    # ← inner layout override for all /admin/* pages
+      index.ts      # layout chain: ['default', 'sidebar']
+      users.ts      # layout chain: ['default', 'sidebar']
+      settings.ts   # layout chain: ['default', 'sidebar']
+```
+
+### `_layout.ts` syntax
+
+Export the inner layout name as a default string:
+
+```ts
+// app/pages/admin/_layout.ts
+export default 'sidebar'
+```
+
+The value must match a filename (without extension) in `app/layouts/`.
+
+### Rendered structure
+
+For a page at `app/pages/admin/users.ts` with the above setup:
+
+```html
+<layout-default>
+  <layout-sidebar>
+    <router-view></router-view>
+  </layout-sidebar>
+</layout-default>
+```
+
+Each layout receives the inner content via `<slot>`.
+
+### Overriding the outer layout
+
+If a page in a nested subtree needs a different outer layout, declare it in `meta.layout` as usual:
+
+```ts
+// app/pages/admin/login.ts
+export const meta = {
+  layout: 'minimal',   // overrides outer; chain = ['minimal', 'sidebar']
+}
+```
+
+### Multiple nesting levels
+
+Nesting is resolved recursively. Each ancestor directory that contains a `_layout.ts` contributes one level to the chain:
+
+```
+app/pages/
+  admin/
+    _layout.ts      → 'sidebar'
+    settings/
+      _layout.ts    → 'settings-tabs'
+      profile.ts    # chain: ['default', 'sidebar', 'settings-tabs']
+```
+
+### `meta.layoutChain` in routes
+
+The framework emits the resolved chain as `meta.layoutChain` on the route object at build time. You can read it at runtime:
+
+```ts
+import routes from 'virtual:cer-routes'
+const adminUsers = routes.find(r => r.path === '/admin/users')
+// adminUsers.meta.layoutChain → ['default', 'sidebar']
+```

package/docs/rendering-modes.md

@@ -223,19 +223,60 @@ Any CDN or static host. Upload the entire `dist/` directory (excluding `dist/ser
 
 ---
 
+## ISR — Incremental Static Regeneration
+
+ISR is a per-route cache layer in the SSR preview server. Pages with `meta.ssg.revalidate` set are rendered once, cached, and re-rendered in the background when the TTL expires (stale-while-revalidate).
+
+### How it works
+
+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.
+
+### Configuration
+
+Add `revalidate` (seconds) to `meta.ssg` in any page:
+
+```ts
+// app/pages/blog/[slug].ts
+export const meta = {
+  ssg: {
+    revalidate: 60,   // cache for 60 s; re-render in background after expiry
+    paths: async () => {
+      const posts = await fetchPosts()
+      return posts.map(p => ({ params: { slug: p.slug } }))
+    },
+  },
+}
+```
+
+### Use cases
+
+| TTL | Use case |
+|---|---|
+| `revalidate: 0` | TTL expires immediately — first request is HIT; every subsequent request is STALE with a background re-render |
+| `revalidate: 60` | News articles, dashboards |
+| `revalidate: 3600` | Product pages, documentation |
+| `revalidate: 86400` | Marketing pages, rarely-changing content |
+
+### 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.
+
+---
+
 ## Comparing modes
 
-| Feature | SPA | SSR | SSG |
-|---|---|---|---|
-| Initial HTML | Empty shell | Full HTML | Full HTML |
-| SEO | Poor | Excellent | Excellent |
-| TTFB | Fast | Depends on server | Very fast (CDN) |
-| Server required | No | Yes | No |
-| Data freshness | Real-time | Real-time | Build-time |
-| Dynamic routes | Yes | Yes | Requires `ssg.paths` |
-| API routes | Separate deploy | Same process | Separate deploy |
-| `useHead()` SSR injection | No | Yes | Yes |
-| Streaming | No | No | No |
+| Feature | SPA | SSR | SSG | ISR |
+|---|---|---|---|---|
+| Initial HTML | Empty shell | Full HTML | Full HTML | Full HTML |
+| SEO | Poor | Excellent | Excellent | Excellent |
+| TTFB | Fast | Depends on server | Very fast (CDN) | Very fast after first render |
+| Server required | No | Yes | No | Yes |
+| Data freshness | Real-time | Real-time | Build-time | Configurable TTL |
+| Dynamic routes | Yes | Yes | Requires `ssg.paths` | Yes |
+| API routes | Separate deploy | Same process | Separate deploy | Same process |
 
 ---
 

package/docs/routing.md

@@ -172,6 +172,72 @@ export const meta = {
 }
 ```
 
+### `meta.ssg.revalidate`
+
+**Type:** `number` (seconds)
+
+Enables Incremental Static Regeneration (ISR) for the route. When set, the preview server caches the rendered HTML and serves it until the TTL expires. After expiry, stale HTML is served immediately while a fresh render runs in the background (stale-while-revalidate).
+
+```ts
+// app/pages/blog/[slug].ts
+export const meta = {
+  ssg: {
+    revalidate: 60,  // re-render at most once per minute
+    paths: async () => { /* ... */ },
+  },
+}
+```
+
+See [Rendering Modes — ISR](rendering-modes.md#isr--incremental-static-regeneration) for full details.
+
+### `meta.transition`
+
+**Type:** `string | boolean`
+
+Attaches transition metadata to the route. The value is extracted at build time and emitted as `meta.transition` on the route object — the framework does **not** apply any CSS or DOM changes automatically.
+
+```ts
+// app/pages/about.ts
+export const meta = {
+  transition: 'fade',   // stored as route.meta.transition at runtime
+}
+```
+
+Read the value in your navigation handler or layout to implement transitions yourself:
+
+```ts
+import routes from 'virtual:cer-routes'
+const about = routes.find(r => r.path === '/about')
+// about.meta.transition → 'fade'
+```
+
+Example — apply a CSS class during navigation using a plugin:
+
+```ts
+// app/plugins/transitions.ts
+export default {
+  setup({ router }) {
+    router.beforeEach((to) => {
+      const name = to.meta?.transition
+      if (name) document.documentElement.setAttribute('data-transition', String(name))
+      else document.documentElement.removeAttribute('data-transition')
+    })
+  },
+}
+```
+
+```css
+[data-transition="fade"] cer-layout-view {
+  animation: fadeIn 0.2s ease;
+}
+@keyframes fadeIn {
+  from { opacity: 0 }
+  to   { opacity: 1 }
+}
+```
+
+Set to `false` to explicitly mark a page as having no transition (useful when a catch-all or default would otherwise apply one).
+
 ---
 
 ## Route sorting

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

@@ -0,0 +1,100 @@
+/**
+ * Tests for ISR (Incremental Static Regeneration), nested layouts, and
+ * runtimeConfig — features added alongside Nuxt/Next parity improvements.
+ *
+ * ISR and runtimeConfig tests only run in SSR mode (preview server).
+ * Nested-layout tests run in all modes.
+ */
+
+const mode = Cypress.env('mode') as 'spa' | 'ssr' | 'ssg'
+
+// ─── ISR (preview server only) ────────────────────────────────────────────────
+
+if (mode === 'ssr') {
+  describe('ISR — stale-while-revalidate cache', () => {
+    it('request to a route with revalidate returns X-Cache: HIT', () => {
+      // On first render (cache miss) the server renders, caches, then serves
+      // from cache — so all requests within the TTL return HIT.
+      cy.request('/blog/first-post').then((response) => {
+        expect(response.headers['x-cache']).to.equal('HIT')
+      })
+    })
+
+    it('subsequent requests within TTL also return X-Cache: HIT', () => {
+      cy.request('/blog/first-post')
+      cy.request('/blog/first-post').then((response) => {
+        expect(response.headers['x-cache']).to.equal('HIT')
+      })
+    })
+
+    it('X-Cache header is absent on non-revalidate routes', () => {
+      cy.request('/about').then((response) => {
+        expect(response.headers).not.to.have.property('x-cache')
+      })
+    })
+
+    // /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', () => {
+      cy.request('/isr-test').then((response) => {
+        expect(response.headers['x-cache']).to.equal('HIT')
+      })
+    })
+
+    it('second request to a revalidate:0 route returns X-Cache: STALE', () => {
+      cy.request('/isr-test') // prime the cache
+      cy.request('/isr-test').then((response) => {
+        expect(response.headers['x-cache']).to.equal('STALE')
+      })
+    })
+  })
+}
+
+// ─── Nested layouts ────────────────────────────────────────────────────────────
+
+describe('Nested layouts — admin section', () => {
+  it('renders the admin dashboard page', () => {
+    cy.visit('/admin/dashboard')
+    cy.get('[data-cy=admin-dashboard-heading]').should('contain', 'Admin Dashboard')
+  })
+
+  it('renders the outer default layout (site-header, site-nav)', () => {
+    cy.visit('/admin/dashboard')
+    cy.get('[data-cy=site-header]').should('exist')
+    cy.get('[data-cy=site-nav]').should('exist')
+  })
+
+  it('renders the inner admin layout (admin-sidebar, admin-content)', () => {
+    cy.visit('/admin/dashboard')
+    cy.get('[data-cy=admin-layout]').should('exist')
+    cy.get('[data-cy=admin-sidebar]').should('exist')
+    cy.get('[data-cy=admin-content]').should('exist')
+  })
+
+  it('layout-admin is a DOM child of layout-default (layout chain order)', () => {
+    // Verifies the chain ['default', 'admin'] is rendered outermost-first.
+    // layout-admin must be in the light DOM of layout-default, not the other
+    // way around. A CSS descendant selector proves this without needing to
+    // pierce slot boundaries.
+    cy.visit('/admin/dashboard')
+    cy.get('layout-default layout-admin').should('exist')
+  })
+
+  if (mode !== 'spa') {
+    it('admin layout is pre-rendered in initial HTML (SSR/SSG)', () => {
+      cy.request('/admin/dashboard').then((response) => {
+        expect(response.body).to.include('admin-layout')
+        expect(response.body).to.include('Admin Dashboard')
+      })
+    })
+  }
+})
+
+// ─── runtimeConfig ─────────────────────────────────────────────────────────────
+
+describe('runtimeConfig.public', () => {
+  it('renders the appName from runtimeConfig on the admin dashboard', () => {
+    cy.visit('/admin/dashboard')
+    cy.get('[data-cy=admin-app-name]').should('contain', 'Kitchen Sink')
+  })
+})

package/e2e/kitchen-sink/app/layouts/admin.ts

@@ -0,0 +1,13 @@
+component('layout-admin', () => {
+  return html`
+    <div data-cy="admin-layout">
+      <aside data-cy="admin-sidebar">
+        <p>Admin Panel</p>
+        <a href="/admin/dashboard" data-cy="admin-nav-dashboard">Dashboard</a>
+      </aside>
+      <section data-cy="admin-content">
+        <slot></slot>
+      </section>
+    </div>
+  `
+})

package/e2e/kitchen-sink/app/pages/admin/_layout.ts

@@ -0,0 +1 @@
+export default 'admin'

package/e2e/kitchen-sink/app/pages/admin/dashboard.ts

@@ -0,0 +1,11 @@
+component('page-admin-dashboard', () => {
+  const config = useRuntimeConfig()
+  const appName = config.public?.appName ?? 'Kitchen Sink'
+
+  return html`
+    <div>
+      <h1 data-cy="admin-dashboard-heading">Admin Dashboard</h1>
+      <p data-cy="admin-app-name">App: ${appName}</p>
+    </div>
+  `
+})

package/e2e/kitchen-sink/app/pages/blog/[slug].ts

@@ -46,6 +46,7 @@ export const loader = async ({ params }: { params: { slug: string } }) => {
 
 export const meta = {
   ssg: {
+    revalidate: 60,
     paths: async () => [
       { params: { slug: 'first-post' } },
       { params: { slug: 'second-post' } },

package/e2e/kitchen-sink/app/pages/isr-test.ts

@@ -0,0 +1,17 @@
+component('page-isr-test', () => {
+  return html`
+    <div>
+      <h1 data-cy="isr-test-heading">ISR Test</h1>
+      <p data-cy="isr-test-description">
+        This page uses <code>revalidate: 0</code> so every post-first request
+        is immediately stale.
+      </p>
+    </div>
+  `
+})
+
+export const meta = {
+  ssg: {
+    revalidate: 0,
+  },
+}

package/e2e/kitchen-sink/cer.config.ts

@@ -2,4 +2,9 @@
 export default {
   ssg: { routes: 'auto', concurrency: 2 },
   autoImports: { runtime: true, components: true, composables: true },
+  runtimeConfig: {
+    public: {
+      appName: 'Kitchen Sink',
+    },
+  },
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jasonshimmy/vite-plugin-cer-app",
-  "version": "0.4.6",
+  "version": "0.5.0",
   "description": "Nuxt-style meta-framework for @jasonshimmy/custom-elements-runtime",
   "type": "module",
   "keywords": [