@uniweb/build 0.73.3 → 0.74.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@uniweb/build",
-  "version": "0.73.3",
+  "version": "0.74.0",
   "description": "Build tooling for the Uniweb Component Web Platform",
   "type": "module",
   "exports": {
@@ -57,15 +57,15 @@
     "js-yaml": "^4.1.0",
     "sharp": "^0.35.3",
     "yaml": "^2.5.0",
-    "@uniweb/schemas": "^0.9.4",
-    "@uniweb/content-writer": "^0.3.4",
+    "@uniweb/content-reader": "^1.2.7",
     "@uniweb/projections": "^0.7.11",
-    "@uniweb/semantic-parser": "^1.5.0",
-    "@uniweb/theming": "^0.2.0",
-    "@uniweb/content-reader": "^1.2.7"
+    "@uniweb/content-writer": "^0.3.4",
+    "@uniweb/semantic-parser": "^1.5.1",
+    "@uniweb/schemas": "^0.10.0",
+    "@uniweb/theming": "^0.2.0"
   },
   "optionalDependencies": {
-    "@uniweb/runtime": "^0.28.3"
+    "@uniweb/runtime": "^0.28.4"
   },
   "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/runtime": "^0.28.3",
-    "@uniweb/core": "^0.35.0"
+    "@uniweb/core": "^0.35.0",
+    "@uniweb/runtime": "^0.28.4"
   },
   "peerDependenciesMeta": {
     "vite": {

package/src/docs.js

@@ -8,6 +8,7 @@
 import { readFile, writeFile } from 'node:fs/promises'
 import { existsSync } from 'node:fs'
 import { join, isAbsolute } from 'node:path'
+import { describeContent } from '@uniweb/schemas/content'
 import { buildSchema } from './schema.js'
 import { resolveFoundationSrcPath } from './utils/foundation-source-root.js'
 
@@ -94,25 +95,30 @@ function generateComponentDocs(name, meta) {
     lines.push('')
   }
 
-  // Content expectations — what an author writes in the markdown. The key is
-  // `content`; this read `meta.content` as `meta.elements` until 2026-09-16 —
-  // the pre-rename name, which nothing has produced since. A dead branch reads
-  // exactly like a component that declares nothing, so the whole section was
-  // missing from every generated catalog.
+  // Content expectations — what an author writes in the markdown, read through
+  // `describeContent`: a built schema holds the lowered list (`SCHEMA_FORMAT` 2), a
+  // `meta.js` the declaration as written, and both describe alike. ⛔ This read
+  // `meta.content` as a map of labels until 2026-09-29 — which the lowered list is not —
+  // and as `meta.elements`, the pre-rename name, until 2026-09-16.
   //
-  // A value is either a label string ('Description [1-2]') or { label, hint }.
-  // The LABEL is the point: `paragraphs` alone tells an author nothing, and the
-  // count hint is the part that says how much to write.
-  const elements = Object.entries(meta.content || {})
+  // The LABEL is the point: `paragraphs` alone tells an author nothing, and the count is
+  // the part that says how much to write — shown in the bracket syntax they write.
+  const { elements } = describeContent(meta)
   if (elements.length > 0) {
     lines.push('### Content')
     lines.push('')
 
-    for (const [key, el] of elements) {
-      const label = typeof el === 'string' ? el : el?.label || ''
-      lines.push(`**${key}**${label ? ` — ${label}` : ''}`)
-      const hint = typeof el === 'object' && el?.hint ? el.hint : ''
-      if (hint) lines.push(`  ${hint}`)
+    for (const el of elements) {
+      const name = el.kind === 'concept' ? `md:${el.key}` : el.element
+      const types = el.element === 'media' && el.types.length < 3 ? ` (${el.types.join(', ')})` : ''
+      const count = bracketCount(el)
+      const label = [el.label, count].filter(Boolean).join(' ')
+      lines.push(`**${name}**${types}${label ? ` — ${label}` : ''}`)
+      if (el.hint) lines.push(`  ${el.hint}`)
+      if (el.except) lines.push(`  Leaves out: ${el.except.join(', ')}`)
+      if (el.content) {
+        lines.push(`  Each entry: ${el.content.map((c) => [c.element, c.label].filter(Boolean).join(' — ')).join(' · ')}`)
+      }
       lines.push('')
     }
   }
@@ -120,6 +126,18 @@ function generateComponentDocs(name, meta) {
   return lines.join('\n')
 }
 
+/** A lowered entry's count, as a developer writes it: `[1]`, `[3-6]`, `[2+]` — or ''. */
+function bracketCount({ min, max }) {
+  if (typeof min !== 'number') return ''
+  if (typeof max !== 'number') return `[${min}+]`
+  return min === max ? `[${min}]` : `[${min}-${max}]`
+}
+
+/** The section types of a foundation schema: every key but `_self`, `_layouts` and `dataSchemas`. */
+function sectionTypesOf(schema) {
+  return Object.keys(schema).filter((key) => !key.startsWith('_') && key !== 'dataSchemas')
+}
+
 /**
  * Generate full markdown documentation for a foundation
  *
@@ -146,8 +164,10 @@ export function generateDocsFromSchema(schema, options = {}) {
   lines.push('---')
   lines.push('')
 
-  // Table of contents
-  const componentNames = Object.keys(schema).filter(k => k !== '_self')
+  // Table of contents. A schema's section types are its keys but `_self`, `_layouts` and
+  // `dataSchemas` (`buildSchema`); ⛔ until 2026-09-29 only `_self` was left out, so a
+  // foundation with layouts or data schemas documented both as components.
+  const componentNames = sectionTypesOf(schema)
 
   if (componentNames.length > 0) {
     lines.push('## Components')
@@ -222,7 +242,7 @@ export async function generateDocs(foundationDir, options = {}) {
   await writeFile(outputPath, markdown)
 
   // Count components
-  const componentCount = Object.keys(schema).filter(k => k !== '_self').length
+  const componentCount = sectionTypesOf(schema).length
 
   return { outputPath, componentCount }
 }

package/src/runtime-schema.js

@@ -28,6 +28,7 @@ import { isRichSchema } from '@uniweb/core'
 import { dataRefOf } from '@uniweb/core/data-keys'
 import { briefFieldMap, wholeFieldMap } from '@uniweb/schemas/conform'
 import { enumValues } from '@uniweb/schemas/format'
+import { lowerData } from '@uniweb/schemas/content'
 
 /**
  * A `data:` entry's schema ref — a ref string, or `{ schema }` — or null for an inline
@@ -282,10 +283,16 @@ export function extractRuntimeSchema(fullMeta, dataSchemaMap = {}) {
   // with their refs, because the keys ARE what the section receives, and a key's ref is
   // what a fetch of another name fills it by. `schemas` carries field defaults for the
   // keys that have fields. `data: false` declares nothing, as no `data:` does.
-  if (fullMeta.data === false) {
+  //
+  // ⭐ A concept block's key is written as its fence is — `'md:faq': 'Questions and
+  // answers'` — and lowered to the key a component reads, `faq`, with no schema: the value
+  // is the author's label, never a ref (`lowerData`; ruled 2026-09-29). A built entry is
+  // already lowered; this holds for a `meta.js` handed in as written.
+  const data = lowerData(fullMeta.data)
+  if (data === false) {
     // declares no key
-  } else if (fullMeta.data && typeof fullMeta.data === 'object' && !Array.isArray(fullMeta.data)) {
-    for (const [key, value] of Object.entries(fullMeta.data)) {
+  } else if (data && typeof data === 'object' && !Array.isArray(data)) {
+    for (const [key, value] of Object.entries(data)) {
       // ⛔ A value that is no schema at all declares a key by accident — it would reach the
       // component as `null`, silently. `data: { inherit: [...] }` — the opt-in to cascaded
       // data from 2026-01-31 until declared keys replaced it — is the shape this refuses: it
@@ -307,9 +314,9 @@ export function extractRuntimeSchema(fullMeta, dataSchemaMap = {}) {
         runtime.schemas[key] = lean
       }
     }
-  } else if (fullMeta.data !== undefined) {
+  } else if (data !== undefined) {
     throw new Error(
-      `[uniweb] Invalid 'data' in meta.js: expected false or { <key>: <schema> }, got ${JSON.stringify(fullMeta.data)}. ` +
+      `[uniweb] Invalid 'data' in meta.js: expected false or { <key>: <schema> }, got ${JSON.stringify(data)}. ` +
         "A <schema> is a named ref ('@/x'), an inline field map, or a rich-form { fields: [...] }."
     )
   }

package/src/schema.js

@@ -16,7 +16,8 @@ import { createHash } from 'node:crypto'
 import { isFontVar } from '@uniweb/theming'
 import { join, dirname, extname, basename } from 'node:path'
 import { pathToFileURL } from 'node:url'
-import { describeChildren, describeVisuals } from '@uniweb/schemas/component'
+import { describeChildren, describeVisuals, lowerChildren } from '@uniweb/schemas/component'
+import { describeContent, lowerData } from '@uniweb/schemas/content'
 import { SECTION_PARAMS, SECTION_KEYS } from '@uniweb/schemas/section'
 import { collectSchemaRefs, buildDataSchemaMap, ownSchemaRefs } from './resolve-data-schema.js'
 import {
@@ -47,6 +48,20 @@ const SECTIONS_PATH = 'sections'
 // The layouts path where layout components are discovered
 export const LAYOUTS_PATH = 'layouts'
 
+/**
+ * Which form a foundation schema's entries hold — `_self.schemaFormat`.
+ *
+ *   (absent)  1 — each entry is its `meta.js`, copied as written
+ *   2         `content:` and `children:` lowered (2026-09-29): `content` is the canonical
+ *             list `describeContent` returns, concept blocks included, and `children` the
+ *             object form `lowerChildren` returns; `data:` keys are the keys a component
+ *             reads (`lowerData`). `visuals` and the `content:` element `data` are refused.
+ *
+ * ⭐ A registered version never changes, so a reader holding one learns its form here,
+ * before the form ever changes again — never by sniffing a key's shape.
+ */
+export const SCHEMA_FORMAT = 2
+
 /**
  * Load a meta.js file via dynamic import — as it is on disk now.
  *
@@ -552,9 +567,17 @@ function createImplicitMeta() {
   return {}
 }
 
+/**
+ * What lowering an entry could not read — said once, when the schema is built
+ * (`reportPlacementDeclarations`), rather than at every discovery: the entry is also
+ * discovered to generate the foundation's entry file.
+ */
+const loweringProblems = new WeakMap()
+
 /**
  * Build a component entry: the `meta.js` default export, plus the build's `name`
- * and `path`.
+ * and `path`, with its declarations LOWERED — the form a foundation registers
+ * (`SCHEMA_FORMAT`).
  *
  * ⭐ `title` IS THERE ONLY WHEN THE DEVELOPER WROTE ONE, so its absence says the
  * component is unnamed. That difference decides whether a name can be translated:
@@ -566,17 +589,73 @@ function createImplicitMeta() {
  * ⛔ Until 2026-09-27 the build filled `title` from the name whenever `meta.js`
  * declared none, and added `titleInferred: true` to restore the fact the filling-in
  * erased. Consumers derive the title where they use it instead [Diego, 2026-09-27].
+ *
+ * ⭐ `content:` and `children:` ARE LOWERED, and `data:` with them (ruled 2026-09-29):
+ * `content` becomes the canonical list `describeContent` returns — `image:` and
+ * `videos:` as the `media` element, a count as `min` / `max`, a label only where one
+ * was written, and each `'md:<tag>'` concept block as `{ key, kind: 'concept' }` —
+ * `children` the object form `lowerChildren` returns, and a `'md:<tag>'` key in `data:`
+ * the key a component reads (`lowerData`), so the lean runtime schema delivers
+ * `content.data.<tag>`. A reader of the registered schema needs no framework grammar.
+ * ⛔ Until then every key was copied as written.
  */
 function buildComponentEntry(name, relativePath, meta) {
+  refuseRetired(name, meta)
+
   // ⭐ `name` and `path` are the build's facts, so they are set AFTER the spread: a
   // `meta.js` declaring either cannot change them. ⛔ Until 2026-09-27 they came first,
   // and a `meta.js` `name` became the entry's `name` — which an editor reads as the
   // section type — while the schema stayed keyed by the folder's name.
-  return {
+  const entry = {
     ...meta,
     name,
     path: relativePath,
   }
+
+  const content = describeContent(meta)
+  if (content.elements.length > 0) entry.content = content.elements
+  else delete entry.content
+
+  const children = lowerChildren(meta)
+  if (children) entry.children = children
+  else delete entry.children
+
+  if (meta.data !== undefined) entry.data = lowerData(meta.data)
+
+  const problems = [...content.problems, ...describeChildren(meta).problems]
+  if (problems.length > 0) loweringProblems.set(entry, problems)
+  return entry
+}
+
+/**
+ * Refuse a declaration that was retired, naming what replaces it. A refusal, not a
+ * warning: a retired key would otherwise register as if it still meant something.
+ */
+function refuseRetired(name, meta) {
+  if (meta.visuals !== undefined) {
+    // ⛔ Retired 2026-09-29: the slot is the `media` element of `content:`.
+    const { max, types } = describeVisuals(meta)
+    const count = max === null ? '' : ` [0-${max}]`
+    const suggestion = types
+      ? `media: { label: 'Visual${count}', types: ${JSON.stringify(types).replace(/"/g, "'")} }`
+      : `media: 'Visual${count}'`
+    throw new Error(
+      `[uniweb] ${name} (meta.js): \`visuals\` is retired. Declare the slot in \`content:\` as \`media\` — ` +
+        `an image, a video, or an embedded component — here, \`${suggestion}\`.`
+    )
+  }
+  if (meta.content && typeof meta.content === 'object' && meta.content.data !== undefined) {
+    // ⛔ Retired 2026-09-29: it named no tag, and declaring it delivered nothing.
+    const declared = Object.keys(meta.data && typeof meta.data === 'object' ? meta.data : {})
+    throw new Error(
+      `[uniweb] ${name} (meta.js): the \`content:\` element \`data\` is retired — it named no tag. ` +
+        `Declare the block's tag as a key in \`data:\`: \`'md:<tag>': '<label>'\` for a concept block ` +
+        `(\`\`\`md:<tag>), \`<tag>: {}\` for a data block.` +
+        (declared.length > 0
+          ? ` ${name} already declares \`data: { ${declared.join(', ')} }\`, so remove \`content.data\`.`
+          : '')
+    )
+  }
 }
 
 /**
@@ -932,9 +1011,9 @@ function reportSupports(srcDir, authored, derived, emitted) {
 }
 
 /**
- * Warn about `children` and `visuals` declarations an editor cannot use — read with
- * `@uniweb/schemas`, the grammar the editor reads them with. The entry is emitted as
- * written either way; these are warnings, never refusals.
+ * Warn about `content` and `children` declarations an editor cannot use — what lowering
+ * them could not read (`@uniweb/schemas`, the grammar the editor reads them with). The
+ * entry is emitted lowered either way; these are warnings, never refusals.
  *
  * ⭐ A `children.types` entry must name one of this foundation's section types. A hidden
  * one is not a section type at all, and a child of a type nothing provides renders
@@ -945,9 +1024,15 @@ function reportSupports(srcDir, authored, derived, emitted) {
  */
 export function reportPlacementDeclarations(components) {
   for (const [name, entry] of Object.entries(components)) {
+    // An entry built here was lowered, and kept what it could not read aside; one handed
+    // in as written is read now. (A lowered entry reads as itself, with no problems.)
     const children = describeChildren(entry)
-    const visuals = describeVisuals(entry)
-    for (const problem of [...children.problems, ...visuals.problems]) {
+    const problems = [
+      ...(loweringProblems.get(entry) || []),
+      ...describeContent(entry).problems,
+      ...children.problems,
+    ]
+    for (const problem of problems) {
       console.warn(`Warning: ${name} (meta.js): ${problem}`)
     }
     for (const type of children.types || []) {
@@ -1082,6 +1167,8 @@ export async function buildSchema(srcDir, sectionPaths, derivedSupports = null)
       ...(foundationConfig.description && { description: foundationConfig.description }),
       ...(foundationConfig.defaultLayout && { defaultLayout: foundationConfig.defaultLayout }),
       ...(isExtension && { role: 'extension' }),
+      // The build's fact, last: which form the entries below hold.
+      schemaFormat: SCHEMA_FORMAT,
     },
     // Layout metadata (full, for editor)
     ...(Object.keys(dataSchemas).length > 0 && { dataSchemas }),

package/src/site/asset-processor.js

@@ -14,6 +14,7 @@ import { existsSync } from 'node:fs'
 import { join, basename, extname, dirname } from 'node:path'
 import { createHash } from 'node:crypto'
 import sharp from 'sharp'
+import { mimeFor } from '@uniweb/semantic-parser'
 
 // Image formats that can be converted to WebP
 const CONVERTIBLE_FORMATS = ['.png', '.jpg', '.jpeg', '.gif']
@@ -157,10 +158,15 @@ export async function processAsset(asset, options = {}) {
  * @param {Object} assetManifest - Asset manifest from content collector
  * @param {Object} options - Processing options
  * @param {string} [options.basePath='/'] - Site base path for subdirectory deployments
- * @returns {Promise<Object>} Mapping of original paths to output URLs
+ * @returns {Promise<Object>} `pathMapping` — original paths to output URLs — `results`, and
+ *   `files`: what the build knows of each file it copied, by original path (`name`, `size`, `mime`)
  */
 export async function processAssets(assetManifest, options = {}) {
   const pathMapping = {}
+  // ⭐ A copied file is renamed `{name}-{hash}{ext}`, so its new address no longer names it. A
+  // document carries its file's `name`, `mime` and `size` (a file record's field names), and this
+  // is the one place that knows all three for a local file — `rewriteContentPaths` stamps them.
+  const files = {}
   const results = {
     processed: 0,
     converted: 0,
@@ -175,6 +181,7 @@ export async function processAssets(assetManifest, options = {}) {
     pathMapping[originalPath] = result.output
 
     if (result.processed) {
+      files[originalPath] = { name: basename(asset.resolved), size: result.size, mime: mimeFor(result.outputPath) }
       results.processed++
       results.totalSize += result.size || 0
       if (result.converted) {
@@ -185,7 +192,7 @@ export async function processAssets(assetManifest, options = {}) {
     }
   }
 
-  return { pathMapping, results }
+  return { pathMapping, results, files }
 }
 
 /**
@@ -220,9 +227,10 @@ function rewriteDataPaths(data, pathMapping) {
  *
  * @param {Object} content - ProseMirror document
  * @param {Object} pathMapping - Map of original paths to new paths
+ * @param {Object} [files] - what the build knows of each file it copied (`processAssets`)
  * @returns {Object} Content with rewritten paths
  */
-export function rewriteContentPaths(content, pathMapping) {
+export function rewriteContentPaths(content, pathMapping, files = null) {
   if (!content) return content
 
   // Deep clone to avoid mutating original
@@ -231,11 +239,26 @@ export function rewriteContentPaths(content, pathMapping) {
   function walk(node) {
     if (!node) return
 
-    // Rewrite image src
+    // Rewrite image src — and a video's `poster` / a document's `preview`, which
+    // the collector processes as assets of their own (`walkContentAssets`). Only
+    // `src` was rewritten until 2026-09-29, so an explicit poster was emitted to
+    // dist/assets/ while the page still pointed at its source path.
     if (node.type === 'image' && node.attrs?.src) {
-      const newPath = pathMapping[node.attrs.src]
-      if (newPath) {
-        node.attrs.src = newPath
+      const original = node.attrs.src
+      for (const attr of ['src', 'poster', 'preview']) {
+        const newPath = node.attrs[attr] && pathMapping[node.attrs[attr]]
+        if (newPath) {
+          node.attrs[attr] = newPath
+        }
+      }
+      // A document whose file the build copied: the file's name as the author gave it — the
+      // address now holds a hashed one — its size, and its type (2026-09-29). Only on the built
+      // output, never on what an author stored; a value written on the node stays.
+      const file = node.attrs.role === 'pdf' ? files?.[original] : null
+      if (file) {
+        for (const key of ['name', 'mime', 'size']) {
+          if (node.attrs[key] === undefined && file[key] !== undefined) node.attrs[key] = file[key]
+        }
       }
     }
 
@@ -305,15 +328,16 @@ export function rewriteParamPaths(params, pathMapping) {
  *
  * @param {Object} siteContent - Full site content object
  * @param {Object} pathMapping - Map of original paths to new paths
+ * @param {Object} [files] - what the build knows of each file it copied (`processAssets`)
  * @returns {Object} Site content with rewritten paths
  */
-export function rewriteSiteContentPaths(siteContent, pathMapping) {
+export function rewriteSiteContentPaths(siteContent, pathMapping, files = null) {
   // Deep clone
   const result = JSON.parse(JSON.stringify(siteContent))
 
   function processSection(section) {
     if (section.content) {
-      section.content = rewriteContentPaths(section.content, pathMapping)
+      section.content = rewriteContentPaths(section.content, pathMapping, files)
     }
     if (section.params) {
       section.params = rewriteParamPaths(section.params, pathMapping)

package/src/site/assets.js

@@ -8,7 +8,7 @@
  * act as implicit imports and should be processed/optimized during build.
  */
 
-import { join, dirname, isAbsolute, normalize } from 'node:path'
+import { join, dirname, isAbsolute, normalize, relative, sep } from 'node:path'
 import { existsSync } from 'node:fs'
 
 // Image extensions we should process
@@ -107,21 +107,23 @@ export function isMediaFieldReference(value) {
  * @param {any} data - Parsed JSON/YAML data
  * @param {Function} visitor - Callback for each asset path: (path) => void
  */
-function walkDataAssets(data, visitor) {
+function walkDataAssets(data, visitor, set) {
   if (typeof data === 'string') {
     if (isLocalAssetPath(data)) {
-      visitor(data)
+      visitor(data, set)
     }
     return
   }
 
   if (Array.isArray(data)) {
-    data.forEach(item => walkDataAssets(item, visitor))
+    data.forEach((item, i) => walkDataAssets(item, visitor, (v) => { data[i] = v }))
     return
   }
 
   if (data && typeof data === 'object') {
-    Object.values(data).forEach(value => walkDataAssets(value, visitor))
+    for (const [key, value] of Object.entries(data)) {
+      walkDataAssets(value, visitor, (v) => { data[key] = v })
+    }
   }
 }
 
@@ -137,7 +139,8 @@ function walkDataBlockAssets(doc, visitor) {
 
   // dataBlock nodes have pre-parsed data in attrs.data
   if (doc.type === 'dataBlock' && doc.attrs?.data) {
-    walkDataAssets(doc.attrs.data, visitor)
+    const attrs = doc.attrs
+    walkDataAssets(attrs.data, visitor, (v) => { attrs.data = v })
   }
 
   // Recurse into content
@@ -203,8 +206,9 @@ export function resolveAssetPath(src, contextPath, siteRoot) {
  * Walk a ProseMirror document and collect all asset references
  *
  * @param {Object} doc - ProseMirror document
- * @param {Function} visitor - Callback for each asset: (node, path, attrName) => void
- *                             attrName is 'src', 'poster', or 'preview'
+ * @param {Function} visitor - Callback for each asset: (node, path, attrName, holder) => void
+ *                             attrName is 'src', 'poster', or 'preview'; `holder` is
+ *                             the attrs object the reference lives on, at `holder[attrName]`
  * @param {string} [path=''] - Current path in document (for debugging)
  */
 export function walkContentAssets(doc, visitor, path = '') {
@@ -212,14 +216,14 @@ export function walkContentAssets(doc, visitor, path = '') {
 
   // Check for image nodes
   if (doc.type === 'image' && doc.attrs?.src) {
-    visitor(doc, path, 'src')
+    visitor(doc, path, 'src', doc.attrs)
 
     // Also collect explicit poster/preview attributes as assets
     if (doc.attrs.poster && !isExternalUrl(doc.attrs.poster)) {
-      visitor({ type: 'image', attrs: { src: doc.attrs.poster } }, path, 'poster')
+      visitor({ type: 'image', attrs: { src: doc.attrs.poster } }, path, 'poster', doc.attrs)
     }
     if (doc.attrs.preview && !isExternalUrl(doc.attrs.preview)) {
-      visitor({ type: 'image', attrs: { src: doc.attrs.preview } }, path, 'preview')
+      visitor({ type: 'image', attrs: { src: doc.attrs.preview } }, path, 'preview', doc.attrs)
     }
   }
 
@@ -234,7 +238,7 @@ export function walkContentAssets(doc, visitor, path = '') {
   if (doc.marks && Array.isArray(doc.marks)) {
     doc.marks.forEach((mark, index) => {
       if (mark.attrs?.src) {
-        visitor(mark, `${path}/marks[${index}]`, 'src')
+        visitor(mark, `${path}/marks[${index}]`, 'src', mark.attrs)
       }
     })
   }
@@ -250,42 +254,45 @@ export function walkContentAssets(doc, visitor, path = '') {
  *   - assets: Asset manifest mapping original paths to resolved info
  *   - hasExplicitPoster: Set of video src paths that have explicit poster attributes
  *   - hasExplicitPreview: Set of PDF src paths that have explicit preview attributes
+ *   - uses: every co-located reference, with the file it resolved to and a setter
+ *     for the place it is written — what `disambiguateAssetRefs` needs to rename
+ *     one. In memory only; never part of the site content.
  */
 export function collectSectionAssets(section, markdownPath, siteRoot) {
   const assets = {}
   const hasExplicitPoster = new Set()
   const hasExplicitPreview = new Set()
-
-  // Track current image node's src when we encounter poster/preview
-  let currentImageSrc = null
+  const uses = []
+
+  // One entry per reference. `set` writes a new reference where this one stands;
+  // `flags` carries the explicit-poster/preview marks a renamed video/PDF must keep.
+  const add = (ref, set, flags = null) => {
+    const result = resolveAssetPath(ref, markdownPath, siteRoot)
+    if (result.external || !result.resolved) return
+    assets[ref] = {
+      original: ref,
+      resolved: result.resolved,
+      isImage: result.isImage,
+      isVideo: result.isVideo,
+      isPdf: result.isPdf
+    }
+    // Only a co-located ref depends on WHERE it is written, so only it can name
+    // two different files with one string. A site-root ref (`/x.png`) cannot.
+    if (!ref.startsWith('/') && set) uses.push({ ref, resolved: result.resolved, set, flags })
+  }
 
   // Collect from ProseMirror content
   if (section.content) {
-    walkContentAssets(section.content, (node, path, attrName) => {
-      const result = resolveAssetPath(node.attrs.src, markdownPath, siteRoot)
-
+    walkContentAssets(section.content, (node, path, attrName, holder) => {
+      const ref = node.attrs.src
+      let flags = null
       if (attrName === 'src') {
-        // Main src attribute - track it for potential poster/preview
-        currentImageSrc = node.attrs.src
-
         // Check if this image has explicit poster/preview
-        if (node.attrs.poster) {
-          hasExplicitPoster.add(node.attrs.src)
-        }
-        if (node.attrs.preview) {
-          hasExplicitPreview.add(node.attrs.src)
-        }
-      }
-
-      if (!result.external && result.resolved) {
-        assets[node.attrs.src] = {
-          original: node.attrs.src,
-          resolved: result.resolved,
-          isImage: result.isImage,
-          isVideo: result.isVideo,
-          isPdf: result.isPdf
-        }
+        if (node.attrs.poster) hasExplicitPoster.add(ref)
+        if (node.attrs.preview) hasExplicitPreview.add(ref)
+        flags = { poster: !!node.attrs.poster, preview: !!node.attrs.preview }
       }
+      add(ref, holder ? (v) => { holder[attrName] = v } : null, flags)
     })
   }
 
@@ -301,16 +308,7 @@ export function collectSectionAssets(section, markdownPath, siteRoot) {
     // Only resolve values that are actually asset references. A dual-use field
     // like `background: gray` (a CSS color) must not be treated as a file path.
     if (isMediaFieldReference(value)) {
-      const result = resolveAssetPath(value, markdownPath, siteRoot)
-      if (!result.external && result.resolved) {
-        assets[value] = {
-          original: value,
-          resolved: result.resolved,
-          isImage: result.isImage,
-          isVideo: result.isVideo,
-          isPdf: result.isPdf
-        }
-      }
+      add(value, (v) => { section.params[field] = v })
     }
   }
 
@@ -318,40 +316,66 @@ export function collectSectionAssets(section, markdownPath, siteRoot) {
   // Background can be { image: { src }, video: { src } } with nested asset paths
   const bg = section.params?.background
   if (bg && typeof bg === 'object') {
-    const bgSources = [bg.image?.src, bg.video?.src].filter(Boolean)
-    for (const src of bgSources) {
-      if (typeof src === 'string') {
-        const result = resolveAssetPath(src, markdownPath, siteRoot)
-        if (!result.external && result.resolved) {
-          assets[src] = {
-            original: src,
-            resolved: result.resolved,
-            isImage: result.isImage,
-            isVideo: result.isVideo,
-            isPdf: result.isPdf
-          }
-        }
-      }
+    for (const media of [bg.image, bg.video]) {
+      if (typeof media?.src === 'string') add(media.src, (v) => { media.src = v })
     }
   }
 
   // Collect from tagged code blocks (JSON/YAML data)
   if (section.content) {
-    walkDataBlockAssets(section.content, (assetPath) => {
-      const result = resolveAssetPath(assetPath, markdownPath, siteRoot)
-      if (!result.external && result.resolved) {
-        assets[assetPath] = {
-          original: assetPath,
-          resolved: result.resolved,
-          isImage: result.isImage,
-          isVideo: result.isVideo,
-          isPdf: result.isPdf
-        }
-      }
-    })
+    walkDataBlockAssets(section.content, (assetPath, set) => add(assetPath, set))
+  }
+
+  return { assets, hasExplicitPoster, hasExplicitPreview, uses }
+}
+
+/**
+ * Give every co-located reference that names more than one file its own key.
+ *
+ * The manifest is keyed by the reference AS WRITTEN, site-wide, and a co-located
+ * ref means a different file in every folder — so two pages that both wrote
+ * `./media/shot.png` shared one entry: the last one collected won, and both pages
+ * rendered its image. Each colliding use is renamed to its file's path from the
+ * site root (`./pages/alpha/media/shot.png`, or `../…` for a mounted folder
+ * outside it), which is one key per file by construction and keeps the extension
+ * the later steps classify by. A ref that names one file keeps its key, so a
+ * site without a collision is unchanged.
+ *
+ * Call it on the merged page + layout collection, before the site config's assets
+ * (which have no written place to rename) are merged in.
+ *
+ * @param {Object} collection - merged asset collection (mutated in place)
+ * @param {string} siteRoot - Site root directory
+ * @returns {number} how many references were renamed
+ */
+export function disambiguateAssetRefs(collection, siteRoot) {
+  const uses = collection.uses || []
+  const filesByRef = new Map()
+  for (const use of uses) {
+    if (!filesByRef.has(use.ref)) filesByRef.set(use.ref, new Set())
+    filesByRef.get(use.ref).add(use.resolved)
   }
 
-  return { assets, hasExplicitPoster, hasExplicitPreview }
+  let renamed = 0
+  for (const use of uses) {
+    if (filesByRef.get(use.ref).size < 2) continue
+    const fromRoot = relative(siteRoot, use.resolved).split(sep).join('/')
+    const key = fromRoot.startsWith('../') ? fromRoot : `./${fromRoot}`
+    const entry = collection.assets[use.ref]
+    collection.assets[key] = { ...entry, original: key, resolved: use.resolved }
+    if (use.flags?.poster) collection.hasExplicitPoster?.add(key)
+    if (use.flags?.preview) collection.hasExplicitPreview?.add(key)
+    use.set(key)
+    renamed++
+  }
+  // The shared key no longer names anything written in the content.
+  for (const [ref, files] of filesByRef) {
+    if (files.size < 2) continue
+    delete collection.assets[ref]
+    collection.hasExplicitPoster?.delete(ref)
+    collection.hasExplicitPreview?.delete(ref)
+  }
+  return renamed
 }
 
 /**
@@ -426,13 +450,15 @@ export function mergeAssetCollections(...collections) {
   const merged = {
     assets: {},
     hasExplicitPoster: new Set(),
-    hasExplicitPreview: new Set()
+    hasExplicitPreview: new Set(),
+    uses: []
   }
 
   for (const collection of collections) {
     // Handle both old format (plain object) and new format (with sets)
     if (collection.assets) {
       Object.assign(merged.assets, collection.assets)
+      if (collection.uses) merged.uses.push(...collection.uses)
       collection.hasExplicitPoster?.forEach(p => merged.hasExplicitPoster.add(p))
       collection.hasExplicitPreview?.forEach(p => merged.hasExplicitPreview.add(p))
     } else {

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

@@ -173,7 +173,7 @@ export async function buildSiteData({
   if (assetsOpts.process && siteContent?.assets) {
     const assetCount = Object.keys(siteContent.assets).length
     if (assetCount > 0) {
-      const { pathMapping } = await processAssets(siteContent.assets, {
+      const { pathMapping, files } = await processAssets(siteContent.assets, {
         outputDir: resolvedDistDir,
         assetsSubdir: assetsOpts.outputDir,
         convertToWebp: assetsOpts.convertToWebp,
@@ -197,7 +197,7 @@ export async function buildSiteData({
           }
         )
 
-        finalContent = rewriteSiteContentPaths(siteContent, pathMapping)
+        finalContent = rewriteSiteContentPaths(siteContent, pathMapping, files)
         if (Object.keys(posterMapping).length > 0 || Object.keys(thumbnailMapping).length > 0) {
           finalContent._assetMeta = {
             posters: posterMapping,
@@ -205,7 +205,7 @@ export async function buildSiteData({
           }
         }
       } else {
-        finalContent = rewriteSiteContentPaths(siteContent, pathMapping)
+        finalContent = rewriteSiteContentPaths(siteContent, pathMapping, files)
       }
     }
   } else {

package/src/site/content-collector.js

@@ -31,7 +31,7 @@ import { join, parse, relative, resolve, sep } from 'node:path'
 import { existsSync, statSync, realpathSync, readdirSync } from 'node:fs'
 import yaml from 'js-yaml'
 import { YAML_OPTIONS } from '../utils/yaml-schema.js'
-import { collectSectionAssets, mergeAssetCollections, collectConfigAssets } from './assets.js'
+import { collectSectionAssets, mergeAssetCollections, collectConfigAssets, disambiguateAssetRefs } from './assets.js'
 import { collectSectionIcons, mergeIconCollections, buildIconManifest } from './icons.js'
 import { normalizeHideIn, dropUnpublishedPages, dropHiddenSections } from './nav-visibility.js'
 import { parseFetchConfig, toFetchList } from './data-fetcher.js'
@@ -2592,6 +2592,12 @@ export async function collectSiteContent(sitePath, options = {}) {
   assetCollection = mergeAssetCollections(assetCollection, layoutAssets)
   iconCollection = mergeIconCollections(iconCollection, layoutIcons)
 
+  // One manifest key per file: a co-located ref written the same way in two
+  // folders (`./media/shot.png`) names two files, and would otherwise share one
+  // entry — every page rendering the last one collected. Before the config
+  // assets, which have no written place to rename.
+  disambiguateAssetRefs(assetCollection, sitePath)
+
   // Merge top-level config assets (e.g. document.yml's book.covers.front,
   // banner images, logos) into the manifest. The compile pipeline reads
   // website.assets[<original src>] to resolve these to filesystem paths

package/src/site/file-records.js

@@ -17,63 +17,16 @@
 
 import { statSync } from 'node:fs'
 import { extname } from 'node:path'
+import { mimeFor } from '@uniweb/semantic-parser'
 import { generatePdfThumbnail } from './advanced-processors.js'
 
 export const FILE_MODEL = '@uniweb/file'
 
 // What a file is, by its extension — for the `mime` a file record carries and the type its upload
-// declares. Anything not here is `application/octet-stream`.
-const MIME = {
-  pdf: 'application/pdf',
-  doc: 'application/msword',
-  docx: 'application/vnd.openxmlformats-officedocument.wordprocessingml.document',
-  xls: 'application/vnd.ms-excel',
-  xlsx: 'application/vnd.openxmlformats-officedocument.spreadsheetml.sheet',
-  ppt: 'application/vnd.ms-powerpoint',
-  pptx: 'application/vnd.openxmlformats-officedocument.presentationml.presentation',
-  odt: 'application/vnd.oasis.opendocument.text',
-  ods: 'application/vnd.oasis.opendocument.spreadsheet',
-  odp: 'application/vnd.oasis.opendocument.presentation',
-  rtf: 'application/rtf',
-  epub: 'application/epub+zip',
-  zip: 'application/zip',
-  gz: 'application/gzip',
-  tar: 'application/x-tar',
-  csv: 'text/csv',
-  tsv: 'text/tab-separated-values',
-  txt: 'text/plain',
-  md: 'text/markdown',
-  json: 'application/json',
-  xml: 'application/xml',
-  yml: 'application/yaml',
-  yaml: 'application/yaml',
-  html: 'text/html',
-  png: 'image/png',
-  jpg: 'image/jpeg',
-  jpeg: 'image/jpeg',
-  gif: 'image/gif',
-  svg: 'image/svg+xml',
-  webp: 'image/webp',
-  avif: 'image/avif',
-  mp3: 'audio/mpeg',
-  wav: 'audio/wav',
-  ogg: 'audio/ogg',
-  m4a: 'audio/mp4',
-  mp4: 'video/mp4',
-  webm: 'video/webm',
-  mov: 'video/quicktime',
-}
-
-/**
- * The media type of a file, by its extension.
- *
- * @param {string} name - a file name or path
- * @returns {string}
- */
-export function mimeFor(name) {
-  const ext = extname(String(name || '')).slice(1).toLowerCase()
-  return MIME[ext] || 'application/octet-stream'
-}
+// declares. ⭐ The table is `@uniweb/semantic-parser`'s: the parser reads it for a document's `mime`,
+// and could not reach one here — it has no dependencies. One table; anything not in it is
+// `application/octet-stream`.
+export { mimeFor }
 
 /** Is this file a PDF — the one type a preview is made for? */
 export function isPdfFile(name) {

package/src/site/plugin.js

@@ -1496,7 +1496,7 @@ export function siteContentPlugin(options = {}) {
           console.log(`[site-content] Processing ${assetCount} assets...`)
 
           // Process standard assets (images)
-          const { pathMapping, results } = await processAssets(siteContent.assets, {
+          const { pathMapping, results, files } = await processAssets(siteContent.assets, {
             outputDir: resolvedOutDir,
             assetsSubdir: assetsOptions.outputDir,
             convertToWebp: assetsOptions.convertToWebp,
@@ -1542,7 +1542,7 @@ export function siteContentPlugin(options = {}) {
             // Merge poster and thumbnail mappings into the path mapping
             // Videos: add a .poster property to the content (not replace the src)
             // PDFs: add a .thumbnail property to the content
-            finalContent = rewriteSiteContentPaths(siteContent, pathMapping)
+            finalContent = rewriteSiteContentPaths(siteContent, pathMapping, files)
 
             // Add poster and thumbnail metadata to the site content
             if (Object.keys(posterMapping).length > 0 || Object.keys(thumbnailMapping).length > 0) {
@@ -1553,7 +1553,7 @@ export function siteContentPlugin(options = {}) {
             }
           } else {
             // Rewrite paths in content
-            finalContent = rewriteSiteContentPaths(siteContent, pathMapping)
+            finalContent = rewriteSiteContentPaths(siteContent, pathMapping, files)
           }
 
           // Log results