@uniweb/build 0.3.1 → 0.4.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@uniweb/build",
-  "version": "0.3.1",
+  "version": "0.4.0",
   "description": "Build tooling for the Uniweb Component Web Platform",
   "type": "module",
   "exports": {
@@ -50,8 +50,8 @@
     "sharp": "^0.33.2"
   },
   "optionalDependencies": {
-    "@uniweb/content-reader": "1.0.7",
-    "@uniweb/runtime": "0.4.2"
+    "@uniweb/content-reader": "1.1.0",
+    "@uniweb/runtime": "0.4.4"
   },
   "peerDependencies": {
     "vite": "^5.0.0 || ^6.0.0 || ^7.0.0",
@@ -60,7 +60,7 @@
     "@tailwindcss/vite": "^4.0.0",
     "@vitejs/plugin-react": "^4.0.0 || ^5.0.0",
     "vite-plugin-svgr": "^4.0.0",
-    "@uniweb/core": "0.2.4"
+    "@uniweb/core": "0.3.0"
   },
   "peerDependenciesMeta": {
     "vite": {

package/src/i18n/collections.js

@@ -9,6 +9,7 @@ import { readFile, writeFile, readdir, mkdir } from 'fs/promises'
 import { existsSync } from 'fs'
 import { join } from 'path'
 import { computeHash } from './hash.js'
+import { loadFreeformCollectionItem } from './freeform.js'
 
 export const COLLECTIONS_DIR = 'collections'
 
@@ -198,13 +199,16 @@ function addUnit(units, source, field, context) {
  * Merge translations into collection data and write locale-specific files
  * @param {string} siteRoot - Site root directory
  * @param {Object} options - Options
+ * @param {boolean} [options.freeformEnabled=true] - Enable free-form translation support
  * @returns {Promise<Object>} Map of locale to output paths
  */
 export async function buildLocalizedCollections(siteRoot, options = {}) {
   const {
     locales = [],
     outputDir = join(siteRoot, 'dist'),
-    collectionsLocalesDir = join(siteRoot, 'locales', COLLECTIONS_DIR)
+    collectionsLocalesDir = join(siteRoot, 'locales', COLLECTIONS_DIR),
+    localesDir = join(siteRoot, 'locales'),
+    freeformEnabled = true
   } = options
 
   const dataDir = join(siteRoot, 'public', 'data')
@@ -240,6 +244,10 @@ export async function buildLocalizedCollections(siteRoot, options = {}) {
       }
     }
 
+    // Check if free-form translations exist for this locale
+    const freeformDir = join(localesDir, 'freeform', locale)
+    const hasFreeform = freeformEnabled && existsSync(freeformDir)
+
     // Create locale data directory
     const localeDataDir = join(outputDir, locale, 'data')
     await mkdir(localeDataDir, { recursive: true })
@@ -262,9 +270,15 @@ export async function buildLocalizedCollections(siteRoot, options = {}) {
           continue
         }
 
-        // Translate each item
-        const translatedItems = items.map(item =>
-          translateItem(item, collectionName, translations)
+        // Translate each item (with free-form support)
+        const translatedItems = await Promise.all(
+          items.map(item =>
+            translateItemAsync(item, collectionName, translations, {
+              locale,
+              localesDir,
+              freeformEnabled: hasFreeform
+            })
+          )
         )
 
         const destPath = join(localeDataDir, file)
@@ -280,13 +294,69 @@ export async function buildLocalizedCollections(siteRoot, options = {}) {
 }
 
 /**
- * Apply translations to a collection item
+ * Apply translations to a collection item (async, with free-form support)
+ *
+ * Resolution order:
+ * 1. Check for free-form translation (complete or partial replacement)
+ * 2. Fall back to hash-based translation
+ *
+ * @param {Object} item - Collection item
+ * @param {string} collectionName - Name of the collection
+ * @param {Object} translations - Hash-based translations
+ * @param {Object} options - Options
+ * @returns {Promise<Object>} Translated item
  */
-function translateItem(item, collectionName, translations) {
+async function translateItemAsync(item, collectionName, translations, options = {}) {
+  const { locale, localesDir, freeformEnabled } = options
   const translated = { ...item }
   const slug = item.slug || 'unknown'
   const context = { collection: collectionName, item: slug }
 
+  // Check for free-form translation first
+  if (freeformEnabled && locale && localesDir) {
+    const freeform = await loadFreeformCollectionItem(item, collectionName, locale, localesDir)
+
+    if (freeform) {
+      // Merge free-form data (supports partial: frontmatter only, body only, or both)
+      if (freeform.frontmatter) {
+        // Merge frontmatter fields from free-form
+        Object.assign(translated, freeform.frontmatter)
+      }
+      if (freeform.content) {
+        // Replace content entirely with free-form content
+        translated.content = freeform.content
+        // Skip hash-based content translation since we have free-form
+        return translateItemFields(translated, context, translations)
+      }
+    }
+  }
+
+  // Fall back to hash-based translation (or continue after partial free-form)
+  return translateItemSync(translated, collectionName, translations)
+}
+
+/**
+ * Apply translations to a collection item (sync, hash-based only)
+ */
+function translateItemSync(item, collectionName, translations) {
+  const translated = { ...item }
+  const slug = item.slug || 'unknown'
+  const context = { collection: collectionName, item: slug }
+
+  // Translate all fields including content
+  return translateItemFields(translated, context, translations, true)
+}
+
+/**
+ * Translate item fields (frontmatter and optionally content)
+ *
+ * @param {Object} translated - Item being translated
+ * @param {Object} context - Translation context
+ * @param {Object} translations - Hash-based translations
+ * @param {boolean} includeContent - Whether to translate ProseMirror content
+ * @returns {Object} Translated item
+ */
+function translateItemFields(translated, context, translations, includeContent = false) {
   // Translate frontmatter fields
   const translatableFields = ['title', 'description', 'excerpt', 'summary', 'subtitle']
 
@@ -320,8 +390,8 @@ function translateItem(item, collectionName, translations) {
     })
   }
 
-  // Translate ProseMirror content
-  if (translated.content?.type === 'doc') {
+  // Translate ProseMirror content (only if requested)
+  if (includeContent && translated.content?.type === 'doc') {
     translated.content = translateProseMirrorDoc(
       translated.content,
       context,
@@ -332,6 +402,14 @@ function translateItem(item, collectionName, translations) {
   return translated
 }
 
+/**
+ * Apply translations to a collection item (legacy sync function)
+ * @deprecated Use translateItemAsync for free-form support
+ */
+function translateItem(item, collectionName, translations) {
+  return translateItemSync(item, collectionName, translations)
+}
+
 /**
  * Translate a ProseMirror document
  */

package/src/i18n/freeform-manifest.js

@@ -0,0 +1,307 @@
+/**
+ * Free-form Translation Manifest Management
+ *
+ * Tracks source content hashes for free-form translations to detect
+ * when source content changes (staleness). The manifest lives at:
+ *   locales/freeform/{locale}/.manifest.json
+ *
+ * Manifest format:
+ * {
+ *   "pages/about/hero.md": { "hash": "a1b2c3d4", "recorded": "2025-01-28" },
+ *   "page-ids/installation/intro.md": { "hash": "b2c3d4e5", "recorded": "2025-01-25" },
+ *   "collections/articles/getting-started.md": { "hash": "c3d4e5f6", "recorded": "2025-01-27" }
+ * }
+ */
+
+import { readFile, writeFile, mkdir } from 'fs/promises'
+import { existsSync } from 'fs'
+import { join, dirname } from 'path'
+import { createHash } from 'crypto'
+
+const MANIFEST_FILENAME = '.manifest.json'
+
+/**
+ * Compute a hash of a ProseMirror document for staleness detection
+ *
+ * Extracts text content and computes a hash that changes when
+ * the content changes (ignoring formatting-only changes).
+ *
+ * @param {Object} doc - ProseMirror document
+ * @returns {string} 8-character hex hash
+ */
+export function computeSourceHash(doc) {
+  if (!doc) return ''
+
+  // Extract all text content from the document
+  const textContent = extractTextFromDoc(doc)
+
+  // Hash the normalized text
+  return createHash('sha256')
+    .update(textContent)
+    .digest('hex')
+    .slice(0, 8)
+}
+
+/**
+ * Recursively extract text from a ProseMirror document
+ * @param {Object} node - ProseMirror node
+ * @returns {string} Concatenated text content
+ */
+function extractTextFromDoc(node) {
+  if (!node) return ''
+
+  if (node.type === 'text') {
+    return node.text || ''
+  }
+
+  if (!node.content || !Array.isArray(node.content)) {
+    return ''
+  }
+
+  return node.content.map(extractTextFromDoc).join(' ')
+}
+
+/**
+ * Get the manifest path for a locale
+ * @param {string} localeDir - Path to locale's freeform directory
+ * @returns {string} Path to manifest file
+ */
+function getManifestPath(localeDir) {
+  return join(localeDir, MANIFEST_FILENAME)
+}
+
+/**
+ * Load the manifest for a locale
+ *
+ * @param {string} localeDir - Path to locale's freeform directory (locales/freeform/{locale})
+ * @returns {Promise<Object>} Manifest object (empty if not found)
+ */
+export async function loadManifest(localeDir) {
+  const manifestPath = getManifestPath(localeDir)
+
+  if (!existsSync(manifestPath)) {
+    return {}
+  }
+
+  try {
+    const content = await readFile(manifestPath, 'utf-8')
+    return JSON.parse(content)
+  } catch (err) {
+    console.warn(`[i18n] Failed to load manifest ${manifestPath}: ${err.message}`)
+    return {}
+  }
+}
+
+/**
+ * Save the manifest for a locale
+ *
+ * @param {string} localeDir - Path to locale's freeform directory
+ * @param {Object} manifest - Manifest object to save
+ */
+export async function saveManifest(localeDir, manifest) {
+  const manifestPath = getManifestPath(localeDir)
+
+  // Ensure directory exists
+  if (!existsSync(localeDir)) {
+    await mkdir(localeDir, { recursive: true })
+  }
+
+  await writeFile(manifestPath, JSON.stringify(manifest, null, 2))
+}
+
+/**
+ * Record a source hash in the manifest
+ *
+ * Called when a new free-form translation is created to record
+ * the hash of the source content at that time.
+ *
+ * @param {string} localeDir - Path to locale's freeform directory
+ * @param {string} relativePath - Path relative to locale dir (e.g., 'pages/about/hero.md')
+ * @param {string} sourceHash - Hash of the source content
+ * @returns {Promise<void>}
+ */
+export async function recordHash(localeDir, relativePath, sourceHash) {
+  const manifest = await loadManifest(localeDir)
+
+  manifest[relativePath] = {
+    hash: sourceHash,
+    recorded: new Date().toISOString().split('T')[0] // YYYY-MM-DD
+  }
+
+  await saveManifest(localeDir, manifest)
+}
+
+/**
+ * Check if a translation is stale (source content changed)
+ *
+ * @param {string} localeDir - Path to locale's freeform directory
+ * @param {string} relativePath - Path relative to locale dir
+ * @param {string} currentSourceHash - Current hash of source content
+ * @returns {Promise<Object>} { isStale, recordedHash, recordedDate, currentHash }
+ */
+export async function checkStaleness(localeDir, relativePath, currentSourceHash) {
+  const manifest = await loadManifest(localeDir)
+  const entry = manifest[relativePath]
+
+  if (!entry) {
+    // No recorded hash - translation was never registered
+    return {
+      isStale: false, // Not stale, just unregistered
+      isNew: true,
+      recordedHash: null,
+      recordedDate: null,
+      currentHash: currentSourceHash
+    }
+  }
+
+  const isStale = entry.hash !== currentSourceHash
+
+  return {
+    isStale,
+    isNew: false,
+    recordedHash: entry.hash,
+    recordedDate: entry.recorded,
+    currentHash: currentSourceHash
+  }
+}
+
+/**
+ * Update the hash for a translation (after translator reviews changes)
+ *
+ * @param {string} localeDir - Path to locale's freeform directory
+ * @param {string} relativePath - Path relative to locale dir
+ * @param {string} newHash - New hash to record
+ * @returns {Promise<void>}
+ */
+export async function updateHash(localeDir, relativePath, newHash) {
+  return recordHash(localeDir, relativePath, newHash)
+}
+
+/**
+ * Remove entries from the manifest
+ *
+ * Used when translations are deleted.
+ *
+ * @param {string} localeDir - Path to locale's freeform directory
+ * @param {string[]} paths - Paths to remove
+ * @returns {Promise<number>} Number of entries removed
+ */
+export async function removeManifestEntries(localeDir, paths) {
+  const manifest = await loadManifest(localeDir)
+  let removed = 0
+
+  for (const path of paths) {
+    if (manifest[path]) {
+      delete manifest[path]
+      removed++
+    }
+  }
+
+  if (removed > 0) {
+    await saveManifest(localeDir, manifest)
+  }
+
+  return removed
+}
+
+/**
+ * Rename entries in the manifest
+ *
+ * Used when translations are moved/renamed.
+ *
+ * @param {string} localeDir - Path to locale's freeform directory
+ * @param {string[]} oldPaths - Old paths
+ * @param {string[]} newPaths - New paths (same order as oldPaths)
+ * @returns {Promise<number>} Number of entries renamed
+ */
+export async function renameManifestEntries(localeDir, oldPaths, newPaths) {
+  if (oldPaths.length !== newPaths.length) {
+    throw new Error('oldPaths and newPaths must have the same length')
+  }
+
+  const manifest = await loadManifest(localeDir)
+  let renamed = 0
+
+  for (let i = 0; i < oldPaths.length; i++) {
+    const oldPath = oldPaths[i]
+    const newPath = newPaths[i]
+
+    if (manifest[oldPath]) {
+      manifest[newPath] = manifest[oldPath]
+      delete manifest[oldPath]
+      renamed++
+    }
+  }
+
+  if (renamed > 0) {
+    await saveManifest(localeDir, manifest)
+  }
+
+  return renamed
+}
+
+/**
+ * Get all stale translations for a locale
+ *
+ * Compares manifest hashes against current source content.
+ *
+ * @param {string} localeDir - Path to locale's freeform directory
+ * @param {Object} sourceHashes - Map of relativePath → currentHash
+ * @returns {Promise<Object[]>} Array of { path, recordedHash, recordedDate, currentHash }
+ */
+export async function getStaleTranslations(localeDir, sourceHashes) {
+  const manifest = await loadManifest(localeDir)
+  const stale = []
+
+  for (const [path, entry] of Object.entries(manifest)) {
+    const currentHash = sourceHashes[path]
+
+    // If we have a current hash and it differs, it's stale
+    if (currentHash && currentHash !== entry.hash) {
+      stale.push({
+        path,
+        recordedHash: entry.hash,
+        recordedDate: entry.recorded,
+        currentHash
+      })
+    }
+  }
+
+  return stale
+}
+
+/**
+ * Get orphaned translations (translations without source)
+ *
+ * @param {string} localeDir - Path to locale's freeform directory
+ * @param {Set<string>} validPaths - Set of valid translation paths that have source content
+ * @returns {Promise<Object[]>} Array of { path, recordedHash, recordedDate }
+ */
+export async function getOrphanedTranslations(localeDir, validPaths) {
+  const manifest = await loadManifest(localeDir)
+  const orphaned = []
+
+  for (const [path, entry] of Object.entries(manifest)) {
+    if (!validPaths.has(path)) {
+      orphaned.push({
+        path,
+        recordedHash: entry.hash,
+        recordedDate: entry.recorded
+      })
+    }
+  }
+
+  return orphaned
+}
+
+/**
+ * Get unregistered translations (translations without manifest entry)
+ *
+ * @param {string} localeDir - Path to locale's freeform directory
+ * @param {string[]} translationPaths - All translation file paths found
+ * @returns {Promise<string[]>} Paths that exist as files but not in manifest
+ */
+export async function getUnregisteredTranslations(localeDir, translationPaths) {
+  const manifest = await loadManifest(localeDir)
+  return translationPaths.filter(path => !manifest[path])
+}

package/src/i18n/freeform.js

@@ -0,0 +1,336 @@
+/**
+ * Free-form Translation Support
+ *
+ * Enables complete content replacement for locales using markdown files,
+ * as an alternative to hash-based string merging. Free-form translations
+ * allow translators to completely reword sections rather than translating
+ * element-by-element.
+ *
+ * Directory structure:
+ *   locales/freeform/{locale}/
+ *     pages/{pageRoute}/{stableId}.md      - By route
+ *     page-ids/{pageId}/{stableId}.md      - By page ID (stable)
+ *     collections/{collectionName}/{slug}.md - Collection items
+ *
+ * Resolution order for sections:
+ *   1. page-ids/{pageId}/{stableId}.md (if page has id:)
+ *   2. pages/{pageRoute}/{stableId}.md
+ *   3. Return null (fall back to granular translation)
+ */
+
+import { readFile, readdir, stat } from 'fs/promises'
+import { existsSync } from 'fs'
+import { join, relative, dirname } from 'path'
+import yaml from 'js-yaml'
+
+// Try to import content-reader for markdown → ProseMirror conversion
+let markdownToProseMirror
+try {
+  const contentReader = await import('@uniweb/content-reader')
+  markdownToProseMirror = contentReader.markdownToProseMirror
+} catch {
+  // Simplified fallback - just wraps content as text
+  markdownToProseMirror = (markdown) => ({
+    type: 'doc',
+    content: [
+      {
+        type: 'paragraph',
+        content: [{ type: 'text', text: markdown.trim() }]
+      }
+    ]
+  })
+}
+
+/**
+ * Parse YAML frontmatter from markdown content
+ * @param {string} content - Raw markdown content
+ * @returns {{ frontmatter: Object, body: string }}
+ */
+function parseFrontmatter(content) {
+  if (!content.trim().startsWith('---')) {
+    return { frontmatter: {}, body: content }
+  }
+
+  const parts = content.split('---\n')
+  if (parts.length < 3) {
+    return { frontmatter: {}, body: content }
+  }
+
+  try {
+    const frontmatter = yaml.load(parts[1]) || {}
+    const body = parts.slice(2).join('---\n')
+    return { frontmatter, body }
+  } catch {
+    return { frontmatter: {}, body: content }
+  }
+}
+
+/**
+ * Normalize route for filesystem path
+ * Removes leading slash, replaces remaining slashes with path separators
+ * @param {string} route - Page route (e.g., '/about/team')
+ * @returns {string} Normalized path (e.g., 'about/team')
+ */
+function normalizeRouteForPath(route) {
+  if (route === '/') return ''
+  return route.replace(/^\//, '').replace(/\//g, '/')
+}
+
+/**
+ * Load free-form translation for a section
+ *
+ * Resolution order:
+ *   1. page-ids/{pageId}/{stableId}.md (if page has id:)
+ *   2. pages/{pageRoute}/{stableId}.md
+ *   3. Return null (fall back to granular)
+ *
+ * @param {Object} section - Section object with stableId
+ * @param {Object} page - Page object with route and optional id
+ * @param {string} locale - Locale code (e.g., 'es', 'fr')
+ * @param {string} localesDir - Path to locales directory
+ * @returns {Promise<Object|null>} Parsed translation { content } or null
+ */
+export async function loadFreeformTranslation(section, page, locale, localesDir) {
+  const stableId = section.stableId
+  if (!stableId) return null
+
+  const freeformDir = join(localesDir, 'freeform', locale)
+  if (!existsSync(freeformDir)) return null
+
+  const candidates = []
+
+  // 1. Try page-ids path (if page has stable id)
+  if (page.id) {
+    candidates.push(join(freeformDir, 'page-ids', page.id, `${stableId}.md`))
+  }
+
+  // 2. Try pages path (by route)
+  const routePath = normalizeRouteForPath(page.route)
+  if (routePath) {
+    candidates.push(join(freeformDir, 'pages', routePath, `${stableId}.md`))
+  } else {
+    // Root page
+    candidates.push(join(freeformDir, 'pages', `${stableId}.md`))
+  }
+
+  // Try each candidate in order
+  for (const filePath of candidates) {
+    if (!existsSync(filePath)) continue
+
+    try {
+      const content = await readFile(filePath, 'utf-8')
+      const { frontmatter, body } = parseFrontmatter(content)
+
+      // Convert markdown body to ProseMirror
+      const proseMirrorContent = markdownToProseMirror(body)
+
+      return {
+        content: proseMirrorContent,
+        frontmatter,
+        filePath,
+        relativePath: relative(join(localesDir, 'freeform', locale), filePath)
+      }
+    } catch (err) {
+      console.warn(`[i18n] Failed to load free-form translation ${filePath}: ${err.message}`)
+      return null
+    }
+  }
+
+  return null
+}
+
+/**
+ * Load free-form translation for a collection item
+ *
+ * Path: collections/{collectionName}/{slug}.md
+ *
+ * @param {Object} item - Collection item with slug
+ * @param {string} collectionName - Name of the collection
+ * @param {string} locale - Locale code
+ * @param {string} localesDir - Path to locales directory
+ * @returns {Promise<Object|null>} Parsed translation { frontmatter, content } or null
+ */
+export async function loadFreeformCollectionItem(item, collectionName, locale, localesDir) {
+  const slug = item.slug
+  if (!slug) return null
+
+  const freeformDir = join(localesDir, 'freeform', locale)
+  if (!existsSync(freeformDir)) return null
+
+  const filePath = join(freeformDir, 'collections', collectionName, `${slug}.md`)
+  if (!existsSync(filePath)) return null
+
+  try {
+    const content = await readFile(filePath, 'utf-8')
+    const { frontmatter, body } = parseFrontmatter(content)
+
+    // Convert markdown body to ProseMirror (if body exists)
+    const proseMirrorContent = body.trim() ? markdownToProseMirror(body) : null
+
+    return {
+      frontmatter: Object.keys(frontmatter).length > 0 ? frontmatter : null,
+      content: proseMirrorContent,
+      filePath,
+      relativePath: relative(join(localesDir, 'freeform', locale), filePath)
+    }
+  } catch (err) {
+    console.warn(`[i18n] Failed to load free-form collection item ${filePath}: ${err.message}`)
+    return null
+  }
+}
+
+/**
+ * Recursively discover all markdown files in a directory
+ * @param {string} dir - Directory to scan
+ * @param {string} baseDir - Base directory for relative paths
+ * @returns {Promise<string[]>} Array of relative paths
+ */
+async function discoverMarkdownFiles(dir, baseDir) {
+  const files = []
+
+  if (!existsSync(dir)) return files
+
+  const entries = await readdir(dir, { withFileTypes: true })
+
+  for (const entry of entries) {
+    const fullPath = join(dir, entry.name)
+
+    if (entry.isDirectory()) {
+      const subFiles = await discoverMarkdownFiles(fullPath, baseDir)
+      files.push(...subFiles)
+    } else if (entry.isFile() && entry.name.endsWith('.md')) {
+      files.push(relative(baseDir, fullPath))
+    }
+  }
+
+  return files
+}
+
+/**
+ * Discover all free-form translation files for a locale
+ *
+ * Used by status commands to show what translations exist.
+ *
+ * @param {string} locale - Locale code
+ * @param {string} localesDir - Path to locales directory
+ * @returns {Promise<Object>} { pages: string[], pageIds: string[], collections: string[] }
+ */
+export async function discoverFreeformTranslations(locale, localesDir) {
+  const freeformDir = join(localesDir, 'freeform', locale)
+
+  const result = {
+    pages: [],
+    pageIds: [],
+    collections: []
+  }
+
+  if (!existsSync(freeformDir)) return result
+
+  // Discover pages translations
+  const pagesDir = join(freeformDir, 'pages')
+  if (existsSync(pagesDir)) {
+    result.pages = await discoverMarkdownFiles(pagesDir, pagesDir)
+  }
+
+  // Discover page-ids translations
+  const pageIdsDir = join(freeformDir, 'page-ids')
+  if (existsSync(pageIdsDir)) {
+    result.pageIds = await discoverMarkdownFiles(pageIdsDir, pageIdsDir)
+  }
+
+  // Discover collection translations
+  const collectionsDir = join(freeformDir, 'collections')
+  if (existsSync(collectionsDir)) {
+    result.collections = await discoverMarkdownFiles(collectionsDir, collectionsDir)
+  }
+
+  return result
+}
+
+/**
+ * Get metadata for a free-form translation file
+ *
+ * @param {string} filePath - Full path to translation file
+ * @returns {Promise<Object>} { mtime, size }
+ */
+export async function getFreeformFileMeta(filePath) {
+  if (!existsSync(filePath)) return null
+
+  const stats = await stat(filePath)
+  return {
+    mtime: stats.mtime.toISOString(),
+    size: stats.size
+  }
+}
+
+/**
+ * Parse a free-form translation file path to extract metadata
+ *
+ * @param {string} relativePath - Path relative to locale's freeform dir
+ * @returns {Object} { type, pageRoute?, pageId?, collectionName?, stableId, slug? }
+ */
+export function parseFreeformPath(relativePath) {
+  const parts = relativePath.split('/')
+
+  if (parts[0] === 'pages') {
+    // pages/about/hero.md → { type: 'page', pageRoute: '/about', stableId: 'hero' }
+    const stableId = parts[parts.length - 1].replace('.md', '')
+    const routeParts = parts.slice(1, -1)
+    const pageRoute = routeParts.length > 0 ? '/' + routeParts.join('/') : '/'
+    return { type: 'page', pageRoute, stableId }
+  }
+
+  if (parts[0] === 'page-ids') {
+    // page-ids/installation/intro.md → { type: 'pageId', pageId: 'installation', stableId: 'intro' }
+    const stableId = parts[parts.length - 1].replace('.md', '')
+    const pageId = parts.slice(1, -1).join('/')
+    return { type: 'pageId', pageId, stableId }
+  }
+
+  if (parts[0] === 'collections') {
+    // collections/articles/getting-started.md → { type: 'collection', collectionName: 'articles', slug: 'getting-started' }
+    const slug = parts[parts.length - 1].replace('.md', '')
+    const collectionName = parts[1]
+    return { type: 'collection', collectionName, slug }
+  }
+
+  return { type: 'unknown', relativePath }
+}
+
+/**
+ * Build the expected free-form translation path for a section
+ *
+ * @param {Object} section - Section with stableId
+ * @param {Object} page - Page with route and optional id
+ * @param {boolean} preferPageId - Whether to prefer page-ids/ over pages/
+ * @returns {string} Relative path (e.g., 'pages/about/hero.md')
+ */
+export function buildFreeformPath(section, page, preferPageId = true) {
+  const stableId = section.stableId
+  if (!stableId) return null
+
+  // Prefer page-ids if page has stable id
+  if (preferPageId && page.id) {
+    return `page-ids/${page.id}/${stableId}.md`
+  }
+
+  // Fall back to route-based path
+  const routePath = normalizeRouteForPath(page.route)
+  if (routePath) {
+    return `pages/${routePath}/${stableId}.md`
+  }
+
+  // Root page
+  return `pages/${stableId}.md`
+}
+
+/**
+ * Build the expected free-form translation path for a collection item
+ *
+ * @param {string} collectionName - Name of the collection
+ * @param {string} slug - Item slug
+ * @returns {string} Relative path (e.g., 'collections/articles/getting-started.md')
+ */
+export function buildFreeformCollectionPath(collectionName, slug) {
+  return `collections/${collectionName}/${slug}.md`
+}

package/src/i18n/index.js

@@ -24,6 +24,30 @@ import {
 } from './collections.js'
 import { generateSearchIndex, isSearchEnabled } from '../search/index.js'
 
+// Free-form translation support
+import {
+  loadFreeformTranslation,
+  loadFreeformCollectionItem,
+  discoverFreeformTranslations,
+  getFreeformFileMeta,
+  parseFreeformPath,
+  buildFreeformPath,
+  buildFreeformCollectionPath
+} from './freeform.js'
+import {
+  computeSourceHash,
+  loadManifest as loadFreeformManifest,
+  saveManifest as saveFreeformManifest,
+  recordHash,
+  checkStaleness,
+  updateHash,
+  removeManifestEntries,
+  renameManifestEntries,
+  getStaleTranslations,
+  getOrphanedTranslations,
+  getUnregisteredTranslations
+} from './freeform-manifest.js'
+
 export {
   // Hash utilities
   computeHash,
@@ -49,7 +73,29 @@ export {
 
   // Locale resolution
   getAvailableLocales,
-  resolveLocales
+  resolveLocales,
+
+  // Free-form translation functions
+  loadFreeformTranslation,
+  loadFreeformCollectionItem,
+  discoverFreeformTranslations,
+  getFreeformFileMeta,
+  parseFreeformPath,
+  buildFreeformPath,
+  buildFreeformCollectionPath,
+
+  // Free-form manifest functions
+  computeSourceHash,
+  loadFreeformManifest,
+  saveFreeformManifest,
+  recordHash,
+  checkStaleness,
+  updateHash,
+  removeManifestEntries,
+  renameManifestEntries,
+  getStaleTranslations,
+  getOrphanedTranslations,
+  getUnregisteredTranslations
 }
 
 /**
@@ -278,7 +324,8 @@ export async function getTranslationStatus(siteRoot, options = {}) {
  * Build translated site content for all locales
  * @param {string} siteRoot - Site root directory
  * @param {Object} options - Options
- * @param {boolean} [options.generateSearchIndex=true] - Generate search indexes for each locale
+ * @param {boolean} [options.generateSearchIndexes=true] - Generate search indexes for each locale
+ * @param {boolean} [options.freeformEnabled=true] - Enable free-form translation support
  * @returns {Object} Map of locale to output paths
  */
 export async function buildLocalizedContent(siteRoot, options = {}) {
@@ -287,7 +334,8 @@ export async function buildLocalizedContent(siteRoot, options = {}) {
     locales = [],
     outputDir = join(siteRoot, 'dist'),
     fallbackToSource = true,
-    generateSearchIndexes = true
+    generateSearchIndexes = true,
+    freeformEnabled = true
   } = options
 
   const localesPath = join(siteRoot, localesDir)
@@ -309,10 +357,29 @@ export async function buildLocalizedContent(siteRoot, options = {}) {
       translations = JSON.parse(localeRaw)
     }
 
-    // Merge translations
-    const translated = mergeTranslations(siteContent, translations, {
-      fallbackToSource
-    })
+    // Check if free-form translations exist for this locale
+    const freeformDir = join(localesPath, 'freeform', locale)
+    const hasFreeform = freeformEnabled && existsSync(freeformDir)
+
+    // Merge translations (with free-form support if enabled)
+    let translated
+    if (hasFreeform) {
+      // Use async merge with free-form support
+      translated = await mergeTranslations(siteContent, translations, {
+        fallbackToSource,
+        locale,
+        localesDir: localesPath,
+        freeformEnabled: true
+      })
+
+      // Check for stale/orphaned free-form translations and warn
+      await warnAboutFreeformIssues(locale, freeformDir, siteContent)
+    } else {
+      // Use sync merge (original behavior)
+      translated = mergeTranslations(siteContent, translations, {
+        fallbackToSource
+      })
+    }
 
     // Mark the active locale in the translated content
     translated.config = { ...translated.config, activeLocale: locale }
@@ -346,6 +413,63 @@ export async function buildLocalizedContent(siteRoot, options = {}) {
   return outputs
 }
 
+/**
+ * Check for stale/orphaned free-form translations and emit warnings
+ * @param {string} locale - Locale code
+ * @param {string} freeformDir - Path to locale's freeform directory
+ * @param {Object} siteContent - Site content for building source hashes
+ */
+async function warnAboutFreeformIssues(locale, freeformDir, siteContent) {
+  try {
+    // Build map of valid source hashes
+    const sourceHashes = {}
+    const validPaths = new Set()
+
+    for (const page of siteContent.pages || []) {
+      for (const section of page.sections || []) {
+        if (section.stableId) {
+          const path = buildFreeformPath(section, page)
+          if (path) {
+            validPaths.add(path)
+            // Compute source hash for staleness check
+            if (section.content) {
+              sourceHashes[path] = computeSourceHash(section.content)
+            }
+          }
+        }
+      }
+    }
+
+    // Check for stale translations
+    const stale = await getStaleTranslations(freeformDir, sourceHashes)
+    for (const item of stale) {
+      console.warn(`[i18n] Free-form translation stale: ${locale}/${item.path} (source changed ${item.recordedDate})`)
+    }
+
+    // Check for orphaned translations
+    const orphaned = await getOrphanedTranslations(freeformDir, validPaths)
+    for (const item of orphaned) {
+      console.warn(`[i18n] Free-form translation orphaned: ${locale}/${item.path}`)
+    }
+
+    // Check for unregistered translations (new files)
+    const discovered = await discoverFreeformTranslations(locale, dirname(dirname(freeformDir)))
+    const allPaths = [...discovered.pages, ...discovered.pageIds, ...discovered.collections]
+    const unregistered = await getUnregisteredTranslations(freeformDir, allPaths)
+    for (const path of unregistered) {
+      // Auto-register new free-form translations
+      const sourcePath = validPaths.has(path) ? path : null
+      if (sourcePath && sourceHashes[sourcePath]) {
+        await recordHash(freeformDir, path, sourceHashes[sourcePath])
+        console.log(`[i18n] Free-form translation registered: ${locale}/${path} (new file)`)
+      }
+    }
+  } catch (err) {
+    // Non-fatal: just log and continue
+    console.warn(`[i18n] Could not check free-form translation status for ${locale}: ${err.message}`)
+  }
+}
+
 /**
  * Format translation status for console output
  * @param {Object} status - Status from getTranslationStatus

package/src/i18n/merge.js

@@ -3,20 +3,55 @@
  *
  * Takes site-content.json and locale translations,
  * produces translated site-content for each locale.
+ *
+ * Supports two translation modes:
+ * 1. Hash-based (granular): Translate individual strings by hash lookup
+ * 2. Free-form: Complete content replacement from markdown files
+ *
+ * Free-form translations are checked first, falling back to hash-based
+ * when no free-form translation exists.
  */
 
 import { computeHash } from './hash.js'
+import { loadFreeformTranslation } from './freeform.js'
 
 /**
  * Merge translations into site content for a specific locale
+ *
  * @param {Object} siteContent - Original site-content.json
  * @param {Object} translations - Locale translations (hash -> translation)
  * @param {Object} options - Merge options
- * @returns {Object} Translated site content
+ * @param {boolean} [options.fallbackToSource=true] - Return source if no translation
+ * @param {string} [options.locale] - Locale code for free-form lookups
+ * @param {string} [options.localesDir] - Path to locales directory
+ * @param {boolean} [options.freeformEnabled=false] - Enable free-form translation lookup
+ * @returns {Object|Promise<Object>} Translated site content (async if freeformEnabled)
  */
 export function mergeTranslations(siteContent, translations, options = {}) {
-  const { fallbackToSource = true } = options
+  const {
+    fallbackToSource = true,
+    locale = null,
+    localesDir = null,
+    freeformEnabled = false
+  } = options
 
+  // If free-form is enabled, use async version
+  if (freeformEnabled && locale && localesDir) {
+    return mergeTranslationsAsync(siteContent, translations, {
+      fallbackToSource,
+      locale,
+      localesDir
+    })
+  }
+
+  // Sync version (original behavior)
+  return mergeTranslationsSync(siteContent, translations, fallbackToSource)
+}
+
+/**
+ * Synchronous merge (original behavior, no free-form)
+ */
+function mergeTranslationsSync(siteContent, translations, fallbackToSource) {
   // Deep clone to avoid mutating original
   const translated = JSON.parse(JSON.stringify(siteContent))
 
@@ -28,7 +63,35 @@ export function mergeTranslations(siteContent, translations, options = {}) {
 
     // Translate section content
     for (const section of page.sections || []) {
-      translateSection(section, pageRoute, translations, fallbackToSource)
+      translateSectionSync(section, pageRoute, translations, fallbackToSource)
+    }
+  }
+
+  return translated
+}
+
+/**
+ * Asynchronous merge with free-form support
+ */
+async function mergeTranslationsAsync(siteContent, translations, options) {
+  const { fallbackToSource, locale, localesDir } = options
+
+  // Deep clone to avoid mutating original
+  const translated = JSON.parse(JSON.stringify(siteContent))
+
+  for (const page of translated.pages || []) {
+    const pageRoute = page.route || '/'
+
+    // Translate page metadata (always hash-based)
+    translatePageMeta(page, pageRoute, translations, fallbackToSource)
+
+    // Translate section content (with free-form check)
+    for (const section of page.sections || []) {
+      await translateSectionAsync(section, page, translations, {
+        fallbackToSource,
+        locale,
+        localesDir
+      })
     }
   }
 
@@ -77,9 +140,9 @@ function translatePageMeta(page, pageRoute, translations, fallbackToSource) {
 }
 
 /**
- * Translate a section's content
+ * Translate a section's content (synchronous, hash-based only)
  */
-function translateSection(section, pageRoute, translations, fallbackToSource) {
+function translateSectionSync(section, pageRoute, translations, fallbackToSource) {
   const sectionId = section.id || 'unknown'
   const context = { page: pageRoute, section: sectionId }
 
@@ -89,7 +152,40 @@ function translateSection(section, pageRoute, translations, fallbackToSource) {
 
   // Recursively translate subsections
   for (const subsection of section.subsections || []) {
-    translateSection(subsection, pageRoute, translations, fallbackToSource)
+    translateSectionSync(subsection, pageRoute, translations, fallbackToSource)
+  }
+}
+
+/**
+ * Translate a section's content (async, with free-form check)
+ *
+ * Resolution order:
+ * 1. Check for free-form translation (complete replacement)
+ * 2. Fall back to hash-based translation (element-by-element)
+ */
+async function translateSectionAsync(section, page, translations, options) {
+  const { fallbackToSource, locale, localesDir } = options
+  const pageRoute = page.route || '/'
+  const sectionId = section.id || 'unknown'
+  const context = { page: pageRoute, section: sectionId }
+
+  // Check for free-form translation first
+  const freeform = await loadFreeformTranslation(section, page, locale, localesDir)
+
+  if (freeform) {
+    // Complete content replacement
+    section.content = freeform.content
+    // Note: We could also merge frontmatter into params here if needed
+  } else {
+    // Fall back to hash-based translation
+    if (section.content?.type === 'doc') {
+      translateProseMirrorDoc(section.content, context, translations, fallbackToSource)
+    }
+  }
+
+  // Recursively translate subsections
+  for (const subsection of section.subsections || []) {
+    await translateSectionAsync(subsection, page, translations, options)
   }
 }
 

package/src/prerender.js

@@ -301,8 +301,7 @@ function renderBlock(block) {
   const componentProps = {
     content,
     params,
-    block,
-    input: block.input
+    block
   }
 
   // Wrapper props

package/src/site/content-collector.js

@@ -523,7 +523,6 @@ async function processPage(pagePath, pageName, siteRoot, { isIndex = false, pare
       title: pageConfig.title || pageName,
       description: pageConfig.description || '',
       label: pageConfig.label || null, // Short label for navigation (defaults to title)
-      order: pageConfig.order,
       lastModified: lastModified?.toISOString(),
 
       // Dynamic route metadata
@@ -599,8 +598,9 @@ function determineIndexPage(orderConfig, availableFolders) {
 
   const sorted = [...staticFolders].sort((a, b) => {
     // Sort by order (lower first), then alphabetically
-    const orderA = a.order ?? 999
-    const orderB = b.order ?? 999
+    // Pages without explicit order come after ordered pages
+    const orderA = a.order ?? Infinity
+    const orderB = b.order ?? Infinity
     if (orderA !== orderB) return orderA - orderB
     return a.name.localeCompare(b.name)
   })
@@ -655,6 +655,15 @@ async function collectPagesRecursive(dirPath, parentRoute, siteRoot, orderConfig
     })
   }
 
+  // Sort page folders by order (ascending), then alphabetically
+  // Pages without explicit order come after ordered pages (order ?? Infinity)
+  pageFolders.sort((a, b) => {
+    const orderA = a.order ?? Infinity
+    const orderB = b.order ?? Infinity
+    if (orderA !== orderB) return orderA - orderB
+    return a.name.localeCompare(b.name)
+  })
+
   // Check if this directory contains version folders (versioned section)
   const folderNames = pageFolders.map(f => f.name)
   const detectedVersions = detectVersions(folderNames)

package/src/site/plugin.js

@@ -93,16 +93,20 @@ async function processDevSectionFetches(sections, cascadedData, fetchOptions) {
     if (sectionFetch) {
       const result = await executeFetch(sectionFetch, fetchOptions)
       if (result.data && !result.error) {
-        // Merge fetched data into cascadedData for this section
-        cascadedData = {
-          ...cascadedData,
-          [sectionFetch.schema]: result.data
-        }
+        // Merge fetched data into section's parsedContent (not cascadedData)
+        // This matches prerender behavior - section's own fetch goes to content.data
+        section.parsedContent = mergeDataIntoContent(
+          section.parsedContent || {},
+          result.data,
+          sectionFetch.schema,
+          sectionFetch.merge
+        )
       }
     }
 
-    // Attach cascaded data to section
-    section.cascadedData = { ...cascadedData }
+    // Attach cascaded data for components with inheritData
+    // Note: cascadedData is from page/site level only, not section's own fetch
+    section.cascadedData = cascadedData
 
     // Process subsections recursively
     if (section.subsections && section.subsections.length > 0) {
@@ -395,14 +399,30 @@ export function siteContentPlugin(options = {}) {
 
   /**
    * Get translated content for a locale
+   *
+   * Supports both hash-based (granular) and free-form (complete replacement) translations.
+   * Free-form translations are checked first, falling back to hash-based when not found.
    */
   async function getTranslatedContent(locale) {
     if (!siteContent) return null
 
     const translations = await loadLocaleTranslations(locale)
-    if (!translations) return null
-
-    return mergeTranslations(siteContent, translations)
+    // Even with no hash-based translations, free-form might exist
+    const hasTranslations = translations !== null
+
+    // Check if free-form translations exist for this locale
+    const freeformDir = join(resolvedSitePath, localesDir, 'freeform', locale)
+    const hasFreeform = existsSync(freeformDir)
+
+    // If no translations at all (neither hash-based nor free-form), return null
+    if (!hasTranslations && !hasFreeform) return null
+
+    // Use free-form enabled merge
+    return mergeTranslations(siteContent, translations || {}, {
+      locale,
+      localesDir: join(resolvedSitePath, localesDir),
+      freeformEnabled: hasFreeform
+    })
   }
 
   return {
@@ -570,6 +590,8 @@ export function siteContentPlugin(options = {}) {
 
       // Watch locales directory for translation changes
       const localesPath = resolve(resolvedSitePath, localesDir)
+      const additionalWatchers = []
+
       if (existsSync(localesPath)) {
         try {
           const localeWatcher = watch(localesPath, { recursive: false }, () => {
@@ -577,17 +599,35 @@ export function siteContentPlugin(options = {}) {
             localeTranslations = {}
             server.ws.send({ type: 'full-reload' })
           })
-          if (watcher) {
-            const originalClose = watcher.close
-            watcher.close = () => {
-              originalClose()
-              localeWatcher.close()
-            }
-          }
+          additionalWatchers.push(localeWatcher)
           console.log(`[site-content] Watching ${localesPath} for translation changes`)
         } catch (err) {
           // locales dir may not exist, that's ok
         }
+
+        // Watch free-form translations directory
+        const freeformPath = resolve(localesPath, 'freeform')
+        if (existsSync(freeformPath)) {
+          try {
+            const freeformWatcher = watch(freeformPath, { recursive: true }, () => {
+              console.log('[site-content] Free-form translation changed, reloading...')
+              server.ws.send({ type: 'full-reload' })
+            })
+            additionalWatchers.push(freeformWatcher)
+            console.log(`[site-content] Watching ${freeformPath} for free-form translation changes`)
+          } catch (err) {
+            // freeform dir may not exist, that's ok
+          }
+        }
+      }
+
+      // Add additional watchers to cleanup
+      if (additionalWatchers.length > 0 && watcher) {
+        const originalClose = watcher.close
+        watcher.close = () => {
+          originalClose()
+          additionalWatchers.forEach(w => w.close())
+        }
       }
 
       // Serve content and SEO files