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

package/src/__tests__/plugin/resolve-config.test.ts

@@ -140,4 +140,19 @@ describe('resolveConfig', () => {
     const cfg = resolveConfig({}, ROOT)
     expect(cfg.root).toBe(ROOT)
   })
+
+  it('defaults runtimeConfig.public to an empty object', () => {
+    const cfg = resolveConfig({}, ROOT)
+    expect(cfg.runtimeConfig.public).toEqual({})
+  })
+
+  it('passes runtimeConfig.public values through', () => {
+    const cfg = resolveConfig({ runtimeConfig: { public: { apiBase: '/api', version: '1' } } }, ROOT)
+    expect(cfg.runtimeConfig.public).toEqual({ apiBase: '/api', version: '1' })
+  })
+
+  it('preserves runtimeConfig.public when other runtimeConfig fields are omitted', () => {
+    const cfg = resolveConfig({ runtimeConfig: { public: { foo: 42 } } }, ROOT)
+    expect(cfg.runtimeConfig.public.foo).toBe(42)
+  })
 })

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

@@ -233,6 +233,22 @@ describe('autoImportTransform — framework composable injection', () => {
     const result = autoImportTransform(code, '/project/app/loading.ts', opts)!
     expect(result).toContain('usePageData')
   })
+
+  it('injects useRuntimeConfig import when useRuntimeConfig is used', () => {
+    const code = "component('page-dashboard', () => { const cfg = useRuntimeConfig(); return html`<div></div>` })"
+    const result = autoImportTransform(code, '/project/app/pages/dashboard.ts', opts)!
+    expect(result).toContain(`from ${FRAMEWORK_PKG}`)
+    expect(result).toContain('useRuntimeConfig')
+  })
+
+  it('injects useRuntimeConfig alongside other framework composables', () => {
+    const code = "component('page-x', () => { useHead({ title: 'x' }); const cfg = useRuntimeConfig(); return html`<div></div>` })"
+    const result = autoImportTransform(code, '/project/app/pages/x.ts', opts)!
+    expect(result).toContain('useHead')
+    expect(result).toContain('useRuntimeConfig')
+    const count = result.split(`from ${FRAMEWORK_PKG}`).length - 1
+    expect(count).toBe(1)
+  })
 })
 
 // ─── Composable import injection ─────────────────────────────────────────────

package/src/__tests__/plugin/virtual/routes.test.ts

@@ -200,3 +200,198 @@ describe('generateRoutesCode — 404.ts convention', () => {
     expect(idIdx).toBeLessThan(allIdx)
   })
 })
