@uniweb/build 0.75.0 → 0.76.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@uniweb/build",
-  "version": "0.75.0",
+  "version": "0.76.0",
   "description": "Build tooling for the Uniweb Component Web Platform",
   "type": "module",
   "exports": {
@@ -59,13 +59,13 @@
     "yaml": "^2.5.0",
     "@uniweb/content-reader": "^1.2.8",
     "@uniweb/content-writer": "^0.3.4",
-    "@uniweb/projections": "^0.7.13",
-    "@uniweb/schemas": "^0.10.2",
-    "@uniweb/theming": "^0.2.0",
-    "@uniweb/semantic-parser": "^1.5.1"
+    "@uniweb/projections": "^0.7.14",
+    "@uniweb/semantic-parser": "^1.5.1",
+    "@uniweb/schemas": "^0.11.0",
+    "@uniweb/theming": "^0.2.0"
   },
   "optionalDependencies": {
-    "@uniweb/runtime": "^0.28.10"
+    "@uniweb/runtime": "^0.29.0"
   },
   "peerDependencies": {
     "vite": "^5.0.0 || ^6.0.0 || ^7.0.0",
@@ -74,8 +74,8 @@
     "@tailwindcss/vite": "^4.0.0",
     "@vitejs/plugin-react": "^4.0.0 || ^5.0.0",
     "vite-plugin-svgr": "^4.0.0",
-    "@uniweb/core": "^0.36.0",
-    "@uniweb/runtime": "^0.28.10"
+    "@uniweb/runtime": "^0.29.0",
+    "@uniweb/core": "^0.37.0"
   },
   "peerDependenciesMeta": {
     "vite": {

package/src/dev/plugin.js

@@ -243,9 +243,9 @@ export function foundationDevPlugin(options = {}) {
           // Ignore generated files (build output triggers entry regeneration)
           if (!filename || filename.includes('_entry.generated')) return
 
-          // Rebuild for source file changes, and for any file the entry is generated
-          // from — a data schema under `schemas/` is `.yml` or `.json` as often as `.js`
-          // (`shouldRegenerateForFile`)
+          // Rebuild for source file changes, and for the other structural files
+          // (`shouldRegenerateForFile`) — a data schema under `schemas/`, `.yml` or `.json`
+          // as often as `.js`, moves the rebuilt schema.json
           if (
             filename.endsWith('.js') ||
             filename.endsWith('.jsx') ||

package/src/generate-entry.js

@@ -12,7 +12,7 @@
  * The `meta` export contains only properties needed at runtime:
  * - `background` - 'self' opt-out when component handles its own background
  * - `data` - the `content.data` keys the component declares, with their schema refs
- * - `schemas` - field defaults for those keys
+ * - `vars` - the CSS variables the component declares, with their defaults
  * - `defaults` - Param default values
  * - `context` - Static capabilities for cross-block coordination
  * - `initialState` - Initial values for mutable block state
@@ -32,7 +32,7 @@ import {
   LAYOUTS_PATH
 } from './schema.js'
 import { extractAllRuntimeSchemas, extractAllLayoutRuntimeSchemas, extractFoundationRuntime } from './runtime-schema.js'
-import { collectSchemaRefs, buildDataSchemaMap, SCHEMA_EXTENSIONS } from './resolve-data-schema.js'
+import { SCHEMA_EXTENSIONS } from './resolve-data-schema.js'
 
 /**
  * The files a foundation's data schemas are read from, relative to its source root:
@@ -196,12 +196,12 @@ function generateEntrySource(components, options = {}) {
     lines.push('const capabilities = null')
   }
 
-  // Per-component runtime metadata (defaults, context, initialState, background, data)
+  // Per-component runtime metadata (defaults, context, initialState, background, data, vars)
   lines.push('')
   const metaJson = JSON.stringify(Object.keys(meta).length > 0 ? meta : {}, null, 2)
   lines.push(`const meta = ${metaJson}`)
 
-  // Per-layout runtime metadata (areas, transitions, defaults)
+  // Per-layout runtime metadata (transitions, layers, scroll, defaults)
   lines.push('')
   const layoutMetaJson = JSON.stringify(Object.keys(layoutMeta).length > 0 ? layoutMeta : {}, null, 2)
   lines.push(`const layoutMeta = ${layoutMetaJson}`)
@@ -311,23 +311,12 @@ export async function generateEntryPoint(srcDir, outputPath = null, options = {}
   const foundationConfig = await loadFoundationConfig(srcDir)
   const foundationRuntime = foundationExports ? extractFoundationRuntime(foundationConfig) : { code: [], data: {} }
 
-  // Resolve the data schemas referenced by section bindings, then extract
-  // per-component runtime metadata (which lean-extracts field defaults from
-  // the resolved schemas into meta.schemas[<key>]).
-  // ⛔ Components only, unlike `schema.js`, which also passes the foundation's
-  // `main.js` `data:`. Not an oversight: this map feeds `extractAllRuntimeSchemas`,
-  // and `extractRuntimeSchema` reads `fullMeta.data` — per component. A
-  // foundation-tier key reaches every section (`declaredKeys`) but has nowhere to
-  // put its lean schema in a PER-COMPONENT runtime meta, so resolving its ref here
-  // would produce an entry nothing reads.
-  //
-  // ⚠️ The consequence is real and still open: a foundation-tier `data:` entry
-  // naming a schema gets no field defaults from `applySchemas` at runtime. Latent
-  // today — every foundation-tier declaration in the templates is ref-less — and
-  // fixing it means deciding where a foundation-wide schema lives in the runtime
-  // meta, which is a design question, not a missing argument.
-  const dataSchemaMap = await buildDataSchemaMap(collectSchemaRefs(components), { srcDir })
-  const meta = extractAllRuntimeSchemas(components, dataSchemaMap)
+  // Per-component runtime metadata. ⭐ No data schema is resolved for it: the runtime reads a
+  // declared key's ref and nothing of its shape (2026-10-05), so the entry no longer depends on
+  // a schema file — `schema.js` resolves them, for schema.json, and a missing one stops the
+  // build there. ⛔ Until then the entry carried each key's field defaults, resolved here, and a
+  // foundation-tier `data:` key got none, having no per-component place to put them.
+  const meta = extractAllRuntimeSchemas(components)
 
   // Extract per-layout runtime metadata from meta.js files
   const layoutMeta = extractAllLayoutRuntimeSchemas(layouts)
@@ -519,13 +508,11 @@ export function shouldRegenerateForFile(file, srcDir) {
     }
   }
 
-  // ⭐ The foundation's data schemas — `schemas/<name>.<ext>` and `schemas.config.js`.
-  // The entry's `meta` carries each declared `data:` key with its schema's field
-  // defaults, and a `@/name` ref whose file is missing stops entry generation. A
-  // section receives only the keys its entry declares (2026-09-14), so an entry that
-  // falls behind withholds data: a `data:` key declaring `@/member` before
-  // `schemas/member.yml` exists fails the regeneration, and until 2026-09-14 writing
-  // the file triggered no other — the dev server kept the entry without the key.
+  // The foundation's data schemas — `schemas/<name>.<ext>` and `schemas.config.js`.
+  // ⚠️ The entry holds nothing read from one since 2026-10-05 (no field defaults), so
+  // regenerating it changes nothing. The match stays for the dev rebuild of a
+  // runtime-linked foundation (`dev/plugin.js`), which also writes the editor's
+  // schema.json — whose `dataSchemas` a schema change does move.
   if (rel.startsWith(`${SCHEMAS_PATH}/`)) {
     const inner = rel.slice(SCHEMAS_PATH.length + 1)
     if (!inner.includes('/') && SCHEMA_EXTENSIONS.some(ext => inner.endsWith(ext))) {

package/src/i18n/data-models.js

@@ -0,0 +1,77 @@
+/**
+ * ⭐ WHAT A SECTION TYPE SAYS ITS DATA BLOCKS ARE. A tagged data block (```yaml:logos) feeds the
+ * data key of its tag, and the section's type declares that key in its `meta.js` `data:` — a data
+ * schema ref (`'@/member'`), an inline field map (`{ name: 'string', style: { type: 'string', enum:
+ * [...] } }`), or nothing said (`{}`). The foundation's `main.js` `data:` reaches every section, and
+ * a key both declare is the section type's (`@uniweb/core/data-keys::declaredKeys`).
+ *
+ * This is the model of each declared shape, lowered by the push's own rule (`records.js::modelOf`),
+ * so the fields a block translates are the ones its model marks `localized`
+ * (`data-strings.js::visitDataBlockStrings`). Every form of a declaration is read by the one
+ * normalizer (`@uniweb/schemas/foundation::normalizeData`); a ref resolves as a query's records
+ * resolve theirs (`resolveRecordSchemas`). A key with no shape, or a ref that does not resolve, has
+ * no model, and its blocks keep the heuristic.
+ */
+import { normalizeData } from '@uniweb/schemas/foundation'
+import { foundationSections, resolveRecordSchemas } from '../site/queries-config.js'
+import { modelOf } from './records.js'
+
+/** The lookup when there is no foundation to ask: every block keeps the heuristic. */
+export const NO_DATA_MODELS = () => null
+
+/**
+ * The lookup for a site: `(sectionType, tag) => model | null`.
+ *
+ * @param {string} siteRoot
+ * @param {object} [siteYml] - an already-read site.yml
+ * @returns {Promise<(type: string, tag: string) => object|null>}
+ */
+export async function dataBlockModels(siteRoot, siteYml = null) {
+  let sections
+  try {
+    sections = await foundationSections(siteRoot, siteYml)
+  } catch {
+    return NO_DATA_MODELS
+  }
+  if (!sections || typeof sections !== 'object') return NO_DATA_MODELS
+
+  // Each declared key, by who declares it: a section type by name, the foundation as ''.
+  const declared = new Map()
+  const declare = (owner, data) => {
+    const normalized = normalizeData(data, { strict: false })
+    for (const [key, decl] of Object.entries(normalized || {})) declared.set(at(owner, key), decl)
+  }
+  for (const [name, entry] of Object.entries(sections)) {
+    if (!entry || typeof entry !== 'object' || name === 'dataSchemas' || name === '_layouts') continue
+    if (name === '_self') declare('', entry.data)
+    else if (!name.startsWith('_')) declare(name, entry.data)
+  }
+  if (!declared.size) return NO_DATA_MODELS
+
+  const refs = [...declared.values()].filter((d) => d.kind === 'schema').map((d) => d.schema)
+  let resolved = {}
+  if (refs.length) {
+    try {
+      resolved = (await resolveRecordSchemas(siteRoot, refs, { siteYml })).schemas || {}
+    } catch {
+      resolved = {}
+    }
+  }
+
+  const models = new Map()
+  for (const [where, decl] of declared) {
+    if (decl.kind === 'schema') models.set(where, modelOf(resolved[decl.schema] || null, decl.schema))
+    else if (decl.kind === 'fields') {
+      const { kind: _kind, problems: _problems, ...schema } = decl
+      models.set(where, modelOf(schema, '@/inline'))
+    } else models.set(where, null)
+  }
+
+  return (type, tag) => {
+    if (!tag) return null
+    if (type && models.has(at(type, tag))) return models.get(at(type, tag)) || null
+    return models.get(at('', tag)) || null
+  }
+}
+
+const at = (owner, key) => `${owner}\u0000${key}`

package/src/i18n/data-strings.js

@@ -19,6 +19,8 @@
  * missed field shows up as untranslated content nobody notices.
  */
 
+import { visitModelStrings } from './model-fields.js'
+
 /** Types that are never translatable regardless of schema. */
 export const NON_TRANSLATABLE_TYPES = new Set([
   'number', 'boolean', 'date', 'datetime', 'url', 'email', 'image'
@@ -112,3 +114,28 @@ export function visitDataStrings(data, visit, path = '', depth = 0) {
     // numbers and booleans are never prose
   }
 }
+
+/**
+ * ⭐ A TAGGED DATA BLOCK'S STRINGS, BY ITS DECLARED SHAPE WHEN IT HAS ONE. A section type that
+ * declares the shape of the key a block is tagged with — `data: { logos: { name: 'string', style:
+ * { type: 'string', enum: [...] } } }`, or a data schema ref — says which of its fields are text,
+ * and that is what is walked: the fields its model marks `localized`, the push's own rule
+ * (`model-fields.js`). An enum, a URL, a `translatable: false` field is never offered, whatever its
+ * name. A block whose key declares no shape (`{}`, or no declaration) keeps the heuristic above.
+ *
+ * ⛔ Until 2026-10-02 every block was walked by the heuristic, so a field the heuristic does not know
+ * — a `style: display-black` naming one of a component's looks — was offered for translation, and
+ * a translated one quietly fell back to the component's default look.
+ *
+ * One rule for the four places that walk a block — extraction, the build's merge, the push and the
+ * pull — so a string extracted is a string translated, and a translation pushed is one read back.
+ *
+ * @param {object|Array} data - the block's value: a list of items, or one
+ * @param {(value: string, path: string) => string|void} visit
+ * @param {object|null} [model] - the block's lowered model (`data-models.js`), or null
+ */
+export function visitDataBlockStrings(data, visit, model = null) {
+  if (!model) return visitDataStrings(data, visit)
+  if (Array.isArray(data)) data.forEach((item, i) => visitModelStrings(item, model, visit, `[${i}]`))
+  else visitModelStrings(data, model, visit)
+}

package/src/i18n/extract.js

@@ -7,7 +7,7 @@
 
 import { resolveDefaultLocale } from '@uniweb/core'
 import { computeHash, stripInlineTags } from './hash.js'
-import { visitDataStrings } from './data-strings.js'
+import { visitDataBlockStrings } 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
@@ -25,9 +25,13 @@ try {
 /**
  * Extract all translatable units from site content
  * @param {Object} siteContent - Parsed site-content.json
+ * @param {Object} [options]
+ * @param {(type: string, tag: string) => Object|null} [options.dataModel] - what each section type
+ *   declares its data blocks are (`data-models.js::dataBlockModels`); without it, every block is
+ *   walked by the heuristic
  * @returns {Object} Manifest with translation units
  */
-export function extractTranslatableContent(siteContent) {
+export function extractTranslatableContent(siteContent, { dataModel = null } = {}) {
   const units = {}
 
   // The site's own Open Graph title and description (`site.yml` `seo:`), in the site's context.
@@ -41,7 +45,7 @@ export function extractTranslatableContent(siteContent) {
 
     // Extract section content
     for (const section of page.sections || []) {
-      extractFromSection(section, pageRoute, units)
+      extractFromSection(section, pageRoute, units, dataModel)
     }
   }
 
@@ -51,7 +55,7 @@ export function extractTranslatableContent(siteContent) {
     const pageRoute = notFoundPage.route || '/404'
     extractFromPageMeta(notFoundPage, pageRoute, units)
     for (const section of notFoundPage.sections || []) {
-      extractFromSection(section, pageRoute, units)
+      extractFromSection(section, pageRoute, units, dataModel)
     }
   }
 
@@ -64,7 +68,7 @@ export function extractTranslatableContent(siteContent) {
         if (layoutPage?.sections) {
           const pageRoute = layoutPage.route || `/layout/${layoutName === 'default' ? '' : layoutName + '/'}${areaKey}`
           for (const section of layoutPage.sections) {
-            extractFromSection(section, pageRoute, units)
+            extractFromSection(section, pageRoute, units, dataModel)
           }
         }
       }
@@ -169,7 +173,7 @@ export function translationContext(section, pageRoute) {
  * @param {string} pageRoute - Parent page route
  * @param {Object} units - Units accumulator
  */
-function extractFromSection(section, pageRoute, units) {
+function extractFromSection(section, pageRoute, units, dataModel = null) {
   const context = translationContext(section, pageRoute)
 
   // Extract from parsed semantic content if available
@@ -179,12 +183,12 @@ function extractFromSection(section, pageRoute, units) {
 
   if (section.content?.type === 'doc') {
     extractFromProseMirrorDoc(section.content, context, units)
-    extractFromDataBlocks(section.content, context, units)
+    extractFromDataBlocks(section.content, context, units, (tag) => dataModel?.(section.type, tag) ?? null)
   }
 
   // Recursively process subsections
   for (const subsection of section.subsections || []) {
-    extractFromSection(subsection, pageRoute, units)
+    extractFromSection(subsection, pageRoute, units, dataModel)
   }
 }
 
@@ -214,14 +218,14 @@ function extractFromSection(section, pageRoute, units) {
  * as the same per-string entries this lane writes — the block-element keying
  * contract is untouched.
  */
-function extractFromDataBlocks(doc, context, units) {
+function extractFromDataBlocks(doc, context, units, modelFor = () => null) {
   for (const node of dataBlockNodes(doc)) {
     const { tag, data } = node.attrs || {}
     if (!tag || !data || typeof data !== 'object') continue
 
-    visitDataStrings(data, (value, fieldPath) => {
+    visitDataBlockStrings(data, (value, fieldPath) => {
       addUnit(units, value, `data.${tag}.${fieldPath}`, context)
-    })
+    }, modelFor(tag))
   }
 }
 

package/src/i18n/index.js

@@ -14,6 +14,7 @@ import { join, dirname } from 'node:path'
 import { computeHash, normalizeText } from './hash.js'
 import { availableLocales, resolveLocaleList } from './locales.js'
 import { extractTranslatableContent } from './extract.js'
+import { dataBlockModels } from './data-models.js'
 import { syncManifests, formatSyncReport } from './sync.js'
 import { mergeTranslations, generateAllLocales } from './merge.js'
 import { auditLocale, cleanLocale, formatAuditReport } from './audit.js'
@@ -160,8 +161,8 @@ export async function extractManifest(siteRoot, siteContent, options = {}) {
     dryRun = false
   } = options
 
-  // Extract translatable content
-  const manifest = extractTranslatableContent(siteContent)
+  // Extract translatable content — a data block by what its section type declares it is
+  const manifest = extractTranslatableContent(siteContent, { dataModel: await dataBlockModels(siteRoot) })
 
   // Ensure locales directory exists
   const localesPath = join(siteRoot, localesDir)
@@ -372,6 +373,8 @@ export async function buildLocalizedContent(siteRoot, options = {}) {
   const defaultLocale = resolveDefaultLocale(siteContent.config)
 
   const outputs = {}
+  // What each section type declares its data blocks are, so a block translates what extraction offered.
+  const dataModel = await dataBlockModels(siteRoot)
 
   // ⭐ 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
@@ -420,7 +423,8 @@ export async function buildLocalizedContent(siteRoot, options = {}) {
         fallbackToSource,
         locale,
         localesDir: localesPath,
-        freeformEnabled: true
+        freeformEnabled: true,
+        dataModel
       })
 
       // Check for stale/orphaned free-form translations and warn
@@ -428,7 +432,8 @@ export async function buildLocalizedContent(siteRoot, options = {}) {
     } else {
       // Use sync merge (original behavior)
       translated = mergeTranslations(siteContent, translations, {
-        fallbackToSource
+        fallbackToSource,
+        dataModel
       })
     }
 

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)
     }
   }
 
@@ -496,9 +504,15 @@ function withMarks(node, marks) {
  * 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 || []) {
@@ -506,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)
@@ -529,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
 }