@jasonshimmy/vite-plugin-cer-app 0.20.3 → 0.20.5

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

@@ -55,10 +55,17 @@ describe('APP_ENTRY_TEMPLATE — meta.hydrate', () => {
   })
 
   it('_doHydrate pre-loads the page and calls _replace', () => {
-    expect(APP_ENTRY_TEMPLATE).toContain('await _loadPageForPath(_initPath)')
+    expect(APP_ENTRY_TEMPLATE).toContain('await _loadPageForPath(')
+    expect(APP_ENTRY_TEMPLATE).toContain('_initPath,')
     expect(APP_ENTRY_TEMPLATE).toContain('await _replace(_initPath)')
   })
 
+  it('_doHydrate reuses existing SSR loader data instead of re-running the initial loader', () => {
+    expect(APP_ENTRY_TEMPLATE).toContain("Object.prototype.hasOwnProperty.call(globalThis, '__CER_DATA__')")
+    expect(APP_ENTRY_TEMPLATE).toContain('runLoader: false')
+    expect(APP_ENTRY_TEMPLATE).toContain('initialData: (globalThis).__CER_DATA__')
+  })
+
   it('_doHydrate skips _replace if URL changed during async module load', () => {
     // Guard: only call _replace when the URL hasn't changed during _loadPageForPath.
     // This prevents _doHydrate from overriding a navigation that fired while the
@@ -75,25 +82,25 @@ describe('APP_ENTRY_TEMPLATE — meta.hydrate', () => {
     expect(APP_ENTRY_TEMPLATE).toContain('_currentPagePath === current.value.path')
   })
 
+  it('keeps the SSR slot during the router subscribe initial state push', () => {
+    expect(APP_ENTRY_TEMPLATE).toContain('let _sawInitialRouteState = false')
+    expect(APP_ENTRY_TEMPLATE).toContain('const _isInitialSubscribePush = !_sawInitialRouteState')
+    expect(APP_ENTRY_TEMPLATE).toContain('if (_isInitialSubscribePush) {')
+    expect(APP_ENTRY_TEMPLATE).toContain('return')
+  })
+
   it('exposes router globally as __cerRouter', () => {
     expect(APP_ENTRY_TEMPLATE).toContain('__cerRouter')
   })
 
-  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.
+  it('_doHydrate keeps initial __CER_DATA__ available after hydration', () => {
+    // The initial page data must survive hydration because some browsers may
+    // perform a later upgrade/re-render of the hydrated page component. The
+    // next real client navigation clears __CER_DATA__ before loading new data.
     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)
+    expect(doHydrateBlock).not.toContain('queueMicrotask(() => { delete (globalThis).__CER_DATA__ })')
   })
 })
 
@@ -108,6 +115,11 @@ describe('APP_ENTRY_TEMPLATE — loader sequence', () => {
     expect(APP_ENTRY_TEMPLATE).toContain('(globalThis).__CER_DATA__ = data')
   })
 
+  it('_loadPageForPath derives primitive attrs from reused loader data too', () => {
+    expect(APP_ENTRY_TEMPLATE).toContain('function _toLoaderAttrs(data)')
+    expect(APP_ENTRY_TEMPLATE).toContain('loaderAttrs = { ...loaderAttrs, ..._toLoaderAttrs(loaderData) }')
+  })
+
   it('_loadPageForPath merges loader primitive values into _currentPageAttrs', () => {
     expect(APP_ENTRY_TEMPLATE).toContain('_currentPageAttrs = loaderAttrs')
   })

package/src/__tests__/runtime/entry-client-template.test.ts

@@ -7,6 +7,12 @@ describe('ENTRY_CLIENT_TEMPLATE', () => {
     expect(ENTRY_CLIENT_TEMPLATE.length).toBeGreaterThan(0)
   })
 
