@uniweb/build 0.38.0 → 0.39.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@uniweb/build",
-  "version": "0.38.0",
+  "version": "0.39.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/content-reader": "^1.2.4",
-    "@uniweb/projections": "^0.5.8",
-    "@uniweb/schemas": "^0.2.13",
     "@uniweb/content-writer": "^0.3.4",
     "@uniweb/semantic-parser": "^1.4.0",
-    "@uniweb/theming": "^0.1.15"
+    "@uniweb/theming": "^0.1.15",
+    "@uniweb/content-reader": "^1.2.4",
+    "@uniweb/projections": "^0.5.9",
+    "@uniweb/schemas": "^0.2.13"
   },
   "optionalDependencies": {
-    "@uniweb/runtime": "^0.15.0"
+    "@uniweb/runtime": "^0.16.0"
   },
   "peerDependencies": {
     "vite": "^5.0.0 || ^6.0.0 || ^7.0.0",
@@ -74,7 +74,7 @@
     "@tailwindcss/vite": "^4.0.0",
     "@vitejs/plugin-react": "^4.0.0 || ^5.0.0",
     "vite-plugin-svgr": "^4.0.0",
-    "@uniweb/core": "^0.20.0"
+    "@uniweb/core": "^0.21.0"
   },
   "peerDependenciesMeta": {
     "vite": {

package/src/site/records-config.js

@@ -143,7 +143,7 @@ export async function readRecordsConfig(siteRoot) {
  *
  * ⛔ ONE PLACEMENT PER ENTITY. Two entries matching one file is a hard error, not
  * a second placement. The wire could carry many-to-many — `folder.js` nests, and
- * placements are keyed by their `path_segment` chain — but `core/src/where.js`'s
+ * placements are keyed by their `name` chain — but `core/src/where.js`'s
  * `matchUnder` is STRING-ONLY, so a record with two paths would match nothing
  * under `where: { path: { under: … } }`, silently. Widening `under` is a
  * predicate the backend also evaluates natively, so it is a cross-lane change to
@@ -184,7 +184,7 @@ export function resolveFolder(entries, pool) {
     const slug = slugForEntity(entity)
     const path = pathSegs.join('/')
     placements.set(key, { entity, path, slug })
-    return { kind: 'ref', path_segment: slug, $entityId: key }
+    return { kind: 'ref', name: slug, $entityId: key }
   }
 
   const resolveEntry = (entry, pathSegs, index, trail) => {
@@ -246,8 +246,13 @@ export function resolveFolder(entries, pool) {
         errors.push(`${RECORDS_YML_RELPATH}: ${where} declares a folder with no name.`)
         return []
       }
-      const branch = { kind: 'branch', path_segment: segment }
-      if (entry.label !== undefined && entry.label !== null) branch.name = String(entry.label)
+      // ⭐ `name` is the handle (the URL segment, sibling-unique); `label` is the
+      // display text. The store renamed the pair on 2026-09-04 — `path_segment` →
+      // `name`, and the old `name` (display) → `label` — so one word means one
+      // thing from records.yml (`folder:` / `label:`) to the wire to the door's
+      // `$name`.
+      const branch = { kind: 'branch', name: segment }
+      if (entry.label !== undefined && entry.label !== null) branch.label = String(entry.label)
       const kids = Array.isArray(entry.records) ? entry.records : []
       if (kids.length === 0) {
         warnings.push(

package/src/uwx/folder.js

@@ -7,10 +7,18 @@
 //   - `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', path_segment, ... }`
-//         with `entry: <uuid>` once the record was minted (back-filled into its file),
+//       - a LEAF references one record entity: `{ kind: 'ref', name, ... }` with
+//         `entry: <uuid>` once the record was minted (back-filled into its file),
 //         or `$ref: "<id>"` while brand-new (resolved within this payload).
-//       - a BRANCH is a sub-folder: `{ kind: 'branch', path_segment, name?, $children }`.
+//       - a BRANCH is a sub-folder: `{ kind: 'branch', name, label?, $children }`.
+//
+// ⭐ `name` IS THE HANDLE — the URL segment, sibling-unique, the door's `$name` —
+// and `label` is the display text, a localized map (`{ en: "Blog" }`). The store
+// renamed the pair on 2026-09-04 (`path_segment` → `name`; the old display `name`
+// → `label`); this emitter writes the new shape only and the pull reader
+// (`records-project.js`) reads the new shape only. No alias on either side: the
+// old key's PRESENCE was the version signal, and there is no population to
+// carry.
 //
 // ⭐ THE ORGANIZATION IS AUTHORED, IN `records.yml`, AND IT IS THE ONLY SOURCE.
 // It used to be DERIVED — one branch per collection, mirroring the `collections/`
@@ -42,7 +50,7 @@ export const FOLDER_ENTITY_KEY = '@folder'
 // it currently carries the Model NAME (e.g. `@std/article`). Wire the name→uuid
 // resolution (a registry data-schema read) as a follow-up.
 function refLeaf(entity) {
-  const leaf = { kind: 'ref', path_segment: entity.slug }
+  const leaf = { kind: 'ref', name: entity.slug }
   if (entity.uuid) leaf.entry = { model: entity.model, entity: entity.uuid }
   else leaf.$ref = entity.id // the payload-local handle
   return leaf
@@ -60,13 +68,16 @@ function refLeaf(entity) {
  * @param {Map<string, object>} byEntityId - record entities, keyed by pool id
  * @param {string[]} missing - collects ids that resolved to no entity
  */
-function contentsFromNodes(nodes, byEntityId, missing) {
+function contentsFromNodes(nodes, byEntityId, missing, sourceLocale) {
   const out = []
   for (const node of nodes || []) {
     if (node.kind === 'branch') {
-      const branch = { kind: 'branch', path_segment: node.path_segment }
-      if (node.name !== undefined) branch.name = node.name
-      branch.$children = contentsFromNodes(node.$children, byEntityId, missing)
+      const branch = { kind: 'branch', name: node.name }
+      // The display text is a LOCALIZED field on the wire — a `{ locale: value }`
+      // map, like every localized scalar this producer sends — keyed by the
+      // site's source locale.
+      if (node.label !== undefined) branch.label = { [sourceLocale]: String(node.label) }
+      branch.$children = contentsFromNodes(node.$children, byEntityId, missing, sourceLocale)
       out.push(branch)
       continue
     }
@@ -82,7 +93,7 @@ function contentsFromNodes(nodes, byEntityId, missing) {
 
 /**
  * Walk a folder document's `contents` tree, visiting every item with the
- * slash-joined `path_segment` chain that addresses it.
+ * slash-joined `name` chain that addresses it.
  *
  * ⛔ IT MUST RECURSE INTO `$children`. `contents` is SELF-NESTING: a walk of the
  * top level sees the branches and misses every record under them — which is 6 of
@@ -92,7 +103,7 @@ function contentsFromNodes(nodes, byEntityId, missing) {
 function walkFolderItems(contents, cb, prefix = '') {
   for (const item of contents || []) {
     if (!item || typeof item !== 'object') continue
-    const seg = typeof item.path_segment === 'string' ? item.path_segment : null
+    const seg = typeof item.name === 'string' ? item.name : null
     const path = seg ? (prefix ? `${prefix}/${seg}` : seg) : prefix
     if (seg) cb(path, item)
     walkFolderItems(item.$children, cb, path)
@@ -102,8 +113,8 @@ function walkFolderItems(contents, cb, prefix = '') {
 /**
  * Harvest per-item identity from the folder document the backend returns.
  *
- * ⭐ THE KEY IS THE `path_segment` CHAIN, and it is the right one because the
- * backend's own model declares `path_segment` SIBLING-UNIQUE — so the chain is
+ * ⭐ THE KEY IS THE `name` CHAIN, and it is the right one because the backend's
+ * own model declares `name` SIBLING-UNIQUE — so the chain is
  * unique within the folder, stable across pushes, and derivable identically on
  * both sides without either lane holding the other's ids.
  *
@@ -163,9 +174,11 @@ export function stampFolderItemUuids(doc, pathToUuid = {}) {
  * @param {Record<string,string>} [params.itemUuids] - path → `$uuid`, harvested
  *        from the folder document a previous push returned. Absent on a first
  *        push, where every item is genuinely new.
+ * @param {string} [params.sourceLocale='en'] - the locale a branch `label` is
+ *        keyed under on the wire
  * @returns {{ id, uuid, model, file, document, warnings }|null}
  */
-export function buildFolderEntity({ recordEntities, folderNodes = [], declared, itemUuids = null }) {
+export function buildFolderEntity({ recordEntities, folderNodes = [], declared, itemUuids = null, sourceLocale = 'en' }) {
   // ⛔ `missing` AND `empty` ARE DIFFERENT, AND THE ASYMMETRY IS DELIBERATE.
   //
   //   no records.yml       → null. INERT: nothing is sent, and the server's
@@ -186,7 +199,7 @@ export function buildFolderEntity({ recordEntities, folderNodes = [], declared,
   for (const e of recordEntities || []) byEntityId.set(e.id, e)
 
   const missing = []
-  const contents = contentsFromNodes(folderNodes, byEntityId, missing)
+  const contents = contentsFromNodes(folderNodes, byEntityId, missing, sourceLocale)
   // ⚠️ `id` IS THE ENTITY'S POOL PATH, NOT A FOLDER PATH — say so, because the two
   // read identically and a reader who takes it for a placement concludes the
   // emitter is dropping a branch it never had. *(Measured 2026-08-31: the backend

package/src/uwx/records-project.js

@@ -6,8 +6,8 @@
 //
 // Identity & placement. A record's on-disk home is `(collection, slug)`:
 //   - `slug` and `collection` come from the FOLDER document — each ref leaf is
-//     `{ entry: { model, entity: <uuid> }, path_segment: <slug> }` inside a branch
-//     (its `$children`) whose `path_segment` names the folder it was placed in.
+//     `{ entry: { model, entity: <uuid> }, name: <slug> }` inside a branch
+//     (its `$children`) whose `name` names the folder it was placed in.
 //     The folder is the authoritative organization on a read (the record
 //     document's own `$id` envelope is not guaranteed to be echoed back), with
 //     the record document's `$id` (its pool identity) as a fallback when present.
@@ -40,6 +40,7 @@ import { writeRecordFile, writeQueriesConfig, writeRecordsConfig } from './proje
 import { defaultSchema, deferredFromSchema, foundationDataSchemas } from './queries-config.js'
 import { poolDirsForSchema, ENTITIES_DIR } from '../site/entity-pool.js'
 import { isContentBodyField } from './data-schema.js'
+import { unwrapLocalized } from './backfill.js'
 import { createTranslationCollector, writeLocaleTranslations, writeFreeformTranslations } from './locale-sync.js'
 import { buildFreeformRecordPath } from '../i18n/freeform.js'
 
@@ -111,9 +112,13 @@ function briefHasContentBody(declaration) {
 
 // Build `uuid → { collection, slug }` from the folder document's ref leaves. The
 // folder is a self-nesting tree under `contents`, nesting via `$children` (the
-// site-content invariant — folder.js). A leaf sits in a branch whose
-// `path_segment` is the collection; the leaf's `path_segment` is the slug and its
-// `entry` is the entity_ref open form `{ model, entity: <uuid> }`. Nested branches
+// site-content invariant — folder.js). A leaf sits in a branch whose `name` is
+// the collection; the leaf's `name` is the slug (the handle) and its `entry` is
+// the entity_ref open form `{ model, entity: <uuid> }`. ⛔ `path_segment` is not
+// read: the store renamed it on 2026-09-04 and a pull emits the new shape only —
+// a reader that kept the old key would index every record as
+// `{ folderPath: null, slug: undefined }` and rewrite records.yml with
+// `folder: undefined` branches (measured on this reader, 2026-09-04). Nested branches
 // are walked; the collection is the NEAREST enclosing branch segment (correct for
 // the default one-branch-per-collection org; a deeply nested virtual org may
 // differ — see the module header).
@@ -122,11 +127,11 @@ function indexFolder(folderDoc) {
   const walk = (nodes, folderPath) => {
     for (const node of nodes || []) {
       if (node?.kind === 'branch') {
-        walk(node.$children, node.path_segment ?? folderPath)
+        walk(node.$children, node.name ?? folderPath)
       } else if (node?.kind === 'ref' && node.entry) {
         // `entry` is `{ model, entity: <uuid> }`; tolerate a bare uuid defensively.
         const uuid = typeof node.entry === 'object' ? node.entry.entity : node.entry
-        if (uuid) byUuid.set(uuid, { folderPath, slug: node.path_segment })
+        if (uuid) byUuid.set(uuid, { folderPath, slug: node.name })
       }
     }
   }
@@ -381,7 +386,7 @@ export function declarationsToQueriesYml({ document, siteRoot }) {
  *        each record landed with.
  * @returns {{ status: 'updated'|'unchanged'|'skipped', entries: Array, warnings: string[] }}
  */
-export function folderToRecordsYml({ folderDoc, siteRoot, poolPathByUuid }) {
+export function folderToRecordsYml({ folderDoc, siteRoot, poolPathByUuid, sourceLocale = 'en' }) {
   const warnings = []
 
   const walk = (nodes) => {
@@ -389,10 +394,11 @@ export function folderToRecordsYml({ folderDoc, siteRoot, poolPathByUuid }) {
     for (const node of nodes || []) {
       if (!node || typeof node !== 'object') continue
       if (node.kind === 'branch') {
-        const entry = { folder: node.path_segment }
+        const entry = { folder: node.name }
         // Only a BRANCH takes a label. A record carries its own title; the folder
-        // does not caption its rows.
-        if (node.name !== undefined) entry.label = node.name
+        // does not caption its rows. On the wire the label is a localized map;
+        // records.yml carries the source-locale string (a bare string passes).
+        if (node.label !== undefined) entry.label = unwrapLocalized(node.label, sourceLocale)
         entry.records = walk(node.$children)
         out.push(entry)
         continue
@@ -404,7 +410,7 @@ export function folderToRecordsYml({ folderDoc, siteRoot, poolPathByUuid }) {
         // means the folder and the pool disagree, and writing the file without it
         // would quietly unpublish that record on the next push.
         warnings.push(
-          `records.yml: a folder leaf ("${node.path_segment ?? '?'}") references a record that ` +
+          `records.yml: a folder leaf ("${node.name ?? '?'}") references a record that ` +
             `was not written locally — the file was left unchanged rather than dropping it.`
         )
         return null
@@ -523,7 +529,7 @@ export function recordsToProject({ folderDoc, recordDocs = [], siteRoot, opts =
   //
   // The folder ENTITY still carries no `$uuid` we persist: the backend owns the
   // site's folder, keyed by the site-content uuid.
-  const records = folderToRecordsYml({ folderDoc, siteRoot, poolPathByUuid })
+  const records = folderToRecordsYml({ folderDoc, siteRoot, poolPathByUuid, sourceLocale })
   warnings.push(...records.warnings)
 
   // Flush localized record-field translations to locales/records/{locale}.json,

package/src/uwx/records.js

@@ -104,14 +104,14 @@ function stripSigils(value) {
     //
     // ⭐ Neither encoding is content. What the folder SAYS is "this branch contains
     // this record, here, in this order" — and that is already hashed: a leaf carries
-    // `path_segment` (the record's slug) inside a branch carrying the collection's.
+    // `name` (the record's handle) inside a branch carrying the collection's.
     // A `folders:` branch's entries are COLLECTION names, so every leaf under one
     // comes from a single collection, where a slug is unique. Position plus segment
     // therefore identify the record on their own; `$ref` adds a payload-local handle
     // and `entry` adds identity, and both are exactly what `$uuid` is stripped for.
     //
     // ⚖️ The previous rule kept `$ref` "so a reference change is visible". It still
-    // is: point a leaf at a different record and its `path_segment` moves with it.
+    // is: point a leaf at a different record and its `name` moves with it.
     const isFolderRefLeaf = value.kind === 'ref'
     const out = {}
     for (const [k, v] of Object.entries(value)) {
@@ -287,7 +287,7 @@ export function recordsToEntities({
     // The qualification is a CONSTRAINT, not a style: the sync response is keyed per
     // (`$model`, `$id`), so a bare slug would collide whenever two queries over the
     // same Model reuse one (see the duplicate check below). ⇒ Do not describe this
-    // value as "the slug" — the folder leaf's `path_segment` is the bare segment, and
+    // value as "the slug" — the folder leaf's `name` is the bare segment, and
     // conflating the two has already misdirected a naming decision.
     const id = record.$id || `${queryName}/${slug}`
     const uuid = record.$uuid || null

package/src/uwx/sync-package.js

@@ -276,6 +276,7 @@ export async function emitSyncPackages(siteRoot, opts = {}) {
   // are complete — new records by `$ref`, already-minted ones by `entry: <uuid>`.
   const folder = buildFolderEntity({
     recordEntities: col.entities,
+    ...(sourceLocale ? { sourceLocale } : {}),
     // ⭐ AUTHORED, from `records.yml`. It used to be derived — one branch per
     // collection — which made the folder a shadow of a directory layout rather
     // than something the author states.