@uniweb/build 0.8.18 → 0.8.20

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@uniweb/build",
-  "version": "0.8.18",
+  "version": "0.8.20",
   "description": "Build tooling for the Uniweb Component Web Platform",
   "type": "module",
   "exports": {
@@ -17,7 +17,8 @@
     "./dev": "./src/dev/index.js",
     "./prerender": "./src/prerender.js",
     "./i18n": "./src/i18n/index.js",
-    "./search": "./src/search/index.js"
+    "./search": "./src/search/index.js",
+    "./import-map-plugin": "./src/import-map-plugin.js"
   },
   "files": [
     "src"
@@ -52,9 +53,9 @@
     "@uniweb/theming": "0.1.2"
   },
   "optionalDependencies": {
-    "@uniweb/runtime": "0.6.13",
-    "@uniweb/schemas": "0.2.1",
-    "@uniweb/content-reader": "1.1.4"
+    "@uniweb/content-reader": "1.1.4",
+    "@uniweb/runtime": "0.6.15",
+    "@uniweb/schemas": "0.2.1"
   },
   "peerDependencies": {
     "vite": "^5.0.0 || ^6.0.0 || ^7.0.0",
@@ -63,7 +64,7 @@
     "@tailwindcss/vite": "^4.0.0",
     "@vitejs/plugin-react": "^4.0.0 || ^5.0.0",
     "vite-plugin-svgr": "^4.0.0",
-    "@uniweb/core": "0.5.12"
+    "@uniweb/core": "0.5.14"
   },
   "peerDependenciesMeta": {
     "vite": {

package/src/import-map-plugin.js

@@ -0,0 +1,145 @@
+/**
+ * Import Map Plugin
+ *
+ * Shared Vite plugin that emits import-map bridge modules so that
+ * foundations loaded via dynamic import() can resolve bare specifiers
+ * (react, @uniweb/core, etc.) to the same instances used by the host app.
+ *
+ * Production: emits deterministic chunks at _importmap/*.js with explicit
+ * named re-exports, and injects a <script type="importmap"> into the HTML.
+ *
+ * Used by:
+ * - Site builds (runtime mode + extensions)  — packages/build/src/site/config.js
+ * - Runtime shell build                      — packages/runtime/vite.config.app.js
+ * - Dynamic-runtime (editor preview)         — packages/uniweb-editor/dynamic-runtime/
+ *
+ * @module @uniweb/build/import-map-plugin
+ */
+
+/** Default externals shared between foundations and hosts */
+const DEFAULT_EXTERNALS = [
+  'react',
+  'react-dom',
+  'react/jsx-runtime',
+  'react/jsx-dev-runtime',
+  '@uniweb/core',
+]
+
+const IMPORT_MAP_PREFIX = '\0importmap:'
+
+/** Valid JS identifier — filters out non-identifier keys from CJS modules */
+const isValidId = (k) => /^[a-zA-Z_$][a-zA-Z0-9_$]*$/.test(k)
+
+/**
+ * Create the import map Vite plugin.
+ *
+ * @param {Object} [options]
+ * @param {string[]} [options.externals] - Package specifiers to bridge (default: react, react-dom, @uniweb/core, etc.)
+ * @param {string} [options.name] - Plugin name (default: 'uniweb:import-map')
+ * @param {string} [options.basePath] - Base path prefix for import map URLs in HTML (default: '/')
+ * @param {string} [options.resolveFrom] - Absolute path to resolve bare specifiers from inside virtual modules.
+ *   Needed when the host project doesn't have the externals as direct dependencies (e.g., site builds
+ *   under pnpm strict mode resolve from the foundation directory instead).
+ * @param {Object} [options.devBridges] - Map of specifier → dev-mode URL for import map injection in dev.
+ *   When provided, the import map is injected in both dev and prod (with different URLs).
+ *   When omitted, the import map is only injected in prod (dev uses other mechanisms like transformRequest).
+ * @returns {import('vite').Plugin}
+ */
+export function importMapPlugin({
+  externals = DEFAULT_EXTERNALS,
+  name = 'uniweb:import-map',
+  basePath = '/',
+  resolveFrom,
+  devBridges,
+} = {}) {
+  let isBuild = false
+
+  return {
+    name,
+
+    configResolved(config) {
+      isBuild = config.command === 'build'
+    },
+
+    resolveId(id, importer) {
+      if (id.startsWith(IMPORT_MAP_PREFIX)) return id
+      // Bare specifiers inside our virtual modules (e.g. '@uniweb/core' re-exported
+      // from '\0importmap:@uniweb/core') can't be resolved by Rollup because virtual
+      // modules have no filesystem context. When a resolveFrom path is provided,
+      // resolve from there (e.g. the foundation directory under pnpm strict mode).
+      if (resolveFrom && importer?.startsWith(IMPORT_MAP_PREFIX) && externals.includes(id)) {
+        return this.resolve(id, resolveFrom, { skipSelf: true })
+      }
+    },
+
+    async load(id) {
+      if (!id.startsWith(IMPORT_MAP_PREFIX)) return
+      const pkg = id.slice(IMPORT_MAP_PREFIX.length)
+
+      // Generate explicit named re-exports (not `export *`) because CJS
+      // packages like React only expose a default via `export *`, losing
+      // individual named exports (useState, jsx, etc.) that foundations need.
+      try {
+        const mod = await import(pkg)
+        const names = Object.keys(mod).filter((k) => k !== '__esModule' && isValidId(k))
+        const hasDefault = 'default' in mod
+        const named = names.filter((k) => k !== 'default')
+        const lines = []
+        if (named.length) {
+          lines.push(`export { ${named.join(', ')} } from '${pkg}'`)
+        }
+        if (hasDefault) {
+          lines.push(`export { default } from '${pkg}'`)
+        }
+        return lines.join('\n') || 'export {}'
+      } catch {
+        // Fallback: generic re-export (may not preserve named exports for CJS)
+        return `export * from '${pkg}'`
+      }
+    },
+
+    // Emit deterministic chunks for each external (production only).
+    // preserveSignature: 'exports-only' tells Rollup to preserve the original
+    // export names (useState, jsx, etc.) instead of mangling them.
+    buildStart() {
+      if (!isBuild) return
+      for (const ext of externals) {
+        this.emitFile({
+          type: 'chunk',
+          id: `${IMPORT_MAP_PREFIX}${ext}`,
+          fileName: `_importmap/${ext.replace(/\//g, '-')}.js`,
+          preserveSignature: 'exports-only',
+        })
+      }
+    },
+
+    // Inject the import map into the HTML.
+    // In prod: always injects with basePath-prefixed _importmap/ URLs.
+    // In dev: only injects if devBridges are provided (otherwise, the consumer
+    //   handles dev-mode resolution via other mechanisms like transformRequest).
+    transformIndexHtml: {
+      order: 'pre',
+      handler(html) {
+        const imports = {}
+
+        if (isBuild) {
+          for (const ext of externals) {
+            imports[ext] = `${basePath}_importmap/${ext.replace(/\//g, '-')}.js`
+          }
+        } else if (devBridges) {
+          Object.assign(imports, devBridges)
+        } else {
+          // No dev injection — consumer handles dev mode separately
+          return html
+        }
+
+        const importMap = JSON.stringify({ imports }, null, 2)
+        const script = `    <script type="importmap">\n${importMap}\n    </script>\n`
+        // Import map must appear before any module scripts
+        return html.replace('<head>', '<head>\n' + script)
+      },
+    },
+  }
+}
+
+export { DEFAULT_EXTERNALS }

package/src/prerender.js

@@ -2,16 +2,14 @@
  * SSG Prerendering for Uniweb Sites
  *
  * Renders each page to static HTML at build time.
- * The output includes full HTML with hydration support.
- *
- * Uses @uniweb/runtime/ssr for rendering components, ensuring
- * the same code path for both SSG and client-side rendering.
+ * Uses @uniweb/runtime/ssr for the rendering pipeline (init, render, inject).
+ * This file handles build-specific orchestration: data fetching, locale discovery,
+ * dynamic route expansion, extension loading, and build-specific HTML injections.
  */
 
 import { readFile, writeFile, mkdir } from 'node:fs/promises'
 import { existsSync, readdirSync, statSync } from 'node:fs'
 import { join, dirname, resolve } from 'node:path'
-import { createRequire } from 'node:module'
 import { pathToFileURL } from 'node:url'
 import { executeFetch, mergeDataIntoContent, singularize } from './site/data-fetcher.js'
 
@@ -46,10 +44,6 @@ function resolveExtensionPath(url, distDir, projectRoot) {
   return url
 }
 
-// Lazily loaded dependencies
-let React, renderToString, createUniweb
-let preparePropsSSR, getComponentMetaSSR
-
 /**
  * Execute all data fetches for prerender
  * Processes site, page, and section level fetches, merging data appropriately
@@ -246,371 +240,6 @@ async function processSectionFetches(sections, fetchOptions, onProgress) {
   }
 }
 
-/**
- * Load dependencies dynamically from the site's context
- * This ensures we use the same React instance as the foundation
- *
- * @param {string} siteDir - Path to the site directory
- */
-async function loadDependencies(siteDir) {
-  if (React) return // Already loaded
-
-  // Load React from the site's node_modules using createRequire.
-  // This ensures we get the same React instance as the foundation
-  // components (which are loaded via pathToFileURL and externalize React
-  // to the same node_modules). Using bare import('react') would resolve
-  // from @uniweb/build's context, creating a dual-React instance problem.
-  const absoluteSiteDir = resolve(siteDir)
-  const siteRequire = createRequire(join(absoluteSiteDir, 'package.json'))
-
-  try {
-    const reactMod = siteRequire('react')
-    const serverMod = siteRequire('react-dom/server')
-    React = reactMod.default || reactMod
-    renderToString = serverMod.renderToString
-  } catch {
-    const [reactMod, serverMod] = await Promise.all([
-      import('react'),
-      import('react-dom/server')
-    ])
-    React = reactMod.default || reactMod
-    renderToString = serverMod.renderToString
-  }
-
-  // Load @uniweb/core
-  const coreMod = await import('@uniweb/core')
-  createUniweb = coreMod.createUniweb
-
-  // Load pure utility functions from runtime SSR bundle.
-  // These are plain functions (no hooks), so they work even if the SSR
-  // bundle resolves a different React instance internally.
-  const runtimeMod = await import('@uniweb/runtime/ssr')
-  preparePropsSSR = runtimeMod.prepareProps
-  getComponentMetaSSR = runtimeMod.getComponentMeta
-}
-
-/**
- * Pre-fetch icons from CDN and populate the Uniweb icon cache.
- * This allows the Icon component to render SVGs synchronously during SSR
- * instead of producing empty placeholders.
- */
-async function prefetchIcons(siteContent, uniweb, onProgress) {
-  const icons = siteContent.icons?.used || []
-  if (icons.length === 0) return
-
-  const cdnBase = siteContent.config?.icons?.cdnUrl || 'https://uniweb.github.io/icons'
-
-  onProgress(`Fetching ${icons.length} icons for SSR...`)
-
-  const results = await Promise.allSettled(
-    icons.map(async (iconRef) => {
-      const [family, name] = iconRef.split(':')
-      const url = `${cdnBase}/${family}/${family}-${name}.svg`
-      const response = await fetch(url)
-      if (!response.ok) throw new Error(`HTTP ${response.status}`)
-      const svg = await response.text()
-      uniweb.iconCache.set(`${family}:${name}`, svg)
-    })
-  )
-
-  const succeeded = results.filter(r => r.status === 'fulfilled').length
-  const failed = results.filter(r => r.status === 'rejected').length
-  if (failed > 0) {
-    console.warn(`[prerender] Fetched ${succeeded}/${icons.length} icons (${failed} failed)`)
-  }
-
-  // Store icon cache on siteContent for embedding in HTML
-  // This allows the client runtime to populate the cache before rendering
-  if (uniweb.iconCache.size > 0) {
-    siteContent._iconCache = Object.fromEntries(uniweb.iconCache)
-  }
-}
-
-/**
- * Valid color contexts for section theming
- */
-const VALID_CONTEXTS = ['light', 'medium', 'dark']
-
-/**
- * Build wrapper props from block configuration
- * Mirrors getWrapperProps in BlockRenderer.jsx
- */
-function getWrapperProps(block) {
-  const theme = block.themeName
-  const blockClassName = block.state?.className || ''
-
-  let contextClass = ''
-  if (theme && VALID_CONTEXTS.includes(theme)) {
-    contextClass = `context-${theme}`
-  }
-
-  let className = contextClass
-  if (blockClassName) {
-    className = className ? `${className} ${blockClassName}` : blockClassName
-  }
-
-  const { background = {} } = block.standardOptions
-  const style = {}
-  if (background.mode) {
-    style.position = 'relative'
-  }
-
-  // Apply context overrides as inline CSS custom properties (mirrors BlockRenderer.jsx)
-  if (block.contextOverrides) {
-    for (const [key, value] of Object.entries(block.contextOverrides)) {
-      style[`--${key}`] = value
-    }
-  }
-
-  const sectionId = block.stableId || block.id
-  return { id: `section-${sectionId}`, style, className, background }
-}
-
-/**
- * Render a background element for SSR
- * Mirrors the Background component in Background.jsx (image, color, gradient only)
- * Video backgrounds are skipped in SSR (they require JS for autoplay)
- */
-function renderBackground(background) {
-  if (!background?.mode) return null
-
-  const containerStyle = {
-    position: 'absolute',
-    inset: '0',
-    overflow: 'hidden',
-    zIndex: 0,
-  }
-
-  const children = []
-
-  // Resolve URL against basePath for subdirectory deployments
-  const basePath = globalThis.uniweb?.activeWebsite?.basePath || ''
-  function resolveUrl(url) {
-    if (!url || !url.startsWith('/')) return url
-    if (!basePath) return url
-    if (url.startsWith(basePath + '/') || url === basePath) return url
-    return basePath + url
-  }
-
-  if (background.mode === 'color' && background.color) {
-    children.push(
-      React.createElement('div', {
-        key: 'bg-color',
-        className: 'background-color',
-        style: { position: 'absolute', inset: '0', backgroundColor: background.color },
-        'aria-hidden': 'true'
-      })
-    )
-  }
-
-  if (background.mode === 'gradient' && background.gradient) {
-    const g = background.gradient
-    // Raw CSS gradient string (e.g., "linear-gradient(to bottom, #000, #333)")
-    const bgValue = typeof g === 'string' ? g
-      : `linear-gradient(${g.angle || 0}deg, ${g.start || 'transparent'} ${g.startPosition || 0}%, ${g.end || 'transparent'} ${g.endPosition || 100}%)`
-    children.push(
-      React.createElement('div', {
-        key: 'bg-gradient',
-        className: 'background-gradient',
-        style: {
-          position: 'absolute', inset: '0',
-          background: bgValue
-        },
-        'aria-hidden': 'true'
-      })
-    )
-  }
-
-  if (background.mode === 'image' && background.image?.src) {
-    const img = background.image
-    children.push(
-      React.createElement('div', {
-        key: 'bg-image',
-        className: 'background-image',
-        style: {
-          position: 'absolute', inset: '0',
-          backgroundImage: `url(${resolveUrl(img.src)})`,
-          backgroundPosition: img.position || 'center',
-          backgroundSize: img.size || 'cover',
-          backgroundRepeat: 'no-repeat'
-        },
-        'aria-hidden': 'true'
-      })
-    )
-  }
-
-  // Overlay
-  if (background.overlay?.enabled) {
-    const ov = background.overlay
-    let overlayStyle
-
-    if (ov.gradient) {
-      const g = ov.gradient
-      overlayStyle = {
-        position: 'absolute', inset: '0', pointerEvents: 'none',
-        background: `linear-gradient(${g.angle || 180}deg, ${g.start || 'rgba(0,0,0,0.7)'} ${g.startPosition || 0}%, ${g.end || 'rgba(0,0,0,0)'} ${g.endPosition || 100}%)`,
-        opacity: ov.opacity ?? 0.5
-      }
-    } else {
-      const baseColor = ov.type === 'light' ? '255, 255, 255' : '0, 0, 0'
-      overlayStyle = {
-        position: 'absolute', inset: '0', pointerEvents: 'none',
-        backgroundColor: `rgba(${baseColor}, ${ov.opacity ?? 0.5})`
-      }
-    }
-
-    children.push(
-      React.createElement('div', {
-        key: 'bg-overlay',
-        className: 'background-overlay',
-        style: overlayStyle,
-        'aria-hidden': 'true'
-      })
-    )
-  }
-
-  if (children.length === 0) return null
-
-  return React.createElement('div', {
-    className: `background background--${background.mode}`,
-    style: containerStyle,
-    'aria-hidden': 'true'
-  }, ...children)
-}
-
-/**
- * Render a single block for SSR
- * Mirrors BlockRenderer.jsx but without hooks (no runtime data fetching in SSR).
- * block.dataLoading is always false at prerender time — runtime fetches only happen client-side.
- */
-function renderBlock(block, { pure = false } = {}) {
-  const Component = block.initComponent()
-
-  if (!Component) {
-    return React.createElement('div', {
-      className: 'block-error',
-      style: { padding: '1rem', background: '#fef2f2', color: '#dc2626' }
-    }, `Component not found: ${block.type}`)
-  }
-
-  // Build content and params with runtime guarantees
-  const meta = getComponentMetaSSR(block.type)
-  const prepared = preparePropsSSR(block, meta)
-  let params = prepared.params
-  let content = {
-    ...prepared.content,
-    ...block.properties,
-  }
-
-  // Resolve inherited entity data (mirrors BlockRenderer.jsx)
-  // EntityStore walks page/site hierarchy to find data matching meta.inheritData
-  const entityStore = block.website?.entityStore
-  if (entityStore) {
-    const resolved = entityStore.resolve(block, meta)
-    if (resolved.status === 'ready' && resolved.data) {
-      const merged = { ...content.data }
-      for (const key of Object.keys(resolved.data)) {
-        if (merged[key] === undefined) {
-          merged[key] = resolved.data[key]
-        }
-      }
-      content.data = merged
-    }
-  }
-
-  const componentProps = { content, params, block }
-
-  // Pure mode: render component without section wrapper (used by ChildBlocks)
-  if (pure) {
-    return React.createElement(Component, componentProps)
-  }
-
-  // Background handling (mirrors BlockRenderer.jsx)
-  const { background, ...wrapperProps } = getWrapperProps(block)
-
-  // Merge Component.className (static classes declared on the component function)
-  // Order: context-{theme} + block.state.className + Component.className
-  const componentClassName = Component.className
-  if (componentClassName) {
-    wrapperProps.className = wrapperProps.className
-      ? `${wrapperProps.className} ${componentClassName}`
-      : componentClassName
-  }
-
-  const hasBackground = background?.mode && meta?.background !== 'self'
-
-  block.hasBackground = hasBackground
-
-  // Use Component.as as the wrapper tag (default: 'section')
-  const wrapperTag = Component.as || 'section'
-
-  if (hasBackground) {
-    return React.createElement(wrapperTag, wrapperProps,
-      renderBackground(background),
-      React.createElement('div', { className: 'relative z-10' },
-        React.createElement(Component, componentProps)
-      )
-    )
-  }
-
-  return React.createElement(wrapperTag, wrapperProps,
-    React.createElement(Component, componentProps)
-  )
-}
-
-/**
- * Render an array of blocks for SSR
- */
-function renderBlocks(blocks) {
-  if (!blocks || blocks.length === 0) return null
-  return blocks.map((block, index) =>
-    React.createElement(React.Fragment, { key: block.id || index },
-      renderBlock(block)
-    )
-  )
-}
-
-/**
- * Render page layout for SSR
- */
-function renderLayout(page, website) {
-  const layoutName = page.getLayoutName()
-  const RemoteLayout = website.getRemoteLayout(layoutName)
-  const layoutMeta = website.getLayoutMeta(layoutName)
-
-  const bodyBlocks = page.getBodyBlocks()
-  const areas = page.getLayoutAreas()
-
-  const bodyElement = bodyBlocks ? renderBlocks(bodyBlocks) : null
-  const areaElements = {}
-  for (const [name, blocks] of Object.entries(areas)) {
-    areaElements[name] = renderBlocks(blocks)
-  }
-
-  if (RemoteLayout) {
-    const params = { ...(layoutMeta?.defaults || {}), ...(page.getLayoutParams() || {}) }
-
-    return React.createElement(RemoteLayout, {
-      page, website, params,
-      body: bodyElement,
-      ...areaElements,
-    })
-  }
-
-  return React.createElement(React.Fragment, null,
-    areaElements.header && React.createElement('header', null, areaElements.header),
-    bodyElement && React.createElement('main', null, bodyElement),
-    areaElements.footer && React.createElement('footer', null, areaElements.footer)
-  )
-}
-
-/**
- * Create a page element for SSR
- */
-function createPageElement(page, website) {
-  return renderLayout(page, website)
-}
-
 /**
  * Discover all locale content files in the dist directory
  * Returns an array of { locale, contentPath, htmlPath, isDefault }
@@ -667,6 +296,85 @@ async function discoverLocaleContents(distDir, defaultContent) {
   return locales
 }
 
+/**
+ * Inject build-specific data into HTML (theme CSS, __SITE_CONTENT__, icon cache).
+ * Called after the shared injectPageContent for build-specific additions.
+ *
+ * @param {string} html - HTML with prerendered content already injected
+ * @param {Object} siteContent - Site content JSON
+ * @returns {string} HTML with build-specific data injected
+ */
+function injectBuildData(html, siteContent) {
+  let result = html
+
+  // Inject theme CSS if not already present
+  if (siteContent?.theme?.css && !result.includes('id="uniweb-theme"')) {
+    result = result.replace(
+      '</head>',
+      `  <style id="uniweb-theme">\n${siteContent.theme.css}\n    </style>\n  </head>`
+    )
+  }
+
+  // Inject site content as JSON for hydration
+  // Strip CSS from theme (it's already in a <style> tag)
+  const contentForJson = { ...siteContent }
+  if (contentForJson.theme?.css) {
+    contentForJson.theme = { ...contentForJson.theme }
+    delete contentForJson.theme.css
+  }
+  const contentScript = `<script id="__SITE_CONTENT__" type="application/json">${JSON.stringify(contentForJson).replace(/</g, '\\u003c')}</script>`
+  if (result.includes('__SITE_CONTENT__')) {
+    // Replace existing site content with updated version (includes expanded dynamic routes)
+    result = result.replace(
+      /<script[^>]*id="__SITE_CONTENT__"[^>]*>[\s\S]*?<\/script>/,
+      contentScript
+    )
+  } else {
+    result = result.replace(
+      '</head>',
+      `  ${contentScript}\n  </head>`
+    )
+  }
+
+  // Inject icon cache so client can render icons immediately without CDN fetches
+  if (siteContent._iconCache) {
+    const iconScript = `<script id="__ICON_CACHE__" type="application/json">${JSON.stringify(siteContent._iconCache).replace(/</g, '\\u003c')}</script>`
+    if (result.includes('__ICON_CACHE__')) {
+      result = result.replace(
+        /<script[^>]*id="__ICON_CACHE__"[^>]*>[\s\S]*?<\/script>/,
+        iconScript
+      )
+    } else {
+      result = result.replace(
+        '</head>',
+        `  ${iconScript}\n  </head>`
+      )
+    }
+  }
+
+  return result
+}
+
+/**
+ * Get output path for a route
+ */
+function getOutputPath(distDir, route) {
+  let normalizedRoute = route
+
+  // Handle root route
+  if (normalizedRoute === '/' || normalizedRoute === '') {
+    return join(distDir, 'index.html')
+  }
+
+  // Remove leading slash
+  if (normalizedRoute.startsWith('/')) {
+    normalizedRoute = normalizedRoute.slice(1)
+  }
+
+  // Create directory structure: /about -> /about/index.html
+  return join(distDir, normalizedRoute, 'index.html')
+}
+
 /**
  * Pre-render all pages in a built site to static HTML
  *
@@ -689,9 +397,13 @@ export async function prerenderSite(siteDir, options = {}) {
     throw new Error(`Site must be built first. No dist directory found at: ${distDir}`)
   }
 
-  // Load dependencies from site's context (ensures same React instance as foundation)
-  onProgress('Loading dependencies...')
-  await loadDependencies(siteDir)
+  // Load shared SSR functions from runtime (lazy — only when prerendering)
+  const {
+    initPrerender,
+    prefetchIcons,
+    renderPage,
+    injectPageContent,
+  } = await import('@uniweb/runtime/ssr')
 
   // Load default site content
   onProgress('Loading site content...')
@@ -753,20 +465,17 @@ export async function prerenderSite(siteDir, options = {}) {
     const shellPath = existsSync(htmlPath) ? htmlPath : join(distDir, 'index.html')
     const htmlShell = await readFile(shellPath, 'utf8')
 
-    // Initialize the Uniweb runtime for this locale
-    onProgress('Initializing runtime...')
-    const uniweb = createUniweb(siteContent)
+    // Initialize the Uniweb runtime using the shared SSR module
+    const uniweb = initPrerender(siteContent, foundation, { onProgress })
 
-    // Pre-populate DataStore so EntityStore can resolve data during prerender
+    // Build-specific: pre-populate DataStore so EntityStore can resolve data during prerender
     if (fetchedData.length > 0 && uniweb.activeWebsite?.dataStore) {
       for (const entry of fetchedData) {
         uniweb.activeWebsite.dataStore.set(entry.config, entry.data)
       }
     }
 
-    uniweb.setFoundation(foundation)
-
-    // Load extensions (secondary foundations via URL)
+    // Build-specific: load extensions (secondary foundations via URL)
     const extensions = siteContent.config?.extensions
     if (extensions?.length) {
       onProgress(`Loading ${extensions.length} extension(s)...`)
@@ -784,41 +493,13 @@ export async function prerenderSite(siteDir, options = {}) {
       }
     }
 
-    // Set base path from site config so components can access it during SSR
-    // (e.g., <Link reload> needs basePath to prefix hrefs for subdirectory deployments)
-    if (siteContent.config?.base && uniweb.activeWebsite?.setBasePath) {
-      uniweb.activeWebsite.setBasePath(siteContent.config.base)
-    }
-
-    // Set foundation capabilities (Layout, props, etc.)
-    if (foundation.default?.capabilities) {
-      uniweb.setFoundationConfig(foundation.default.capabilities)
-    }
-
-    // Attach layout metadata (areas, transitions, defaults)
-    if (foundation.default?.layoutMeta && uniweb.foundationConfig) {
-      uniweb.foundationConfig.layoutMeta = foundation.default.layoutMeta
-    }
-
-    // Set childBlockRenderer so foundation components using ChildBlocks/Visual
-    // can render child blocks and insets during prerender (inline, no hooks)
-    uniweb.childBlockRenderer = function InlineChildBlocks({ blocks, from, pure = false }) {
-      const blockList = blocks || from?.childBlocks || []
-      return blockList.map((childBlock, index) =>
-        React.createElement(React.Fragment, { key: childBlock.id || index },
-          renderBlock(childBlock, { pure })
-        )
-      )
-    }
-
     // Pre-fetch icons for SSR embedding
     await prefetchIcons(siteContent, uniweb, onProgress)
 
     // Pre-render each page
-    const pages = uniweb.activeWebsite.pages
     const website = uniweb.activeWebsite
 
-    for (const page of pages) {
+    for (const page of website.pages) {
       // Skip dynamic template pages — they exist in the content for runtime
       // route matching but can't be pre-rendered (no concrete route)
       if (page.route.includes(':')) continue
@@ -830,43 +511,31 @@ export async function prerenderSite(siteDir, options = {}) {
 
       onProgress(`Rendering ${outputRoute}...`)
 
-      // Set this as the active page
-      uniweb.activeWebsite.setActivePage(page.route)
-
-      // Create the page element for SSR
-      const element = createPageElement(page, website)
-
-      // Render to HTML string
-      let renderedContent
-      try {
-        renderedContent = renderToString(element)
-      } catch (err) {
-        const msg = err.message || ''
+      const result = renderPage(page, website)
 
-        if (msg.includes('Invalid hook call') || msg.includes('useState') || msg.includes('useEffect')) {
+      if (result.error) {
+        if (result.error.type === 'hooks' || result.error.type === 'null-component') {
           console.warn(
-            `  Skipped SSG for ${outputRoute} — contains components with React hooks ` +
-            `(useState/useEffect) that cannot render during pre-rendering. ` +
-            `The page will render correctly client-side.`
-          )
-        } else if (msg.includes('Element type is invalid') && msg.includes('null')) {
-          console.warn(
-            `  Skipped SSG for ${outputRoute} — a component resolved to null during pre-rendering. ` +
-            `This often happens with components that use React hooks. ` +
+            `  Skipped SSG for ${outputRoute} — ${result.error.message}. ` +
             `The page will render correctly client-side.`
           )
         } else {
-          console.warn(`  Warning: Failed to render ${outputRoute}: ${msg}`)
+          console.warn(`  Warning: Failed to render ${outputRoute}: ${result.error.message}`)
         }
 
         if (process.env.DEBUG) {
-          console.error(err.stack)
+          // renderPage swallows the stack, but the classification message is informative
         }
         continue
       }
 
-      // Inject into shell
-      const html = injectContent(htmlShell, renderedContent, page, siteContent)
+      // Shared injection: #root, title, meta, section override CSS
+      let html = injectPageContent(htmlShell, result.renderedContent, page, {
+        sectionOverrideCSS: result.sectionOverrideCSS,
+      })
+
+      // Build-specific: theme CSS, __SITE_CONTENT__, icon cache
+      html = injectBuildData(html, siteContent)
 
       // Output to the locale-prefixed route
       const outputPath = getOutputPath(distDir, outputRoute)
@@ -886,123 +555,4 @@ export async function prerenderSite(siteDir, options = {}) {
   }
 }
 
-/**
- * Inject rendered content into HTML shell
- */
-function injectContent(shell, renderedContent, page, siteContent) {
-  let html = shell
-
-  // Inject theme CSS if not already present
-  if (siteContent?.theme?.css && !html.includes('id="uniweb-theme"')) {
-    html = html.replace(
-      '</head>',
-      `  <style id="uniweb-theme">\n${siteContent.theme.css}\n    </style>\n  </head>`
-    )
-  }
-
-  // Replace the empty root div with pre-rendered content
-  html = html.replace(
-    /<div id="root">[\s\S]*?<\/div>/,
-    `<div id="root">${renderedContent}</div>`
-  )
-
-  // Update page title
-  if (page.title) {
-    html = html.replace(
-      /<title>.*?<\/title>/,
-      `<title>${escapeHtml(page.title)}</title>`
-    )
-  }
-
-  // Add meta description if available
-  if (page.description) {
-    const metaDesc = `<meta name="description" content="${escapeHtml(page.description)}">`
-    if (html.includes('<meta name="description"')) {
-      html = html.replace(
-        /<meta name="description"[^>]*>/,
-        metaDesc
-      )
-    } else {
-      html = html.replace(
-        '</head>',
-        `  ${metaDesc}\n  </head>`
-      )
-    }
-  }
-
-  // Inject site content as JSON for hydration
-  // Replace existing content if present, otherwise add it
-  // Strip CSS from theme (it's already in a <style> tag)
-  const contentForJson = { ...siteContent }
-  if (contentForJson.theme?.css) {
-    contentForJson.theme = { ...contentForJson.theme }
-    delete contentForJson.theme.css
-  }
-  const contentScript = `<script id="__SITE_CONTENT__" type="application/json">${JSON.stringify(contentForJson).replace(/</g, '\\u003c')}</script>`
-  if (html.includes('__SITE_CONTENT__')) {
-    // Replace existing site content with updated version (includes expanded dynamic routes)
-    // Match script tag with attributes in any order
-    html = html.replace(
-      /<script[^>]*id="__SITE_CONTENT__"[^>]*>[\s\S]*?<\/script>/,
-      contentScript
-    )
-  } else {
-    html = html.replace(
-      '</head>',
-      `  ${contentScript}\n  </head>`
-    )
-  }
-
-  // Inject icon cache so client can render icons immediately without CDN fetches
-  if (siteContent._iconCache) {
-    const iconScript = `<script id="__ICON_CACHE__" type="application/json">${JSON.stringify(siteContent._iconCache).replace(/</g, '\\u003c')}</script>`
-    if (html.includes('__ICON_CACHE__')) {
-      html = html.replace(
-        /<script[^>]*id="__ICON_CACHE__"[^>]*>[\s\S]*?<\/script>/,
-        iconScript
-      )
-    } else {
-      html = html.replace(
-        '</head>',
-        `  ${iconScript}\n  </head>`
-      )
-    }
-  }
-
-  return html
-}
-
-/**
- * Get output path for a route
- */
-function getOutputPath(distDir, route) {
-  let normalizedRoute = route
-
-  // Handle root route
-  if (normalizedRoute === '/' || normalizedRoute === '') {
-    return join(distDir, 'index.html')
-  }
-
-  // Remove leading slash
-  if (normalizedRoute.startsWith('/')) {
-    normalizedRoute = normalizedRoute.slice(1)
-  }
-
-  // Create directory structure: /about -> /about/index.html
-  return join(distDir, normalizedRoute, 'index.html')
-}
-
-/**
- * Escape HTML special characters
- */
-function escapeHtml(str) {
-  if (!str) return ''
-  return String(str)
-    .replace(/&/g, '&amp;')
-    .replace(/</g, '&lt;')
-    .replace(/>/g, '&gt;')
-    .replace(/"/g, '&quot;')
-    .replace(/'/g, '&#39;')
-}
-
 export default prerenderSite

package/src/site/config.js

@@ -24,6 +24,7 @@ import { existsSync, readFileSync } from 'node:fs'
 import { resolve, dirname, join } from 'node:path'
 import yaml from 'js-yaml'
 import { generateEntryPoint, shouldRegenerateForFile } from '../generate-entry.js'
+import { importMapPlugin } from '../import-map-plugin.js'
 
 /**
  * Normalize a base path for Vite compatibility
@@ -343,105 +344,73 @@ export async function defineSiteConfig(options = {}) {
 
   if (noopFoundationPlugin) plugins.push(noopFoundationPlugin)
 
-  // Import map plugin for runtime mode production builds
+  // Import map plugin for runtime mode production builds.
   // Emits re-export modules for each externalized package (react, @uniweb/core, etc.)
-  // so the browser can resolve bare specifiers in the dynamically-imported foundation
-  const IMPORT_MAP_EXTERNALS = [
-    'react',
-    'react-dom',
-    'react/jsx-runtime',
-    'react/jsx-dev-runtime',
-    '@uniweb/core'
-  ]
-  const IMPORT_MAP_PREFIX = '\0importmap:'
-
-  const importMapPlugin = needsImportMap ? (() => {
-    let isBuild = false
-
-    return {
-      name: 'uniweb:import-map',
-
-      configResolved(config) {
-        isBuild = config.command === 'build'
-      },
-
-      resolveId(id, importer) {
-        if (id.startsWith(IMPORT_MAP_PREFIX)) return id
-        // Bare specifiers inside our virtual modules (e.g. '@uniweb/core' re-exported
-        // from '\0importmap:@uniweb/core') can't be resolved by Rollup because virtual
-        // modules have no filesystem context. Resolve from the foundation directory where
-        // @uniweb/core is a direct dependency (the site may not have it under pnpm strict).
-        if (importer?.startsWith(IMPORT_MAP_PREFIX) && IMPORT_MAP_EXTERNALS.includes(id)) {
-          const resolveFrom = foundationInfo.path
-            ? resolve(foundationInfo.path, 'package.json')
-            : resolve(siteRoot, 'main.js')
-          return this.resolve(id, resolveFrom, { skipSelf: true })
-        }
-      },
+  // so the browser can resolve bare specifiers in the dynamically-imported foundation.
+  // In dev mode, Vite's transformRequest() handles bare specifier resolution instead.
+  if (needsImportMap) {
+    plugins.push(importMapPlugin({
+      basePath: base || '/',
+      // Under pnpm strict mode, the site may not have @uniweb/core in its own
+      // node_modules. Resolve from the foundation directory where it's a direct dep.
+      resolveFrom: foundationInfo.path
+        ? resolve(foundationInfo.path, 'package.json')
+        : resolve(siteRoot, 'main.js'),
+    }))
+  }
 
-      async load(id) {
-        if (!id.startsWith(IMPORT_MAP_PREFIX)) return
-        const pkg = id.slice(IMPORT_MAP_PREFIX.length)
-        // Dynamically discover exports at build time by importing the package.
-        // We generate explicit named re-exports (not `export *`) because CJS
-        // packages like React only expose a default via `export *`, losing
-        // individual named exports (useState, jsx, etc.) that foundations need.
-        try {
-          const mod = await import(pkg)
-          const names = Object.keys(mod).filter(k => k !== '__esModule')
-          const hasDefault = 'default' in mod
-          const named = names.filter(k => k !== 'default')
-          const lines = []
-          if (named.length) {
-            lines.push(`export { ${named.join(', ')} } from '${pkg}'`)
-          }
-          if (hasDefault) {
-            lines.push(`export { default } from '${pkg}'`)
+  // Preload hints for runtime-loaded foundations and extensions.
+  // In runtime mode, foundation JS is loaded via import() and CSS is injected
+  // dynamically in JavaScript — the browser doesn't discover them until JS executes.
+  // These <link> tags let the browser start fetching during HTML parsing.
+  // Shell mode is excluded: URLs come from __DATA__ at serve time (unicloud handles it).
+  if (isRuntimeMode && !isShellMode) {
+    plugins.push({
+      name: 'uniweb:foundation-preload',
+      transformIndexHtml: {
+        order: 'post',
+        handler() {
+          const tags = []
+
+          // Foundation JS modulepreload
+          if (foundationConfig.url) {
+            tags.push({
+              tag: 'link',
+              attrs: { rel: 'modulepreload', href: foundationConfig.url },
+              injectTo: 'head',
+            })
           }
-          return lines.join('\n') || `export {}`
-        } catch {
-          // Fallback: generic re-export (may not preserve named exports for CJS)
-          return `export * from '${pkg}'`
-        }
-      },
 
-      // Emit deterministic chunks for each external (production only).
-      // preserveSignature: 'exports-only' tells Rollup to preserve the original
-      // export names (useState, jsx, etc.) instead of mangling them.
-      // In dev mode, Vite's transformRequest() resolves bare specifiers instead.
-      buildStart() {
-        if (!isBuild) return
-        for (const ext of IMPORT_MAP_EXTERNALS) {
-          this.emitFile({
-            type: 'chunk',
-            id: `${IMPORT_MAP_PREFIX}${ext}`,
-            fileName: `_importmap/${ext.replace(/\//g, '-')}.js`,
-            preserveSignature: 'exports-only'
-          })
-        }
-      },
+          // Foundation CSS — injected as a real <link> so the browser fetches it
+          // during HTML parsing instead of waiting for loadFoundationCSS() in JS.
+          // The runtime's dynamic <link> deduplicates (same URL, already cached).
+          if (foundationConfig.cssUrl) {
+            tags.push({
+              tag: 'link',
+              attrs: { rel: 'stylesheet', href: foundationConfig.cssUrl },
+              injectTo: 'head',
+            })
+          }
 
-      // Inject the import map into the HTML (production only).
-      // In dev mode, Vite's transformRequest() handles bare specifier resolution.
-      transformIndexHtml: {
-        order: 'pre',
-        handler(html) {
-          if (!isBuild) return html
-          const basePath = base || '/'
-          const imports = {}
-          for (const ext of IMPORT_MAP_EXTERNALS) {
-            imports[ext] = `${basePath}_importmap/${ext.replace(/\//g, '-')}.js`
+          // Extension JS modulepreload (CSS left to runtime — we can't reliably
+          // derive CSS URLs for all extension formats)
+          const extensions = siteConfig.extensions || []
+          for (const ext of extensions) {
+            const url = typeof ext === 'string' ? ext : ext?.url
+            if (url) {
+              tags.push({
+                tag: 'link',
+                attrs: { rel: 'modulepreload', href: url },
+                injectTo: 'head',
+              })
+            }
           }
-          const importMap = JSON.stringify({ imports }, null, 2)
-          const script = `    <script type="importmap">\n${importMap}\n    </script>\n`
-          // Import map must appear before any module scripts
-          return html.replace('<head>', '<head>\n' + script)
-        }
-      }
-    }
-  })() : null
 
-  if (importMapPlugin) plugins.push(importMapPlugin)
+          return tags
+        },
+      },
+    })
+  }
 
   // Build foundation config for runtime
   const foundationConfig = {