@uniweb/build 0.72.0 → 0.73.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@uniweb/build",
-  "version": "0.72.0",
+  "version": "0.73.1",
   "description": "Build tooling for the Uniweb Component Web Platform",
   "type": "module",
   "exports": {
@@ -58,10 +58,10 @@
     "sharp": "^0.35.3",
     "yaml": "^2.5.0",
     "@uniweb/content-reader": "^1.2.7",
-    "@uniweb/content-writer": "^0.3.4",
+    "@uniweb/schemas": "^0.9.2",
     "@uniweb/projections": "^0.7.11",
     "@uniweb/semantic-parser": "^1.4.1",
-    "@uniweb/schemas": "^0.9.1",
+    "@uniweb/content-writer": "^0.3.4",
     "@uniweb/theming": "^0.2.0"
   },
   "optionalDependencies": {
@@ -74,8 +74,8 @@
     "@tailwindcss/vite": "^4.0.0",
     "@vitejs/plugin-react": "^4.0.0 || ^5.0.0",
     "vite-plugin-svgr": "^4.0.0",
-    "@uniweb/core": "^0.35.0",
-    "@uniweb/runtime": "^0.28.3"
+    "@uniweb/runtime": "^0.28.3",
+    "@uniweb/core": "^0.35.0"
   },
   "peerDependenciesMeta": {
     "vite": {

package/src/i18n/records.js

@@ -14,7 +14,7 @@ import { readFile, writeFile, readdir, mkdir, rm } from 'fs/promises'
 import { existsSync } from 'node:fs'
 import { join, resolve, sep } from 'node:path'
 import { pathToFileURL } from 'node:url'
-import { DATA_DIR } from '@uniweb/core'
+import { DATA_DIR, resolveDefaultLocale } from '@uniweb/core'
 import yaml from 'js-yaml'
 import { YAML_OPTIONS } from '../utils/yaml-schema.js'
 import { markdownToProseMirror } from '@uniweb/content-reader'
@@ -28,7 +28,9 @@ import { toDeliveredRecord, contentBodyField, misplacedFields, mergedFromStored,
 import { resolveDocForLocale } from './merge.js'
 import { extractUnitsFromDoc } from './extract.js'
 import { flatFormRefusal, extractExcerpt } from '../site/query-processor.js'
-import { poolDirsForSchema, schemaForPoolDirs, resolveRecordsDir } from '../site/entity-pool.js'
+import { poolDirsForSchema, schemaForPoolDirs, resolveRecordsDir, readEntityPool, groupPoolBySchema } from '../site/entity-pool.js'
+import { readRecordsConfig, resolveFolder } from '../site/records-config.js'
+import { labelIn } from '../site/entry-label.js'
 // The heuristic judgement about which strings inside structured data are prose.
 // It lives in its own module because the page lane needs exactly the same
 // answer for a tagged data block's payload — a `label` is prose and an `href`
@@ -679,7 +681,9 @@ async function poolDirsByQuery(siteRoot) {
  *   none), which says where a free-form body and frontmatter go, and where the body is;
  * - `models` — the model its records are pushed as (`modelOf`), which says which of their fields
  *   are translated; `targets` — the model each reference names, by its ref, transitively;
- * - `excerpts` — its excerpt settings, which derive an excerpt (`EXCERPT`).
+ * - `excerpts` — its excerpt settings, which derive an excerpt (`EXCERPT`);
+ * - `labels` — the labels its records' folder entries give per language, by record name, which
+ *   each language answers as `$label` (`entry-label.js`); and `defaultLocale`, the site's.
  *
  * ⭐ THE MODEL IS THE TYPE THE RECORDS ARE OF, which is not always the schema they are delivered
  * in. A query whose name-defaulted schema (`@/team`) no data schema answers, for a data key the
@@ -687,9 +691,11 @@ async function poolDirsByQuery(siteRoot) {
  * as its entities (`uwx/data-key-types.js`) — while the build delivers them as they are written.
  * The type is read from the foundation's built `schema.json`, the input a push reads it from.
  *
- * @returns {Promise<{ poolDirs: Map<string, string>, schemas: Map<string, Object|null>, models: Map<string, Object|null>, targets: Map<string, Object|null>, excerpts: Map<string, Object> }>}
+ * @returns {Promise<{ poolDirs: Map<string, string>, schemas: Map<string, Object|null>, models: Map<string, Object|null>, targets: Map<string, Object|null>, excerpts: Map<string, Object>, labels: Map<string, Map<string, Object>>, defaultLocale: string|null }>}
  */
 async function recordQueries(siteRoot) {
+  const labels = new Map()
+  let defaultLocale = null
   const poolDirs = new Map()
   const schemas = new Map()
   const models = new Map()
@@ -697,6 +703,7 @@ async function recordQueries(siteRoot) {
   const excerpts = new Map()
   try {
     const siteYml = await readSiteYml(siteRoot)
+    defaultLocale = resolveDefaultLocale(siteYml) ?? null
     const { declarations } = await resolveQueriesConfig(siteRoot, { siteYml })
     const entries = Object.entries(declarations || {})
     for (const [name, decl] of entries) {
@@ -706,6 +713,24 @@ async function recordQueries(siteRoot) {
       excerpts.set(name, { maxLength: decl.excerpt?.maxLength || 160, field: decl.excerpt?.field || null })
     }
     const local = entries.filter(([, d]) => d.url === undefined && d.schema)
+
+    // ⭐ A LABEL GIVEN PER LANGUAGE (`records/folder.yml`, 2026-09-28) is answered per language:
+    // the site's own when its data was compiled (`query-processor.js`), and every other one here,
+    // from the same placements the compile read — so the two cannot place a label differently.
+    const pool = await readEntityPool(siteRoot)
+    const folderCfg = await readRecordsConfig(siteRoot, { dir: pool.dir })
+    if (!folderCfg.error) {
+      const { placements } = resolveFolder(folderCfg.entries, pool.entities, { dir: pool.dir })
+      const bySchema = groupPoolBySchema(pool.entities)
+      for (const [name, decl] of local) {
+        const byName = new Map()
+        for (const entity of bySchema.get(decl.schema) || []) {
+          const label = placements.get(entity.id)?.label
+          if (isPlainObject(label)) byName.set(String(entity.slug), label)
+        }
+        if (byName.size) labels.set(name, byName)
+      }
+    }
     const resolved = (await resolveRecordSchemas(siteRoot, local.map(([, d]) => d.schema), { siteYml })).schemas
     for (const [name, decl] of entries) schemas.set(name, (decl.schema && resolved[decl.schema]) || null)
 
@@ -740,7 +765,7 @@ async function recordQueries(siteRoot) {
     // No resolvable config — every record keys by its query name, which is what
     // the extractor did before records existed.
   }
-  return { poolDirs, schemas, models, targets, excerpts }
+  return { poolDirs, schemas, models, targets, excerpts, labels, defaultLocale }
 }
 
 /** A site's `site.yml`, or `{}`. */
@@ -979,7 +1004,7 @@ export async function buildLocalizedRecords(siteRoot, options = {}) {
   // simply miss and every string falls back to its source. (This was missing for
   // a while and the failure was swallowed by the per-file catch below — the build
   // stayed green while nothing was translated.)
-  const { poolDirs, schemas: dataSchemas, models, targets, excerpts } = await recordQueries(siteRoot)
+  const { poolDirs, schemas: dataSchemas, models, targets, excerpts, labels, defaultLocale } = await recordQueries(siteRoot)
 
   const outputs = {}
   // Reported rather than only logged — see the catch below.
@@ -1058,7 +1083,12 @@ export async function buildLocalizedRecords(siteRoot, options = {}) {
               ? await translateItemAsync(record, recordDir, translations, schema, recordOptions)
               : record
             if (isPlainObject(record)) wholes.set(recordHandle(record), { source: record, translated: translatedRecord })
-            const written = dataSchema && isPlainObject(translatedRecord) ? storedFromMerged(dataSchema, translatedRecord) : translatedRecord
+            const written = relabel(
+              dataSchema && isPlainObject(translatedRecord) ? storedFromMerged(dataSchema, translatedRecord) : translatedRecord,
+              labels.get(queryName),
+              locale,
+              defaultLocale
+            )
             await mkdir(localeRecordsDir, { recursive: true })
             await writeFile(join(localeRecordsDir, name), JSON.stringify(written, null, 2))
           } catch (err) {
@@ -1077,7 +1107,8 @@ export async function buildLocalizedRecords(siteRoot, options = {}) {
         )
 
         const destPath = join(localeDataDir, file)
-        await writeFile(destPath, JSON.stringify(translatedItems, null, 2))
+        const labelled = translatedItems.map((item) => relabel(item, labels.get(queryName), locale, defaultLocale))
+        await writeFile(destPath, JSON.stringify(labelled, null, 2))
         outputs[locale][queryName] = destPath
       } catch (err) {
         // ⛔ A FAILURE HERE USED TO BE A `console.warn` AND NOTHING ELSE, and it
@@ -1278,7 +1309,7 @@ export async function translateRecordData(items, queryName, siteRoot, options =
   if (!Array.isArray(items) && !one) return items
 
   const schema = await resolveSchema(queryName, siteRoot)
-  const { poolDirs, schemas: dataSchemas, models, targets, excerpts } = await recordQueries(siteRoot)
+  const { poolDirs, schemas: dataSchemas, models, targets, excerpts, labels, defaultLocale } = await recordQueries(siteRoot)
   const recordDir = poolDirs.get(queryName) ?? queryName
   const recordOptions = {
     locale,
@@ -1305,8 +1336,35 @@ export async function translateRecordData(items, queryName, siteRoot, options =
     records.map((item) => translateItemAsync(item, recordDir, translations, schema, { ...recordOptions, whole: wholes.get(recordHandle(item)) }))
   )
 
-  if (!one) return translated
-  return dataSchema && isPlainObject(translated[0]) ? storedFromMerged(dataSchema, translated[0]) : translated[0]
+  const labelsOf = labels.get(queryName)
+  if (!one) return translated.map((item) => relabel(item, labelsOf, locale, defaultLocale))
+  return relabel(
+    dataSchema && isPlainObject(translated[0]) ? storedFromMerged(dataSchema, translated[0]) : translated[0],
+    labelsOf,
+    locale,
+    defaultLocale
+  )
+}
+
+/**
+ * A record in one language, with its entry's label in that language: `$label` as the label a
+ * folder entry gives per language answers it there (`entry-label.js::labelIn`), and no `$label`
+ * when it gives none of that language's chain. A record whose entry gives one text keeps the
+ * `$label` its compile gave it.
+ *
+ * @param {*} record - a list item or a record's own file, with its `$name`
+ * @param {Map<string, Object>|undefined} labelsOf - the query's labels per language, by record name
+ * @param {string} locale
+ * @param {string|null} defaultLocale
+ */
+function relabel(record, labelsOf, locale, defaultLocale) {
+  if (!labelsOf || !isPlainObject(record) || record.$name === undefined) return record
+  const label = labelsOf.get(String(record.$name))
+  if (!label) return record
+  const text = labelIn(label, locale, defaultLocale)
+  if (text) return { ...record, $label: text }
+  const { $label: _none, ...rest } = record
+  return rest
 }
 
 // ---------------------------------------------------------------------------

package/src/resolve-data-schema.js

@@ -39,6 +39,7 @@ import { readFile } from 'node:fs/promises'
 import { existsSync, readdirSync, statSync } from 'node:fs'
 import { join, resolve, isAbsolute, extname, basename } from 'node:path'
 import { dataRefOf } from '@uniweb/core/data-keys'
+import { SYSTEM_RECORD_SCHEMAS } from '@uniweb/schemas/system'
 import { pathToFileURL } from 'node:url'
 import { createRequire } from 'node:module'
 import yaml from 'js-yaml'
@@ -138,10 +139,17 @@ export async function resolveSchemaRef(ref, { srcDir, aliases }) {
     return validateAndNormalizeSchema(await loadSchemaFile(file), ref)
   }
 
+  // ⭐ THE SYSTEM MODELS A SITE'S RECORDS MAY NAME — `@uniweb/link` — resolve from the build's own
+  // copy (`@uniweb/schemas/system`), whatever the foundation holds: a site with no backend builds,
+  // validates and renders a link record with it. Every other `@uniweb/` name is platform plumbing,
+  // never a data-schema source. (The whole scope was refused until 2026-09-28.)
   if (scope === RESERVED_SYSTEM_SCOPE) {
+    const system = SYSTEM_RECORD_SCHEMAS[name]
+    if (system) return validateAndNormalizeSchema(system, ref)
+    const allowed = Object.keys(SYSTEM_RECORD_SCHEMAS).map((n) => `'@${scope}/${n}'`).join(', ')
     throw new Error(
-      `'@${scope}' is the reserved platform system namespace and is not a data-schema source. ` +
-        `Use '@std/${name}' for the shared standard schemas.`
+      `'@${scope}' is the reserved platform system namespace: the only data schemas a site's records ` +
+        `may name in it are ${allowed}. Use '@std/${name}' for the shared standard schemas.`
     )
   }
 

package/src/site/entity-pool.js

@@ -172,6 +172,16 @@ export function resolveRecordsDir(siteRoot, paths) {
 /** Source extensions a record file may have. Mirrors the sync-lane reader. */
 export const ENTITY_EXTENSIONS = new Set(['.md', '.yml', '.yaml', '.json', '.bib'])
 
+/**
+ * ⭐ WHERE THE FILE ITSELF IS THE RECORD — `<records>/uniweb/file/`, `@uniweb/file` (2026-09-28
+ * [Diego]). Any file placed there, of any type, is a record named by its stem, and nothing in it is
+ * read: a `.yml` there is a file to deliver, not a record's data. What the folder says about it — its
+ * label and tags — is its `folder.yml` entry.
+ */
+export const FILE_RECORD_DIRS = Object.freeze(['uniweb', 'file'])
+const isFileRecordDir = (dirs) =>
+  dirs.length === 2 && dirs[0] === FILE_RECORD_DIRS[0] && dirs[1] === FILE_RECORD_DIRS[1]
+
 const isHidden = (name) => name.startsWith('_') || name.startsWith('.')
 
 /**
@@ -267,6 +277,8 @@ export async function readEntityPool(siteRoot, opts = {}) {
 
   const entities = []
   const errors = []
+  // A file record is named by its stem, so two files of one stem cannot both be one.
+  const fileStems = new Map()
 
   const walk = async (dir, dirs) => {
     let listing
@@ -299,7 +311,8 @@ export async function readEntityPool(siteRoot, opts = {}) {
       // The folder's organization, not a record — see the header.
       if (dirs.length === 0 && e.name === FOLDER_YML) continue
       const ext = extname(e.name).toLowerCase()
-      if (!ENTITY_EXTENSIONS.has(ext)) continue
+      const fileRecord = isFileRecordDir(dirs)
+      if (!fileRecord && !ENTITY_EXTENSIONS.has(ext)) continue
       if (dirs.length === 0) {
         errors.push(
           `${rel}/${e.name} sits directly in \`${rel}/\`, which names no model. ` +
@@ -314,7 +327,20 @@ export async function readEntityPool(siteRoot, opts = {}) {
       // DATE (`2026-03-…`), and the two are indistinguishable by shape, so
       // consuming one into the record's name mangles the other. A number is read
       // to SORT by (`compareByNumericPrefix`) and never to rename.
-      const slug = basename(e.name, ext)
+      // The extension is cut as written: `ext` is lowercased to be compared, and `basename` cuts
+      // only an exact suffix — so `Scan.PDF` was the record "Scan.PDF" until 2026-09-28.
+      const slug = basename(e.name, extname(e.name))
+      if (fileRecord) {
+        const first = fileStems.get(slug)
+        if (first) {
+          errors.push(
+            `${rel}/${dirs.join('/')}/${e.name}: a file record is named by its file, and ${first} is ` +
+              `named "${slug}" too — rename one of them. This one is not a record until then.`
+          )
+          continue
+        }
+        fileStems.set(slug, e.name)
+      }
       entities.push({
         id: [...dirs, slug].join('/'),
         schema: schemaForPoolDirs(dirs),
@@ -325,6 +351,7 @@ export async function readEntityPool(siteRoot, opts = {}) {
         poolPath: [...dirs, e.name].join('/'),
         absPath: full,
         ext,
+        ...(fileRecord ? { fileRecord: true } : {}),
       })
     }
   }

package/src/site/entry-label.js

@@ -0,0 +1,110 @@
+// A folder entry's `label` — what an entry is called in its folder — in its two forms, and the one
+// rule for which text a language gets. Every lane that touches a label reads it here: the authored
+// file (`records-config.js`), the push (`uwx/folder.js`), the pull (`uwx/records-project.js`) and
+// the static lane (`query-processor.js` for the site's language, `i18n/records.js` for the others).
+//
+// ⭐ A LABEL KEEPS EVERY LANGUAGE IT HOLDS [Diego, 2026-09-28]. `records/folder.yml` writes it as one
+// text — the site's default language — or as one text per language, `{ en: …, fr: … }`. The form
+// is framework's to choose; a map of languages is the start. ⛔ Until then the file held the
+// default language only: a pull dropped a label's other languages, and the next push sent the one
+// it had kept, so a label translated in an editor lost its translations on a round trip.
+//
+// On the wire a label is always a map of languages (`{ <locale>: text }`); a backend may also hold
+// one plain text for every language, and a pull reads that too.
+
+/** A text, as YAML may type one (`2024` is a number): a non-empty trimmed string, or null. */
+function textOf(value) {
+  if (typeof value !== 'string' && typeof value !== 'number') return null
+  const text = String(value).trim()
+  return text || null
+}
+
+const isPlainObject = (value) => Boolean(value) && typeof value === 'object' && !Array.isArray(value)
+
+/**
+ * A label as an author writes it in `records/folder.yml`, normalized: one text, or a map of
+ * languages to texts — an empty one of either is no label.
+ *
+ * @param {*} value - the entry's `label:`
+ * @returns {{ label: string|Object<string,string>|null } | { error: string }}
+ */
+export function readLabel(value) {
+  if (value === undefined || value === null) return { label: null }
+  if (typeof value === 'string' || typeof value === 'number') return { label: textOf(value) }
+  if (!isPlainObject(value)) return { error: 'is neither a text nor one text per language' }
+  const label = {}
+  for (const [locale, text] of Object.entries(value)) {
+    if (!locale.trim()) return { error: 'names a language with no code' }
+    if (text === undefined || text === null) continue
+    if (typeof text !== 'string' && typeof text !== 'number') {
+      return { error: `gives \`${locale}\` something that is not text` }
+    }
+    const t = textOf(text)
+    if (t) label[locale.trim()] = t
+  }
+  return { label: Object.keys(label).length ? label : null }
+}
+
+/**
+ * A label as the wire carries it — a map of languages. One text is the source language's.
+ *
+ * @param {string|Object<string,string>} label - as `readLabel` returns it
+ * @param {string} sourceLocale - the site's default language
+ * @returns {Object<string,string>}
+ */
+export function labelOnWire(label, sourceLocale) {
+  if (isPlainObject(label)) return { ...label }
+  return { [sourceLocale]: String(label) }
+}
+
+/**
+ * A label as `records/folder.yml` holds it, from what a store holds: one text when it holds the
+ * source language's alone — the form an author writes most — and every language it holds
+ * otherwise, the source language first. Null when it holds no text.
+ *
+ * @param {*} stored - the entry's `label` off the wire: a map of languages, or one text
+ * @param {string} sourceLocale - the site's default language
+ * @returns {string|Object<string,string>|null}
+ */
+export function labelForFile(stored, sourceLocale) {
+  if (stored === undefined || stored === null) return null
+  if (!isPlainObject(stored)) return textOf(stored)
+  const texts = Object.entries(stored)
+    .map(([locale, text]) => [locale, textOf(text)])
+    .filter(([, text]) => text)
+  if (texts.length === 0) return null
+  if (texts.length === 1 && texts[0][0] === sourceLocale) return texts[0][1]
+  // The source language first, then the others as stored.
+  texts.sort(([a], [b]) => (a === sourceLocale ? -1 : b === sourceLocale ? 1 : 0))
+  return Object.fromEntries(texts)
+}
+
+/** `fr-CA` → `fr`; a language with no region is its own base. */
+const baseOf = (locale) => (typeof locale === 'string' ? locale.split(/[-_]/)[0] : null)
+
+/**
+ * The text a language gets of a label: that language, else its base language (`fr-CA` → `fr`),
+ * else the site's default language and its base; else none — as a records service answers `$label`
+ * in the read's language and not at all when the label holds none of its chain. One text is every
+ * language's.
+ *
+ * With no language known at all (a caller that did not say), the first text the label holds.
+ *
+ * @param {string|Object<string,string>|null|undefined} label
+ * @param {string|null} locale - the language being answered
+ * @param {string|null} [defaultLocale] - the site's default language
+ * @returns {string|null}
+ */
+export function labelIn(label, locale, defaultLocale = null) {
+  if (label === undefined || label === null) return null
+  if (!isPlainObject(label)) return textOf(label)
+  const chain = [locale, baseOf(locale), defaultLocale, baseOf(defaultLocale)].filter(Boolean)
+  for (const code of chain) {
+    const text = textOf(label[code])
+    if (text) return text
+  }
+  if (!locale && !defaultLocale) {
+    for (const text of Object.values(label)) if (textOf(text)) return textOf(text)
+  }
+  return null
+}

package/src/site/fetch-shapes.js

@@ -65,6 +65,14 @@ const RETIRED_KEYS = ['merge']
  * The declaration as an author would have written it — the wire's resolved form
  * minus what the build derived, and minus a retired key the build would refuse.
  *
+ * ⭐ `as` EQUAL TO THE QUERY NAME IS THE DEFAULT, so it is dropped too: the parse fills
+ * it (`data-fetcher.js`, `as: fetch.as || fetch.query`) and a fetch's key is "its
+ * query's name unless the author wrote another" (`@uniweb/core/data-keys`), so writing
+ * it back changes nothing but the file. ⛔ Until 2026-09-28 it was kept on a `fetch:`
+ * object while `queryNamesOf` already dropped it for the `query:` shorthand, so a round
+ * trip of `fetch: { query: posts, limit: 3 }` came back with `as: posts` added. An `as`
+ * naming another key is the author's, and stays.
+ *
  * @param {object} fetch a `fetch:` declaration off the sync wire
  * @returns {object} the same declaration, safe to write into authored config
  */
@@ -75,6 +83,7 @@ export function authorableFetch(fetch) {
   const out = {}
   for (const [k, v] of Object.entries(fetch)) {
     if (drop.includes(k)) continue
+    if (shape === 'query' && k === 'as' && v === fetch.query) continue
     out[k] = v
   }
   return out

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 ?? '' }