@uniweb/build 0.6.4 → 0.6.6

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@uniweb/build",
-  "version": "0.6.4",
+  "version": "0.6.6",
   "description": "Build tooling for the Uniweb Component Web Platform",
   "type": "module",
   "exports": {
@@ -51,7 +51,7 @@
   },
   "optionalDependencies": {
     "@uniweb/schemas": "0.2.1",
-    "@uniweb/runtime": "0.5.13",
+    "@uniweb/runtime": "0.5.15",
     "@uniweb/content-reader": "1.1.2"
   },
   "peerDependencies": {
@@ -61,7 +61,7 @@
     "@tailwindcss/vite": "^4.0.0",
     "@vitejs/plugin-react": "^4.0.0 || ^5.0.0",
     "vite-plugin-svgr": "^4.0.0",
-    "@uniweb/core": "0.4.2"
+    "@uniweb/core": "0.4.4"
   },
   "peerDependenciesMeta": {
     "vite": {

package/src/dev/plugin.js

@@ -63,20 +63,28 @@ export function foundationDevPlugin(options = {}) {
     console.log(`[foundation] Building ${name}...`)
 
     try {
-      // Use Vite's native config loading by specifying configFile
       const configPath = join(resolvedFoundationPath, 'vite.config.js')
 
-      // Build using Vite with the foundation's own config file
-      await build({
-        root: resolvedFoundationPath,
-        configFile: existsSync(configPath) ? configPath : false,
-        logLevel: 'warn',
-        build: {
-          outDir: 'dist',
-          emptyOutDir: true,
-          watch: null // Don't use Vite's watch, we handle it ourselves
-        }
-      })
+      // Temporarily change cwd to foundation directory so that
+      // defineFoundationConfig() resolves the entry path correctly
+      // (it uses process.cwd() as the foundation root)
+      const originalCwd = process.cwd()
+      process.chdir(resolvedFoundationPath)
+
+      try {
+        await build({
+          root: resolvedFoundationPath,
+          configFile: existsSync(configPath) ? configPath : false,
+          logLevel: 'warn',
+          build: {
+            outDir: 'dist',
+            emptyOutDir: true,
+            watch: null // Don't use Vite's watch, we handle it ourselves
+          }
+        })
+      } finally {
+        process.chdir(originalCwd)
+      }
 
       lastBuildTime = Date.now()
       console.log(`[foundation] Built ${name} in ${lastBuildTime - startTime}ms`)
@@ -173,7 +181,10 @@ export function foundationDevPlugin(options = {}) {
 
         try {
           watcher = watch(srcPath, { recursive: true }, (eventType, filename) => {
-            // Ignore non-source files
+            // Ignore generated files (build output triggers entry regeneration)
+            if (filename && filename.includes('_entry.generated')) return
+
+            // Only rebuild for source file changes
             if (
               filename &&
               (filename.endsWith('.js') ||

package/src/i18n/extract.js

@@ -41,7 +41,7 @@ export function extractTranslatableContent(siteContent) {
   for (const layoutKey of ['header', 'footer', 'left', 'right']) {
     const layoutPage = siteContent[layoutKey]
     if (layoutPage?.sections) {
-      const pageRoute = layoutPage.route || `/@${layoutKey}`
+      const pageRoute = layoutPage.route || `/layout/${layoutKey}`
       for (const section of layoutPage.sections) {
         extractFromSection(section, pageRoute, units)
       }

package/src/i18n/merge.js

@@ -80,7 +80,7 @@ function mergeTranslationsSync(siteContent, translations, fallbackToSource) {
   for (const layoutKey of ['header', 'footer', 'left', 'right']) {
     const layoutPage = translated[layoutKey]
     if (layoutPage?.sections) {
-      const pageRoute = layoutPage.route || `/@${layoutKey}`
+      const pageRoute = layoutPage.route || `/layout/${layoutKey}`
       for (const section of layoutPage.sections) {
         translateSectionSync(section, pageRoute, translations, fallbackToSource)
       }
@@ -132,8 +132,8 @@ async function mergeTranslationsAsync(siteContent, translations, options) {
   for (const layoutKey of ['header', 'footer', 'left', 'right']) {
     const layoutPage = translated[layoutKey]
     if (layoutPage?.sections) {
-      // Ensure route is set for context matching (extract uses /@header, etc.)
-      if (!layoutPage.route) layoutPage.route = `/@${layoutKey}`
+      // Ensure route is set for context matching
+      if (!layoutPage.route) layoutPage.route = `/layout/${layoutKey}`
       for (const section of layoutPage.sections) {
         await translateSectionAsync(section, layoutPage, translations, {
           fallbackToSource,

package/src/prerender.js

@@ -15,6 +15,37 @@ import { createRequire } from 'node:module'
 import { pathToFileURL } from 'node:url'
 import { executeFetch, mergeDataIntoContent, singularize } from './site/data-fetcher.js'
 
+/**
+ * Resolve an extension URL to a filesystem path for prerender.
+ * Browser URLs like "/effects/foundation.js" need mapping to local files.
+ *
+ * Resolution order:
+ * 1. dist directory (post-build copy target, e.g., site/dist/effects/foundation.js)
+ * 2. Project root with dist subdir (dev layout, e.g., project/effects/dist/foundation.js)
+ * 3. Original URL (absolute or remote — let import() handle it)
+ */
+function resolveExtensionPath(url, distDir, projectRoot) {
+  // Only resolve URLs that look like root-relative paths
+  if (url.startsWith('/')) {
+    // Try dist directory first (production: files copied to site/dist/)
+    const distPath = join(distDir, url)
+    if (existsSync(distPath)) return distPath
+
+    // Try project root with dist subdir (dev layout: effects/dist/foundation.js)
+    // "/effects/foundation.js" → "effects/dist/foundation.js"
+    const parts = url.slice(1).split('/')
+    if (parts.length >= 2) {
+      const pkgName = parts[0]
+      const rest = parts.slice(1).join('/')
+      const devPath = join(projectRoot, pkgName, 'dist', rest)
+      if (existsSync(devPath)) return devPath
+    }
+  }
+
+  // Return as-is for absolute paths or remote URLs
+  return url
+}
+
 // Lazily loaded dependencies
 let React, renderToString, createUniweb
 let preparePropsSSR, getComponentMetaSSR
@@ -714,6 +745,24 @@ export async function prerenderSite(siteDir, options = {}) {
 
     uniweb.setFoundation(foundation)
 
+    // Load extensions (secondary foundations via URL)
+    const extensions = siteContent.config?.extensions
+    if (extensions?.length) {
+      onProgress(`Loading ${extensions.length} extension(s)...`)
+      const projectRoot = join(siteDir, '..')
+      for (const ext of extensions) {
+        try {
+          const url = typeof ext === 'string' ? ext : ext.url
+          const extPath = resolveExtensionPath(url, distDir, projectRoot)
+          const extModule = await import(pathToFileURL(extPath).href)
+          uniweb.registerExtension(extModule)
+          onProgress(`  Extension loaded: ${url}`)
+        } catch (err) {
+          onProgress(`  Warning: Extension failed to load: ${ext} (${err.message})`)
+        }
+      }
+    }
+
     // 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) {

package/src/search/extract.js

@@ -41,11 +41,6 @@ export function extractSearchContent(siteContent, options = {}) {
       continue
     }
 
-    // Skip special pages (header, footer, etc.)
-    if (pageRoute.startsWith('/@')) {
-      continue
-    }
-
     // Skip pages marked as noindex
     if (page.seo?.noindex) {
       continue

package/src/site/collection-processor.js

@@ -26,7 +26,7 @@
  */
 
 import { readFile, readdir, stat, writeFile, mkdir, copyFile } from 'node:fs/promises'
-import { join, basename, extname, dirname, relative } from 'node:path'
+import { join, basename, extname, dirname, relative, resolve } from 'node:path'
 import { existsSync } from 'node:fs'
 import yaml from 'js-yaml'
 import { applyFilter, applySort } from './data-fetcher.js'
@@ -421,8 +421,9 @@ async function processContentItem(dir, filename, config, siteRoot) {
  * @param {Object} config - Parsed collection config
  * @returns {Promise<Array>} Array of processed items
  */
-async function collectItems(siteDir, config) {
-  const collectionDir = join(siteDir, config.path)
+async function collectItems(siteDir, config, collectionsBase) {
+  const base = collectionsBase || siteDir
+  const collectionDir = resolve(base, config.path)
 
   // Check if collection directory exists
   if (!existsSync(collectionDir)) {
@@ -496,7 +497,7 @@ async function collectItems(siteDir, config) {
  * })
  * // { articles: [...], products: [...] }
  */
-export async function processCollections(siteDir, collectionsConfig) {
+export async function processCollections(siteDir, collectionsConfig, collectionsBase) {
   if (!collectionsConfig || typeof collectionsConfig !== 'object') {
     return {}
   }
@@ -505,7 +506,7 @@ export async function processCollections(siteDir, collectionsConfig) {
 
   for (const [name, config] of Object.entries(collectionsConfig)) {
     const parsed = parseCollectionConfig(name, config)
-    const items = await collectItems(siteDir, parsed)
+    const items = await collectItems(siteDir, parsed, collectionsBase)
     results[name] = items
     console.log(`[collection-processor] Processed ${name}: ${items.length} items`)
   }

package/src/site/config.js

@@ -175,12 +175,15 @@ export async function defineSiteConfig(options = {}) {
   const rawBase = baseOption || process.env.UNIWEB_BASE || siteConfig.base
   const base = rawBase ? normalizeBasePath(String(rawBase)) : undefined
 
+  // Check for shell mode (no embedded content, for dynamic backend)
+  const isShellMode = process.env.UNIWEB_SHELL === 'true'
+
   // Detect foundation type
   const foundationInfo = detectFoundationType(siteConfig.foundation, siteRoot)
 
-  // Check for runtime mode (env variable or URL-based foundation)
+  // Check for runtime mode (env variable, URL-based foundation, or shell mode)
   const isRuntimeMode =
-    process.env.VITE_FOUNDATION_MODE === 'runtime' || foundationInfo.type === 'url'
+    isShellMode || process.env.VITE_FOUNDATION_MODE === 'runtime' || foundationInfo.type === 'url'
 
   // Dynamic imports for optional peer dependencies
   // These are imported dynamically to avoid requiring them when not needed
@@ -267,7 +270,8 @@ export async function defineSiteConfig(options = {}) {
     // Site content collection and injection
     siteContentPlugin({
       sitePath: './',
-      inject: true,
+      inject: !isShellMode,
+      shell: isShellMode,
       seo,
       assets,
       search,
@@ -291,11 +295,122 @@ export async function defineSiteConfig(options = {}) {
   // Build resolve.alias configuration
   const alias = {}
 
-  // Set up #foundation alias for bundled mode
-  if (!isRuntimeMode && foundationInfo.type !== 'url') {
+  if (isRuntimeMode) {
+    // In runtime mode, foundation is loaded via URL at runtime.
+    // main.js still imports #foundation so Vite can resolve it,
+    // but start() ignores the import and uses the URL instead.
+    // Point #foundation at a virtual noop module.
+    alias['#foundation'] = '\0__foundation-noop__'
+  } else if (foundationInfo.type !== 'url') {
+    // Bundled mode: #foundation points to the actual package
     alias['#foundation'] = foundationInfo.name
   }
 
+  // Virtual module plugin for the noop foundation stub
+  const noopFoundationPlugin = isRuntimeMode ? {
+    name: 'uniweb:foundation-noop',
+    resolveId(id) {
+      if (id === '\0__foundation-noop__' || id.startsWith('\0__foundation-noop__')) return id
+    },
+    load(id) {
+      if (id === '\0__foundation-noop__') return 'export default {}'
+      // Handle #foundation/styles → noop CSS
+      if (id.startsWith('\0__foundation-noop__')) return ''
+    }
+  } : null
+
+  if (noopFoundationPlugin) plugins.push(noopFoundationPlugin)
+
+  // 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 = isRuntimeMode ? (() => {
+    let isBuild = false
+
+    return {
+      name: 'uniweb:import-map',
+
+      configResolved(config) {
+        isBuild = config.command === 'build'
+      },
+
+      resolveId(id) {
+        if (id.startsWith(IMPORT_MAP_PREFIX)) return id
+      },
+
+      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}'`)
+          }
+          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'
+          })
+        }
+      },
+
+      // 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`
+          }
+          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)
+
   // Build foundation config for runtime
   const foundationConfig = {
     mode: isRuntimeMode ? 'runtime' : 'bundled',
@@ -311,7 +426,7 @@ export async function defineSiteConfig(options = {}) {
     plugins,
 
     define: {
-      __FOUNDATION_CONFIG__: JSON.stringify(foundationConfig)
+      __FOUNDATION_CONFIG__: isShellMode ? 'null' : JSON.stringify(foundationConfig)
     },
 
     resolve: {
@@ -328,7 +443,21 @@ export async function defineSiteConfig(options = {}) {
     server: {
       fs: {
         // Allow parent directory for foundation sibling access
-        allow: ['..']
+        // Plus any external content paths from site.yml paths: group
+        allow: (() => {
+          const allowed = ['..']
+          const parentDir = resolve(siteRoot, '..')
+          const paths = siteConfig.paths || {}
+          for (const key of ['pages', 'layout', 'collections']) {
+            if (paths[key]) {
+              const resolved = resolve(siteRoot, paths[key])
+              if (!resolved.startsWith(parentDir)) {
+                allowed.push(resolved)
+              }
+            }
+          }
+          return allowed
+        })()
       },
       ...(siteConfig.build?.port && { port: siteConfig.build.port }),
       ...serverOverrides

package/src/site/content-collector.js

@@ -1,11 +1,12 @@
 /**
  * Content Collector
  *
- * Collects site content from a pages/ directory structure:
+ * Collects site content from a site directory structure:
  * - site.yml: Site configuration
  * - pages/: Directory of page folders
  *   - page.yml: Page metadata
  *   - *.md: Section content with YAML frontmatter
+ * - layout/: Layout panel folders (header, footer, left, right)
  *
  * Section frontmatter reserved properties:
  * - type: Component type (e.g., "Hero", "Features")
@@ -23,7 +24,7 @@
  */
 
 import { readFile, readdir, stat } from 'node:fs/promises'
-import { join, parse } from 'node:path'
+import { join, parse, resolve } from 'node:path'
 import { existsSync } from 'node:fs'
 import yaml from 'js-yaml'
 import { collectSectionAssets, mergeAssetCollections } from './assets.js'
@@ -184,6 +185,33 @@ function isMarkdownFile(filename) {
   return filename.endsWith('.md') && !filename.startsWith('_')
 }
 
+/**
+ * Read folder configuration, determining content mode from config file presence.
+ *
+ * - folder.yml present → pages mode (md files are child pages)
+ * - page.yml present → sections mode (md files are sections of this page)
+ * - Neither → inherit mode from parent
+ *
+ * @param {string} dirPath - Directory path
+ * @param {string} inheritedMode - Mode inherited from parent ('sections' or 'pages')
+ * @returns {Promise<{config: Object, mode: string, source: string}>}
+ */
+async function readFolderConfig(dirPath, inheritedMode) {
+  const folderYml = await readYamlFile(join(dirPath, 'folder.yml'))
+  if (Object.keys(folderYml).length > 0) {
+    return { config: folderYml, mode: 'pages', source: 'folder.yml' }
+  }
+  const pageYml = await readYamlFile(join(dirPath, 'page.yml'))
+  if (Object.keys(pageYml).length > 0) {
+    return { config: pageYml, mode: 'sections', source: 'page.yml' }
+  }
+  // Check for empty folder.yml (presence signals pages mode even if empty)
+  if (existsSync(join(dirPath, 'folder.yml'))) {
+    return { config: {}, mode: 'pages', source: 'folder.yml' }
+  }
+  return { config: {}, mode: inheritedMode, source: 'inherited' }
+}
+
 /**
  * Parse numeric prefix from filename (e.g., "1-hero.md" → { prefix: "1", name: "hero" })
  * Supports:
@@ -225,6 +253,89 @@ function compareFilenames(a, b) {
   return 0
 }
 
+/**
+ * Apply non-strict ordering to a list of items.
+ * Listed items appear first in array order, then unlisted items in their existing order.
+ *
+ * Unlike strict arrays (pages: [...], sections: [...]) which hide unlisted items,
+ * this preserves all items — it only affects order.
+ *
+ * @param {Array} items - Items with a .name property
+ * @param {Array<string>} orderArray - Names in desired order
+ * @returns {Array} Reordered items (all items preserved)
+ */
+function applyNonStrictOrder(items, orderArray) {
+  if (!Array.isArray(orderArray) || orderArray.length === 0) return items
+  const orderMap = new Map(orderArray.map((name, i) => [name, i]))
+  const listed = items.filter(i => orderMap.has(i.name))
+    .sort((a, b) => orderMap.get(a.name) - orderMap.get(b.name))
+  const unlisted = items.filter(i => !orderMap.has(i.name))
+  return [...listed, ...unlisted]
+}
+
+/**
+ * Process a markdown file as a standalone page (pages mode).
+ * Creates a page with a single section from the markdown content.
+ *
+ * @param {string} filePath - Path to markdown file
+ * @param {string} fileName - Filename (e.g., "getting-started.md")
+ * @param {string} siteRoot - Site root directory for asset resolution
+ * @param {string} parentRoute - Parent route (e.g., '/docs')
+ * @returns {Promise<Object>} Page data with assets manifest
+ */
+async function processFileAsPage(filePath, fileName, siteRoot, parentRoute) {
+  const { name } = parse(fileName)
+  const { prefix, name: stableName } = parseNumericPrefix(name)
+  const pageName = stableName || name
+  const route = parentRoute === '/' ? `/${pageName}` : `${parentRoute}/${pageName}`
+
+  // Process the markdown as a single section
+  const { section, assetCollection, iconCollection } = await processMarkdownFile(
+    filePath, '1', siteRoot, pageName
+  )
+
+  const fileStat = await stat(filePath)
+
+  return {
+    page: {
+      route,
+      sourcePath: null,
+      id: null,
+      isIndex: false,
+      title: pageName,
+      description: '',
+      label: null,
+      lastModified: fileStat.mtime?.toISOString() || null,
+      isDynamic: false,
+      paramName: null,
+      parentSchema: null,
+      version: null,
+      versionMeta: null,
+      versionScope: null,
+      hidden: false,
+      hideInHeader: false,
+      hideInFooter: false,
+      layout: {
+        header: true,
+        footer: true,
+        leftPanel: true,
+        rightPanel: true
+      },
+      seo: {
+        noindex: false,
+        image: null,
+        changefreq: null,
+        priority: null
+      },
+      fetch: null,
+      sections: [section],
+      order: prefix ? parseFloat(prefix) : undefined
+    },
+    assetCollection,
+    iconCollection
+  }
+}
+
 /**
  * Process a markdown file into a section
  *
@@ -502,10 +613,7 @@ async function processPage(pagePath, pageName, siteRoot, { isIndex = false, pare
 
   // First, calculate the folder-based route (what the route would be without index handling)
   let folderRoute
-  if (pageName.startsWith('@')) {
-    // Special pages (layout areas) keep their @ prefix
-    folderRoute = parentRoute === '/' ? `/@${pageName.slice(1)}` : `${parentRoute}/@${pageName.slice(1)}`
-  } else if (isDynamic) {
+  if (isDynamic) {
     // Dynamic routes: /blog/[slug] → /blog/:slug (for route matching)
     folderRoute = parentRoute === '/' ? `/:${paramName}` : `${parentRoute}/:${paramName}`
   } else {
@@ -631,12 +739,13 @@ function determineIndexPage(orderConfig, availableFolders) {
  * @param {string} dirPath - Directory to scan
  * @param {string} parentRoute - Parent route (e.g., '/' or '/docs')
  * @param {string} siteRoot - Site root directory for asset resolution
- * @param {Object} orderConfig - { pages: [...], index: 'name' } from parent's config
+ * @param {Object} orderConfig - { pages: [...], index: 'name', order: [...] } from parent's config
  * @param {Object} parentFetch - Parent page's fetch config (for dynamic child routes)
  * @param {Object} versionContext - Version context from parent { version, versionMeta }
- * @returns {Promise<Object>} { pages, assetCollection, iconCollection, header, footer, left, right, notFound, versionedScopes }
+ * @param {string} contentMode - 'sections' (default) or 'pages' (md files are child pages)
+ * @returns {Promise<Object>} { pages, assetCollection, iconCollection, notFound, versionedScopes }
  */
-async function collectPagesRecursive(dirPath, parentRoute, siteRoot, orderConfig = {}, parentFetch = null, versionContext = null) {
+async function collectPagesRecursive(dirPath, parentRoute, siteRoot, orderConfig = {}, parentFetch = null, versionContext = null, contentMode = 'sections') {
   const entries = await readdir(dirPath)
   const pages = []
   let assetCollection = {
@@ -648,30 +757,31 @@ async function collectPagesRecursive(dirPath, parentRoute, siteRoot, orderConfig
     icons: new Set(),
     bySource: new Map()
   }
-  let header = null
-  let footer = null
-  let left = null
-  let right = null
   let notFound = null
   const versionedScopes = new Map() // scope route → versionMeta
 
-  // First pass: discover all page folders and read their order values
+  // First pass: discover all page folders and read their config
   const pageFolders = []
   for (const entry of entries) {
     const entryPath = join(dirPath, entry)
     const stats = await stat(entryPath)
     if (!stats.isDirectory()) continue
 
-    // Read page.yml to get order and child page config
-    const pageConfig = await readYamlFile(join(entryPath, 'page.yml'))
+    // Read folder.yml or page.yml to determine mode and get config
+    const { config: dirConfig, mode: dirMode } = await readFolderConfig(entryPath, contentMode)
+    const numericOrder = typeof dirConfig.order === 'number' ? dirConfig.order : undefined
+    const childOrderArray = Array.isArray(dirConfig.order) ? dirConfig.order : undefined
+
     pageFolders.push({
       name: entry,
       path: entryPath,
-      order: pageConfig.order,
-      pageConfig,
+      order: numericOrder,
+      dirConfig,
+      dirMode,
       childOrderConfig: {
-        pages: pageConfig.pages,
-        index: pageConfig.index
+        pages: dirConfig.pages,
+        index: dirConfig.index,
+        order: childOrderArray
       }
     })
   }
@@ -685,67 +795,46 @@ async function collectPagesRecursive(dirPath, parentRoute, siteRoot, orderConfig
     return a.name.localeCompare(b.name)
   })
 
+  // Apply non-strict order from parent config (if present)
+  const orderedFolders = applyNonStrictOrder(pageFolders, orderConfig?.order)
+
   // Check if this directory contains version folders (versioned section)
-  const folderNames = pageFolders.map(f => f.name)
+  const folderNames = orderedFolders.map(f => f.name)
   const detectedVersions = detectVersions(folderNames)
 
-  // If versioned section, handle version folders specially
+  // If versioned section, handle version folders specially (always sections mode)
   if (detectedVersions && !versionContext) {
-    // Read parent page.yml for version metadata
     const parentConfig = await readYamlFile(join(dirPath, 'page.yml'))
     const versionMeta = buildVersionMetadata(detectedVersions, parentConfig)
-
-    // Record this versioned scope
     versionedScopes.set(parentRoute, versionMeta)
 
-    // Process version folders
-    for (const folder of pageFolders) {
-      const { name: entry, path: entryPath, childOrderConfig, pageConfig } = folder
+    for (const folder of orderedFolders) {
+      const { name: entry, path: entryPath, childOrderConfig } = folder
 
       if (isVersionFolder(entry)) {
-        // This is a version folder
         const versionInfo = versionMeta.versions.find(v => v.id === entry)
         const isLatest = versionInfo?.latest || false
-
-        // For latest version, use parent route directly
-        // For other versions, add version prefix to route
-        // Handle root scope specially to avoid double slash (//v1 → /v1)
         const versionRoute = isLatest
           ? parentRoute
           : parentRoute === '/'
             ? `/${entry}`
             : `${parentRoute}/${entry}`
 
-        // Recurse into version folder with version context
         const subResult = await collectPagesRecursive(
-          entryPath,
-          versionRoute,
-          siteRoot,
-          childOrderConfig,
-          parentFetch,
-          {
-            version: versionInfo,
-            versionMeta,
-            scope: parentRoute // The route where versioning is scoped
-          }
+          entryPath, versionRoute, siteRoot, childOrderConfig, parentFetch,
+          { version: versionInfo, versionMeta, scope: parentRoute }
         )
 
         pages.push(...subResult.pages)
         assetCollection = mergeAssetCollections(assetCollection, subResult.assetCollection)
         iconCollection = mergeIconCollections(iconCollection, subResult.iconCollection)
-        // Merge any nested versioned scopes (shouldn't happen often, but possible)
         for (const [scope, meta] of subResult.versionedScopes) {
           versionedScopes.set(scope, meta)
         }
-      } else if (!entry.startsWith('@')) {
-        // Non-version, non-special folders in a versioned section
-        // These could be shared across versions - process normally
+      } else {
         const result = await processPage(entryPath, entry, siteRoot, {
-          isIndex: false,
-          parentRoute,
-          parentFetch
+          isIndex: false, parentRoute, parentFetch
         })
-
         if (result) {
           pages.push(result.page)
           assetCollection = mergeAssetCollections(assetCollection, result.assetCollection)
@@ -754,83 +843,238 @@ async function collectPagesRecursive(dirPath, parentRoute, siteRoot, orderConfig
       }
     }
 
-    // Return early - we've handled all children
-    return { pages, assetCollection, iconCollection, header, footer, left, right, notFound, versionedScopes }
+    return { pages, assetCollection, iconCollection, notFound, versionedScopes }
   }
 
-  // Determine which page is the index for this level
-  // A directory with its own .md content is a real page, not a container —
-  // never promote a child as index, even if explicit config says so
-  // (that config is likely a leftover from before the directory had content)
-  const regularFolders = pageFolders.filter(f => !f.name.startsWith('@'))
-  const hasExplicitOrder = orderConfig?.index || (Array.isArray(orderConfig?.pages) && orderConfig.pages.length > 0)
-  const hasMdContent = entries.some(e => isMarkdownFile(e))
-  const indexPageName = hasMdContent ? null : determineIndexPage(orderConfig, regularFolders)
+  // --- Pages mode: .md files are child pages ---
+  if (contentMode === 'pages') {
+    // Collect and process .md files as individual pages
+    const mdFiles = entries.filter(isMarkdownFile).sort(compareFilenames)
+    const mdPageItems = []
 
-  // Second pass: process each page folder
-  for (const folder of pageFolders) {
-    const { name: entry, path: entryPath, childOrderConfig } = folder
-    const isIndex = entry === indexPageName
-    const isSpecial = entry.startsWith('@')
-
-    // Process this directory as a page
-    // Pass parentFetch so dynamic routes can inherit parent's data schema
-    const result = await processPage(entryPath, entry, siteRoot, {
-      isIndex: isIndex && !isSpecial,
-      parentRoute,
-      parentFetch,
-      versionContext
-    })
+    for (const file of mdFiles) {
+      const { name } = parse(file)
+      const { name: stableName } = parseNumericPrefix(name)
+      const result = await processFileAsPage(join(dirPath, file), file, siteRoot, parentRoute)
+      if (result) {
+        mdPageItems.push({ name: stableName || name, result })
+      }
+    }
+
+    // Apply non-strict order to md-file-pages
+    const orderedMdPages = applyNonStrictOrder(mdPageItems, orderConfig?.order)
 
-    if (result) {
+    // In pages mode, only promote an index if explicitly set via index: in folder.yml
+    // The container page itself owns the parent route — don't auto-promote children
+    const indexName = orderConfig?.index || null
+
+    // Add md-file-pages
+    for (const { name, result } of orderedMdPages) {
       const { page, assetCollection: pageAssets, iconCollection: pageIcons } = result
       assetCollection = mergeAssetCollections(assetCollection, pageAssets)
       iconCollection = mergeIconCollections(iconCollection, pageIcons)
 
-      // Handle special pages (layout areas and 404) - only at root level
-      if (parentRoute === '/') {
-        if (entry === '@header') {
-          header = page
-        } else if (entry === '@footer') {
-          footer = page
-        } else if (entry === '@left') {
-          left = page
-        } else if (entry === '@right') {
-          right = page
-        } else if (entry === '404') {
-          notFound = page
-        } else {
+      // Handle index: promote to parent route
+      if (name === indexName) {
+        page.isIndex = true
+        page.sourcePath = page.route
+        page.route = parentRoute
+      }
+
+      pages.push(page)
+    }
+
+    // Process subdirectories
+    for (const folder of orderedFolders) {
+      const { name: entry, path: entryPath, dirConfig, dirMode, childOrderConfig } = folder
+      const isIndex = entry === indexName
+
+      if (dirMode === 'sections') {
+        // Subdirectory overrides to sections mode — process normally
+        const result = await processPage(entryPath, entry, siteRoot, {
+          isIndex, parentRoute, parentFetch, versionContext
+        })
+
+        if (result) {
+          const { page, assetCollection: pageAssets, iconCollection: pageIcons } = result
+          assetCollection = mergeAssetCollections(assetCollection, pageAssets)
+          iconCollection = mergeIconCollections(iconCollection, pageIcons)
           pages.push(page)
+
+          // Recurse into subdirectories (sections mode)
+          const childParentRoute = isIndex ? parentRoute : page.route
+          const childFetch = page.fetch || parentFetch
+          const subResult = await collectPagesRecursive(entryPath, childParentRoute, siteRoot, childOrderConfig, childFetch, versionContext, 'sections')
+          pages.push(...subResult.pages)
+          assetCollection = mergeAssetCollections(assetCollection, subResult.assetCollection)
+          iconCollection = mergeIconCollections(iconCollection, subResult.iconCollection)
+          for (const [scope, meta] of subResult.versionedScopes) {
+            versionedScopes.set(scope, meta)
+          }
         }
       } else {
-        pages.push(page)
-      }
+        // Container directory in pages mode — create minimal page, recurse
+        const containerRoute = isIndex
+          ? parentRoute
+          : parentRoute === '/' ? `/${entry}` : `${parentRoute}/${entry}`
+
+        const containerPage = {
+          route: containerRoute,
+          sourcePath: isIndex ? (parentRoute === '/' ? `/${entry}` : `${parentRoute}/${entry}`) : null,
+          id: dirConfig.id || null,
+          isIndex,
+          title: dirConfig.title || entry,
+          description: dirConfig.description || '',
+          label: dirConfig.label || null,
+          lastModified: null,
+          isDynamic: false,
+          paramName: null,
+          parentSchema: null,
+          version: versionContext?.version || null,
+          versionMeta: versionContext?.versionMeta || null,
+          versionScope: versionContext?.scope || null,
+          hidden: dirConfig.hidden || false,
+          hideInHeader: dirConfig.hideInHeader || false,
+          hideInFooter: dirConfig.hideInFooter || false,
+          layout: {
+            header: dirConfig.layout?.header !== false,
+            footer: dirConfig.layout?.footer !== false,
+            leftPanel: dirConfig.layout?.leftPanel !== false,
+            rightPanel: dirConfig.layout?.rightPanel !== false
+          },
+          seo: {
+            noindex: dirConfig.seo?.noindex || false,
+            image: dirConfig.seo?.image || null,
+            changefreq: dirConfig.seo?.changefreq || null,
+            priority: dirConfig.seo?.priority || null
+          },
+          fetch: null,
+          sections: [],
+          order: typeof dirConfig.order === 'number' ? dirConfig.order : undefined
+        }
 
-      // Recursively process subdirectories (but not special @ directories)
-      if (!isSpecial) {
-        // The child route depends on whether this page is the index
-        // For explicit index (from site.yml `index:` or `pages:`), children use parentRoute
-        // since that's a true structural promotion. For auto-detected index, children use
-        // the page's original folder path so they nest correctly under it.
-        const childParentRoute = isIndex
-          ? (hasExplicitOrder ? parentRoute : (page.sourcePath || page.route))
-          : page.route
-        // Pass this page's fetch config to children (for dynamic routes that inherit parent data)
-        const childFetch = page.fetch || parentFetch
-        // Pass version context to children (maintains version scope)
-        const subResult = await collectPagesRecursive(entryPath, childParentRoute, siteRoot, childOrderConfig, childFetch, versionContext)
+        pages.push(containerPage)
+
+        // Recurse in pages mode
+        const subResult = await collectPagesRecursive(entryPath, containerRoute, siteRoot, childOrderConfig, parentFetch, versionContext, 'pages')
         pages.push(...subResult.pages)
         assetCollection = mergeAssetCollections(assetCollection, subResult.assetCollection)
         iconCollection = mergeIconCollections(iconCollection, subResult.iconCollection)
-        // Merge any versioned scopes from children
         for (const [scope, meta] of subResult.versionedScopes) {
           versionedScopes.set(scope, meta)
         }
       }
     }
+
+    return { pages, assetCollection, iconCollection, notFound, versionedScopes }
+  }
+
+  // --- Sections mode (default): existing behavior ---
+
+  // Determine which page is the index for this level
+  // A directory with its own .md content is a real page, not a container —
+  // never promote a child as index, even if explicit config says so
+  const hasExplicitOrder = orderConfig?.index || (Array.isArray(orderConfig?.pages) && orderConfig.pages.length > 0)
+  const hasMdContent = entries.some(e => isMarkdownFile(e))
+  const indexPageName = hasMdContent ? null : determineIndexPage(orderConfig, orderedFolders)
+
+  // Second pass: process each page folder
+  for (const folder of orderedFolders) {
+    const { name: entry, path: entryPath, dirConfig, dirMode, childOrderConfig } = folder
+    const isIndex = entry === indexPageName
+
+    if (dirMode === 'pages') {
+      // Child directory switches to pages mode (has folder.yml) —
+      // create container page with empty sections, recurse in pages mode
+      const containerRoute = isIndex
+        ? parentRoute
+        : parentRoute === '/' ? `/${entry}` : `${parentRoute}/${entry}`
+
+      const containerPage = {
+        route: containerRoute,
+        sourcePath: isIndex ? (parentRoute === '/' ? `/${entry}` : `${parentRoute}/${entry}`) : null,
+        id: dirConfig.id || null,
+        isIndex,
+        title: dirConfig.title || entry,
+        description: dirConfig.description || '',
+        label: dirConfig.label || null,
+        lastModified: null,
+        isDynamic: false,
+        paramName: null,
+        parentSchema: null,
+        version: versionContext?.version || null,
+        versionMeta: versionContext?.versionMeta || null,
+        versionScope: versionContext?.scope || null,
+        hidden: dirConfig.hidden || false,
+        hideInHeader: dirConfig.hideInHeader || false,
+        hideInFooter: dirConfig.hideInFooter || false,
+        layout: {
+          header: dirConfig.layout?.header !== false,
+          footer: dirConfig.layout?.footer !== false,
+          leftPanel: dirConfig.layout?.leftPanel !== false,
+          rightPanel: dirConfig.layout?.rightPanel !== false
+        },
+        seo: {
+          noindex: dirConfig.seo?.noindex || false,
+          image: dirConfig.seo?.image || null,
+          changefreq: dirConfig.seo?.changefreq || null,
+          priority: dirConfig.seo?.priority || null
+        },
+        fetch: null,
+        sections: [],
+        order: typeof dirConfig.order === 'number' ? dirConfig.order : undefined
+      }
+
+      if (parentRoute === '/' && entry === '404') {
+        notFound = containerPage
+      } else {
+        pages.push(containerPage)
+      }
+
+      const subResult = await collectPagesRecursive(entryPath, containerRoute, siteRoot, childOrderConfig, parentFetch, versionContext, 'pages')
+      pages.push(...subResult.pages)
+      assetCollection = mergeAssetCollections(assetCollection, subResult.assetCollection)
+      iconCollection = mergeIconCollections(iconCollection, subResult.iconCollection)
+      for (const [scope, meta] of subResult.versionedScopes) {
+        versionedScopes.set(scope, meta)
+      }
+    } else {
+      // Sections mode — process directory as a page (existing behavior)
+      const result = await processPage(entryPath, entry, siteRoot, {
+        isIndex, parentRoute, parentFetch, versionContext
+      })
+
+      if (result) {
+        const { page, assetCollection: pageAssets, iconCollection: pageIcons } = result
+        assetCollection = mergeAssetCollections(assetCollection, pageAssets)
+        iconCollection = mergeIconCollections(iconCollection, pageIcons)
+
+        // Handle 404 page - only at root level
+        if (parentRoute === '/' && entry === '404') {
+          notFound = page
+        } else {
+          pages.push(page)
+        }
+
+        // Recursively process subdirectories
+        {
+          const childParentRoute = isIndex
+            ? (hasExplicitOrder ? parentRoute : (page.sourcePath || page.route))
+            : page.route
+          const childFetch = page.fetch || parentFetch
+          const subResult = await collectPagesRecursive(entryPath, childParentRoute, siteRoot, childOrderConfig, childFetch, versionContext, dirMode)
+          pages.push(...subResult.pages)
+          assetCollection = mergeAssetCollections(assetCollection, subResult.assetCollection)
+          iconCollection = mergeIconCollections(iconCollection, subResult.iconCollection)
+          for (const [scope, meta] of subResult.versionedScopes) {
+            versionedScopes.set(scope, meta)
+          }
+        }
+      }
+    }
   }
 
-  return { pages, assetCollection, iconCollection, header, footer, left, right, notFound, versionedScopes }
+  return { pages, assetCollection, iconCollection, notFound, versionedScopes }
 }
 
 /**
@@ -863,6 +1107,43 @@ async function loadFoundationVars(foundationPath) {
   }
 }
 
+/**
+ * Collect layout panels from the layout/ directory
+ *
+ * Layout panels (header, footer, left, right) are persistent regions
+ * that appear on every page. They live in layout/ parallel to pages/.
+ *
+ * @param {string} layoutDir - Path to layout directory
+ * @param {string} siteRoot - Path to site root
+ * @returns {Promise<Object>} { header, footer, left, right }
+ */
+async function collectLayoutPanels(layoutDir, siteRoot) {
+  const result = { header: null, footer: null, left: null, right: null }
+
+  if (!existsSync(layoutDir)) return result
+
+  const knownPanels = ['header', 'footer', 'left', 'right']
+  const entries = await readdir(layoutDir)
+
+  for (const entry of entries) {
+    if (!knownPanels.includes(entry)) continue
+    const entryPath = join(layoutDir, entry)
+    const stats = await stat(entryPath)
+    if (!stats.isDirectory()) continue
+
+    const pageResult = await processPage(entryPath, entry, siteRoot, {
+      isIndex: false,
+      parentRoute: '/layout'
+    })
+
+    if (pageResult) {
+      result[entry] = pageResult.page
+    }
+  }
+
+  return result
+}
+
 /**
  * Collect all site content
  *
@@ -873,10 +1154,18 @@ async function loadFoundationVars(foundationPath) {
  */
 export async function collectSiteContent(sitePath, options = {}) {
   const { foundationPath } = options
-  const pagesPath = join(sitePath, 'pages')
 
   // Read site config and raw theme config
   const siteConfig = await readYamlFile(join(sitePath, 'site.yml'))
+
+  // Resolve content paths from site.yml paths: group, defaulting to standard locations
+  const pagesPath = siteConfig.paths?.pages
+    ? resolve(sitePath, siteConfig.paths.pages)
+    : join(sitePath, 'pages')
+
+  const layoutPath = siteConfig.paths?.layout
+    ? resolve(sitePath, siteConfig.paths.layout)
+    : join(sitePath, 'layout')
   const rawThemeConfig = await readYamlFile(join(sitePath, 'theme.yml'))
 
   // Load foundation vars and process theme
@@ -904,12 +1193,19 @@ export async function collectSiteContent(sitePath, options = {}) {
   // Extract page ordering config from site.yml
   const siteOrderConfig = {
     pages: siteConfig.pages,
-    index: siteConfig.index
+    index: siteConfig.index,
+    order: Array.isArray(siteConfig.order) ? siteConfig.order : undefined
   }
 
+  // Determine root content mode from folder.yml/page.yml presence in pages directory
+  const { mode: rootContentMode } = await readFolderConfig(pagesPath, 'sections')
+
+  // Collect layout panels from layout/ directory
+  const { header, footer, left, right } = await collectLayoutPanels(layoutPath, sitePath)
+
   // Recursively collect all pages
-  const { pages, assetCollection, iconCollection, header, footer, left, right, notFound, versionedScopes } =
-    await collectPagesRecursive(pagesPath, '/', sitePath, siteOrderConfig)
+  const { pages, assetCollection, iconCollection, notFound, versionedScopes } =
+    await collectPagesRecursive(pagesPath, '/', sitePath, siteOrderConfig, null, null, rootContentMode)
 
   // Deduplicate: remove content-less container pages whose route duplicates
   // a content-bearing page (e.g., a promoted index page)

package/src/site/plugin.js

@@ -338,6 +338,7 @@ export function siteContentPlugin(options = {}) {
     pagesDir = 'pages',
     variableName = '__SITE_CONTENT__',
     inject = true,
+    shell = false,
     filename = 'site-content.json',
     watch: shouldWatch = true,
     seo = {},
@@ -376,6 +377,10 @@ export function siteContentPlugin(options = {}) {
   let collectionTranslations = {} // Cache: { locale: collection translations }
   let localesDir = 'locales' // Default, updated from site config
   let collectionsConfig = null // Cached for watcher setup
+  let resolvedPagesPath = null // Resolved from site.yml pagesDir or default
+  let resolvedLayoutPath = null // Resolved from site.yml layoutDir or default
+  let resolvedCollectionsBase = null // Resolved from site.yml collectionsDir
+  let headHtml = '' // Contents of site/head.html for injection
 
   /**
    * Load translations for a specific locale
@@ -423,6 +428,18 @@ export function siteContentPlugin(options = {}) {
     }
   }
 
+  /**
+   * Read head.html from site root (if it exists)
+   */
+  async function loadHeadHtml() {
+    const headPath = resolve(resolvedSitePath, 'head.html')
+    try {
+      return await readFile(headPath, 'utf-8')
+    } catch {
+      return ''
+    }
+  }
+
   /**
    * Get available locales from locales directory
    */
@@ -486,21 +503,50 @@ export function siteContentPlugin(options = {}) {
           const earlyContent = await collectSiteContent(resolvedSitePath, { foundationPath })
           collectionsConfig = earlyContent.config?.collections
 
+          // Resolve content directory paths from site.yml paths: group
+          const paths = earlyContent?.config?.paths || {}
+          resolvedPagesPath = paths.pages
+            ? resolve(resolvedSitePath, paths.pages)
+            : resolve(resolvedSitePath, pagesDir)
+          resolvedLayoutPath = paths.layout
+            ? resolve(resolvedSitePath, paths.layout)
+            : resolve(resolvedSitePath, 'layout')
+          resolvedCollectionsBase = paths.collections
+            ? resolve(resolvedSitePath, paths.collections)
+            : null
+
           if (collectionsConfig) {
             console.log('[site-content] Processing content collections...')
-            const collections = await processCollections(resolvedSitePath, collectionsConfig)
+            const collections = await processCollections(resolvedSitePath, collectionsConfig, resolvedCollectionsBase)
             await writeCollectionFiles(resolvedSitePath, collections)
           }
         } catch (err) {
           console.warn('[site-content] Early collection processing failed:', err.message)
         }
       }
+
+      // In production, resolve content paths from site.yml directly
+      if (isProduction || !resolvedPagesPath) {
+        const { readSiteConfig } = await import('./config.js')
+        const cfg = readSiteConfig(resolvedSitePath)
+        const paths = cfg.paths || {}
+        resolvedPagesPath = paths.pages
+          ? resolve(resolvedSitePath, paths.pages)
+          : resolve(resolvedSitePath, pagesDir)
+        resolvedLayoutPath = paths.layout
+          ? resolve(resolvedSitePath, paths.layout)
+          : resolve(resolvedSitePath, 'layout')
+        resolvedCollectionsBase = paths.collections
+          ? resolve(resolvedSitePath, paths.collections)
+          : null
+      }
     },
 
     async buildStart() {
       // Collect content at build start
       try {
         siteContent = await collectSiteContent(resolvedSitePath, { foundationPath })
+        headHtml = await loadHeadHtml()
         console.log(`[site-content] Collected ${siteContent.pages?.length || 0} pages`)
 
         // Process content collections if defined in site.yml
@@ -508,7 +554,7 @@ export function siteContentPlugin(options = {}) {
         // In production, do it here
         if (isProduction && siteContent.config?.collections) {
           console.log('[site-content] Processing content collections...')
-          const collections = await processCollections(resolvedSitePath, siteContent.config.collections)
+          const collections = await processCollections(resolvedSitePath, siteContent.config.collections, resolvedCollectionsBase)
           await writeCollectionFiles(resolvedSitePath, collections)
         }
 
@@ -537,7 +583,6 @@ export function siteContentPlugin(options = {}) {
 
       // Watch for content changes in dev mode
       if (shouldWatch) {
-        const pagesPath = resolve(resolvedSitePath, pagesDir)
         const siteYmlPath = resolve(resolvedSitePath, 'site.yml')
         const themeYmlPath = resolve(resolvedSitePath, 'theme.yml')
 
@@ -549,6 +594,7 @@ export function siteContentPlugin(options = {}) {
             console.log('[site-content] Content changed, rebuilding...')
             try {
               siteContent = await collectSiteContent(resolvedSitePath, { foundationPath })
+              headHtml = await loadHeadHtml()
               // Execute fetches for the updated content
               await executeDevFetches(siteContent, resolvedSitePath)
               console.log(`[site-content] Rebuilt ${siteContent.pages?.length || 0} pages`)
@@ -571,7 +617,7 @@ export function siteContentPlugin(options = {}) {
               // Use collectionsConfig (cached from configResolved) or siteContent
               const collections = collectionsConfig || siteContent?.config?.collections
               if (collections) {
-                const processed = await processCollections(resolvedSitePath, collections)
+                const processed = await processCollections(resolvedSitePath, collections, resolvedCollectionsBase)
                 await writeCollectionFiles(resolvedSitePath, processed)
               }
               // Send full reload to client
@@ -585,12 +631,24 @@ export function siteContentPlugin(options = {}) {
         // Track all watchers for cleanup
         const watchers = []
 
-        // Watch pages directory
-        try {
-          watchers.push(watch(pagesPath, { recursive: true }, scheduleRebuild))
-          console.log(`[site-content] Watching ${pagesPath}`)
-        } catch (err) {
-          console.warn('[site-content] Could not watch pages directory:', err.message)
+        // Watch pages directory (resolved from site.yml pagesDir or default)
+        if (existsSync(resolvedPagesPath)) {
+          try {
+            watchers.push(watch(resolvedPagesPath, { recursive: true }, scheduleRebuild))
+            console.log(`[site-content] Watching ${resolvedPagesPath}`)
+          } catch (err) {
+            console.warn('[site-content] Could not watch pages directory:', err.message)
+          }
+        }
+
+        // Watch layout directory (resolved from site.yml layoutDir or default)
+        if (existsSync(resolvedLayoutPath)) {
+          try {
+            watchers.push(watch(resolvedLayoutPath, { recursive: true }, scheduleRebuild))
+            console.log(`[site-content] Watching ${resolvedLayoutPath}`)
+          } catch (err) {
+            console.warn('[site-content] Could not watch layout directory:', err.message)
+          }
         }
 
         // Watch site.yml
@@ -607,14 +665,23 @@ export function siteContentPlugin(options = {}) {
           // theme.yml may not exist, that's ok
         }
 
+        // Watch head.html
+        const headHtmlPath = resolve(resolvedSitePath, 'head.html')
+        try {
+          watchers.push(watch(headHtmlPath, scheduleRebuild))
+        } catch {
+          // head.html may not exist, that's ok
+        }
+
         // Watch content/ folder for collection changes
         // Use collectionsConfig cached from configResolved (siteContent may be null here)
         if (collectionsConfig) {
           const contentPaths = new Set()
+          const collectionBase = resolvedCollectionsBase || resolvedSitePath
           for (const config of Object.values(collectionsConfig)) {
             const collectionPath = typeof config === 'string' ? config : config.path
             if (collectionPath) {
-              contentPaths.add(resolve(resolvedSitePath, collectionPath))
+              contentPaths.add(resolve(collectionBase, collectionPath))
             }
           }
 
@@ -806,6 +873,9 @@ export function siteContentPlugin(options = {}) {
     async transformIndexHtml(html, ctx) {
       if (!siteContent) return html
 
+      // Shell mode: skip all HTML injections — backend provides __DATA__ at serve time
+      if (shell) return html
+
       // Detect locale from URL (e.g., /es/about → 'es')
       let contentToInject = siteContent
       let activeLocale = null
@@ -829,6 +899,29 @@ export function siteContentPlugin(options = {}) {
 
       let headInjection = ''
 
+      // Inject user's head.html (analytics, third-party scripts)
+      if (headHtml) {
+        headInjection += headHtml + '\n'
+      }
+
+      // Inject font preconnect links (before theme CSS so browser starts DNS early)
+      const fontImports = contentToInject.theme?.fonts?.import
+      if (Array.isArray(fontImports) && fontImports.length > 0) {
+        const origins = new Set()
+        for (const font of fontImports) {
+          if (font.url) {
+            try { origins.add(new URL(font.url).origin) } catch {}
+          }
+        }
+        for (const origin of origins) {
+          headInjection += `    <link rel="preconnect" href="${origin}">\n`
+        }
+        // Google Fonts serves CSS from googleapis.com but font files from gstatic.com
+        if (origins.has('https://fonts.googleapis.com')) {
+          headInjection += `    <link rel="preconnect" href="https://fonts.gstatic.com" crossorigin>\n`
+        }
+      }
+
       // Inject theme CSS
       if (contentToInject.theme?.css) {
         headInjection += `    <style id="uniweb-theme">\n${contentToInject.theme.css}\n    </style>\n`