+
+// ─── _layout.ts filtering ─────────────────────────────────────────────────────
+
+describe('generateRoutesCode — _layout.ts filtering', () => {
+  beforeEach(() => {
+    vi.mocked(existsSync).mockReturnValue(true)
+    vi.mocked(scanDirectory).mockResolvedValue([])
+    vi.mocked(readFile).mockResolvedValue('' as never)
+  })
+
+  it('excludes _layout.ts files from the generated routes', async () => {
+    vi.mocked(scanDirectory).mockResolvedValue([
+      `${PAGES}/admin/index.ts`,
+      `${PAGES}/admin/_layout.ts`,
+    ])
+    const code = await generateRoutesCode(PAGES)
+    expect(code).not.toContain('_layout')
+    expect(code).toContain('/admin')
+  })
+
+  it('generates a route for non-underscore files in the same directory', async () => {
+    vi.mocked(scanDirectory).mockResolvedValue([
+      `${PAGES}/admin/users.ts`,
+      `${PAGES}/admin/_layout.ts`,
+    ])
+    const code = await generateRoutesCode(PAGES)
+    expect(code).toContain('/admin/users')
+    expect(code).not.toContain('_layout')
+  })
+})
+
+// ─── meta.revalidate ─────────────────────────────────────────────────────────
+
+describe('generateRoutesCode — meta.ssg.revalidate', () => {
+  beforeEach(() => {
+    vi.mocked(existsSync).mockReturnValue(true)
+    vi.mocked(scanDirectory).mockResolvedValue([])
+    vi.mocked(readFile).mockResolvedValue('' as never)
+  })
+
+  it('emits meta.ssg.revalidate when declared in page source', async () => {
+    vi.mocked(scanDirectory).mockResolvedValue([`${PAGES}/blog.ts`])
+    vi.mocked(readFile).mockResolvedValue(
+      `export const meta = { ssg: { revalidate: 60 } }` as never,
+    )
+    const code = await generateRoutesCode(PAGES)
+    expect(code).toContain('ssg: { revalidate: 60 }')
+  })
+
+  it('emits larger revalidate values correctly', async () => {
+    vi.mocked(scanDirectory).mockResolvedValue([`${PAGES}/products.ts`])
+    vi.mocked(readFile).mockResolvedValue(
+      `export const meta = { ssg: { revalidate: 3600 } }` as never,
+    )
+    const code = await generateRoutesCode(PAGES)
+    expect(code).toContain('ssg: { revalidate: 3600 }')
+  })
+
+  it('omits ssg meta when no revalidate is declared', async () => {
+    vi.mocked(scanDirectory).mockResolvedValue([`${PAGES}/about.ts`])
+    vi.mocked(readFile).mockResolvedValue(
+      `component('page-about', () => html\`<h1>About</h1>\`)` as never,
+    )
+    const code = await generateRoutesCode(PAGES)
+    expect(code).not.toContain('revalidate')
+  })
+
+  it('can combine revalidate with layout in meta', async () => {
+    vi.mocked(scanDirectory).mockResolvedValue([`${PAGES}/blog.ts`])
+    vi.mocked(readFile).mockResolvedValue(
+      `export const meta = { layout: 'minimal', ssg: { revalidate: 120 } }` as never,
+    )
+    const code = await generateRoutesCode(PAGES)
+    expect(code).toContain('layout: "minimal"')
+    expect(code).toContain('ssg: { revalidate: 120 }')
+  })
+})
+
+// ─── meta.transition ─────────────────────────────────────────────────────────
+
+describe('generateRoutesCode — meta.transition', () => {
+  beforeEach(() => {
+    vi.mocked(existsSync).mockReturnValue(true)
+    vi.mocked(scanDirectory).mockResolvedValue([])
+    vi.mocked(readFile).mockResolvedValue('' as never)
+  })
+
+  it('emits meta.transition string when declared', async () => {
+    vi.mocked(scanDirectory).mockResolvedValue([`${PAGES}/about.ts`])
+    vi.mocked(readFile).mockResolvedValue(
+      `export const meta = { transition: 'fade' }` as never,
+    )
+    const code = await generateRoutesCode(PAGES)
+    expect(code).toContain('transition: "fade"')
+  })
+
+  it('emits meta.transition true (boolean) when declared', async () => {
+    vi.mocked(scanDirectory).mockResolvedValue([`${PAGES}/about.ts`])
+    vi.mocked(readFile).mockResolvedValue(
+      `export const meta = { transition: true }` as never,
+    )
+    const code = await generateRoutesCode(PAGES)
+    expect(code).toContain('transition: true')
+  })
+
+  it('omits transition meta when not declared', async () => {
+    vi.mocked(scanDirectory).mockResolvedValue([`${PAGES}/about.ts`])
+    vi.mocked(readFile).mockResolvedValue(
+      `component('page-about', () => html\`<h1>About</h1>\`)` as never,
+    )
+    const code = await generateRoutesCode(PAGES)
+    expect(code).not.toContain('transition')
+  })
+
+  it('emits meta.transition false (boolean) when declared', async () => {
+    vi.mocked(scanDirectory).mockResolvedValue([`${PAGES}/about.ts`])
+    vi.mocked(readFile).mockResolvedValue(
+      `export const meta = { transition: false }` as never,
+    )
+    const code = await generateRoutesCode(PAGES)
+    expect(code).toContain('transition: false')
+  })
+
+  it('can combine transition with middleware', async () => {
+    vi.mocked(scanDirectory).mockResolvedValue([`${PAGES}/dashboard.ts`])
+    vi.mocked(readFile).mockResolvedValue(
+      `export const meta = { transition: 'slide', middleware: ['auth'] }` as never,
+    )
+    const code = await generateRoutesCode(PAGES)
+    expect(code).toContain('transition: "slide"')
+    expect(code).toContain('beforeEnter')
+    expect(code).toContain('"auth"')
+  })
+})
+
+// ─── nested layouts (layoutChain) ────────────────────────────────────────────
+
+describe('generateRoutesCode — layoutChain (nested layouts)', () => {
+  beforeEach(() => {
+    vi.mocked(existsSync).mockReturnValue(true)
+    vi.mocked(scanDirectory).mockResolvedValue([])
+    vi.mocked(readFile).mockResolvedValue('' as never)
+  })
+
+  it('emits meta.layoutChain when a _layout.ts exists in ancestor directory', async () => {
+    vi.mocked(scanDirectory).mockResolvedValue([`${PAGES}/admin/users.ts`])
+    vi.mocked(readFile).mockImplementation(async (path: unknown) => {
+      if (String(path).endsWith('_layout.ts')) return 'export default \'minimal\''
+      return ''
+    })
+    const code = await generateRoutesCode(PAGES)
+    expect(code).toContain('layoutChain:')
+    expect(code).toContain('"default"')
+    expect(code).toContain('"minimal"')
+  })
+
+  it('uses outerLayout from page meta when layoutChain is emitted', async () => {
+    vi.mocked(scanDirectory).mockResolvedValue([`${PAGES}/admin/users.ts`])
+    vi.mocked(readFile).mockImplementation(async (path: unknown) => {
+      const p = String(path)
+      if (p.endsWith('_layout.ts')) return 'export default \'sidebar\''
+      // page source has its own layout
+      return `export const meta = { layout: 'clean' }`
+    })
+    const code = await generateRoutesCode(PAGES)
+    expect(code).toContain('layoutChain:')
+    expect(code).toContain('"clean"')
+    expect(code).toContain('"sidebar"')
+    // Should not emit a plain meta.layout — the chain replaces it
+    expect(code).not.toContain('layout: "clean"')
+  })
+
+  it('omits layoutChain for top-level pages with no _layout.ts', async () => {
+    vi.mocked(existsSync).mockImplementation((p: unknown) => {
+      // Return false for any _layout.ts path so no chain is resolved
+      if (String(p).endsWith('_layout.ts')) return false
+      return true
+    })
+    vi.mocked(scanDirectory).mockResolvedValue([`${PAGES}/about.ts`])
+    vi.mocked(readFile).mockResolvedValue(
+      `export const meta = { layout: 'default' }` as never,
+    )
+    const code = await generateRoutesCode(PAGES)
+    expect(code).not.toContain('layoutChain')
+    expect(code).toContain('layout: "default"')
+  })
+
+  it('omits layoutChain for top-level pages even when existsSync returns true', async () => {
+    // top-level page has no subdirectory segments, so resolveLayoutChain returns null immediately
+    vi.mocked(scanDirectory).mockResolvedValue([`${PAGES}/index.ts`])
+    vi.mocked(readFile).mockResolvedValue('' as never)
+    const code = await generateRoutesCode(PAGES)
+    expect(code).not.toContain('layoutChain')
+  })
+})

