@jasonshimmy/vite-plugin-cer-app 0.1.2 → 0.1.4

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

@@ -227,3 +227,66 @@ describe('autoImportTransform — framework composable injection', () => {
     expect(result).toContain('usePageData')
   })
 })
+
+// ─── Composable import injection ─────────────────────────────────────────────
+
+describe('autoImportTransform — composable import injection', () => {
+  const COMPOSABLES_PKG = `'virtual:cer-composables'`
+
+  it('injects composable import when a registered composable is used', () => {
+    const composableExports = new Map([['useTheme', '/project/app/composables/useTheme.ts']])
+    const code = "component('page-x', () => { const t = useTheme(); return html`<div></div>` })"
+    const result = autoImportTransform(code, '/project/app/pages/x.ts', { srcDir, composableExports })!
+    expect(result).toContain(`from ${COMPOSABLES_PKG}`)
+    expect(result).toContain('useTheme')
+  })
+
+  it('does not inject composable import when composable is not used in file', () => {
+    const composableExports = new Map([['useTheme', '/project/app/composables/useTheme.ts']])
+    const code = "component('page-x', () => html`<h1>Hello</h1>`)"
+    const result = autoImportTransform(code, '/project/app/pages/x.ts', { srcDir, composableExports })
+    expect(result === null || !result!.includes('virtual:cer-composables')).toBe(true)
+  })
+
+  it('does not inject when already imported from virtual:cer-composables (single quotes)', () => {
+    const composableExports = new Map([['useTheme', '/project/app/composables/useTheme.ts']])
+    const code = `import { useTheme } from 'virtual:cer-composables'\ncomponent('x', () => { useTheme(); return html\`\` })`
+    const result = autoImportTransform(code, '/project/app/pages/x.ts', { srcDir, composableExports })
+    const count = (result ?? code).split(`from ${COMPOSABLES_PKG}`).length - 1
+    expect(count).toBe(1)
+  })
+
+  it('does not inject when already imported from virtual:cer-composables (double quotes)', () => {
+    const composableExports = new Map([['useTheme', '/project/app/composables/useTheme.ts']])
+    const code = `import { useTheme } from "virtual:cer-composables"\ncomponent('x', () => { useTheme(); return html\`\` })`
+    const result = autoImportTransform(code, '/project/app/pages/x.ts', { srcDir, composableExports })
+    const count = (result ?? code).split('virtual:cer-composables').length - 1
+    expect(count).toBe(1)
+  })
+
+  it('injects all used composables in a single import statement', () => {
+    const composableExports = new Map([
+      ['useTheme', '/project/app/composables/useTheme.ts'],
+      ['useAuth', '/project/app/composables/useAuth.ts'],
+    ])
+    const code = "component('page-x', () => { useTheme(); useAuth(); return html`<div></div>` })"
+    const result = autoImportTransform(code, '/project/app/pages/x.ts', { srcDir, composableExports })!
+    expect(result).toContain('useTheme')
+    expect(result).toContain('useAuth')
+    const count = result.split(`from ${COMPOSABLES_PKG}`).length - 1
+    expect(count).toBe(1)
+  })
+
+  it('returns null when composableExports is empty and no other identifiers used', () => {
+    const composableExports = new Map<string, string>()
+    const code = 'const x = 1'
+    const result = autoImportTransform(code, '/project/app/pages/x.ts', { srcDir, composableExports })
+    expect(result).toBeNull()
+  })
+
+  it('returns null when composableExports is undefined and no other identifiers used', () => {
+    const code = 'const x = 1'
+    const result = autoImportTransform(code, '/project/app/pages/x.ts', { srcDir })
+    expect(result).toBeNull()
+  })
+})

package/src/cli/create/index.ts

