@uniweb/build 0.1.23 → 0.1.25

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@uniweb/build",
-  "version": "0.1.23",
+  "version": "0.1.25",
   "description": "Build tooling for the Uniweb Component Web Platform",
   "type": "module",
   "exports": {
@@ -59,7 +59,7 @@
     "@tailwindcss/vite": "^4.0.0",
     "@vitejs/plugin-react": "^4.0.0 || ^5.0.0",
     "vite-plugin-svgr": "^4.0.0",
-    "@uniweb/core": "0.1.10"
+    "@uniweb/core": "0.1.11"
   },
   "peerDependenciesMeta": {
     "vite": {

package/src/foundation/config.js

@@ -48,6 +48,9 @@ const DEFAULT_EXTERNALS = [
  * @param {Object} [options={}] - Configuration options
  * @param {string} [options.entry] - Entry point path (default: 'src/_entry.generated.js')
  * @param {string} [options.fileName] - Output file name (default: 'foundation')
+ * @param {string[]} [options.components] - Paths to search for components (relative to src/).
+ *                                          Default: ['components']
+ *                                          Example: ['components', 'components/sections']
  * @param {string[]} [options.externals] - Additional packages to externalize
  * @param {boolean} [options.includeDefaultExternals] - Include default externals (default: true)
  * @param {Array} [options.plugins] - Additional Vite plugins
@@ -60,6 +63,7 @@ export async function defineFoundationConfig(options = {}) {
   const {
     entry = 'src/_entry.generated.js',
     fileName = 'foundation',
+    components: componentPaths,
     externals: additionalExternals = [],
     includeDefaultExternals = true,
     plugins: extraPlugins = [],
@@ -104,7 +108,7 @@ export async function defineFoundationConfig(options = {}) {
   // Build the plugins array
   // foundationPlugin handles entry generation and schema building
   const plugins = [
-    foundationPlugin({ srcDir: 'src' }),
+    foundationPlugin({ srcDir: 'src', components: componentPaths }),
     tailwind && tailwindcss(),
     react(),
     svgr(),

package/src/generate-entry.js

@@ -6,28 +6,24 @@
  * Exports:
  * - `components` - Object map of component name -> React component
  * - `capabilities` - Custom Layout and props from src/exports.js (if present)
- * - `meta` - Runtime metadata extracted from component meta.js files
+ * - `meta` - Per-component runtime metadata extracted from meta.js files
  *
- * The `meta` export contains properties from meta.js that are needed at runtime,
- * not just editor-time. Currently this includes:
- * - `input` - Form input schemas (for components that accept user input)
+ * The `meta` export contains only properties needed at runtime:
+ * - `background` - Engine-level background image handling
+ * - `data` - CMS entity binding ({ type, limit })
+ * - `defaults` - Param default values
+ * - `context` - Static capabilities for cross-block coordination
+ * - `initialState` - Initial values for mutable block state
  *
  * Full component metadata lives in schema.json (for the visual editor).
- * Only runtime-essential properties are extracted here to keep bundles small.
+ * Foundation identity (name, description) comes from package.json in the editor schema.
  */
 
 import { writeFile, mkdir } from 'node:fs/promises'
 import { existsSync } from 'node:fs'
 import { join, dirname } from 'node:path'
 import { discoverComponents } from './schema.js'
-
-/**
- * Keys from meta.js that should be included in the runtime bundle.
- * These are properties needed at runtime, not just editor-time.
- *
- * - input: Form schemas for components that accept user input
- */
-const RUNTIME_META_KEYS = ['input']
+import { extractAllRuntimeSchemas } from './runtime-schema.js'
 
 /**
  * Detect foundation exports file (for custom Layout, props, etc.)
@@ -63,32 +59,21 @@ function detectCssFile(srcDir) {
   return null
 }
 
-/**
- * Extract runtime-needed properties from component meta
- */
-function extractRuntimeMeta(componentsMeta) {
-  const meta = {}
-
-  for (const [name, componentMeta] of Object.entries(componentsMeta)) {
-    const extracted = {}
-    for (const key of RUNTIME_META_KEYS) {
-      if (componentMeta[key] !== undefined) {
-        extracted[key] = componentMeta[key]
-      }
-    }
-    if (Object.keys(extracted).length > 0) {
-      meta[name] = extracted
-    }
-  }
-
-  return meta
-}
 
 /**
  * Generate the entry point source code
+ *
+ * @param {Object} components - Map of componentName -> { name, path, ext, ...meta }
+ * @param {Object} options - Generation options
  */
-function generateEntrySource(componentNames, options = {}) {
-  const { cssPath = null, componentExtensions = {}, foundationExports = null, runtimeMeta = {} } = options
+function generateEntrySource(components, options = {}) {
+  const {
+    cssPath = null,
+    foundationExports = null,
+    meta = {},
+  } = options
+
+  const componentNames = Object.keys(components).sort()
 
   const lines = [
     '// Auto-generated foundation entry point',
@@ -106,10 +91,10 @@ function generateEntrySource(componentNames, options = {}) {
     lines.push(`import capabilities from '${foundationExports.path}'`)
   }
 
-  // Component imports (use detected extension or default to .js)
+  // Component imports (use component's path and detected extension)
   for (const name of componentNames) {
-    const ext = componentExtensions[name] || 'js'
-    lines.push(`import ${name} from './components/${name}/index.${ext}'`)
+    const { path, ext = 'js' } = components[name]
+    lines.push(`import ${name} from './${path}/index.${ext}'`)
   }
 
   lines.push('')
@@ -131,14 +116,11 @@ function generateEntrySource(componentNames, options = {}) {
     lines.push('export const capabilities = null')
   }
 
-  // Runtime meta (form schemas, etc.) - only if non-empty
+  // Per-component metadata (defaults, context, initialState, background, data)
   lines.push('')
-  if (Object.keys(runtimeMeta).length > 0) {
-    const metaJson = JSON.stringify(runtimeMeta, null, 2)
-      .split('\n')
-      .map((line, i) => (i === 0 ? line : line))
-      .join('\n')
-    lines.push(`// Runtime metadata (form schemas, etc.)`)
+  if (Object.keys(meta).length > 0) {
+    const metaJson = JSON.stringify(meta, null, 2)
+    lines.push(`// Per-component runtime metadata (from meta.js)`)
     lines.push(`export const meta = ${metaJson}`)
   } else {
     lines.push('export const meta = {}')
@@ -151,9 +133,12 @@ function generateEntrySource(componentNames, options = {}) {
 
 /**
  * Detect the index file extension for a component
+ *
+ * @param {string} srcDir - Source directory
+ * @param {string} componentPath - Relative path to component (e.g., 'components/Hero')
  */
-function detectComponentExtension(srcDir, componentName) {
-  const basePath = join(srcDir, 'components', componentName)
+function detectComponentExtension(srcDir, componentPath) {
+  const basePath = join(srcDir, componentPath)
   for (const ext of ['jsx', 'tsx', 'js', 'ts']) {
     if (existsSync(join(basePath, `index.${ext}`))) {
       return ext
@@ -164,20 +149,27 @@ function detectComponentExtension(srcDir, componentName) {
 
 /**
  * Generate the foundation entry point file
+ *
+ * @param {string} srcDir - Source directory
+ * @param {string} [outputPath] - Output file path (default: srcDir/_entry.generated.js)
+ * @param {Object} [options] - Options
+ * @param {string[]} [options.componentPaths] - Paths to search for components (relative to srcDir)
  */
-export async function generateEntryPoint(srcDir, outputPath = null) {
+export async function generateEntryPoint(srcDir, outputPath = null, options = {}) {
+  const { componentPaths } = options
+
   // Discover components (includes meta from meta.js files)
-  const components = await discoverComponents(srcDir)
+  const components = await discoverComponents(srcDir, componentPaths)
   const componentNames = Object.keys(components).sort()
 
   if (componentNames.length === 0) {
     console.warn('Warning: No exposed components found')
   }
 
-  // Detect extensions for each component
-  const componentExtensions = {}
+  // Detect extensions for each component and add to component info
   for (const name of componentNames) {
-    componentExtensions[name] = detectComponentExtension(srcDir, name)
+    const component = components[name]
+    component.ext = detectComponentExtension(srcDir, component.path)
   }
 
   // Check for CSS file
@@ -186,15 +178,14 @@ export async function generateEntryPoint(srcDir, outputPath = null) {
   // Check for foundation exports (custom Layout, props, etc.)
   const foundationExports = detectFoundationExports(srcDir)
 
-  // Extract runtime-needed meta (form schemas, etc.)
-  const runtimeMeta = extractRuntimeMeta(components)
+  // Extract per-component runtime metadata from meta.js files
+  const meta = extractAllRuntimeSchemas(components)
 
   // Generate source
-  const source = generateEntrySource(componentNames, {
+  const source = generateEntrySource(components, {
     cssPath,
-    componentExtensions,
     foundationExports,
-    runtimeMeta,
+    meta,
   })
 
   // Write to file
@@ -212,6 +203,7 @@ export async function generateEntryPoint(srcDir, outputPath = null) {
     outputPath: output,
     componentNames,
     foundationExports,
+    meta,
   }
 }
 

package/src/images.js

@@ -132,28 +132,21 @@ export async function processComponentPreviews(componentDir, componentName, outp
  *
  * @param {string} srcDir - Source directory (e.g., src/)
  * @param {string} outputDir - Output directory (e.g., dist/)
- * @param {Object} schema - Schema object to update with image info
+ * @param {Object} schema - Schema object with components (each has `path` property)
  * @param {boolean} isProduction - Whether to convert to webp
  * @returns {Object} Updated schema with image references
  */
 export async function processAllPreviews(srcDir, outputDir, schema, isProduction = true) {
-  const componentsDir = join(srcDir, 'components')
-
-  if (!existsSync(componentsDir)) {
-    return schema
-  }
-
-  const entries = await readdir(componentsDir, { withFileTypes: true })
   let totalImages = 0
 
-  for (const entry of entries) {
-    if (!entry.isDirectory()) continue
+  // Iterate through components in schema (skip _self)
+  for (const [componentName, componentMeta] of Object.entries(schema)) {
+    if (componentName === '_self') continue
+    if (!componentMeta.path) continue
 
-    const componentName = entry.name
-    const componentDir = join(componentsDir, componentName)
+    const componentDir = join(srcDir, componentMeta.path)
 
-    // Skip if component not in schema
-    if (!schema[componentName]) continue
+    if (!existsSync(componentDir)) continue
 
     // Process preview images
     const previews = await processComponentPreviews(

package/src/prerender.js

@@ -263,6 +263,52 @@ function PageRenderer({ page, foundation }) {
   )
 }
 
+/**
+ * Guarantee content structure exists (mirrors runtime/prepare-props.js)
+ * Returns a content object with all standard paths guaranteed to exist
+ */
+function guaranteeContentStructure(parsedContent) {
+  const content = parsedContent || {}
+
+  // Spread content first, then override with guaranteed structure
+  // This ensures main.body.paragraphs etc. are always arrays
+  return {
+    // Preserve any additional fields from parser
+    ...content,
+    // Main content section (override with guarantees)
+    main: {
+      header: {
+        title: content.main?.header?.title || '',
+        pretitle: content.main?.header?.pretitle || '',
+        subtitle: content.main?.header?.subtitle || '',
+      },
+      body: {
+        paragraphs: content.main?.body?.paragraphs || [],
+        links: content.main?.body?.links || [],
+        imgs: content.main?.body?.imgs || [],
+        lists: content.main?.body?.lists || [],
+        icons: content.main?.body?.icons || [],
+      },
+    },
+    // Content items (H3 sections)
+    items: content.items || [],
+  }
+}
+
+/**
+ * Apply param defaults from runtime schema
+ */
+function applyDefaults(params, defaults) {
+  if (!defaults || Object.keys(defaults).length === 0) {
+    return params || {}
+  }
+
+  return {
+    ...defaults,
+    ...(params || {}),
+  }
+}
+
 /**
  * Block renderer - maps block to foundation component
  */
@@ -290,13 +336,24 @@ function BlockRenderer({ block, foundation }) {
     )
   }
 
-  // Build content object (same as runtime's BlockRenderer)
-  let content
+  // Get runtime schema for defaults (from foundation.runtimeSchema)
+  const runtimeSchema = foundation.runtimeSchema || {}
+  const schema = runtimeSchema[componentName] || null
+  const defaults = schema?.defaults || {}
+
+  // Build content and params with runtime guarantees (same as runtime's BlockRenderer)
+  let content, params
   if (block.parsedContent?.raw) {
+    // Simple PoC format - content was passed directly
     content = block.parsedContent.raw
+    params = block.properties
   } else {
+    // Apply param defaults from meta.js
+    params = applyDefaults(block.properties, defaults)
+
+    // Guarantee content structure + merge with properties for backward compat
     content = {
-      ...block.parsedContent,
+      ...guaranteeContentStructure(block.parsedContent),
       ...block.properties,
       _prosemirror: block.parsedContent
     }
@@ -313,10 +370,8 @@ function BlockRenderer({ block, foundation }) {
   // Component props
   const componentProps = {
     content,
-    params: block.properties,
+    params,
     block,
-    page: globalThis.uniweb?.activeWebsite?.activePage,
-    website: globalThis.uniweb?.activeWebsite,
     input: block.input
   }
 

package/src/runtime-schema.js

@@ -0,0 +1,125 @@
+/**
+ * Runtime Schema Extractor
+ *
+ * Extracts lean runtime-relevant metadata from full meta.js files.
+ * The runtime schema is optimized for size and contains only what's
+ * needed at render time:
+ *
+ * - background: boolean for engine-level background handling
+ * - data: { type, limit } for CMS entity binding
+ * - defaults: param default values
+ * - context: static capabilities for cross-block coordination
+ * - initialState: initial values for mutable block state
+ *
+ * Full metadata (titles, descriptions, hints, etc.) stays in schema.json
+ * for the visual editor.
+ */
+
+/**
+ * Parse data string into structured object
+ * 'events' -> { type: 'events', limit: null }
+ * 'events:6' -> { type: 'events', limit: 6 }
+ *
+ * @param {string} dataString
+ * @returns {{ type: string, limit: number|null }}
+ */
+function parseDataString(dataString) {
+  if (!dataString || typeof dataString !== 'string') {
+    return null
+  }
+
+  const [type, limitStr] = dataString.split(':')
+  return {
+    type: type.trim(),
+    limit: limitStr ? parseInt(limitStr, 10) : null,
+  }
+}
+
+/**
+ * Extract param defaults from params object
+ *
+ * @param {Object} params - The params object from meta.js
+ * @returns {Object|null} - Object of { paramName: defaultValue } or null if empty
+ */
+function extractParamDefaults(params) {
+  if (!params || typeof params !== 'object') {
+    return null
+  }
+
+  const defaults = {}
+
+  for (const [key, param] of Object.entries(params)) {
+    if (param && typeof param === 'object' && param.default !== undefined) {
+      defaults[key] = param.default
+    }
+  }
+
+  return Object.keys(defaults).length > 0 ? defaults : null
+}
+
+/**
+ * Extract lean runtime schema from a full meta.js object
+ *
+ * @param {Object} fullMeta - The full meta.js default export
+ * @returns {Object|null} - Lean runtime schema or null if empty
+ */
+export function extractRuntimeSchema(fullMeta) {
+  if (!fullMeta || typeof fullMeta !== 'object') {
+    return null
+  }
+
+  const runtime = {}
+
+  // Background handling (boolean or 'auto'/'manual')
+  if (fullMeta.background) {
+    runtime.background = fullMeta.background
+  }
+
+  // Data binding (CMS entities)
+  if (fullMeta.data) {
+    const parsed = parseDataString(fullMeta.data)
+    if (parsed) {
+      runtime.data = parsed
+    }
+  }
+
+  // Param defaults - support both v2 'params' and v1 'properties'
+  const paramsObj = fullMeta.params || fullMeta.properties
+  const defaults = extractParamDefaults(paramsObj)
+  if (defaults) {
+    runtime.defaults = defaults
+  }
+
+  // Context - static capabilities for cross-block coordination
+  // e.g., { allowTranslucentTop: true } for Hero components
+  if (fullMeta.context && typeof fullMeta.context === 'object') {
+    runtime.context = fullMeta.context
+  }
+
+  // Initial state - default values for mutable block state
+  // e.g., { expanded: false } for accordion-like components
+  if (fullMeta.initialState && typeof fullMeta.initialState === 'object') {
+    runtime.initialState = fullMeta.initialState
+  }
+
+  return Object.keys(runtime).length > 0 ? runtime : null
+}
+
+/**
+ * Extract runtime schemas for all components
+ *
+ * @param {Object} componentsMeta - Map of componentName -> meta.js content
+ * @returns {Object} - Map of componentName -> runtime schema (excludes null entries)
+ */
+export function extractAllRuntimeSchemas(componentsMeta) {
+  const schemas = {}
+
+  for (const [name, meta] of Object.entries(componentsMeta)) {
+    const schema = extractRuntimeSchema(meta)
+    if (schema) {
+      schemas[name] = schema
+    }
+  }
+
+  return schemas
+}

package/src/schema.js

@@ -13,6 +13,9 @@ import { pathToFileURL } from 'node:url'
 // Meta file name (standardized to meta.js)
 const META_FILE_NAME = 'meta.js'
 
+// Default component paths (relative to srcDir)
+const DEFAULT_COMPONENT_PATHS = ['components']
+
 /**
  * Load a meta.js file via dynamic import
  */
@@ -57,23 +60,25 @@ export async function loadFoundationMeta(srcDir) {
 }
 
 /**
- * Discover all exposed components in a foundation
- * Returns map of componentName -> meta
+ * Discover components in a single path
+ * @param {string} srcDir - Source directory (e.g., 'src')
+ * @param {string} relativePath - Path relative to srcDir (e.g., 'components' or 'components/sections')
+ * @returns {Object} Map of componentName -> { name, path, ...meta }
  */
-export async function discoverComponents(srcDir) {
-  const componentsDir = join(srcDir, 'components')
+async function discoverComponentsInPath(srcDir, relativePath) {
+  const fullPath = join(srcDir, relativePath)
 
-  if (!existsSync(componentsDir)) {
+  if (!existsSync(fullPath)) {
     return {}
   }
 
-  const entries = await readdir(componentsDir, { withFileTypes: true })
+  const entries = await readdir(fullPath, { withFileTypes: true })
   const components = {}
 
   for (const entry of entries) {
     if (!entry.isDirectory()) continue
 
-    const componentDir = join(componentsDir, entry.name)
+    const componentDir = join(fullPath, entry.name)
     const result = await loadComponentMeta(componentDir)
 
     if (result && result.meta) {
@@ -84,6 +89,7 @@ export async function discoverComponents(srcDir) {
 
       components[entry.name] = {
         name: entry.name,
+        path: join(relativePath, entry.name), // e.g., 'components/Hero' or 'components/sections/Hero'
         ...result.meta,
       }
     }
@@ -92,13 +98,43 @@ export async function discoverComponents(srcDir) {
   return components
 }
 
+/**
+ * Discover all exposed components in a foundation
+ *
+ * @param {string} srcDir - Source directory (e.g., 'src')
+ * @param {string[]} [componentPaths] - Paths to search for components (relative to srcDir)
+ *                                      Default: ['components']
+ * @returns {Object} Map of componentName -> { name, path, ...meta }
+ */
+export async function discoverComponents(srcDir, componentPaths = DEFAULT_COMPONENT_PATHS) {
+  const components = {}
+
+  for (const relativePath of componentPaths) {
+    const found = await discoverComponentsInPath(srcDir, relativePath)
+
+    for (const [name, meta] of Object.entries(found)) {
+      if (components[name]) {
+        // Component already found in an earlier path - skip (first wins)
+        console.warn(`Warning: Component "${name}" found in multiple paths. Using ${components[name].path}, ignoring ${meta.path}`)
+        continue
+      }
+      components[name] = meta
+    }
+  }
+
+  return components
+}
+
 /**
  * Build complete schema for a foundation
  * Returns { _self: foundationMeta, ComponentName: componentMeta, ... }
+ *
+ * @param {string} srcDir - Source directory
+ * @param {string[]} [componentPaths] - Paths to search for components
  */
-export async function buildSchema(srcDir) {
+export async function buildSchema(srcDir, componentPaths) {
   const foundationMeta = await loadFoundationMeta(srcDir)
-  const components = await discoverComponents(srcDir)
+  const components = await discoverComponents(srcDir, componentPaths)
 
   return {
     _self: foundationMeta,
@@ -108,8 +144,11 @@ export async function buildSchema(srcDir) {
 
 /**
  * Get list of exposed component names
+ *
+ * @param {string} srcDir - Source directory
+ * @param {string[]} [componentPaths] - Paths to search for components
  */
-export async function getExposedComponents(srcDir) {
-  const components = await discoverComponents(srcDir)
+export async function getExposedComponents(srcDir, componentPaths) {
+  const components = await discoverComponents(srcDir, componentPaths)
   return Object.keys(components)
 }

package/src/site/plugin.js

@@ -30,12 +30,14 @@
  * })
  */
 
-import { resolve } from 'node:path'
-import { watch } from 'node:fs'
+import { resolve, join } from 'node:path'
+import { watch, existsSync } from 'node:fs'
+import { readFile, readdir } from 'node:fs/promises'
 import { collectSiteContent } from './content-collector.js'
 import { processAssets, rewriteSiteContentPaths } from './asset-processor.js'
 import { processAdvancedAssets } from './advanced-processors.js'
 import { generateSearchIndex, isSearchEnabled, getSearchIndexFilename } from '../search/index.js'
+import { mergeTranslations } from '../i18n/merge.js'
 
 /**
  * Generate sitemap.xml content
@@ -269,6 +271,62 @@ export function siteContentPlugin(options = {}) {
   let isProduction = false
   let watcher = null
   let server = null
+  let localeTranslations = {} // Cache: { locale: translations }
+  let localesDir = 'locales' // Default, updated from site config
+
+  /**
+   * Load translations for a specific locale
+   */
+  async function loadLocaleTranslations(locale) {
+    if (localeTranslations[locale]) {
+      return localeTranslations[locale]
+    }
+
+    const localePath = join(resolvedSitePath, localesDir, `${locale}.json`)
+    if (!existsSync(localePath)) {
+      return null
+    }
+
+    try {
+      const content = await readFile(localePath, 'utf-8')
+      const translations = JSON.parse(content)
+      localeTranslations[locale] = translations
+      return translations
+    } catch {
+      return null
+    }
+  }
+
+  /**
+   * Get available locales from locales directory
+   */
+  async function getAvailableLocales() {
+    const localesPath = join(resolvedSitePath, localesDir)
+    if (!existsSync(localesPath)) {
+      return []
+    }
+
+    try {
+      const files = await readdir(localesPath)
+      return files
+        .filter(f => f.endsWith('.json') && f !== 'manifest.json' && !f.startsWith('_'))
+        .map(f => f.replace('.json', ''))
+    } catch {
+      return []
+    }
+  }
+
+  /**
+   * Get translated content for a locale
+   */
+  async function getTranslatedContent(locale) {
+    if (!siteContent) return null
+
+    const translations = await loadLocaleTranslations(locale)
+    if (!translations) return null
+
+    return mergeTranslations(siteContent, translations)
+  }
 
   return {
     name: 'uniweb:site-content',
@@ -284,6 +342,14 @@ export function siteContentPlugin(options = {}) {
       try {
         siteContent = await collectSiteContent(resolvedSitePath)
         console.log(`[site-content] Collected ${siteContent.pages?.length || 0} pages`)
+
+        // Update localesDir from site config
+        if (siteContent.config?.i18n?.localesDir) {
+          localesDir = siteContent.config.i18n.localesDir
+        }
+
+        // Clear translation cache on rebuild
+        localeTranslations = {}
       } catch (err) {
         console.error('[site-content] Failed to collect content:', err.message)
         siteContent = { config: {}, theme: {}, pages: [] }
@@ -346,14 +412,59 @@ export function siteContentPlugin(options = {}) {
         watcher = { close: () => watchers.forEach(w => w.close()) }
       }
 
+      // Watch locales directory for translation changes
+      const localesPath = resolve(resolvedSitePath, localesDir)
+      if (existsSync(localesPath)) {
+        try {
+          const localeWatcher = watch(localesPath, { recursive: false }, () => {
+            console.log('[site-content] Translation files changed, clearing cache...')
+            localeTranslations = {}
+            server.ws.send({ type: 'full-reload' })
+          })
+          if (watcher) {
+            const originalClose = watcher.close
+            watcher.close = () => {
+              originalClose()
+              localeWatcher.close()
+            }
+          }
+          console.log(`[site-content] Watching ${localesPath} for translation changes`)
+        } catch (err) {
+          // locales dir may not exist, that's ok
+        }
+      }
+
       // Serve content and SEO files
-      devServer.middlewares.use((req, res, next) => {
+      devServer.middlewares.use(async (req, res, next) => {
+        // Handle default locale site-content request
         if (req.url === `/${filename}`) {
           res.setHeader('Content-Type', 'application/json')
           res.end(JSON.stringify(siteContent, null, 2))
           return
         }
 
+        // Handle locale-prefixed site-content request (e.g., /es/site-content.json)
+        const localeContentMatch = req.url.match(/^\/([a-z]{2})\/site-content\.json$/)
+        if (localeContentMatch) {
+          const locale = localeContentMatch[1]
+          const translatedContent = await getTranslatedContent(locale)
+
+          if (translatedContent) {
+            // Add activeLocale to the content so runtime knows which locale is active
+            const contentWithLocale = {
+              ...translatedContent,
+              config: {
+                ...translatedContent.config,
+                activeLocale: locale
+              }
+            }
+            res.setHeader('Content-Type', 'application/json')
+            res.end(JSON.stringify(contentWithLocale, null, 2))
+            return
+          }
+          // If no translations, fall through to serve default content
+        }
+
         // Serve sitemap.xml in dev mode
         if (req.url === '/sitemap.xml' && seoEnabled && siteContent?.pages) {
           res.setHeader('Content-Type', 'application/xml')
@@ -394,14 +505,35 @@ export function siteContentPlugin(options = {}) {
       })
     },
 
-    transformIndexHtml(html) {
+    async transformIndexHtml(html, ctx) {
       if (!siteContent) return html
 
+      // Detect locale from URL (e.g., /es/about → 'es')
+      let contentToInject = siteContent
+      let activeLocale = null
+
+      if (ctx?.originalUrl) {
+        const localeMatch = ctx.originalUrl.match(/^\/([a-z]{2})(\/|$)/)
+        if (localeMatch) {
+          activeLocale = localeMatch[1]
+          const translatedContent = await getTranslatedContent(activeLocale)
+          if (translatedContent) {
+            contentToInject = {
+              ...translatedContent,
+              config: {
+                ...translatedContent.config,
+                activeLocale
+              }
+            }
+          }
+        }
+      }
+
       let headInjection = ''
 
       // Inject SEO meta tags
       if (seoEnabled) {
-        const metaTags = generateMetaTags(siteContent, seoOptions)
+        const metaTags = generateMetaTags(contentToInject, seoOptions)
         if (metaTags) {
           headInjection += `    ${metaTags}\n`
         }
@@ -409,7 +541,7 @@ export function siteContentPlugin(options = {}) {
 
       // Inject content as JSON script tag
       if (inject) {
-        headInjection += `    <script type="application/json" id="${variableName}">${JSON.stringify(siteContent)}</script>\n`
+        headInjection += `    <script type="application/json" id="${variableName}">${JSON.stringify(contentToInject)}</script>\n`
       }
 
       if (!headInjection) return html

package/src/vite-foundation-plugin.js

@@ -16,8 +16,8 @@ import { processAllPreviews } from './images.js'
 /**
  * Build schema.json with preview image references
  */
-async function buildSchemaWithPreviews(srcDir, outDir, isProduction) {
-  const schema = await buildSchema(srcDir)
+async function buildSchemaWithPreviews(srcDir, outDir, isProduction, componentPaths) {
+  const schema = await buildSchema(srcDir, componentPaths)
 
   // Process preview images
   const { schema: schemaWithImages, totalImages } = await processAllPreviews(
@@ -42,6 +42,7 @@ export function foundationBuildPlugin(options = {}) {
     srcDir = 'src',
     generateEntry = true,
     entryFileName = '_entry.generated.js',
+    components: componentPaths,
   } = options
 
   let resolvedSrcDir
@@ -58,7 +59,7 @@ export function foundationBuildPlugin(options = {}) {
       const root = config.root || process.cwd()
       const srcPath = resolve(root, srcDir)
       const entryPath = join(srcPath, entryFileName)
-      await generateEntryPoint(srcPath, entryPath)
+      await generateEntryPoint(srcPath, entryPath, { componentPaths })
     },
 
     async configResolved(config) {
@@ -78,7 +79,8 @@ export function foundationBuildPlugin(options = {}) {
       const schema = await buildSchemaWithPreviews(
         resolvedSrcDir,
         outDir,
-        isProduction
+        isProduction,
+        componentPaths
       )
 
       const schemaPath = join(metaDir, 'schema.json')
@@ -97,6 +99,7 @@ export function foundationDevPlugin(options = {}) {
   const {
     srcDir = 'src',
     entryFileName = '_entry.generated.js',
+    components: componentPaths,
   } = options
 
   let resolvedSrcDir
@@ -109,7 +112,7 @@ export function foundationDevPlugin(options = {}) {
       const root = config.root || process.cwd()
       const srcPath = resolve(root, srcDir)
       const entryPath = join(srcPath, entryFileName)
-      await generateEntryPoint(srcPath, entryPath)
+      await generateEntryPoint(srcPath, entryPath, { componentPaths })
     },
 
     configResolved(config) {
@@ -118,10 +121,11 @@ export function foundationDevPlugin(options = {}) {
 
     async handleHotUpdate({ file, server }) {
       // Regenerate entry when meta.js files change
-      if (file.includes('/components/') && file.endsWith('/meta.js')) {
+      // Check if file is a meta.js in the src directory
+      if (file.startsWith(resolvedSrcDir) && file.endsWith('/meta.js')) {
         console.log('Component meta.js changed, regenerating entry...')
         const entryPath = join(resolvedSrcDir, entryFileName)
-        await generateEntryPoint(resolvedSrcDir, entryPath)
+        await generateEntryPoint(resolvedSrcDir, entryPath, { componentPaths })
 
         // Trigger full reload since entry changed
         server.ws.send({ type: 'full-reload' })
@@ -131,7 +135,7 @@ export function foundationDevPlugin(options = {}) {
       if (file.endsWith('/exports.js') || file.endsWith('/exports.jsx')) {
         console.log('Foundation exports changed, regenerating entry...')
         const entryPath = join(resolvedSrcDir, entryFileName)
-        await generateEntryPoint(resolvedSrcDir, entryPath)
+        await generateEntryPoint(resolvedSrcDir, entryPath, { componentPaths })
         server.ws.send({ type: 'full-reload' })
       }
     },