@uniweb/build 0.73.0 → 0.73.2

package/src/site/file-records.js

@@ -0,0 +1,109 @@
+// ⭐ A FILE RECORD — `@uniweb/file` (2026-09-28 [Diego]). The file itself is the record: any file
+// placed in `<records>/uniweb/file/` (`entity-pool.js::FILE_RECORD_DIRS`) is a record named by its
+// stem, and its label and tags are its `folder.yml` entry's.
+//
+// ⭐ ITS VALUE IS AN ASSET, the same object on every lane:
+//
+//     { url, name, mime, size, preview? }
+//
+// — `url` where the file is served, `name` its file name, `mime` and `size` from the file, and for a
+// PDF a `preview` image. Uploaded to a host, the asset's identity rides beside each URL as media's
+// does (`assetId`/`assetExt`, `previewAssetId`/`previewAssetExt` — `@uniweb/semantic-parser`'s
+// `ASSET_SLOTS`), so a host that moves its assets costs a config edit, not a migration. A component
+// reads `file.url` wherever it renders.
+//
+// ⚠️ A PDF's preview is a PLACEHOLDER card ("PDF · N pages", `advanced-processors.js::
+// generatePdfThumbnail`), not a render of the page — and none at all without `pdf-lib`.
+
+import { statSync } from 'node:fs'
+import { extname } from 'node:path'
+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'
+}
+
+/** Is this file a PDF — the one type a preview is made for? */
+export function isPdfFile(name) {
+  return extname(String(name || '')).toLowerCase() === '.pdf'
+}
+
+/**
+ * A file record's value: `{ url, name, mime, size }`, with `preview` when one is given.
+ *
+ * @param {object} params
+ * @param {string} params.absPath - the file
+ * @param {string} params.name - its file name (`brochure.pdf`)
+ * @param {string} params.url - where it is served, or the key a push rewrites to that
+ * @param {string} [params.preview] - where its preview is served, or the key a push rewrites
+ * @returns {{ url: string, name: string, mime: string, size: number, preview?: string }}
+ */
+export function fileRecordValue({ absPath, name, url, preview }) {
+  const value = { url, name, mime: mimeFor(name), size: statSync(absPath).size }
+  if (preview) value.preview = preview
+  return value
+}
+
+/**
+ * Make a PDF's preview image at `outputPath` — a placeholder card, not a render of the page — or
+ * report that none was made (not a PDF, or `pdf-lib` not installed).
+ *
+ * @returns {Promise<boolean>} whether a preview now exists at `outputPath`
+ */
+export async function makeFilePreview(absPath, outputPath) {
+  if (!isPdfFile(absPath)) return false
+  const result = await generatePdfThumbnail(absPath, outputPath)
+  return Boolean(result?.success)
+}

package/src/site/queries-config.js

@@ -31,6 +31,7 @@
 import { join } from 'node:path'
 import { existsSync, readFileSync } from 'node:fs'
 import { recordLayout } from '@uniweb/schemas/conform'
+import { isSystemRecordRef } from '@uniweb/schemas/system'
 import { detectFoundationType, parseCatalogRef } from './foundation-ref.js'
 import { readRegisteredFoundation } from './registered-foundation.js'
 import { buildDataSchemaMap, SCHEMA_NOT_FOUND } from '../resolve-data-schema.js'
