@uniweb/build 0.16.16 → 0.16.18

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@uniweb/build",
-  "version": "0.16.16",
+  "version": "0.16.18",
   "description": "Build tooling for the Uniweb Component Web Platform",
   "type": "module",
   "exports": {
@@ -61,12 +61,13 @@
     "yaml": "^2.5.0",
     "@uniweb/content-writer": "0.3.3",
     "@uniweb/projections": "0.2.5",
+    "@uniweb/schemas": "0.2.6",
     "@uniweb/theming": "0.1.15"
   },
   "optionalDependencies": {
     "@uniweb/content-reader": "1.2.2",
     "@uniweb/runtime": "0.9.7",
-    "@uniweb/schemas": "0.2.5",
+    "@uniweb/schemas": "0.2.6",
     "@uniweb/semantic-parser": "1.2.1"
   },
   "peerDependencies": {

package/src/dev/plugin.js

@@ -26,6 +26,7 @@ import { readFile } from 'node:fs/promises'
 import { existsSync, readdirSync } from 'node:fs'
 import { build } from 'vite'
 import { resolveFoundationSrcPath } from '../utils/foundation-source-root.js'
+import { DEV_REBUILD_MARKER } from '../vite-foundation-plugin.js'
 
 /** Directories that never hold foundation source and must never be walked. */
 const UNWATCHABLE_DIRS = new Set(['node_modules', 'dist', 'build', 'coverage'])
@@ -126,6 +127,13 @@ export function foundationDevPlugin(options = {}) {
           root: resolvedFoundationPath,
           configFile: existsSync(configPath) ? configPath : false,
           logLevel: 'warn',
+          // Marks this as a dev rebuild so the foundation plugin skips the
+          // `entry-ssr.js` sub-build — a second full Vite pass, on every save,
+          // producing something nothing in the dev loop reads. A marker plugin
+          // rather than an option because the foundation's own vite.config.js
+          // constructs the plugin, not us; and rather than `mode`/`command`,
+          // which both say "build" here since this IS a real build.
+          plugins: [{ name: DEV_REBUILD_MARKER }],
           build: {
             outDir: 'dist',
             emptyOutDir: true,

package/src/resolve-data-schema.js

@@ -25,11 +25,14 @@
  * scope directory for that one name. Both take precedence over the '@org/schemas'
  * package convention (file over directory over package); see `loadSchemaAliases`.
  *
- * The authoring format and its canonical type vocabulary are documented in
- * `data-schema-format.md`. This module validates that format and normalizes the
- * friendly type aliases to the canonical kinds. Normalization is the only
- * transformation it performs — it does not lower the structure to any storage
- * model.
+ * The authoring format itself — the type vocabulary and the normalization of its
+ * friendly aliases to canonical kinds — lives in `@uniweb/schemas/format`, and is
+ * re-exported below so every existing import of this module keeps working. It was
+ * moved there because it is a contract with more than one consumer (this build,
+ * the `@uniweb/schemas` package's own `validate()`, and any tooling that reads a
+ * schema), and a reader that cannot reach it grows a second copy that drifts —
+ * which is exactly what had happened. This module keeps the half that needs a
+ * disk: finding a ref's file, alias routing, and closing the resolution graph.
  */
 
 import { readFile } from 'node:fs/promises'
@@ -39,42 +42,26 @@ import { pathToFileURL } from 'node:url'
 import { createRequire } from 'node:module'
 import yaml from 'js-yaml'
 
-// Extensions a foundation-local schema file may use, in resolution order.
-const SCHEMA_EXTENSIONS = ['.js', '.json', '.yml', '.yaml']
-
-// The authoring type vocabulary. Scalars + structural; aliases fold in below.
-// Exported so a conformance checker can speak the same definition of each kind
-// that normalization produces — "normalizes" and "conforms" stay in lockstep.
-export const SCALAR_KINDS = new Set([
-  'string', 'text', 'int', 'decimal', 'bool',
-  'date', 'datetime', 'file', 'json',
-])
-export const STRUCTURAL_KINDS = new Set(['object', 'array', 'ref'])
-// Friendly aliases → canonical kind.
-const TYPE_ALIASES = {
-  number: 'decimal',
-  integer: 'int',
-  boolean: 'bool',
-  image: 'file',
-}
-// Friendly type aliases that lower to a base kind + a carried `format` marker.
-// `url`/`email` → `string` (server-validated value subtypes). `markdown`/`html` →
-// `text` (a file-based rich-content body — round-trips as the raw source string).
-const FORMAT_TYPE_ALIASES = {
-  url: { type: 'string', format: 'url' },
-  email: { type: 'string', format: 'email' },
-  markdown: { type: 'text', format: 'markdown' },
-  html: { type: 'text', format: 'html' },
-  // `richtext` → a ProseMirror rich document (`json` + `format: prosemirror`): the
-  // framework's standard way to represent rich text — the structured, lossless form
-  // the visual app edits (text, media, tables, code, data blocks, icons, and inline
-  // components). Synced to file mode as enhanced markdown via content-writer. Contrast
-  // `markdown`/`html`, which are source-string bodies (raw text, no structured editor).
-  richtext: { type: 'json', format: 'prosemirror' },
-}
-// The advertised format-aliasing type words (drives the "Known types" hint).
-export const FORMAT_TYPES = new Set(['url', 'email', 'markdown', 'html', 'richtext'])
-export const SECTION_KINDS = new Set(['single', 'multi', 'binder'])
+import {
+  SCHEMA_EXTENSIONS,
+  parseSchemaRef,
+  validateAndNormalizeSchema,
+  collectNestedRefs,
+} from '@uniweb/schemas/format'
+
+// The authoring format, re-exported so this module stays the build's single
+// entry point for schema resolution + normalization (no call site moved when the
+// format itself did).
+export {
+  SCALAR_KINDS,
+  STRUCTURAL_KINDS,
+  FORMAT_TYPES,
+  SECTION_KINDS,
+  SCHEMA_EXTENSIONS,
+  parseSchemaRef,
+  validateAndNormalizeSchema,
+  collectNestedRefs,
+} from '@uniweb/schemas/format'
 
 // Scope → schema package resolution. The shared standard schemas are referenced
 // under '@std' but ship in the framework's '@uniweb/schemas' package; every
@@ -86,30 +73,6 @@ const SCOPE_PACKAGE = { std: '@uniweb/schemas' }
 const RESERVED_SYSTEM_SCOPE = 'uniweb'
 const packageForScope = (scope) => SCOPE_PACKAGE[scope] ?? `@${scope}/schemas`
 
-/**
- * Parse a data-schema ref into `{ scope, name }`.
- *   '@/member'       → { scope: '',    name: 'member' }   (self namespace)
- *   '@std/person'    → { scope: 'std', name: 'person' }
- */
-export function parseSchemaRef(ref) {
-  if (typeof ref !== 'string' || ref[0] !== '@') {
-    throw new Error(
-      `Invalid data-schema ref ${JSON.stringify(ref)}: must start with '@' ` +
-        `(e.g. '@/member' for this foundation, or '@std/person' for a shared standard).`
-    )
-  }
-  const slash = ref.indexOf('/')
-  if (slash === -1) {
-    throw new Error(`Invalid data-schema ref '${ref}': expected '@<scope>/<name>' (use '@/<name>' for this foundation).`)
-  }
-  const scope = ref.slice(1, slash) // '' for '@/...'
-  const name = ref.slice(slash + 1)
-  if (!name || name.includes('/')) {
-    throw new Error(`Invalid data-schema ref '${ref}': expected a single '<name>' segment after the namespace.`)
-  }
-  return { scope, name }
-}
-
 /**
  * Collect every distinct schema ref used by a foundation's section bindings.
  * Reads `data: { key: '<ref>' }` (short) and `data: { key: { schema: '<ref>' } }`
@@ -336,343 +299,6 @@ function resolvePackageEntryFile(packageDir, pkg) {
   return join(packageDir, entry || 'index.js')
 }
 
-// --- validation + normalization --------------------------------------------
-
-/**
- * Validate a schema definition against the authoring format and return a
- * normalized copy (type aliases folded to canonical kinds). Pure — no I/O.
- * Throws an Error naming the schema + the offending field/section.
- *
- * @param {Object} schema - the schema as authored
- * @param {string} ref - for error messages (e.g. '@/product')
- * @returns {Object} normalized schema
- */
-export function validateAndNormalizeSchema(schema, ref) {
-  if (!schema || typeof schema !== 'object' || Array.isArray(schema)) {
-    throw new Error(`Data schema '${ref}' did not export a schema object.`)
-  }
-
-  const out = {}
-  for (const k of ['name', 'version', 'description']) {
-    if (schema[k] !== undefined) out[k] = schema[k]
-  }
-
-  // The model's sort axis names a DATE FIELD IN THE BRIEF section (not a boolean,
-  // not a field-level flag) — the lowering stamps `sort_date: true` on that field.
-  // Authored as `sort_date` (the authoring vocabulary is snake_case, like
-  // `append_only`); `sortDate` is an accepted alias. Both normalize to `sortDate`,
-  // the single key the lowering reads — carrying the two spellings through verbatim
-  // meant an authored `sort_date` was silently dropped.
-  const sortDate = schema.sort_date ?? schema.sortDate
-  if (sortDate !== undefined) {
-    if (typeof sortDate !== 'string') {
-      throw new Error(
-        `Data schema '${ref}': 'sort_date' must name a date field in the brief section, got ${typeof sortDate}.`
-      )
-    }
-    out.sortDate = sortDate
-  }
-
-  const hasFields = schema.fields !== undefined
-  const hasSections = schema.sections !== undefined
-  if (hasFields && hasSections) {
-    throw new Error(`Data schema '${ref}': declare either 'fields' (shorthand) or 'sections', not both.`)
-  }
-  if (!hasFields && !hasSections) {
-    throw new Error(`Data schema '${ref}': must declare 'fields' or 'sections'.`)
-  }
-
-  if (hasSections) {
-    out.sections = normalizeSections(schema.sections, ref)
-  } else {
-    out.fields = normalizeFields(schema.fields, ref, '')
-  }
-  return out
-}
-
-function normalizeSections(sections, ref) {
-  if (!sections || typeof sections !== 'object' || Array.isArray(sections)) {
-    throw new Error(`Data schema '${ref}': 'sections' must be a map of section name → definition.`)
-  }
-  const briefState = { count: 0 }
-  const out = {}
-  for (const [name, section] of Object.entries(sections)) {
-    out[name] = normalizeSection(section, ref, `sections.${name}`, briefState)
-  }
-  return out
-}
-
-function normalizeSection(section, ref, path, briefState) {
-  if (!section || typeof section !== 'object' || Array.isArray(section)) {
-    throw new Error(`Data schema '${ref}': section '${path}' must be an object.`)
-  }
-  if (section.many !== undefined && typeof section.many !== 'boolean') {
-    throw new Error(`Data schema '${ref}': section '${path}' 'many' must be a boolean.`)
-  }
-  // Cardinality. Friendly sugar: `many: true` → a list of records; a section with
-  // only child `sections:` (no `fields:`) is a binder — inferred, never written.
-  // Explicit `kind:` is still honored (the lower-level form it normalizes to).
-  let kind = section.kind
-  if (kind === undefined) {
-    if (section.many === true) kind = 'multi'
-    else if (section.fields === undefined && section.sections !== undefined) kind = 'binder'
-    else kind = 'single'
-  }
-  if (!SECTION_KINDS.has(kind)) {
-    throw new Error(`Data schema '${ref}': section '${path}' has invalid kind '${kind}' (expected single | multi | binder).`)
-  }
-  const out = { kind }
-
-  if (section.brief === true) {
-    if (kind !== 'single') {
-      throw new Error(`Data schema '${ref}': brief section '${path}' must be a single record (drop 'many').`)
-    }
-    if (++briefState.count > 1) {
-      throw new Error(`Data schema '${ref}': more than one section marked 'brief: true' (at most one).`)
-    }
-    out.brief = true
-  }
-
-  if (kind === 'binder') {
-    if (section.fields !== undefined) {
-      throw new Error(`Data schema '${ref}': binder section '${path}' carries only child 'sections', not 'fields'.`)
-    }
-    if (section.sections === undefined) {
-      throw new Error(`Data schema '${ref}': binder section '${path}' must declare child 'sections'.`)
-    }
-  }
-  if (section.fields !== undefined) out.fields = normalizeFields(section.fields, ref, path)
-  if (section.sections !== undefined) {
-    const childBrief = { count: 0 }
-    out.sections = {}
-    for (const [n, s] of Object.entries(section.sections)) {
-      out.sections[n] = normalizeSection(s, ref, `${path}.sections.${n}`, childBrief)
-    }
-  }
-  if (section.constraints !== undefined) out.constraints = section.constraints
-
-  // `tree: true` (friendly) / `nestable: true` (lower-level) — a list section whose
-  // records form a tree among themselves. Carried into the IR so the lowering maps
-  // it to the model's `self_nesting`. The parent/child link is internal to the
-  // backend (`parent_item_id`); no explicit field expresses it.
-  const treeFlag = section.tree ?? section.nestable
-  if (treeFlag !== undefined) {
-    if (typeof treeFlag !== 'boolean') {
-      throw new Error(`Data schema '${ref}': section '${path}' 'tree' must be a boolean.`)
-    }
-    if (treeFlag && kind !== 'multi') {
-      throw new Error(`Data schema '${ref}': section '${path}' is 'tree: true' but not a list — only a 'many: true' section can form a tree.`)
-    }
-    if (treeFlag) out.nestable = true
-  }
-
-  // `append_only` — a multi whose records are insert-only: the backend accepts
-  // appends but refuses edits or deletes of existing items, so the section is
-  // tamper-evident (activity logs, submissions, audit trails). Carried into the IR
-  // verbatim for the submission lowering to emit as the model's `append_only`.
-  // Like `nestable`, only a `multi` section can be append-only.
-  if (section.append_only !== undefined) {
-    if (typeof section.append_only !== 'boolean') {
-      throw new Error(`Data schema '${ref}': section '${path}' 'append_only' must be a boolean.`)
-    }
-    if (section.append_only && kind !== 'multi') {
-      throw new Error(`Data schema '${ref}': section '${path}' is 'append_only: true' but not a list — only a 'many: true' section can be append-only.`)
-    }
-    if (section.append_only) out.append_only = true
-  }
-
-  return out
-}
-
-function normalizeFields(fields, ref, path) {
-  if (!fields || typeof fields !== 'object' || Array.isArray(fields)) {
-    throw new Error(`Data schema '${ref}': 'fields'${path ? ` in '${path}'` : ''} must be a map of field name → definition.`)
-  }
-  const out = {}
-  for (const [name, field] of Object.entries(fields)) {
-    out[name] = normalizeField(field, ref, path ? `${path}.${name}` : name)
-  }
-  return out
-}
-
-function normalizeField(field, ref, path) {
-  // Shorthand: a bare type string.
-  if (typeof field === 'string') field = { type: field }
-  if (!field || typeof field !== 'object' || Array.isArray(field)) {
-    throw new Error(`Data schema '${ref}': field '${path}' must be an object or a type string.`)
-  }
-
-  // Sugar: `many: true` → a list. Wrap the field-minus-`many` as the array's item
-  // type (lowers to the canonical `multiple`). The common cases —
-  // `{ ref: '@/x', many: true }`, `{ type: string, many: true }` — read as "a list
-  // of X" with no `array`/`items` ceremony.
-  if (field.many !== undefined) {
-    if (typeof field.many !== 'boolean') {
-      throw new Error(`Data schema '${ref}': field '${path}' 'many' must be a boolean.`)
-    }
-    if (field.many) {
-      // Collection-level metadata (required, default, label, help, description)
-      // rides on the array; the type-bearing attributes describe each item.
-      const ITEM_KEYS = new Set(['type', 'ref', 'options', 'enum', 'fields', 'items', 'format'])
-      const out = { type: 'array' }
-      const item = {}
-      for (const [k, v] of Object.entries(field)) {
-        if (k === 'many') continue
-        if (ITEM_KEYS.has(k)) item[k] = v
-        else out[k] = v
-      }
-      out.items = normalizeField(item, ref, `${path}[]`)
-      return out
-    }
-    const { many, ...rest } = field // many: false → a single value
-    field = rest
-  }
-
-  // Sugar: infer `type` from `ref:`/`options:` when omitted — `{ ref: '@/x' }` is a
-  // reference; `{ options: '@/x' }` is a curated picklist value.
-  if (field.type === undefined) {
-    if (typeof field.ref === 'string') field = { ...field, type: 'ref' }
-    else if (typeof field.options === 'string') field = { ...field, type: 'string' }
-  }
-
-  const rawType = field.type
-  if (typeof rawType !== 'string') {
-    throw new Error(`Data schema '${ref}': field '${path}' has no 'type'.`)
-  }
-
-  const out = {}
-  // Carry-through metadata (render hints / flags / value).
-  for (const k of ['required', 'default', 'label', 'help', 'description', 'translatable', 'format']) {
-    if (field[k] !== undefined) out[k] = field[k]
-  }
-
-  // Resolve the type: format-aliases (url/email → string; markdown/html → text;
-  // richtext → json) carry a `format` marker; else the plain alias map; else verbatim.
-  const formatAlias = FORMAT_TYPE_ALIASES[rawType]
-  if (formatAlias) {
-    out.type = formatAlias.type
-    out.format = field.format ?? formatAlias.format
-  } else {
-    out.type = TYPE_ALIASES[rawType] ?? rawType
-  }
-
-  if (!SCALAR_KINDS.has(out.type) && !STRUCTURAL_KINDS.has(out.type)) {
-    throw new Error(
-      `Data schema '${ref}': field '${path}' has unknown type '${rawType}'. ` +
-        `Known: ${[...SCALAR_KINDS, ...STRUCTURAL_KINDS, ...Object.keys(TYPE_ALIASES), ...FORMAT_TYPES].sort().join(', ')}.`
-    )
-  }
-
-  // Content `format` markers are registered per-shape (uwx-format.md §3): the
-  // rich-content markers `markdown`/`html` belong on a `text` field; `prosemirror`
-  // (a ProseMirror doc) and `scene` (a Scene Composition Format payload — an opaque
-  // structured blob the app edits via the Designer / visual canvas) both belong on
-  // a `json` field. Catch a mismatch at build time, not at publish (the backend
-  // rejects it). Value-validator formats (email/url) are unrestricted here.
-  if ((out.format === 'markdown' || out.format === 'html') && out.type !== 'text') {
-    throw new Error(
-      `Data schema '${ref}': field '${path}' has format '${out.format}', valid only on a 'text' field (got '${out.type}').`
-    )
-  }
-  if ((out.format === 'prosemirror' || out.format === 'scene') && out.type !== 'json') {
-    throw new Error(
-      `Data schema '${ref}': field '${path}' has format '${out.format}', valid only on a 'json' field (got '${out.type}').`
-    )
-  }
-
-  // Picklists: enum = inline list; options = a curated '@/x' ref (item_ref).
-  if (field.enum !== undefined) {
-    if (!Array.isArray(field.enum)) {
-      throw new Error(`Data schema '${ref}': field '${path}' 'enum' must be a list of values.`)
-    }
-    out.enum = field.enum
-  }
-  if (field.options !== undefined) {
-    if (typeof field.options !== 'string' || field.options[0] !== '@') {
-      throw new Error(
-        `Data schema '${ref}': field '${path}' 'options' must be a '@/<name>' ref to a curated options schema. ` +
-          `For an inline list use 'enum:'.`
-      )
-    }
-    parseSchemaRef(field.options) // shape-check the ref
-    out.options = field.options
-  }
-
-  // Structural kinds.
-  if (out.type === 'object') {
-    // Two ways to describe an object, and they answer different questions:
-    //
-    //   fields  the object's KNOWN keys — `{ street, city }`
-    //   values  an OPEN MAP whose keys belong to the author and whose values all
-    //           conform to one shape — `{ <anything>: <a field spec> }`
-    //
-    // `values` is to an object what `items` is to an array, and it exists for
-    // the same reason: a form's `fields` is a map keyed by author-chosen names
-    // (see `@std/form`), which could not be described at all until this landed.
-    // Requested by the editor team 2026-07-31 — the shape they needed and could
-    // not state in this vocabulary either.
-    if (field.values !== undefined && field.fields !== undefined) {
-      throw new Error(
-        `Data schema '${ref}': object field '${path}' declares both 'fields' and 'values'. ` +
-          `Use 'fields' for known keys, 'values' for an open map — not both.`
-      )
-    }
-    if (field.values !== undefined) {
-      out.values = normalizeField(field.values, ref, `${path}{}`)
-    } else if (field.fields === undefined) {
-      throw new Error(
-        `Data schema '${ref}': object field '${path}' must declare nested 'fields' (known keys) or 'values' (an open map).`
-      )
-    } else {
-      out.fields = normalizeFields(field.fields, ref, path)
-    }
-  } else if (out.type === 'array') {
-    // `items` (the element type) is recommended but optional — an array with
-    // no declared element type is an untyped list.
-    if (field.items !== undefined) {
-      out.items = normalizeField(field.items, ref, `${path}[]`)
-    }
-  } else if (out.type === 'ref') {
-    if (typeof field.ref !== 'string' || field.ref[0] !== '@') {
-      throw new Error(`Data schema '${ref}': ref field '${path}' must name a target schema, e.g. ref: '@/person'.`)
-    }
-    parseSchemaRef(field.ref)
-    out.ref = field.ref
-  }
-
-  return out
-}
-
-/**
- * Walk a normalized schema and collect every nested `ref`/`options` target —
- * the data schemas this one depends on. Used to close the resolution graph.
- *
- * @param {Object} schema - a normalized schema
- * @returns {string[]} distinct ref strings
- */
-export function collectNestedRefs(schema) {
-  const found = new Set()
-  const walkFields = (fields) => {
-    for (const field of Object.values(fields || {})) {
-      if (typeof field !== 'object' || !field) continue
-      if (typeof field.ref === 'string') found.add(field.ref)
-      if (typeof field.options === 'string') found.add(field.options)
-      if (field.fields) walkFields(field.fields)
-      if (field.items) walkFields({ _: field.items })
-      if (field.values) walkFields({ _: field.values })
-    }
-  }
-  const walkSections = (sections) => {
-    for (const section of Object.values(sections || {})) {
-      if (section?.fields) walkFields(section.fields)
-      if (section?.sections) walkSections(section.sections)
-    }
-  }
-  if (schema?.fields) walkFields(schema.fields)
-  if (schema?.sections) walkSections(schema.sections)
-  return [...found]
-}
-
 // --- internals --------------------------------------------------------------
 
 function findSelfSchemaFile(srcDir, name) {

package/src/uwx/data-schema.js

@@ -29,6 +29,14 @@ const TEXT_KINDS = new Set(['string', 'text'])
 // carrying one round-trips as the RAW source string (no ProseMirror conversion).
 const CONTENT_TEXT_FORMATS = new Set(['markdown', 'html'])
 
+// The field an open map's key lowers into. `name` matches the idiom already in use
+// for this shape (the backend's site-content `collections` section), so an open map
+// and a hand-authored row set produce the same wire shape rather than two spellings
+// of one thing. Not configurable on purpose: a second way to spell it would be a
+// vocabulary addition for a collision that does not exist yet — a value schema that
+// declares its own `name` is an error instead, which names the problem precisely.
+const OPEN_MAP_KEY = 'name'
+
 /**
  * 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
@@ -119,7 +127,7 @@ function lowerSectionsForm(sectionsMap, resolve, optResolve) {
   let explicit = null
   let firstSingle = null
   for (const [secName, def] of Object.entries(sectionsMap)) {
-    sections[secName] = lowerSection(def, resolve, optResolve)
+    sections[secName] = lowerSection(def, resolve, optResolve, secName)
     if (def.brief === true) explicit = secName
     if (!firstSingle && (def.kind || 'single') === 'single') firstSingle = secName
   }
@@ -138,7 +146,7 @@ function lowerSectionsForm(sectionsMap, resolve, optResolve) {
 // are type: section"); `nestable` → `self_nesting`; `append_only` (insert-only
 // records) passes through; authored cross-cutting `constraints` pass through as a
 // bare array. Leaves and nested sections share one ordered `fields:` namespace.
-function lowerSection(def, resolve, optResolve) {
+function lowerSection(def, resolve, optResolve, path = '') {
   const out = {}
   if ((def.kind || 'single') === 'multi') out.multiple = true
   if (def.brief === true) out.brief = true
@@ -147,74 +155,181 @@ function lowerSection(def, resolve, optResolve) {
 
   const fields = {}
   for (const [key, rawField] of Object.entries(def.fields || {})) {
-    fields[key] = lowerField(rawField, resolve, optResolve)
+    fields[key] = lowerField(rawField, resolve, optResolve, path ? `${path}/${key}` : key)
   }
   // Explicit child sections (sections-form, e.g. under a binder) → `type: section`
   // fields, in the same ordered namespace as the leaves.
   for (const [childName, childDef] of Object.entries(def.sections || {})) {
-    fields[childName] = { type: 'section', ...lowerSection(childDef, resolve, optResolve) }
+    const childPath = path ? `${path}/${childName}` : childName
+    fields[childName] = {
+      type: 'section',
+      ...lowerSection(childDef, resolve, optResolve, childPath)
+    }
+  }
+  // A section with neither leaves nor sub-sections carries nothing, and is not a
+  // valid section on this wire by either party's reckoning. Refusing here fails at
+  // the schema author's screen; emitting it fails in a consumer's restore, which is
+  // the last possible moment and the wrong screen (2026-08-04: `@std/form` shipped
+  // exactly this, because `values:` had no lowering and silently produced no fields).
+  if (!Object.keys(fields).length) {
+    throw new Error(
+      `Data schema: section '${path || '(root)'}' declares no fields and no sub-sections. ` +
+        `A section must carry at least one leaf or child section.`
+    )
   }
-  if (Object.keys(fields).length) out.fields = fields
+  out.fields = fields
   if (Array.isArray(def.constraints) && def.constraints.length) out.constraints = def.constraints
   return out
 }
 
-// Lower one field to its declaration value. Leaves carry their kind + attributes;
-// structural kinds become sections or multi-valued leaves:
-//   object           → a single nested section
+// Lower one field to its declaration value:
+//   object            → a single nested section
 //   array of object   → a multi nested section
-//   array of ref      → entity_ref + multiple
-//   array of scalar   → the scalar kind + multiple
-//   ref               → entity_ref (model by name)
-function lowerField(rawField, resolve, optResolve) {
+//   array of ref      → entity_ref + multiple      ┐
+//   array of scalar   → the scalar kind + multiple ├─ leaf-shaped: lowerLeaf
+//   ref               → entity_ref (model by name) │
+//   scalar            → the kind + its attributes  ┘
+//
+// Every LEAF-SHAPED output goes through `lowerLeaf`, which is the whole point of
+// the split: the field attributes (`label` / `description` / `required`, plus
+// `enum` / `format` / `localized`) are emitted in exactly one place, so a kind
+// cannot quietly miss them. They used to be emitted inline at the end of this
+// function, which each structural branch returned before reaching — so a
+// multi-valued leaf reached the wire as a bare `{ type, multiple }`, losing its
+// closed set, its format validation and its localization, and an `entity_ref`
+// lost its label/description/required while `item_ref` (which fell through)
+// kept them. That asymmetry between the two reference kinds is what gave the
+// bug away: nothing had decided it, the control flow had.
+//
+// SECTION-shaped outputs (`object`, `array of object`) still carry none of
+// those attributes. That is NOT settled — a section body's documented shape is
+// `multiple` / `brief` / `self_nesting` / `append_only` / `constraints` /
+// `fields`, so whether the wire accepts `label` / `description` / `required` on
+// a section is the consumer's contract to state, not ours to assume. Until it
+// does, an authored `required: true` on a nested object or a list of records is
+// still dropped here. `@std/publication`'s `authors` is exactly that case.
+function lowerField(rawField, resolve, optResolve, path = '') {
   const field = asField(rawField)
   const type = field.type
 
   if (type === 'object') {
-    return { type: 'section', ...lowerSection({ kind: 'single', fields: field.fields }, resolve, optResolve) }
+    // An OPEN MAP (`values:`) is ROWS, not a singleton. Its keys belong to the
+    // author, which makes them data — so the map lowers to a `multi` section whose
+    // key field carries what was the object key, with a section-scoped uniqueness
+    // rule making that key the row's identity. This is the same shape `array of
+    // object` already lowers to, and the idiom the backend's own site-content
+    // `collections` section uses; no new wire construct is involved.
+    //
+    // Identity is the KEY, never row position — a round-trip that rebuilds the map
+    // from order looks correct and drifts the first time rows are reordered.
+    // Authoring order is still preserved into row order, because for a form the
+    // field order is what the visitor sees.
+    if (field.values !== undefined) {
+      const value = asField(field.values)
+      if (value.type !== 'object' || !value.fields) {
+        throw new Error(
+          `Data schema: open map at '${path}' declares 'values' that is not an object with ` +
+            `'fields'. An open map lowers to rows, and a row needs declared columns.`
+        )
+      }
+      if (value.fields[OPEN_MAP_KEY]) {
+        throw new Error(
+          `Data schema: open map at '${path}' has a value field named '${OPEN_MAP_KEY}', which ` +
+            `is the field the map's key lowers into. Rename that field.`
+        )
+      }
+      return {
+        type: 'section',
+        ...lowerSection(
+          {
+            kind: 'multi',
+            // `translatable: false` is load-bearing, not tidiness: a string field is
+            // localized by default, and a localized key could differ per locale —
+            // which would destroy the identity the key exists to carry. The key is an
+            // identifier, never content.
+            fields: {
+              [OPEN_MAP_KEY]: { type: 'string', required: true, translatable: false },
+              ...value.fields
+            },
+            constraints: [{ kind: 'unique_field', field: OPEN_MAP_KEY, scope: 'section' }]
+          },
+          resolve,
+          optResolve,
+          path
+        )
+      }
+    }
+    return {
+      type: 'section',
+      ...lowerSection({ kind: 'single', fields: field.fields }, resolve, optResolve, path)
+    }
   }
   if (type === 'array') {
     const items = field.items ? asField(field.items) : null
     if (items && items.type === 'object') {
-      return { type: 'section', ...lowerSection({ kind: 'multi', fields: items.fields }, resolve, optResolve) }
-    }
-    if (items && items.type === 'ref') {
-      // Multi-valued reference — the per-field `multiple` flag (the `array` Kind
-      // that once forced a child multi section is retired).
-      const out = { type: 'entity_ref', multiple: true }
-      if (items.ref) out.model = resolve(items.ref)
-      return out
+      return {
+        type: 'section',
+        ...lowerSection({ kind: 'multi', fields: items.fields }, resolve, optResolve, path)
+      }
     }
-    // Array of scalars → a multi-valued leaf.
-    return { type: items ? items.type : 'string', multiple: true }
-  }
-  if (type === 'ref') {
-    const out = { type: 'entity_ref' }
-    if (field.ref) out.model = resolve(field.ref)
-    return out
+    // A multi-valued LEAF or REFERENCE. `normalizeField` split this field in two
+    // when it expanded `many: true` — collection-level metadata (`required`,
+    // `label`, `description`, `translatable`) stayed on the array, the
+    // type-bearing attributes (`type`, `ref`, `options`, `enum`, `format`) moved
+    // to `items` — so rejoin the halves and lower them as one leaf carrying
+    // `multiple: true`. Reading only `items.type` here is what silently dropped
+    // both halves' attributes; the rejoin is the exact inverse of the split.
+    const { items: _items, ...collection } = field
+    return lowerLeaf(
+      { ...collection, ...items, type: items ? items.type : 'string' },
+      resolve,
+      optResolve,
+      { multiple: true }
+    )
   }
 
-  // A leaf (scalar) kind. `richtext` is NOT a kind — it is the author alias for a
-  // ProseMirror document (`json` + `format: prosemirror`), normalized upstream in
-  // resolve-data-schema.js, so normalized IR never carries a raw `richtext` kind. The
-  // only way one could reach here is a STALE prebuilt schema.json (a foundation built
-  // before the 2026-06-02 kind retirement and loaded from dist/meta/schema.json without
-  // re-resolving). Fail locally — rebuild the foundation — rather than ship a kind the
-  // backend rejects.
-  if (type === 'richtext') {
+  return lowerLeaf(field, resolve, optResolve)
+}
+
+// Lower a LEAF-SHAPED field — a scalar, a reference (`entity_ref`), or a curated
+// picklist (`item_ref`) — with or without `multiple`. The single place field
+// attributes are emitted, so every leaf-shaped kind carries the same set.
+function lowerLeaf(field, resolve, optResolve, { multiple = false } = {}) {
+  const leafType = field.type
+
+  // `richtext` is NOT a kind — it is the author alias for a ProseMirror document
+  // (`json` + `format: prosemirror`), normalized upstream in resolve-data-schema.js,
+  // so normalized IR never carries a raw `richtext` kind. The only way one reaches
+  // here is a STALE prebuilt schema.json (a foundation built before the 2026-06-02
+  // kind retirement and loaded from dist/meta/schema.json without re-resolving).
+  // Fail locally — rebuild the foundation — rather than ship a kind the backend
+  // rejects. (Routing multi-valued leaves through here closes a hole: the old
+  // array branch never consulted this guard, so `richtext` could reach the wire
+  // as long as it was a list.)
+  if (leafType === 'richtext') {
     throw new Error(
       'This foundation carries the retired `richtext` kind in its built schema — ' +
         'rebuild it (`richtext` is now json + format: prosemirror).'
     )
   }
-  const leafType = type
   const leafFormat = field.format
 
   const out = { type: leafType }
+  if (multiple) out.multiple = true
   if (field.label) out.label = field.label
   if (field.description) out.description = field.description
   if (field.required) out.required = true
 
+  // A reference to a whole entity, hydrating to the target's brief. It is a
+  // FIELD, so it carries field attributes — the same ones `item_ref` below has
+  // always carried. Never localized: the text a reader sees belongs to the
+  // referenced entity, which localizes on its own.
+  if (leafType === 'ref') {
+    out.type = 'entity_ref'
+    if (field.ref) out.model = resolve(field.ref)
+    return out
+  }
+
   // A curated picklist is an item_ref (machine-ish — never localized).
   if (field.options !== undefined) {
     out.type = 'item_ref'

package/src/validate-data.js

@@ -6,23 +6,21 @@
  * question: *is my data correct according to the schemas I said it should
  * comply with?*
  *
- * Two layers:
+ * Two layers, and only the second one lives here:
  *   - `validateItem(schema, item)` — pure, facet-driven: walks a normalized
  *     schema's declared facets (required / type / enum / format / nested
- *     object+array) and emits one finding per failed facet. No I/O.
+ *     object+array / open map) and emits one finding per failed facet. No I/O.
+ *     It now lives in `@uniweb/schemas/conform`, beside the vocabulary it must
+ *     agree with, and is re-exported below so every caller here is unchanged.
  *   - `validateDataInputs({ siteRoot, foundationPath })` — the join: pairs each
  *     section's data input with the schema its `meta.js` binds to that key,
  *     validates each unique (file, schema) pair once, and attributes findings
- *     back to the sections that use it.
+ *     back to the sections that use it. This half needs a disk, so it stays.
  *
  * This is a pre-live dev/CI gate, not a render-time guard. The runtime stays
  * tolerant (apply defaults, ignore the rest); a wrong value is best caught
  * here, before a site is live — so the engine returns findings and the caller
  * decides whether they should fail a build (CI treats them as errors).
- *
- * The type vocabulary (`SCALAR_KINDS` / `FORMAT_TYPES`) is shared with the
- * schema normalizer, so what *normalizes* and what *conforms* speak one
- * definition of each kind.
  */
 
 import { readFile } from 'node:fs/promises'
@@ -31,218 +29,18 @@ import { join, resolve, basename } from 'node:path'
 import yaml from 'js-yaml'
 import { collectionNameFromUrl } from '@uniweb/core'
 
-import { SCALAR_KINDS, FORMAT_TYPES, validateAndNormalizeSchema } from './resolve-data-schema.js'
+import { validateItem, isStaticallyCheckable } from '@uniweb/schemas/conform'
+import { validateAndNormalizeSchema } from './resolve-data-schema.js'
+
+// The pure checker, re-exported so `@uniweb/build/validate` stays the one import
+// path callers know (`uniweb validate`, the CLI, and the contract tests all
+// reach it here) even though the implementation moved next to the vocabulary.
+export { validateItem, isStaticallyCheckable } from '@uniweb/schemas/conform'
 import { buildSchema } from './schema.js'
 import { resolveFoundationSrcPath } from './utils/foundation-source-root.js'
 import { collectSiteContent } from './site/content-collector.js'
 import { processCollections } from './site/collection-processor.js'
 
-// --- the pure validator -----------------------------------------------------
-
-/**
- * Validate one data item against a normalized data schema.
- *
- * Operates on the *normalized* schema (canonical kinds + `required` / `enum` /
- * `format` / nested `fields` / `items`) — the shape `dataSchemas[ref]` carries.
- * Facet-driven: each declared facet contributes its own check, so a new facet
- * in the schema model is covered without restructuring this function.
- *
- * Scope: a `fields`-form schema (the locally-testable case). A `sections`-form
- * (rich) schema describes the backend's section/item graph, which a flat file
- * can't reproduce — callers defer those rather than pass them here; given one,
- * this returns `[]`.
- *
- * @param {Object} schema - a normalized data schema (`{ fields }` or `{ sections }`)
- * @param {*} item - the data item to check
- * @returns {Array<{ field: string, rule: string, message: string }>}
- */
-export function validateItem(schema, item) {
-  if (!schema || typeof schema !== 'object') return []
-  if (schema.fields) return validateFields(schema.fields, item, '')
-  // `sections`-form schemas are deferred upstream (rich model — not reproducible
-  // from a flat file); this is a no-op safety net.
-  return []
-}
-
-/**
- * Whether a normalized schema can be checked statically against a flat file.
- * `fields`-form yes; `sections`-form no (the rich, backend-graph case).
- */
-export function isStaticallyCheckable(schema) {
-  return !!(schema && typeof schema === 'object' && schema.fields)
-}
-
-function validateFields(fields, obj, prefix) {
-  const out = []
-  const record = isPlainObject(obj) ? obj : {}
-  for (const [name, rawDef] of Object.entries(fields)) {
-    const def = asFieldDef(rawDef)
-    const path = prefix ? `${prefix}.${name}` : name
-    const has = Object.prototype.hasOwnProperty.call(record, name) && record[name] != null
-
-    // required — a promised field with no value. Don't flag a merely-absent
-    // optional field: the runtime fills it from `default` (or leaves it unset).
-    if (def.required === true && !has) {
-      out.push(violation(path, 'required', `missing required field '${path}'`))
-      continue
-    }
-    if (!has) continue
-
-    out.push(...validateValue(def, record[name], path))
-  }
-  return out
-}
-
-function validateValue(def, value, path) {
-  const out = []
-  const kind = def.type
-
-  // ref / options — a reference into the entity graph (entity_ref / item_ref).
-  // Its target isn't resolvable without the backend, so the value can't be
-  // checked statically. `required` already ran in validateFields; presence is
-  // all we can assert here.
-  if (kind === 'ref' || def.options !== undefined) return out
-
-  // enum (inline picklist) — the value must be one of the allowed set. Mirrors
-  // the runtime, which checks enum membership regardless of the base type, so a
-  // wrong-type-and-wrong-value lands as one clear enum finding (not two).
-  if (Array.isArray(def.enum)) {
-    if (!def.enum.includes(value)) {
-      out.push(violation(path, 'enum', `${fmt(value)} is not one of [${def.enum.map(fmt).join(', ')}]`))
-    }
-    return out
-  }
-
-  if (kind === 'object') {
-    if (!isPlainObject(value)) {
-      out.push(violation(path, 'type', `expected object, got ${typeName(value)}`))
-    } else if (def.fields) {
-      out.push(...validateFields(def.fields, value, path))
-    } else if (def.values) {
-      // An OPEN MAP: the keys are the author's, every value conforms to one
-      // shape. `values` is to an object what `items` is to an array.
-      //
-      // Note what this deliberately does NOT do: reject a key. It cannot — the
-      // keys are the whole point — and it must not reject unexpected keys
-      // WITHIN a value either, which falls out of `validateFields` walking the
-      // schema's fields rather than the data's. That tolerance is load-bearing
-      // for `@std/form`: a form definition may carry per-field keys the current
-      // builder cannot author (hand-written, or from a newer editor), and the
-      // editor's boundary passes them through untouched. A stricter check here
-      // would fail builds on good content.
-      for (const [key, item] of Object.entries(value)) {
-        out.push(...validateValue(def.values, item, `${path}.${key}`))
-      }
-    }
-    return out
-  }
-
-  if (kind === 'array') {
-    if (!Array.isArray(value)) {
-      out.push(violation(path, 'type', `expected array, got ${typeName(value)}`))
-    } else if (def.items !== undefined) {
-      const itemDef = asFieldDef(def.items)
-      value.forEach((el, i) => out.push(...validateValue(itemDef, el, `${path}[${i}]`)))
-    }
-    return out
-  }
-
-  // scalar kind
-  if (!isKind(kind, value)) {
-    out.push(violation(path, 'type', `expected ${kind}, got ${typeName(value)}`))
-    return out
-  }
-
-  // format (url / email) — only on present string scalars
-  if (typeof value === 'string' && FORMAT_TYPES.has(def.format)) {
-    if (def.format === 'email' && !isEmailish(value)) {
-      out.push(violation(path, 'format', `${fmt(value)} is not a valid email`))
-    } else if (def.format === 'url' && !isUrlish(value)) {
-      out.push(violation(path, 'format', `${fmt(value)} is not a valid url`))
-    }
-  }
-
-  return out
-}
-
-// Scalar kinds this checker knows how to verify. Kept in lockstep with the
-// normalizer's SCALAR_KINDS by the coverage guard at the bottom of this file —
-// adding a kind to the shared vocabulary without teaching the checker throws at
-// module load, rather than silently passing everything via the default branch.
-const KNOWN_SCALAR_KINDS = new Set([
-  'string', 'text', 'file',
-  'int', 'decimal', 'bool', 'date', 'datetime', 'json',
-])
-
-/**
- * Does a value match a canonical scalar kind?
- */
-function isKind(kind, value) {
-  switch (kind) {
-    case 'string':
-    case 'text':
-    case 'file':
-      return typeof value === 'string'
-    case 'int':
-      return typeof value === 'number' && Number.isInteger(value)
-    case 'decimal':
-      return typeof value === 'number' && Number.isFinite(value)
-    case 'bool':
-      return typeof value === 'boolean'
-    case 'date':
-    case 'datetime':
-      // YAML parses bare dates to Date objects; JSON carries them as strings.
-      return typeof value === 'string' || value instanceof Date
-    case 'json':
-      return true // structured / untyped — no scalar constraint
-    default:
-      return true // unknown kind → forward-compatible, not a violation
-  }
-}
-
-// Lenient format checks — strict enough to catch garbage, loose enough not to
-// flag the shapes authors legitimately write (bare domains, root-relative
-// paths). The north star is no false positives.
-function isEmailish(v) {
-  return /^[^@\s]+@[^@\s]+\.[^@\s]+$/.test(v.trim())
-}
-function isUrlish(v) {
-  const s = v.trim()
-  if (!s || /\s/.test(s)) return false
-  if (/^[a-z][a-z0-9+.-]*:\/\//i.test(s)) return true // scheme://
-  if (s.startsWith('//') || s.startsWith('/') || s.startsWith('./') || s.startsWith('../')) return true
-  if (/^[\w-]+(\.[\w-]+)+/.test(s)) return true // bare domain (example.com, sub.site.io/x)
-  return false
-}
-
-function violation(field, rule, message) {
-  return { field, rule, message }
-}
-
-function asFieldDef(def) {
-  // Normalized schemas always carry objects, but tolerate a bare type string
-  // (the authoring shorthand) so callers can validate against either form.
-  if (typeof def === 'string') return { type: def }
-  return def && typeof def === 'object' ? def : { type: undefined }
-}
-
-function isPlainObject(v) {
-  return v !== null && typeof v === 'object' && !Array.isArray(v) && !(v instanceof Date)
-}
-
-function typeName(v) {
-  if (v === null) return 'null'
-  if (Array.isArray(v)) return 'array'
-  if (v instanceof Date) return 'date'
-  return typeof v
-}
-
-function fmt(v) {
-  if (typeof v === 'string') return `"${v}"`
-  if (v instanceof Date) return v.toISOString()
-  return String(v)
-}
-
 // --- the join: sections ↔ schemas -------------------------------------------
 
 /**
@@ -631,14 +429,3 @@ function itemLabel(item, idx) {
   }
   return String(idx)
 }
-
-// Coverage guard — see KNOWN_SCALAR_KINDS. Every scalar kind the normalizer can
-// emit must be one this checker handles, so the two never drift apart silently.
-for (const kind of SCALAR_KINDS) {
-  if (!KNOWN_SCALAR_KINDS.has(kind)) {
-    throw new Error(
-      `validate-data: scalar kind '${kind}' is in the schema vocabulary but has ` +
-        'no conformance predicate. Add a case to isKind() and KNOWN_SCALAR_KINDS.'
-    )
-  }
-}

package/src/vite-foundation-plugin.js

@@ -466,6 +466,22 @@ async function buildEntrySSR(foundationRoot, entrySourcePath, outDir) {
   }
 }
 
+/**
+ * Marks a foundation build as a DEV-server rebuild.
+ *
+ * The dev server runs a real Vite `build()` of the foundation on every watched
+ * change (`dev/plugin.js`), so `command`, `mode` and `isProduction` cannot tell
+ * a dev rebuild from a shipping build — all of them say "build". An injected
+ * marker plugin can, and it survives the foundation's own `vite.config.js`
+ * being merged in, which a plugin *option* would not (the dev server does not
+ * construct the foundation plugin — the foundation's config file does).
+ *
+ * Used to skip the `entry-ssr.js` sub-build in dev: it is a second full Vite
+ * pass per save, and nothing in the dev loop reads it (dev never ships, and the
+ * SSR lanes that run locally — SSG prerender and unipress — load `entry.js`).
+ */
+export const DEV_REBUILD_MARKER = 'uniweb:dev-foundation-rebuild'
+
 /**
  * Vite plugin for foundation builds
  */
@@ -481,6 +497,7 @@ export function foundationBuildPlugin(options = {}) {
   let resolvedOutDir
   let resolvedRoot
   let isProduction
+  let isDevRebuild = false
 
   return {
     name: 'uniweb-foundation-build',
@@ -500,6 +517,7 @@ export function foundationBuildPlugin(options = {}) {
       resolvedOutDir = config.build.outDir
       resolvedRoot = config.root
       isProduction = config.mode === 'production'
+      isDevRebuild = (config.plugins || []).some((p) => p?.name === DEV_REBUILD_MARKER)
     },
 
     async writeBundle() {
@@ -554,8 +572,20 @@ export function foundationBuildPlugin(options = {}) {
       //
       // (The legacy self-contained buildSSRBundle() — React + runtime INLINED,
       // ~14 MB with Shiki — is retained below, unused, for reference only.)
-      const entrySourcePath = join(resolvedSrcDir, entryFileName)
-      await buildEntrySSR(resolvedRoot, entrySourcePath, outDir)
+      // Skipped on a DEV rebuild: this is a second full Vite pass, it runs on
+      // every save, and nothing in the dev loop reads its output. The local SSR
+      // lanes load `entry.js` (SSG prerender via `import()`, unipress the same);
+      // only the edge isolate needs the single-file twin, and dev ships nothing
+      // to it.
+      //
+      // Shipping lanes are unaffected — `uniweb build`, and `register`/`publish`
+      // which build through it. `register`'s build-if-stale check also requires
+      // `entry-ssr.js`, so a dist left behind by a dev session is treated as
+      // stale and rebuilt rather than uploaded without one.
+      if (!isDevRebuild) {
+        const entrySourcePath = join(resolvedSrcDir, entryFileName)
+        await buildEntrySSR(resolvedRoot, entrySourcePath, outDir)
+      }
     },
 
     async closeBundle() {