@uniweb/build 1.3.7 → 1.3.9

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@uniweb/build",
-  "version": "1.3.7",
+  "version": "1.3.9",
   "description": "Build tooling for the Uniweb Component Web Platform",
   "type": "module",
   "exports": {
@@ -57,11 +57,11 @@
     "sharp": "^0.35.3",
     "yaml": "^2.5.0",
     "@uniweb/content-writer": "~1.1.2",
+    "@uniweb/schemas": "~1.3.1",
     "@uniweb/content-reader": "~1.4.0",
-    "@uniweb/projections": "~1.1.1",
-    "@uniweb/semantic-parser": "~1.8.1",
     "@uniweb/theming": "~1.2.0",
-    "@uniweb/schemas": "~1.3.1"
+    "@uniweb/projections": "~1.1.1",
+    "@uniweb/semantic-parser": "~1.8.1"
   },
   "optionalDependencies": {
     "@uniweb/runtime": "~1.1.4"

package/src/i18n/freeform-manifest.js

@@ -92,6 +92,19 @@ export async function loadManifest(localeDir) {
   }
 }
 
+/**
+ * A manifest as its file holds it — the one format for its two writers, the CLI's
+ * (`saveManifest`) and a pull's (`uwx/locale-sync.js::writeFreeformTranslations`).
+ * ⛔ Until 2026-10-17 the CLI wrote no final newline and a pull wrote one, so a pull
+ * that changed one entry of a CLI-written manifest also changed its last line.
+ *
+ * @param {Object} manifest
+ * @returns {string}
+ */
+export function manifestText(manifest) {
+  return JSON.stringify(manifest, null, 2) + '\n'
+}
+
 /**
  * Save the manifest for a locale
  *
@@ -106,7 +119,7 @@ export async function saveManifest(localeDir, manifest) {
     await mkdir(localeDir, { recursive: true })
   }
 
-  await writeFile(manifestPath, JSON.stringify(manifest, null, 2))
+  await writeFile(manifestPath, manifestText(manifest))
 }
 
 /**

package/src/i18n/freeform.js

@@ -346,8 +346,8 @@ function freeformSections(siteContent) {
 
 /**
  * What a site's content says about its free-form translations — the ONE index for the
- * build's stale and orphan check and for the CLI's `status --freeform`, `update-hash` and
- * `prune --freeform`, so no two of them can judge a file differently.
+ * build's stale and orphan check and for the CLI's `status --freeform`, `init-freeform`,
+ * `update-hash` and `prune --freeform`, so no two of them judge a file by different rules.
  *
  *   - `validPaths` — every path the renderer reads a section's translation from
  *     (`freeformPathsFor`), for every section it translates;
@@ -355,12 +355,19 @@ function freeformSections(siteContent) {
  *     translates, which a recorded hash is compared with;
  *   - `canJudge(path)` — whether this content can say a translation at `path` is
  *     orphaned. ⛔ Only a page section's (`pages/…`, `page-ids/…`), and not one for a page
- *     whose sections the content does not carry — a prerendered site with split content
- *     rewrites `site-content.json` without them. A record's (`records/…`) is read from
- *     records this content does not hold. A check that cannot see the source must never
- *     call its translation orphaned: `prune --freeform` deletes what it is told is.
+ *     whose sections the content does not carry — as a prerendered site's split
+ *     `site-content.json` does not. A record's (`records/…`) is read from records this
+ *     content does not hold. A check that cannot see the source must never call its
+ *     translation orphaned: `prune --freeform` deletes what it is told is.
  *
- * @param {Object} siteContent - collected site content, as `dist/site-content.json` holds it
+ * ⚠️ The rules are one; the content is the caller's. The CLI's commands pass the site's
+ * SOURCE, collected as `uniweb i18n extract` collects it, `hidden:` pages and sections
+ * included (`cli/src/commands/i18n.js::collectSourceContent`) — ⛔ until 2026-10-17 they read
+ * `dist/site-content.json`, split or not. The build passes what it publishes, before its
+ * prerender splits it: no `hidden:` page or section, so it warns of their translations as
+ * orphaned (a warning only — it deletes nothing).
+ *
+ * @param {Object} siteContent - collected site content
  * @returns {{ validPaths: Set<string>, sourceHashes: Object<string, string>, canJudge: (path: string) => boolean }}
  */
 export function freeformSourceIndex(siteContent) {

package/src/site/entity-pool.js

@@ -53,8 +53,7 @@
 // there is no population to carry): a leftover `entities/` beside `records/` would
 // otherwise hold records nothing reads, silently.
 
-import { readdir } from 'node:fs/promises'
-import { existsSync, readFileSync, statSync } from 'node:fs'
+import { existsSync, readFileSync, readdirSync, statSync } from 'node:fs'
 import { join, extname, basename, resolve } from 'node:path'
 import yaml from 'js-yaml'
 import { YAML_OPTIONS } from '../utils/yaml-schema.js'
@@ -263,6 +262,17 @@ export function poolPathReadings(dirs) {
  *   leaves the backend's folder alone for a site with no records directory.
  */
 export async function readEntityPool(siteRoot, opts = {}) {
+  return readEntityPoolSync(siteRoot, opts)
+}
+
+/**
+ * `readEntityPool`, for a caller that cannot wait — the pull's projection, which asks what a
+ * `folder.yml` already says (`records-project.js`). One walk, which the async form returns.
+ *
+ * @param {string} siteRoot
+ * @param {object} [opts] - as `readEntityPool`'s
+ */
+export function readEntityPoolSync(siteRoot, opts = {}) {
   let rel
   if (opts.dir) {
     rel = String(opts.dir).replace(/\/+$/, '')
@@ -280,10 +290,10 @@ export async function readEntityPool(siteRoot, opts = {}) {
   // A file record is named by its stem, so two files of one stem cannot both be one.
   const fileStems = new Map()
 
-  const walk = async (dir, dirs) => {
+  const walk = (dir, dirs) => {
     let listing
     try {
-      listing = await readdir(dir, { withFileTypes: true })
+      listing = readdirSync(dir, { withFileTypes: true })
     } catch {
       return
     }
@@ -304,7 +314,7 @@ export async function readEntityPool(siteRoot, opts = {}) {
           )
           continue
         }
-        await walk(full, [...dirs, e.name])
+        walk(full, [...dirs, e.name])
         continue
       }
       if (!e.isFile()) continue
@@ -356,7 +366,7 @@ export async function readEntityPool(siteRoot, opts = {}) {
     }
   }
 
-  await walk(base, [])
+  walk(base, [])
   return { entities, errors, exists: true, dir: rel }
 }
 

package/src/uwx/backfill.js

@@ -296,7 +296,13 @@ export function renderEntityDocument({ document, declaration, format, sourceLoca
   if (document?.$disabled === true) record.draft = true
 
   if (format === 'json') return JSON.stringify(record, null, 2) + '\n'
-  if (format === 'md') return `---\n${yaml.dump(record)}---\n${dec.body}`
+  if (format === 'md') {
+    // ⭐ Written as a section is (`project-writer.js::assembleSection`): a blank line after the front
+    // matter, and a final newline. ⛔ Until 2026-10-17 it had neither, so a pull that rewrote an
+    // edited record took both out of the author's file.
+    const body = String(dec.body ?? '').replace(/^(?:[ \t]*\n)+/, '').replace(/\s+$/, '')
+    return `---\n${yaml.dump(record)}---\n${body ? `\n${body}\n` : ''}`
+  }
   return yaml.dump(record) // yaml / yaml
 }
 

package/src/uwx/locale-sync.js

@@ -25,7 +25,7 @@ import { computeHash } from '../i18n/hash.js'
 import { blockElements, elementText, dataBlockNodes } from '../i18n/extract.js'
 import { visitDataBlockStrings } from '../i18n/data-strings.js'
 import { resolveDocForLocale, translatedInline, linkLabels, toPlainText } from '../i18n/merge.js'
-import { computeSourceHash } from '../i18n/freeform-manifest.js'
+import { computeSourceHash, manifestText } from '../i18n/freeform-manifest.js'
 import { sameMarkdownDocument, canonicalJson } from './same-content.js'
 import { parseFrontmatter } from '../utils/frontmatter.js'
 
@@ -304,12 +304,23 @@ export function isLocalizedContent(value) {
  */
 export function createTranslationCollector(sourceLocale, { siteRoot = null } = {}) {
   const byLocale = {} // { locale: { hash: target } }
+  // ⭐ What says each value read, in the place it was read — the push's own rule there — so the
+  // writer keeps an author's entry that says the same thing in another spelling (`reconcileTranslation`).
+  const says = {} // { locale: { hash: { plain?: (value) => boolean, values: { [contextKey]: (value) => boolean } } } }
   const freeformPending = [] // [{ locale, content }] — target-locale free-form bodies
 
+  function noteSays(locale, hash, context, check) {
+    const entry = ((says[locale] ||= {})[hash] ||= { plain: undefined, values: {} })
+    if (context) entry.values[contextKey(context)] = check
+    else entry.plain = check
+  }
+
   // Record a localized SCALAR field's target locales (hash of the source scalar). ⭐ With `context`
   // — the record it was read in (`{ key: '<pool>/<handle>' }`) — a translation that differs from one
   // record to another comes back as the author's `{ default, overrides }`, as a page section's does.
-  function add(localizedValue, context = null) {
+  // ⭐ `plainText` for a field the push sends as text (`plainTextTargets`): any value with those words
+  // says it.
+  function add(localizedValue, context = null, { plainText = false } = {}) {
     if (!isLocalizedMap(localizedValue)) return
     const source = localizedValue[sourceLocale]
     if (typeof source !== 'string' || source.length === 0) return
@@ -318,6 +329,7 @@ export function createTranslationCollector(sourceLocale, { siteRoot = null } = {
       if (locale === sourceLocale) continue
       if (typeof value !== 'string') continue
       const table = (byLocale[locale] ||= {})
+      noteSays(locale, hash, context, plainText ? saysAsText(value) : saysAsIs(value))
       if (!context) {
         if (table[hash] instanceof SeenInContexts) table[hash].plain = value
         else table[hash] = value
@@ -335,12 +347,14 @@ export function createTranslationCollector(sourceLocale, { siteRoot = null } = {
   // from one section to another is kept per section, and comes back as the author's
   // context-specific overrides (`writeLocaleTranslations`). ⛔ Until 2026-09-26 the last section
   // read won, and a pull wrote that one string over the author's `{ default, overrides }`.
-  function addStructuralMap(locale, map, context = null) {
+  // `checks` — what says each element's translation (`deriveStructuralMap`); a value as read, else.
+  function addStructuralMap(locale, map, context = null, checks = null) {
     if (locale === sourceLocale || !map || typeof map !== 'object' || Array.isArray(map)) return
     const table = (byLocale[locale] ||= {})
     for (const [src, target] of Object.entries(map)) {
       if (typeof src !== 'string' || typeof target !== 'string') continue
       const hash = computeHash(src)
+      noteSays(locale, hash, context, checks?.[src] ?? saysAsIs(target))
       if (!context) {
         if (table[hash] instanceof SeenInContexts) table[hash].plain = target
         else table[hash] = target
@@ -375,7 +389,7 @@ export function createTranslationCollector(sourceLocale, { siteRoot = null } = {
     return null
   }
 
-  return { add, addStructuralMap, noteFreeform, keptFreeform, byLocale, freeformPending }
+  return { add, addStructuralMap, noteFreeform, keptFreeform, byLocale, says, freeformPending }
 }
 
 /**
@@ -391,7 +405,7 @@ export function createTranslationCollector(sourceLocale, { siteRoot = null } = {
  * per-locale link hrefs survive. Keyed by the source element's cleaned text, so
  * `computeHash(key)` matches the extractor's unit hash — closing the round trip.
  */
-function deriveStructuralMap(sourceDoc, targetDoc, modelFor = () => null) {
+function deriveStructuralMap(sourceDoc, targetDoc, modelFor = () => null, checks = {}) {
   if (!isProseMirrorDoc(sourceDoc) || !isProseMirrorDoc(targetDoc)) return null
   const src = blockElements(sourceDoc)
   const tgt = blockElements(targetDoc)
@@ -406,12 +420,47 @@ function deriveStructuralMap(sourceDoc, targetDoc, modelFor = () => null) {
       const tgtMd = serializeInlineContent(tgt[i].content || [])
       if (srcMd === tgtMd) continue // unchanged → untranslated → omit
       map[key] = labelsAlone(src[i].content || [], tgt[i].content || [], tgtMd) ?? tgtMd
+      checks[key] = saysElement(src[i].content || [], tgtMd)
     }
   } catch {
     // a mark we can't serialize → don't risk a lossy map; store as free-form
     return null
   }
-  return addDataBlockStrings(map, sourceDoc, targetDoc, modelFor)
+  return addDataBlockStrings(map, sourceDoc, targetDoc, modelFor, checks)
+}
+
+// ⭐ WHAT SAYS A TRANSLATION, WHERE A PULL READ IT — the push's own rule for that place. A pull reads
+// one spelling back, and an author's entry may say the same thing in another: `[Faire un don](/contact)`
+// where the merge reads the label onto the source's own link, or `[Se connecter](/sign-in)` for a page
+// title, which the push sends as its words.
+//   - an element of a section: what `merge.js::translatedInline` makes of a value there;
+//   - a plain-text field (`plainTextTargets`): a value's words;
+//   - anything else: the value as read.
+function saysElement(source, pushed) {
+  return (value) => {
+    if (typeof value !== 'string') return false
+    try {
+      const back = translatedInline(source, value)
+      return !!back && serializeInlineContent(back) === pushed
+    } catch {
+      return false
+    }
+  }
+}
+
+function saysAsText(read) {
+  return (value) => {
+    if (typeof value !== 'string') return false
+    try {
+      return toPlainText(value) === read
+    } catch {
+      return false
+    }
+  }
+}
+
+function saysAsIs(read) {
+  return (value) => value === read
 }
 
 // Whether a free-form file says `target`, read as a push reads it — its body, as stored.
@@ -447,7 +496,7 @@ function labelsAlone(source, target, whole) {
 // A target that is not the source with only those strings changed — another shape, another `href` —
 // cannot be said per string, and the whole translation is free-form. ⛔ Until 2026-09-26 a data block
 // was not read here at all, and its translations were not sent (`merge.js::translateDataBlocks`).
-function addDataBlockStrings(map, sourceDoc, targetDoc, modelFor = () => null) {
+function addDataBlockStrings(map, sourceDoc, targetDoc, modelFor = () => null, checks = null) {
   const srcBlocks = dataBlockNodes(sourceDoc)
   const tgtBlocks = dataBlockNodes(targetDoc)
   if (srcBlocks.length !== tgtBlocks.length) return null
@@ -476,7 +525,10 @@ function addDataBlockStrings(map, sourceDoc, targetDoc, modelFor = () => null) {
     const rebuilt = JSON.parse(JSON.stringify(s.data))
     visitDataBlockStrings(rebuilt, (value) => pairs.get(value) ?? value, modelFor(s.tag))
     if (canonicalJson(rebuilt) !== canonicalJson(t.data)) return null
-    for (const [from, to] of pairs) map[from.trim()] = to
+    for (const [from, to] of pairs) {
+      map[from.trim()] = to
+      if (checks) checks[from.trim()] = saysAsIs(to)
+    }
   }
   return map
 }
@@ -501,8 +553,9 @@ export function unwrapLocalizedContent(content, sourceLocale, collector, freefor
     if (isProseMirrorDoc(value)) {
       // A translation the site keeps as a free-form file stays one, even when it lines up.
       const kept = collector?.keptFreeform?.(locale, freeformCandidates || freeformRelPath) || null
-      const map = kept ? null : deriveStructuralMap(source, value, modelFor)
-      if (map) collector?.addStructuralMap?.(locale, map, context)
+      const checks = {}
+      const map = kept ? null : deriveStructuralMap(source, value, modelFor, checks)
+      if (map) collector?.addStructuralMap?.(locale, map, context, checks)
       else collector?.noteFreeform?.(locale, value, source, kept || freeformRelPath)
     } else {
       collector?.addStructuralMap?.(locale, value, context)
@@ -525,37 +578,58 @@ class SeenInContexts {
 // still hold. The default is what the places without an override of their own say (the most of
 // them; the author's default when tied, else the first read). An override for a place this pull did
 // not see is kept, and one that now says the default is dropped.
-function reconcileTranslation(existing, seen) {
+// ⭐ A value AGREES with a place when, pushed there, it says what the pull read (`check`, from the
+// collector — the read value itself, where none was noted). So the author's entry is kept as written
+// wherever it still says what every place read: a pull that changes nothing writes nothing.
+// ⛔ Until 2026-10-17 values agreed only when spelled alike, and a pull rewrote an entry that says the
+// same thing another way: `[Faire un don](/contact)` to its label, a string a heading and a link
+// share into per-place overrides, a page title's `[Se connecter](/sign-in)` to its words.
+function reconcileTranslation(existing, seen, check = null) {
   const own = existing && typeof existing === 'object' && existing.overrides && typeof existing.overrides === 'object' ? existing.overrides : {}
   const authoredDefault = typeof existing === 'string' ? existing : existing && typeof existing === 'object' ? existing.default : undefined
-  const contexts = Object.entries(seen.values)
-  const candidates = [...(seen.plain !== undefined ? [seen.plain] : []), ...contexts.filter(([k]) => !(k in own)).map(([, v]) => v)]
+  // Each place read: its context's key (null where it has none), what it read, and what says that.
+  const places = [
+    ...(seen.plain !== undefined ? [[null, seen.plain, check?.plain ?? saysAsIs(seen.plain)]] : []),
+    ...Object.entries(seen.values).map(([k, v]) => [k, v, check?.values?.[k] ?? saysAsIs(v)]),
+  ]
+  const at = (k) => (k !== null && k in own ? own[k] : authoredDefault)
+  if (existing !== undefined && places.length && places.every(([k, , says]) => says(at(k)))) return existing
+  // The places the default speaks for: those with no override of the author's own.
+  const free = places.filter(([k]) => k === null || !(k in own))
   let def = authoredDefault
-  if (candidates.length) {
-    const counts = new Map()
-    for (const v of candidates) counts.set(v, (counts.get(v) || 0) + 1)
-    const most = Math.max(...counts.values())
-    const top = [...counts].filter(([, n]) => n === most).map(([v]) => v)
-    def = top.includes(authoredDefault) ? authoredDefault : top[0]
+  if (free.length) {
+    let most = -1
+    for (const candidate of [...(authoredDefault !== undefined ? [authoredDefault] : []), ...free.map(([, read]) => read)]) {
+      const agree = free.filter(([, , says]) => says(candidate)).length
+      if (agree > most) [def, most] = [candidate, agree]
+    }
   } else if (def === undefined) {
-    def = contexts[0]?.[1]
+    def = places.find(([k]) => k !== null)?.[1]
   }
   const overrides = { ...own }
-  for (const [k, v] of contexts) {
-    if (v === def) delete overrides[k]
-    else overrides[k] = v
+  for (const [k, read, says] of places) {
+    if (k === null) continue
+    if (says(def)) delete overrides[k]
+    else if (!(k in own && says(own[k]))) overrides[k] = read
   }
   return Object.keys(overrides).length ? { default: def, overrides } : def
 }
 
 /**
  * Write captured target-locale FREE-FORM bodies to `locales/freeform/{locale}/<relpath>`
- * (markdown, body-only) and record each one's SOURCE hash in that locale's
+ * (markdown, body-only) and record the SOURCE hash of each one it writes in that locale's
  * `.manifest.json` for staleness tracking. Sync + idempotent: a body is rewritten
  * only when its markdown changes, and a manifest `recorded` date is (re)stamped only
  * when the source hash changes — so a no-op re-projection is byte-stable. Entries
  * with no `relpath` (unplaceable, e.g. a layout section) are surfaced as `skipped`.
  *
+ * ⭐ A MANIFEST ENTRY SAYS WHICH SOURCE A TRANSLATION WAS MADE FROM, so it is stamped only with a
+ * translation this pull writes. One the pull leaves as it is keeps the author's entry, whatever it
+ * says: a translation the source has moved past stays stale. ⛔ Until 2026-10-17 every pull
+ * stamped the hash of the source it brought — the stale translation came back current, and a
+ * manifest recorded under another reading of an unchanged source was rewritten by a pull that
+ * changed nothing.
+ *
  * @returns {{ written: string[], skipped: object[] }}
  */
 export function writeFreeformTranslations(siteRoot, freeformPending) {
@@ -600,12 +674,11 @@ export function writeFreeformTranslations(siteRoot, freeformPending) {
       // markdown is not theirs (blank lines, line breaks), as for a section body (`writeSectionFile`).
       // Compared as a push reads it (`i18n/freeform.js::loadFreeformTranslation`). ⛔ Until 2026-10-08 the
       // file was trimmed first, so one whose last line ended in a space was rewritten by every pull.
-      if (current !== text && !(current !== null && sameStoredFreeform(current, filePath, target))) {
-        mkdirSync(dirname(filePath), { recursive: true })
-        writeFileSync(filePath, text)
-        report.written.push(filePath)
-      }
-      // Staleness hash of the SOURCE; re-stamp `recorded` only when it changes.
+      if (current === text || (current !== null && sameStoredFreeform(current, filePath, target))) continue
+      mkdirSync(dirname(filePath), { recursive: true })
+      writeFileSync(filePath, text)
+      report.written.push(filePath)
+      // Staleness hash of the SOURCE this translation comes with; re-stamp `recorded` only when it changes.
       const hash = computeSourceHash(source)
       const existing = manifest[relpath]
       if (!existing || existing.hash !== hash) {
@@ -616,7 +689,7 @@ export function writeFreeformTranslations(siteRoot, freeformPending) {
 
     if (manifestChanged) {
       mkdirSync(localeDir, { recursive: true })
-      writeFileSync(manifestPath, JSON.stringify(manifest, null, 2) + '\n')
+      writeFileSync(manifestPath, manifestText(manifest))
     }
   }
 
@@ -664,9 +737,14 @@ function jsonObjectText(entries) {
  * in the file, and new ones follow it, sorted, so a pull that changes nothing writes
  * nothing. Creates `locales/` if absent.
  *
+ * @param {string} siteRoot
+ * @param {object} byLocale - the collector's `byLocale`
+ * @param {string} [subdir] - `records` for record translations
+ * @param {object} [says] - the collector's `says`: what says each value read, in its place
+ *   (`reconcileTranslation`). Without it, a value says only itself.
  * @returns {{ [locale: string]: 'updated' | 'unchanged' }}
  */
-export function writeLocaleTranslations(siteRoot, byLocale, subdir = '') {
+export function writeLocaleTranslations(siteRoot, byLocale, subdir = '', says = null) {
   const report = {}
   for (let [locale, entries] of Object.entries(byLocale || {})) {
     if (!entries || Object.keys(entries).length === 0) continue
@@ -692,9 +770,13 @@ export function writeLocaleTranslations(siteRoot, byLocale, subdir = '') {
     // whole file by hash — measured on the `international` template, whose `es.json` runs in page
     // order: a pull that changed no translation rewrote all 77 lines.
     // A translation read in several sections becomes the string or the `{ default, overrides }` the
-    // author keeps (`reconcileTranslation`).
+    // author keeps (`reconcileTranslation`) — and one read in one place too, which keeps an entry
+    // that says it in another spelling, and an override for a place the pull did not see.
     entries = Object.fromEntries(
-      Object.entries(entries).map(([key, value]) => [key, value instanceof SeenInContexts ? reconcileTranslation(existing[key], value) : value])
+      Object.entries(entries).map(([key, value]) => [
+        key,
+        reconcileTranslation(existing[key], value instanceof SeenInContexts ? value : new SeenInContexts(value), says?.[locale]?.[key]),
+      ])
     )
     const fresh = Object.keys(entries).filter((key) => !(key in existing)).sort()
     if (fresh.length === 0 && Object.entries(entries).every(([key, value]) => canonicalJson(existing[key]) === canonicalJson(value))) {

package/src/uwx/open-graph.js

@@ -61,7 +61,8 @@ export function foldOpenGraph(holder, seo, sourceLocale, collector = null, conte
   for (const [wire, key] of OPEN_GRAPH_KEYS) {
     const value = holder?.[wire]
     if (value === undefined) continue
-    collector?.add(value, context)
+    // A plain-text field: the push sends a translation's words (`plainTextTargets`).
+    collector?.add(value, context, { plainText: true })
     const source = unwrapLocalized(value, sourceLocale)
     if (typeof source === 'string' && source !== '') out[key] = source
   }

package/src/uwx/project-writer.js

@@ -418,14 +418,16 @@ function restates(authored, decl) {
  * (`records/`, or wherever `site.yml::paths.records` puts it), as a LIST.
  *
  * ⛔ A FULL WRITE, NOT A MERGE, and that is the one place this differs from every
- * other projected config. The file mirrors the folder's sub-folders: concrete refs
- * on both sides, nothing to invert, so a pull is a mirror rather than an update.
- * There is also nothing a shallow merge could mean here — the file is a sequence,
- * and merging two lists either duplicates entries or silently drops them.
+ * other projected config: the file is a sequence, and merging two lists either
+ * duplicates entries or silently drops them.
  *
- * The caller decides whether there is anything to write: a folder with no
- * sub-folders is no file at all (`folderToFolderYml` removes it), since missing and
- * empty mean the same. ⚠️ *Until 2026-09-21 this said an empty file was destructive
+ * The caller decides whether there is anything to write: a file that already says
+ * what the pulled folder says — its patterns included — is left alone
+ * (`records-project.js::organizesAlike`), and a folder with no sub-folders is no file
+ * at all (`folderToFolderYml` removes it), since missing and empty mean the same.
+ * ⛔ *Until 2026-10-17 this called the file a mirror — "concrete refs on both sides,
+ * nothing to invert" — and every pull wrote the folder's paths over a developer's
+ * patterns.* ⚠️ *Until 2026-09-21 this said an empty file was destructive
  * on the next push; that stopped being true when the directory, not this file,
  * became what decides which records the folder holds.*
  *

package/src/uwx/records-project.js

@@ -43,8 +43,9 @@ import { parseFrontmatter } from './entity-source.js'
 import { writeRecordFile, writeQueriesConfig, writeRecordsConfig } from './project-writer.js'
 import { foundationDataSchemas, foundationSchemaJson, QUERIES_YML_RELPATH } from './queries-config.js'
 import { dataKeyTypes } from './data-key-types.js'
-import { poolDirsForSchema, schemaForPoolDirs, resolveRecordsDir } from '../site/entity-pool.js'
-import { folderYmlPath } from '../site/records-config.js'
+import { poolDirsForSchema, schemaForPoolDirs, resolveRecordsDir, readEntityPoolSync } from '../site/entity-pool.js'
+import { folderYmlPath, resolveFolder } from '../site/records-config.js'
+import { canonicalJson } from './same-content.js'
 import { contentBodyTarget } from './record-layout.js'
 import { qualifyRef } from '@uniweb/schemas/refs'
 import { unresolveSelfScope, ownSchemaNames, refuseOrgOption } from './self-scope.js'
@@ -501,9 +502,14 @@ export function declarationsToQueriesYml({ document, siteRoot, scope, ...rest })
  * Project a pulled `@uniweb/folder` document back to `folder.yml` in the records
  * directory (`records/folder.yml`, or under `site.yml::paths.records`).
  *
- * ⭐ THE FOLDER ROUND-TRIPS TRIVIALLY, and that is by design rather than luck:
- * `folder.yml` holds concrete paths on both sides, so there is nothing to invert.
- * The old shape put QUERY MACROS in the folder — a virtual `folders:` tree naming
+ * ⭐ A FILE THAT SAYS WHAT THE PULLED FOLDER SAYS IS LEFT AS WRITTEN — its patterns
+ * (`member/*.md`), its comments, its order (`organizesAlike`). Otherwise the folder
+ * is written as the paths the backend's folder places, which is what it says.
+ * ⛔ *This read "the folder round-trips trivially: `folder.yml` holds concrete paths
+ * on both sides, so there is nothing to invert" until 2026-10-17 — read as "the file
+ * holds no patterns", which it does — and every pull with a folder wrote its paths
+ * over the developer's patterns: a record added afterwards fell outside them.* The
+ * old shape put QUERY MACROS in the folder — a virtual `folders:` tree naming
  * collections — and inverting a macro is not possible in general. Taking queries
  * out of the folder is what dissolved that.
  *
@@ -600,6 +606,16 @@ export function folderToFolderYml({ folderDoc, siteRoot, poolPathByUuid, sourceL
 
   const entries = walk(folderDoc.contents, false)
   if (unplaceable) return { status: 'skipped', entries: [], warnings, file }
+  if (existsSync(abs) && organizesAlike({ abs, entries, siteRoot, poolPathByUuid })) {
+    return { status: 'unchanged', entries, warnings, file }
+  }
+  // Said when it replaces a developer's pattern: a record they add from here is placed by nothing.
+  if (existsSync(abs) && holdsPattern(abs)) {
+    warnings.push(
+      `${file}: the folder no longer places its records as its patterns say, so it was written as their ` +
+        `paths. A record you add from here sits at the top of the folder until ${file} places it.`
+    )
+  }
   if (entries.length === 0) {
     if (!existsSync(abs)) return { status: 'unchanged', entries, warnings, file }
     unlinkSync(abs)
@@ -608,6 +624,67 @@ export function folderToFolderYml({ folderDoc, siteRoot, poolPathByUuid, sourceL
   return { status: writeRecordsConfig(siteRoot, entries), entries, warnings, file }
 }
 
+/**
+ * Does the `folder.yml` on disk say what the pulled folder says — read by the rule a push reads it
+ * by (`resolveFolder`), over the records directory as this pull left it?
+ *
+ * ⭐ About the records the backend's folder holds, every word: the folders, by name, label and tags,
+ * in order; and each record's folder, its tags and label, and its place among the others. Records
+ * the backend does not hold yet — a file the developer added and has not pushed — are theirs, so a
+ * pattern placing one is not a difference; nor is a folder holding only those. So `member/*.md` is
+ * kept while it places exactly the members the backend's folder has there, and goes on placing the
+ * next one the developer adds.
+ *
+ * @returns {boolean}
+ */
+function organizesAlike({ abs, entries, siteRoot, poolPathByUuid }) {
+  let authored
+  try {
+    authored = yaml.load(readFileSync(abs, 'utf8'), YAML_OPTIONS)
+  } catch {
+    return false
+  }
+  if (!Array.isArray(authored)) return false
+  const pool = readEntityPoolSync(siteRoot).entities
+  const pulled = new Set(poolPathByUuid.values())
+  const held = new Set(pool.filter((e) => pulled.has(e.poolPath)).map((e) => e.id))
+  const mine = resolveFolder(authored, pool)
+  const theirs = resolveFolder(entries, pool)
+  if (mine.errors.length || theirs.errors.length) return false
+  const theirFolders = new Set()
+  const said = (n) => ({ ...(n.label != null ? { label: n.label } : {}), ...(n.tags ? { tags: n.tags } : {}) })
+  // A tree as it reads for the held records. `keep(path, holds)` decides whether a folder stays.
+  const shape = (nodes, at, keep) =>
+    (nodes || []).flatMap((n) => {
+      if (n.kind === 'ref') return held.has(n.$entityId) ? [{ record: n.$entityId, ...said(n) }] : []
+      if (n.kind !== 'branch') return []
+      const path = [...at, n.name]
+      const records = shape(n.$children, path, keep)
+      return keep(path.join('/'), records.length > 0) ? [{ folder: n.name, ...said(n), records }] : []
+    })
+  // Every folder the backend has stays, empty or not; one of the file's stays when it holds a held
+  // record or the backend has it too — else it is the developer's, not pushed yet.
+  const theirShape = shape(theirs.nodes, [], (path) => (theirFolders.add(path), true))
+  const myShape = shape(mine.nodes, [], (path, holds) => holds || theirFolders.has(path))
+  return canonicalJson(myShape) === canonicalJson(theirShape)
+}
+
+// Does the `folder.yml` on disk place records by a pattern (`member/*.md`) anywhere?
+function holdsPattern(abs) {
+  let authored
+  try {
+    authored = yaml.load(readFileSync(abs, 'utf8'), YAML_OPTIONS)
+  } catch {
+    return false
+  }
+  const has = (entries) =>
+    (Array.isArray(entries) ? entries : []).some((entry) => {
+      const path = typeof entry === 'string' ? entry : entry?.path
+      return (typeof path === 'string' && /[*?]/.test(path)) || has(entry?.records)
+    })
+  return has(authored)
+}
+
 /**
  * Project a pulled folder + its record entities to `records/**` files.
  *
@@ -823,7 +900,7 @@ export function recordsToProject({ folderDoc, recordDocs = [], siteRoot, opts =
 
   // Flush localized record-field translations to locales/records/{locale}.json,
   // and any prosemirror free-form body overrides to locales/freeform/{locale}/.
-  const locales = writeLocaleTranslations(siteRoot, collector.byLocale, 'records')
+  const locales = writeLocaleTranslations(siteRoot, collector.byLocale, 'records', collector.says)
   const freeform = writeFreeformTranslations(siteRoot, collector.freeformPending)
 
   if (opts.backend && Object.keys(learned).length) {

package/src/uwx/site-project.js

@@ -224,7 +224,8 @@ export function siteInfoToConfig({ document, siteRoot, backend = null, sourceLoc
   // Localized text fields → unwrapped to the source locale (the target locales are
   // captured into the locales/ collector when one is supplied).
   collector?.add(info.name)
-  collector?.add(info.description)
+  // A plain-text field: the push sends a translation's words (`plainTextTargets`).
+  collector?.add(info.description, null, { plainText: true })
   const name = unwrapLocalized(info.name, sourceLocale)
   if (name !== undefined) siteChanges.name = name
   const description = unwrapLocalized(info.description, sourceLocale)
@@ -273,7 +274,7 @@ export function siteInfoToConfig({ document, siteRoot, backend = null, sourceLoc
 
   // `settings.keywords` is a LOCALIZED list (it renders into `<meta name="keywords">`)
   // → unwrap to the source locale; the target locales go to the collector.
-  if (Array.isArray(settingsSection.keywords)) settingsSection.keywords.forEach((kw) => collector?.add(kw))
+  if (Array.isArray(settingsSection.keywords)) settingsSection.keywords.forEach((kw) => collector?.add(kw, null, { plainText: true }))
   const settingsKeywords = unwrapLocalizedList(settingsSection.keywords, sourceLocale)
   if (settingsKeywords !== undefined) siteChanges.keywords = settingsKeywords
 
@@ -816,15 +817,17 @@ function writePagesTree(pages, pagesDir, sourceLocale, report, ctx, routePrefix
     // Capture target-locale translations of the page's localized scalars; the
     // source value goes inline into page.yml below (pageRecordToYml unwraps it). In the page's
     // context, as the build translates them (`<route>:_meta`), so an override for one page comes back.
+    // Each a plain-text field: the push sends a translation's words (`site.js::localizePageMeta`).
     const meta = { page: canon, section: '_meta' }
-    ctx.collector?.add(record.title, meta)
-    ctx.collector?.add(record.label, meta)
-    ctx.collector?.add(record.description, meta)
-    ctx.collector?.add(record.og_title, meta)
-    ctx.collector?.add(record.og_description, meta)
+    const text = { plainText: true }
+    ctx.collector?.add(record.title, meta, text)
+    ctx.collector?.add(record.label, meta, text)
+    ctx.collector?.add(record.description, meta, text)
+    ctx.collector?.add(record.og_title, meta, text)
+    ctx.collector?.add(record.og_description, meta, text)
     // keywords is a localized ARRAY — capture each element's target locales.
-    if (Array.isArray(record.keywords)) record.keywords.forEach((kw) => ctx.collector?.add(kw, meta))
-    else ctx.collector?.add(record.keywords, meta)
+    if (Array.isArray(record.keywords)) record.keywords.forEach((kw) => ctx.collector?.add(kw, meta, text))
+    else ctx.collector?.add(record.keywords, meta, text)
 
     const route = routePrefix ? `${routePrefix}/${slug}` : slug
     // Addressed as the push addresses it: its free-form translations and its translations' contexts
@@ -1347,7 +1350,7 @@ export function siteContentDocumentToProject({ document, siteRoot, backend = nul
   }
   projectLayout(document?.layout_sections, layoutBaseDir, report, prune, ctx)
 
-  report.locales = writeLocaleTranslations(siteRoot, collector.byLocale)
+  report.locales = writeLocaleTranslations(siteRoot, collector.byLocale, '', collector.says)
   // Target-locale FREE-FORM bodies → locales/freeform/{locale}/<relpath> + manifest.
   report.freeform = writeFreeformTranslations(siteRoot, collector.freeformPending)
   writePullIndex(siteRoot, ctx.newIndex)