@@ -348,8 +349,8 @@ export function toConfigQueries(declarations) {
  * A `@/name` ref the foundation defines no schema for is absent without a word: a query
  * is named after no schema when its records have none. Any other ref that does not
  * resolve is absent too, and reported in `failures`. With no local foundation only
- * `@std/*` refs resolve — from the build's own copy of the standard schemas — since
- * nothing else is on disk.
+ * `@std/*` refs resolve — from the build's own copy of the standard schemas — and the
+ * system Models a record may name (`@uniweb/link`), since nothing else is on disk.
  *
  * @param {string} siteRoot
  * @param {Iterable<string>} refs - the `schema:` refs of the site's queries
@@ -364,7 +365,7 @@ export async function resolveRecordSchemas(siteRoot, refs, opts = {}) {
   const siteYml = opts.siteYml || (await readYamlFile(join(siteRoot, 'site.yml')))
   const srcDir = localFoundationSrcDir(siteRoot, siteYml)
   for (const ref of wanted) {
-    if (!srcDir && !ref.startsWith('@std/')) continue
+    if (!srcDir && !ref.startsWith('@std/') && !isSystemRecordRef(ref)) continue
     try {
       Object.assign(schemas, await buildDataSchemaMap([ref], { srcDir: srcDir ?? siteRoot }))
     } catch (err) {

package/src/site/query-processor.js

@@ -70,6 +70,8 @@ import { dataKeyTypes } from '../uwx/data-key-types.js'
 import { parseFrontmatter } from '../utils/frontmatter.js'
 import { toDeliveredRecord, toStoredRecord, storedPath, briefFieldMap, contentBodyField, misplacedFields, mapReferences, recordLayout } from '@uniweb/schemas/conform'
 import { collectNestedRefs } from '@uniweb/schemas/format'
+import { labelIn } from './entry-label.js'
+import { fileRecordValue, makeFilePreview } from './file-records.js'
 
 // Try to import content-reader for markdown parsing
 let markdownToProseMirror
@@ -824,6 +826,8 @@ function warnDuplicateSlugs(items, queryName) {
 function readPooledRecords(pooled, config, siteDir, recordsRoot, basePath) {
   return Promise.all(
     pooled.map((e) => {
+      // ⭐ The file itself is the record (`file-records.js`) — nothing in it is read.
+      if (e.fileRecord) return processFileRecord(e, config, siteDir, recordsRoot, basePath)
       const dir = resolve(recordsRoot, ...e.dirs)
       const file = `${e.slug}${e.ext}`
       if (e.ext === '.bib') {
@@ -840,6 +844,18 @@ function readPooledRecords(pooled, config, siteDir, recordsRoot, basePath) {
   )
 }
 
+/**
+ * A file record — `@uniweb/file` (`file-records.js`): the file published under `public/records/`
+ * as a record's co-located asset is (`publishRecordAsset`), a PDF's placeholder preview beside it,
+ * and the record delivered as `{ file: { url, name, mime, size, preview? } }`.
+ */
+async function processFileRecord(e, config, siteDir, recordsRoot, basePath) {
+  const { url, copied } = await publishRecordAsset(e.absPath, siteDir, recordsRoot, basePath)
+  const preview = (await makeFilePreview(e.absPath, `${copied}.preview.webp`)) ? `${url}.preview.webp` : undefined
+  const record = { slug: e.slug, file: fileRecordValue({ absPath: e.absPath, name: e.file, url, preview }) }
+  return deliverRecord(record, config, e.relPath)
+}
+
 /**
  * References, delivered as a host's records service delivers them — measured 2026-09-24
  * on a local backend: `{ entity, brief }`, the record a reference names reduced to its
@@ -933,12 +949,15 @@ function pickBrief(record, keys) {
 }
 
 // What a record's folder entry says about it, as the keys a record is answered with — `$tags`
-// (in the order written) and `$label` — or null when it says nothing.
-function entryKeys(placed) {
+// (in the order written) and `$label` — or null when it says nothing. A label given per language
+// answers in the language compiled (`entry-label.js::labelIn`); the site's other languages get
+// theirs where their files are written (`i18n/records.js`).
+function entryKeys(placed, locale = null) {
   if (!placed) return null
   const out = {}
   if (Array.isArray(placed.tags) && placed.tags.length) out.$tags = [...placed.tags]
-  if (typeof placed.label === 'string' && placed.label) out.$label = placed.label
+  const label = labelIn(placed.label, locale, locale)
+  if (label) out.$label = label
   return Object.keys(out).length ? out : null
 }
 
@@ -1001,7 +1020,7 @@ async function collectItems(siteDir, config, recordsRoot, basePath, locale = nul
   // answers them (ruled 2026-09-27 [Diego]). Absent when the entry says none.
   items = items.map((result, i) => {
     const placed = pooled[i] ? config.placements?.get(pooled[i].id) : null
-    const said = entryKeys(placed)
+    const said = entryKeys(placed, locale)
     const at = (item) => {
       if (!item) return item
       const out = { ...item, ...said, [BRANCH_KEY]: placed?.path ?? '' }

package/src/site/records-config.js

@@ -47,6 +47,11 @@ import yaml from 'js-yaml'
 import { YAML_OPTIONS } from '../utils/yaml-schema.js'
 import { compareByNumericPrefix } from '../utils/numeric-prefix.js'
 import { RECORDS_DIR, FOLDER_YML, resolveRecordsDir } from './entity-pool.js'
+import { readLabel } from './entry-label.js'
+
+// What a label may be, for every message that refuses one.
+const LABEL_FORMS =
+  "A label is the entry's display text: one text, or one per language (`label: { en: …, fr: … }`)."
 
 export { FOLDER_YML }
 
@@ -276,13 +281,15 @@ export function resolveFolder(entries, pool, { dir = RECORDS_DIR } = {}) {
       }
       if (tags.length) said.tags = tags
     }
+    // ⭐ One text — the site's default language — or one text per language, `{ en: …, fr: … }`
+    // (`entry-label.js`, 2026-09-28).
     if (entry.label !== undefined && entry.label !== null) {
-      if (typeof entry.label !== 'string' && typeof entry.label !== 'number') {
-        errors.push(`${file}: ${where} has a \`label:\` that is not text. A label is the entry's display text.`)
+      const read = readLabel(entry.label)
+      if (read.error) {
+        errors.push(`${file}: ${where} has a \`label:\` that ${read.error}. ${LABEL_FORMS}`)
         return null
       }
-      const label = String(entry.label).trim()
-      if (label) said.label = label
+      if (read.label !== null) said.label = read.label
     }
     return said
   }
@@ -371,7 +378,14 @@ export function resolveFolder(entries, pool, { dir = RECORDS_DIR } = {}) {
       }
       folderAt.set(at, where)
       const branch = { kind: 'branch', name: segment }
-      if (entry.label !== undefined && entry.label !== null) branch.label = String(entry.label)
+      if (entry.label !== undefined && entry.label !== null) {
+        const read = readLabel(entry.label)
+        if (read.error) {
+          errors.push(`${file}: folder "${segment}" (${where}) has a \`label:\` that ${read.error}. ${LABEL_FORMS}`)
+          return []
+        }
+        if (read.label !== null) branch.label = read.label
+      }
       // A folder takes `tags:` as a record's entry does — kept, sent and pulled back, though
       // no question answers a folder.
       if (entry.tags !== undefined && entry.tags !== null) {

package/src/uwx/entity-source.js

@@ -73,7 +73,8 @@ export async function readEntityFile(filepath) {
 async function readOneFile(filepath) {
   const ext = extname(filepath).toLowerCase()
   const format = formatFor(ext)
-  const slugFromName = basename(filepath, ext)
+  // Cut as written, as the pool names it (`site/entity-pool.js`) — `ext` is lowercased.
+  const slugFromName = basename(filepath, extname(filepath))
   const raw = await readFile(filepath, 'utf-8')
 
   if (format === 'md') {

package/src/uwx/file-records.js

@@ -0,0 +1,178 @@
+// ⭐ A FILE RECORD IS A FOLDER ENTRY OF KIND `file`, NEVER AN ENTITY — `@uniweb/file` (2026-09-28).
+//
+// On the file side the file itself is the record (`site/file-records.js`): any file in
+// `records/uniweb/file/`, named by its stem, its label and tags on its `folder.yml` entry. On the wire
+// a backend holds it as an item of the site's `@uniweb/folder`:
+//
+//     { kind: 'file', name, file: { url, name, mime, size, preview?, assetId, assetExt, … }, label?, tags?, $uuid? }
+//
+// — its value an ASSET: the file goes up through the asset lane the site's media use (owned by the
+// site), and the push writes the serve URL and the asset's identity where the upload key stood,
+// exactly as it does for media (`sync-package.js::rewriteEntityAssets`).
+//
+// ⭐ ITS IDENTITY is the entry's `$uuid`. A file cannot carry it, so the CLI banks it per backend in
+// `sync.json`, keyed by the file's path in the records directory (`files`): a renamed file is a new
+// record, as a renamed record file's name is a new name.
+
+import { existsSync, mkdirSync } from 'node:fs'
+import { dirname, join } from 'node:path'
+import { labelOnWire } from '../site/entry-label.js'
+import { FILE_RECORD_DIRS } from '../site/entity-pool.js'
+import { fileRecordValue, makeFilePreview, mimeFor } from '../site/file-records.js'
+
+export { FILE_MODEL } from '../site/file-records.js'
+
+/** The key a push writes where a file record's URL goes, until its upload maps it to the serve URL. */
+export const fileUploadKey = (poolPath) => `records/${poolPath}`
+/** …and where its preview's goes. */
+export const previewUploadKey = (poolPath) => `records/${poolPath}.preview.webp`
+
+/**
+ * Each file record's value as a push first writes it — upload keys where the URLs go — and the files
+ * the push uploads for them: the file, and a PDF's preview made into `.uniweb/file-previews/`.
+ *
+ * @param {object} params
+ * @param {Array<{ poolPath: string, name: string, absPath: string }>} params.files
+ * @param {string} params.siteRoot
+ * @returns {Promise<{ values: Map<string, object>, uploads: Array<{ ref: string, path: string, contentType: string }> }>}
+ *   `values` by pool path
+ */
+export async function fileRecordUploads({ files = [], siteRoot }) {
+  const values = new Map()
+  const uploads = []
+  for (const f of files) {
+    const previewPath = join(siteRoot, '.uniweb', 'file-previews', `${f.poolPath}.preview.webp`)
+    mkdirSync(dirname(previewPath), { recursive: true })
+    const hasPreview = (await makeFilePreview(f.absPath, previewPath)) && existsSync(previewPath)
+    values.set(
+      f.poolPath,
+      fileRecordValue({
+        absPath: f.absPath,
+        name: f.name,
+        url: fileUploadKey(f.poolPath),
+        ...(hasPreview ? { preview: previewUploadKey(f.poolPath) } : {}),
+      })
+    )
+    uploads.push({ ref: fileUploadKey(f.poolPath), path: f.absPath, contentType: mimeFor(f.name) })
+    if (hasPreview) uploads.push({ ref: previewUploadKey(f.poolPath), path: previewPath, contentType: 'image/webp' })
+  }
+  return { values, uploads }
+}
+
+/**
+ * A file entry as the wire carries it.
+ *
+ * @param {{ slug: string, uuid?: string|null, value: object }} file
+ * @param {{ label?: *, tags?: string[] }} node - its placement
+ * @param {string} sourceLocale
+ */
+export function fileLeaf(file, node, sourceLocale) {
+  const leaf = { kind: 'file', name: file.slug, file: { ...file.value } }
+  if (file.uuid) leaf.$uuid = file.uuid
+  if (node?.label !== undefined) leaf.label = labelOnWire(node.label, sourceLocale)
+  if (Array.isArray(node?.tags) && node.tags.length) leaf.tags = [...node.tags]
+  return leaf
+}
+
+/**
+ * Every file entry in a folder document.
+ *
+ * @param {object} folderDoc - `{ contents }`, nesting through `$children`
+ * @returns {object[]}
+ */
+export function fileItems(folderDoc) {
+  const out = []
+  const walk = (nodes) => {
+    for (const node of nodes || []) {
+      if (!node || typeof node !== 'object') continue
+      if (node.kind === 'branch') walk(node.$children)
+      else if (node.kind === 'file') out.push(node)
+    }
+  }
+  walk(folderDoc?.contents)
+  return out
+}
+
+/**
+ * After a push: the uuid the backend holds each file entry under, by the file's path — what the CLI
+ * banks in `sync.json` (`files`). Matched by name: a file record's name is its file's stem, and no
+ * two share one.
+ *
+ * @param {object} params
+ * @param {Array<{ slug: string, poolPath: string }>} params.files
+ * @param {object} params.folderDoc - the folder document the backend returned
+ * @returns {Object<string,string>} pool path → the backend's uuid
+ */
+export function bankedFileUuids({ files = [], folderDoc }) {
+  const bySlug = new Map(files.map((f) => [f.slug, f]))
+  const out = {}
+  for (const item of fileItems(folderDoc)) {
+    const file = bySlug.get(item.name)
+    if (file && typeof item.$uuid === 'string' && item.$uuid) out[file.poolPath] = item.$uuid
+  }
+  return out
+}
+
+/**
+ * A pull: where each file entry of the folder lands in `records/uniweb/file/`, and which files have
+ * to be fetched — a file the project already holds under that entry's identity is kept, one whose
+ * asset has changed is fetched again, and one it does not hold is fetched to `<its name>`.
+ *
+ * ⛔ A FILE OF THAT NAME HOLDING ANOTHER RECORD IS NOT WRITTEN OVER — reported, and left out.
+ *
+ * @param {object} params
+ * @param {object} params.folderDoc
+ * @param {string} params.recordsRoot - the records directory, absolute
+ * @param {Object<string,string>} [params.fileMap] - pool path → the backend's uuid (`sync.json` `files`)
+ * @param {Object<string,{ id: string }>} [params.assetMap] - upload key → the asset it last uploaded as
+ * @returns {{ pathByUuid: Map<string,string>, downloads: Array<{ url: string, path: string, poolPath: string, ref: string, assetId?: string, assetExt?: string }>, learned: Object<string,string>, warnings: string[] }}
+ *   a download's `ref` is the key its asset is recorded under (`sync.json` `assets`), as a push records it
+ */
+export function filesToPull({ folderDoc, recordsRoot, fileMap = {}, assetMap = {} }) {
+  const pathByTheirs = new Map(Object.entries(fileMap).map(([poolPath, theirs]) => [theirs, poolPath]))
+  const pathByUuid = new Map()
+  const downloads = []
+  const learned = {}
+  const warnings = []
+  for (const item of fileItems(folderDoc)) {
+    const theirs = typeof item.$uuid === 'string' && item.$uuid ? item.$uuid : null
+    const url = typeof item.file?.url === 'string' ? item.file.url : null
+    const fileName = fileNameFor(item)
+    if (!theirs || !url || !fileName) {
+      warnings.push(`the folder holds a file ("${item.name ?? '?'}") with no identity, url or name — not written.`)
+      continue
+    }
+    let poolPath = pathByTheirs.get(theirs) || null
+    const held = poolPath && existsSync(join(recordsRoot, ...poolPath.split('/')))
+    if (!held) {
+      poolPath = [...FILE_RECORD_DIRS, fileName].join('/')
+      const at = join(recordsRoot, ...poolPath.split('/'))
+      if (existsSync(at) && fileMap[poolPath] !== theirs) {
+        warnings.push(`${poolPath} holds another file than the folder's "${item.name}" — it was not written over.`)
+        continue
+      }
+    }
+    const path = join(recordsRoot, ...poolPath.split('/'))
+    const current = assetMap[fileUploadKey(poolPath)]?.id
+    if (!held || (item.file.assetId && current !== item.file.assetId)) {
+      downloads.push({
+        url,
+        path,
+        poolPath,
+        ref: fileUploadKey(poolPath),
+        ...(item.file.assetId ? { assetId: item.file.assetId, assetExt: item.file.assetExt || '' } : {}),
+      })
+    }
+    pathByUuid.set(theirs, poolPath)
+    learned[poolPath] = theirs
+  }
+  return { pathByUuid, downloads, learned, warnings }
+}
+
+/** The name a pulled file is written under: its value's `name`, else the entry's name and the asset's extension. */
+function fileNameFor(item) {
+  const named = typeof item.file?.name === 'string' ? item.file.name.trim() : ''
+  if (named && !named.includes('/') && !named.includes('\\') && !named.startsWith('.')) return named
+  const ext = typeof item.file?.assetExt === 'string' && item.file.assetExt ? `.${item.file.assetExt}` : ''
+  return typeof item.name === 'string' && item.name ? `${item.name}${ext}` : null
+}

package/src/uwx/folder.js

@@ -50,6 +50,10 @@
 // is keyed by the site's uuid on that backend, from `sync.json`). The framework
 // never holds a folder uuid.
 
+import { labelOnWire } from '../site/entry-label.js'
+import { linkLeaf } from './link-records.js'
+import { fileLeaf } from './file-records.js'
+
 export const FOLDER_MODEL_NAME = '@uniweb/folder'
 export const FOLDER_ENTITY_KEY = '@folder'
 
@@ -91,20 +95,34 @@ function refLeaf(entity) {
  * @param {Map<string, object>} byEntityId - record entities, keyed by pool id
  * @param {string[]} missing - collects ids that resolved to no entity
  */
-function contentsFromNodes(nodes, byEntityId, missing, sourceLocale) {
+function contentsFromNodes(nodes, byEntityId, missing, sourceLocale, byLinkId = new Map(), byFileId = new Map()) {
   const out = []
   for (const node of nodes || []) {
     if (node.kind === 'branch') {
       const branch = { kind: 'branch', name: node.name }
       // The display text is a LOCALIZED field on the wire — a `{ locale: value }`
-      // map, like every localized scalar this producer sends — keyed by the
-      // site's source locale.
-      if (node.label !== undefined) branch.label = { [sourceLocale]: String(node.label) }
+      // map, like every localized scalar this producer sends: every language the
+      // file gives, or the one text it gives as the site's source locale's
+      // (`entry-label.js`).
+      if (node.label !== undefined) branch.label = labelOnWire(node.label, sourceLocale)
       if (Array.isArray(node.tags) && node.tags.length) branch.tags = [...node.tags]
-      branch.$children = contentsFromNodes(node.$children, byEntityId, missing, sourceLocale)
+      branch.$children = contentsFromNodes(node.$children, byEntityId, missing, sourceLocale, byLinkId, byFileId)
       out.push(branch)
       continue
     }
+    // ⭐ A LINK RECORD IS AN ENTRY OF ITS OWN KIND, holding its data — never a ref to an entity
+    // (`./link-records.js`).
+    const link = byLinkId.get(node.$entityId)
+    if (link) {
+      out.push(linkLeaf(link, node, sourceLocale))
+      continue
+    }
+    // …and so is a file record, its value an asset (`./file-records.js`).
+    const file = byFileId.get(node.$entityId)
+    if (file) {
+      out.push(fileLeaf(file, node, sourceLocale))
+      continue
+    }
     const entity = byEntityId.get(node.$entityId)
     if (!entity) {
       missing.push(node.$entityId)
@@ -114,7 +132,7 @@ function contentsFromNodes(nodes, byEntityId, missing, sourceLocale) {
     // ⭐ What the folder says about the record (`records/folder.yml`, ruled 2026-09-27
     // [Diego]): its display text, localized as a branch's is, and its tags, in the order
     // written. A records service answers them beside the record as `$label` and `$tags`.
-    if (node.label !== undefined) leaf.label = { [sourceLocale]: String(node.label) }
+    if (node.label !== undefined) leaf.label = labelOnWire(node.label, sourceLocale)
     if (Array.isArray(node.tags) && node.tags.length) leaf.tags = [...node.tags]
     out.push(leaf)
   }
@@ -205,7 +223,13 @@ export function stampFolderItemUuids(doc, pathToUuid = {}) {
   let stamped = 0
   let unknown = 0
   const claimed = new Set()
+  // ⭐ An item that already carries its identity keeps it — a link entry's `$uuid` is its
+  // record's (`./link-records.js`) — and no other item may be stamped with it.
+  walkFolderItems(doc?.contents, (_at, item) => {
+    if (typeof item.$uuid === 'string' && item.$uuid) claimed.add(item.$uuid)
+  })
   walkFolderItems(doc?.contents, ({ path, unique, record }, item) => {
+    if (typeof item.$uuid === 'string' && item.$uuid) return
     let uuid = record ? pathToUuid[`@${record}`] : undefined
     if (!uuid && unique) uuid = pathToUuid[path]
     if (uuid && !claimed.has(uuid)) {
@@ -228,6 +252,10 @@ export function stampFolderItemUuids(doc, pathToUuid = {}) {
  * @param {object} params
  * @param {object[]} params.recordEntities - the record entities (full set, BEFORE
  *        send-only-changed filtering), each `{ id, uuid, slug, model }`
+ * @param {object[]} [params.links] - the link records, each `{ id, slug, url, uuid }` — sent as
+ *        entries of kind `link`, never as entities (`./link-records.js`)
+ * @param {object[]} [params.files] - the file records, each `{ id, slug, uuid, value }` — sent as
+ *        entries of kind `file`, their `value` an asset (`./file-records.js`)
  * @param {Array} params.folderNodes - the placed records: `folder.yml`'s sub-folders,
  *        then every record at the top
  * @param {boolean} [params.declared] - whether the records DIRECTORY exists. See below.
@@ -238,7 +266,7 @@ export function stampFolderItemUuids(doc, pathToUuid = {}) {
  *        keyed under on the wire
  * @returns {{ id, uuid, model, file, document, warnings }|null}
  */
-export function buildFolderEntity({ recordEntities, folderNodes = [], declared, itemUuids = null, sourceLocale = 'en' }) {
+export function buildFolderEntity({ recordEntities, links = [], files = [], folderNodes = [], declared, itemUuids = null, sourceLocale = 'en' }) {
   // ⛔ `missing` AND `empty` ARE DIFFERENT, AND THE ASYMMETRY IS DELIBERATE.
   //
   //   no records directory  → null. INERT: nothing is sent, and the backend's
@@ -256,9 +284,11 @@ export function buildFolderEntity({ recordEntities, folderNodes = [], declared,
 
   const byEntityId = new Map()
   for (const e of recordEntities || []) byEntityId.set(e.id, e)
+  const byLinkId = new Map((links || []).map((l) => [l.id, l]))
+  const byFileId = new Map((files || []).map((f) => [f.id, f]))
 
   const missing = []
-  const contents = contentsFromNodes(folderNodes, byEntityId, missing, sourceLocale)
+  const contents = contentsFromNodes(folderNodes, byEntityId, missing, sourceLocale, byLinkId, byFileId)
   // ⚠️ `id` IS THE RECORD'S PATH IN THE RECORDS DIRECTORY, NOT A FOLDER PATH — say
   // so, because the two read identically and a reader who takes it for a placement
   // concludes the emitter is dropping a branch it never had. *(Measured 2026-08-31:

package/src/uwx/index.js

@@ -188,3 +188,11 @@ export {
   writeRegisteredFoundation,
 } from '../site/registered-foundation.js'
 export { parseCatalogRef } from '../site/foundation-ref.js'
+
+// Link records — `@uniweb/link`: a file in `records/uniweb/link/` on the file side, a folder entry of
+// kind `link` on the wire, never an entity.
+export { LINK_MODEL, linkItems, backfillLinkUuids, writeLinkRecords, linkRecordRefusal } from './link-records.js'
+
+// File records — `@uniweb/file`: the file itself in `records/uniweb/file/` on the file side, a folder
+// entry of kind `file` on the wire, its value an asset.
+export { FILE_MODEL, fileItems, bankedFileUuids, filesToPull } from './file-records.js'