package/src/__tests__/runtime/use-runtime-config.test.ts

@@ -0,0 +1,59 @@
+import { describe, it, expect, beforeEach } from 'vitest'
+import { useRuntimeConfig, initRuntimeConfig } from '../../runtime/composables/use-runtime-config.js'
+
+beforeEach(() => {
+  // Reset global state between tests
+  delete (globalThis as Record<string, unknown>).__cerRuntimeConfig
+})
+
+describe('initRuntimeConfig', () => {
+  it('stores the config on globalThis', () => {
+    initRuntimeConfig({ public: { apiBase: '/api' } })
+    expect((globalThis as Record<string, unknown>).__cerRuntimeConfig).toEqual({ public: { apiBase: '/api' } })
+  })
+
+  it('overwrites a previous config', () => {
+    initRuntimeConfig({ public: { apiBase: '/v1' } })
+    initRuntimeConfig({ public: { apiBase: '/v2' } })
+    const stored = (globalThis as Record<string, unknown>).__cerRuntimeConfig as { public: Record<string, unknown> }
+    expect(stored.public.apiBase).toBe('/v2')
+  })
+})
+
+describe('useRuntimeConfig', () => {
+  it('returns empty public config when not initialized', () => {
+    const config = useRuntimeConfig()
+    expect(config.public).toEqual({})
+  })
+
+  it('returns the config set by initRuntimeConfig', () => {
+    initRuntimeConfig({ public: { apiBase: '/api' } })
+    const config = useRuntimeConfig()
+    expect(config.public.apiBase).toBe('/api')
+  })
+
+  it('returns the full public config object', () => {
+    initRuntimeConfig({ public: { apiBase: '/api', version: '1.0', debug: false } })
+    const config = useRuntimeConfig()
+    expect(config.public).toEqual({ apiBase: '/api', version: '1.0', debug: false })
+  })
+
+  it('returns a reference to the stored config (not a copy)', () => {
+    const stored = { public: { apiBase: '/api' } }
+    initRuntimeConfig(stored)
+    const config = useRuntimeConfig()
+    expect(config).toBe(stored)
+  })
+
+  it('reflects updates when initRuntimeConfig is called again', () => {
+    initRuntimeConfig({ public: { key: 'first' } })
+    initRuntimeConfig({ public: { key: 'second' } })
+    expect(useRuntimeConfig().public.key).toBe('second')
+  })
+
+  it('handles empty public config', () => {
+    initRuntimeConfig({ public: {} })
+    const config = useRuntimeConfig()
+    expect(config.public).toEqual({})
+  })
+})

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/cli/create/templates/spa/package.json.tpl

