@uniweb/build 0.14.17 → 0.14.19

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@uniweb/build",
-  "version": "0.14.17",
+  "version": "0.14.19",
   "description": "Build tooling for the Uniweb Component Web Platform",
   "type": "module",
   "exports": {
@@ -59,13 +59,13 @@
     "js-yaml": "^4.1.0",
     "sharp": "^0.33.2",
     "yaml": "^2.5.0",
-    "@uniweb/content-writer": "0.2.5",
+    "@uniweb/content-writer": "0.2.6",
     "@uniweb/theming": "0.1.4"
   },
   "optionalDependencies": {
+    "@uniweb/runtime": "0.8.20",
     "@uniweb/content-reader": "1.1.12",
-    "@uniweb/schemas": "0.2.3",
-    "@uniweb/runtime": "0.8.20"
+    "@uniweb/schemas": "0.2.3"
   },
   "peerDependencies": {
     "vite": "^5.0.0 || ^6.0.0 || ^7.0.0",

package/src/hosts/s3-cloudfront.js

@@ -74,8 +74,8 @@ const REDIRECTS_FILE    = '_redirects'
  * left it to be loaded by URL at runtime (linked).
  *
  * The user's site.yml `foundation:` declaration is the only thing that
- * controls this — `uniweb build` never auto-publishes (that's exclusive
- * to `uniweb deploy` against uniweb-edge), so the rule is:
+ * controls this — `uniweb build` never registers or ships foundation code,
+ * so the rule is purely the shape of the `foundation:` ref:
  *   - registry ref ('@ns/name@ver'), https:// URL, or { url } object → linked
  *   - everything else (file: ref, workspace path) → standalone
  */

package/src/i18n/extract.js

@@ -163,11 +163,10 @@ function extractFromProseMirrorDoc(doc, context, units) {
 
   let headingIndex = { h1: 0, h2: 0, h3: 0, h4: 0 }
   let paragraphIndex = 0
-  let linkIndex = 0
 
   for (const node of doc.content) {
     if (node.type === 'heading') {
-      const text = extractTextFromNode(node)
+      const text = elementText(node)
       if (!text) continue
 
       const level = node.attrs?.level || 1
@@ -176,14 +175,13 @@ function extractFromProseMirrorDoc(doc, context, units) {
 
       addUnit(units, text, field, context)
     } else if (node.type === 'paragraph') {
-      const result = extractFromParagraph(node, context, units, linkIndex)
-      linkIndex = result.linkIndex
-
-      // Add paragraph text if it's substantial (not just links/buttons)
-      const plainText = extractPlainTextFromParagraph(node)
-      if (plainText && plainText.length > 0) {
+      // Whole-element keying: ONE unit per paragraph, with link text kept INLINE
+      // (not split into a separate link.label unit). The conformance gate is
+      // tests/i18n/structural-keying-vectors.json (vectors A–H).
+      const text = elementText(node)
+      if (text) {
         const field = paragraphIndex === 0 ? 'paragraph' : `paragraph.${paragraphIndex}`
-        addUnit(units, plainText, field, context)
+        addUnit(units, text, field, context)
         paragraphIndex++
       }
     } else if (node.type === 'bulletList' || node.type === 'orderedList') {
@@ -205,47 +203,8 @@ function getHeadingField(level, index) {
 }
 
 /**
- * Extract from paragraph node, handling links specially
- */
-function extractFromParagraph(node, context, units, linkIndex) {
-  if (!node.content) return { linkIndex }
-
-  for (const child of node.content) {
-    if (child.type === 'text' && child.marks) {
-      const linkMark = child.marks.find(m => m.type === 'link')
-      if (linkMark && child.text) {
-        const field = linkIndex === 0 ? 'link.label' : `link.${linkIndex}.label`
-        addUnit(units, child.text, field, context)
-        linkIndex++
-      }
-    }
-  }
-
-  return { linkIndex }
-}
-
-/**
- * Extract plain text from paragraph, excluding link text
- */
-function extractPlainTextFromParagraph(node) {
-  if (!node.content) return ''
-
-  const parts = []
-  for (const child of node.content) {
-    if (child.type === 'text') {
-      // Skip if it's a link
-      const isLink = child.marks?.some(m => m.type === 'link')
-      if (!isLink && child.text && child.text.trim()) {
-        parts.push(child.text)
-      }
-    }
-  }
-
-  return parts.join('').trim()
-}
-
-/**
- * Extract from list items
+ * Extract from list items — one whole-element unit per list item (link text
+ * stays inline, same rule as paragraphs; vectors G and H).
  */
 function extractFromList(listNode, context, units) {
   if (!listNode.content) return
@@ -254,7 +213,7 @@ function extractFromList(listNode, context, units) {
     if (listItem.type === 'listItem' && listItem.content) {
       for (const child of listItem.content) {
         if (child.type === 'paragraph') {
-          const text = extractTextFromNode(child)
+          const text = elementText(child)
           if (text) {
             addUnit(units, text, `list.${index}`, context)
           }
@@ -265,36 +224,56 @@ function extractFromList(listNode, context, units) {
 }
 
 /**
- * Extract all text content from a node.
- * When a node has multiple text children with some carrying span marks
- * (e.g., `[text]{accent}`), wraps the marked spans in XLIFF-style
- * `<N>...</N>` tags so translators can reposition them.
+ * A block element's cleaned source text — the WHOLE-ELEMENT translation key.
+ * ALL inline marks (bold, italic, link, span, …) flatten into the text: link
+ * text stays INLINE (not split out), spans contribute their plain text (no
+ * `<N>` tags in the key). Inline atom nodes (image/icon/emoji/math/hardBreak)
+ * are skipped. Leading/trailing whitespace is trimmed; internal whitespace is
+ * preserved (the hash collapses it for matching — see hash.js normalizeText).
  */
-function extractTextFromNode(node) {
-  if (!node.content) return ''
-  const textChildren = node.content.filter(n => n.type === 'text')
-
-  // Check for mixed inline marks (span marks from `[text]{class}` syntax)
-  const hasInlineMarks = textChildren.length > 1 &&
-    textChildren.some(n => n.marks?.some(m => m.type === 'span'))
+export function elementText(node) {
+  return collectInlineText(node).trim()
+}
 
-  if (!hasInlineMarks) {
-    return textChildren.map(n => n.text || '').join('').trim()
+function collectInlineText(node) {
+  if (!node || !node.content) return ''
+  let out = ''
+  for (const child of node.content) {
+    if (child.type === 'text') {
+      out += child.text || ''
+    } else if (child.content) {
+      // recurse through inline wrappers into their text
+      out += collectInlineText(child)
+    }
+    // else: inline atom (image/icon/emoji/math/hardBreak) → contributes no text
   }
+  return out
+}
 
-  // Wrap span-marked text in numbered tags
-  let markCounter = 0
-  const parts = []
-  for (const child of textChildren) {
-    const text = child.text || ''
-    if (child.marks?.some(m => m.type === 'span')) {
-      markCounter++
-      parts.push(`<${markCounter}>${text}</${markCounter}>`)
-    } else {
-      parts.push(text)
+/**
+ * The translatable block elements of a content doc, in document order, with the
+ * SAME coverage as extraction above (headings, paragraphs, and each list item's
+ * paragraphs). Shared by the merge resolver (push) and the pull-side
+ * structural-map derivation so all paths walk identically and keys never drift.
+ * Returns the element nodes themselves — callers read `.type`/`.content` and key
+ * them via elementText.
+ */
+export function blockElements(doc) {
+  const out = []
+  for (const node of doc?.content || []) {
+    if (node.type === 'heading' || node.type === 'paragraph') {
+      out.push(node)
+    } else if (node.type === 'bulletList' || node.type === 'orderedList') {
+      for (const listItem of node.content || []) {
+        if (listItem.type === 'listItem' && listItem.content) {
+          for (const child of listItem.content) {
+            if (child.type === 'paragraph') out.push(child)
+          }
+        }
+      }
     }
   }
-  return parts.join('').trim()
+  return out
 }
 
 /**

package/src/i18n/merge.js

@@ -12,8 +12,24 @@
  * when no free-form translation exists.
  */
 
-import { computeHash, stripInlineTags, parseInlineTags } from './hash.js'
+import { computeHash } from './hash.js'
 import { loadFreeformTranslation } from './freeform.js'
+import { elementText, blockElements } from './extract.js'
+
+// Inline-markdown → ProseMirror inline fragment, for resolving a whole-element
+// translation VALUE (which carries marks/links/icons as inline markdown). Same
+// lazy-import-with-fallback pattern as freeform.js / collection-processor.js, so
+// the synchronous merge path has the converter ready at call time.
+let markdownToProseMirror
+try {
+  const contentReader = await import('@uniweb/content-reader')
+  markdownToProseMirror = contentReader.markdownToProseMirror
+} catch {
+  markdownToProseMirror = (markdown) => ({
+    type: 'doc',
+    content: [{ type: 'paragraph', content: [{ type: 'text', text: markdown.trim() }] }]
+  })
+}
 
 /**
  * Merge translations into site content for a specific locale
@@ -253,100 +269,67 @@ async function translateSectionAsync(section, page, translations, options) {
 }
 
 /**
- * Translate text nodes in a ProseMirror document
+ * Resolve a ProseMirror content doc for a target locale: replace each block
+ * element's inline content with its translation, looked up by the WHOLE-ELEMENT
+ * key (shared with extract.js via elementText, so the two never drift). A
+ * missing translation leaves the source element untouched (graceful per-element
+ * fallback). The translation VALUE is inline markdown — it carries marks, inline
+ * links (with their own, possibly re-targeted, href) and inline atoms — so this
+ * is lossless for emphasis/links, unlike the former plain-string substitution.
  */
 function translateProseMirrorDoc(doc, context, translations, fallbackToSource) {
-  if (!doc.content) return
+  let changed = false
+  for (const el of blockElements(doc)) {
+    if (applyElementTranslation(el, context, translations, fallbackToSource)) changed = true
+  }
+  return changed
+}
 
-  for (const node of doc.content) {
-    translateNode(node, context, translations, fallbackToSource)
+// 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.
+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)
+  if (fragment && fragment.length) {
+    node.content = fragment
+    return true
   }
+  return false
 }
 
 /**
- * Recursively translate a node and its children.
- * For nodes with mixed marked/unmarked text children (inline span marks),
- * translates the node as a whole unit using XLIFF-style inline tags,
- * then rebuilds children with original marks re-applied.
+ * Resolve ONE ProseMirror content doc for a single target locale: a deep clone of
+ * the source doc with each whole-element translated (inline content replaced from
+ * the table's inline-markdown value). `table` is `{ hash: value }` for that locale.
+ * Returns the resolved doc, or null when the table translated nothing in this doc
+ * (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).
  */
-function translateNode(node, context, translations, fallbackToSource) {
-  if (!node.content) return
-
-  // Check for inline span marks across multiple text children
-  const textChildren = node.content.filter(n => n.type === 'text')
-  const hasInlineMarks = textChildren.length > 1 &&
-    textChildren.some(n => n.marks?.some(m => m.type === 'span'))
-
-  if (hasInlineMarks) {
-    // Build tagged source string (mirrors extraction)
-    let markCounter = 0
-    const markMap = [] // tag index → original marks array
-    const parts = []
-    for (const child of textChildren) {
-      const text = child.text || ''
-      if (child.marks?.some(m => m.type === 'span')) {
-        markCounter++
-        markMap.push(child.marks)
-        parts.push(`<${markCounter}>${text}</${markCounter}>`)
-      } else {
-        parts.push(text)
-      }
-    }
-    const plainSource = stripInlineTags(parts.join('').trim())
-
-    const translated = lookupTranslation(plainSource, context, translations, fallbackToSource)
-    if (translated !== plainSource) {
-      // Parse tagged translation and rebuild text children
-      const { segments } = parseInlineTags(translated)
-      const newTextChildren = segments.map(seg => {
-        if (seg.markIndex !== undefined && markMap[seg.markIndex]) {
-          return { type: 'text', text: seg.text, marks: [...markMap[seg.markIndex]] }
-        }
-        return { type: 'text', text: seg.text }
-      })
-
-      // Replace text children in content, preserve non-text children in place
-      const result = []
-      let textInserted = false
-      for (const child of node.content) {
-        if (child.type === 'text') {
-          if (!textInserted) {
-            result.push(...newTextChildren)
-            textInserted = true
-          }
-          // Skip remaining old text children
-        } else {
-          result.push(child)
-        }
-      }
-      node.content = result
-    }
-
-    // Recurse into non-text children
-    for (const child of node.content) {
-      if (child.type !== 'text') {
-        translateNode(child, context, translations, fallbackToSource)
-      }
-    }
-    return
-  }
+export function resolveDocForLocale(sourceDoc, table, context = { page: '', section: '' }) {
+  if (!sourceDoc || sourceDoc.type !== 'doc' || !table) return null
+  const doc = JSON.parse(JSON.stringify(sourceDoc))
+  const changed = translateProseMirrorDoc(doc, context, table, true)
+  return changed ? doc : null
+}
 
-  // Default: translate each child individually
-  for (const child of node.content) {
-    if (child.type === 'text' && child.text) {
-      const translated = lookupTranslation(
-        child.text,
-        context,
-        translations,
-        fallbackToSource
-      )
-      if (translated !== child.text) {
-        child.text = translated
-      }
-    } else {
-      translateNode(child, context, translations, fallbackToSource)
-    }
+// Parse an inline-markdown translation value into a ProseMirror inline fragment.
+// A value is expected to be one element's inline content (one paragraph once
+// parsed); take that paragraph's inline children. If the converter yields
+// several blocks, flatten their inline content rather than drop any.
+function inlineMarkdownToFragment(value) {
+  if (typeof value !== 'string' || value.trim() === '') return null
+  const doc = markdownToProseMirror(value)
+  const inline = []
+  for (const block of doc?.content || []) {
+    if (Array.isArray(block.content)) inline.push(...block.content)
   }
+  return inline.length ? inline : [{ type: 'text', text: value.trim() }]
 }
 
 /**

package/src/resolve-data-schema.js

@@ -409,6 +409,21 @@ function normalizeSection(section, ref, path, briefState) {
     if (section.nestable) out.nestable = true
   }
 
+  // `append_only` — a multi whose records are insert-only: the backend accepts
+  // appends but refuses edits or deletes of existing items, so the section is
+  // tamper-evident (activity logs, submissions, audit trails). Carried into the IR
+  // verbatim for the submission lowering to emit as the model's `append_only`.
+  // Like `nestable`, only a `multi` section can be append-only.
+  if (section.append_only !== undefined) {
+    if (typeof section.append_only !== 'boolean') {
+      throw new Error(`Data schema '${ref}': section '${path}' 'append_only' must be a boolean.`)
+    }
+    if (section.append_only && kind !== 'multi') {
+      throw new Error(`Data schema '${ref}': section '${path}' is 'append_only: true' but kind '${kind}' — only a 'multi' section can be append-only.`)
+    }
+    if (section.append_only) out.append_only = true
+  }
+
   return out
 }
 

package/src/site/config.js

@@ -65,17 +65,14 @@ function normalizeBasePath(raw) {
  *   - `'local'` — workspace-local source (sibling directory, file: dep, or
  *     `../../foundations/<name>/`). The build inlines or runtime-links it
  *     depending on the operating mode.
- *   - `'url'`  — loaded by URL at runtime. Three URL shapes:
+ *   - `'url'`  — loaded by URL at runtime. Two URL shapes:
  *       - `@org/name@ver`   → catalog ref (resolves against the registry CDN)
- *       - `~siteId/name@ver` → site-bound ref (resolves to per-site storage
- *                              at `sites/{siteId}/_src/...` on uniweb-edge,
- *                              never enters the catalog namespace)
  *       - `https://...`    → arbitrary URL
  *
- * Versionless registry refs (`@org/name`, `~siteId/name`) are rejected with
- * a specific error — they were a silent fall-through before. Versionless
- * names that don't match any local resolution path are also rejected, with
- * guidance toward the right shape.
+ * Versionless registry refs (`@org/name`) are rejected with a specific error —
+ * they were a silent fall-through before. Versionless names that don't match
+ * any local resolution path are also rejected, with guidance toward the right
+ * shape.
  *
  * @param {string|Object} foundation - Foundation config from site.yml
  * @param {string} siteRoot - Path to site directory
@@ -111,43 +108,26 @@ export function detectFoundationType(foundation, siteRoot) {
     }
   }
 
-  // Two URL-resolved registry shapes:
-  //   `@org/name@version`     → catalog ref. Resolves via the registry CDN.
-  //   `~siteId/name@version`  → site-bound ref. Resolves to per-site storage
-  //                             on uniweb-edge (sites/{siteId}/_src/...);
-  //                             never reaches the catalog R2 namespace.
-  // Both are link-mode by definition — the foundation lives on the hosting
-  // edge and is loaded at runtime. Surfacing this as `type: 'url'` makes
-  // Vite skip the local-foundation bundling path and use the noop virtual
-  // module. Base URL defaults to the production worker but is overridable
-  // via UNIWEB_REGISTRY_URL for self-hosted / staging.
+  // Catalog registry ref:
+  //   `@org/name@version`  → resolves via the registry CDN.
+  // Link-mode by definition — the foundation lives on the hosting edge and is
+  // loaded at runtime. Surfacing this as `type: 'url'` makes Vite skip the
+  // local-foundation bundling path and use the noop virtual module. Base URL
+  // defaults to the production worker but is overridable via UNIWEB_REGISTRY_URL
+  // for self-hosted / staging.
   const orgScopedMatch = /^@([a-z0-9_-]+)\/([a-z0-9_-]+)@(.+)$/.exec(name)
-  const siteBoundMatch = /^~([A-Za-z0-9_-]+)\/([a-z0-9_-]+)@(.+)$/.exec(name)
-  if (orgScopedMatch || siteBoundMatch) {
+  if (orgScopedMatch) {
     const base = process.env.UNIWEB_REGISTRY_URL || 'https://site-router.uniweb-edge.workers.dev'
-    if (orgScopedMatch) {
-      const [, ns, fn, ver] = orgScopedMatch
-      // Legacy plain-slash URL form (preserved — worker still accepts it
-      // for back-compat with sites built against earlier CLI releases).
-      return {
-        type: 'url',
-        url: `${base}/foundations/${ns}/${fn}/${ver}/foundation.js`,
-        cssUrl: `${base}/foundations/${ns}/${fn}/${ver}/assets/foundation.css`
-      }
-    }
-    // Site-bound URL form — sigil + canonical `<name>@<version>` shape.
-    // The worker dispatches on the `~` sigil to per-site storage rather
-    // than the catalog namespace.
-    const [, siteId, fn, ver] = siteBoundMatch
+    const [, ns, fn, ver] = orgScopedMatch
     return {
       type: 'url',
-      url: `${base}/foundations/~${siteId}/${fn}@${ver}/foundation.js`,
-      cssUrl: `${base}/foundations/~${siteId}/${fn}@${ver}/assets/foundation.css`
+      url: `${base}/foundations/${ns}/${fn}/${ver}/foundation.js`,
+      cssUrl: `${base}/foundations/${ns}/${fn}/${ver}/assets/foundation.css`
     }
   }
 
-  // Versionless scoped names (`@org/name`, `~siteId/name`) are valid as
-  // *handles* — they resolve through the local checks below (file: dep,
+  // Versionless scoped names (`@org/name`) are valid as *handles* — they
+  // resolve through the local checks below (file: dep,
   // workspace sibling) when the developer is iterating locally on a
   // foundation that will eventually be published as `@org/name@ver`.
   // Tianyu's uniweb.io site uses this shape:
@@ -196,7 +176,7 @@ export function detectFoundationType(foundation, siteRoot) {
   // Versionless scoped name that didn't resolve locally — likely a typo
   // or a missing file: dep. Give a specific hint distinguishing the two
   // common causes (forgot @version vs. forgot to wire the file: dep).
-  if (/^@[a-z0-9_-]+\//.test(name) || name.startsWith('~')) {
+  if (/^@[a-z0-9_-]+\//.test(name)) {
     throw new Error(
       `site.yml foundation: '${name}' did not resolve to a local source and no version was specified.\n` +
       `If this is a workspace-local foundation, add it to the site's package.json:\n` +
@@ -216,7 +196,7 @@ export function detectFoundationType(foundation, siteRoot) {
     `  - a workspace-local sibling (a directory next to the site, named '${name}')\n` +
     `  - a 'file:' dep in the site's package.json\n` +
     `  - a directory in '../../foundations/${name}'\n` +
-    `  - a versioned registry ref: '@org/${name}@<version>' or '~<siteId>/${name}@<version>'\n` +
+    `  - a versioned registry ref: '@org/${name}@<version>'\n` +
     `  - a full URL: 'https://...'\n` +
     `Foundations are runtime federated modules, not npm packages — there is no fall-through to node_modules.`
   )

package/src/uwx/data-schema.js

@@ -135,14 +135,15 @@ function lowerSectionsForm(sectionsMap, resolve, optResolve) {
 // Lower one section to its declaration body (the caller keys it by name; a nested
 // section gets a `type: section` marker prepended in lowerField). `kind: multi` →
 // `multiple: true`; `binder` is derived (no marker — it falls out of "all fields
-// are type: section"); `nestable` → `self_nesting`; authored cross-cutting
-// `constraints` pass through as a bare array. Leaves and nested sections share one
-// ordered `fields:` namespace.
+// are type: section"); `nestable` → `self_nesting`; `append_only` (insert-only
+// records) passes through; authored cross-cutting `constraints` pass through as a
+// bare array. Leaves and nested sections share one ordered `fields:` namespace.
 function lowerSection(def, resolve, optResolve) {
   const out = {}
   if ((def.kind || 'single') === 'multi') out.multiple = true
   if (def.brief === true) out.brief = true
   if (def.nestable) out.self_nesting = true
+  if (def.append_only) out.append_only = true
 
   const fields = {}
   for (const [key, rawField] of Object.entries(def.fields || {})) {

package/src/uwx/locale-sync.js

@@ -18,9 +18,10 @@
 
 import { readFileSync, writeFileSync, existsSync, mkdirSync, readdirSync } from 'node:fs'
 import { join, dirname } from 'node:path'
-import { proseMirrorToMarkdown } from '@uniweb/content-writer'
-import { computeHash, stripInlineTags } from '../i18n/hash.js'
-import { extractUnitsFromDoc } from '../i18n/extract.js'
+import { proseMirrorToMarkdown, serializeInlineContent } from '@uniweb/content-writer'
+import { computeHash } from '../i18n/hash.js'
+import { blockElements, elementText } from '../i18n/extract.js'
+import { resolveDocForLocale } from '../i18n/merge.js'
 import { computeSourceHash } from '../i18n/freeform-manifest.js'
 
 const FREEFORM_MANIFEST = '.manifest.json'
@@ -99,14 +100,18 @@ export function loadLocaleTranslations(siteRoot, locales, subdir = '') {
 
 /**
  * Wrap a section's source-locale content DOC into its localized `content` form: the
- * source locale stays the doc; each target locale becomes a structural
- * `{ source-text: target }` map built from the doc's translatable units joined with
- * `locales/{locale}.json`. The map is keyed by the cleaned (inline-tag-stripped)
- * source text, so the projector's `computeHash(key)` matches the unit hash —
- * closing the round trip. Reuses the i18n extractor (extractUnitsFromDoc).
+ * source locale stays the doc, and EACH TARGET LOCALE BECOMES A SELF-CONTAINED DOC
+ * (not a structural map) — resolved from the doc's source structure joined with
+ * `locales/{locale}.json` via the merge resolver. A self-contained doc is the
+ * portable, renderer-ready form — a source-keyed map is an authoring representation
+ * that must be resolved against the source before it can be rendered; the structural
+ * map lives only on disk (`locales/{locale}.json`) and is recovered on pull (see
+ * unwrapLocalizedContent).
  *
  * Returns the bare doc unchanged when there are no target locales / no translations
- * for any of them (single-locale and pre-localization sites are untouched).
+ * for any of them (single-locale and pre-localization sites are untouched). A
+ * target locale with no translation for THIS doc is omitted (it falls back to the
+ * source locale), so the payload stays lean.
  *
  * @param {object} doc - the source-locale ProseMirror content doc
  * @param {string} sourceLocale
@@ -117,17 +122,12 @@ export function localizeContentDoc(doc, sourceLocale, targetLocales, translation
   if (!isProseMirrorDoc(doc) || !targetLocales || targetLocales.length === 0 || !translations) {
     return doc
   }
-  const units = extractUnitsFromDoc(doc)
   const result = { [sourceLocale]: doc }
   for (const locale of targetLocales) {
     const table = translations[locale]
     if (!table) continue
-    const map = {}
-    for (const [hash, unit] of Object.entries(units)) {
-      const tgt = table[hash]
-      if (typeof tgt === 'string') map[stripInlineTags(unit.source)] = tgt
-    }
-    if (Object.keys(map).length > 0) result[locale] = map
+    const resolved = resolveDocForLocale(doc, table)
+    if (resolved) result[locale] = resolved
   }
   // Only wrap when at least one target carried a translation — else stay a bare doc.
   return Object.keys(result).length > 1 ? result : doc
@@ -235,20 +235,66 @@ export function createTranslationCollector(sourceLocale) {
   return { add, addStructuralMap, noteFreeform, byLocale, freeformPending }
 }
 
+/**
+ * Derive a structural `{ source-text: target-inline-markdown }` map from a
+ * (source doc, target doc) pair — the inverse of resolveDocForLocale, used on pull
+ * to recover the compact `locales/{locale}.json` surface from the DOC the wire now
+ * carries. Returns the map when the target is structurally CONGRUENT with the
+ * source (same sequence of block elements by type) so it round-trips losslessly;
+ * returns null when the target diverges (the caller stores it as a free-form body
+ * instead). An element whose inline markdown is identical to the source is
+ * untranslated and omitted. The value is the target element's inline content as
+ * inline markdown (serializeInlineContent), so emphasis, inline icons, and
+ * 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) {
+  if (!isProseMirrorDoc(sourceDoc) || !isProseMirrorDoc(targetDoc)) return null
+  const src = blockElements(sourceDoc)
+  const tgt = blockElements(targetDoc)
+  if (src.length !== tgt.length) return null // structurally divergent → free-form
+  const map = {}
+  try {
+    for (let i = 0; i < src.length; i++) {
+      if (src[i].type !== tgt[i].type) return null // divergent → free-form
+      const key = elementText(src[i])
+      if (!key) continue
+      const srcMd = serializeInlineContent(src[i].content || [])
+      const tgtMd = serializeInlineContent(tgt[i].content || [])
+      if (srcMd === tgtMd) continue // unchanged → untranslated → omit
+      map[key] = tgtMd
+    }
+  } catch {
+    // a mark we can't serialize → don't risk a lossy map; store as free-form
+    return null
+  }
+  return map
+}
+
 /**
  * Unwrap a (possibly localized) `content` field to the SOURCE-locale ProseMirror
- * doc for the `.md` body, capturing target locales into `collector`: a structural
- * `{ src: target }` map → hash entries; a free-form doc override → noted with its
- * freeform path (`freeformRelPath`, from buildFreeformPath) so it can be written to
- * `locales/freeform/{locale}/…`. A bare doc (no locale wrap) is returned unchanged.
+ * doc for the `.md` body, capturing target locales into `collector`. The wire now
+ * carries a self-contained DOC per target locale: a target structurally congruent
+ * with the source is recovered as a structural `locales/{locale}.json` map (via
+ * deriveStructuralMap); a divergent target is a free-form body override → noted
+ * with its freeform path (`freeformRelPath`, from buildFreeformPath). A structural
+ * map still on the wire (legacy / transition) passes through unchanged. The
+ * reserved `@` (and `$`-prefixed) key is opaque metadata — NEVER a locale. A bare
+ * doc (no locale wrap) is returned unchanged.
  */
 export function unwrapLocalizedContent(content, sourceLocale, collector, freeformRelPath) {
   if (!isLocalizedContent(content)) return content
   const source = content[sourceLocale]
   for (const [locale, value] of Object.entries(content)) {
     if (locale === sourceLocale) continue
-    if (isProseMirrorDoc(value)) collector?.noteFreeform?.(locale, value, source, freeformRelPath)
-    else collector?.addStructuralMap?.(locale, value)
+    if (locale === '@' || locale.startsWith('$')) continue // reserved metadata, not a locale
+    if (isProseMirrorDoc(value)) {
+      const map = deriveStructuralMap(source, value)
+      if (map) collector?.addStructuralMap?.(locale, map)
+      else collector?.noteFreeform?.(locale, value, source, freeformRelPath)
+    } else {
+      collector?.addStructuralMap?.(locale, value)
+    }
   }
   return source
 }

package/src/uwx/registry-package.js

@@ -48,9 +48,14 @@ try {
  * @param {string} [params.scope] - org scope (`@acme` or `acme`) resolving `@/x` -> `@acme/x`.
  * @param {Object} [params.exporter] - `{ tool, version, instance }` for the envelope.
  * @param {string} [params.exportedAt] - ISO timestamp (default: now).
+ * @param {string} [params.digest] - the foundation's content digest (`sha256:…`),
+ *   computed by the CLI over what register ships (shipping-model.md §4.1). Rides
+ *   in the foundation-schema entity's `info.digest`; the backend stores it
+ *   OPAQUE and returns it on the foundation-latest read so `publish`/`status`
+ *   can detect "code changed since release" with no local state.
  * @returns {Object} the `.uwx` document (uwx/1; entities, names only, no uuids).
  */
-export function buildRegistryPackage({ schema, foundationDir, scope, exporter, exportedAt } = {}) {
+export function buildRegistryPackage({ schema, foundationDir, scope, exporter, exportedAt, digest } = {}) {
   const self = schema?._self
   if (!self || !self.name || !self.version) {
     throw new Error('buildRegistryPackage: schema._self with name + version is required')
@@ -65,7 +70,7 @@ export function buildRegistryPackage({ schema, foundationDir, scope, exporter, e
 
   const foundationEntity = {
     model: FOUNDATION_SCHEMA,
-    info: buildInfo(self, org),
+    info: buildInfo(self, org, digest),
     schema: buildSchemaBlob(schema),
     i18n: { locales: loadI18nLocales(foundationDir) },
     'data-schemas': { refs: buildRefs(dataSchemas, scoped) },
@@ -136,12 +141,15 @@ function wrapEntities(entities, exporter, exportedAt) {
 
 // --- foundation-schema content (names only) ----------------------------------
 
-// Identity card — decomposed so it's readable without opening the blob.
-function buildInfo(self, org) {
+// Identity card — decomposed so it's readable without opening the blob. The
+// optional `digest` (sha256:…) is the foundation's content fingerprint; the
+// backend stores it opaque and returns it on the foundation-latest read.
+function buildInfo(self, org, digest) {
   // Scope a bare foundation name (`src` -> `@acme/src`); leave an already-scoped name.
   const name = org && !String(self.name).startsWith('@') ? `@${org}/${self.name}` : self.name
   const info = { name, version: self.version, role: self.role || 'foundation' }
   if (self.description !== undefined) info.description = self.description
+  if (digest) info.digest = digest
   return info
 }