@uniweb/build 0.15.13 → 0.16.0

package/src/site/build-site-data.js

@@ -21,7 +21,7 @@ import { writeFile, readFile, mkdir, cp } from 'node:fs/promises'
 import { existsSync } from 'node:fs'
 import { join, resolve, dirname } from 'node:path'
 
-import { resolveDefaultLocale } from '@uniweb/core'
+import { resolveDefaultLocale, DATA_DIR } from '@uniweb/core'
 import { collectSiteContent } from './content-collector.js'
 import { processCollections, writeCollectionFiles } from './collection-processor.js'
 import { processAssets, rewriteSiteContentPaths } from './asset-processor.js'
@@ -35,7 +35,9 @@ import {
   renderPageMarkdown,
   resolveAgentsConfig,
   selectIndexablePages,
+  selectIndexBranches,
   pageMarkdownFilename,
+  branchIndexFilename,
   INDEX_FILENAME
 } from '@uniweb/projections'
 
@@ -133,8 +135,8 @@ export async function buildSiteData({
     )
     await writeCollectionFiles(resolvedSiteRoot, collections, siteContent.config.collections)
 
-    const publicDataDir = join(resolvedSiteRoot, 'public', 'data')
-    const distDataDir = join(resolvedDistDir, 'data')
+    const publicDataDir = join(resolvedSiteRoot, 'public', DATA_DIR)
+    const distDataDir = join(resolvedDistDir, DATA_DIR)
     if (existsSync(publicDataDir)) {
       await cp(publicDataDir, distDataDir, { recursive: true })
     }
@@ -228,7 +230,7 @@ export async function buildSiteData({
     const collectionIndexes = []
     for (const [collName, collConfig] of Object.entries(collections)) {
       if (!collConfig.search?.enabled || !collConfig.route) continue
-      const cascadeFile = join(resolvedDistDir, 'data', `${collName}.json`)
+      const cascadeFile = join(resolvedDistDir, DATA_DIR, `${collName}.json`)
       if (!existsSync(cascadeFile)) continue
       let collectionData
       try {
@@ -297,6 +299,23 @@ async function writeProjections(siteContent, distDir) {
   if (agents.index) {
     const index = renderSiteIndex(siteContent, { ...options, exclude: agents.exclude })
     await writeFile(join(distDir, INDEX_FILENAME), index)
+
+    // Additive scoped indexes; the root one above stays complete. See
+    // `selectIndexBranches` for why this is not a delegation.
+    if (agents.branchIndexes) {
+      const branches = selectIndexBranches(siteContent.pages, {
+        exclude: agents.exclude,
+        minPages: agents.branchMinPages
+      })
+      for (const branch of branches) {
+        const target = join(distDir, branchIndexFilename(branch.route))
+        await mkdir(dirname(target), { recursive: true })
+        await writeFile(
+          target,
+          renderSiteIndex(siteContent, { ...options, exclude: agents.exclude, branch: branch.route })
+        )
+      }
+    }
   }
 
   if (!agents.markdown) return

package/src/site/collection-processor.js

@@ -32,11 +32,12 @@
  * await writeCollectionFiles(siteDir, collections)
  */
 
-import { readFile, readdir, stat, writeFile, mkdir, copyFile } from 'node:fs/promises'
-import { join, basename, extname, dirname, relative, resolve } from 'node:path'
+import { readFile, readdir, stat, writeFile, mkdir, copyFile, rm } from 'node:fs/promises'
+import { join, basename, extname, dirname, relative, resolve, sep } from 'node:path'
 import { existsSync } from 'node:fs'
 import yaml from 'js-yaml'
 import { parseBibtex } from '@citestyle/bibtex'
+import { DATA_DIR } from '@uniweb/core'
 import { applyFilter, applySort } from './data-fetcher.js'
 import { resolveAssetPath, walkContentAssets, isLocalAssetPath } from './assets.js'
 
@@ -642,6 +643,62 @@ export async function processCollections(siteDir, collectionsConfig, collections
   return results
 }
 
+/**
+ * Reconcile a deferred collection's per-record directory with the records it
+ * should hold this run — delete the `<slug>.json` files that are no longer
+ * backed by a record.
+ *
+ * Why this is not optional. `public/data/` is a persistent, normally-committed
+ * directory, so anything written there survives until something removes it.
+ * Without this, unpublishing a record (`published: false`, which the build
+ * honours automatically) or deleting its source file drops it from the cascade
+ * listing — it vanishes from the site — while its per-record file stays on
+ * disk with the full body, gets committed, and gets deployed. The author has
+ * every reason to believe the content is gone. It is still fetchable at a URL
+ * that was public a moment ago.
+ *
+ * `public/data/` is the build's output directory and nothing else — authors
+ * provide structured data through `collections/`, which is the only supported
+ * way. So `<name>/` is entirely ours and the reconciliation is total: anything
+ * in it that this run did not write is stale by definition. `expected` is
+ * empty when a collection stops declaring `deferred:`, which correctly clears
+ * a directory that will otherwise never be written again.
+ *
+ * NOT covered: a collection removed from `site.yml` entirely. There is no
+ * declaration left to reconcile against, so pruning it would mean the build
+ * asserting ownership of a directory on a name match alone. That needs the
+ * ownership question answered on purpose, not as a side effect of this.
+ *
+ * @param {string} dataDir - `public/data/`, the containing output directory
+ * @param {string} name - the declared collection name
+ * @param {Set<string>} expected - filenames this run wrote, e.g. `hello.json`
+ * @returns {Promise<string[]>} the entry names removed
+ */
+async function pruneOrphanedRecords(dataDir, name, expected) {
+  const recordsDir = join(dataDir, name)
+
+  // This routine deletes, and `name` reaches it from site.yml. A name that
+  // resolves outside the output directory would make the traversal somebody
+  // else's files, so refuse rather than trust the caller.
+  const contained = resolve(recordsDir)
+  if (contained !== resolve(dataDir, name) || !contained.startsWith(resolve(dataDir) + sep)) {
+    console.warn(
+      `[collection-processor] Refusing to prune "${name}" — it does not resolve ` +
+      `inside ${dataDir}`
+    )
+    return []
+  }
+  if (!existsSync(recordsDir)) return []
+
+  const removed = []
+  for (const entry of await readdir(recordsDir, { withFileTypes: true })) {
+    if (expected.has(entry.name)) continue
+    await rm(join(recordsDir, entry.name), { recursive: true, force: true })
+    removed.push(entry.isDirectory() ? `${entry.name}/` : entry.name)
+  }
+  return removed
+}
+
 /**
  * Write collection data to JSON files in public/data/
  *
@@ -660,7 +717,7 @@ export async function writeCollectionFiles(siteDir, collections, collectionsConf
     return
   }
 
-  const dataDir = join(siteDir, 'public', 'data')
+  const dataDir = join(siteDir, 'public', DATA_DIR)
   await mkdir(dataDir, { recursive: true })
 
   for (const [name, items] of Object.entries(collections)) {
@@ -677,13 +734,15 @@ export async function writeCollectionFiles(siteDir, collections, collectionsConf
       const recordsDir = join(dataDir, name)
       await mkdir(recordsDir, { recursive: true })
 
-      let perRecordCount = 0
+      const written = new Set()
       for (const item of items) {
         if (!item || typeof item !== 'object' || !item.slug) continue
-        const recordPath = join(recordsDir, `${item.slug}.json`)
-        await writeFile(recordPath, JSON.stringify(item, null, 2))
-        perRecordCount++
+        const filename = `${item.slug}.json`
+        await writeFile(join(recordsDir, filename), JSON.stringify(item, null, 2))
+        written.add(filename)
       }
+      const perRecordCount = written.size
+      const pruned = await pruneOrphanedRecords(dataDir, name, written)
 
       const stripped = items.map((item) => {
         if (!item || typeof item !== 'object') return item
@@ -697,10 +756,29 @@ export async function writeCollectionFiles(siteDir, collections, collectionsConf
         `[collection-processor] Generated ${cascadePath} (${items.length} items, ` +
         `deferred: [${deferred.join(', ')}]) + ${perRecordCount} per-record files`
       )
+      if (pruned.length > 0) {
+        // A deletion is always worth naming. These files were public a moment
+        // ago, so "which ones went" is the question an author will have.
+        console.log(
+          `[collection-processor] Removed ${pruned.length} stale per-record ` +
+          `file(s) from ${recordsDir}: ${pruned.join(', ')}`
+        )
+      }
     } else {
       const filepath = join(dataDir, `${name}.json`)
       await writeFile(filepath, JSON.stringify(items, null, 2))
       console.log(`[collection-processor] Generated ${filepath} (${items.length} items)`)
+
+      // This collection is not deferred, so it has no per-record files. If it
+      // used to, the directory is still there and will never be written again
+      // — every file in it is stale. Same reconciliation, empty expected set.
+      const pruned = await pruneOrphanedRecords(dataDir, name, new Set())
+      if (pruned.length > 0) {
+        console.log(
+          `[collection-processor] Removed ${pruned.length} per-record file(s) ` +
+          `from ${join(dataDir, name)} — "${name}" no longer declares deferred:`
+        )
+      }
     }
   }
 }

package/src/site/content-collector.js

@@ -2152,9 +2152,10 @@ export async function collectSiteContent(sitePath, options = {}) {
   // base prefix while the hydrated browser routes were fine.
   //
   // Only a real base is written. At '/' the field stays absent, because in
-  // shell mode `config.base` is the SERVING layer's channel (it injects the
-  // served subpath, e.g. /gateway/site/<uuid>/) and a build-time '/' would
-  // be a meaningless value sitting in its slot.
+  // shell mode `config.base` is the SERVING layer's channel — the host injects
+  // whatever subpath it serves the site under, and a build-time '/' would be a
+  // meaningless value sitting in its slot. The build deliberately does not model
+  // what that subpath looks like; that is the host's shape, not ours.
   if (base && base !== '/') {
     siteConfig.base = base
   }

package/src/site/data-ball.js

@@ -19,6 +19,7 @@
 import { existsSync } from 'node:fs'
 import { readFile, readdir } from 'node:fs/promises'
 import { join, relative, sep } from 'node:path'
+import { DATA_DIR } from '@uniweb/core'
 import { isLocalAssetPath } from './assets.js'
 
 // Walk a dist subdir for *.json → { "<posix-relpath>": <parsedJson> }. Unparseable
@@ -58,7 +59,7 @@ function collectionOf(relPath) {
  */
 export async function assembleDataBall(distDir, schemalessNames = []) {
   const schemaless = new Set(schemalessNames)
-  const allData = await readJsonTree(join(distDir, 'data'))
+  const allData = await readJsonTree(join(distDir, DATA_DIR))
   const data = {}
   for (const [relPath, value] of Object.entries(allData)) {
     if (schemaless.has(collectionOf(relPath))) data[relPath] = value

package/src/site/data-fetcher.js

@@ -20,7 +20,7 @@ import { readFile } from 'node:fs/promises'
 import { join } from 'node:path'
 import { existsSync } from 'node:fs'
 import yaml from 'js-yaml'
-import { matchWhere } from '@uniweb/core'
+import { matchWhere, collectionDataUrl } from '@uniweb/core'
 
 /**
  * Infer schema name from path or URL
@@ -290,7 +290,7 @@ export function parseFetchConfig(fetch) {
   if (fetch.collection) {
     if (fetch.filter !== undefined) warnFilterDeprecated()
     return {
-      path: `/data/${fetch.collection}.json`,
+      path: collectionDataUrl(fetch.collection),
       url: undefined,
       schema: fetch.schema || fetch.collection,
       prerender: fetch.prerender ?? true,

package/src/site/head-markers.js

@@ -1,16 +1,26 @@
 /**
  * Stable markers for head content the build injects.
  *
- * Two stages can write the same block: the vite plugin's `transformIndexHtml`
- * (which produces `dist/index.html`) and the prerenderer (which post-processes
- * that HTML per page). The marker lets the second stage tell "already injected"
- * from "never injected" instead of guessing, so a page rendered through both
- * paths gets exactly one copy.
+ * Several stages can write the same block: this package's vite plugin
+ * (`transformIndexHtml`, which produces `dist/index.html`), this package's
+ * prerenderer (which post-processes that HTML per page), and — since the
+ * 2026-07-28 seam fix — `@uniweb/runtime`'s `injectPageContent()`, the prerender
+ * seam every lane shares. The marker lets a later stage tell "already injected"
+ * from "never injected" instead of guessing, so a page passing through several
+ * gets exactly one copy.
  *
  * The theme CSS uses `id="uniweb-theme"` on its <style> for the same purpose;
  * <link> tags have no natural id to hang that on, hence the comment marker.
  *
+ * **The marker itself now lives in `@uniweb/theming`**, beside the code that
+ * generates the block it delimits. This package and `@uniweb/runtime` cannot
+ * import one another, but both depend on `@uniweb/theming` — so that is the one
+ * home neither has to reach across a dependency boundary to read, and the
+ * literal is never duplicated (two halves of a dedupe check that drift apart
+ * stop deduping, silently). Re-exported here so every existing import in this
+ * package keeps working unchanged.
+ *
  * @module @uniweb/build/site
  */
 
-export const FONT_LINKS_MARKER = '<!--uniweb-fonts-->'
+export { FONT_LINKS_MARKER } from '@uniweb/theming'

package/src/site/plugin.js

@@ -33,13 +33,15 @@
 import { resolve, join } from 'node:path'
 import { watch, existsSync } from 'node:fs'
 import { readFile, readdir } from 'node:fs/promises'
-import { resolveDefaultLocale } from '@uniweb/core'
+import { resolveDefaultLocale, DATA_DIR } from '@uniweb/core'
 import {
   renderSiteIndex,
   renderPageMarkdown,
   resolveAgentsConfig,
   selectIndexablePages,
+  selectIndexBranches,
   pageMarkdownFilename,
+  branchIndexFilename,
   applyRouteTranslation,
   INDEX_FILENAME
 } from '@uniweb/projections'
@@ -275,19 +277,68 @@ function escapeXml(str) {
     .replace(/'/g, ''')
 }
 
+/** The three defined Content Signals, in the order they are emitted. */
+const CONTENT_SIGNAL_KEYS = ['search', 'ai-input', 'ai-train']
+
+/**
+ * Format the `Content-Signal:` directive from `seo.robots.contentSignals`.
+ *
+ * Content Signals express what a site permits its content to be *used for*,
+ * which is a different axis from `Disallow:` — that governs fetching, this
+ * governs use after fetching. The three defined signals:
+ *
+ * - `search`    — appear in search results
+ * - `ai-input`  — be retrieved at inference time (RAG, grounding)
+ * - `ai-train`  — be used to train a model
+ *
+ * **Emitted only when declared.** There is no default: a preference the site
+ * owner did not state is not ours to assert, in either direction. An absent
+ * signal means "unstated", which is not the same as `no`.
+ *
+ * Unknown keys are ignored rather than passed through — the vocabulary is a
+ * closed set, and forwarding an invented signal would produce a directive no
+ * crawler honors while reading as though it were doing something.
+ *
+ * @param {Object|null} signals - e.g. `{ search: true, 'ai-input': true, 'ai-train': false }`
+ * @returns {string} The directive line, or `''` when nothing is declared
+ */
+export function formatContentSignals(signals) {
+  if (!signals || typeof signals !== 'object') return ''
+
+  const parts = []
+  for (const key of CONTENT_SIGNAL_KEYS) {
+    if (!(key in signals)) continue
+    const value = signals[key]
+    const yes = value === true || value === 'yes'
+    const no = value === false || value === 'no'
+    if (!yes && !no) continue
+    parts.push(`${key}=${yes ? 'yes' : 'no'}`)
+  }
+
+  return parts.length ? `Content-Signal: ${parts.join(', ')}` : ''
+}
+
 /**
  * Generate robots.txt content
  */
-function generateRobotsTxt(baseUrl, options = {}) {
+export function generateRobotsTxt(baseUrl, options = {}) {
   const {
     disallow = [],
     allow = [],
     crawlDelay = null,
-    additionalSitemaps = []
+    additionalSitemaps = [],
+    contentSignals = null
   } = options
 
   let content = 'User-agent: *\n'
 
+  const signals = formatContentSignals(contentSignals)
+  if (signals) {
+    // Inside the User-agent group, before the rules — the directive applies to
+    // the group it sits in.
+    content += `${signals}\n`
+  }
+
   for (const path of allow) {
     content += `Allow: ${path}\n`
   }
@@ -622,6 +673,31 @@ export function siteContentPlugin(options = {}) {
         source: renderSiteIndex(content, { ...options, exclude: agents.exclude })
       })
       console.log(`[site-content] Generated ${localeDir}${INDEX_FILENAME}`)
+
+      // Branch indexes are ADDITIVE — the root index above still enumerates
+      // every page, because the two-hop criterion depends on it. These are a
+      // scoped entry point for an agent already inside a branch.
+      if (agents.branchIndexes) {
+        const branches = selectIndexBranches(content.pages, {
+          exclude: agents.exclude,
+          minPages: agents.branchMinPages
+        })
+        for (const branch of branches) {
+          this.emitFile({
+            type: 'asset',
+            fileName: `${localeDir}${branchIndexFilename(branch.route)}`,
+            source: renderSiteIndex(content, {
+              ...options,
+              exclude: agents.exclude,
+              branch: branch.route
+            })
+          })
+        }
+        if (branches.length) {
+          const names = branches.map(b => `${b.route} (${b.count})`).join(', ')
+          console.log(`[site-content] Generated ${branches.length} branch index(es): ${names}`)
+        }
+      }
     }
 
     if (agents.markdown) {
@@ -1006,18 +1082,39 @@ export function siteContentPlugin(options = {}) {
           const agents = resolveAgentsConfig(siteContent.config)
           const url = req.url.split('?')[0]
 
-          const indexMatch = url.match(new RegExp(`^(?:\\/(${LOCALE_RE}))?\\/${INDEX_FILENAME}$`))
+          // `/llms.txt`, `/fr/llms.txt`, and the branch form `/docs/llms.txt`.
+          // The optional middle group is the branch route; an empty one is the
+          // site index, so a single pattern serves both rather than two that
+          // could drift.
+          const indexMatch = url.match(
+            new RegExp(`^(?:\\/(${LOCALE_RE}))?((?:\\/[^/]+)*)\\/${INDEX_FILENAME}$`)
+          )
           if (indexMatch && agents.index) {
             const localized = (indexMatch[1] ? await getTranslatedContent(indexMatch[1]) : null) || siteContent
-            res.setHeader('Content-Type', 'text/plain; charset=utf-8')
-            res.end(
-              renderSiteIndex(localized, {
-                ...projectionOptions(localized),
-                locale: indexMatch[1] || projectionOptions(localized).locale,
-                exclude: agents.exclude
-              })
-            )
-            return
+            const branch = indexMatch[2] || null
+
+            // Serve a branch index only where the build would emit one, or dev
+            // and the built output disagree about which URLs exist.
+            const served =
+              !branch ||
+              (agents.branchIndexes &&
+                selectIndexBranches(localized.pages, {
+                  exclude: agents.exclude,
+                  minPages: agents.branchMinPages
+                }).some(b => b.route === branch))
+
+            if (served) {
+              res.setHeader('Content-Type', 'text/plain; charset=utf-8')
+              res.end(
+                renderSiteIndex(localized, {
+                  ...projectionOptions(localized),
+                  locale: indexMatch[1] || projectionOptions(localized).locale,
+                  exclude: agents.exclude,
+                  branch
+                })
+              )
+              return
+            }
           }
 
           const markdownMatch = url.match(new RegExp(`^(?:\\/(${LOCALE_RE}))?\\/(.+)\\.md$`))
@@ -1038,12 +1135,12 @@ export function siteContentPlugin(options = {}) {
         }
 
         // Handle localized collection data (e.g., /fr/data/articles.json)
-        const localeDataMatch = req.url.match(new RegExp(`^\\/(${LOCALE_RE})\\/data\\/(.+\\.json)$`))
+        const localeDataMatch = req.url.match(new RegExp(`^\\/(${LOCALE_RE})\\/${DATA_DIR}\\/(.+\\.json)$`))
         if (localeDataMatch) {
           const locale = localeDataMatch[1]
           const filename = localeDataMatch[2]
           const collectionName = filename.replace('.json', '')
-          const sourcePath = join(resolvedSitePath, 'public', 'data', filename)
+          const sourcePath = join(resolvedSitePath, 'public', DATA_DIR, filename)
 
           if (existsSync(sourcePath)) {
             try {

package/src/uwx/locale-sync.js

@@ -108,29 +108,50 @@ export function loadLocaleTranslations(siteRoot, locales, subdir = '') {
  * map lives only on disk (`locales/{locale}.json`) and is recovered on pull (see
  * unwrapLocalizedContent).
  *
- * Returns the bare doc unchanged when there are no target locales / no translations
- * for any of them (single-locale and pre-localization sites are untouched). A
- * target locale with no translation for THIS doc is omitted (it falls back to the
- * source locale), so the payload stays lean.
+ * ALWAYS returns the per-locale map — `{ [sourceLocale]: doc }` at minimum. A target
+ * locale with no translation for THIS doc is omitted (it falls back to the source
+ * locale through the delivery locale chain), so the payload stays lean.
+ *
+ * It used to return the bare doc when nothing had been translated, which made the
+ * wire shape depend on *whether a given section happened to have a translation* —
+ * so one push could carry a map for a translated section and a bare doc for its
+ * untranslated neighbour, on the same page. The field declares `localized: true`,
+ * and a bare doc makes that declaration false: `{type, content}` is an object, so
+ * it satisfies "must be a map" with `type` and `content` sitting where locale codes
+ * belong, and a store cannot validate the one property the field declares. Every
+ * reader then has to disambiguate by asking "does this object happen to look like a
+ * ProseMirror doc" — a heuristic that has to be implemented identically in three
+ * codebases forever, and has already fail-opened in one of them.
+ *
+ * `localizeScalar` below has always wrapped unconditionally, so the producer was
+ * also inconsistent with itself: a section's `title` shipped as `{en: …}` while its
+ * `content` shipped bare, in the same payload.
+ *
+ * Readers stay tolerant of the bare form permanently — it exists in stores, in
+ * `.uwx` files on disk, and in every backup taken before this change. This changes
+ * what we WRITE, never what we accept (see `isLocalizedContent`, and
+ * `unwrapLocalizedContent`, which returns `content[sourceLocale]` so a source-only
+ * map round-trips back to a bare doc on the file lane).
  *
  * @param {object} doc - the source-locale ProseMirror content doc
  * @param {string} sourceLocale
- * @param {string[]} targetLocales
- * @param {object} translations - `{ locale: { hash: tgt } }` from loadLocaleTranslations
+ * @param {string[]} [targetLocales]
+ * @param {object} [translations] - `{ locale: { hash: tgt } }` from loadLocaleTranslations
  */
 export function localizeContentDoc(doc, sourceLocale, targetLocales, translations) {
-  if (!isProseMirrorDoc(doc) || !targetLocales || targetLocales.length === 0 || !translations) {
-    return doc
-  }
+  // Non-docs (null, an already-localized map) pass through untouched.
+  if (!isProseMirrorDoc(doc)) return doc
+
   const result = { [sourceLocale]: doc }
-  for (const locale of targetLocales) {
-    const table = translations[locale]
-    if (!table) continue
-    const resolved = resolveDocForLocale(doc, table)
-    if (resolved) result[locale] = resolved
+  if (targetLocales && translations) {
+    for (const locale of targetLocales) {
+      const table = translations[locale]
+      if (!table) continue
+      const resolved = resolveDocForLocale(doc, table)
+      if (resolved) result[locale] = resolved
+    }
   }
-  // Only wrap when at least one target carried a translation — else stay a bare doc.
-  return Object.keys(result).length > 1 ? result : doc
+  return result
 }
 
 /**

package/src/uwx/site.js

@@ -54,7 +54,7 @@ import {
   processMarkdownFile,
 } from '../site/content-collector.js'
 import { normalizeHideIn } from '../site/nav-visibility.js'
-import { resolveDefaultLocale, validateLanguageConfig } from '@uniweb/core'
+import { resolveDefaultLocale, validateLanguageConfig, collectionDataUrl } from '@uniweb/core'
 import { emitEntitySyncPackage } from './entity-document.js'
 import { loadLocaleTranslations, localizeScalar, localizeScalarList, localizeContentDoc, localesDir, isLocalizedContent } from './locale-sync.js'
 import { unwrapLocalized } from './backfill.js'
@@ -182,7 +182,7 @@ function buildPageData(config, ctx) {
     // `schema` (the collection name) is BOTH the content.data key and part of the
     // dataStore cache key (deriveCacheKey hashes {path,url,schema,…}; `collection`
     // is ignored). Mirrors the static build's parseFetchConfig resolution.
-    fetch = { path: `/data/${collection}.json`, schema: collection, ...rest }
+    fetch = { path: collectionDataUrl(collection), schema: collection, ...rest }
   }
   setIf(data, 'fetch', fetch)
   if (isDynamic) {
@@ -663,11 +663,14 @@ export async function siteProjectToDocument(siteRoot, opts = {}) {
 
   // Wrap each section's content into its per-locale form (source doc + target
   // structural maps from locales/{locale}.json, or a free-form body override from
-  // locales/freeform/**) when the site is multi-locale. A non-invasive post-pass
-  // over the built tree — single-locale sites are untouched.
-  if (targetLocales.length > 0) {
-    await localizeContentTree(pages, layoutSections, sourceLocale, targetLocales, translations, siteRoot)
-  }
+  // locales/freeform/**). A non-invasive post-pass over the built tree.
+  //
+  // Runs for EVERY site, including single-locale ones: `content` declares
+  // `localized: true`, so it ships as `{ [sourceLocale]: doc }` whatever the
+  // language count. Guarding this on `targetLocales.length` is what used to send
+  // a bare doc from single-locale sites — see localizeContentDoc for why one
+  // field with two shapes is a store that cannot validate its own declaration.
+  await localizeContentTree(pages, layoutSections, sourceLocale, targetLocales, translations, siteRoot)
 
   // Collection DECLARATIONS — the merged collections.yml + site.yml::collections
   // config (the records themselves are separate entities; this is just the config).