@jasonshimmy/vite-plugin-cer-app 0.20.2 → 0.20.4

package/e2e/kitchen-sink/app/pages/blog/index.ts

@@ -9,6 +9,10 @@ component('page-blog', () => {
 
   const ssrData = usePageData<{ posts: Post[] }>()
   const posts = ref<Post[]>(ssrData?.posts ?? [])
+  // Captured once at element-creation time (during the hydration re-render).
+  // 'ssr' proves usePageData() was non-null — the queueMicrotask timing fix works.
+  // 'client' means __CER_DATA__ was deleted before setup ran (regression).
+  const dataSource = ssrData ? 'ssr' : 'client'
 
   useOnConnected(async () => {
     if (ssrData) return  // already hydrated — skip client fetch
@@ -28,6 +32,7 @@ component('page-blog', () => {
     <div>
       <h1 data-cy="blog-heading">Blog</h1>
       <p>Posts are loaded via a page <strong>loader</strong> (SSR/SSG) or client-side fetch (SPA).</p>
+      <span data-cy="blog-data-source" hidden>${dataSource}</span>
       <ul data-cy="blog-list">
         ${posts.value.map(post => html`
           <li data-cy="blog-item">

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jasonshimmy/vite-plugin-cer-app",
-  "version": "0.20.2",
+  "version": "0.20.4",
   "description": "Nuxt-style meta-framework for @jasonshimmy/custom-elements-runtime",
   "type": "module",
   "keywords": [
@@ -72,13 +72,16 @@
     "e2e:serve:spa": "node dist/cli/index.js preview --root e2e/kitchen-sink --port 4174",
     "e2e:serve:ssr": "node dist/cli/index.js preview --root e2e/kitchen-sink --port 4175 --ssr",
     "e2e:serve:ssg": "node dist/cli/index.js preview --root e2e/kitchen-sink --port 4176",
+    "e2e:serve:dev": "node dist/cli/index.js dev --root e2e/kitchen-sink --port 4177 --mode ssr",
     "e2e:run:spa": "cypress run --config baseUrl=http://localhost:4174 --env mode=spa",
     "e2e:run:ssr": "cypress run --config baseUrl=http://localhost:4175 --env mode=ssr",
     "e2e:run:ssg": "cypress run --config baseUrl=http://localhost:4176 --env mode=ssg",
+    "e2e:run:dev": "cypress run --config baseUrl=http://localhost:4177 --env mode=dev",
     "e2e:spa": "npm run e2e:build:spa && start-server-and-test e2e:serve:spa http://localhost:4174 e2e:run:spa",
     "e2e:ssr": "npm run e2e:build:ssr && start-server-and-test e2e:serve:ssr http://localhost:4175 e2e:run:ssr",
     "e2e:ssg": "npm run e2e:build:ssg && start-server-and-test e2e:serve:ssg http://localhost:4176 e2e:run:ssg",
-    "e2e": "npm run e2e:ssr && npm run e2e:ssg && npm run e2e:spa",
+    "e2e:dev": "npm run e2e:clean && start-server-and-test e2e:serve:dev http://localhost:4177 e2e:run:dev",
+    "e2e": "npm run e2e:ssr && npm run e2e:ssg && npm run e2e:spa && npm run e2e:dev",
     "cypress:open": "cypress open"
   },
   "peerDependencies": {

package/src/__tests__/plugin/build-ssg.test.ts

@@ -137,8 +137,8 @@ describe('buildSSG — path collection', () => {
   it('calls fg when pagesDir exists and no explicit routes', async () => {
     vi.mocked(existsSync).mockReturnValue(true)
     await buildSSG(makeConfig())
-    // fg is called once for page discovery and once by loadContentStore (content scan)
-    expect(fg).toHaveBeenCalledTimes(2)
+    // fg is called once for page discovery
+    expect(fg).toHaveBeenCalledTimes(1)
   })
 
   it('skips Vite dev server when all discovered pages are static', async () => {

package/src/__tests__/plugin/content/loader.test.ts

@@ -79,38 +79,37 @@ describe('resolveContentDir', () => {
 
 describe('loadContentStore — nonexistent dir', () => {
   it('returns empty array when contentDir does not exist', async () => {
-    const items = await loadContentStore('/path/does/not/exist', false, false)
+    const items = await loadContentStore('/path/does/not/exist', false)
     expect(items).toEqual([])
   })
 })
 
-describe('loadContentStore — dev mode (isProduction=false)', () => {
-  it('loads all files including drafts', async () => {
-    const items = await loadContentStore(contentDir, false, false)
+describe('loadContentStore — drafts excluded by default (includeDrafts=false)', () => {
+  it('loads all non-draft files', async () => {
+    const items = await loadContentStore(contentDir, false)
     const paths = items.map((i) => i._path).sort()
-    // Root, about, blog/hello, blog/secret, data/products
+    // Root, about, blog/hello (not secret — it is a draft), data/products
     expect(paths).toContain('/')
     expect(paths).toContain('/about')
     expect(paths).toContain('/blog/hello')
-    expect(paths).toContain('/blog/secret')
+    expect(paths).not.toContain('/blog/secret')
     expect(paths).toContain('/data/products')
   })
 
-  it('includes draft items', async () => {
-    const items = await loadContentStore(contentDir, false, false)
+  it('excludes draft items', async () => {
+    const items = await loadContentStore(contentDir, false)
     const secret = items.find((i) => i._path === '/blog/secret')
-    expect(secret).toBeDefined()
-    expect(secret?.draft).toBe(true)
+    expect(secret).toBeUndefined()
   })
 
   it('strips date prefix from slug', async () => {
-    const items = await loadContentStore(contentDir, false, false)
+    const items = await loadContentStore(contentDir, false)
     expect(items.find((i) => i._path === '/blog/hello')).toBeDefined()
     expect(items.find((i) => i._path === '/blog/2026-04-03-hello')).toBeUndefined()
   })
 
   it('each item has required ContentItem fields', async () => {
-    const items = await loadContentStore(contentDir, false, false)
+    const items = await loadContentStore(contentDir, false)
     for (const item of items) {
       expect(typeof item._path).toBe('string')
       expect(typeof item._file).toBe('string')
@@ -121,7 +120,7 @@ describe('loadContentStore — dev mode (isProduction=false)', () => {
   })
 
   it('normalises date fields to strings (not Date objects)', async () => {
-    const items = await loadContentStore(contentDir, false, false)
+    const items = await loadContentStore(contentDir, false)
     const about = items.find((i) => i._path === '/about')
     expect(about).toBeDefined()
     expect(typeof about?.date).toBe('string')
@@ -129,31 +128,24 @@ describe('loadContentStore — dev mode (isProduction=false)', () => {
   })
 })
 
-describe('loadContentStore — production mode (isProduction=true, isDraft=false)', () => {
-  it('excludes draft items', async () => {
-    const items = await loadContentStore(contentDir, false, true)
+describe('loadContentStore — drafts included (includeDrafts=true)', () => {
+  it('includes draft items when includeDrafts=true', async () => {
+    const items = await loadContentStore(contentDir, true)
     const secret = items.find((i) => i._path === '/blog/secret')
-    expect(secret).toBeUndefined()
+    expect(secret).toBeDefined()
+    expect(secret?.draft).toBe(true)
   })
 
   it('includes non-draft items', async () => {
-    const items = await loadContentStore(contentDir, false, true)
+    const items = await loadContentStore(contentDir, true)
     expect(items.find((i) => i._path === '/blog/hello')).toBeDefined()
     expect(items.find((i) => i._path === '/about')).toBeDefined()
   })
 })
 
-describe('loadContentStore — production mode with drafts enabled (isDraft=true)', () => {
-  it('includes draft items when isDraft=true in production', async () => {
-    const items = await loadContentStore(contentDir, true, true)
-    const secret = items.find((i) => i._path === '/blog/secret')
-    expect(secret).toBeDefined()
-  })
-})
-
 describe('loadContentStore — JSON files', () => {
   it('includes JSON files with _type json', async () => {
-    const items = await loadContentStore(contentDir, false, false)
+    const items = await loadContentStore(contentDir, false)
     const products = items.find((i) => i._path === '/data/products')
     expect(products).toBeDefined()
     expect(products?._type).toBe('json')

package/src/__tests__/plugin/entry-server-template.test.ts

@@ -117,7 +117,10 @@ describe('entry-server-template (ENTRY_SERVER_TEMPLATE content)', () => {
   })
 
   it('merges SSR html with client template when available', () => {
-    expect(src).toContain('_mergeWithClientTemplate(ssrHtml, _clientTemplate)')
+    // Dev mode: per-request global takes precedence over module-level _clientTemplate
+    expect(src).toContain('_resolvedClientTemplate')
+    expect(src).toContain('(globalThis).__CER_CLIENT_TEMPLATE__ ?? _clientTemplate')
+    expect(src).toContain('_mergeWithClientTemplate(ssrHtml, _resolvedClientTemplate)')
   })
 
   it('exports handler as both named and default export', () => {

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

@@ -81,4 +81,49 @@ describe('generatePluginsCode', () => {
     expect(code).toContain('export const plugins')
     expect(code).toContain('export default plugins')
   })
+
+  // ─── .client.ts convention ────────────────────────────────────────────────
+
+  it('includes .client.ts plugins by default (client-side)', async () => {
+    vi.mocked(scanDirectory).mockResolvedValue([
+      `${PLUGINS}/auth.ts`,
+      `${PLUGINS}/cer-material.client.ts`,
+    ])
+    const code = await generatePluginsCode(PLUGINS)
+    expect(code).toContain('cer-material.client.ts')
+    expect(code).toContain('auth.ts')
+  })
+
+  it('excludes .client.ts plugins when serverSafeOnly is true', async () => {
+    vi.mocked(scanDirectory).mockResolvedValue([
+      `${PLUGINS}/auth.ts`,
+      `${PLUGINS}/cer-material.client.ts`,
+    ])
+    const code = await generatePluginsCode(PLUGINS, true)
+    expect(code).not.toContain('cer-material.client.ts')
+    expect(code).toContain('auth.ts')
+  })
+
+  it('returns empty plugins array when all plugins are .client.ts and serverSafeOnly is true', async () => {
+    vi.mocked(scanDirectory).mockResolvedValue([
+      `${PLUGINS}/cer-material.client.ts`,
+    ])
+    const code = await generatePluginsCode(PLUGINS, true)
+    expect(code).toContain('export const plugins = []')
+    expect(code).not.toContain('cer-material.client.ts')
+  })
+
+  it('preserves non-.client.ts plugins in server-safe mode', async () => {
+    vi.mocked(scanDirectory).mockResolvedValue([
+      `${PLUGINS}/01.analytics.ts`,
+      `${PLUGINS}/02.fonts.client.ts`,
+      `${PLUGINS}/03.auth.ts`,
+    ])
+    const code = await generatePluginsCode(PLUGINS, true)
+    expect(code).toContain('01.analytics.ts')
+    expect(code).toContain('03.auth.ts')
+    expect(code).not.toContain('02.fonts.client.ts')
+    // Two plugins remain: _p0 and _p1
+    expect(code).toContain('export const plugins = [_p0, _p1]')
+  })
 })

package/src/__tests__/runtime/app-template.test.ts

@@ -79,12 +79,21 @@ describe('APP_ENTRY_TEMPLATE — meta.hydrate', () => {
     expect(APP_ENTRY_TEMPLATE).toContain('__cerRouter')
   })
 
-  it('_doHydrate clears __CER_DATA__ after navigation', () => {
-    // delete must appear inside _doHydrate, i.e. after _replace and before the closing }
+  it('_doHydrate defers __CER_DATA__ deletion via queueMicrotask after navigation', () => {
+    // The delete must happen inside a queueMicrotask callback so that
+    // cer-layout-view's reactive re-render (queued by the router subscription)
+    // runs BEFORE the data is cleared. A synchronous delete would remove the
+    // data before the scheduled render can read it, causing usePageData() to
+    // always return null on initial SSR/SSG page load.
     const doHydrateStart = APP_ENTRY_TEMPLATE.indexOf('const _doHydrate')
     const doHydrateEnd = APP_ENTRY_TEMPLATE.indexOf('\n    }', doHydrateStart)
     const doHydrateBlock = APP_ENTRY_TEMPLATE.slice(doHydrateStart, doHydrateEnd)
+    expect(doHydrateBlock).toContain('queueMicrotask')
     expect(doHydrateBlock).toContain('delete (globalThis).__CER_DATA__')
+    // The delete must be INSIDE a queueMicrotask callback, not inline
+    const microtaskIdx = doHydrateBlock.indexOf('queueMicrotask')
+    const deleteIdx = doHydrateBlock.indexOf('delete (globalThis).__CER_DATA__')
+    expect(deleteIdx).toBeGreaterThan(microtaskIdx)
   })
 })
 

package/src/cli/commands/dev.ts

@@ -77,9 +77,14 @@ export function devCommand(): Command {
     .option('-p, --port <port>', 'Port to listen on', '3000')
     .option('--host <host>', 'Host to bind to', 'localhost')
     .option('--root <root>', 'Project root directory', process.cwd())
+    .option('--mode <mode>', 'Dev mode: spa, ssr, or ssg (overrides cer.config.ts)')
     .action(async (options) => {
       const root = resolve(options.root)
       const userConfig = await loadCerConfig(root)
+      // CLI --mode flag overrides config file (mirrors build command behaviour)
+      if (options.mode) {
+        userConfig.mode = options.mode as 'spa' | 'ssr' | 'ssg'
+      }
       const port = options.port ? parseInt(options.port, 10) : (userConfig.port ?? 3000)
 
       console.log('[cer-app] Starting dev server...')

package/src/plugin/build-ssg.ts

@@ -5,7 +5,6 @@ import { createServer, type UserConfig } from 'vite'
 import type { ResolvedCerConfig } from './dev-server.js'
 import { buildSSR } from './build-ssr.js'
 import { buildRouteEntry } from './path-utils.js'
-import { CONTENT_STORE_KEY, loadContentStore, resolveContentDir } from './content/index.js'
 import fg from 'fast-glob'
 
 interface SsgManifest {
@@ -250,17 +249,6 @@ export async function buildSSG(
   const paths = await collectSsgPaths(config, viteUserConfig)
   console.log(`[cer-app] Found ${paths.length} path(s) to generate:`, paths)
 
-  // Restore the in-memory content store to the production (no-draft) content.
-  // collectSsgPaths may spin up a Vite dev server (watchMode=true) whose
-  // buildStart hook overwrites globalThis.__CER_CONTENT_STORE__ with drafts
-  // included.  Re-running loadContentStore with isProduction=true corrects this
-  // so that every renderPath call sees only published content.
-  {
-    const contentDir = resolveContentDir(config.root)
-    const productionItems = await loadContentStore(contentDir, false, true)
-    ;(globalThis as Record<string, unknown>)[CONTENT_STORE_KEY] = productionItems
-  }
-
   // Step 3+4: Render and write paths with bounded concurrency.
   // The server bundle uses per-request router instances (initRouter returns the
   // router; the factory passes it to createStreamingSSRHandler as { vnode, router })

package/src/plugin/content/index.ts

@@ -24,14 +24,14 @@ export function resolveContentDir(root: string, contentConfig?: CerContentConfig
 
 /**
  * Loads all content files from `contentDir`, parses them concurrently, and
- * returns the full `ContentItem[]`. Excludes drafts in production unless
- * `drafts: true`. Uses async I/O + `Promise.all` for concurrent disk reads,
- * which is significantly faster than sequential `readFileSync` at 10k+ pages.
+ * returns the full `ContentItem[]`. Excludes drafts unless `includeDrafts: true`
+ * is set in the content config. Uses async I/O + `Promise.all` for concurrent
+ * disk reads, which is significantly faster than sequential `readFileSync` at
+ * 10k+ pages.
  */
 export async function loadContentStore(
   contentDir: string,
   isDraft: boolean,
-  isProduction: boolean,
 ): Promise<ContentItem[]> {
   if (!existsSync(contentDir)) return []
 
@@ -41,8 +41,8 @@ export async function loadContentStore(
     files.map(async (file) => {
       try {
         const item = await parseContentFileAsync(file, contentDir)
-        // Skip drafts in production (unless drafts flag is set)
-        if (isProduction && !isDraft && item.draft === true) return null
+        // Skip drafts unless the user explicitly opted in via drafts: true
+        if (!isDraft && item.draft === true) return null
         return item
       } catch (err) {
         // Warn and skip unparseable / invalid files so one bad file does not
@@ -175,8 +175,7 @@ export function cerContent(
     },
 
     async buildStart() {
-      const isProduction = this.meta.watchMode === false
-      const items = await loadContentStore(_resolvedContentDir, includeDrafts, isProduction)
+      const items = await loadContentStore(_resolvedContentDir, includeDrafts)
       const g = globalThis as Record<string, unknown>
       g[CONTENT_STORE_KEY] = items
     },
@@ -225,9 +224,7 @@ export function cerContent(
 }
 
 async function refreshStore(contentDir: string, includeDrafts: boolean): Promise<void> {
-  // HMR runs in dev (watchMode=true) — use isProduction=false so draft items
-  // remain visible, matching the initial buildStart behaviour in dev mode.
-  const items = await loadContentStore(contentDir, includeDrafts, false)
+  const items = await loadContentStore(contentDir, includeDrafts)
   const g = globalThis as Record<string, unknown>
   g[CONTENT_STORE_KEY] = items
   // Invalidate the dev middleware caches so the next request rebuilds manifest

package/src/plugin/dev-server.ts

@@ -1,5 +1,7 @@
 import type { ViteDevServer } from 'vite'
 import type { IncomingMessage, ServerResponse } from 'node:http'
+import { existsSync, readFileSync } from 'node:fs'
+import { resolve } from 'node:path'
 import { join } from 'pathe'
 import { getGeneratedDir } from './generated-dir.js'
 
@@ -246,7 +248,7 @@ export function configureCerDevServer(
       const acceptsHtml =
         (req.headers['accept'] ?? '').includes('text/html') ||
         url === '/' ||
-        (!url.includes('.') && !url.startsWith('/api/'))
+        (!url.includes('.') && !url.startsWith('/api/') && !url.startsWith('/@'))
 
       if (acceptsHtml) {
         // Check per-route render mode — skip SSR for 'spa' routes.
@@ -257,6 +259,20 @@ export function configureCerDevServer(
           for (const route of pageRoutes) {
             if (_matchDevRoute(route.path, urlPathOnly)) {
               if (route.meta?.render === 'spa') {
+                // In SSR/SSG dev mode, a route with render:'spa' should be served as
+                // the SPA shell (no server rendering). Serve .cer/index.html so the
+                // client bundle boots and handles the route client-side.
+                const _userHtml = resolve(config.root, 'index.html')
+                const _cerHtml = join(getGeneratedDir(config.root), 'index.html')
+                const _spaSrcPath = existsSync(_userHtml) ? _userHtml : _cerHtml
+                if (existsSync(_spaSrcPath)) {
+                  const rawHtml = readFileSync(_spaSrcPath, 'utf-8')
+                  const transformed = await server.transformIndexHtml(url, rawHtml)
+                  res.setHeader('Content-Type', 'text/html; charset=utf-8')
+                  res.statusCode = 200
+                  res.end(transformed)
+                  return
+                }
                 next()
                 return
               }
@@ -276,7 +292,26 @@ export function configureCerDevServer(
             ssrEntry.handler ?? ssrEntry.default?.handler
 
           if (typeof handler === 'function') {
-            await handler(req, res)
+            // In dev mode _clientTemplate inside entry-server.ts is null because
+            // the dist/client/index.html path doesn't exist. Set the global that
+            // the handler reads per-request so the SSR response includes the
+            // Vite client scripts (/@vite/client, HMR, module imports for app.ts).
+            const _userIndexPath = resolve(config.root, 'index.html')
+            const _genIndexPath = join(getGeneratedDir(config.root), 'index.html')
+            const _rawHtml = existsSync(_userIndexPath)
+              ? readFileSync(_userIndexPath, 'utf-8')
+              : existsSync(_genIndexPath)
+                ? readFileSync(_genIndexPath, 'utf-8')
+                : null
+            if (_rawHtml) {
+              ;(globalThis as Record<string, unknown>).__CER_CLIENT_TEMPLATE__ =
+                await server.transformIndexHtml(url, _rawHtml)
+            }
+            try {
+              await handler(req, res)
+            } finally {
+              ;(globalThis as Record<string, unknown>).__CER_CLIENT_TEMPLATE__ = undefined
+            }
             return
           }
 

package/src/plugin/dts-generator.ts

@@ -40,7 +40,13 @@ export function writeTsconfigPaths(root: string, srcDir: string): void {
   }
 
   const content = JSON.stringify(tsconfig, null, 2) + '\n'
-  writeFileSync(join(cerDir, 'tsconfig.json'), content, 'utf-8')
+  const tsconfigPath = join(cerDir, 'tsconfig.json')
+  // Skip write when content is unchanged to avoid triggering Vite's tsconfig
+  // watcher, which would cause an unnecessary server restart on every dev start.
+  try {
+    if (existsSync(tsconfigPath) && readFileSync(tsconfigPath, 'utf-8') === content) return
+  } catch { /* proceed to write */ }
+  writeFileSync(tsconfigPath, content, 'utf-8')
 }
 
 const RUNTIME_GLOBALS = [

package/src/plugin/index.ts

@@ -123,7 +123,7 @@ async function generateVirtualModule(
     case RESOLVED_IDS.composables:
       return generateComposablesCode(config.composablesDir)
     case RESOLVED_IDS.plugins:
-      return generatePluginsCode(config.pluginsDir)
+      return generatePluginsCode(config.pluginsDir, ssr)
     case RESOLVED_IDS.middleware:
       return generateMiddlewareCode(config.middlewareDir)
     case RESOLVED_IDS.serverApi:
@@ -307,9 +307,12 @@ export function cerApp(userConfig: CerAppConfig = {}): Plugin[] {
       if (!allResolved.includes(id)) return null
 
       const ssr = options?.ssr ?? false
-      // For virtual:cer-app-config the SSR and client variants differ (private
-      // defaults are only included in the SSR bundle), so use separate cache keys.
-      const cacheKey = id === RESOLVED_IDS.appConfig ? `${id}:${ssr ? 'ssr' : 'client'}` : id
+      // For virtual:cer-app-config and virtual:cer-plugins the SSR and client
+      // variants differ: app-config includes private defaults in SSR; plugins
+      // excludes .client.ts files in SSR. Use separate cache keys for both.
+      const cacheKey = (id === RESOLVED_IDS.appConfig || id === RESOLVED_IDS.plugins)
+        ? `${id}:${ssr ? 'ssr' : 'client'}`
+        : id
 
       // Return from cache if available
       if (moduleCache.has(cacheKey)) {
@@ -362,6 +365,13 @@ export function cerApp(userConfig: CerAppConfig = {}): Plugin[] {
       if (!existsSync(userHtml)) {
         const cerHtmlPath = join(getGeneratedDir(config.root), 'index.html')
         server.middlewares.use(async (req, res, next) => {
+          // In SSR/SSG mode, HTML requests must fall through to configureCerDevServer
+          // so the SSR handler can run loaders and inject __CER_DATA__ into the response.
+          // Only SPA mode (no server rendering) should serve the raw SPA shell here.
+          if (config.mode === 'ssr' || config.mode === 'ssg') {
+            next()
+            return
+          }
           const url = (req as { url?: string }).url ?? '/'
           const isHtmlRequest =
             url === '/' ||

package/src/plugin/virtual/plugins.ts

@@ -5,8 +5,14 @@ import { sortPluginFiles } from '../path-utils.js'
 /**
  * Generates the virtual:cer-plugins module code.
  * Scans app/plugins/ and produces an ordered array of plugin imports.
+ *
+ * @param pluginsDir - Absolute path to app/plugins/
+ * @param serverSafeOnly - When true, excludes files ending in `.client.ts`.
+ *   These are client-only plugins (CSS injections, browser component libraries,
+ *   etc.) that must not be imported in the SSR server entry. Naming convention:
+ *   `app/plugins/my-plugin.client.ts` → excluded from the server bundle.
  */
-export async function generatePluginsCode(pluginsDir: string): Promise<string> {
+export async function generatePluginsCode(pluginsDir: string, serverSafeOnly = false): Promise<string> {
   if (!existsSync(pluginsDir)) {
     return `// AUTO-GENERATED by @jasonshimmy/vite-plugin-cer-app\nexport const plugins = []\nexport default plugins\n`
   }
@@ -18,10 +24,14 @@ export async function generatePluginsCode(pluginsDir: string): Promise<string> {
   }
 
   const sorted = sortPluginFiles(files)
+  // In server-safe mode, exclude `.client.ts` plugins — they are browser-only
+  // (CSS imports, client component libraries, etc.) and must not be loaded
+  // server-side. Rename the file to `*.client.ts` to mark it as client-only.
+  const filtered = serverSafeOnly ? sorted.filter(f => !f.endsWith('.client.ts')) : sorted
   const lines: string[] = ['// AUTO-GENERATED by @jasonshimmy/vite-plugin-cer-app', '']
 
   const aliases: string[] = []
-  sorted.forEach((file, i) => {
+  filtered.forEach((file, i) => {
     const alias = `_p${i}`
     aliases.push(alias)
     lines.push(`import ${alias} from ${JSON.stringify(file)}`)

package/src/runtime/app-template.ts

@@ -287,9 +287,15 @@ if (typeof window !== 'undefined') {
         // the initial paint — the loading component must not flash over pre-rendered content.
         await _replace(_initPath)
       }
-      // Clear SSR loader data after initial navigation so subsequent client-side
-      // navigations don't accidentally reuse stale server data.
-      delete (globalThis).__CER_DATA__
+      // Defer the data cleanup by one microtask so that cer-layout-view's reactive
+      // re-render — scheduled via queueMicrotask by the reactive system when the
+      // router fires its subscribers during _replace — can still read __CER_DATA__.
+      // Clearing synchronously here would remove the data before the queued render
+      // runs, causing usePageData() to return null on the initial page load.
+      // Subsequent navigations via router.push / router.replace each delete
+      // __CER_DATA__ themselves before calling _loadPageForPath, so this deferred
+      // cleanup only matters for the very first hydration render.
+      queueMicrotask(() => { delete (globalThis).__CER_DATA__ })
     }
 
     if (_hydrateStrategy === 'idle') {

package/src/runtime/composables/use-page-data.ts

@@ -10,13 +10,15 @@
  *    component renders with real data in the initial SSR/SSG HTML.
  *
  * 2. **Client hydration** — the server also serializes the data as
- *    `window.__CER_DATA__` in the page `<head>`. The client entry captures
- *    this into `globalThis.__CER_DATA__` before the app boots. On first
- *    component instantiation `usePageData()` returns that value so the client
+ *    `window.__CER_DATA__` in the page `<head>`. On first component
+ *    instantiation `usePageData()` returns that value so the client
  *    starts with the correct state without an extra network round-trip.
  *
- * The client-side value is cleared after the first read so subsequent
- * client-side navigations don't accidentally reuse stale SSR data.
+ * The client-side value is cleared via `queueMicrotask` in `_doHydrate`
+ * (app-template) after the initial router navigation completes — deferred by
+ * one microtask so the queued reactive re-render can still read the data
+ * before it is removed. Subsequent navigations via `router.push` / `router.replace`
+ * each clear `__CER_DATA__` synchronously before loading the next page's data.
  *
  * @returns The serialized loader result, or `null` if no SSR data is present.
  *

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

@@ -394,8 +394,14 @@ export const handler = async (req, res) => {
       // (loader data script, useHead() tags, JIT styles). No polyfill in body yet.
       const ssrHtml = \`<!DOCTYPE html><html><head>\${headContent}</head><body>\${firstChunk}</body></html>\`
 
-      const merged = _clientTemplate
-        ? _mergeWithClientTemplate(ssrHtml, _clientTemplate)
+      // In dev mode the module-level _clientTemplate is null (only the
+      // production dist/client/index.html path is searched at init time).
+      // The dev server sets (globalThis).__CER_CLIENT_TEMPLATE__ per-request
+      // after running server.transformIndexHtml so the Vite client scripts
+      // (/@vite/client, HMR) are included in every SSR response.
+      const _resolvedClientTemplate = (globalThis).__CER_CLIENT_TEMPLATE__ ?? _clientTemplate
+      const merged = _resolvedClientTemplate
+        ? _mergeWithClientTemplate(ssrHtml, _resolvedClientTemplate)
         : ssrHtml
 
       // Split at </body> so async swap scripts and the DSD polyfill can be streamed