+  it('marks the SSR entry URL before app boots so generated middleware can skip hydration replay once', () => {
+    expect(ENTRY_CLIENT_TEMPLATE).toContain('(globalThis).__CER_HYDRATION_ENTRY__')
+    expect(ENTRY_CLIENT_TEMPLATE).toContain('path: window.location.pathname')
+    expect(ENTRY_CLIENT_TEMPLATE).toContain('new URLSearchParams(window.location.search)')
+  })
+
   it('captures __CER_DATA__ from window to globalThis before app boots', () => {
     // SSR loader data must be captured before any module clears window.__CER_DATA__
     expect(ENTRY_CLIENT_TEMPLATE).toContain('window.__CER_DATA__')
@@ -33,7 +39,7 @@ describe('ENTRY_CLIENT_TEMPLATE', () => {
     // Guards are required so the template works in SSR environments where
     // window is not defined.
     const windowChecks = (ENTRY_CLIENT_TEMPLATE.match(/typeof window !== 'undefined'/g) ?? []).length
-    expect(windowChecks).toBeGreaterThanOrEqual(3)
+    expect(windowChecks).toBeGreaterThanOrEqual(4)
   })
 
   it('captures globals before importing app.js', () => {

package/src/__tests__/runtime/use-page-data.test.ts

@@ -1,5 +1,15 @@
-import { describe, it, expect, beforeEach, afterEach } from 'vitest'
+import { describe, it, expect, beforeEach, afterEach, vi } from 'vitest'
 import { AsyncLocalStorage } from 'node:async_hooks'
+
+// --- Module-level mock for @jasonshimmy/custom-elements-runtime ---
+// usePageData imports getCurrentComponentContext from the runtime. We mock the
+// module so unit tests can control which context (if any) is "active".
+let _mockContext: Record<string, unknown> | null = null
+
+vi.mock('@jasonshimmy/custom-elements-runtime', () => ({
+  getCurrentComponentContext: () => _mockContext,
+}))
+
 import { usePageData } from '../../runtime/composables/use-page-data.js'
 
 describe('usePageData', () => {
@@ -119,3 +129,170 @@ describe('usePageData — AsyncLocalStorage (server-side)', () => {
     })
   })
 })
+
+// ─── Component context caching ─────────────────────────────────────────────
+//
+// usePageData() caches the result on the component context (via Object.defineProperty)
+// so that re-renders of the same element instance return the same value even after
+// __CER_DATA__ is deleted by the post-hydration queueMicrotask cleanup.
+//
+// Background: renderFn passed to component() IS the render function — it runs on
+// every re-render, not just once as a setup phase. Without caching, calling
+// usePageData() on the second render after __CER_DATA__ is deleted returns null,
+// which flips `ssrData ? 'ssr' : 'client'` guards and re-triggers client fetches.
+
+describe('usePageData — component context caching', () => {
+  const _PAGE_DATA_KEY = '_cerPageData'
+
+  beforeEach(() => {
+    delete (globalThis as Record<string, unknown>)['__CER_DATA__']
+    delete (globalThis as Record<string, unknown>)['__CER_DATA_STORE__']
+    _mockContext = null
+  })
+
+  afterEach(() => {
+    delete (globalThis as Record<string, unknown>)['__CER_DATA__']
+    _mockContext = null
+  })
+
+  it('returns null and does not cache when context is null (no render in progress)', () => {
+    _mockContext = null
+    ;(globalThis as Record<string, unknown>)['__CER_DATA__'] = { value: 42 }
+    const result = usePageData()
+    expect(result).toEqual({ value: 42 })
+    // No context to cache on — nothing to assert, just no crash
+  })
+
+  it('caches the result on the component context using Object.defineProperty', () => {
+    const ctx: Record<string, unknown> = {}
+    _mockContext = ctx
+    ;(globalThis as Record<string, unknown>)['__CER_DATA__'] = { value: 42 }
+
+    usePageData()
+
+    // Should be defined on ctx via Object.defineProperty (non-enumerable)
+    expect(Object.prototype.hasOwnProperty.call(ctx, _PAGE_DATA_KEY)).toBe(true)
+    expect(ctx[_PAGE_DATA_KEY]).toEqual({ value: 42 })
+  })
+
+  it('cached property is non-enumerable (does not appear in Object.keys)', () => {
+    const ctx: Record<string, unknown> = {}
+    _mockContext = ctx
+    ;(globalThis as Record<string, unknown>)['__CER_DATA__'] = { value: 42 }
+
+    usePageData()
+
+    expect(Object.keys(ctx)).not.toContain(_PAGE_DATA_KEY)
+  })
+
+  it('cached property is non-writable (reactive proxy set-trap cannot overwrite it)', () => {
+    const ctx: Record<string, unknown> = {}
+    _mockContext = ctx
+    ;(globalThis as Record<string, unknown>)['__CER_DATA__'] = { value: 42 }
+
+    usePageData()
+
+    // Attempting to overwrite a writable:false property silently fails in non-strict mode
+    // and throws in strict mode. Verify the value doesn't change.
+    try { ctx[_PAGE_DATA_KEY] = { value: 999 } } catch { /* strict mode */ }
+    expect(ctx[_PAGE_DATA_KEY]).toEqual({ value: 42 })
+  })
+
+  it('returns cached value on second call even after __CER_DATA__ is deleted', () => {
+    const ctx: Record<string, unknown> = {}
+    _mockContext = ctx
+    ;(globalThis as Record<string, unknown>)['__CER_DATA__'] = { value: 42 }
+
+    // First call (simulates initial render while __CER_DATA__ is present)
+    const first = usePageData()
+    expect(first).toEqual({ value: 42 })
+
+    // Simulate post-hydration cleanup: queueMicrotask(() => delete __CER_DATA__)
+    delete (globalThis as Record<string, unknown>)['__CER_DATA__']
+
+    // Second call (simulates re-render after cleanup) — must return cached value
+    const second = usePageData()
+    expect(second).toEqual({ value: 42 })
+  })
+
+  it('caches null result so repeated calls with no data do not re-read the deleted global', () => {
+    const ctx: Record<string, unknown> = {}
+    _mockContext = ctx
+    // No __CER_DATA__ — returns null and caches null
+
+    const first = usePageData()
+    expect(first).toBeNull()
+
+    // Set __CER_DATA__ AFTER first call — second call should return cached null
+    ;(globalThis as Record<string, unknown>)['__CER_DATA__'] = { value: 99 }
+    const second = usePageData()
+    expect(second).toBeNull()
+  })
+
+  it('each component element instance has its own independent cache', () => {
+    const ctxA: Record<string, unknown> = {}
+    const ctxB: Record<string, unknown> = {}
+
+    // First component: has SSR data
+    _mockContext = ctxA
+    ;(globalThis as Record<string, unknown>)['__CER_DATA__'] = { page: 'home' }
+    const resultA = usePageData()
+    expect(resultA).toEqual({ page: 'home' })
+
+    // Simulate navigation: delete home data, set blog data
+    delete (globalThis as Record<string, unknown>)['__CER_DATA__']
+    ;(globalThis as Record<string, unknown>)['__CER_DATA__'] = { page: 'blog' }
+
+    // Second component (different element, different context)
+    _mockContext = ctxB
+    const resultB = usePageData()
+    expect(resultB).toEqual({ page: 'blog' })
+
+    // First component re-rendered — still returns its cached value
+    _mockContext = ctxA
+    delete (globalThis as Record<string, unknown>)['__CER_DATA__']
+    const resultA2 = usePageData()
+    expect(resultA2).toEqual({ page: 'home' }) // cached, not stale blog data
+  })
+
+  it('ALS path takes precedence over context cache (server-side always uses ALS)', () => {
+    const store = new AsyncLocalStorage<unknown>()
+    ;(globalThis as Record<string, unknown>)['__CER_DATA_STORE__'] = store
+
+    const ctx: Record<string, unknown> = {}
+    // Pre-seed a stale client cache on the context
+    Object.defineProperty(ctx, _PAGE_DATA_KEY, { value: { stale: true }, writable: false, configurable: true, enumerable: false })
+    _mockContext = ctx
+
+    const alsData = { fresh: true }
+    store.run(alsData, () => {
+      const result = usePageData()
+      // ALS wins — context cache is not consulted for server-side renders
+      expect(result).toEqual(alsData)
+    })
+
+    delete (globalThis as Record<string, unknown>)['__CER_DATA_STORE__']
+  })
+
+  it('context cache survives across multiple renderFn() invocations (re-render stability)', () => {
+    const ctx: Record<string, unknown> = {}
+    _mockContext = ctx
+    ;(globalThis as Record<string, unknown>)['__CER_DATA__'] = { title: 'My Page' }
+
+    // Simulate 5 re-renders (e.g. reactive state updates)
+    for (let i = 0; i < 5; i++) {
+      const result = usePageData<{ title: string }>()
+      expect(result?.title).toBe('My Page')
+    }
+
+    // Delete __CER_DATA__ (post-hydration cleanup)
+    delete (globalThis as Record<string, unknown>)['__CER_DATA__']
+
+    // 5 more re-renders post-cleanup
+    for (let i = 0; i < 5; i++) {
+      const result = usePageData<{ title: string }>()
+      expect(result?.title).toBe('My Page')
+    }
+  })
+})
+

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

@@ -365,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/routes.ts

@@ -449,6 +449,17 @@ export async function generateRoutesCode(pagesDir: string, i18n?: I18nRouteConfi
       const mwLiteral = JSON.stringify(mw)
       mwChainBody = (
         `    beforeEnter: async (to, from) => {\n` +
+        `      const _hydrationEntry = (globalThis).__CER_HYDRATION_ENTRY__\n` +
+        `      if (\n` +
+        `        _hydrationEntry &&\n` +
+        `        from.path === to.path &&\n` +
+        `        JSON.stringify(from.params ?? {}) === JSON.stringify(to.params ?? {}) &&\n` +
+        `        _hydrationEntry.path === to.path &&\n` +
+        `        JSON.stringify(_hydrationEntry.query ?? {}) === JSON.stringify(to.query ?? {})\n` +
+        `      ) {\n` +
+        `        delete (globalThis).__CER_HYDRATION_ENTRY__\n` +
+        `        return true\n` +
+        `      }\n` +
         `      const { middleware } = await import('virtual:cer-middleware')\n` +
         `      const _names = ${mwLiteral}\n` +
         `      let _idx = 0\n` +

package/src/runtime/app-template.ts

@@ -50,12 +50,20 @@ let _currentPageAttrs = {}
 // back to <router-view> when the current route differs from what was pre-loaded.
 let _currentPagePath = null
 
+function _toLoaderAttrs(data) {
+  if (data === undefined || data === null || typeof data !== 'object') return {}
+  return Object.fromEntries(
+    Object.entries(data).filter(([, v]) => v !== null && v !== undefined && typeof v !== 'object' && typeof v !== 'function')
+  )
+}
+
 // Pre-loads the page module for \`path\`, calls its loader if present, and
 // stores the results so cer-layout-view can pass them as element attributes.
-async function _loadPageForPath(path) {
+async function _loadPageForPath(path, options = {}) {
   try {
     const url = new URL(path, 'http://x')
     const query = Object.fromEntries(url.searchParams)
+    const { runLoader = true, initialData } = options ?? {}
     const matched = router.matchRoute(url.pathname)
     const route = matched?.route
     if (!route?.load) {
@@ -69,17 +77,14 @@ async function _loadPageForPath(path) {
     _currentPagePath = url.pathname
     const params = matched.params ?? {}
     let loaderAttrs = { ...params }
-    if (typeof mod.loader === 'function') {
+    let loaderData = initialData
+    if (typeof mod.loader === 'function' && runLoader) {
       try {
         const data = await mod.loader({ params, query })
         if (data !== undefined && data !== null) {
+          loaderData = data
           // Make loader data available via usePageData() for this navigation.
           ;(globalThis).__CER_DATA__ = data
-          // Merge primitive values as element attributes so useProps() works.
-          const primitives = Object.fromEntries(
-            Object.entries(data).filter(([, v]) => v !== null && v !== undefined && typeof v !== 'object' && typeof v !== 'function')
-          )
-          loaderAttrs = { ...loaderAttrs, ...primitives }
         }
       } catch (err) {
         // Loader errors are surfaced through currentError so the error boundary
@@ -88,6 +93,11 @@ async function _loadPageForPath(path) {
         currentError.value = err instanceof Error ? err.message : String(err)
       }
     }
+    // For the very first hydration pass in SSR/SSG we already have the server's
+    // loader payload in globalThis.__CER_DATA__ / window.__CER_DATA__. Reuse it
+    // instead of re-running the loader on the client, then derive primitive attrs
+    // from that payload so useProps() stays consistent with usePageData().
+    loaderAttrs = { ...loaderAttrs, ..._toLoaderAttrs(loaderData) }
     _currentPageAttrs = loaderAttrs
   } catch {
     _currentPageTag = null
@@ -173,13 +183,22 @@ component('cer-layout-view', () => {
 
   const current = ref(router.getCurrent())
   let unsub
+  let _sawInitialRouteState = false
 
   useOnConnected(() => {
-    // Any router navigation (including the initial _replace in _doHydrate) will
-    // arrive here. If we are still in the hydration gap when a navigation fires
-    // (e.g. a redirect or user interaction before _doHydrate finishes), drop the
-    // slot immediately so the live render takes over.
+    // store.subscribe() synchronously pushes the current route once on
+    // subscription. That initial callback is not a real navigation and must not
+    // tear down the SSR slot before _doHydrate has pre-loaded the page.
+    // Subsequent callbacks are real navigations (including the initial _replace
+    // in _doHydrate), so if they arrive during the hydration gap we drop the
+    // slot immediately and let the live render take over.
     unsub = router.subscribe((s) => {
+      const _isInitialSubscribePush = !_sawInitialRouteState
+      _sawInitialRouteState = true
+      if (_isInitialSubscribePush) {
+        current.value = s
+        return
+      }
       if (_cerHydrating.value) _cerHydrating.value = false
       current.value = s
     })
@@ -270,9 +289,15 @@ if (typeof window !== 'undefined') {
   } else {
     const _doHydrate = async () => {
       const _initPath = window.location.pathname + window.location.search + window.location.hash
+      const _hasInitialLoaderData = Object.prototype.hasOwnProperty.call(globalThis, '__CER_DATA__')
       // Pre-load the page module and run the loader so cer-layout-view renders
       // the page tag directly with loader attrs (enables useProps() on hydration).
-      await _loadPageForPath(_initPath)
+      await _loadPageForPath(
+        _initPath,
+        _hasInitialLoaderData
+          ? { runLoader: false, initialData: (globalThis).__CER_DATA__ }
+          : undefined,
+      )
       // Only activate the initial route if the URL hasn't changed while we were
       // loading the module asynchronously (e.g. a test or plugin navigated away
       // before _doHydrate finished).  Calling _replace with a stale path would
@@ -287,15 +312,17 @@ if (typeof window !== 'undefined') {
         // the initial paint — the loading component must not flash over pre-rendered content.
         await _replace(_initPath)
       }
-      // 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__ })
+      // The client entry marks the already-rendered entry URL so generated
+      // route middleware can skip the browser router's startup replay once.
+      // Clear any leftover flag after the first hydrated route commits so later
+      // navigations always run middleware normally.
+      queueMicrotask(() => { delete (globalThis).__CER_HYDRATION_ENTRY__ })
+      // Keep the initial route's SSR data available after hydration.
+      // Browser engines do not all upgrade and re-render custom elements with
+      // identical timing, so deleting __CER_DATA__ here can cause a later
+      // hydration render to fall back to the client-only path. The next real
+      // router.push/router.replace clears __CER_DATA__ before loading the new
+      // route, so stale page data still does not leak across navigations.
     }
 
     if (_hydrateStrategy === 'idle') {