@uniweb/build 0.14.11 → 0.14.13

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@uniweb/build",
-  "version": "0.14.11",
+  "version": "0.14.13",
   "description": "Build tooling for the Uniweb Component Web Platform",
   "type": "module",
   "exports": {
@@ -60,21 +60,21 @@
     "sharp": "^0.33.2",
     "yaml": "^2.5.0",
     "@uniweb/content-writer": "0.2.5",
-    "@uniweb/theming": "0.1.3"
+    "@uniweb/theming": "0.1.4"
   },
   "optionalDependencies": {
-    "@uniweb/schemas": "0.2.3",
+    "@uniweb/runtime": "0.8.18",
     "@uniweb/content-reader": "1.1.12",
-    "@uniweb/runtime": "0.8.16"
+    "@uniweb/schemas": "0.2.3"
   },
   "peerDependencies": {
     "vite": "^5.0.0 || ^6.0.0 || ^7.0.0",
-    "react": "^18.0.0 || ^19.0.0",
-    "react-dom": "^18.0.0 || ^19.0.0",
+    "react": "^19.0.0",
+    "react-dom": "^19.0.0",
     "@tailwindcss/vite": "^4.0.0",
     "@vitejs/plugin-react": "^4.0.0 || ^5.0.0",
     "vite-plugin-svgr": "^4.0.0",
-    "@uniweb/core": "0.7.12"
+    "@uniweb/core": "0.7.13"
   },
   "peerDependenciesMeta": {
     "vite": {

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-project.js

@@ -99,6 +99,7 @@ const INFO_TO_SITE_YML = {
   search: 'search',
   paths: 'paths',
   data: 'data',
+  template: 'template',
 }
 
 /**

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
@@ -535,6 +554,10 @@ export async function siteProjectToDocument(siteRoot, opts = {}) {
   setIf(info, 'search', siteYml.search)
   setIf(info, 'paths', siteYml.paths)
   setIf(info, 'data', siteYml.data ?? siteYml.fetch)
+  // `template: true` designates this site as a clonable SITE-TEMPLATE: on push the
+  // backend applies a clonability designation to this site-content entity (it is
+  // NOT a registry artifact). Verbatim; absent → a normal (non-template) site.
+  setIf(info, 'template', siteYml.template)
 
   const ctx = { siteRoot, siteIndex: siteYml.index, sourceLocale, translations }
   const pagesPath = siteYml.paths?.pages

package/src/vite-foundation-plugin.js

@@ -13,6 +13,7 @@ import { join, resolve } from 'node:path'
 import { buildSchema } from './schema.js'
 import { generateEntryPoint, shouldRegenerateForFile } from './generate-entry.js'
 import { processAllPreviews } from './images.js'
+import { generateFoundationVars } from './theme/index.js'
 
 /**
  * Build schema.json with preview image references
@@ -300,6 +301,45 @@ async function buildSSRBundle(outDir) {
   }
 }
 
+/**
+ * Append the foundation's theme-variable DEFAULTS as a `:root{}` baseline to the
+ * built CSS (`assets/style.css`), so a runtime-loaded foundation carries its own
+ * var defaults wherever it loads (registry ref / URL — where the site build can't
+ * read them). Context-aware vars (color/gradient) are excluded: those are applied
+ * per light/dark context by the site theme, not as a flat default. Idempotent
+ * (marker-guarded), and a no-op when the foundation declares no vars or ships no
+ * stylesheet to carry them.
+ */
+async function emitFoundationVarsCss(outDir, schema) {
+  const rawVars = schema?._self?.vars
+  if (!rawVars || Object.keys(rawVars).length === 0) return
+
+  const CONTEXT_AWARE = new Set(['color', 'gradient'])
+  const flatVars = Object.fromEntries(
+    Object.entries(rawVars).filter(
+      ([, cfg]) => !(cfg && typeof cfg === 'object' && CONTEXT_AWARE.has(cfg.type))
+    )
+  )
+
+  const rootCss = generateFoundationVars(flatVars)
+  if (!rootCss) return
+
+  const cssPath = join(outDir, 'assets', 'style.css')
+  if (!existsSync(cssPath)) {
+    console.warn(
+      `Foundation declares ${Object.keys(flatVars).length} theme var(s) but has no assets/style.css to carry their defaults — skipped.`
+    )
+    return
+  }
+
+  const marker = '/* uniweb:foundation-var-defaults */'
+  const existing = await readFile(cssPath, 'utf-8')
+  if (existing.includes(marker)) return
+
+  await writeFile(cssPath, `${existing.trimEnd()}\n\n${marker}\n${rootCss}\n`, 'utf-8')
+  console.log(`Emitted ${Object.keys(flatVars).length} foundation theme-var default(s) to assets/style.css`)
+}
+
 /**
  * Vite plugin for foundation builds
  */
@@ -359,6 +399,18 @@ export function foundationBuildPlugin(options = {}) {
 
       console.log(`Generated meta/schema.json with ${Object.keys(schema).length - 1} components`)
 
+      // Emit the foundation's theme-variable DEFAULTS as a :root{} baseline into
+      // the delivered CSS. A runtime-loaded foundation (registry ref / URL) is
+      // loaded with only its dist/ — the site build can't read these defaults
+      // (they live in schema._self.vars, which the site never sees), so without
+      // this the foundation renders with its theme vars undefined (e.g. collapsed
+      // section spacing where components use py-[var(--section-padding-y)]).
+      // Shipping the defaults in the foundation's own CSS makes it self-sufficient
+      // in every load mode; a site's theme.yml overrides still win (the site theme
+      // loads after the foundation CSS). Bundled sites already get these via the
+      // site build's theme.css — this is harmless redundancy there.
+      await emitFoundationVarsCss(outDir, schema)
+
       // Emit runtime-pin.json so the edge isolate (under Strategy S) can
       // side-load the matching runtime/{ver}/ssr.js. Lands silently before
       // the dual-mode resolver ships; foundations published in the dual-mode