@uniweb/build 0.52.6 → 0.53.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@uniweb/build",
-  "version": "0.52.6",
+  "version": "0.53.0",
   "description": "Build tooling for the Uniweb Component Web Platform",
   "type": "module",
   "exports": {
@@ -58,14 +58,14 @@
     "sharp": "^0.35.3",
     "yaml": "^2.5.0",
     "@uniweb/content-reader": "^1.2.5",
+    "@uniweb/schemas": "^0.3.3",
+    "@uniweb/theming": "^0.1.15",
     "@uniweb/content-writer": "^0.3.4",
     "@uniweb/projections": "^0.7.3",
-    "@uniweb/semantic-parser": "^1.4.1",
-    "@uniweb/schemas": "^0.3.1",
-    "@uniweb/theming": "^0.1.15"
+    "@uniweb/semantic-parser": "^1.4.1"
   },
   "optionalDependencies": {
-    "@uniweb/runtime": "^0.26.4"
+    "@uniweb/runtime": "^0.26.5"
   },
   "peerDependencies": {
     "vite": "^5.0.0 || ^6.0.0 || ^7.0.0",
@@ -74,8 +74,8 @@
     "@tailwindcss/vite": "^4.0.0",
     "@vitejs/plugin-react": "^4.0.0 || ^5.0.0",
     "vite-plugin-svgr": "^4.0.0",
-    "@uniweb/core": "^0.29.4",
-    "@uniweb/runtime": "^0.26.4"
+    "@uniweb/runtime": "^0.26.5",
+    "@uniweb/core": "^0.29.4"
   },
   "peerDependenciesMeta": {
     "vite": {

package/src/i18n/audit.js

@@ -11,6 +11,17 @@ import { readFile, writeFile } from 'fs/promises'
 import { existsSync } from 'node:fs'
 import { join } from 'node:path'
 
+// Inline markdown → ProseMirror, so the markup check asks the merge's own question
+// ("would this value produce marks?") instead of pattern-matching markdown syntax.
+// Same lazy-import-with-fallback pattern as merge.js / extract.js.
+let markdownToProseMirror
+try {
+  const contentReader = await import('@uniweb/content-reader')
+  markdownToProseMirror = contentReader.markdownToProseMirror
+} catch {
+  markdownToProseMirror = null
+}
+
 /**
  * Audit a locale file against the manifest
  * @param {string} localesPath - Path to locales directory
@@ -46,18 +57,27 @@ export async function auditLocale(localesPath, locale) {
   const valid = []
   const missing = []
   const stale = []
-  const needsTags = []
+  const losesMarkup = []
 
   // Check manifest entries
   for (const hash of manifestHashes) {
     if (translationHashes.has(hash)) {
-      const source = manifest.units[hash].source
+      const unit = manifest.units[hash]
+      const source = unit.source
       const translation = getTranslationText(translations[hash])
       valid.push({ hash, source, translation })
 
-      // Flag entries where source has inline tags but translation doesn't
-      if (/<\d+>/.test(source) && !/<\d+>/.test(translation) && translation.length > 0) {
-        needsTags.push({ hash, source, translation })
+      // ⭐ The source element carries inline markdown; the translation does not.
+      // `merge` builds the translated element from the VALUE alone — it never
+      // re-applies marks from the source — so this entry will render as flat prose
+      // and its links will be gone. It still counts as translated, which is why
+      // coverage cannot see it: the whole class scores 100%.
+      // ⛔ REPLACES a `<N>`-tag check that could no longer fire. Those tags were the
+      // pre-2026-06-24 keying scheme (`d12d594`); extraction has not emitted one
+      // since, so the check was dead while looking like a live guard — and it was
+      // the only thing in the pipeline that even gestured at mark fidelity.
+      if (unit.markup && translation.length > 0 && !carriesInlineMarkup(translation)) {
+        losesMarkup.push({ hash, source, markup: unit.markup, translation })
       }
     } else {
       missing.push({
@@ -86,7 +106,29 @@ export async function auditLocale(localesPath, locale) {
     valid,
     missing,
     stale,
-    needsTags
+    losesMarkup
+  }
+}
+
+/**
+ * Does this translation value produce any inline marks when the merge parses it?
+ *
+ * Asks the parser rather than a regex: the merge resolves a value through
+ * `markdownToProseMirror`, so the only honest test of "will this keep its link"
+ * is to run the same conversion. With no converter available the check declines
+ * to fire — a missing dependency must not invent findings.
+ */
+function carriesInlineMarkup(value) {
+  if (!markdownToProseMirror) return true
+  try {
+    const doc = markdownToProseMirror(value)
+    const walk = (nodes) =>
+      (nodes || []).some(
+        (n) => (n?.marks && n.marks.length > 0) || (n?.type && n.type !== 'text' && n.type !== 'paragraph') || walk(n?.content)
+      )
+    return walk(doc?.content)
+  } catch {
+    return true
   }
 }
 
@@ -161,8 +203,8 @@ export function formatAuditReport(results, options = {}) {
     lines.push(`  Valid:   ${result.valid.length} (${coverage}%)`)
     lines.push(`  Missing: ${result.missing.length}`)
     lines.push(`  Stale:   ${result.stale.length}`)
-    if (result.needsTags?.length > 0) {
-      lines.push(`  Needs tags: ${result.needsTags.length}`)
+    if (result.losesMarkup?.length > 0) {
+      lines.push(`  Loses markup: ${result.losesMarkup.length}  (links/bold in the source, plain in the translation)`)
     }
 
     if (verbose && result.stale.length > 0) {
@@ -176,14 +218,16 @@ export function formatAuditReport(results, options = {}) {
       }
     }
 
-    if (verbose && result.needsTags?.length > 0) {
-      lines.push(`\n  Translations missing inline tags:`)
-      for (const entry of result.needsTags.slice(0, 10)) {
-        const src = truncate(entry.source, 50)
-        lines.push(`    - ${entry.hash}: "${src}"`)
+    if (verbose && result.losesMarkup?.length > 0) {
+      lines.push(`\n  Translations that drop the source's inline markup:`)
+      lines.push(`  (a translation value is inline markdown — copy the links and marks across)`)
+      for (const entry of result.losesMarkup.slice(0, 10)) {
+        lines.push(`    - ${entry.hash}`)
+        lines.push(`        source: "${truncate(entry.markup, 60)}"`)
+        lines.push(`        yours:  "${truncate(entry.translation, 60)}"`)
       }
-      if (result.needsTags.length > 10) {
-        lines.push(`    ... and ${result.needsTags.length - 10} more`)
+      if (result.losesMarkup.length > 10) {
+        lines.push(`    ... and ${result.losesMarkup.length - 10} more`)
       }
     }
   }

package/src/i18n/extract.js

@@ -9,6 +9,19 @@ import { resolveDefaultLocale } from '@uniweb/core'
 import { computeHash, stripInlineTags } from './hash.js'
 import { visitDataStrings } from './data-strings.js'
 
+// ProseMirror inline fragment → inline markdown, for the TRANSLATOR-FACING half of
+// a unit. Same lazy-import-with-fallback pattern as merge.js, so the synchronous
+// extraction path has the serializer ready at call time. The fallback is the plain
+// text we already had, so a resolution failure degrades to the old behaviour rather
+// than breaking extraction.
+let serializeInlineContent
+try {
+  const contentWriter = await import('@uniweb/content-writer')
+  serializeInlineContent = contentWriter.serializeInlineContent
+} catch {
+  serializeInlineContent = null
+}
+
 /**
  * Extract all translatable units from site content
  * @param {Object} siteContent - Parsed site-content.json
@@ -231,7 +244,7 @@ function extractFromProseMirrorDoc(doc, context, units) {
       const field = getHeadingField(level, headingIndex)
       headingIndex[`h${level}`]++
 
-      addUnit(units, text, field, context)
+      addUnit(units, text, field, context, elementMarkup(node))
       return
     }
 
@@ -242,12 +255,12 @@ function extractFromProseMirrorDoc(doc, context, units) {
     if (!text) return
 
     if (listIndex !== null) {
-      addUnit(units, text, `list.${listIndex}`, context)
+      addUnit(units, text, `list.${listIndex}`, context, elementMarkup(node))
       return
     }
 
     const field = paragraphIndex === 0 ? 'paragraph' : `paragraph.${paragraphIndex}`
-    addUnit(units, text, field, context)
+    addUnit(units, text, field, context, elementMarkup(node))
     paragraphIndex++
   })
 }
@@ -348,6 +361,37 @@ export function elementText(node) {
   return collectInlineText(node).trim()
 }
 
+/**
+ * A block element's INLINE MARKDOWN — the translator-facing half of a unit.
+ *
+ * ⛔ NOT a second key. `elementText` above stays the key and the hash input,
+ * deliberately: bolding a word or re-targeting a link must not move a hash and
+ * orphan an existing translation.
+ *
+ * WHY THIS EXISTS. `merge.js` parses a translation VALUE as inline markdown, so
+ * the value channel carries links, marks and inline atoms losslessly. The SOURCE
+ * channel did not: a unit stored only the flattened text, `uniweb i18n generate`
+ * seeded locale files from it, and a translator was therefore shown a paragraph
+ * with its links already gone. They cannot restore what they were never shown —
+ * so a fully translated, 100%-covered site rendered with zero inline links, and
+ * no instrument reported anything (coverage counts keys, not fidelity).
+ * Measured 2026-09-18 on a documentation site with 266 internal links.
+ *
+ * Returns null when the serializer is unavailable or adds nothing over the plain
+ * text, so `markup` appears on a unit only when it actually carries more.
+ */
+export function elementMarkup(node) {
+  if (!serializeInlineContent || !node?.content) return null
+  try {
+    const markup = serializeInlineContent(node.content)
+    if (typeof markup !== 'string') return null
+    const trimmed = markup.trim()
+    return trimmed && trimmed !== elementText(node) ? trimmed : null
+  } catch {
+    return null
+  }
+}
+
 function collectInlineText(node) {
   if (!node || !node.content) return ''
   let out = ''
@@ -385,14 +429,18 @@ export function blockElements(doc) {
 /**
  * Add a translation unit to the accumulator
  */
-function addUnit(units, source, field, context) {
+function addUnit(units, source, field, context, markup = null) {
   if (!source || source.length === 0) return
 
   // Hash on plain text (strip inline tags) so keys stay stable
   const hash = computeHash(stripInlineTags(source))
 
   if (units[hash]) {
-    // Unit exists - add context if not already present
+    // Unit exists - add context if not already present.
+    // Two elements can share a key and differ in markup ("Learn more" plain in one
+    // place, linked in another). The first occurrence wins the field and the order,
+    // but a later one may be the only carrier of markup, so fill it rather than drop it.
+    if (markup && !units[hash].markup) units[hash].markup = markup
     const existingContexts = units[hash].contexts
     const contextKey = `${context.page}:${context.section}`
     const exists = existingContexts.some(
@@ -402,9 +450,11 @@ function addUnit(units, source, field, context) {
       existingContexts.push({ ...context })
     }
   } else {
-    // New unit
+    // New unit. `markup` is omitted unless the element carries inline markdown —
+    // most units are plain prose and gain nothing from a duplicate string.
     units[hash] = {
       source,
+      ...(markup ? { markup } : {}),
       field,
       contexts: [{ ...context }]
     }

package/src/i18n/hash.js

@@ -31,7 +31,21 @@ export function normalizeText(text) {
 
 /**
  * Strip inline mark tags for hashing: "<1>text</1>" → "text"
- * Used to keep hash keys stable regardless of mark tagging.
+ *
+ * VESTIGIAL BUT LIVE. `<N>` tags were the pre-2026-06-24 mark-preservation scheme:
+ * a unit's source carried numbered tags and the merge re-applied the source's marks
+ * to the matching spans positionally. Whole-element keying replaced it (`d12d594`) —
+ * a translation VALUE is now inline markdown and the merge re-parses it, so nothing
+ * emits a `<N>` tag any more.
+ *
+ * ⛔ This stays anyway, because it runs on the HASH path: a manifest written before
+ * that change still holds tagged sources, and stripping keeps their keys matching
+ * what extraction produces today. Removing it would silently orphan those
+ * translations. The tag PARSER that went with it (`parseInlineTags`) had no callers
+ * and was deleted 2026-09-18; it was the only thing in the codebase that still looked
+ * like a live mark-preservation convention, which cost a peer lane a day of hunting
+ * for the placeholder syntax it implied.
+ *
  * @param {string} text
  * @returns {string}
  */
@@ -39,36 +53,3 @@ export function stripInlineTags(text) {
   if (typeof text !== 'string') return ''
   return text.replace(/<\/?(\d+)>/g, '')
 }
-
-/**
- * Parse tagged translation string into segments.
- * "plain <1>marked</1> more" →
- *   { segments: [{ text: "plain " }, { text: "marked", markIndex: 0 }, { text: " more" }], hasMarks: true }
- *
- * Tag numbers are 1-based in the string, markIndex is 0-based in the result.
- * @param {string} text
- * @returns {{ segments: Array<{ text: string, markIndex?: number }>, hasMarks: boolean }}
- */
-export function parseInlineTags(text) {
-  const regex = /<(\d+)>([\s\S]*?)<\/\1>/g
-  const segments = []
-  let lastIndex = 0
-  let hasMarks = false
-  let match
-
-  while ((match = regex.exec(text)) !== null) {
-    hasMarks = true
-    if (match.index > lastIndex) {
-      segments.push({ text: text.slice(lastIndex, match.index) })
-    }
-    segments.push({ text: match[2], markIndex: parseInt(match[1], 10) - 1 })
-    lastIndex = regex.lastIndex
-  }
-
-  if (lastIndex < text.length) {
-    segments.push({ text: text.slice(lastIndex) })
-  }
-
-  if (!hasMarks) return { segments: [{ text }], hasMarks: false }
-  return { segments, hasMarks }
-}

package/src/i18n/index.js

@@ -23,6 +23,7 @@ import {
   translateRecordData,
   RECORDS_DIR
 } from './records.js'
+import { resolveDefaultLocale } from '@uniweb/core'
 import { generateSearchIndex } from '@uniweb/projections'
 import { searchDeclaredOn } from '../site/search-declared.js'
 
@@ -329,6 +330,48 @@ export async function getTranslationStatus(siteRoot, options = {}) {
   }
 }
 
+/**
+ * ⭐ THE LOCALE SET A PAYLOAD DECLARES — resolved here, because this is the only
+ * place that knows it.
+ *
+ * ⛔ THE BUILD AND THE RUNTIME USED TO DISAGREE ABOUT WHERE LOCALES COME FROM, and
+ * nothing failed when they did. The build derives them from the FILESYSTEM —
+ * every `locales/*.json`, which is also what `languages: '*'` means — while
+ * `Website.buildLocalesList` reads `config.languages` and nothing else. So a site
+ * with locale files and no `languages:` in `site.yml` built a complete
+ * `dist/<locale>/` tree whose Website reported `hasMultipleLocales() === false`.
+ *
+ * Everything gated on that answer then silently switched off, in the rendered
+ * output, with no warning anywhere:
+ *   - no link was locale-prefixed (`applyLocale`, @uniweb/kit/utils/href) — every
+ *     internal link on a French page pointed into the English tree;
+ *   - no route translation was applied, although the build had emitted the
+ *     translated routes as directories (`/fr/a-propos/` existed; nothing linked
+ *     to it);
+ *   - any foundation UI gated on `hasMultipleLocales()` — the language switcher —
+ *     vanished from the very pages that needed it.
+ *
+ * Measured 2026-09-18 on our own `international` template, which was in exactly
+ * this state. ⇒ **The producer stamps what it resolved; the consumer reads it.**
+ * Guessing the set twice, from two different sources, is what this replaces.
+ *
+ * Declared entries are kept as authored — a `{ code, label }` object carries a
+ * label the filesystem cannot know — and resolved codes are appended.
+ */
+function declaredLanguages(config, defaultLocale, locales) {
+  const authored = Array.isArray(config?.languages) ? config.languages : []
+  const codeOf = (e) => (typeof e === 'string' ? e : e?.code)
+  const seen = new Set(authored.map(codeOf).filter(Boolean))
+  const out = authored.filter((e) => codeOf(e) && codeOf(e) !== '*')
+  for (const code of [defaultLocale, ...locales]) {
+    if (code && !seen.has(code)) {
+      seen.add(code)
+      out.push(code)
+    }
+  }
+  return out
+}
+
 /**
  * Build translated site content for all locales
  * @param {string} siteRoot - Site root directory
@@ -353,10 +396,36 @@ export async function buildLocalizedContent(siteRoot, options = {}) {
   const siteContentPath = join(outputDir, 'site-content.json')
   const siteContentRaw = await readFile(siteContentPath, 'utf-8')
   const siteContent = JSON.parse(siteContentRaw)
+  const defaultLocale = resolveDefaultLocale(siteContent.config)
 
   const outputs = {}
 
+  // ⭐ The DEFAULT locale's payload needs the same stamp. It is not written in
+  // this loop — it is the source this function reads — but a visitor landing on
+  // `/` gets a Website built from it, and without the set that page loses its
+  // language switcher while every translated page has one.
+  const stampedLanguages = declaredLanguages(siteContent.config, defaultLocale, locales)
+  if (JSON.stringify(siteContent.config?.languages) !== JSON.stringify(stampedLanguages)) {
+    siteContent.config = { ...siteContent.config, languages: stampedLanguages }
+    await writeFile(siteContentPath, JSON.stringify(siteContent, null, 2))
+  }
+
   for (const locale of locales) {
+    // ⛔ THE DEFAULT LOCALE IS THE ROOT TREE, NEVER A SUBDIRECTORY. Emitting
+    // `dist/<default>/` mints a byte-identical duplicate of every page at a second
+    // URL — duplicate content on any real domain, and the `hreflang` block already
+    // points that locale at `/` (`locale.default`, site/plugin.js) so nothing links
+    // to the copy.
+    //
+    // ⚠️ It was reachable only through the DECLARED form, which is the form the
+    // contract tells authors to use: `resolveLocales` returns an explicit
+    // `languages: [en, fr]` verbatim, default included, while the wildcard and
+    // filesystem forms exclude it by accident (there is no `locales/en.json`). So
+    // the documented spelling was the broken one. `uniweb i18n generate` has always
+    // skipped the default explicitly; this is the same rule, one stage later.
+    // Measured 2026-09-18: 47 pages duplicated under /en/.
+    if (locale === defaultLocale) continue
+
     const localePath = join(localesPath, `${locale}.json`)
 
     // Load translations (or empty object if not exists)
@@ -390,8 +459,14 @@ export async function buildLocalizedContent(siteRoot, options = {}) {
       })
     }
 
-    // Mark the active locale in the translated content
-    translated.config = { ...translated.config, activeLocale: locale }
+    // Mark the active locale in the translated content, and stamp the resolved
+    // locale set so the runtime does not have to re-derive it — see
+    // `declaredLanguages`.
+    translated.config = {
+      ...translated.config,
+      activeLocale: locale,
+      languages: declaredLanguages(siteContent.config, defaultLocale, locales)
+    }
 
     // Write to locale subdirectory
     const localeOutputDir = join(outputDir, locale)

package/src/i18n/merge.js

@@ -173,48 +173,93 @@ async function mergeTranslationsAsync(siteContent, translations, options) {
   return translated
 }
 
+/**
+ * ⭐ A TRANSLATION VALUE IS INLINE MARKDOWN, AND A PLAIN-TEXT SLOT RENDERS ITS TEXT.
+ *
+ * Units are deduplicated by normalized plain text, so ONE id carries every role
+ * that text plays on the site — and on a documentation site the two roles
+ * collide by design, because the house style is to link to a page by its title:
+ * "See [Roles and permissions](page:…)" makes that page's own title and the link
+ * to it the same string, hence the same unit.
+ *
+ * ⛔ That collision used to be unresolvable for the translator. A body occurrence
+ * needs the markdown (or the link is lost); a title occurrence was assigned the
+ * value RAW, so the same markdown landed verbatim in `<title>` — brackets,
+ * `page:` protocol and all — in the tab, the nav and every search result.
+ * Measured 2026-09-18: 32 of one site's 41 link texts were also page titles, so
+ * neither "markdown everywhere" nor "markdown nowhere" was shippable.
+ *
+ * ⭐ The resolution is on the CONSUMER, not the key. A body element parses the
+ * value into a fragment; a title takes its TEXT. One value serves both, and a
+ * page's title stays in lockstep with the links pointing at it — which is the
+ * property a cross-linked site wants and a role-keyed hash would destroy (the
+ * same word translated once per role, free to drift).
+ *
+ * ⛔ Do not add the field or the role to the hash. Genuine wording divergence by
+ * context is what `overrides` is for (`lookupTranslation`); representation
+ * divergence is this function's job.
+ */
+function toPlainText(value) {
+  if (typeof value !== 'string' || !value.includes('[') && !value.includes('*') && !value.includes('`') && !value.includes('_')) {
+    return value
+  }
+  try {
+    const doc = markdownToProseMirror(value)
+    const collect = (nodes) =>
+      (nodes || [])
+        .map((n) => (n.type === 'text' ? n.text || '' : n.type === 'hardBreak' ? ' ' : collect(n.content)))
+        .join('')
+    const text = collect(doc?.content).trim()
+    return text || value
+  } catch {
+    return value
+  }
+}
+
 /**
  * Translate page metadata (title, description, keywords, etc.)
+ *
+ * Every field here is a PLAIN-TEXT slot — `<title>`, a nav label, a meta
+ * description — so each value is flattened. See `toPlainText`.
  */
 function translatePageMeta(page, pageRoute, translations, fallbackToSource) {
   const context = { page: pageRoute, section: '_meta' }
+  const translate = (value) =>
+    toPlainText(lookupTranslation(value, context, translations, fallbackToSource))
 
   // Translate title
   if (page.title && typeof page.title === 'string') {
-    page.title = lookupTranslation(page.title, context, translations, fallbackToSource)
+    page.title = translate(page.title)
   }
 
   // Translate label (short navigation label)
   if (page.label && typeof page.label === 'string') {
-    page.label = lookupTranslation(page.label, context, translations, fallbackToSource)
+    page.label = translate(page.label)
   }
 
   // Translate description
   if (page.description && typeof page.description === 'string') {
-    page.description = lookupTranslation(page.description, context, translations, fallbackToSource)
+    page.description = translate(page.description)
   }
 
   // Translate SEO fields
   if (page.seo) {
     if (page.seo.ogTitle && typeof page.seo.ogTitle === 'string') {
-      page.seo.ogTitle = lookupTranslation(page.seo.ogTitle, context, translations, fallbackToSource)
+      page.seo.ogTitle = translate(page.seo.ogTitle)
     }
     if (page.seo.ogDescription && typeof page.seo.ogDescription === 'string') {
-      page.seo.ogDescription = lookupTranslation(page.seo.ogDescription, context, translations, fallbackToSource)
+      page.seo.ogDescription = translate(page.seo.ogDescription)
     }
   }
 
   // Translate keywords
   if (page.keywords) {
     if (Array.isArray(page.keywords)) {
-      page.keywords = page.keywords.map(keyword => {
-        if (keyword && typeof keyword === 'string') {
-          return lookupTranslation(keyword, context, translations, fallbackToSource)
-        }
-        return keyword
-      })
+      page.keywords = page.keywords.map(keyword =>
+        keyword && typeof keyword === 'string' ? translate(keyword) : keyword
+      )
     } else if (typeof page.keywords === 'string') {
-      page.keywords = lookupTranslation(page.keywords, context, translations, fallbackToSource)
+      page.keywords = translate(page.keywords)
     }
   }
 }

package/src/i18n/sync.js

@@ -15,6 +15,7 @@ export function syncManifests(previous, current) {
   const report = {
     unchanged: [],
     moved: [],
+    remarked: [],
     changed: [],
     added: [],
     removed: []
@@ -42,6 +43,23 @@ export function syncManifests(previous, current) {
           previousContexts: prevUnit.contexts,
           currentContexts: currentUnit.contexts
         })
+      } else if (prevUnit.markup !== currentUnit.markup) {
+        // ⭐ Same words, different inline markup — an author added a link, bolded a
+        // phrase or re-targeted an href without touching the text.
+        //
+        // ⛔ THE HASH CANNOT SEE THIS, BY DESIGN. It is computed over the flattened
+        // plain text precisely so that marking up a sentence does not orphan its
+        // existing translation. The cost is that nothing told a translator to go
+        // back and add the link, and the existing translation stays "valid" and
+        // fully counted while silently losing the markup the source gained.
+        // Measured 2026-09-18; before this bucket the report was simply silent.
+        report.remarked.push({
+          hash,
+          source: currentUnit.source,
+          previousMarkup: prevUnit.markup || null,
+          currentMarkup: currentUnit.markup || null,
+          contexts: currentUnit.contexts
+        })
       } else {
         report.unchanged.push({ hash, source: currentUnit.source })
       }
@@ -155,6 +173,21 @@ export function formatSyncReport(report) {
     }
   }
 
+  if (report.remarked?.length > 0) {
+    lines.push(
+      `  ✎ ${report.remarked.length} strings kept their words but changed inline markup (links/bold)`
+    )
+    lines.push(
+      `    Existing translations still count as valid — update them or the markup is lost.`
+    )
+    for (const item of report.remarked.slice(0, 5)) {
+      lines.push(`    - "${truncate(item.currentMarkup || item.source, 60)}"`)
+    }
+    if (report.remarked.length > 5) {
+      lines.push(`    ... and ${report.remarked.length - 5} more`)
+    }
+  }
+
   if (report.changed.length > 0) {
     lines.push(`  ⚠ ${report.changed.length} strings changed (need re-translation)`)
     for (const item of report.changed.slice(0, 5)) {

package/src/site/config.js

@@ -97,7 +97,10 @@ export function readSiteConfig(siteRoot) {
  * @param {Array} [options.plugins] - Additional Vite plugins
  * @param {Object} [options.build] - Vite build options
  * @param {Object} [options.resolve] - Vite resolve options
- * @param {Object} [options.seo] - SEO configuration for siteContentPlugin
+ * @param {Object} [options.seo] - SEO OVERRIDES for siteContentPlugin, merged
+ *   OVER the site's own `site.yml::seo` block. Omit it and `site.yml` decides —
+ *   a site's `vite.config.js` is scaffolding, so nothing a site GETS may depend
+ *   on what it passes here.
  * @param {Object} [options.assets] - Asset processing configuration
  * @param {Object} [options.search] - Search index configuration
  * @param {boolean} [options.tailwind] - Include Tailwind CSS v4 Vite plugin (default: true)

package/src/site/plugin.js

@@ -493,6 +493,51 @@ function escapeHtml(str) {
     .replace(/"/g, '"')
 }
 
+/**
+ * The effective `seo` block for a collected site.
+ *
+ * ⛔ **`site.yml::seo` IS THE SOURCE. The plugin option is an OVERRIDE.**
+ * This plugin read `options.seo` alone until 2026-09-17, and nothing ever put
+ * `site.yml`'s block there: `defineSiteConfig` passes its own `seo` option
+ * straight through and defaults it to `{}`, while the scaffolded
+ * `vite.config.js` calls `defineSiteConfig()` with no arguments. So on the
+ * bundle lane `seo.baseUrl` and `seo.robots` were authored, documented
+ * (`cli/partials/agents.md`), read by `uniweb doctor` — and dead. The symptom,
+ * reported from a real site: `seo.baseUrl` set, doctor's
+ * `agents-index-relative-links` warning cleared, and `uniweb build` / `uniweb
+ * export` emitting neither `sitemap.xml` nor `robots.txt` while `llms.txt`
+ * links stayed root-relative.
+ *
+ * ⭐ **The data-only path was never wrong** — `build-site-data.js::writeProjections`
+ * reads `siteContent.config.seo.baseUrl`. Reading the same place here is what
+ * makes the two lanes unable to disagree, which is the whole reason
+ * `projectionOptions` exists.
+ *
+ * ⚠️ The generators were unit-tested throughout (`tests/robots-content-signals.test.js`
+ * calls `generateRobotsTxt` directly), which is why a green suite proved
+ * nothing: the tests supplied the input the wiring never delivered. That is why
+ * this is an exported function rather than a closure — the RESOLUTION is the
+ * part that was missing, so it is the part that gets asserted.
+ *
+ * A site's `vite.config.js` is CLI scaffolding — strip it and the site is
+ * unchanged — so a site's SEO must not depend on what it passes. An explicit
+ * override still wins, key by key, the way `base` does.
+ *
+ * @param {Object} [content] - Collected site content (reads `content.config.seo`)
+ * @param {Object} [overrides] - Caller overrides, merged OVER the site's block
+ * @returns {{ baseUrl: string, defaultImage: ?string, twitterHandle: ?string, locales: Array, robots: Object }}
+ */
+export function resolveEffectiveSeo(content, overrides = {}) {
+  const merged = { ...(content?.config?.seo || {}), ...overrides }
+  return {
+    baseUrl: merged.baseUrl?.replace(/\/$/, '') || '', // Remove trailing slash
+    defaultImage: merged.defaultImage || null,
+    twitterHandle: merged.twitterHandle || null,
+    locales: merged.locales || [],
+    robots: merged.robots || {}
+  }
+}
+
 /**
  * Create the site content plugin
  *
@@ -503,7 +548,10 @@ function escapeHtml(str) {
  * @param {boolean} [options.inject=true] - Inject content into HTML
  * @param {string} [options.filename='site-content.json'] - Output filename
  * @param {boolean} [options.watch=true] - Watch for changes in dev mode
- * @param {Object} [options.seo] - SEO configuration
+ * @param {Object} [options.seo] - SEO OVERRIDES, merged OVER `site.yml::seo`
+ *   key by key. The site's own block is the source; this is for a caller that
+ *   must override it (a preview build pointing at a staging origin, say).
+ *   ⛔ Do not reach for this to make `site.yml::seo` work — it already does.
  * @param {string} [options.seo.baseUrl] - Base URL for sitemap and canonical URLs
  * @param {string} [options.seo.defaultImage] - Default OG image path
  * @param {string} [options.seo.twitterHandle] - Twitter handle for cards
@@ -548,15 +596,8 @@ export function siteContentPlugin(options = {}) {
     pdfThumbnails: assetsConfig.pdfThumbnails !== false // Default true
   }
 
-  // Extract SEO options with defaults
-  const seoEnabled = !!seo.baseUrl
-  const seoOptions = {
-    baseUrl: seo.baseUrl?.replace(/\/$/, '') || '', // Remove trailing slash
-    defaultImage: seo.defaultImage || null,
-    twitterHandle: seo.twitterHandle || null,
-    locales: seo.locales || [],
-    robots: seo.robots || {}
-  }
+  /** This plugin's SEO resolution — `site.yml::seo`, with `options.seo` over it. */
+  const resolveSeo = content => resolveEffectiveSeo(content, seo)
 
   // Warn once per build, not once per collection — the dev server re-collects
   // on every content change and would otherwise repeat this on every keystroke.
@@ -756,7 +797,7 @@ export function siteContentPlugin(options = {}) {
   function projectionOptions(content) {
     const defaultLocale = resolveDefaultLocale(content.config)
     return {
-      baseUrl: seoOptions.baseUrl,
+      baseUrl: resolveSeo(content).baseUrl,
       basePath,
       locale: content.config?.activeLocale || defaultLocale,
       defaultLocale
@@ -1185,17 +1226,22 @@ export function siteContentPlugin(options = {}) {
           // If no translations, fall through to serve default content
         }
 
+        // Dev serves the same two SEO artifacts the build emits, off the same
+        // resolution — so `uniweb dev` and `uniweb build` cannot disagree about
+        // whether a site has them.
+        const devSeo = resolveSeo(siteContent)
+
         // Serve sitemap.xml in dev mode
-        if (req.url === '/sitemap.xml' && seoEnabled && siteContent?.pages) {
+        if (req.url === '/sitemap.xml' && devSeo.baseUrl && siteContent?.pages) {
           res.setHeader('Content-Type', 'application/xml')
-          res.end(generateSitemap(siteContent.pages, seoOptions.baseUrl, filterSeoLocales(seoOptions.locales, siteContent.config), siteContent.config?.i18n?.routeTranslations))
+          res.end(generateSitemap(siteContent.pages, devSeo.baseUrl, filterSeoLocales(devSeo.locales, siteContent.config), siteContent.config?.i18n?.routeTranslations))
           return
         }
 
         // Serve robots.txt in dev mode
-        if (req.url === '/robots.txt' && seoEnabled) {
+        if (req.url === '/robots.txt' && devSeo.baseUrl) {
           res.setHeader('Content-Type', 'text/plain')
-          res.end(generateRobotsTxt(seoOptions.baseUrl, seoOptions.robots))
+          res.end(generateRobotsTxt(devSeo.baseUrl, devSeo.robots))
           return
         }
 
@@ -1398,8 +1444,9 @@ export function siteContentPlugin(options = {}) {
       }
 
       // Inject SEO meta tags
-      if (seoEnabled) {
-        const metaTags = generateMetaTags(contentToInject, seoOptions)
+      const injectSeo = resolveSeo(contentToInject)
+      if (injectSeo.baseUrl) {
+        const metaTags = generateMetaTags(contentToInject, injectSeo)
         if (metaTags) {
           headInjection += `    ${metaTags}\n`
         }
@@ -1555,9 +1602,10 @@ export function siteContentPlugin(options = {}) {
       })
 
       // Generate SEO files if enabled
-      if (seoEnabled && finalContent?.pages) {
+      const buildSeo = resolveSeo(finalContent)
+      if (buildSeo.baseUrl && finalContent?.pages) {
         // Generate sitemap.xml
-        const sitemap = generateSitemap(finalContent.pages, seoOptions.baseUrl, filterSeoLocales(seoOptions.locales, finalContent.config), finalContent.config?.i18n?.routeTranslations)
+        const sitemap = generateSitemap(finalContent.pages, buildSeo.baseUrl, filterSeoLocales(buildSeo.locales, finalContent.config), finalContent.config?.i18n?.routeTranslations)
         this.emitFile({
           type: 'asset',
           fileName: 'sitemap.xml',
@@ -1566,7 +1614,7 @@ export function siteContentPlugin(options = {}) {
         console.log('[site-content] Generated sitemap.xml')
 
         // Generate robots.txt
-        const robotsTxt = generateRobotsTxt(seoOptions.baseUrl, seoOptions.robots)
+        const robotsTxt = generateRobotsTxt(buildSeo.baseUrl, buildSeo.robots)
         this.emitFile({
           type: 'asset',
           fileName: 'robots.txt',

package/src/uwx/emit-surface.json

@@ -36,9 +36,6 @@
         ],
         "template": [
           "site.yml::template"
-        ],
-        "url": [
-          "site.yml::$url"
         ]
       }
     },

package/src/uwx/site-project.js

@@ -150,15 +150,15 @@ const INFO_TO_SITE_YML = {
   // the path an author wrote for an image in the project, which `restoreAssetRefs`
   // has already put back by recognizing the serve URL the push recorded in
   // `assets.json` (asset-map.js). [Diego, 2026-09-10]
-  preview: 'preview',
-  // ⭐ `url` — where the site is live → `site.yml::$url`. The backend records it at
-  // every publish, and pull is its only way onto disk; recorded rather than authored,
-  // so it lands under the `$` like `$uuid`.
   //
-  // ⚠️ Both were listed here as "DELIBERATELY ABSENT… BACKEND-STAMPED" until
+  // ⚠️ It was listed here as "DELIBERATELY ABSENT… BACKEND-STAMPED" until
   // 2026-09-10. Leaving an app-written field out of this map is what lets the next
   // push destroy it, since `info` is replaced whole.
-  url: '$url',
+  preview: 'preview',
+  // ⛔ `url` is RETIRED (2026-09-17) and must not come back: where a site went live
+  // is a deploy fact, which `publish` records in `deploy.yml`, not site config. A
+  // document that still carries `info.url` writes nothing — an unlisted key is
+  // ignored — and a `$url` already on disk is left alone and never read.
 }
 
 // ── `settings` Section → site.yml ─────────────────────────────────────────────

package/src/uwx/site.js

@@ -56,6 +56,7 @@ import {
   checkDeclaration,
   fetchFromQueryShorthand,
   assertRouteFolder,
+  mountEntriesOf,
 } from '../site/content-collector.js'
 import { refuseBinding, refuseUnder, refuseOutsideLanguage, warnDuplicateBindings } from '../site/data-fetcher.js'
 import { readLayoutFolder } from '../site/layout-folder.js'
@@ -557,6 +558,30 @@ async function collectPageSectionsNested(pageDir, siteRoot, pageConfig) {
   return sections.map((s, i) => sectionToRecord(s, i))
 }
 
+// A folder-mode folder's `.md` files are pages to the build and nothing to this
+// lane. Name every one of them, so the shortfall is visible at push time rather
+// than by reading the backend's store or opening the published site.
+async function warnFolderModePagesSkipped(dirPath, siteRoot) {
+  let files
+  try {
+    files = (await readdir(dirPath)).filter(isMarkdownFile)
+  } catch {
+    return
+  }
+  if (files.length === 0) return
+  const where = relative(siteRoot, dirPath)
+  console.warn(
+    `uwx/site: ${files.length} page(s) in \`${where}\` will NOT be pushed — ` +
+      `it is a folder-mode folder (\`folder.yml\`), and pushing \`.md\`-as-pages ` +
+      `is not implemented on the sync lane. A build renders them; the backend ` +
+      `will not have them.\n` +
+      files.map((f) => `  - ${where}/${f}`).join('\n') +
+      `\n  To publish them, make each one a page-mode directory ` +
+      `(\`<name>/page.yml\` + its section files). To ship them as they are, ` +
+      `use \`uniweb export\` or \`uniweb deploy --host <adapter>\`.`
+  )
+}
+
 // Recursively build the `pages` tree: each record carries its fields, its inline
 // `page_sections` (page mode only), and its child pages under `$children`.
 async function walkPagesNested(ctx, dirPath, parentSlugPath, inheritedMode, parentConfig, isRoot) {
@@ -594,6 +619,20 @@ async function walkPagesNested(ctx, dirPath, parentSlugPath, inheritedMode, pare
     if (mode === 'page') {
       const sections = await collectPageSectionsNested(f.path, siteRoot, f.config)
       if (sections.length > 0) record.page_sections = sections
+    } else {
+      // ⛔ FOLDER MODE: the build makes each `.md` file here a PAGE; this lane
+      // makes it nothing. It is a v0 mapper gap (bidirectional-sync.md §"Other
+      // v0 mapper gaps"), and until it closes the ONLY thing standing between an
+      // author and a site that publishes a fraction of itself is this warning.
+      //
+      // ⭐ It has to be here, not in `status` or `push`. Those compare the built
+      // document against what was last sent, so with the pages already absent
+      // from the document both correctly report "Synced" / "Nothing to push".
+      // The loss happens upstream of every diff, which is why it was invisible:
+      // measured 2026-09-18, a 49-page documentation site published 2 pages with
+      // every CLI instrument reporting success [measured:backend, channel with
+      // backend, and reproduced here against the same site].
+      await warnFolderModePagesSkipped(f.path, siteRoot)
     }
 
     const children = await walkPagesNested(ctx, f.path, slugPath, f.internalMode, f.config, false)
@@ -1332,20 +1371,38 @@ export async function siteProjectToDocument(siteRoot, opts = {}) {
   //     fingerprint `assets.json` recorded for it).
   // The app leaves an author's value alone.
   //
-  // ⚠️ This read "`url` and `preview_image` are BACKEND-STAMPED and framework emits
-  // NEITHER" until 2026-09-10. Neither half held: nothing stamped `url`, and leaving
-  // an app-written field off an allowlist destroys it on every push, because `info`
-  // is replaced whole.
+  // ⚠️ Until 2026-09-10 framework emitted no preview, on the premise that the host
+  // stamps it. Nothing did, and leaving an app-written field off an allowlist
+  // destroys it on every push, because `info` is replaced whole.
   setIf(info, 'preview', scalarString(siteYml.preview))
-  // ⭐ `url` — where the site is live, so a site card can link to it without opening
-  // the editor. The backend records it at every publish (stated by backend,
-  // 2026-09-10) and pull brings it into `site.yml::$url`; nothing in framework writes
-  // it. The `$` marks it as recorded rather than authored, like `$uuid` — and keeps it
-  // out of the rendered payload, where a bare `url:` would sit beside `seo.baseUrl`,
-  // the authored canonical address.
-  setIf(info, 'url', siteYml.$url)
+  // ⛔ `url` IS RETIRED (2026-09-17) — do not reintroduce it, in either direction.
+  // It carried where the site went live, read from `site.yml::$url` (which pull
+  // wrote), so a site card could link to it. That is a fact about a DEPLOY, not
+  // about the site: `publish` prints it and records it in `deploy.yml`, and a
+  // derived value must not round-trip (the round-trip law, uwx-format.md). The host
+  // no longer declares the field and refuses a push that carries it. A `$url` line
+  // left in an old site.yml is inert — nothing reads it, so nothing sends it.
+  // (uwx-format.md → info.url.)
 
   const ctx = { siteRoot, siteIndex: siteYml.index, sourceLocale, translations }
+  // ⛔ ONE `paths:` CONVENTION, TWO READERS, AND THIS ONE IS A STRICT SUBSET.
+  // The build honours sub-mounts — `paths: { pages/<segment>: <dir> }`, through
+  // `resolveMounts`/`mountEntriesOf` in `site/content-collector.js` — and this
+  // lane reads `paths.pages` alone. A sub-mounted folder therefore syncs as an
+  // EMPTY container: its directory on disk holds only the `folder.yml`, so it
+  // emits with no children and nothing anywhere says so. Measured 2026-09-18 on
+  // a site whose entire corpus was one sub-mount: 49 pages built, 2 pushed.
+  // Deferred by design for now (bidirectional-sync.md); warned about here so it
+  // is not also silent.
+  for (const [segment] of mountEntriesOf(siteYml.paths)) {
+    console.warn(
+      `uwx/site: \`paths: { pages/${segment}: … }\` is NOT read on the sync lane — ` +
+        `\`${segment}\` will be pushed as an empty container and none of the mounted ` +
+        `pages will reach the backend. A build mounts it normally. Inline the ` +
+        `directory under \`pages/${segment}/\` to push it, or ship the site with ` +
+        `\`uniweb export\` / \`uniweb deploy --host <adapter>\`.`
+    )
+  }
   const pagesPath = siteYml.paths?.pages
     ? join(siteRoot, siteYml.paths.pages)
     : join(siteRoot, 'pages')

package/src/uwx/yaml-upsert.js

@@ -60,7 +60,7 @@ export function upsertYamlScalar(filePath, key, value) {
  * rather than half-removed.
  *
  * @param {string} filePath
- * @param {string} key - a top-level scalar key (e.g. `$url`)
+ * @param {string} key - a top-level scalar key (e.g. `preview`)
  * @returns {boolean} true if the file changed
  */
 export function removeYamlScalar(filePath, key) {