@uniweb/build 0.14.10 → 0.14.12

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@uniweb/build",
-  "version": "0.14.10",
+  "version": "0.14.12",
   "description": "Build tooling for the Uniweb Component Web Platform",
   "type": "module",
   "exports": {
@@ -63,9 +63,9 @@
     "@uniweb/content-writer": "0.2.5"
   },
   "optionalDependencies": {
-    "@uniweb/runtime": "0.8.16",
     "@uniweb/content-reader": "1.1.12",
-    "@uniweb/schemas": "0.2.2"
+    "@uniweb/schemas": "0.2.3",
+    "@uniweb/runtime": "0.8.17"
   },
   "peerDependencies": {
     "vite": "^5.0.0 || ^6.0.0 || ^7.0.0",

package/src/site/content-collector.js

@@ -1234,6 +1234,12 @@ async function processPage(pagePath, pageName, siteRoot, { isIndex = false, pare
       title: pageConfig.title || extractH1(hierarchicalSections[0]?.content) || prettifySlug(pageName),
       description: pageConfig.description || '',
       label: pageConfig.label || null, // Short label for navigation (defaults to title)
+      // Localized URL slug overrides: { <locale>: <segment> }. Compiled into
+      // config.i18n.routeTranslations by collectSiteContent, then stripped from
+      // the page payload (build is authoritative; runtime hydrates the map).
+      ...(pageConfig.slug && typeof pageConfig.slug === 'object' && !Array.isArray(pageConfig.slug)
+        ? { slug: pageConfig.slug }
+        : {}),
       lastModified: lastModified?.toISOString(),
 
       // Dynamic route metadata
@@ -2133,11 +2139,33 @@ export async function collectSiteContent(sitePath, options = {}) {
   const intelligenceConfig = await readYamlFile(join(sitePath, 'intelligence.yml'))
   const hasIntelligence = intelligenceConfig && Object.keys(intelligenceConfig).length > 0
 
+  // Compile per-page `slug:` maps into config.i18n.routeTranslations
+  // (canonical route → per-locale display route). Producer-only: the runtime
+  // (@uniweb/core website.js) and the sitemap generator already consume this
+  // map; nothing else produces it on the file-based lane. The default locale
+  // keeps the canonical (folder-based) route. Strip the build-time `slug` from
+  // pages afterward — the runtime hydrates the precomputed map, not per-page
+  // slugs (see "Minimize Runtime Payload").
+  const defaultLocale =
+    siteConfig.defaultLanguage ||
+    (Array.isArray(siteConfig.languages) ? siteConfig.languages[0] : null) ||
+    'en'
+  const routeTranslations = buildRouteTranslations(pages, {
+    defaultLocale,
+    languages: Array.isArray(siteConfig.languages) ? siteConfig.languages : null,
+  })
+  for (const page of pages) {
+    if (page.slug) delete page.slug
+  }
+
   return {
     config: {
       ...siteConfig,
       fetch: parseFetchConfig(siteConfig.fetch),
       ...(hasIntelligence && { intelligence: intelligenceConfig }),
+      ...(routeTranslations
+        ? { i18n: { ...(siteConfig.i18n || {}), routeTranslations } }
+        : {}),
     },
     theme: {
       ...processedTheme,
@@ -2162,7 +2190,115 @@ export async function collectSiteContent(sitePath, options = {}) {
 // than the flattened collector output but reuses these primitives so
 // markdown→ProseMirror, ordering, and mode detection stay consistent with a
 // normal build. Additive: no existing behavior changes.
+/**
+ * Whether a value is a usable single URL path segment (no slashes, no
+ * whitespace). Localized slug segments must satisfy this to be applied.
+ */
+function isValidSlugSegment(s) {
+  return typeof s === 'string' && s.length > 0 && !s.includes('/') && !/\s/.test(s)
+}
+
+/**
+ * Compose the full localized display route for a canonical route in a locale,
+ * substituting the localized segment for any ancestor (or self) that declares
+ * one in `slugByRoute`. Falls back to the canonical segment where no valid
+ * localized slug exists. E.g. with /blog→blogue and /blog/my-post→mon-article,
+ * `/blog/my-post` (fr) → `/blogue/mon-article`.
+ */
+function composeLocalizedRoute(canonicalRoute, locale, slugByRoute) {
+  if (!canonicalRoute || canonicalRoute === '/') return canonicalRoute || '/'
+  const segments = canonicalRoute.split('/').filter(Boolean)
+  let cumulative = ''
+  const out = []
+  for (const seg of segments) {
+    cumulative += `/${seg}`
+    const localized = slugByRoute.get(cumulative)?.[locale]
+    out.push(isValidSlugSegment(localized) ? localized : seg)
+  }
+  return '/' + out.join('/')
+}
+
+/**
+ * Build `config.i18n.routeTranslations` from per-page `slug:` maps.
+ *
+ * Author surface: a page declares `slug: { <locale>: <segment> }` in its
+ * page.yml. The canonical route stays the folder name; for each non-default
+ * locale the localized URL substitutes the declared segment(s). The runtime
+ * (`@uniweb/core` website.js: translateRoute/getLocaleUrl/getPageHierarchy) and
+ * the build sitemap already consume this map — this is its only producer on the
+ * file-based lane. Children without their own slug inherit a localized ancestor
+ * via the runtime's prefix-cascade, so only pages that declare a slug get an
+ * explicit entry.
+ *
+ * Pure + non-mutating. Returns `{ [locale]: { [canonicalRoute]: displayRoute } }`,
+ * or null when no page declares a usable localized slug.
+ *
+ * @param {Array} pages - Flat page list (each with canonical `route` + optional `slug`).
+ * @param {Object} [opts]
+ * @param {string} [opts.defaultLocale='en'] - Default locale; its routes are the
+ *   canonical keys, so default-locale slugs are skipped (renaming the default
+ *   URL away from the folder name is a separate, heavier concern).
+ * @param {string[]|null} [opts.languages=null] - Declared site locales; when an
+ *   array, slug locales outside it are skipped with a warning. null = no filter.
+ * @returns {Object|null}
+ */
+function buildRouteTranslations(pages, { defaultLocale = 'en', languages = null } = {}) {
+  if (!Array.isArray(pages)) return null
+
+  // Index canonical route → { locale: segment } for pages declaring a slug map.
+  const slugByRoute = new Map()
+  for (const page of pages) {
+    const slug = page?.slug
+    if (slug && typeof slug === 'object' && !Array.isArray(slug) && page.route) {
+      slugByRoute.set(page.route, slug)
+    }
+  }
+  if (slugByRoute.size === 0) return null
+
+  const langSet = Array.isArray(languages) ? new Set(languages) : null
+  const result = {}
+
+  for (const [canonicalRoute, localeMap] of slugByRoute) {
+    for (const [locale, segment] of Object.entries(localeMap)) {
+      // Default locale keeps the canonical (folder-based) route.
+      if (locale === defaultLocale) continue
+      if (langSet && !langSet.has(locale)) {
+        console.warn(
+          `[content-collector] slug locale '${locale}' on '${canonicalRoute}' is not in site languages — skipping`
+        )
+        continue
+      }
+      if (!isValidSlugSegment(segment)) {
+        console.warn(
+          `[content-collector] invalid slug '${segment}' for '${canonicalRoute}' (${locale}) — must be a single URL-safe path segment`
+        )
+        continue
+      }
+      const display = composeLocalizedRoute(canonicalRoute, locale, slugByRoute)
+      ;(result[locale] ||= {})[canonicalRoute] = display
+    }
+  }
+
+  // Warn on within-locale display collisions (two canonical routes → same URL).
+  for (const [locale, map] of Object.entries(result)) {
+    const seen = new Map()
+    for (const [canon, disp] of Object.entries(map)) {
+      const prev = seen.get(disp)
+      if (prev) {
+        console.warn(
+          `[content-collector] localized route collision in '${locale}': '${canon}' and '${prev}' both map to '${disp}'`
+        )
+      } else {
+        seen.set(disp, canon)
+      }
+    }
+  }
+
+  return Object.keys(result).length > 0 ? result : null
+}
+
 export {
+  buildRouteTranslations,
   extractItemName,
   parseWildcardArray,
   applyWildcardOrder,

package/src/uwx/collections.js

@@ -96,7 +96,12 @@ function encodeFieldValue(value, field, sourceLocale, translations) {
     // path, flushed to locales/collections/{locale}.json by the caller.
     const doc = typeof value === 'string' ? markdownToProseMirror(value) : value
     if (!field.localized) return doc
-    return localizeContentDoc(doc, sourceLocale, Object.keys(translations || {}), translations)
+    const localized = localizeContentDoc(doc, sourceLocale, Object.keys(translations || {}), translations)
+    // localizeContentDoc returns a BARE doc when there are no target locales. A
+    // localized field MUST ride as a `{ lang: value }` map on the wire — the
+    // schema-driven projector drops a localized field whose value isn't a map — so
+    // wrap the source doc, consistent with localizeScalar (which always wraps).
+    return isLocalizedContent(localized) ? localized : { [sourceLocale]: localized }
   }
   if (field.localized) {
     // A markup `text` BODY (format markdown|html) rides as a RAW string, wrapped
@@ -143,33 +148,52 @@ export function collectionRecordsToEntities({
   if (!declaration || !declaration.name) {
     throw new Error('uwx/collections: a declaration with a name is required')
   }
-  // The brief is the section marked `brief: true` (the sections-tree has no
-  // schema-level `brief:` back-reference); its `fields` is a map keyed by name.
-  const briefEntry = Object.entries(declaration.sections || {}).find(([, s]) => s && s.brief === true)
+  // A record (one source file) maps to the Model's SINGLE sections in declared
+  // order — the brief (the card) plus any sibling single sections, e.g. a body
+  // section like `article_body`. Multi-section Models are the norm for `@std/*`
+  // types; the markdown body lands in the designated content field WHEREVER it is
+  // declared (the brief, or a non-brief body section). `multi` sections (repeating
+  // items) can't be expressed by one flat record and are skipped. The brief is the
+  // section marked `brief: true` (the sections-tree has no schema-level back-ref).
+  const sectionEntries = Object.entries(declaration.sections || {})
+  const briefEntry = sectionEntries.find(([, s]) => s && s.brief === true)
   const briefName = briefEntry?.[0]
-  const brief = briefEntry?.[1]
-  if (!brief) {
-    throw new Error(
-      `uwx/collections: Model ${declaration.name} has no brief section — ` +
-        'v1 maps flat records to the brief single section only'
-    )
+  if (!briefName) {
+    throw new Error(`uwx/collections: Model ${declaration.name} has no brief section`)
+  }
+  // The single sections a flat record can populate (the brief + sibling singles),
+  // and a global field→section map across them — for distributing frontmatter and
+  // flagging unknown keys. Field names are unique across a Model's sections (the
+  // declaration's own convention); a collision keeps the first occurrence.
+  const recordSections = sectionEntries.filter(([, s]) => s && s.multiple !== true)
+  const fieldByKey = new Map()
+  for (const [, sec] of recordSections) {
+    for (const [key, field] of Object.entries(sec.fields || {})) {
+      if (!fieldByKey.has(key)) fieldByKey.set(key, field)
+    }
   }
-  const briefFields = brief.fields || {}
-  const fieldByKey = new Map(Object.entries(briefFields))
 
-  // The markdown body of a `.md` collection record is the value of the brief's
-  // CONTENT field — a markup `text` field (raw source string) or a `format:
-  // prosemirror` json field (docs/reference/entity-content.md). One content field is
-  // the body target; zero means a `.md` body has nowhere to go (warn per record).
-  const contentEntries = Object.entries(briefFields).filter(([, f]) => isContentBodyField(f))
-  const bodyFieldKey = contentEntries[0]?.[0] || null
+  // The markdown body of a `.md` record is the value of the Model's CONTENT body
+  // field — a markup `text` field (raw source string) or a `format: prosemirror`
+  // json field (docs/reference/entity-content.md) — wherever it is declared (the
+  // brief, or a non-brief body section like `article_body.content`). encodeFieldValue
+  // does the md→ProseMirror conversion per field kind. One content field is the body
+  // target; zero means a `.md` body has nowhere to go (warn per record).
+  const contentMatches = []
+  for (const [secName, sec] of recordSections) {
+    for (const [key, field] of Object.entries(sec.fields || {})) {
+      if (isContentBodyField(field)) contentMatches.push({ secName, key })
+    }
+  }
+  const bodyTarget = contentMatches[0] || null
 
   const entities = []
   const warnings = []
-  if (contentEntries.length > 1) {
+  if (contentMatches.length > 1) {
     warnings.push(
-      `${collectionName}: ${declaration.name}.${briefName} has more than one content ` +
-        `(markdown / html / prosemirror) field — the markdown body maps to "${bodyFieldKey}"`
+      `${collectionName}: ${declaration.name} has more than one content ` +
+        `(markdown / html / prosemirror) field — the markdown body maps to ` +
+        `"${bodyTarget.secName}.${bodyTarget.key}"`
     )
   }
   for (const record of records || []) {
@@ -185,43 +209,53 @@ export function collectionRecordsToEntities({
     const uuid = record.$uuid || null
     const hasBody = typeof record.$body === 'string' && record.$body.trim() !== ''
 
-    // Brief section data in schema-declared field order (the wire's canonical
-    // order). An absent field is simply omitted — an incomplete entity is a
-    // valid stored state; the foundation copes at render time. The markdown body
-    // fills the content body field unless the frontmatter already set it explicitly.
-    const data = {}
-    for (const [key, field] of Object.entries(briefFields)) {
-      let value = record[key]
-      if (value === undefined && key === bodyFieldKey && hasBody) value = record.$body
-      if (value === undefined) continue
-      const encoded = encodeFieldValue(value, field, sourceLocale, translations)
-      if (encoded !== undefined) data[key] = encoded
+    // Per-section data in schema-declared field order (the wire's canonical order).
+    // Frontmatter keys land in their declaring section; the markdown body fills the
+    // designated content field (in whatever section declares it) unless frontmatter
+    // already set it explicitly. An absent field is simply omitted — an incomplete
+    // entity is a valid stored state; the foundation copes at render time.
+    const sectionData = {}
+    for (const [secName, sec] of recordSections) {
+      const data = {}
+      for (const [key, field] of Object.entries(sec.fields || {})) {
+        let value = record[key]
+        if (value === undefined && bodyTarget && secName === bodyTarget.secName && key === bodyTarget.key && hasBody) {
+          value = record.$body
+        }
+        if (value === undefined) continue
+        const encoded = encodeFieldValue(value, field, sourceLocale, translations)
+        if (encoded !== undefined) data[key] = encoded
+      }
+      if (Object.keys(data).length) sectionData[secName] = data
     }
-    // Warn for author keys that aren't on the Model. A real unknown key means the
+    // Warn for author keys not on ANY record section. A real unknown key means the
     // frontmatter doesn't match the collection's data schema — that SHOULD warn
     // (only identity/transport keys in SKIP_KEYS are silent).
     for (const key of Object.keys(record)) {
       if (SKIP_KEYS.has(key) || fieldByKey.has(key)) continue
       warnings.push(
         `${collectionName}/${slug}: field "${key}" is not on ` +
-          `${declaration.name}.${briefName} — not synced`
+          `${declaration.name} — not synced`
       )
     }
-    if (hasBody && !bodyFieldKey) {
+    if (hasBody && !bodyTarget) {
       warnings.push(
         `${collectionName}/${slug}: markdown body present but ` +
-          `${declaration.name}.${briefName} has no content body field — body not synced`
+          `${declaration.name} has no content body field — body not synced`
       )
     }
 
-    // The `$`-document body, in canonical key order: `$uuid?`, `$id`, `$model`,
-    // then the brief section. `$owner`/`$unit`/`$meta` are omitted — the backend
-    // binds owner + unit on its side.
+    // The `$`-document, in canonical key order: `$uuid?`, `$id`, `$model`, then each
+    // populated section in declared order (the brief always present as the card).
+    // `$owner`/`$unit`/`$meta` are omitted — the backend binds owner + unit on its side.
     const document = {}
     if (uuid) document.$uuid = uuid
     document.$id = id
     document.$model = declaration.name
-    document[briefName] = data
+    document[briefName] = sectionData[briefName] || {}
+    for (const [secName] of recordSections) {
+      if (secName !== briefName && sectionData[secName]) document[secName] = sectionData[secName]
+    }
 
     entities.push({
       id,

package/src/uwx/folder.js

@@ -2,12 +2,15 @@
 //
 // A site sync carries the site-content entity, the collection-record entities, and
 // — when the site has collections — ONE `@uniweb/folder` entity describing how those
-// records are organized. The folder holds REFERENCES, never content:
-//
-//   - a LEAF references one record entity, by `$ref: "<collection>/<slug>"` when the
-//     record has no `$uuid` yet (resolved within this payload), or `entry: <uuid>`
-//     when it was minted on an earlier sync (back-filled into the record's file).
-//   - a BRANCH is a sub-folder (`path_segment` + nested `entries`).
+// records are organized. `@uniweb/folder` is a normal section-keyed entity (the
+// "structured content all the way down" invariant): its document is `{ info?, contents }`.
+//   - `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),
+//         or `$ref: "<collection>/<slug>"` while brand-new (resolved within this payload).
+//       - a BRANCH is a sub-folder: `{ kind: 'branch', path_segment, name?, $children }`.
 //
 // Organization comes from `collections.yml::folders` (a VIRTUAL tree, decoupled from
 // the on-disk layout) when present; otherwise the default is one branch per
@@ -20,10 +23,18 @@
 export const FOLDER_MODEL_NAME = '@uniweb/folder'
 export const FOLDER_ENTITY_KEY = '@folder'
 
-// One record → a `ref` leaf. Known uuid → `entry`; brand-new → `$ref` handle.
+// One record → a `ref` leaf. The folder's `contents` field is polymorphic (it can
+// reference any Model), so the ref uses the entity_ref OPEN form `{ model, entity }`
+// — not a bare uuid (a bare uuid is only valid when the field pins a single model).
+// Known uuid → `entry: { model, entity: <uuid> }`; brand-new → `$ref` handle
+// (resolved within this payload to the minted entity).
+//
+// TODO: the sync lane is uuid-keyed, so `model` should be the resolved Model UUID;
+// 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 }
-  if (entity.uuid) leaf.entry = entity.uuid
+  if (entity.uuid) leaf.entry = { model: entity.model, entity: entity.uuid }
   else leaf.$ref = entity.id // the `<collection>/<slug>` payload-local handle
   return leaf
 }
@@ -40,37 +51,37 @@ function groupByCollection(recordEntities) {
 }
 
 // Default org: one branch per collection (declaration order), records as leaves.
-function defaultEntries(groups) {
-  const entries = []
+function defaultContents(groups) {
+  const contents = []
   for (const [collection, records] of groups) {
-    entries.push({
+    contents.push({
       kind: 'branch',
       path_segment: collection,
-      entries: records.map(refLeaf),
+      $children: records.map(refLeaf),
     })
   }
-  return entries
+  return contents
 }
 
 // Virtual org from `collections.yml::folders`. Each node is either a collection
 // NAME (string — expands to that collection's record leaves under a branch named
 // after it) or a `{ segment, label?, entries: [...] }` branch (recursively).
-function virtualEntries(folders, groups) {
+function virtualContents(folders, groups) {
   const buildNode = (node) => {
     if (typeof node === 'string') {
       const records = groups.get(node) || []
       return {
         kind: 'branch',
         path_segment: node,
-        entries: records.map(refLeaf),
+        $children: records.map(refLeaf),
       }
     }
     if (node && typeof node === 'object') {
       const segment = node.segment ?? node.path_segment
       const branch = { kind: 'branch', path_segment: segment }
-      if (node.label !== undefined) branch.label = node.label
+      if (node.label !== undefined) branch.name = node.label
       const children = Array.isArray(node.entries) ? node.entries : []
-      branch.entries = children.flatMap((child) => {
+      branch.$children = children.flatMap((child) => {
         // A bare collection name inside `entries:` expands to its leaves directly
         // (so the records sit in THIS branch, not a nested one).
         if (typeof child === 'string' && groups.has(child)) {
@@ -100,12 +111,12 @@ function virtualEntries(folders, groups) {
 export function buildFolderEntity({ recordEntities, folders = null }) {
   if (!Array.isArray(recordEntities) || recordEntities.length === 0) return null
   const groups = groupByCollection(recordEntities)
-  const entries = folders ? virtualEntries(folders, groups) : defaultEntries(groups)
+  const contents = folders ? virtualContents(folders, groups) : defaultContents(groups)
 
   const document = {
     $id: FOLDER_ENTITY_KEY,
     $model: FOLDER_MODEL_NAME,
-    entries,
+    contents,
   }
 
   return {

package/src/uwx/site.js

@@ -132,7 +132,12 @@ function mapSectionData(section) {
 function buildPageData(config, ctx) {
   const { slug, mode, isDynamic, paramName, isRoot, siteIndex, sourceLocale, translations } =
     ctx
-  const data = { slug, mode } // both required by the entity type
+  // The page `slug` is the localized route source — a `{lang: slug}` map (the
+  // site-content Model declares it localized; greenlit 2026-06-13). A single-locale
+  // site emits one entry (`{ en: "home" }`); per-locale slug overrides for
+  // multi-locale localized routes (from i18n.routeTranslations) are follow-on
+  // producer work. `mode` is the plain delivery mode.
+  const data = { slug: { [sourceLocale]: slug }, mode } // both required by the entity type
   setIf(data, 'stable_id', config.id)
   setIf(data, 'title', localizeScalar(config.title, sourceLocale, translations))
   setIf(data, 'description', localizeScalar(config.description, sourceLocale, translations))
@@ -148,11 +153,25 @@ function buildPageData(config, ctx) {
   setIf(data, 'rewrite', config.rewrite)
   setIf(data, 'layout', config.layout)
   setIf(data, 'seo', config.seo)
-  const fetch =
+  let fetch =
     config.fetch ??
     (config.data
       ? { collection: Array.isArray(config.data) ? config.data[0] : config.data }
       : undefined)
+  // Resolve the build-time `collection:` shorthand to the runtime-fetchable
+  // `path: /data/<name>.json` (the static convention the default-fetcher uses).
+  // A shell/backend-hosted site renders client-side with NO prerender, so the
+  // runtime fetches this decl directly — and `collection:` is build-time-only, so
+  // it would never resolve at render (the static build resolves it the same way
+  // in site/data-fetcher.js parseFetchConfig). The gateway serves the collection
+  // at `<base>/data/<name>.json`.
+  if (fetch && typeof fetch.collection === 'string') {
+    const { collection, ...rest } = fetch
+    // `schema` (the collection name) is BOTH the content.data key and part of the
+    // dataStore cache key (deriveCacheKey hashes {path,url,schema,…}; `collection`
+    // is ignored). Mirrors the static build's parseFetchConfig resolution.
+    fetch = { path: `/data/${collection}.json`, schema: collection, ...rest }
+  }
   setIf(data, 'fetch', fetch)
   if (isDynamic) {
     data.is_dynamic = true