@uniweb/build 0.52.7 → 0.53.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@uniweb/build",
-  "version": "0.52.7",
+  "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/semantic-parser": "^1.4.1",
     "@uniweb/schemas": "^0.3.3",
     "@uniweb/theming": "^0.1.15",
     "@uniweb/content-writer": "^0.3.4",
-    "@uniweb/projections": "^0.7.3"
+    "@uniweb/projections": "^0.7.3",
+    "@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,7 +74,7 @@
     "@tailwindcss/vite": "^4.0.0",
     "@vitejs/plugin-react": "^4.0.0 || ^5.0.0",
     "vite-plugin-svgr": "^4.0.0",
-    "@uniweb/runtime": "^0.26.4",
+    "@uniweb/runtime": "^0.26.5",
     "@uniweb/core": "^0.29.4"
   },
   "peerDependenciesMeta": {

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/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)
@@ -1346,6 +1385,24 @@ export async function siteProjectToDocument(siteRoot, opts = {}) {
   // (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')