@uniweb/build 0.73.0 → 0.73.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@uniweb/build",
-  "version": "0.73.0",
+  "version": "0.73.2",
   "description": "Build tooling for the Uniweb Component Web Platform",
   "type": "module",
   "exports": {
@@ -57,11 +57,11 @@
     "js-yaml": "^4.1.0",
     "sharp": "^0.35.3",
     "yaml": "^2.5.0",
-    "@uniweb/content-reader": "^1.2.7",
+    "@uniweb/schemas": "^0.9.3",
     "@uniweb/content-writer": "^0.3.4",
     "@uniweb/projections": "^0.7.11",
-    "@uniweb/schemas": "^0.9.1",
     "@uniweb/semantic-parser": "^1.4.1",
+    "@uniweb/content-reader": "^1.2.7",
     "@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/prerender.js

@@ -32,14 +32,34 @@ import { FONT_LINKS_MARKER } from './site/head-markers.js'
 import { getAdapter } from './hosts/index.js'
 import { detectCiContext } from './hosts/detect-ci-context.js'
 import { stripBasePath } from './site/extension-urls.js'
+import { isSiteRelative, resolveExtensionDist } from './site/emit-extensions.js'
 
 /**
- * Resolve an extension URL to a filesystem path for prerender.
+ * Resolve an extension URL to the file prerender imports.
  * Browser URLs like "/effects/entry.js" need mapping to local files.
  *
+ * ⭐ AN EXTENSION IS IMPORTED FROM ITS OWN BUILD, as the primary foundation is
+ * (`<foundation>/dist/entry.js`, in prerenderSite). A foundation build leaves its
+ * externals — `@uniweb/core`, `react`, `react/jsx-runtime` — as bare imports, and
+ * Node resolves them from where the FILE sits: inside the extension's own
+ * package, which depends on them.
+ *
+ * ⛔ Not from the copy the site build emits into `dist/` (site/emit-extensions.js).
+ * That copy is the browser's, which resolves the same imports through the page's
+ * import map; here it sits under the site package, which need not depend on
+ * `@uniweb/core` at all. It was the first candidate until 2026-09-28 — an order
+ * written when nothing put a file there — and once the build began emitting one
+ * (2026-08-05), every workspace extension failed here with "Cannot find package
+ * '@uniweb/core'", and the static HTML carried `Component not found` where its
+ * sections belonged until the page ran in the browser.
+ *
  * Resolution order:
- * 1. dist directory (post-build copy target, e.g., site/dist/effects/entry.js)
- * 2. Project root with dist subdir (dev layout, e.g., project/effects/dist/entry.js)
+ * 1. The extension's own build — `<project>/<name>/dist/` or
+ *    `<project>/extensions/<name>/dist/` — found by the emitter's lookup
+ *    (`resolveExtensionDist`), so the two lanes find the same build.
+ * 2. A file in the site's dist, for an extension no workspace package builds (a
+ *    pre-built module placed in `public/`). Its bare imports resolve only where
+ *    the site's own dependencies carry them.
  * 3. Original URL (absolute or remote — let import() handle it)
  */
 export function resolveExtensionPath(url, distDir, projectRoot, base) {
@@ -50,32 +70,18 @@ export function resolveExtensionPath(url, distDir, projectRoot, base) {
   // so a payload produced before this change still resolves.
   url = stripBasePath(url, base)
 
-  // Only resolve URLs that look like root-relative paths
-  if (url.startsWith('/')) {
-    // Try dist directory first (production: files copied to site/dist/)
-    const distPath = join(distDir, url)
-    if (existsSync(distPath)) return distPath
-
-    // Workspace layouts: "/effects/entry.js" → "<pkg>/dist/entry.js", checked
-    // both at the project root and under an `extensions/` parent — the standard
-    // multi-foundation layout puts extensions in `extensions/<name>/`, so the
-    // bare-root candidate alone misses the built module and prerender can't load
-    // the extension.
-    const parts = url.slice(1).split('/')
-    if (parts.length >= 2) {
-      const pkgName = parts[0]
-      const rest = parts.slice(1).join('/')
-      const candidates = [
-        join(projectRoot, pkgName, 'dist', rest),
-        join(projectRoot, 'extensions', pkgName, 'dist', rest),
-      ]
-      for (const devPath of candidates) {
-        if (existsSync(devPath)) return devPath
-      }
-    }
+  // Return as-is for absolute paths or remote URLs
+  if (!isSiteRelative(url)) return url
+
+  const build = resolveExtensionDist(url, projectRoot)
+  if (build) {
+    const inBuild = join(build.distDir, build.rest)
+    if (existsSync(inBuild)) return inBuild
   }
 
-  // Return as-is for absolute paths or remote URLs
+  const inDist = join(distDir, url)
+  if (existsSync(inDist)) return inDist
+
   return url
 }
 

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/schema.js

@@ -17,7 +17,7 @@ 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 { SECTION_PARAMS } from '@uniweb/schemas/section'
+import { SECTION_PARAMS, SECTION_KEYS } from '@uniweb/schemas/section'
 import { collectSchemaRefs, buildDataSchemaMap, ownSchemaRefs } from './resolve-data-schema.js'
 import {
   composeSupports,
@@ -958,19 +958,32 @@ export function reportPlacementDeclarations(components) {
           `provides renders "Component not found".`
       )
     }
-    // A name framework reserves in a section's params whose value the component never
-    // receives — `component: false` in `@uniweb/schemas/section`, as `grid` is.
+    // A name framework reserves in a section's params: a setting of the SECTION, which framework
+    // applies — `component: false` in `@uniweb/schemas/section`. A component that declares one in
+    // its `params:` declares a setting it is never given. ⛔ Until 2026-09-28 this said the param
+    // "never receives the author's theme:" and to rename it — read as "the section loses the
+    // author's value", the opposite of what happens: the section gets it, and framework applies it.
     const params = entry.params && typeof entry.params === 'object' ? entry.params : {}
     for (const [param, reserved] of Object.entries(SECTION_PARAMS)) {
       if (reserved.component || !Object.hasOwn(params, param)) continue
       console.warn(
-        `Warning: ${name} (meta.js): a param named "${param}" never receives the author's ${param}: — framework ` +
-          `reserves it in a section's params (@uniweb/schemas/section). Rename the param.` +
+        `Warning: ${name} (meta.js): params declares "${param}", a setting of the section, not of its ` +
+          `component — framework applies an author's ${param}: to the section and never passes it to the ` +
+          `component, and an editor offers it for every section (@uniweb/schemas/section). Remove it from params:.` +
           (param === 'grid'
             ? ` To offer layouts for the child sections, declare children: { grid: [...] } and lay them out with kit's ChildGrid.`
             : '')
       )
     }
+    // …and a key of a section's frontmatter that is not a param at all (`SECTION_KEYS`): the build
+    // takes it out before the params are stored, so a param of that name is never given one.
+    for (const [key, { is }] of Object.entries(SECTION_KEYS)) {
+      if (!Object.hasOwn(params, key)) continue
+      console.warn(
+        `Warning: ${name} (meta.js): params declares "${key}", a key a section's frontmatter keeps for ` +
+          `itself — ${is} — so the component is never given it (@uniweb/schemas/section). Remove it from params:.`
+      )
+    }
   }
 }
 

package/src/site/content-collector.js

@@ -23,6 +23,7 @@
 
 import { readFile, readdir, stat } from 'node:fs/promises'
 import { resolveQueriesConfig, toConfigQueries } from './queries-config.js'
+import { isSectionKey } from '@uniweb/schemas/section'
 import { parseNumericPrefix, compareByNumericPrefix } from '../utils/numeric-prefix.js'
 import { isMarkdownFile, isIgnoredFolder } from '../utils/content-files.js'
 import { readLayoutFolder, DEFAULT_LAYOUT, layoutAreaRoute } from './layout-folder.js'
@@ -1016,9 +1017,14 @@ async function processMarkdownFile(filePath, id, siteRoot, defaultStableId = nul
     console.warn(`[content-collector] ${err.message}`)
   }
 
-  // `query`, `fetch` and `data` are never params: `query:` / `fetch:` declare the
-  // section's own data, and a leftover `data:` is refused (`declaredFetch`).
-  const { type, hidden, preset, input, props, fetch, query, data, id: frontmatterId, ...params } = frontMatter
+  // ⭐ WHAT IS NOT A PARAM is `SECTION_KEYS` (`@uniweb/schemas/section`) — the list the build's
+  // warning on a component's `params:` reads too — and `fetch`, one of the section's settings,
+  // kept on the section as a field of its own. `query:` / `fetch:` declare the section's own
+  // data, and a leftover `data:` is refused (`declaredFetch`).
+  const { type, hidden, preset, input, props, fetch, query, data, id: frontmatterId } = frontMatter
+  const params = Object.fromEntries(
+    Object.entries(frontMatter).filter(([key]) => !isSectionKey(key) && key !== 'fetch')
+  )
   // ⭐ `hidden: true` — a draft section, the page's meaning one level down: left out of a
   // published build, kept by `uniweb dev`, and synced as the section's own `hidden`
   // [Diego, 2026-09-28]. ⛔ Until then it was an ordinary param: the component received it

package/src/site/emit-extensions.js

@@ -39,6 +39,11 @@
  * Same browser/internal split the runtime's distribution channel draws, for the
  * same reason: what a visitor fetches and what a renderer needs are different
  * sets, and only one of them belongs on a public origin.
+ *
+ * ⛔ The emitted copy is the BROWSER's, and only the browser's. Prerender imports
+ * the extension from its own build (`resolveExtensionPath`), because the copy
+ * sits under the site package, where the extension's bare imports
+ * (`@uniweb/core`, `react`) do not resolve.
  */
 
 import { existsSync, readdirSync, readFileSync, statSync } from 'node:fs'
@@ -69,26 +74,31 @@ function isBrowserAsset(rel) {
 }
 
 /**
- * Locate the built `dist/` behind a site-relative extension URL.
+ * Locate the built `dist/` behind a site-relative extension URL:
+ * `/effects/entry.js` → `<project>/effects/dist/` or
+ * `<project>/extensions/effects/dist/`, with `rest` the path inside it.
  *
- * The same candidates `resolveExtensionPath` walks for prerender, kept in step
- * deliberately: if prerender can load an extension from the workspace but the
- * build cannot find it to emit, that is exactly the split that produced the
- * bug — one lane resolving it and the other not.
+ * One lookup for both lanes that need the extension's build: this emitter, which
+ * copies it into the site's output, and prerender, which imports it from where it
+ * was built (`resolveExtensionPath`). Neither can find an extension the other
+ * cannot, by construction rather than by two lists kept in step by hand.
  *
- * @returns {{ distDir: string, urlBase: string }|null}
+ * @param {string} url - a site-relative URL, with any deployment base removed
+ * @param {string} projectRoot - the directory holding the site and its extensions
+ * @returns {{ distDir: string, urlBase: string, rest: string }|null}
  */
-export function resolveExtensionDist(url, siteDir) {
+export function resolveExtensionDist(url, projectRoot) {
   const parts = url.replace(/^\//, '').split('/')
   if (parts.length < 2) return null
   const pkgName = parts[0]
-  const projectRoot = resolve(siteDir, '..')
 
   for (const candidate of [
     join(projectRoot, pkgName, 'dist'),
     join(projectRoot, 'extensions', pkgName, 'dist')
   ]) {
-    if (existsSync(candidate)) return { distDir: candidate, urlBase: pkgName }
+    if (existsSync(candidate)) {
+      return { distDir: candidate, urlBase: pkgName, rest: parts.slice(1).join('/') }
+    }
   }
   return null
 }
@@ -108,11 +118,12 @@ export function collectExtensionAssets(extensions, siteDir) {
   const emit = []
   const unresolved = []
   if (!Array.isArray(extensions)) return { emit, unresolved }
+  const projectRoot = resolve(siteDir, '..')
 
   for (const decl of extensions) {
     if (!isSiteRelative(decl)) continue // absolute URL or a ref — someone else serves it
     const url = typeof decl === 'string' ? decl : decl.url
-    const found = resolveExtensionDist(url, siteDir)
+    const found = resolveExtensionDist(url, projectRoot)
     if (!found) {
       unresolved.push(url)
       continue

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