@uniweb/build 0.74.4 → 0.75.1

package/src/i18n/merge.js

@@ -15,7 +15,7 @@
 import { computeHash } from './hash.js'
 import { loadFreeformTranslation } from './freeform.js'
 import { elementText, blockElements, translationContext, SITE_META_CONTEXT } from './extract.js'
-import { visitDataStrings } from './data-strings.js'
+import { visitDataBlockStrings } from './data-strings.js'
 
 // Inline-markdown → ProseMirror inline fragment, for resolving a whole-element
 // translation VALUE (which carries marks/links/icons as inline markdown). Same
@@ -42,6 +42,9 @@ try {
  * @param {string} [options.locale] - Locale code for free-form lookups
  * @param {string} [options.localesDir] - Path to locales directory
  * @param {boolean} [options.freeformEnabled=false] - Enable free-form translation lookup
+ * @param {(type: string, tag: string) => Object|null} [options.dataModel] - what each section type
+ *   declares its data blocks are (`data-models.js::dataBlockModels`), so a block translates the
+ *   fields extraction offered; without it, every block is walked by the heuristic
  * @returns {Object|Promise<Object>} Translated site content (async if freeformEnabled)
  */
 export function mergeTranslations(siteContent, translations, options = {}) {
@@ -49,7 +52,8 @@ export function mergeTranslations(siteContent, translations, options = {}) {
     fallbackToSource = true,
     locale = null,
     localesDir = null,
-    freeformEnabled = false
+    freeformEnabled = false,
+    dataModel = null
   } = options
 
   // If free-form is enabled, use async version
@@ -57,18 +61,19 @@ export function mergeTranslations(siteContent, translations, options = {}) {
     return mergeTranslationsAsync(siteContent, translations, {
       fallbackToSource,
       locale,
-      localesDir
+      localesDir,
+      dataModel
     })
   }
 
   // Sync version (original behavior)
-  return mergeTranslationsSync(siteContent, translations, fallbackToSource)
+  return mergeTranslationsSync(siteContent, translations, fallbackToSource, dataModel)
 }
 
 /**
  * Synchronous merge (original behavior, no free-form)
  */
-function mergeTranslationsSync(siteContent, translations, fallbackToSource) {
+function mergeTranslationsSync(siteContent, translations, fallbackToSource, dataModel = null) {
   // Deep clone to avoid mutating original
   const translated = JSON.parse(JSON.stringify(siteContent))
   translateSiteMeta(translated.config, translations, fallbackToSource)
@@ -81,7 +86,7 @@ function mergeTranslationsSync(siteContent, translations, fallbackToSource) {
 
     // Translate section content
     for (const section of page.sections || []) {
-      translateSectionSync(section, pageRoute, translations, fallbackToSource)
+      translateSectionSync(section, pageRoute, translations, fallbackToSource, dataModel)
     }
   }
 
@@ -90,7 +95,7 @@ function mergeTranslationsSync(siteContent, translations, fallbackToSource) {
     const pageRoute = translated.notFound.route || '/404'
     translatePageMeta(translated.notFound, pageRoute, translations, fallbackToSource)
     for (const section of translated.notFound.sections || []) {
-      translateSectionSync(section, pageRoute, translations, fallbackToSource)
+      translateSectionSync(section, pageRoute, translations, fallbackToSource, dataModel)
     }
   }
 
@@ -103,7 +108,7 @@ function mergeTranslationsSync(siteContent, translations, fallbackToSource) {
         if (layoutPage?.sections) {
           const pageRoute = layoutPage.route || `/layout/${layoutName === 'default' ? '' : layoutName + '/'}${areaKey}`
           for (const section of layoutPage.sections) {
-            translateSectionSync(section, pageRoute, translations, fallbackToSource)
+            translateSectionSync(section, pageRoute, translations, fallbackToSource, dataModel)
           }
         }
       }
@@ -117,7 +122,7 @@ function mergeTranslationsSync(siteContent, translations, fallbackToSource) {
  * Asynchronous merge with free-form support
  */
 async function mergeTranslationsAsync(siteContent, translations, options) {
-  const { fallbackToSource, locale, localesDir } = options
+  const { fallbackToSource, locale, localesDir, dataModel } = options
 
   // Deep clone to avoid mutating original
   const translated = JSON.parse(JSON.stringify(siteContent))
@@ -134,7 +139,8 @@ async function mergeTranslationsAsync(siteContent, translations, options) {
       await translateSectionAsync(section, page, translations, {
         fallbackToSource,
         locale,
-        localesDir
+        localesDir,
+        dataModel
       })
     }
   }
@@ -147,7 +153,8 @@ async function mergeTranslationsAsync(siteContent, translations, options) {
       await translateSectionAsync(section, translated.notFound, translations, {
         fallbackToSource,
         locale,
-        localesDir
+        localesDir,
+        dataModel
       })
     }
   }
@@ -164,7 +171,8 @@ async function mergeTranslationsAsync(siteContent, translations, options) {
             await translateSectionAsync(section, layoutPage, translations, {
               fallbackToSource,
               locale,
-              localesDir
+              localesDir,
+              dataModel
             })
           }
         }
@@ -281,17 +289,17 @@ function translatePageMeta(page, pageRoute, translations, fallbackToSource) {
 /**
  * Translate a section's content (synchronous, hash-based only)
  */
-function translateSectionSync(section, pageRoute, translations, fallbackToSource) {
+function translateSectionSync(section, pageRoute, translations, fallbackToSource, dataModel = null) {
   const context = translationContext(section, pageRoute)
 
   if (section.content?.type === 'doc') {
     translateProseMirrorDoc(section.content, context, translations, fallbackToSource)
-    translateDataBlocks(section.content, context, translations, fallbackToSource)
+    translateDataBlocks(section.content, context, translations, fallbackToSource, (tag) => dataModel?.(section.type, tag) ?? null)
   }
 
   // Recursively translate subsections
   for (const subsection of section.subsections || []) {
-    translateSectionSync(subsection, pageRoute, translations, fallbackToSource)
+    translateSectionSync(subsection, pageRoute, translations, fallbackToSource, dataModel)
   }
 }
 
@@ -303,7 +311,7 @@ function translateSectionSync(section, pageRoute, translations, fallbackToSource
  * 2. Fall back to hash-based translation (element-by-element)
  */
 async function translateSectionAsync(section, page, translations, options) {
-  const { fallbackToSource, locale, localesDir } = options
+  const { fallbackToSource, locale, localesDir, dataModel } = options
   const pageRoute = page.route || '/'
   const context = translationContext(section, pageRoute)
 
@@ -318,7 +326,7 @@ async function translateSectionAsync(section, page, translations, options) {
     // Fall back to hash-based translation
     if (section.content?.type === 'doc') {
       translateProseMirrorDoc(section.content, context, translations, fallbackToSource)
-      translateDataBlocks(section.content, context, translations, fallbackToSource)
+      translateDataBlocks(section.content, context, translations, fallbackToSource, (tag) => dataModel?.(section.type, tag) ?? null)
     }
   }
 
@@ -345,16 +353,16 @@ function translateProseMirrorDoc(doc, context, translations, fallbackToSource) {
   return changed
 }
 
-// Replace one block element's inline content with the parsed translation
-// fragment. `lookupTranslation` with the already-trimmed key adds no surrounding
-// whitespace and returns the source on a miss, so `value === key` means
-// "no translation" → leave the element as-is. Returns true if it replaced.
+// Replace one block element's inline content with what its translation gives it
+// (`translatedInline`). `lookupTranslation` with the already-trimmed key adds no
+// surrounding whitespace and returns the source on a miss, so `value === key`
+// means "no translation" → leave the element as-is. Returns true if it replaced.
 function applyElementTranslation(node, context, translations, fallbackToSource) {
   const key = elementText(node)
   if (!key) return false
   const value = lookupTranslation(key, context, translations, fallbackToSource)
   if (value === key) return false
-  const fragment = inlineMarkdownToFragment(value)
+  const fragment = translatedInline(node.content, value)
   if (fragment && fragment.length) {
     node.content = fragment
     return true
@@ -362,6 +370,129 @@ function applyElementTranslation(node, context, translations, fallbackToSource)
   return false
 }
 
+/**
+ * ⭐ WHAT A TRANSLATION GIVES AN ELEMENT: its value, parsed as inline markdown — with one
+ * exception. A value that names no link, given to an element made only of links, is their
+ * LABELS: a button's translation is its label (`Créer un groupe`), and buttons on consecutive
+ * lines take one label per line. Each keeps its source link — its target and its attributes
+ * (`{role=primary icon=…}`), which are structure, not words.
+ *
+ * ⛔ Until 2026-10-01 the value replaced the element whole, so a label translated on its own lost
+ * its link: the button became a plain paragraph, or vanished from a section that renders only
+ * links. Locale files keyed before whole-element keying hold exactly such labels.
+ *
+ * A value that writes a link is taken as written, re-targeted or not. So is a plain value for an
+ * element that mixes words and links, since which words were linked cannot be known;
+ * `uniweb i18n status` reports that loss (`translationKeepsMarkup`).
+ *
+ * @param {Array} source - the element's source inline content
+ * @param {string} value - the translation, inline markdown
+ * @returns {Array|null} the translated inline content; null for an empty value
+ */
+export function translatedInline(source, value) {
+  const fragment = inlineMarkdownToFragment(value)
+  if (!fragment) return null
+  return asLinkLabels(source, fragment) || fragment
+}
+
+/**
+ * Does a translation keep the inline markup of its source element? The merge's own answer —
+ * what `translatedInline` makes of the value — so the audit can neither report a loss the merge
+ * does not make nor miss one it does.
+ *
+ * @param {string} markup - the source element's inline markdown (a manifest unit's `markup`)
+ * @param {string} value - the translation
+ * @returns {boolean}
+ */
+export function translationKeepsMarkup(markup, value) {
+  const result = translatedInline(inlineMarkdownToFragment(markup) || [], value) || []
+  return result.some((node) => node.type !== 'text' || (node.marks && node.marks.length > 0))
+}
+
+// The source's links with the fragment as their labels — the whole fragment for one link, a line
+// each for several — or null: the fragment names a link of its own, the source is not only links,
+// or the lines do not match the links one to one.
+function asLinkLabels(source, fragment) {
+  if (fragment.some((node) => linkMarkOf(node))) return null
+  const links = linkRuns(source)
+  if (!links) return null
+  const labels = links.length === 1 ? [trimInline(fragment)] : inlineLines(fragment)
+  if (labels.length !== links.length || labels.some((label) => !label.length)) return null
+  const out = []
+  links.forEach((link, i) => {
+    if (i > 0) out.push(...link.before)
+    for (const node of labels[i]) out.push(withMarks(node, link.marks))
+  })
+  return out
+}
+
+// An element made only of links, as its runs: each link's marks (those all its text shares) and
+// the line breaks or spaces before it. Null when anything else is in it — words outside a link,
+// an icon, an image.
+function linkRuns(source) {
+  const runs = []
+  let gap = []
+  for (const node of source || []) {
+    if (!node) continue
+    const link = linkMarkOf(node)
+    if (link) {
+      const last = runs[runs.length - 1]
+      if (last && !gap.length && sameMark(last.link, link)) {
+        last.marks = last.marks.filter((mark) => node.marks.some((own) => sameMark(own, mark)))
+      } else {
+        runs.push({ link, marks: [...node.marks], before: gap })
+      }
+      gap = []
+    } else if (node.type === 'hardBreak' || (node.type === 'text' && !node.marks?.length && !node.text?.trim())) {
+      gap.push(node)
+    } else {
+      return null
+    }
+  }
+  return runs.length ? runs : null
+}
+
+function linkMarkOf(node) {
+  return node?.type === 'text' ? node.marks?.find((mark) => mark.type === 'link') || null : null
+}
+
+function sameMark(a, b) {
+  return Boolean(a && b) && a.type === b.type && JSON.stringify(a.attrs || {}) === JSON.stringify(b.attrs || {})
+}
+
+// A fragment's lines, split at line breaks, each trimmed; blank lines dropped.
+function inlineLines(fragment) {
+  const lines = [[]]
+  for (const node of fragment) {
+    if (node.type === 'hardBreak') {
+      lines.push([])
+    } else if (node.type === 'text' && node.text.includes('\n')) {
+      node.text.split('\n').forEach((part, i) => {
+        if (i > 0) lines.push([])
+        if (part) lines[lines.length - 1].push({ ...node, text: part })
+      })
+    } else {
+      lines[lines.length - 1].push(node)
+    }
+  }
+  return lines.map(trimInline).filter((line) => line.length)
+}
+
+// Leading and trailing whitespace off a run of inline nodes.
+function trimInline(nodes) {
+  const out = nodes.map((node) => ({ ...node }))
+  if (out[0]?.type === 'text') out[0].text = out[0].text.replace(/^\s+/, '')
+  const last = out[out.length - 1]
+  if (last?.type === 'text') last.text = last.text.replace(/\s+$/, '')
+  return out.filter((node) => node.type !== 'text' || node.text)
+}
+
+// A label node with its link's marks; a mark of its own of another type stays.
+function withMarks(node, marks) {
+  const own = (node.marks || []).filter((mark) => !marks.some((linkMark) => linkMark.type === mark.type))
+  return { ...node, marks: [...marks, ...own] }
+}
+
 /**
  * Translate the human-readable strings inside a section's TAGGED DATA BLOCKS,
  * in place. The other half of the fix in `extract.js` — a manifest entry nobody
@@ -373,9 +504,15 @@ function applyElementTranslation(node, context, translations, fallbackToSource)
  * silently; it now does (`uwx/locale-sync.js::deriveStructuralMap`), so the two
  * halves travel together.
  *
+ * ⭐ A block whose key its section type declares the shape of translates the fields that shape says
+ * are text, and only those (`data-strings.js::visitDataBlockStrings`) — the fields extraction
+ * offered, so a translation of an enum's value that happens to share its words with prose elsewhere
+ * is never applied to it.
+ *
+ * @param {(tag: string) => Object|null} [modelFor] - the model of a block's key, by its tag
  * @returns {boolean} whether any value was translated
  */
-function translateDataBlocks(doc, context, translations, fallbackToSource) {
+function translateDataBlocks(doc, context, translations, fallbackToSource, modelFor = () => null) {
   let changed = false
   const walk = (nodes) => {
     for (const node of nodes || []) {
@@ -383,11 +520,11 @@ function translateDataBlocks(doc, context, translations, fallbackToSource) {
       if (node.type === 'dataBlock') {
         const data = node.attrs?.data
         if (data && typeof data === 'object') {
-          visitDataStrings(data, (value) => {
+          visitDataBlockStrings(data, (value) => {
             const translated = lookupTranslation(value, context, translations, fallbackToSource)
             if (translated !== value) changed = true
             return translated
-          })
+          }, modelFor(node.attrs?.tag))
         }
       } else if (Array.isArray(node.content)) {
         walk(node.content)
@@ -406,12 +543,15 @@ function translateDataBlocks(doc, context, translations, fallbackToSource) {
  * (so the caller can omit an untranslated locale — it falls back to the source
  * locale). Lets the sync producer emit a self-contained per-locale DOC instead of a
  * source-keyed map (which a consumer would otherwise resolve against the source).
+ *
+ * `modelFor` is the section's data-block models by tag — `(tag) => dataModel(section.type, tag)` —
+ * so a push translates a block as the build does; without it, blocks are walked by the heuristic.
  */
-export function resolveDocForLocale(sourceDoc, table, context = { page: '', section: '' }) {
+export function resolveDocForLocale(sourceDoc, table, context = { page: '', section: '' }, modelFor = () => null) {
   if (!sourceDoc || sourceDoc.type !== 'doc' || !table) return null
   const doc = JSON.parse(JSON.stringify(sourceDoc))
   const elements = translateProseMirrorDoc(doc, context, table, true)
-  const data = translateDataBlocks(doc, context, table, true)
+  const data = translateDataBlocks(doc, context, table, true, modelFor)
   return elements || data ? doc : null
 }
 

package/src/i18n/model-fields.js

@@ -0,0 +1,97 @@
+/**
+ * ⭐ A RECORD'S FIELDS, WALKED BY ITS MODEL — the shape a push sends it in, lowered by the push's
+ * own rule (`uwx/data-schema.js::toDataSchemaDeclaration`), which marks `localized` exactly the
+ * fields that travel per locale: text — never an enum, a value format (a URL, an email), a
+ * `translatable: false` field, a number, a date, a file or a reference.
+ *
+ * One walk for two things a model describes: a record (`records.js`), and a tagged data block whose
+ * key a section type declares the shape of (`data-strings.js::visitDataBlockStrings`).
+ */
+import { isOpenMapSection } from '../uwx/data-schema.js'
+
+export function isPlainObject(value) {
+  return !!value && typeof value === 'object' && !Array.isArray(value)
+}
+
+/**
+ * ⛔ A RECORD'S SYSTEM FIELDS ARE NEVER PROSE — never extracted, never translated, by
+ * either path. A `$`-prefixed key at any depth is the system's (`$name`, the handle a
+ * parametric page's URL names; `$uuid`; `$branch`, the folder a compiled list holds a
+ * record under), and a top-level `slug` is how a record's reader hands the file's name
+ * on. Until 2026-09-14 they became translation units, and a translation whose source
+ * happened to equal one rewrote it, so a record's page stopped matching its URL.
+ * ⛔ A top-level `path` was one too until 2026-09-27, when the placement it named moved to
+ * `$branch` [Diego]: a field an author names `path` is theirs, and translated as its schema says.
+ *
+ * @param {string|number} key - a field name (an array index is never one)
+ * @param {boolean} topLevel - whether the key sits at the record's own level
+ * @returns {boolean}
+ */
+export function isRecordSystemField(key, topLevel) {
+  if (typeof key !== 'string') return false
+  return key.startsWith('$') || (topLevel && key === 'slug')
+}
+
+/**
+ * Each field of a model that a record holds a value for, in the shape the record is DELIVERED in
+ * (`toDeliveredRecord`): the brief's fields at the top — every field, for a model of one single
+ * section — and each other section under its name, a list of them for a `multiple` one, a nested
+ * section the same way. Calls `visit(holder, name, field, path)` for each.
+ */
+export function eachModelField(record, model, visit) {
+  const sections = Object.entries(model?.sections || {})
+  const flat = sections.length === 1 && !sections[0][1]?.multiple
+  for (const [name, section] of sections) {
+    if (flat || section?.brief) eachSectionField(record, section?.fields, '', visit)
+    else eachSectionValue(record?.[name], section, name, visit)
+  }
+}
+
+function eachSectionValue(value, section, path, visit) {
+  if (!section?.multiple) return eachSectionField(value, section?.fields, path, visit)
+  if (Array.isArray(value)) value.forEach((item, i) => eachSectionField(item, section.fields, `${path}[${i}]`, visit))
+  // An open map as its file holds it: each entry is one of the rows a push sends (`isOpenMapSection`).
+  else if (isOpenMapSection(section) && isPlainObject(value)) {
+    for (const [key, item] of Object.entries(value)) eachSectionField(item, section.fields, `${path}.${key}`, visit)
+  }
+}
+
+export function eachSectionField(holder, fields, path, visit) {
+  if (!isPlainObject(holder)) return
+  for (const [name, field] of Object.entries(fields || {})) {
+    if (holder[name] == null || isRecordSystemField(name, !path)) continue
+    const at = path ? `${path}.${name}` : name
+    if (field?.type === 'section') eachSectionValue(holder[name], field, at, visit)
+    else visit(holder, name, field || {}, at)
+  }
+}
+
+/**
+ * Each string a record's model marks `localized` — a text field's value, or each string of a list
+ * of them — handed to `visit(value, path)`; a different string returned replaces it, in place, as
+ * `data-strings.js::visitDataStrings` does. A rich field is one string here: a data block holds its
+ * markdown as written.
+ *
+ * @param {object} record
+ * @param {object} model - a lowered data schema (`toDataSchemaDeclaration`)
+ * @param {(value: string, path: string) => string|void} visit
+ * @param {string} [prefix] - prepended to each path (`[0]` for a list's first item)
+ */
+export function visitModelStrings(record, model, visit, prefix = '') {
+  const pathOf = (path) => (prefix ? (path.startsWith('[') ? `${prefix}${path}` : `${prefix}.${path}`) : path)
+  eachModelField(record, model, (holder, name, field, path) => {
+    if (!field.localized) return
+    const value = holder[name]
+    if (typeof value === 'string') {
+      if (!value.trim()) return
+      const next = visit(value, pathOf(path))
+      if (typeof next === 'string' && next !== value) holder[name] = next
+    } else if (Array.isArray(value)) {
+      value.forEach((item, i) => {
+        if (typeof item !== 'string' || !item.trim()) return
+        const next = visit(item, pathOf(`${path}[${i}]`))
+        if (typeof next === 'string' && next !== item) value[i] = next
+      })
+    }
+  })
+}

package/src/i18n/records.js

@@ -23,7 +23,8 @@ import { computeHash } from './hash.js'
 import { loadFreeformRecord } from './freeform.js'
 import { resolveQueriesConfig, resolveRecordSchemas, foundationSchemaJson } from '../site/queries-config.js'
 import { dataKeyTypes, keyOfDefaultRef } from '../uwx/data-key-types.js'
-import { toDataSchemaDeclaration, isProseMirrorField, isOpenMapSection } from '../uwx/data-schema.js'
+import { toDataSchemaDeclaration, isProseMirrorField } from '../uwx/data-schema.js'
+import { eachModelField, eachSectionField, isRecordSystemField, isPlainObject } from './model-fields.js'
 import { toDeliveredRecord, contentBodyField, misplacedFields, mergedFromStored, storedFromMerged } from '@uniweb/schemas/conform'
 import { resolveDocForLocale } from './merge.js'
 import { extractUnitsFromDoc } from './extract.js'
@@ -186,7 +187,7 @@ function isFieldTranslatable(fieldDef) {
  * @param {string} ref - the ref it was resolved from
  * @returns {Object|null} the lowered declaration, or null when there is none
  */
-function modelOf(schema, ref) {
+export function modelOf(schema, ref) {
   if (!schema) return null
   try {
     return toDataSchemaDeclaration(schema, { name: ref || '@/record', resolveName: (r) => r })
@@ -208,40 +209,6 @@ function referencedModels(model) {
   return out
 }
 
-/**
- * Each field of a model that a record holds a value for, in the shape the record is DELIVERED in
- * (`toDeliveredRecord`): the brief's fields at the top — every field, for a model of one single
- * section — and each other section under its name, a list of them for a `multiple` one, a nested
- * section the same way. Calls `visit(holder, name, field, path)` for each.
- */
-function eachModelField(record, model, visit) {
-  const sections = Object.entries(model?.sections || {})
-  const flat = sections.length === 1 && !sections[0][1]?.multiple
-  for (const [name, section] of sections) {
-    if (flat || section?.brief) eachSectionField(record, section?.fields, '', visit)
-    else eachSectionValue(record?.[name], section, name, visit)
-  }
-}
-
-function eachSectionValue(value, section, path, visit) {
-  if (!section?.multiple) return eachSectionField(value, section?.fields, path, visit)
-  if (Array.isArray(value)) value.forEach((item, i) => eachSectionField(item, section.fields, `${path}[${i}]`, visit))
-  // An open map as its file holds it: each entry is one of the rows a push sends (`isOpenMapSection`).
-  else if (isOpenMapSection(section) && isPlainObject(value)) {
-    for (const [key, item] of Object.entries(value)) eachSectionField(item, section.fields, `${path}.${key}`, visit)
-  }
-}
-
-function eachSectionField(holder, fields, path, visit) {
-  if (!isPlainObject(holder)) return
-  for (const [name, field] of Object.entries(fields || {})) {
-    if (holder[name] == null || isRecordSystemField(name, !path)) continue
-    const at = path ? `${path}.${name}` : name
-    if (field?.type === 'section') eachSectionValue(holder[name], field, at, visit)
-    else visit(holder, name, field || {}, at)
-  }
-}
-
 /** The fields of a model's brief — what a reference to one of its records is delivered as. */
 function briefFields(model) {
   const sections = Object.values(model?.sections || {})
@@ -360,25 +327,6 @@ function derivesExcerpt(record, whole, dataSchema, config) {
   return derivedExcerptOf(whole ?? record, dataSchema, config) === record.excerpt
 }
 
-/**
- * ⛔ A RECORD'S SYSTEM FIELDS ARE NEVER PROSE — never extracted, never translated, by
- * either path. A `$`-prefixed key at any depth is the system's (`$name`, the handle a
- * parametric page's URL names; `$uuid`; `$branch`, the folder a compiled list holds a
- * record under), and a top-level `slug` is how a record's reader hands the file's name
- * on. Until 2026-09-14 they became translation units, and a translation whose source
- * happened to equal one rewrote it, so a record's page stopped matching its URL.
- * ⛔ A top-level `path` was one too until 2026-09-27, when the placement it named moved to
- * `$branch` [Diego]: a field an author names `path` is theirs, and translated as its schema says.
- *
- * @param {string|number} key - a field name (an array index is never one)
- * @param {boolean} topLevel - whether the key sits at the record's own level
- * @returns {boolean}
- */
-function isRecordSystemField(key, topLevel) {
-  if (typeof key !== 'string') return false
-  return key.startsWith('$') || (topLevel && key === 'slug')
-}
-
 /**
  * A record's handle — `$name`, which the build sets from the record's file (`slug:` or
  * its name). ⭐ Not `slug` alone: a record of a schema whose brief declares a `slug`
@@ -1208,10 +1156,6 @@ function applyFreeform(record, freeform, dataSchema, schemaRef) {
   return out
 }
 
-function isPlainObject(value) {
-  return !!value && typeof value === 'object' && !Array.isArray(value)
-}
-
 /**
  * Apply translations to a collection item (sync, hash-based only) — by the model it is pushed as
  * when it has one (`translateByModel`), else a companion schema's fields, else the heuristic.

package/src/runtime-schema.js

@@ -434,3 +434,87 @@ export function extractAllLayoutRuntimeSchemas(layoutsMeta) {
 
   return schemas
 }
+
+/**
+ * ⭐ WHAT THE RUNTIME READS OF A FOUNDATION'S `main.js` — and nothing else of it. Ruled
+ * 2026-10-01 [Diego]: *"Only what runtime really reads for rendering should reach it."*
+ *
+ * Read off every runtime reader of the entry's `capabilities` (2026-10-01): core's `Uniweb` and
+ * `Website`, the runtime's wiring, navigation and scroll, `@uniweb/theming`, kit's xref, the
+ * fetch dispatcher, and press. Two kinds:
+ *
+ *   code  `handlers`, `defaultInsets`, `xref`, `transports`, `outputs` — functions and
+ *         components, so the entry REFERENCES each from the module and the bundler drops the rest
+ *         of `main.js`'s default export.
+ *   data  `defaultLayout`, `defaultSection`, `viewTransitions`, `scroll`; `vars`, each var's
+ *         `default`, `type` and `applyTo` — all `@uniweb/theming` reads; `data`, each key's schema
+ *         ref — all `declaredKeys` reads. Written as a literal, like a section type's lean schema.
+ *
+ * ⛔ Never: `name`, `description`, `extension`, a var's label or description, a data key's shape,
+ * or any key the framework does not read. ⛔ Until 2026-10-01 the entry spread the whole default
+ * export into `capabilities`, and a foundation's name and its vars' descriptions shipped in every
+ * published bundle.
+ *
+ * A data key whose value is not plain data (a function, say) is referenced like code, so nothing
+ * is lost to serialization.
+ *
+ * @param {Object} config - the foundation's `main.js`, as `loadFoundationConfig` reads it
+ * @returns {{ code: string[], data: Object }} the code keys to reference, and the data to inline
+ */
+export function extractFoundationRuntime(config = {}) {
+  const code = RUNTIME_CODE_CAPABILITIES.filter((key) => config?.[key] !== undefined)
+  const data = {}
+  for (const key of RUNTIME_DATA_CAPABILITIES) {
+    const value = config?.[key]
+    if (value === undefined) continue
+    if (isPlainData(value)) data[key] = value
+    else code.push(key)
+  }
+  const vars = leanVars(config?.vars)
+  if (vars) data.vars = vars
+  const keys = leanDataKeys(config?.data)
+  if (keys) data.data = keys
+  return { code, data }
+}
+
+/** The `main.js` capabilities the runtime calls or renders — referenced, never copied. */
+export const RUNTIME_CODE_CAPABILITIES = ['handlers', 'defaultInsets', 'xref', 'transports', 'outputs']
+
+/** The `main.js` values the runtime reads as data — written into the entry. */
+const RUNTIME_DATA_CAPABILITIES = ['defaultLayout', 'defaultSection', 'viewTransitions', 'scroll']
+
+/** What `@uniweb/theming` reads of a foundation var: its value, its kind, and a font role's selectors. */
+const RUNTIME_VAR_FIELDS = ['default', 'type', 'applyTo']
+
+function leanVars(vars) {
+  if (!vars || typeof vars !== 'object' || Array.isArray(vars)) return null
+  const out = {}
+  for (const [name, config] of Object.entries(vars)) {
+    if (config !== null && typeof config === 'object' && !Array.isArray(config)) {
+      const lean = {}
+      for (const field of RUNTIME_VAR_FIELDS) if (config[field] !== undefined) lean[field] = config[field]
+      out[name] = lean
+    } else {
+      out[name] = config
+    }
+  }
+  return Object.keys(out).length > 0 ? out : null
+}
+
+/** A foundation's `data:` as a section type's lean `data` is: each key → its schema ref, or null. */
+function leanDataKeys(data) {
+  const lowered = lowerData(data)
+  if (!lowered || typeof lowered !== 'object' || Array.isArray(lowered)) return null
+  const out = {}
+  for (const [key, value] of Object.entries(lowered)) out[key] = dataRef(value)
+  return Object.keys(out).length > 0 ? out : null
+}
+
+function isPlainData(value) {
+  if (value === null || ['string', 'number', 'boolean'].includes(typeof value)) return true
+  if (Array.isArray(value)) return value.every(isPlainData)
+  if (typeof value === 'object' && Object.getPrototypeOf(value) === Object.prototype) {
+    return Object.values(value).every(isPlainData)
+  }
+  return false
+}