@@ -8,11 +8,11 @@
     "preview": "cer-app preview"
   },
   "dependencies": {
-    "@jasonshimmy/custom-elements-runtime": "^3.2.1"
+    "@jasonshimmy/custom-elements-runtime": "^3.4.0"
   },
   "devDependencies": {
     "vite": "^8.0.1",
-    "@jasonshimmy/vite-plugin-cer-app": "^0.4.2",
+    "@jasonshimmy/vite-plugin-cer-app": "^0.6.0",
     "typescript": "^5.9.3"
   }
 }

package/src/cli/create/templates/ssg/package.json.tpl

@@ -9,11 +9,11 @@
     "preview": "cer-app preview"
   },
   "dependencies": {
-    "@jasonshimmy/custom-elements-runtime": "^3.2.1"
+    "@jasonshimmy/custom-elements-runtime": "^3.4.0"
   },
   "devDependencies": {
     "vite": "^8.0.1",
-    "@jasonshimmy/vite-plugin-cer-app": "^0.4.2",
+    "@jasonshimmy/vite-plugin-cer-app": "^0.6.0",
     "typescript": "^5.9.3"
   }
 }

package/src/cli/create/templates/ssr/package.json.tpl

@@ -8,11 +8,11 @@
     "preview": "cer-app preview --ssr"
   },
   "dependencies": {
-    "@jasonshimmy/custom-elements-runtime": "^3.2.1"
+    "@jasonshimmy/custom-elements-runtime": "^3.4.0"
   },
   "devDependencies": {
     "vite": "^8.0.1",
-    "@jasonshimmy/vite-plugin-cer-app": "^0.4.2",
+    "@jasonshimmy/vite-plugin-cer-app": "^0.6.0",
     "typescript": "^5.9.3"
   }
 }

package/src/plugin/build-ssg.ts

@@ -131,12 +131,14 @@ async function renderPath(
 
   // Mock req/res for the Express-style handler.
   // The handler internally merges with dist/client/index.html, so we just
-  // capture whatever it ends with.
+  // capture whatever it writes/ends with.
   const mockReq = { url: path, headers: {} }
   return new Promise<string>((resolve, reject) => {
+    const chunks: string[] = []
     const mockRes = {
       setHeader: () => {},
-      end: (body: string) => resolve(body),
+      write: (chunk: string) => { chunks.push(chunk) },
+      end: (body?: string) => resolve(chunks.join('') + (body ?? '')),
     }
     ;(handlerFn as (req: unknown, res: unknown) => Promise<void>)(mockReq, mockRes).catch(reject)
   })

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`
+  )
 }
 
 /**