@uniweb/build 0.66.0 → 0.66.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@uniweb/build",
-  "version": "0.66.0",
+  "version": "0.66.1",
   "description": "Build tooling for the Uniweb Component Web Platform",
   "type": "module",
   "exports": {
@@ -57,12 +57,12 @@
     "js-yaml": "^4.1.0",
     "sharp": "^0.35.3",
     "yaml": "^2.5.0",
-    "@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"
+    "@uniweb/content-writer": "^0.3.4",
+    "@uniweb/semantic-parser": "^1.4.1",
+    "@uniweb/theming": "^0.1.15"
   },
   "optionalDependencies": {
     "@uniweb/runtime": "^0.27.8"
@@ -74,8 +74,8 @@
     "@tailwindcss/vite": "^4.0.0",
     "@vitejs/plugin-react": "^4.0.0 || ^5.0.0",
     "vite-plugin-svgr": "^4.0.0",
-    "@uniweb/runtime": "^0.27.8",
-    "@uniweb/core": "^0.32.0"
+    "@uniweb/core": "^0.32.0",
+    "@uniweb/runtime": "^0.27.8"
   },
   "peerDependenciesMeta": {
     "vite": {

package/src/site/query-processor.js

@@ -932,6 +932,16 @@ function pickBrief(record, keys) {
   return out
 }
 
+// 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) {
+  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
+  return Object.keys(out).length ? out : null
+}
+
 // A query's records in folder-tree order (`folderTreeOrder`), before anything reads them — so
 // `where`, `sort` (stable) and `limit` start from the order a records service answers in.
 function inFolderOrder(pooled, rank) {
@@ -985,10 +995,20 @@ 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.
+  //
+  // ⭐ AND WHAT THE FOLDER SAYS ABOUT THE RECORD — its entry's `tags` and `label` — rides
+  // beside it as `$tags` and `$label`, in its list and in its own file, as a records service
+  // answers them (ruled 2026-09-27 [Diego]). Absent when the entry says none.
   items = items.map((result, i) => {
-    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 }
+    const placed = pooled[i] ? config.placements?.get(pooled[i].id) : null
+    const said = entryKeys(placed)
+    const at = (item) => {
+      if (!item) return item
+      const out = { ...item, ...said, [BRANCH_KEY]: placed?.path ?? '' }
+      if (said && out[WHOLE_RECORD]) out[WHOLE_RECORD] = { ...out[WHOLE_RECORD], ...said }
+      return out
+    }
+    return Array.isArray(result) ? result.map(at) : at(result)
   })
 
   // Flatten one level: a .bib file contributes its entries individually. Every other

package/src/site/records-config.js

@@ -164,9 +164,25 @@ export async function readRecordsConfig(siteRoot, { dir } = {}) {
  * @param {object} [opts]
  * @param {string} [opts.dir] - the records directory as written, for messages
  * @returns {{ nodes: Array, placements: Map, errors: string[], warnings: string[] }}
- *   `nodes` is the folder tree — the declared sub-folders in file order, then every
- *   record no sub-folder names; `placements` maps EVERY record's id to its
- *   `{ entity, path, slug }`, `path` being `''` at the top of the folder.
+ *   `nodes` is the folder tree — the declared entries in file order, then every
+ *   record no entry names; `placements` maps EVERY record's id to its
+ *   `{ entity, path, slug, tags?, label? }`, `path` being `''` at the top of the folder.
+ *
+ * ⭐ WHAT THE FOLDER SAYS ABOUT A RECORD — its entry's `tags` and `label` (ruled
+ * 2026-09-27 [Diego]). A record's entry is a path, or `{ path, tags?, label? }`:
+ *
+ *     - folder: team
+ *       records:
+ *         - team/grace.md
+ *         - path: team/ada.md
+ *           tags: [staff, featured]
+ *           label: Ada Lovelace
+ *
+ * They are the ENTRY's, not the record's — a backend keeps them on the folder entry and
+ * answers them beside the record as `$tags` and `$label`, and so does the static lane.
+ * Tags keep the order written. At the top level an entry is allowed only when it says
+ * one of them: a bare path there would claim to place a record the directory already
+ * placed.
  */
 export function resolveFolder(entries, pool, { dir = RECORDS_DIR } = {}) {
   // The file as the author sees it, for every message below.
@@ -187,7 +203,7 @@ export function resolveFolder(entries, pool, { dir = RECORDS_DIR } = {}) {
     byRelPath.set(e.poolPath, e)
   }
 
-  const place = (entity, pathSegs, where) => {
+  const place = (entity, pathSegs, where, said = null) => {
     const key = entity.id
     const prior = claimedBy.get(key)
     if (prior) {
@@ -200,60 +216,94 @@ export function resolveFolder(entries, pool, { dir = RECORDS_DIR } = {}) {
     claimedBy.set(key, where)
     const slug = slugForEntity(entity)
     const path = pathSegs.join('/')
-    placements.set(key, { entity, path, slug })
-    return { kind: 'ref', name: slug, $entityId: key }
+    placements.set(key, { entity, path, slug, ...said })
+    return { kind: 'ref', name: slug, $entityId: key, ...said }
+  }
+
+  // The records one path names — a file, or a pattern's matches — placed where the entry sits.
+  const placePath = (raw, pathSegs, where, said = null) => {
+    const pattern = typeof raw === 'string' ? raw.trim() : ''
+    if (!pattern) {
+      errors.push(`${file}: ${where} ${said ? 'has an empty `path:`' : 'is an empty string'}.`)
+      return []
+    }
+    if (!isPattern(pattern)) {
+      const hit = byRelPath.get(pattern)
+      if (!hit) {
+        errors.push(
+          `${file}: ${where} names "${pattern}", which is not in ${dir}/. ` +
+            `A path is relative to ${dir}/, extension included.`
+        )
+        return []
+      }
+      const leaf = place(hit, pathSegs, where, said)
+      return leaf ? [leaf] : []
+    }
+    // ⛔ A PATTERN MATCHING NOTHING IS AN ERROR. `artcle/*.md` is the old
+    // empty-branch defect respelled, and it produced a real, reachable, empty
+    // path with no warning.
+    const matches = [...byRelPath.entries()]
+      .filter(([rel]) => matchEntityPattern(pattern, rel))
+      .map(([, e]) => e)
+    if (matches.length === 0) {
+      errors.push(
+        `${file}: ${where} pattern "${pattern}" matches no record in ${dir}/. ` +
+          `Check the schema folder name and the extension.`
+      )
+      return []
+    }
+    // Matches sort alphanumerically by filename, numeric-aware — so `1-`, `2-`,
+    // `10-` order as written rather than as strings, and `2025-…` precedes
+    // `2026-…`. Ordering only: the number never leaves the name.
+    matches.sort((a, b) => compareByNumericPrefix(a.slug, b.slug))
+    return matches.map((e) => place(e, pathSegs, where, said)).filter(Boolean)
+  }
+
+  // An entry's `tags` and `label` — text, as YAML may type a tag or a label a number
+  // (`2024`). Tags keep the order written; an empty one is dropped. Null when one is
+  // not text (said).
+  const saidOf = (entry, where) => {
+    const said = {}
+    if (entry.tags !== undefined && entry.tags !== null) {
+      const tags = []
+      for (const tag of Array.isArray(entry.tags) ? entry.tags : [entry.tags]) {
+        if (typeof tag !== 'string' && typeof tag !== 'number') {
+          errors.push(`${file}: ${where} has a tag that is not text: ${JSON.stringify(tag)}. Write each tag as a word.`)
+          return null
+        }
+        const text = String(tag).trim()
+        if (text) tags.push(text)
+      }
+      if (tags.length) said.tags = tags
+    }
+    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.`)
+        return null
+      }
+      const label = String(entry.label).trim()
+      if (label) said.label = label
+    }
+    return said
   }
 
   const resolveEntry = (entry, pathSegs, index, trail) => {
     const where = `entry ${trail}[${index}]`
 
     if (typeof entry === 'string') {
-      const pattern = entry.trim()
       // ⛔ A PATH AT THE TOP LEVEL SELECTED RECORDS until 2026-09-21 — it was how a
       // file became one. Every file in the directory is a record now, so the line
       // would claim to choose while choosing nothing: refused, with the reason.
       if (pathSegs.length === 0) {
         errors.push(
-          `${file}: ${where} ("${pattern}") lists records at the top level. Every file in ` +
-            `${dir}/ is a record already — ${file} only sorts records into folders. ` +
+          `${file}: ${where} ("${entry.trim()}") lists records at the top level. Every file in ` +
+            `${dir}/ is a record already — ${file} only sorts records into folders, and says ` +
+            `what a folder knows about a record (\`tags:\`, \`label:\`). ` +
             `Remove the entry, or put it under a \`folder:\`.`
         )
         return []
       }
-      if (!pattern) {
-        errors.push(`${file}: ${where} is an empty string.`)
-        return []
-      }
-      if (!isPattern(pattern)) {
-        const hit = byRelPath.get(pattern)
-        if (!hit) {
-          errors.push(
-            `${file}: ${where} names "${pattern}", which is not in ${dir}/. ` +
-              `A path is relative to ${dir}/, extension included.`
-          )
-          return []
-        }
-        const leaf = place(hit, pathSegs, where)
-        return leaf ? [leaf] : []
-      }
-      // ⛔ A PATTERN MATCHING NOTHING IS AN ERROR. `artcle/*.md` is the old
-      // empty-branch defect respelled, and it produced a real, reachable, empty
-      // path with no warning.
-      const matches = [...byRelPath.entries()]
-        .filter(([rel]) => matchEntityPattern(pattern, rel))
-        .map(([, e]) => e)
-      if (matches.length === 0) {
-        errors.push(
-          `${file}: ${where} pattern "${pattern}" matches no record in ${dir}/. ` +
-            `Check the schema folder name and the extension.`
-        )
-        return []
-      }
-      // Matches sort alphanumerically by filename, numeric-aware — so `1-`, `2-`,
-      // `10-` order as written rather than as strings, and `2025-…` precedes
-      // `2026-…`. Ordering only: the number never leaves the name.
-      matches.sort((a, b) => compareByNumericPrefix(a.slug, b.slug))
-      return matches.map((e) => place(e, pathSegs, where)).filter(Boolean)
+      return placePath(entry, pathSegs, where)
     }
 
     if (!entry || typeof entry !== 'object' || Array.isArray(entry)) {
@@ -263,6 +313,30 @@ export function resolveFolder(entries, pool, { dir = RECORDS_DIR } = {}) {
       return []
     }
 
+    // ⭐ A RECORD'S ENTRY WITH WHAT THE FOLDER SAYS ABOUT IT — `{ path, tags?, label? }`.
+    if (entry.path !== undefined) {
+      const extra = Object.keys(entry).filter((k) => !['path', 'tags', 'label'].includes(k))
+      if (extra.length) {
+        errors.push(
+          `${file}: ${where} is a record's entry (\`path:\`), which takes \`tags:\` and \`label:\` — ` +
+            `not ${extra.map((k) => `\`${k}:\``).join(', ')}.` +
+            (extra.includes('folder') || extra.includes('records') ? ' A folder is its own entry, `folder:`.' : '')
+        )
+        return []
+      }
+      const said = saidOf(entry, where)
+      if (!said) return []
+      if (pathSegs.length === 0 && !said.tags && !said.label) {
+        errors.push(
+          `${file}: ${where} ("${String(entry.path).trim()}") lists a record at the top level and says ` +
+            `nothing about it. Every file in ${dir}/ sits at the top already — give it \`tags:\` or a ` +
+            `\`label:\`, or remove the entry.`
+        )
+        return []
+      }
+      return placePath(entry.path, pathSegs, where, said)
+    }
+
     if (entry.folder !== undefined) {
       // ⚠️ COERCED, because YAML types a bare `2024` as a NUMBER — and a folder
       // named for a year is the single most likely one anybody writes. Both the
@@ -298,6 +372,13 @@ 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)
+      // 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) {
+        const said = saidOf({ tags: entry.tags }, where)
+        if (!said) return []
+        if (said.tags) branch.tags = said.tags
+      }
       const kids = Array.isArray(entry.records) ? entry.records : []
       if (kids.length === 0) {
         warnings.push(
@@ -328,8 +409,8 @@ export function resolveFolder(entries, pool, { dir = RECORDS_DIR } = {}) {
     errors.push(
       `${file}: ${where} has no recognized kind. ` +
         (pathSegs.length
-          ? `Inside a folder, a path names records; anything else says \`folder:\`.`
-          : `An entry is a \`folder:\` — its \`records:\` are paths under ${dir}/.`)
+          ? `Inside a folder, a path names records — or \`path:\` with its \`tags:\` and \`label:\`; anything else says \`folder:\`.`
+          : `An entry is a \`folder:\` — its \`records:\` are paths under ${dir}/ — or a record's \`path:\` with its \`tags:\` or \`label:\`.`)
     )
     return []
   }

package/src/uwx/folder.js

@@ -7,11 +7,12 @@
 //   - `contents` is the self-nesting tree (an array), nesting via `$children` — the
 //     same mechanism site-content pages/sections use. Each node holds REFERENCES,
 //     never content:
-//       - a LEAF references one record entity: `{ kind: 'ref', name, entry }` —
+//       - a LEAF references one record entity: `{ kind: 'ref', name, entry, label?, tags? }` —
 //         `entry: { schema, entity: <uuid> }` once the record was minted (back-filled
 //         into its file), or `entry: { $ref: "<$id>" }` while brand-new (resolved
-//         within this payload).
-//       - a BRANCH is a sub-folder: `{ kind: 'branch', name, label?, $children }`.
+//         within this payload); `label` (a localized map) and `tags` are what
+//         `records/folder.yml` says about the record, since 2026-09-27.
+//       - a BRANCH is a sub-folder: `{ kind: 'branch', name, label?, tags?, $children }`.
 //
 // ⭐ A LEAF'S `name` IS ITS RECORD'S HANDLE — the slug, the records service's `$name` —
 // and a branch's `name` is the segment a query's `scope:` names. `label` is a branch's
@@ -99,6 +100,7 @@ function contentsFromNodes(nodes, byEntityId, missing, sourceLocale) {
       // 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) }
+      if (Array.isArray(node.tags) && node.tags.length) branch.tags = [...node.tags]
       branch.$children = contentsFromNodes(node.$children, byEntityId, missing, sourceLocale)
       out.push(branch)
       continue
@@ -108,7 +110,13 @@ function contentsFromNodes(nodes, byEntityId, missing, sourceLocale) {
       missing.push(node.$entityId)
       continue
     }
-    out.push(refLeaf(entity))
+    const leaf = refLeaf(entity)
+    // ⭐ 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 (Array.isArray(node.tags) && node.tags.length) leaf.tags = [...node.tags]
+    out.push(leaf)
   }
   return out
 }

package/src/uwx/records-project.js

@@ -493,7 +493,9 @@ export function declarationsToQueriesYml({ document, siteRoot, scope, ...rest })
  * there — so `folder.yml` carries the branches and the records placed in them, and
  * a folder with no branches is a site with no `folder.yml`: a local one is REMOVED
  * (it could only describe sub-folders the backend's folder no longer has). No state
- * of the file removes a record, so this cannot empty anything.
+ * of the file removes a record, so this cannot empty anything. ⭐ The one exception,
+ * since 2026-09-27: a record whose entry has `tags` or a `label` is written wherever it
+ * sits, as `{ path, tags?, label? }`, since only `folder.yml` can say them.
  *
  * ⛔ A PULL THAT CARRIED NO FOLDER, or one with a placed record that was not written
  * locally, leaves the file alone: it has nothing true to write.
@@ -524,22 +526,34 @@ export function folderToFolderYml({ folderDoc, siteRoot, poolPathByUuid, sourceL
         // does not caption its rows. On the wire the label is a localized map;
         // folder.yml carries the source-locale string (a bare string passes).
         if (node.label !== undefined) entry.label = unwrapLocalized(node.label, sourceLocale)
+        if (Array.isArray(node.tags) && node.tags.length) entry.tags = node.tags.map(String)
         entry.records = walk(node.$children, true)
         out.push(entry)
         continue
       }
       const uuid = node.entry?.entity ?? node.entry
       const rel = typeof uuid === 'string' ? poolPathByUuid.get(uuid) : null
-      // A record at the top of the folder needs no line — but one that did not land
-      // is still said: the next push sends the folder the directory holds, which
-      // would not have it.
+      // ⭐ What the folder says about the record — its entry's `tags` and `label` — comes
+      // back as the entry `{ path, tags?, label? }` (ruled 2026-09-27 [Diego]).
+      const said = {}
+      if (Array.isArray(node.tags) && node.tags.length) said.tags = node.tags.map(String)
+      if (node.label !== undefined && node.label !== null) {
+        const label = unwrapLocalized(node.label, sourceLocale)
+        if (typeof label === 'string' && label) said.label = label
+      }
+      const says = Object.keys(said).length > 0
+      // A record at the top of the folder needs no line unless the folder says something
+      // about it — but one that did not land is still said: the next push sends the folder
+      // the directory holds, which would not have it.
       if (!inBranch) {
         if (!rel) {
           warnings.push(
             `the folder holds a record ("${node.name ?? '?'}") that was not written locally — ` +
               `a push from here would remove it from the folder.`
           )
+          continue
         }
+        if (says && !out.some((e) => e?.path === rel)) out.push({ path: rel, ...said })
         continue
       }
       if (!rel) {
@@ -554,7 +568,8 @@ export function folderToFolderYml({ folderDoc, siteRoot, poolPathByUuid, sourceL
         continue
       }
       // A list file holds several records and is one path — listed once.
-      if (!out.includes(rel)) out.push(rel)
+      if (out.some((e) => e === rel || e?.path === rel)) continue
+      out.push(says ? { path: rel, ...said } : rel)
     }
     return out
   }

package/src/uwx/records.js

@@ -729,8 +729,13 @@ function placeProducedRecords(nodes, producedBy) {
       out.push({ ...node, $children: placeProducedRecords(node.$children, producedBy) })
       continue
     }
+    // What the folder says about the record — its entry's `tags` and `label` — goes with
+    // every record the file produced.
+    const said = {}
+    if (node?.tags) said.tags = node.tags
+    if (node?.label !== undefined) said.label = node.label
     for (const r of producedBy.get(node?.$entityId) || []) {
-      out.push({ kind: 'ref', name: r.slug, $entityId: r.id })
+      out.push({ kind: 'ref', name: r.slug, $entityId: r.id, ...said })
     }
   }
   return out