@@ -218,7 +218,7 @@ async function generateInlineTemplate(
   // app/app.ts
   await writeFile(
     join(targetDir, 'app/app.ts'),
-    `import '@jasonshimmy/custom-elements-runtime/css'\nimport 'virtual:cer-components'\nimport routes from 'virtual:cer-routes'\nimport layouts from 'virtual:cer-layouts'\nimport plugins from 'virtual:cer-plugins'\nimport { hasLoading, loadingTag } from 'virtual:cer-loading'\nimport { hasError, errorTag } from 'virtual:cer-error'\nimport { component, ref, useOnConnected, useOnDisconnected, registerBuiltinComponents } from '@jasonshimmy/custom-elements-runtime'\nimport { initRouter } from '@jasonshimmy/custom-elements-runtime/router'\nimport { enableJITCSS } from '@jasonshimmy/custom-elements-runtime/jit-css'\nimport { createDOMJITCSS } from '@jasonshimmy/custom-elements-runtime/dom-jit-css'\n\nregisterBuiltinComponents()\nenableJITCSS()\n\nconst router = initRouter({ routes })\n\nconst isNavigating = ref(false)\nconst currentError = ref(null)\n;(globalThis as any).resetError = () => { currentError.value = null; router.replace(router.getCurrent().path) }\nconst _push = router.push.bind(router)\nconst _replace = router.replace.bind(router)\nrouter.push = async (path) => { isNavigating.value = true; currentError.value = null; try { await _push(path) } catch (err) { currentError.value = err instanceof Error ? err.message : String(err) } finally { isNavigating.value = false } }\nrouter.replace = async (path) => { isNavigating.value = true; currentError.value = null; try { await _replace(path) } catch (err) { currentError.value = err instanceof Error ? err.message : String(err) } finally { isNavigating.value = false } }\n\ncomponent('cer-layout-view', () => {\n  const current = ref(router.getCurrent())\n  let unsub: (() => void) | undefined\n  useOnConnected(() => { unsub = router.subscribe((s: typeof current.value) => { current.value = s }) })\n  useOnDisconnected(() => { unsub?.(); unsub = undefined })\n  if (currentError.value !== null) {\n    if (hasError && errorTag) return { tag: errorTag, props: { attrs: { error: String(currentError.value) } }, children: [] }\n    return { tag: 'div', props: { attrs: { style: 'padding:2rem;font-family:monospace' } }, children: [String(currentError.value)] }\n  }\n  if (isNavigating.value && hasLoading && loadingTag) return { tag: loadingTag, props: {}, children: [] }\n  const matched = router.matchRoute(current.value.path)\n  const layoutName = (matched?.route as any)?.meta?.layout ?? 'default'\n  const layoutTag = (layouts as Record<string, string>)[layoutName]\n  const routerView = { tag: 'router-view', props: {}, children: [] }\n  return layoutTag ? { tag: layoutTag, props: {}, children: [routerView] } : routerView\n})\n\nfor (const plugin of plugins ?? []) {\n  if (plugin && typeof plugin.setup === 'function') {\n    await plugin.setup({ router, provide: (key, value) => { (globalThis as any)[key] = value }, config: {} })\n  }\n}\n\nif (typeof window !== 'undefined') {\n  await router.replace(window.location.pathname + window.location.search + window.location.hash)\n  createDOMJITCSS().mount()\n}\n\nexport { router }\n`,
+    `import '@jasonshimmy/custom-elements-runtime/css'\nimport 'virtual:cer-components'\nimport routes from 'virtual:cer-routes'\nimport layouts from 'virtual:cer-layouts'\nimport plugins from 'virtual:cer-plugins'\nimport { hasLoading, loadingTag } from 'virtual:cer-loading'\nimport { hasError, errorTag } from 'virtual:cer-error'\nimport { component, ref, provide, useOnConnected, useOnDisconnected, registerBuiltinComponents } from '@jasonshimmy/custom-elements-runtime'\nimport { initRouter } from '@jasonshimmy/custom-elements-runtime/router'\nimport { enableJITCSS } from '@jasonshimmy/custom-elements-runtime/jit-css'\nimport { createDOMJITCSS } from '@jasonshimmy/custom-elements-runtime/dom-jit-css'\n\nregisterBuiltinComponents()\nenableJITCSS()\n\nconst router = initRouter({ routes })\n\nconst isNavigating = ref(false)\nconst currentError = ref(null)\n;(globalThis as any).resetError = () => { currentError.value = null; router.replace(router.getCurrent().path) }\nconst _push = router.push.bind(router)\nconst _replace = router.replace.bind(router)\nrouter.push = async (path) => { isNavigating.value = true; currentError.value = null; try { await _push(path) } catch (err) { currentError.value = err instanceof Error ? err.message : String(err) } finally { isNavigating.value = false } }\nrouter.replace = async (path) => { isNavigating.value = true; currentError.value = null; try { await _replace(path) } catch (err) { currentError.value = err instanceof Error ? err.message : String(err) } finally { isNavigating.value = false } }\n\nconst _pluginProvides = new Map()\n;(globalThis as any).__cerPluginProvides = _pluginProvides\n\ncomponent('cer-layout-view', () => {\n  for (const [key, value] of _pluginProvides) { provide(key, value) }\n  const current = ref(router.getCurrent())\n  let unsub: (() => void) | undefined\n  useOnConnected(() => { unsub = router.subscribe((s: typeof current.value) => { current.value = s }) })\n  useOnDisconnected(() => { unsub?.(); unsub = undefined })\n  if (currentError.value !== null) {\n    if (hasError && errorTag) return { tag: errorTag, props: { attrs: { error: String(currentError.value) } }, children: [] }\n    return { tag: 'div', props: { attrs: { style: 'padding:2rem;font-family:monospace' } }, children: [String(currentError.value)] }\n  }\n  if (isNavigating.value && hasLoading && loadingTag) return { tag: loadingTag, props: {}, children: [] }\n  const matched = router.matchRoute(current.value.path)\n  const layoutName = (matched?.route as any)?.meta?.layout ?? 'default'\n  const layoutTag = (layouts as Record<string, string>)[layoutName]\n  const routerView = { tag: 'router-view', props: {}, children: [] }\n  return layoutTag ? { tag: layoutTag, props: {}, children: [routerView] } : routerView\n})\n\nfor (const plugin of plugins ?? []) {\n  if (plugin && typeof plugin.setup === 'function') {\n    await plugin.setup({ router, provide: (key: string, value: unknown) => { _pluginProvides.set(key, value) }, config: {} })\n  }\n}\n\nif (typeof window !== 'undefined') {\n  const _initMatch = router.matchRoute(window.location.pathname)\n  if (_initMatch?.route?.load) {\n    try { await _initMatch.route.load() } catch { /* non-fatal */ }\n  }\n}\n\nif (typeof window !== 'undefined') {\n  await _replace(window.location.pathname + window.location.search + window.location.hash)\n  delete (globalThis as any).__CER_DATA__\n  createDOMJITCSS().mount()\n}\n\nexport { router }\n`,
     'utf-8',
   )
 

package/src/cli/create/templates/spa/app/app.ts.tpl

@@ -8,6 +8,7 @@ import { hasError, errorTag } from 'virtual:cer-error'
 import {
   component,
   ref,
+  provide,
   useOnConnected,
   useOnDisconnected,
   registerBuiltinComponents,
@@ -41,7 +42,14 @@ router.replace = async (path) => {
   try { await _replace(path) } catch (err) { currentError.value = err instanceof Error ? err.message : String(err) } finally { isNavigating.value = false }
 }
 
+const _pluginProvides = new Map<string, unknown>()
+;(globalThis as any).__cerPluginProvides = _pluginProvides
+
 component('cer-layout-view', () => {
+  for (const [key, value] of _pluginProvides) {
+    provide(key, value)
+  }
+
   const current = ref(router.getCurrent())
   let unsub: (() => void) | undefined
   useOnConnected(() => { unsub = router.subscribe((s: typeof current.value) => { current.value = s }) })
@@ -49,7 +57,7 @@ component('cer-layout-view', () => {
 
   if (currentError.value !== null) {
     if (hasError && errorTag) return { tag: errorTag, props: { attrs: { error: String(currentError.value) } }, children: [] }
-    return { tag: 'div', props: { attrs: { style: 'padding:2rem;font-family:monospace' } }, children: [String(currentError.value)] }
+    return { tag: 'div', props: { attrs: { style: 'padding:2rem;font-family:monospace' } }, children: String(currentError.value) }
   }
   if (isNavigating.value && hasLoading && loadingTag) return { tag: loadingTag, props: {}, children: [] }
 
@@ -62,12 +70,24 @@ component('cer-layout-view', () => {
 
 for (const plugin of plugins) {
   if (plugin && typeof plugin.setup === 'function') {
-    await plugin.setup({ router, provide: (key, value) => { (globalThis as any)[key] = value }, config: {} })
+    await plugin.setup({ router, provide: (key: string, value: unknown) => { _pluginProvides.set(key, value) }, config: {} })
+  }
+}
+
+// Pre-load the current page's route chunk AFTER plugins run so that
+// cer-layout-view's first render (which calls provide()) completes before
+// page components are defined. This ensures inject() in child components
+// can find values stored by provide().
+if (typeof window !== 'undefined') {
+  const _initMatch = router.matchRoute(window.location.pathname)
+  if (_initMatch?.route?.load) {
+    try { await _initMatch.route.load() } catch { /* non-fatal */ }
   }
 }
 
 if (typeof window !== 'undefined') {
-  await router.replace(window.location.pathname + window.location.search + window.location.hash)
+  // Use the original (unwrapped) replace so isNavigating stays false on first paint.
+  await _replace(window.location.pathname + window.location.search + window.location.hash)
   createDOMJITCSS().mount()
 }
 

package/src/cli/create/templates/ssg/app/app.ts.tpl

@@ -8,6 +8,7 @@ import { hasError, errorTag } from 'virtual:cer-error'
 import {
   component,
   ref,
+  provide,
   useOnConnected,
   useOnDisconnected,
   registerBuiltinComponents,
@@ -41,7 +42,14 @@ router.replace = async (path) => {
   try { await _replace(path) } catch (err) { currentError.value = err instanceof Error ? err.message : String(err) } finally { isNavigating.value = false }
 }
 
+const _pluginProvides = new Map<string, unknown>()
+;(globalThis as any).__cerPluginProvides = _pluginProvides
+
 component('cer-layout-view', () => {
+  for (const [key, value] of _pluginProvides) {
+    provide(key, value)
+  }
+
   const current = ref(router.getCurrent())
   let unsub: (() => void) | undefined
   useOnConnected(() => { unsub = router.subscribe((s: typeof current.value) => { current.value = s }) })
@@ -49,7 +57,7 @@ component('cer-layout-view', () => {
 
   if (currentError.value !== null) {
     if (hasError && errorTag) return { tag: errorTag, props: { attrs: { error: String(currentError.value) } }, children: [] }
-    return { tag: 'div', props: { attrs: { style: 'padding:2rem;font-family:monospace' } }, children: [String(currentError.value)] }
+    return { tag: 'div', props: { attrs: { style: 'padding:2rem;font-family:monospace' } }, children: String(currentError.value) }
   }
   if (isNavigating.value && hasLoading && loadingTag) return { tag: loadingTag, props: {}, children: [] }
 
@@ -62,12 +70,28 @@ component('cer-layout-view', () => {
 
 for (const plugin of plugins) {
   if (plugin && typeof plugin.setup === 'function') {
-    await plugin.setup({ router, provide: (key, value) => { (globalThis as any)[key] = value }, config: {} })
+    await plugin.setup({ router, provide: (key: string, value: unknown) => { _pluginProvides.set(key, value) }, config: {} })
+  }
+}
+
+// Pre-load the current page's route chunk AFTER plugins run so that
+// cer-layout-view's first render (which calls provide()) completes before
+// page components are defined. This ensures inject() in child components
+// can find values stored by provide().
+if (typeof window !== 'undefined') {
+  const _initMatch = router.matchRoute(window.location.pathname)
+  if (_initMatch?.route?.load) {
+    try { await _initMatch.route.load() } catch { /* non-fatal */ }
   }
 }
 
 if (typeof window !== 'undefined') {
-  await router.replace(window.location.pathname + window.location.search + window.location.hash)
+  // Use the original (unwrapped) replace so isNavigating stays false on first
+  // paint — the loading component must not flash over pre-rendered SSG content.
+  await _replace(window.location.pathname + window.location.search + window.location.hash)
+  // Clear SSR hydration data after initial navigation so subsequent navigations
+  // don't accidentally reuse it.
+  delete (globalThis as any).__CER_DATA__
   createDOMJITCSS().mount()
 }
 

package/src/cli/create/templates/ssg/app/pages/index.ts.tpl

@@ -6,12 +6,3 @@ component('page-index', () => {
     </div>
   `
 })
-
-// Export page metadata for SSG
-export const meta = {
-  layout: 'default',
-  ssg: {
-    // No dynamic paths needed for the index page
-    paths: async () => [],
-  },
-}

package/src/cli/create/templates/ssr/app/app.ts.tpl

@@ -8,6 +8,7 @@ import { hasError, errorTag } from 'virtual:cer-error'
 import {
   component,
   ref,
+  provide,
   useOnConnected,
   useOnDisconnected,
   registerBuiltinComponents,
@@ -41,7 +42,14 @@ router.replace = async (path) => {
   try { await _replace(path) } catch (err) { currentError.value = err instanceof Error ? err.message : String(err) } finally { isNavigating.value = false }
 }
 
+const _pluginProvides = new Map<string, unknown>()
+;(globalThis as any).__cerPluginProvides = _pluginProvides
+
 component('cer-layout-view', () => {
+  for (const [key, value] of _pluginProvides) {
+    provide(key, value)
+  }
+
   const current = ref(router.getCurrent())
   let unsub: (() => void) | undefined
   useOnConnected(() => { unsub = router.subscribe((s: typeof current.value) => { current.value = s }) })
@@ -49,7 +57,7 @@ component('cer-layout-view', () => {
 
   if (currentError.value !== null) {
     if (hasError && errorTag) return { tag: errorTag, props: { attrs: { error: String(currentError.value) } }, children: [] }
-    return { tag: 'div', props: { attrs: { style: 'padding:2rem;font-family:monospace' } }, children: [String(currentError.value)] }
+    return { tag: 'div', props: { attrs: { style: 'padding:2rem;font-family:monospace' } }, children: String(currentError.value) }
   }
   if (isNavigating.value && hasLoading && loadingTag) return { tag: loadingTag, props: {}, children: [] }
 
@@ -62,12 +70,28 @@ component('cer-layout-view', () => {
 
 for (const plugin of plugins) {
   if (plugin && typeof plugin.setup === 'function') {
-    await plugin.setup({ router, provide: (key, value) => { (globalThis as any)[key] = value }, config: {} })
+    await plugin.setup({ router, provide: (key: string, value: unknown) => { _pluginProvides.set(key, value) }, config: {} })
+  }
+}
+
+// Pre-load the current page's route chunk AFTER plugins run so that
+// cer-layout-view's first render (which calls provide()) completes before
+// page components are defined. This ensures inject() in child components
+// can find values stored by provide().
+if (typeof window !== 'undefined') {
+  const _initMatch = router.matchRoute(window.location.pathname)
+  if (_initMatch?.route?.load) {
+    try { await _initMatch.route.load() } catch { /* non-fatal */ }
   }
 }
 
 if (typeof window !== 'undefined') {
-  await router.replace(window.location.pathname + window.location.search + window.location.hash)
+  // Use the original (unwrapped) replace so isNavigating stays false on first
+  // paint — the loading component must not flash over pre-rendered SSR content.
+  await _replace(window.location.pathname + window.location.search + window.location.hash)
+  // Clear SSR hydration data after initial navigation so subsequent navigations
+  // don't accidentally reuse it.
+  delete (globalThis as any).__CER_DATA__
   createDOMJITCSS().mount()
 }
 

package/src/plugin/build-ssg.ts

@@ -146,8 +146,9 @@ async function renderPath(
  * Writes the rendered HTML to the output directory.
  * path '/' -> dist/index.html
  * path '/about' -> dist/about/index.html
+ * @internal exported for unit testing
  */
-async function writeRenderedPath(
+export async function writeRenderedPath(
   path: string,
   html: string,
   distDir: string,

package/src/plugin/build-ssr.ts

@@ -40,6 +40,7 @@ import { registerBuiltinComponents } from '@jasonshimmy/custom-elements-runtime'
 import { registerEntityMap, renderToStringWithJITCSSDSD, DSD_POLYFILL_SCRIPT } from '@jasonshimmy/custom-elements-runtime/ssr'
 import entitiesJson from '@jasonshimmy/custom-elements-runtime/entities.json'
 import { initRouter } from '@jasonshimmy/custom-elements-runtime/router'
+import { beginHeadCollection, endHeadCollection, serializeHeadTags } from '@jasonshimmy/vite-plugin-cer-app/composables'
 
 registerBuiltinComponents()
 
@@ -69,13 +70,16 @@ function _mergeWithClientTemplate(ssrHtml, clientTemplate) {
     ? ssrHtml.slice(headStart + headTag.length, headEnd).trim() : ''
   const ssrBody = bodyStart >= 0 && bodyEnd > bodyStart
     ? ssrHtml.slice(bodyStart + bodyTag.length, bodyEnd).trim() : ssrHtml
-  // Hoist <style> elements from the SSR body into the document <head> so
-  // JIT CSS rules are applied before the layout paints.
+  // Hoist only top-level <style id=...> elements (cer-ssr-jit, cer-ssr-global)
+  // from the SSR body into the document <head>. Plain <style> blocks without
+  // an id attribute belong to shadow DOM templates and must stay in place —
+  // hoisting them to <head> breaks shadow DOM style encapsulation (document
+  // styles do not pierce shadow roots), which is the root cause of FOUC.
   const headParts = ssrHead ? [ssrHead] : []
   let ssrBodyContent = ssrBody
   let pos = 0
   while (pos < ssrBodyContent.length) {
-    const styleOpen  = ssrBodyContent.indexOf('<style', pos)
+    const styleOpen  = ssrBodyContent.indexOf('<style id=', pos)
     if (styleOpen < 0) break
     const styleClose = ssrBodyContent.indexOf('</style>', styleOpen)
     if (styleClose < 0) break
@@ -95,7 +99,14 @@ function _mergeWithClientTemplate(ssrHtml, clientTemplate) {
       '<div id="app">' + ssrBodyContent + '</div>')
   }
   const headAdditions = headParts.filter(Boolean).join('\\n')
-  if (headAdditions) merged = merged.replace('</head>', headAdditions + '\\n</head>')
+  if (headAdditions) {
+    // If SSR provides a <title>, replace the client template's <title> so the
+    // SSR title wins (client template title is the fallback default).
+    if (headAdditions.includes('<title>')) {
+      merged = merged.replace(/<title>[^<]*<\\/title>/, '')
+    }
+    merged = merged.replace('</head>', headAdditions + '\\n</head>')
+  }
   return merged
 }
 
@@ -157,6 +168,9 @@ export const handler = async (req, res) => {
     ;(globalThis).__CER_DATA__ = loaderData
   }
 
+  // Begin collecting useHead() calls made during the synchronous render pass.
+  beginHeadCollection()
+
   // dsdPolyfill: false — we inject the polyfill manually after merging so it
   // lands at the end of <body>, not inside <cer-layout-view> light DOM where
   // scripts may not execute.
@@ -165,13 +179,19 @@ export const handler = async (req, res) => {
     router,
   })
 
+  // Collect and serialize any useHead() calls from the rendered components.
+  const headTags = serializeHeadTags(endHeadCollection())
+
   // Clear immediately after the synchronous render so the value never leaks
   // to the next request on this same server process.
   delete (globalThis).__CER_DATA__
 
+  // Merge loader data script + useHead() tags into the document head.
+  const headContent = [head, headTags].filter(Boolean).join('\\n')
+
   // Wrap the rendered body in a full HTML document and inject the head additions
   // (loader data script, useHead() tags, JIT styles). No polyfill in body yet.
-  const ssrHtml = \`<!DOCTYPE html><html><head>\${head ?? ''}</head><body>\${htmlWithStyles}</body></html>\`
+  const ssrHtml = \`<!DOCTYPE html><html><head>\${headContent}</head><body>\${htmlWithStyles}</body></html>\`
 
   let finalHtml = _clientTemplate
     ? _mergeWithClientTemplate(ssrHtml, _clientTemplate)
@@ -259,7 +279,7 @@ export async function buildSSR(
       },
     },
     ssr: {
-      noExternal: ['@jasonshimmy/custom-elements-runtime'],
+      noExternal: ['@jasonshimmy/custom-elements-runtime', '@jasonshimmy/vite-plugin-cer-app'],
     },
   })
 

package/src/runtime/composables/index.ts

@@ -1,3 +1,3 @@
-export { useHead } from './use-head.js'
+export { useHead, beginHeadCollection, endHeadCollection, serializeHeadTags } from './use-head.js'
 export type { HeadInput } from './use-head.js'
 export { usePageData } from './use-page-data.js'

package/src/runtime/composables/use-head.ts

@@ -6,15 +6,18 @@ export interface HeadInput {
   style?: Array<Record<string, string>>
 }
 
-// SSR: global collector, reset per-request
-let _ssrCollector: HeadInput[] | null = null
+// SSR: store collector on globalThis so all module instances (server entry +
+// dynamically-imported page chunks) share the same reference. A module-level
+// variable would create separate instances per chunk, breaking the singleton.
+const _g = globalThis as Record<string, unknown>
+const _KEY = '__CER_HEAD_COLLECTOR__'
 
 /**
  * Begin collecting head tags for an SSR render pass.
  * Call this before invoking the render function.
  */
 export function beginHeadCollection(): void {
-  _ssrCollector = []
+  _g[_KEY] = [] as HeadInput[]
 }
 
 /**
@@ -22,8 +25,8 @@ export function beginHeadCollection(): void {
  * Resets the collector to null.
  */
 export function endHeadCollection(): HeadInput[] {
-  const collected = _ssrCollector ?? []
-  _ssrCollector = null
+  const collected = (_g[_KEY] as HeadInput[]) ?? []
+  _g[_KEY] = null
   return collected
 }
 
@@ -111,9 +114,10 @@ export function serializeHeadTags(heads: HeadInput[]): string {
  * - On the client: imperatively updates document.title and meta/link tags
  */
 export function useHead(input: HeadInput): void {
-  if (_ssrCollector !== null) {
-    // SSR mode
-    _ssrCollector.push(input)
+  const collector = _g[_KEY] as HeadInput[] | null | undefined
+  if (collector != null) {
+    // SSR mode: push to the shared globalThis collector
+    collector.push(input)
   } else if (typeof document !== 'undefined') {
     // Client-side
     if (input.title !== undefined) {

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

@@ -57,13 +57,16 @@ function _mergeWithClientTemplate(ssrHtml, clientTemplate) {
     ? ssrHtml.slice(headStart + headTag.length, headEnd).trim() : ''
   const ssrBody = bodyStart >= 0 && bodyEnd > bodyStart
     ? ssrHtml.slice(bodyStart + bodyTag.length, bodyEnd).trim() : ssrHtml
-  // Hoist <style> elements from the SSR body into the document <head> so
-  // JIT CSS rules are applied before the layout paints.
+  // Hoist only top-level <style id=...> elements (cer-ssr-jit, cer-ssr-global)
+  // from the SSR body into the document <head>. Plain <style> blocks without
+  // an id attribute belong to shadow DOM templates and must stay in place —
+  // hoisting them to <head> breaks shadow DOM style encapsulation (document
+  // styles do not pierce shadow roots), which is the root cause of FOUC.
   const headParts = ssrHead ? [ssrHead] : []
   let ssrBodyContent = ssrBody
   let pos = 0
   while (pos < ssrBodyContent.length) {
-    const styleOpen  = ssrBodyContent.indexOf('<style', pos)
+    const styleOpen  = ssrBodyContent.indexOf('<style id=', pos)
     if (styleOpen < 0) break
     const styleClose = ssrBodyContent.indexOf('</style>', styleOpen)
     if (styleClose < 0) break
@@ -83,7 +86,14 @@ function _mergeWithClientTemplate(ssrHtml, clientTemplate) {
       '<div id="app">' + ssrBodyContent + '</div>')
   }
   const headAdditions = headParts.filter(Boolean).join('\\n')
-  if (headAdditions) merged = merged.replace('</head>', headAdditions + '\\n</head>')
+  if (headAdditions) {
+    // If SSR provides a <title>, replace the client template's <title> so the
+    // SSR title wins (client template title is the fallback default).
+    if (headAdditions.includes('<title>')) {
+      merged = merged.replace(/<title>[^<]*<\\/title>/, '')
+    }
+    merged = merged.replace('</head>', headAdditions + '\\n</head>')
+  }
   return merged
 }
 

package/vitest.config.ts

@@ -19,10 +19,14 @@ export default defineConfig({
       include: ['src/**/*.ts'],
       exclude: [
         'src/cli/**',
-        'src/runtime/app-template.ts',
         'src/runtime/entry-client-template.ts',
         'src/runtime/entry-server-template.ts',
         'src/__tests__/**',
+        // Pure type-only files — no executable statements, V8 cannot instrument them
+        'src/types/**',
+        // Barrel re-export files — only `export { } from ...` lines, no logic
+        'src/index.ts',
+        'src/runtime/composables/index.ts',
       ],
     },
   },