@uniweb/build 0.6.5 → 0.6.7

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@uniweb/build",
-  "version": "0.6.5",
+  "version": "0.6.7",
   "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.14",
+    "@uniweb/runtime": "0.5.16",
     "@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.3"
+    "@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/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/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: {

package/src/site/content-collector.js

@@ -185,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:
@@ -226,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
  *
@@ -629,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 = {
@@ -649,23 +760,28 @@ async function collectPagesRecursive(dirPath, parentRoute, siteRoot, orderConfig
   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
       }
     })
   }
@@ -679,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 {
-        // Non-version folders in a versioned section
-        // These could be shared across versions - process normally
         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)
@@ -748,67 +843,235 @@ async function collectPagesRecursive(dirPath, parentRoute, siteRoot, orderConfig
       }
     }
 
-    // Return early - we've handled all children
     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
-  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
+    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 })
+      }
+    }
 
-    // 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,
-      parentRoute,
-      parentFetch,
-      versionContext
-    })
+    // 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 404 page - only at root level
-      if (parentRoute === '/' && entry === '404') {
-        notFound = page
-      } else {
-        pages.push(page)
+      // Handle index: promote to parent route
+      if (name === indexName) {
+        page.isIndex = true
+        page.sourcePath = page.route
+        page.route = parentRoute
       }
 
-      // Recursively process subdirectories
-      {
-        // 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(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 {
+        // 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
+        }
+
+        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, notFound, versionedScopes }
@@ -930,15 +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, notFound, versionedScopes } =
-    await collectPagesRecursive(pagesPath, '/', sitePath, siteOrderConfig)
+    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 = {},
@@ -379,6 +380,7 @@ export function siteContentPlugin(options = {}) {
   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
@@ -426,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
    */
@@ -532,6 +546,7 @@ export function siteContentPlugin(options = {}) {
       // 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
@@ -579,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`)
@@ -649,6 +665,14 @@ 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) {
@@ -849,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
@@ -872,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`