@uniweb/build 0.24.0 → 0.24.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@uniweb/build",
-  "version": "0.24.0",
+  "version": "0.24.1",
   "description": "Build tooling for the Uniweb Component Web Platform",
   "type": "module",
   "exports": {
@@ -60,15 +60,16 @@
     "sharp": "^0.35.3",
     "yaml": "^2.5.0",
     "@uniweb/theming": "^0.1.15",
-    "@uniweb/content-writer": "^0.3.3",
     "@uniweb/projections": "^0.3.3",
-    "@uniweb/schemas": "^0.2.10"
+    "@uniweb/semantic-parser": "^1.2.3",
+    "@uniweb/schemas": "^0.2.10",
+    "@uniweb/content-writer": "^0.3.3"
   },
   "optionalDependencies": {
-    "@uniweb/runtime": "^0.12.0",
-    "@uniweb/semantic-parser": "^1.2.2",
-    "@uniweb/schemas": "^0.2.10",
-    "@uniweb/content-reader": "^1.2.2"
+    "@uniweb/content-reader": "^1.2.3",
+    "@uniweb/runtime": "^0.12.1",
+    "@uniweb/semantic-parser": "^1.2.3",
+    "@uniweb/schemas": "^0.2.10"
   },
   "peerDependencies": {
     "vite": "^5.0.0 || ^6.0.0 || ^7.0.0",
@@ -77,7 +78,7 @@
     "@tailwindcss/vite": "^4.0.0",
     "@vitejs/plugin-react": "^4.0.0 || ^5.0.0",
     "vite-plugin-svgr": "^4.0.0",
-    "@uniweb/core": "^0.10.0"
+    "@uniweb/core": "^0.10.1"
   },
   "peerDependenciesMeta": {
     "vite": {

package/src/site/build-site-data.js

@@ -42,23 +42,33 @@ import {
  *
  * Emits to `distDir`:
  *   - `site-content.json` — full content tree, sections always inlined.
- *     The deploy CLI reads this and ships it as `payload.locales[default]`
- *     to the worker. Keeping sections inlined is load-bearing: the worker
- *     re-evaluates split-content from the full payload it receives, and
- *     emits `_pages/<lang>/<route>.json` itself when split is active.
- *     If we shipped a stripped manifest (as prerender does for static-host
- *     bundles), the worker would mis-detect split and serve broken pages.
+ *     The deploy CLI reads this and ships it as `payload.locales[default]`.
+ *
+ *     ⛔ Ship FULL sections; never strip them per the split-content rule.
+ *     A stripped manifest is what prerender emits for static-host bundles,
+ *     and a consumer that re-derives split content from the full payload
+ *     would mis-detect split and serve broken pages.
+ *
+ *     ⚠️ This used to justify the rule by stating what the receiving host
+ *     does with the payload. Removed 2026-08-18: the description was
+ *     accurate about one deployment and false about another, and both were
+ *     live at once — so naming "the worker" was wrong even though the
+ *     sentence was true somewhere. Framework has no host client and no host
+ *     knowledge (root CLAUDE.md, THE LANE CHAIN); we cannot tell consumers
+ *     apart and must not write as though we can.
+ *
+ *     ⇒ The rule stands on its own: we do not know which consumers
+ *     re-derive, so we always ship enough for the ones that do.
  *   - `data/<collection>.json` (+ per-record files for `deferred:`
  *     collections) — same shape `processCollections` produces today.
  *   - `assets/<media>` — processed images / video posters / PDF
  *     thumbnails. Filtered by the deploy CLI to MEDIA only at upload time.
  *
  * Does NOT emit:
- *   - HTML, JS, CSS, source maps, `_importmap/*` — none of these are
- *     consumed by Uniweb-edge; the worker generates HTML at request time.
- *   - `_pages/<route>.json` — only meaningful for static-host bundles
- *     where they're served as static assets. Worker derives them from
- *     `payload.locales[lang].pages[].sections` server-side.
+ *   - HTML, JS, CSS, source maps, `_importmap/*` — static-host bundle
+ *     artifacts; a host on this lane renders pages itself.
+ *   - `_pages/<route>.json` — only meaningful for static-host bundles,
+ *     where they are served as files.
  *   - `sitemap.xml`, `robots.txt` — static-host bundle territory. Note these
  *     are simply absent from Uniweb-hosted sites today: nothing in platform
  *     generates them, at publish time or at request time.
@@ -193,11 +203,38 @@ export async function buildSiteData({
   delete finalContent.hasExplicitPoster
   delete finalContent.hasExplicitPreview
 
+  // ⛔ `config.icons` is a HOST-owned slot on this lane — drop it.
+  //
+  // This payload only ever goes to a backend (link mode is what `uniweb deploy`
+  // runs), and `config` is site.yml spread whole, so an author's
+  // `icons.cdnUrl` would otherwise ride along and land in a slot the host is
+  // supposed to fill. The icon base is a property of the DEPLOYMENT, identical
+  // for every site a given backend serves — not something one site gets to
+  // choose [Diego, 2026-08-17].
+  //
+  // The reason it cannot be a site's call is that the base and the NAMESPACE
+  // are coupled: icon filenames are minted by whoever built the corpus, so
+  // content carrying one host's names 404s wholesale against a different base.
+  // A site-level override here is a broken site, not a preference.
+  //
+  // The sync lane never had this exposure — `uwx/site.js` builds `info.*` from
+  // a key-by-key allowlist with no `icons` entry. This makes the two agree.
+  // `site.yml::icons` stays fully live on the bundled/static lanes, which have
+  // no host to ask.
+  //
+  // Rebuilt rather than mutated: `finalContent` is sometimes `siteContent`
+  // itself, and `config` is shared by reference through the shallow copies
+  // above.
+  if (finalContent.config?.icons !== undefined) {
+    const { icons: _hostOwnedIcons, ...configWithoutIcons } = finalContent.config
+    finalContent = { ...finalContent, config: configWithoutIcons }
+  }
+
   // 4. Write `dist/site-content.json` with FULL sections inlined.
   //    Important: do NOT strip sections per the split-content rule here.
-  //    The link-mode deploy ships full content; the worker re-evaluates
-  //    split + emits `_pages/<lang>/<route>.json` itself. Stripping at
-  //    this stage would silently break split-mode sites in production.
+  //    Stripping would silently break split-mode sites on any consumer that
+  //    re-derives split content from the full payload. See the header for
+  //    why this no longer names one.
   const contentPath = join(resolvedDistDir, 'site-content.json')
   await writeFile(contentPath, JSON.stringify(finalContent, null, 2))
 

package/src/site/content-collector.js

@@ -1396,6 +1396,16 @@ async function processPage(pagePath, pageName, siteRoot, { isIndex = false, pare
       // Knowledge page — content feeds AI pipeline instead of (or in addition to) rendering
       ...(pageConfig.knowledge != null ? { knowledge: pageConfig.knowledge } : {}),
 
+      // Per-page section instrumentation opt-in. ⛔ PAGE-LEVEL ONLY, and it must
+      // stay that way: a site-wide form would emit one event per section on every
+      // page, whose cardinality a counter-based collector cannot store (measured:
+      // ~160 distinct values against a 50-value cap folds ~70% into `(other)`).
+      // Deliberately NOT part of the site → page → section cascade that
+      // `prerender:` uses, even though that is the local convention — following it
+      // would re-create the unscoped mode through the front door.
+      // the tracking design, §10b.
+      ...(pageConfig.trackSections != null ? { trackSections: pageConfig.trackSections } : {}),
+
       // Layout options (named layout + per-page overrides)
       layout: {
         ...(resolvedLayoutName ? { name: resolvedLayoutName } : {}),
@@ -2357,7 +2367,7 @@ export async function collectSiteContent(sitePath, options = {}) {
   for (const { message } of langValidation.warnings) {
     console.warn(`[content-collector] ${message}`)
   }
-  // Publish filter (kb/framework/build/uwx-format.md → "Per-locale publish
+  // Publish filter (the sync format's "Per-locale publish
   // readiness"): on published build paths, only the publishable intersection
   // (publishLanguages ∩ languages; absent field = all declared) ships — in
   // the embedded languages list and in route translations. Dev keeps the
@@ -2411,7 +2421,7 @@ export async function collectSiteContent(sitePath, options = {}) {
       // needs no line at all on this lane (`config` spreads all of site.yml) and one
       // line on the sync lane, so it reaches BOTH. The separate file could only ever
       // reach this one, which is what made an authored persona vanish on hosted
-      // sites. See kb/framework/architecture/assistant-config.md.
+      // sites.
       ...(routeTranslations
         ? { i18n: { ...(siteConfig.i18n || {}), routeTranslations } }
         : {}),

package/src/uwx/asset-map.js

@@ -0,0 +1,192 @@
+/**
+ * `assets.json` — the site's committed map from a local asset path to the
+ * backend's content-addressed id.
+ *
+ * ## Why it is COMMITTED, and why that is the whole point
+ *
+ * The same map used to be built on every push and thrown away
+ * (`assetsByLocalUrl`, in memory, consumed by the content rewrite and dropped).
+ * Rebuilt per push it is a private detail; committed it is a **log every machine
+ * collaborating on this site can read**:
+ *
+ *   - a teammate who clones knows which bytes the project expects to exist and
+ *     can fetch the ones they lack, instead of discovering a missing image at
+ *     render;
+ *   - `pull` can put an asset back at **the path its author wrote**, rather than
+ *     inventing one — without this, a push turns `/images/hero.png` into an
+ *     opaque id and nothing remembers it was ever called that;
+ *   - a re-push of unchanged media is visibly a no-op rather than a silent one.
+ *
+ * ⇒ It is project state, not cache. `.uniweb/` is gitignored in both scaffolded
+ * templates, which is why this does not live there.
+ *
+ * ## ⛔ Diff stability is a hard requirement, not tidiness
+ *
+ * A committed file that reorders itself produces a spurious diff on every push
+ * and trains people to stop reading it — at which point a real change to what a
+ * site ships passes unnoticed. Keys are therefore **sorted**, the shape is flat,
+ * and the writer is a no-op when nothing changed (it does not rewrite an
+ * identical file, so `git status` stays clean on a push that moved no assets).
+ *
+ * ## What it deliberately does NOT hold
+ *
+ * ⛔ **No serve URL.** A URL is a host's route layout, and storing one here would
+ * re-create — in a committed file, on every machine — exactly the coupling that
+ * deleting `buildAssetUrl` removed from this CLI. The id plus the host's
+ * `config.assets.url` pattern is the whole address, and only the host owns the
+ * second half.
+ *
+ * ⛔ **No mime or size.** The store validates those and they are its to change;
+ * a second copy here is a second thing to disagree.
+ */
+
+import { existsSync, readFileSync, writeFileSync } from 'node:fs'
+import { ASSET_SLOTS } from '@uniweb/semantic-parser'
+import { join } from 'node:path'
+
+export const ASSET_MAP_FILE = 'assets.json'
+
+/** Current on-disk shape. Bumped only for a breaking layout change. */
+const VERSION = 1
+
+const mapPath = (siteDir) => join(siteDir, ASSET_MAP_FILE)
+
+/**
+ * Read the site's asset map. A missing, unreadable or malformed file reads as
+ * empty rather than throwing: the map is an accelerator and a record, and a
+ * corrupt one must never be the reason a push fails. The next write repairs it.
+ *
+ * @param {string} siteDir
+ * @returns {Record<string, { id: string, ext: string }>} local ref → identity
+ */
+export function readAssetMap(siteDir) {
+  const p = mapPath(siteDir)
+  if (!existsSync(p)) return {}
+  try {
+    const parsed = JSON.parse(readFileSync(p, 'utf8'))
+    const assets = parsed?.assets
+    if (!assets || typeof assets !== 'object') return {}
+    const out = {}
+    for (const [ref, v] of Object.entries(assets)) {
+      if (v && typeof v.id === 'string' && v.id) {
+        out[ref] = { id: v.id, ext: typeof v.ext === 'string' ? v.ext : '' }
+      }
+    }
+    return out
+  } catch {
+    return {}
+  }
+}
+
+/**
+ * Merge `entries` into the site's map and write it if anything changed.
+ *
+ * MERGE, not replace: a push carries only the refs that page's content touched,
+ * so replacing would drop every asset this run happened not to mention — which
+ * is most of them on a partial push. An entry whose id changed is overwritten
+ * (the bytes at that path changed); an identical entry is left alone.
+ *
+ * @param {string} siteDir
+ * @param {Record<string, { id: string, ext: string }>} entries
+ * @returns {{ added: string[], changed: string[], written: boolean }}
+ */
+export function updateAssetMap(siteDir, entries) {
+  const prior = readAssetMap(siteDir)
+  const added = []
+  const changed = []
+
+  for (const [ref, v] of Object.entries(entries || {})) {
+    if (!v?.id) continue
+    const was = prior[ref]
+    if (!was) added.push(ref)
+    else if (was.id !== v.id) changed.push(ref)
+    else continue
+    prior[ref] = { id: v.id, ext: v.ext || '' }
+  }
+
+  if (!added.length && !changed.length) return { added, changed, written: false }
+
+  // Sorted keys + a trailing newline: a committed file that reorders itself
+  // produces a diff on every push and teaches people to skip reading it.
+  const assets = {}
+  for (const ref of Object.keys(prior).sort()) assets[ref] = prior[ref]
+  writeFileSync(
+    mapPath(siteDir),
+    JSON.stringify({ version: VERSION, assets }, null, 2) + '\n'
+  )
+  return { added, changed, written: true }
+}
+
+/**
+ * The local ref a given asset id is known at, or null.
+ *
+ * This is the direction `pull` needs and the reason the map is worth
+ * committing: stored content carries an id, and only this can say the author
+ * called it `/images/hero.png`. Without it a pull must invent a path.
+ *
+ * @param {Record<string, { id: string, ext: string }>} map
+ * @param {string} id
+ * @returns {string|null}
+ */
+export function refForAssetId(map, id) {
+  if (!id) return null
+  for (const [ref, v] of Object.entries(map || {})) {
+    if (v.id === id) return ref
+  }
+  return null
+}
+
+/**
+ * Restore authored asset paths on a document being projected back to files.
+ *
+ * The inverse of the push-side stamp in `sync-package.js`: push replaces a local
+ * ref with the host's serve URL and stamps `assetId` beside it; this reads the
+ * id back and puts the author's own path where the URL is.
+ *
+ * ⭐ **This is the reason the map is committed.** Stored content carries an id
+ * and a URL, and neither says the author called it `/images/hero.png`. Without
+ * this, a dev who pulls a site they pushed yesterday finds every image rewritten
+ * to a backend route — their source mangled by a round trip that touched
+ * nothing. With it, a push/pull cycle is a fixed point on the paths they wrote.
+ *
+ * ⛔ An id the map does not know is LEFT ALONE, deliberately. That is an asset
+ * this project has never held — authored in the app, or pushed from another
+ * machine whose map entry has not arrived — and the honest projection is the URL
+ * that works, not a local path to a file that is not there. Filling those in is
+ * the download's job, not this one.
+ *
+ * `assetId` itself is not removed: it is not a markdown attribute, so the
+ * serializer drops it on the way to disk, and leaving it lets a caller project
+ * the same document twice without the second pass losing identity.
+ *
+ * @param {object} document - the site-content document (mutated in place)
+ * @param {Record<string, { id: string, ext: string }>} map - readAssetMap()
+ * @returns {{ restored: number, unknown: number }}
+ */
+export function restoreAssetRefs(document, map) {
+  const byId = new Map()
+  for (const [ref, v] of Object.entries(map || {})) {
+    if (v?.id && !byId.has(v.id)) byId.set(v.id, ref)
+  }
+  const stats = { restored: 0, unknown: 0 }
+  if (!byId.size) return stats
+
+  const visit = (node) => {
+    if (Array.isArray(node)) return node.forEach(visit)
+    if (!node || typeof node !== 'object') return
+    // Every slot: a poster is the one asset a round trip would still mangle if
+    // only the primary reference were restored.
+    for (const slot of ASSET_SLOTS) {
+      const id = node[slot.id]
+      if (typeof id !== 'string' || !id) continue
+      const ref = byId.get(id)
+      if (!ref) { stats.unknown++; continue }
+      const urlAttr = slot.urls.find((k) => typeof node[k] === 'string') || slot.urls[0]
+      node[urlAttr] = ref
+      stats.restored++
+    }
+    for (const v of Object.values(node)) visit(v)
+  }
+  visit(document)
+  return stats
+}

package/src/uwx/index.js

@@ -72,6 +72,13 @@ export {
   localeFilePath,
 } from './locale-sync.js'
 export { emitSyncPackages } from './sync-package.js'
+export {
+  readAssetMap,
+  updateAssetMap,
+  refForAssetId,
+  restoreAssetRefs,
+  ASSET_MAP_FILE,
+} from './asset-map.js'
 export {
   diffSiteUnits,
   describeSiteDiff,

package/src/uwx/site-project.js

@@ -33,6 +33,7 @@
 // the i18n pipeline). Absent `info` keys are left untouched on disk.
 
 import { join, relative, extname, basename } from 'node:path'
+import { readAssetMap, restoreAssetRefs } from './asset-map.js'
 import { readFileSync, existsSync, unlinkSync, renameSync, rmSync, readdirSync, statSync } from 'node:fs'
 import { createHash } from 'node:crypto'
 import yaml from 'js-yaml'
@@ -373,7 +374,7 @@ export function pageSectionsToFiles({ pageDir, pageSections, ctx, pageContext })
 // and preserved. Keep in sync with pageRecordToYml below.
 const PAGE_YML_MANAGED_KEYS = new Set([
   'id', 'title', 'description', 'label', 'keywords', 'index', 'hidden',
-  'hideIn', 'knowledge', 'redirect', 'rewrite', 'layout', 'seo',
+  'hideIn', 'knowledge', 'trackSections', 'redirect', 'rewrite', 'layout', 'seo',
   'fetch', 'sections',
 ])
 
@@ -396,6 +397,12 @@ function pageRecordToYml(record, sectionsArray, sourceLocale) {
   if (record.hidden !== undefined) y.hidden = record.hidden
   if (record.hide_in !== undefined) y.hideIn = record.hide_in
   if (record.knowledge !== undefined) y.knowledge = record.knowledge
+  // Wire snake_case → authored camelCase, the same crossing `hide_in` → `hideIn`
+  // makes two lines up. ⛔ Both directions or neither: a page prop that pushes
+  // and does not pull is WORSE than one that does neither, because the author's
+  // flag is silently removed from their `page.yml` the first time they run
+  // `uniweb pull`.
+  if (record.track_sections !== undefined) y.trackSections = record.track_sections
   if (record.redirect !== undefined) y.redirect = record.redirect
   if (record.rewrite !== undefined) y.rewrite = record.rewrite
   if (record.layout !== undefined) y.layout = record.layout
@@ -620,12 +627,19 @@ function projectLayout(layoutSections, layoutBaseDir, report, prune, ctx) {
  * @returns {{ config: object, collections: object, locales: object, pages: string[], sections: string[], layout: string[], deleted: string[], renamed: object[] }}
  */
 export function siteContentDocumentToProject({ document, siteRoot, sourceLocale = LOCALIZED_FIELD_ASSUMPTION.defaultSourceLocale, prune = false }) {
-  const report = { config: null, collections: null, locales: null, pages: [], sections: [], layout: [], deleted: [], renamed: [] }
+  const report = { config: null, collections: null, locales: null, assets: null, pages: [], sections: [], layout: [], deleted: [], renamed: [] }
 
   // Collects target-locale translations of localized scalars as they're projected;
   // flushed to locales/{locale}.json at the end (the manifest stays derivable).
   const collector = createTranslationCollector(sourceLocale)
 
+  // Put the author's own asset paths back before anything is serialized. Stored
+  // content carries an id and a serve URL; only the committed map knows the ref
+  // the author wrote. Without this a push/pull cycle rewrites every image in a
+  // developer's source to a backend route — a mangling of files they own, by a
+  // round trip that changed nothing.
+  report.assets = restoreAssetRefs(document, readAssetMap(siteRoot))
+
   report.config = siteInfoToConfig({ document, siteRoot, sourceLocale, collector })
   report.collections = declarationsToCollectionsYml({ document, siteRoot })
 

package/src/uwx/site.js

@@ -206,6 +206,16 @@ function buildPageData(config, ctx) {
   // equivalently by walking the page tree). A reader that tests this field alone
   // honours the branch root and silently misses every child.
   setIf(data, 'knowledge', config.knowledge)
+  // Per-page section instrumentation opt-in. ⭐ Authored camelCase → wire
+  // snake_case, the same crossing `hideIn` → `hide_in` already makes; the
+  // backend's field list is entirely snake_case and stays that way.
+  // ⛔ It MUST cross: without this line the flag works on `--bundle`/`--link`
+  // and is silently ignored on a backend-hosted site, where page config comes
+  // from the backend's projection — i.e. it would fail on the one lane the
+  // feature is sold on, with no instrument able to say why.
+  // ⚠️ Declared backend-side FIRST (`track_sections`, generation 7) — an
+  // undeclared field refuses the whole push, not the field.
+  setIf(data, 'track_sections', config.trackSections)
   setIf(data, 'redirect', config.redirect)
   setIf(data, 'rewrite', config.rewrite)
   setIf(data, 'layout', config.layout)
@@ -282,7 +292,7 @@ const DYNAMIC_RE = /^\[(.+)\]$/
 // The flat `siteProjectToEntity` above emits `items[]` with positional
 // `parent_path` tuple-chains (the register lane, package.js). This lane emits the
 // section-keyed `$`-document the backend's @uniweb/site-content Model actually
-// declares (apps/uniweb-rs/.../system-models/site-content.fixture.yaml) and that
+// declares (the backend's site-content system-model fixture) and that
 // docs/reference/entity-content.md specifies:
 //
 //   - `page_sections` is a CHILD section of `pages` → it rides as an INLINE FIELD
@@ -716,8 +726,16 @@ export async function siteProjectToDocument(siteRoot, opts = {}) {
   // (registry ref / URL / local path), the round-trip source of truth.
   info.foundation = siteYml.foundation
   setIf(info, 'base', siteYml.base)
-  // favicon — a verbatim URL/path string (the kit resolves it, like other media
-  // refs). `assets` is a build-DERIVED upload manifest, not authored config, so it
+  // favicon — a verbatim URL/path string. ⚠️ This comment claimed "the kit
+  // resolves it, like other media refs" until 2026-08-17; measured, `favicon`
+  // appears nowhere in `kit/src` or `runtime/src`. The real consumer is
+  // `build/src/site/plugin.js`, which injects a `<link>` into `index.html` at
+  // BUILD time — from `config.favicon` verbatim, else by auto-detecting
+  // `public/favicon.{svg,ico,png}`. So it is a build-time injection, not a
+  // runtime resolve, and anything giving the favicon a resolvable asset
+  // reference has to act there rather than in the runtime.
+  //
+  // `assets` is a build-DERIVED upload manifest, not authored config, so it
   // is never produced from / projected to the site files.
   setIf(info, 'favicon', siteYml.favicon)
   // Site-level SEO/social metadata — the same shape as page.yml's `seo:` + the
@@ -757,7 +775,7 @@ export async function siteProjectToDocument(siteRoot, opts = {}) {
   // file, which needed a bespoke line in each lane and got one in only the
   // bundle lane — so an authored persona never reached a hosted site at all.
   // A key inside site.yml cannot repeat that, because only this lane needs a
-  // line. (kb/framework/architecture/assistant-config.md)
+  // line.
   //
   // ⛔ Credentials are stripped, not trusted — see `stripCredentials`.
   setIf(info, 'assistant', stripCredentials(siteYml.assistant, 'assistant'))
@@ -773,7 +791,7 @@ export async function siteProjectToDocument(siteRoot, opts = {}) {
   // strip only reaches a KEYED FIELD: a key embedded in the endpoint URL itself
   // (`https://collector/e?key=…`) is invisible here and is disclosed. The host's
   // secret store is the only right home either way.
-  // (kb/framework/plans/tracking.md)
+
   setIf(info, 'tracking', stripCredentials(siteYml.tracking, 'tracking'))
   setIf(info, 'paths', siteYml.paths)
   setIf(info, 'data', siteYml.data ?? siteYml.fetch)

package/src/uwx/sync-package.js

@@ -20,6 +20,7 @@
 //     lane (the idempotent no-op).
 
 import { buildCollectionEntities, entityContentHash } from './collections.js'
+import { ASSET_SLOTS } from '@uniweb/semantic-parser'
 import { buildFolderEntity } from './folder.js'
 import { siteProjectToDocument } from './site.js'
 import { stampUnitUuids, collectUnitUuids } from './site-diff.js'
@@ -110,22 +111,59 @@ function walkEntityAssets(node, visitor) {
 }
 
 // In-place: replace every local-asset-path string the map covers with its serve
-// URL. A ref the map omits (upload failed/skipped) is left untouched — never a
-// broken URL. Returns the (mutated) node.
-function rewriteEntityAssets(node, map) {
+// URL, and stamp the asset's IDENTITY beside it. A ref the map omits (upload
+// failed/skipped) is left untouched — never a broken URL. Returns the (mutated)
+// node.
+//
+// ⭐ `ids` writes `assetId`/`assetExt` ALONGSIDE the URL rather than instead of
+// it, and the "alongside" is the whole safety property of the interim:
+//
+//   - **the id is what survives.** A URL is a host's route layout frozen into
+//     content that outlives it; an id is re-resolved on every render, so a host
+//     that moves its assets costs a config edit rather than a migration.
+//   - **the URL is what RENDERS today.** No deployment emits `config.assets.url`
+//     yet, so a resolver handed an id alone would resolve nothing. With the URL
+//     still there it falls through and renders exactly as before.
+//
+// ⇒ Writing both means content authored now stays correct whichever order the
+// halves arrive in — the same reason the app writes both. The URL is dropped
+// only once every deployment declares a pattern.
+//
+// Identity is stamped on the OBJECT carrying the reference, which covers a
+// ProseMirror image node's attrs (`{src, alt, …}`) and a section background's
+// media object (`{image: {src}}`) with one rule — the two shapes framework
+// resolves, reached through the same walk.
+function rewriteEntityAssets(node, map, ids) {
   if (Array.isArray(node)) {
     for (let i = 0; i < node.length; i++) {
       const v = node[i]
       if (typeof v === 'string') { if (map[v]) node[i] = map[v] }
-      else rewriteEntityAssets(v, map)
+      else rewriteEntityAssets(v, map, ids)
     }
     return node
   }
   if (node && typeof node === 'object') {
+    // Stamp BEFORE the string swap below, while the reference is still the
+    // local ref the ids map is keyed by.
+    if (ids) {
+      // Every asset slot, not just the primary: a video's `poster` and a
+      // document's `preview` are assets like any other, and each has identity
+      // attrs naming which reference they belong to (ASSET_SLOTS).
+      for (const slot of ASSET_SLOTS) {
+        const ref = slot.urls
+          .map((k) => (typeof node[k] === 'string' ? node[k] : null))
+          .find(Boolean)
+        const identity = ref ? ids[ref] : null
+        if (identity?.id) {
+          node[slot.id] = identity.id
+          if (identity.ext) node[slot.ext] = identity.ext
+        }
+      }
+    }
     for (const key of Object.keys(node)) {
       const v = node[key]
       if (typeof v === 'string') { if (map[v]) node[key] = map[v] }
-      else rewriteEntityAssets(v, map)
+      else rewriteEntityAssets(v, map, ids)
     }
   }
   return node
@@ -165,6 +203,8 @@ function rewriteEntityAssets(node, map) {
  *        `publish` fills this for the site's LOCAL extensions after releasing them;
  *        the parallel of `info.foundation`, and needed because `extensions` is a
  *        sibling of `info` rather than a field in it.
+ * @param {Object<string,{id:string,ext:string}>} [opts.assetIds] - local asset ref →
+ *        backend identity, stamped as `assetId`/`assetExt` BESIDE the URL
  * @param {Object<string,string>} [opts.assetRewrite] - map of local asset ref →
  *        backend serve URL; rewrites the entities' media refs before push (the
  *        deploy's 2nd emit). Absent → no rewrite (the f225 sync path is unchanged).
@@ -263,9 +303,11 @@ export async function emitSyncPackages(siteRoot, opts = {}) {
   // every non-deploy caller, so the f225 sync path is byte-identical without it.
   const assetRewrite =
     opts.assetRewrite && typeof opts.assetRewrite === 'object' ? opts.assetRewrite : null
+  const assetIds =
+    opts.assetIds && typeof opts.assetIds === 'object' ? opts.assetIds : null
   if (assetRewrite) {
-    if (siteDoc) rewriteEntityAssets(siteDoc, assetRewrite)
-    for (const e of col.entities) rewriteEntityAssets(e.document, assetRewrite)
+    if (siteDoc) rewriteEntityAssets(siteDoc, assetRewrite, assetIds)
+    for (const e of col.entities) rewriteEntityAssets(e.document, assetRewrite, assetIds)
   }
   // Collect the site-root local refs the deploy must upload (`/images/x.png`).
   // Co-located refs (`./x`, `../x`) need the source `.md` location to resolve — the

package/src/vite-foundation-plugin.js

@@ -60,10 +60,18 @@ let _buildingSSRBundle = false
  * The pin is a **compatibility floor**, not a selector, and it cannot be a
  * selector: a site loads a primary foundation plus N extensions, each emitting
  * its own pin, while a site has exactly one runtime — pins are plural, the
- * choice is singular. The selector is `site.yml::runtime`. The pin's use is
- * VALIDATION — is a site's runtime at or above max() of every loaded
- * foundation's floor? — which belongs wherever all of those foundations are
- * held, not here: this build sees one foundation.
+ * choice is singular. The pin's use is VALIDATION — is a site's runtime at or
+ * above max() of every loaded foundation's floor? — which belongs wherever all
+ * of those foundations are held, not here: this build sees one foundation.
+ *
+ * ⚠️ **This used to say "the selector is `site.yml::runtime`". It is not.** That
+ * key is an operator-level override, not the authoring surface: a link-mode site
+ * is CODELESS, so it has nothing that binds to a runtime version and no basis for
+ * an opinion about one. The selector is the backend's resolution (an explicit pin
+ * → the site's current → a deployment default → newest installed). What a
+ * foundation declares here is the CONSTRAINT on that choice, never the choice.
+ * the site/foundation/runtime model, § "who gets to say
+ * whether a site accepts a newer runtime" is the authority.
  *
  * Reads the resolved version from the foundation's node_modules/@uniweb/
  * runtime/package.json so the pin reflects what was actually linked at
@@ -80,6 +88,27 @@ let _buildingSSRBundle = false
  * foundation's own package.json is recorded alongside the runtime version,
  * declaring the author's intent for the validation above.
  *
+ * ⛔ **`policy` REACHES NOBODY TODAY — it is written here and read by nothing.**
+ * `readRuntimePin()` (`cli/src/utils/code-upload.js`) returns only `.runtime`, so
+ * `register` carries the floor as `info.runtime` and the policy is dropped. A
+ * foundation author who sets `uniweb.runtimePolicy` gets it emitted into `dist/`
+ * and silently discarded.
+ *
+ * ⚖️ **This is a field with standing and no consumer — NOT a mistake to delete.**
+ * The architecture assigns this declaration to the foundation on principle: each
+ * version policy is declared by the party whose code binds to the thing being
+ * updated, and the foundation's JS is what links against the runtime's React and
+ * core. So this is the designated home for the answer; nothing has asked for the
+ * answer yet.
+ *
+ * ⇒ **The event that gives it a consumer** (agreed with the backend, 2026-08-16):
+ * when the runtime declares what it supplies — replacing today's `>=` version
+ * compare, which is a proxy that holds only while the runtime's version number
+ * tracks its externals contract — **or** when the publish path starts consulting
+ * floors at all, whichever lands first. Ask again then; until one of those, delivering
+ * `policy` would add a field compared against a number already known to be a
+ * stand-in. **Do not wire it, and do not remove it, without re-opening that.**
+ *
  * @param {string} outDir - dist/ directory to write to.
  * @param {string} projectRoot - foundation project root (where package.json lives).
  */
@@ -171,6 +200,15 @@ async function emitRuntimePin(outDir, projectRoot) {
   const pinPath = join(outDir, 'runtime-pin.json')
   await writeFile(pinPath, JSON.stringify(pin, null, 2) + '\n', 'utf-8')
   console.log(`Generated runtime-pin.json (runtime ${runtimeVersion}${policy ? `, policy ${policy}` : ''})`)
+  // Said HERE, not only in the header above: this line is where a foundation
+  // author meets the field, and reading "policy X" next to a floor that IS
+  // delivered implies both travel. Only the floor does.
+  if (policy) {
+    console.log(
+      `  note: runtimePolicy "${policy}" is recorded but not yet delivered — nothing consumes it today.\n` +
+        `        The floor (runtime ${runtimeVersion}) does travel, as info.runtime at register.`
+    )
+  }
 }
 
 /**