@uniweb/build 0.63.4 → 0.64.1

package/src/runtime-schema.js

@@ -26,6 +26,7 @@
 
 import { isRichSchema } from '@uniweb/core'
 import { deliveredFields } from '@uniweb/schemas/conform'
+import { enumValues } from '@uniweb/schemas/format'
 
 /**
  * A `data:` entry's schema ref — a ref string, or `{ schema }` — or null for an inline
@@ -70,7 +71,8 @@ function extractSchemaField(field) {
   // inert at runtime but carried through.
   if (field.type) lean.type = field.type
   if (field.default !== undefined) lean.default = field.default
-  if (field.enum !== undefined) lean.enum = field.enum
+  // The values only: an entry's label (`{ value, label }`) is an editor's, and the runtime compares.
+  if (field.enum !== undefined) lean.enum = enumValues(field.enum)
   if (field.options) lean.options = field.options
 
   // Nested object → recurse into its field map.

package/src/site/content-collector.js

@@ -26,7 +26,7 @@ import { readFile, readdir, stat } from 'node:fs/promises'
 import { resolveQueriesConfig, toConfigQueries } from './queries-config.js'
 import { parseNumericPrefix, compareByNumericPrefix } from '../utils/numeric-prefix.js'
 import { isMarkdownFile, isIgnoredFolder } from '../utils/content-files.js'
-import { readLayoutFolder, DEFAULT_LAYOUT } from './layout-folder.js'
+import { readLayoutFolder, DEFAULT_LAYOUT, layoutAreaRoute } from './layout-folder.js'
 import { join, parse, relative, resolve, sep } from 'node:path'
 import { existsSync, statSync, realpathSync, readdirSync } from 'node:fs'
 import yaml from 'js-yaml'
@@ -2419,7 +2419,7 @@ async function collectLayouts(layoutDir, siteRoot) {
       assetCollection = mergeAssetCollections(assetCollection, result.assetCollection)
       iconCollection = mergeIconCollections(iconCollection, result.iconCollection)
     }
-    const route = area.layout === DEFAULT_LAYOUT ? `/layout/${area.area}` : `/layout/${area.layout}/${area.area}`
+    const route = layoutAreaRoute(area.layout, area.area)
     layouts[area.layout] ??= {}
     layouts[area.layout][area.area] = {
       route,
@@ -2693,6 +2693,11 @@ export async function collectSiteContent(sitePath, options = {}) {
   for (const { message } of langValidation.warnings) {
     console.warn(`[content-collector] ${message}`)
   }
+  // Errors stop a publish build (below); in dev they are said, so the author meets them here
+  // rather than first at a push.
+  if (!dropUnpublished) {
+    for (const { message } of langValidation.errors) console.warn(`[content-collector] ${message}`)
+  }
   // Publish filter (the sync format's "Per-locale publish
   // readiness"): on published build paths, only the publishable intersection
   // (publishLanguages ∩ languages; absent field = all declared) ships — in
@@ -2956,9 +2961,35 @@ function buildRouteTranslations(pages, { defaultLocale = 'en', languages = null
   return Object.keys(result).length > 0 ? result : null
 }
 
+/**
+ * One level's pages in the order a push walks them, and a pull reproduces: explicit `order:`, then
+ * numeric-prefix filename order, then the parent config's `pages:` list. Shared by the push's walk
+ * (`uwx/site.js::orderedSubfolders`) and the pull (`uwx/site-project.js`), so the two cannot
+ * disagree on what a level's order is.
+ *
+ * ⚠️ The build's own page-folder sort (`collectPagesRecursive`) is not this function: it compares
+ * folder names whole, as strings. The two differ only for numbered page folders — see the note at
+ * `orderedSubfolders`.
+ *
+ * @param {Array<{ dirName: string, name: string, order?: number }>} folders
+ * @param {Array} [parentPages] - the parent config's `pages:`
+ * @returns {Array} the folders, ordered
+ */
+function orderFolders(folders, parentPages) {
+  const sorted = [...folders].sort(
+    (a, b) => (a.order ?? Infinity) - (b.order ?? Infinity) || compareFilenames(a.dirName, b.dirName)
+  )
+  const parsed = Array.isArray(parentPages) ? parseWildcardArray(parentPages) : null
+  return parsed && parsed.mode !== 'all' ? applyWildcardOrder(sorted, parsed) : sorted
+}
+
 export {
   assertRouteFolder,
   buildRouteTranslations,
+  composeLocalizedRoute,
+  isValidSlugSegment,
+  declaredHomepage,
+  orderFolders,
   extractItemName,
   parseWildcardArray,
   applyWildcardOrder,

package/src/site/layout-folder.js

@@ -40,6 +40,21 @@ import { layoutNameKey } from '@uniweb/core/layout-name'
 /** The key the default layout's areas are held under, on every lane. */
 export const DEFAULT_LAYOUT = 'default'
 
+/**
+ * The route a layout area renders at — `/layout/<area>` in the default layout,
+ * `/layout/<layout>/<area>` in a named one. A layout area's free-form translations are
+ * addressed by it (`i18n/freeform.js`), so the build, the push and the pull must all use
+ * this one rule: the push said "layout sections have no free-form home" until 2026-09-26,
+ * and a translation the build rendered never left the author's machine.
+ *
+ * @param {string} [layoutName]
+ * @param {string} area
+ * @returns {string}
+ */
+export function layoutAreaRoute(layoutName, area) {
+  return !layoutName || layoutName === DEFAULT_LAYOUT ? `/layout/${area}` : `/layout/${layoutName}/${area}`
+}
+
 /**
  * Area names a layout folder is most likely to have been meant as. A folder under
  * `layout/` named like one of them was, before this convention, an area of the

package/src/site/queries-config.js

@@ -31,7 +31,8 @@
 import { join } from 'node:path'
 import { existsSync, readFileSync } from 'node:fs'
 import { recordLayout } from '@uniweb/schemas/conform'
-import { detectFoundationType } from './foundation-ref.js'
+import { detectFoundationType, parseCatalogRef } from './foundation-ref.js'
+import { readRegisteredFoundation } from './registered-foundation.js'
 import { buildDataSchemaMap, SCHEMA_NOT_FOUND } from '../resolve-data-schema.js'
 import { resolveFoundationSrcPath } from '../utils/foundation-source-root.js'
 import { refuseQueryRoute, refuseLimit } from './data-fetcher.js'
@@ -457,6 +458,12 @@ export function foundationDataSchemas(siteRoot, siteYml) {
  */
 export function foundationSchemaJson(siteRoot, siteYml) {
   if (!siteYml?.foundation) return null
+  // ⭐ A foundation named by catalog ref — every clone's — is read from the registered version the
+  // project keeps (`registered-foundation.js`): its section types, with their `data:`, and no data
+  // schemas, which travel as Models. Null until a push or a pull has read it.
+  if (parseCatalogRef(siteYml.foundation)) {
+    return readRegisteredFoundation(siteRoot, siteYml.foundation)?.schema || null
+  }
   let info
   try {
     info = detectFoundationType(siteYml.foundation, siteRoot)

package/src/site/query-processor.js

@@ -186,23 +186,34 @@ function extractPlainText(node) {
   if (node.type === 'text') {
     return node.text || ''
   }
+  if (node.type === 'hardBreak' || node.type === 'hard_break') return ' '
 
   if (Array.isArray(node.content)) {
-    return node.content.map(extractPlainText).join('')
+    // A textblock's inline children join as written; blocks are separated by a space. ⛔ Until
+    // 2026-09-26 blocks joined with nothing too, so an excerpt ran one paragraph into the next
+    // ("…in 1816.The river…").
+    const inline = node.content.every((child) => child?.type === 'text' || INLINE_NODES.has(child?.type))
+    return node.content.map(extractPlainText).join(inline ? '' : ' ')
   }
 
   return ''
 }
 
+// The inline nodes a textblock holds beside text.
+const INLINE_NODES = new Set(['hardBreak', 'hard_break', 'image', 'inset_ref', 'inset_placeholder', 'icon'])
+
 /**
  * Extract excerpt from content
  *
+ * Exported for the localized build (`i18n/records.js`), which derives each locale's
+ * excerpt from that locale's body by this same rule.
+ *
  * @param {Object} frontmatter - Parsed frontmatter
  * @param {Object} content - ProseMirror content
  * @param {Object} excerptConfig - Excerpt configuration
  * @returns {string} Excerpt text
  */
-function extractExcerpt(frontmatter, content, excerptConfig) {
+export function extractExcerpt(frontmatter, content, excerptConfig) {
   const { maxLength = 160, field = null } = excerptConfig || {}
 
   // Check for explicit excerpt in frontmatter

package/src/site/registered-foundation.js

@@ -0,0 +1,47 @@
+/**
+ * A REGISTERED FOUNDATION, AS A PROJECT THAT NAMES IT BY CATALOG REF KEEPS IT.
+ *
+ * A site whose foundation is a catalog ref (`@acme/fnd@1.2.0`) — every clone — has no build of it
+ * to read from. What the project's own tools need from it is its section types' `data:`, which is
+ * what types a query named for a data key (`uwx/data-key-types.js`). The CLI reads the registered
+ * version from the backend the site is on and keeps the reply here, under `.uniweb/`; the build,
+ * the push and the pull read it back through `foundationSchemaJson`.
+ *
+ * ⭐ A registered version never changes, so the copy never goes stale, and losing it costs a round
+ * trip, never a wrong answer: the next push or pull reads it again. That is what makes `.uniweb/`
+ * (gitignored, per copy) the right home for it.
+ *
+ * The reply is kept whole, as the backend answered it — its `schema` is the foundation schema a
+ * build would emit, less its data schemas, which travel as Models.
+ */
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs'
+import { dirname, join } from 'node:path'
+import { parseCatalogRef } from './foundation-ref.js'
+
+/** Where a project keeps a registered foundation's reply — null for anything but a catalog ref. */
+export function registeredFoundationPath(siteRoot, ref) {
+  const parsed = parseCatalogRef(ref)
+  if (!parsed) return null
+  return join(siteRoot, '.uniweb', 'foundations', parsed.scope, `${parsed.name}@${parsed.version}.json`)
+}
+
+/** The kept reply for a catalog ref, or null when the project keeps none. */
+export function readRegisteredFoundation(siteRoot, ref) {
+  const path = registeredFoundationPath(siteRoot, ref)
+  if (!path || !existsSync(path)) return null
+  try {
+    const reply = JSON.parse(readFileSync(path, 'utf8'))
+    return reply && typeof reply === 'object' ? reply : null
+  } catch {
+    return null
+  }
+}
+
+/** Keep a registered foundation's reply. Returns whether it was written. */
+export function writeRegisteredFoundation(siteRoot, ref, reply) {
+  const path = registeredFoundationPath(siteRoot, ref)
+  if (!path || !reply || typeof reply !== 'object') return false
+  mkdirSync(dirname(path), { recursive: true })
+  writeFileSync(path, JSON.stringify(reply, null, 2) + '\n')
+  return true
+}

package/src/uwx/asset-map.js

@@ -70,9 +70,14 @@ export function servedFingerprint(url) {
  * that works, not a local path to a file that is not there. Filling those in is
  * the download's job, not this one.
  *
- * `assetId` itself is not removed: it is not a markdown attribute, so the
- * serializer drops it on the way to disk, and leaving it lets a caller project
- * the same document twice without the second pass losing identity.
+ * ⭐ **And the identity goes with the URL it stood beside.** A restored reference is
+ * the author's path again, and that path's id is kept in `sync.json`, which the next
+ * push stamps from (`rewriteEntityAssets`). ⛔ Until 2026-09-26 `assetId` was left in
+ * place, on the ground that the markdown serializer drops it — true of a body, and of
+ * nothing else: a pull into the copy that pushed wrote `assetId`/`assetExt` into the
+ * frontmatter of every section whose background it restored, and a body holding a
+ * pushed image never compared as unchanged, since the author's markdown parses with
+ * no id. An id the map does not know keeps its identity, with its URL.
  *
  * @param {object} document - the site-content document (mutated in place)
  * @param {Record<string, { id: string, ext: string }>} map - readAssetMap()
@@ -98,6 +103,8 @@ export function restoreAssetRefs(document, map) {
       if (!ref) { stats.unknown++; continue }
       const urlAttr = slot.urls.find((k) => typeof node[k] === 'string') || slot.urls[0]
       node[urlAttr] = ref
+      delete node[slot.id]
+      delete node[slot.ext]
       stats.restored++
     }
     for (const v of Object.values(node)) visit(v)

package/src/uwx/backfill.js

@@ -32,7 +32,7 @@ import yaml from 'js-yaml'
 import { YAML_OPTIONS } from '../utils/yaml-schema.js'
 import { proseMirrorToMarkdown } from '@uniweb/content-writer'
 import { parseFrontmatter } from './entity-source.js'
-import { isProseMirrorField } from './data-schema.js'
+import { isProseMirrorField, isOpenMapSection, openMapFromRows } from './data-schema.js'
 import { recordFileLayout, contentBodyTarget } from './record-layout.js'
 import { unwrapLocalizedContent } from './locale-sync.js'
 import { parseBibtex, exportBibtex } from '@citestyle/bibtex'
@@ -254,7 +254,7 @@ const isPlainObject = (v) => v !== null && typeof v === 'object' && !Array.isArr
  *        it has no name for is written as the uuid.
  * @returns {string} the source-file text
  */
-export function renderEntityDocument({ document, declaration, format, sourceLocale = 'en', collector, freeformRelPath, refName }) {
+export function renderEntityDocument({ document, declaration, format, sourceLocale = 'en', collector, freeformRelPath, refName, context = null }) {
   const layout = recordFileLayout(declaration)
   if (layout.sections.length === 0) {
     throw new Error('uwx/render: the data schema declares no sections')
@@ -267,7 +267,7 @@ export function renderEntityDocument({ document, declaration, format, sourceLoca
   }
   // Markdown: the content body field, wherever its single section is, becomes the body.
   const { target } = contentBodyTarget(declaration)
-  const dec = { sourceLocale, collector, freeformRelPath, refName, bodyAt: format === 'md' ? target : null, body: '' }
+  const dec = { sourceLocale, collector, freeformRelPath, refName, context, bodyAt: format === 'md' ? target : null, body: '' }
 
   const record = {}
   if (document?.$uuid) record.$uuid = document.$uuid
@@ -307,7 +307,7 @@ function decodeRecord(fields, value, dec, sectionName) {
     const raw = value[key]
     if (raw === undefined) continue
     if (field?.type === 'section') {
-      out[key] = field.multiple === true ? decodeList(field, raw, dec) : decodeRecord(field.fields, raw, dec, null)
+      out[key] = field.multiple === true ? decodeSectionList(field, raw, dec) : decodeRecord(field.fields, raw, dec, null)
       continue
     }
     const isBody = Boolean(dec.bodyAt) && sectionName === dec.bodyAt.section && key === dec.bodyAt.key
@@ -318,6 +318,14 @@ function decodeRecord(fields, value, dec, sectionName) {
   return out
 }
 
+// A `many` field's records — an OPEN MAP's written back as the author's map, keyed by each row's
+// `name` (`isOpenMapSection`), which is what the push reads a map from. Rows that cannot be a map
+// stay a list, which the push reads too.
+function decodeSectionList(def, value, dec) {
+  const list = decodeList(def, value, dec)
+  return (isOpenMapSection(def) && openMapFromRows(list)) || list
+}
+
 // The records of a `many` section; a self-nesting one's `$children` nest back under
 // `children:`, the reserved key the push reads them from.
 function decodeList(def, value, dec) {
@@ -332,22 +340,25 @@ function decodeList(def, value, dec) {
 }
 
 // A leaf's authored value. A localized SCALAR's target locales are captured into the
-// collector (the content body's are captured by `unwrapLocalizedContent`, with its
-// free-form path); a list of localized values is unwrapped element by element.
+// collector — a markdown body's too, keyed by its whole text as the records extractor keys it
+// (a ProseMirror body's are captured by `unwrapLocalizedContent`, with its free-form path); a
+// list of localized values is unwrapped element by element. ⛔ Until 2026-09-26 a body was
+// taken to be ProseMirror, so a markdown one's translations were captured nowhere and a
+// clone rendered it in the source language.
 function decodeLeaf(raw, field, dec, isBody) {
   if (field?.type === 'entity_ref') return decodeReference(raw, field, dec)
   if (isProseMirrorField(field)) {
     const sourceDoc = field.localized
-      ? unwrapLocalizedContent(raw, dec.sourceLocale, dec.collector, isBody ? dec.freeformRelPath : undefined)
+      ? unwrapLocalizedContent(raw, dec.sourceLocale, dec.collector, isBody ? dec.freeformRelPath : undefined, null, dec.context)
       : raw
     return sourceDoc ? proseMirrorToMarkdown(sourceDoc) : ''
   }
   if (!field?.localized) return raw
   if (Array.isArray(raw)) {
-    if (!isBody) for (const item of raw) dec.collector?.add(item)
+    for (const item of raw) dec.collector?.add(item, dec.context)
     return unwrapLocalizedList(raw, dec.sourceLocale)
   }
-  if (!isBody) dec.collector?.add(raw)
+  dec.collector?.add(raw, dec.context)
   return unwrapLocalized(raw, dec.sourceLocale)
 }
 

package/src/uwx/data-schema.js

@@ -37,6 +37,40 @@ const CONTENT_TEXT_FORMATS = new Set(['markdown', 'html'])
 // declares its own `name` is an error instead, which names the problem precisely.
 const OPEN_MAP_KEY = 'name'
 
+/**
+ * ⭐ AN OPEN MAP'S LOWERED SECTION. `values:` lowers to rows (`lowerField`): a `multiple` section
+ * whose required string `name` — the map's key — is made each row's identity by a `unique_field`
+ * rule. A record FILE holds it as the author wrote it, a map from key to value; the WIRE holds the
+ * rows. This is the one test, read off the declaration alone, because a pull into a clone has
+ * nothing else: the push turns a file's map into rows by it, and the pull the rows back into a map.
+ */
+export function isOpenMapSection(def) {
+  if (def?.multiple !== true || def.self_nesting === true) return false
+  const key = def.fields?.[OPEN_MAP_KEY]
+  if (key?.type !== 'string' || key.required !== true || key.localized === true) return false
+  return (def.constraints || []).some((c) => c?.kind === 'unique_field' && c.field === OPEN_MAP_KEY && c.scope === 'section')
+}
+
+/** A file's open map as the rows it lowers to, in the map's key order: each key is its row's `name`. */
+export function openMapEntries(map) {
+  return Object.entries(map).map(([key, value]) => ({ key, value, row: { ...value, [OPEN_MAP_KEY]: key } }))
+}
+
+/**
+ * Rows back as the map a file holds, or null when they cannot be one — a row with no key, or a key
+ * two rows share — so a caller keeps them a list, which a push reads too, and nothing is lost.
+ */
+export function openMapFromRows(rows) {
+  const map = {}
+  for (const row of rows || []) {
+    const key = row?.[OPEN_MAP_KEY]
+    if (typeof key !== 'string' || key === '' || Object.hasOwn(map, key)) return null
+    const { [OPEN_MAP_KEY]: _key, ...value } = row
+    map[key] = value
+  }
+  return map
+}
+
 /**
  * A `text` field marked as rich content (`format: markdown` or `html`): the
  * file-based body target. Round-trips as the raw source string — what the retired

package/src/uwx/emit-surface.json

@@ -74,6 +74,12 @@
         "layout": [
           "site.yml::layout"
         ],
+        "og_description": [
+          "site.yml::seo"
+        ],
+        "og_title": [
+          "site.yml::seo"
+        ],
         "paths": [
           "site.yml::paths"
         ],

package/src/uwx/index.js

@@ -179,3 +179,12 @@ export {
 // is the foundation-less variant (only data-schema entities) for a schemas-only package.
 export { buildRegistryPackage, buildSchemaOnlyPackage } from './registry-package.js'
 export { toDataSchemaDeclaration } from './data-schema.js'
+
+// A registered foundation a project names by catalog ref — a clone's — kept under `.uniweb/` as the
+// backend answered for it, so the build, the push and the pull can read its section types.
+export {
+  registeredFoundationPath,
+  readRegisteredFoundation,
+  writeRegisteredFoundation,
+} from '../site/registered-foundation.js'
+export { parseCatalogRef } from '../site/foundation-ref.js'