@uniweb/build 0.65.0 → 0.66.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@uniweb/build",
-  "version": "0.65.0",
+  "version": "0.66.0",
   "description": "Build tooling for the Uniweb Component Web Platform",
   "type": "module",
   "exports": {
@@ -57,15 +57,15 @@
     "js-yaml": "^4.1.0",
     "sharp": "^0.35.3",
     "yaml": "^2.5.0",
-    "@uniweb/schemas": "^0.8.0",
-    "@uniweb/projections": "^0.7.5",
-    "@uniweb/theming": "^0.1.15",
     "@uniweb/content-writer": "^0.3.4",
     "@uniweb/content-reader": "^1.2.5",
+    "@uniweb/schemas": "^0.8.0",
+    "@uniweb/projections": "^0.7.6",
+    "@uniweb/theming": "^0.1.15",
     "@uniweb/semantic-parser": "^1.4.1"
   },
   "optionalDependencies": {
-    "@uniweb/runtime": "^0.27.7"
+    "@uniweb/runtime": "^0.27.8"
   },
   "peerDependencies": {
     "vite": "^5.0.0 || ^6.0.0 || ^7.0.0",
@@ -74,8 +74,8 @@
     "@tailwindcss/vite": "^4.0.0",
     "@vitejs/plugin-react": "^4.0.0 || ^5.0.0",
     "vite-plugin-svgr": "^4.0.0",
-    "@uniweb/core": "^0.31.0",
-    "@uniweb/runtime": "^0.27.7"
+    "@uniweb/runtime": "^0.27.8",
+    "@uniweb/core": "^0.32.0"
   },
   "peerDependenciesMeta": {
     "vite": {

package/src/i18n/records.js

@@ -361,10 +361,12 @@ function derivesExcerpt(record, whole, dataSchema, config) {
 /**
  * ⛔ A RECORD'S SYSTEM FIELDS ARE NEVER PROSE — never extracted, never translated, by
  * either path. A `$`-prefixed key at any depth is the system's (`$name`, the handle a
- * parametric page's URL names; `$uuid`), and a record's top-level `slug` and `path`
- * are its handle and its placement in `folder.yml`. Until 2026-09-14 they became
- * translation units, and a translation whose source happened to equal one rewrote it,
- * so a record's page stopped matching its URL.
+ * parametric page's URL names; `$uuid`; `$branch`, the folder a compiled list holds a
+ * record under), and a top-level `slug` is how a record's reader hands the file's name
+ * on. Until 2026-09-14 they became translation units, and a translation whose source
+ * happened to equal one rewrote it, so a record's page stopped matching its URL.
+ * ⛔ A top-level `path` was one too until 2026-09-27, when the placement it named moved to
+ * `$branch` [Diego]: a field an author names `path` is theirs, and translated as its schema says.
  *
  * @param {string|number} key - a field name (an array index is never one)
  * @param {boolean} topLevel - whether the key sits at the record's own level
@@ -372,7 +374,7 @@ function derivesExcerpt(record, whole, dataSchema, config) {
  */
 function isRecordSystemField(key, topLevel) {
   if (typeof key !== 'string') return false
-  return key.startsWith('$') || (topLevel && (key === 'slug' || key === 'path'))
+  return key.startsWith('$') || (topLevel && key === 'slug')
 }
 
 /**

package/src/prerender.js

@@ -14,7 +14,6 @@ import { pathToFileURL } from 'node:url'
 import {
   resolveDefaultLocale,
   resolveFetchConfigs,
-  joinPathCapture,
   pageRouteQuery,
   routeSelection,
   routeParamValues,
@@ -410,13 +409,14 @@ export function expandDynamicPages(pages, fetched, onProgress = () => {}, stats
       }
       for (const paramValue of values) {
 
-        // Create concrete route: /blog/:slug → /blog/my-post. Under `[...path]` the
-        // record's URL is its placement (the folder `folder.yml` put it in, carried
-        // as `path`) plus its handle — the split rule in reverse. ⛔ A FILE PATH, so
-        // decoded: the server decodes the request before looking the file up.
-        const capture = catchAll ? joinPathCapture({ dir: item.path, slug: paramValue }) : null
+        // Create concrete route: /blog/:slug → /blog/my-post, and the same under
+        // `[...path]`: a record carries no branch, so its own URL is its handle alone
+        // (ruled 2026-09-27 [Diego]), the URL its `$route` names (`fillRoutePattern`).
+        // ⛔ Until then this prefixed the record's `path`. ⛔ A FILE PATH, so decoded: the
+        // server decodes the request before looking the file up.
+        const capture = catchAll ? String(paramValue) : null
         const concreteRoute = catchAll
-          ? page.route.replace(new RegExp(`:${catchAll}\\*$`), capture)
+          ? page.route.replace(new RegExp(`:${catchAll}\\*$`), () => capture)
           : page.route.replace(`:${paramName}`, paramValue)
 
         // ⛔ TWO RECORDS, ONE ROUTE — normal the moment the route field is not

package/src/site/data-fetcher.js

@@ -88,7 +88,7 @@ export function applyWhere(items, where) {
  * `@uniweb/core`'s `evaluateQuery`, the one order of work the runtime's default
  * fetcher uses too:
  *
- *   1. the query's set — `scope` over each record's placement (`path`), `where`,
+ *   1. the query's set — `scope` over the branch each record is held with (`$branch`), `where`,
  *      `sort`, `limit`;
  *   2. the fetch's `narrow` of it — `where` (and `match`), `sort`, `limit`.
  *

package/src/site/file-transport.js

@@ -72,8 +72,9 @@ export function createFileTransport({ siteRoot, distDir = null, publicDir = 'pub
       const body = await readFile(file, 'utf8')
       return response(body, path.endsWith('.json') ? 'application/json' : 'text/plain')
     }
-    // ⚖️ Not an error here. A page can ask for a per-record file a `deferred:` query never wrote,
-    // and the step reports the outcome so the caller can see it rather than crash a build.
+    // ⚖️ Not an error here. A page can ask for a per-record file that was never written — a
+    // record this run withholds as a draft, say — and the step reports the outcome so the caller
+    // can see it rather than crash a build.
     return missing(path)
   }
 }

package/src/site/query-processor.js

@@ -58,7 +58,7 @@ import { createHash } from 'node:crypto'
 import yaml from 'js-yaml'
 import { YAML_OPTIONS } from '../utils/yaml-schema.js'
 import { parseBibtex } from '@citestyle/bibtex'
-import { DATA_DIR, withoutRouteVariables, mapQueryPaths } from '@uniweb/core'
+import { DATA_DIR, withoutRouteVariables, mapQueryPaths, BRANCH_KEY } from '@uniweb/core'
 import { applyWhere, applySort, refuseUnder, refuseOutsideLanguage, refuseQueryRoute, refuseLimit } from './data-fetcher.js'
 import { resolveAssetPath, walkContentAssets, isLocalAssetPath } from './assets.js'
 import { readEntityPool, groupPoolBySchema, poolDirsForSchema } from './entity-pool.js'
@@ -760,8 +760,8 @@ export function flatFormRefusal(where, ref, schema, misplaced) {
  * Every source file in a collection, as paths relative to the collection root —
  * `hello.md`, `2024/spring.md`, `2024/q1/notes.yml`.
  *
- * Nesting is how an author gives a collection an internal structure, and it is
- * what the `path` field and the `under` predicate address. Before this walk the
+ * Nesting is how an author organizes the files; the folder branch a record sits in, which a
+ * query's `scope:` reads, is `records/folder.yml`'s to say (`records-config.js`). Before this walk the
  * scan was a flat `readdir`, so a record in a subdirectory was not ignored with
  * a warning — it was invisible, and the site simply rendered without it.
  *
@@ -800,7 +800,7 @@ function warnDuplicateSlugs(items, queryName) {
   for (const item of items) {
     if (!item || item.$name === undefined) continue
     const name = String(item.$name)
-    const where = item.path ? `${item.path}/` : ''
+    const where = item[BRANCH_KEY] ? `${item[BRANCH_KEY]}/` : ''
     if (seen.has(name)) {
       console.warn(
         `[query-processor] Query "${queryName}" has more than one record named ` +
@@ -927,7 +927,7 @@ function pickBrief(record, keys) {
     return out
   }
   for (const [key, value] of Object.entries(record)) {
-    if (!key.startsWith('$') && !['slug', 'path', 'excerpt', 'image', 'draft'].includes(key)) out[key] = value
+    if (!key.startsWith('$') && !['slug', 'excerpt', 'image', 'draft'].includes(key)) out[key] = value
   }
   return out
 }
@@ -966,10 +966,17 @@ async function collectItems(siteDir, config, recordsRoot, basePath, locale = nul
   // BibTeX → CSL-JSON bibliography items).
   let items = await readPooledRecords(pooled, config, siteDir, recordsRoot, basePath)
 
-  // ⭐ `path` IS THE FOLDER `folder.yml` PLACED THE RECORD IN — `''` at the top —
+  // ⭐ `$branch` IS THE FOLDER `folder.yml` PLACED THE RECORD IN — `''` at the top —
   // and it is the whole reason folders exist: `scope: archive` is how a query asks
   // for a slice. Structure is query scope, not navigation.
   //
+  // ⛔ THE COMPILED FILE'S OWN KEY, NOT THE RECORD'S (ruled 2026-09-27 [Diego]): the
+  // browser evaluates `scope` over this file, so the file holds each record's branch, and
+  // no answer carries it — `@uniweb/core`'s `evaluateQuery` reads it and drops it, as a
+  // records service answers no branch. ⛔ Until then it was `path`: it reached every
+  // component, wrote over an authored field named `path`, and made a `[...path]` record's
+  // link `<branch>/<name>`.
+  //
   // ⛔ THIS WAS HARDCODED TO `''` FOR A WHILE, AND THE COMMENT SAID "until the
   // folder producer lands". It landed, and this was not revisited — so every
   // folder slice matched NOTHING on the delivery lane, silently, which is the one
@@ -979,9 +986,9 @@ async function collectItems(siteDir, config, recordsRoot, basePath, locale = nul
   // ⚠️ It stays a SCALAR. `@uniweb/core`'s `withinScope` matches strings only, so
   // an array would match nothing — one placement per record is the ruling.
   items = items.map((result, i) => {
-    const path = pooled[i] ? (config.placements?.get(pooled[i].id)?.path ?? '') : ''
-    if (Array.isArray(result)) return result.map((item) => item && { ...item, path })
-    return result && { ...result, path }
+    const branch = pooled[i] ? (config.placements?.get(pooled[i].id)?.path ?? '') : ''
+    if (Array.isArray(result)) return result.map((item) => item && { ...item, [BRANCH_KEY]: branch })
+    return result && { ...result, [BRANCH_KEY]: branch }
   })
 
   // Flatten one level: a .bib file contributes its entries individually. Every other
@@ -1053,7 +1060,8 @@ async function collectItems(siteDir, config, recordsRoot, basePath, locale = nul
   // since 2026-09-11, could select anything from it.
 
   // ⭐ EACH RECORD'S BRIEF — what its list holds: the brief's fields at the top, beside the record's
-  // own keys and what the build derives (`excerpt`, `image`, `path`). A record of a schema with no
+  // own keys, what the build derives (`excerpt`, `image`), and the branch the list holds for `scope`
+  // (`$branch`, which no answer carries). A record of a schema with no
   // brief, or of one with a single section, is its brief as it is.
   const briefOf = briefBuilder(config.dataSchema)
   if (briefOf) {
@@ -1127,7 +1135,7 @@ export async function processQueries(siteDir, queriesConfig, recordsDir, basePat
   }
 
   // ⭐ EVERY FILE IN `records/` IS A RECORD (ruled 2026-09-21 [Diego]), so every one
-  // is compiled; `records/folder.yml` only says which folder each sits in (`path`),
+  // is compiled; `records/folder.yml` only says which folder each sits in (`$branch`),
   // which is what a query's `scope` reads. ⛔ Until 2026-09-21 `records.yml`, at the
   // site root, listed the records, and an unlisted file was left out of
   // `/data/<name>.json` here.
@@ -1347,7 +1355,9 @@ export async function writeQueryFiles(siteDir, byQuery, queriesConfig = null) {
       const handle = item.$name
       if (handle === undefined || handle === null || handle === '') continue
       const filename = `${handle}.json`
-      await writeFile(join(recordsDir, filename), JSON.stringify(item[WHOLE_RECORD] ?? item, null, 2))
+      // The record's own file answers it whole, so it holds no branch (the list does, for `scope`).
+      const { [BRANCH_KEY]: _branch, ...own } = item
+      await writeFile(join(recordsDir, filename), JSON.stringify(item[WHOLE_RECORD] ?? own, null, 2))
       written.add(filename)
     }
     const pruned = await pruneOrphanedRecords(dataDir, name, written)

package/src/site/records-config.js

@@ -153,7 +153,7 @@ export async function readRecordsConfig(siteRoot, { dir } = {}) {
  *
  * ⛔ ONE PLACEMENT PER RECORD. Two entries matching one file is a hard error, not
  * a second placement. The wire could carry many-to-many — `folder.js` nests, and
- * a placement is banked by the record it references — but a record's `path` is one string:
+ * a placement is banked by the record it references — but a record's branch is one string:
  * `@uniweb/core`'s `withinScope` matches nothing that is not a string, so a record
  * with two paths would fall outside every `scope:`, silently. The records service
  * evaluates `scope` natively, so widening it is a cross-lane change to agree first,