@uniweb/build 0.16.17 → 0.16.19

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@uniweb/build",
-  "version": "0.16.17",
+  "version": "0.16.19",
   "description": "Build tooling for the Uniweb Component Web Platform",
   "type": "module",
   "exports": {
@@ -59,15 +59,16 @@
     "js-yaml": "^4.1.0",
     "sharp": "^0.35.3",
     "yaml": "^2.5.0",
+    "@uniweb/schemas": "0.2.7",
     "@uniweb/theming": "0.1.15",
-    "@uniweb/projections": "0.2.5",
-    "@uniweb/content-writer": "0.3.3"
+    "@uniweb/content-writer": "0.3.3",
+    "@uniweb/projections": "0.2.5"
   },
   "optionalDependencies": {
-    "@uniweb/content-reader": "1.2.2",
+    "@uniweb/schemas": "0.2.7",
+    "@uniweb/runtime": "0.9.8",
     "@uniweb/semantic-parser": "1.2.1",
-    "@uniweb/schemas": "0.2.5",
-    "@uniweb/runtime": "0.9.7"
+    "@uniweb/content-reader": "1.2.2"
   },
   "peerDependencies": {
     "vite": "^5.0.0 || ^6.0.0 || ^7.0.0",

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/site/emit-extensions.js

@@ -0,0 +1,129 @@
+/**
+ * Emit a workspace extension's built code into the site's own output.
+ *
+ * ── The gap this closes ──
+ *
+ * A site declares an extension by URL. The site-relative form —
+ * `extensions: ['/effects/entry.js']` — means "served from this site's own
+ * origin", and it is what the `extensions` template ships. But nothing ever put
+ * the file there.
+ *
+ * The result was a build that succeeds and a site that is wrong: prerender
+ * loads the extension from the workspace (via `resolveExtensionPath`) and
+ * renders its sections into the static HTML, then the browser fetches
+ * `/effects/entry.js`, gets a 404, `loadExtensions()` drops it, and hydration
+ * REPLACES the correct markup with `Component not found`. A visitor watches a
+ * working section break. Measured on the `extensions` template, 2026-08-05.
+ *
+ * ── Why here ──
+ *
+ * The build is the only party that knows both the declared URL and where the
+ * extension's `dist/` actually is, and the site's output is the only place the
+ * two can meet. This is the emission half of "site-hosted linked" — the shape
+ * the model doc lists as producible only by hand.
+ *
+ * ── What is emitted, and what is not ──
+ *
+ * The BROWSER delivery set. A foundation's `dist/` also carries things only
+ * other consumers want, and a static host should not serve them:
+ *
+ *   entry.js, assets/**       → emitted; the browser loads these
+ *   entry-ssr.js              → skipped; the single-file SSR twin, for an
+ *                               isolate that loads one module. Nothing on a
+ *                               static host reads it.
+ *   meta/**                   → skipped; the editor schema. Authoring-time, and
+ *                               not something to publish to visitors.
+ *   runtime-pin.json          → skipped; build provenance, read by no browser.
+ *   *.map                     → skipped; dev-only.
+ *
+ * Same browser/internal split the runtime's distribution channel draws, for the
+ * same reason: what a visitor fetches and what a renderer needs are different
+ * sets, and only one of them belongs on a public origin.
+ */
+
+import { existsSync, readdirSync, readFileSync, statSync } from 'node:fs'
+import { join, relative, resolve } from 'node:path'
+
+/** True for the `/effects/entry.js` form — the only one this site can serve. */
+export function isSiteRelative(decl) {
+  const url = typeof decl === 'string' ? decl : decl?.url
+  return typeof url === 'string' && url.startsWith('/') && !url.startsWith('//')
+}
+
+/** Every file under `dir`, relative to it. */
+function walk(dir, base = dir) {
+  if (!existsSync(dir)) return []
+  return readdirSync(dir).flatMap((entry) => {
+    const full = join(dir, entry)
+    return statSync(full).isDirectory() ? walk(full, base) : [relative(base, full)]
+  })
+}
+
+/** Is this file part of what a browser fetches? */
+function isBrowserAsset(rel) {
+  if (rel.endsWith('.map')) return false
+  if (rel === 'runtime-pin.json') return false
+  if (rel.startsWith('meta/') || rel.startsWith(`meta\\`)) return false
+  if (/(^|[/\\])entry-ssr\.js$/.test(rel)) return false
+  return true
+}
+
+/**
+ * Locate the built `dist/` behind a site-relative extension URL.
+ *
+ * The same candidates `resolveExtensionPath` walks for prerender, kept in step
+ * deliberately: if prerender can load an extension from the workspace but the
+ * build cannot find it to emit, that is exactly the split that produced the
+ * bug — one lane resolving it and the other not.
+ *
+ * @returns {{ distDir: string, urlBase: string }|null}
+ */
+export function resolveExtensionDist(url, siteDir) {
+  const parts = url.replace(/^\//, '').split('/')
+  if (parts.length < 2) return null
+  const pkgName = parts[0]
+  const projectRoot = resolve(siteDir, '..')
+
+  for (const candidate of [
+    join(projectRoot, pkgName, 'dist'),
+    join(projectRoot, 'extensions', pkgName, 'dist')
+  ]) {
+    if (existsSync(candidate)) return { distDir: candidate, urlBase: pkgName }
+  }
+  return null
+}
+
+/**
+ * Files to emit for a site's declared extensions.
+ *
+ * Returns `{ fileName, source }` pairs for Rollup's `emitFile`, plus the
+ * declarations that could not be resolved — the caller warns about those rather
+ * than failing, because an absolute-URL extension is legitimately not ours to
+ * emit and a missing workspace build is a warning the developer can act on.
+ *
+ * @param {Array} extensions - `site.yml::extensions`, as declared.
+ * @param {string} siteDir - the site package directory.
+ */
+export function collectExtensionAssets(extensions, siteDir) {
+  const emit = []
+  const unresolved = []
+  if (!Array.isArray(extensions)) return { emit, unresolved }
+
+  for (const decl of extensions) {
+    if (!isSiteRelative(decl)) continue // absolute URL or a ref — someone else serves it
+    const url = typeof decl === 'string' ? decl : decl.url
+    const found = resolveExtensionDist(url, siteDir)
+    if (!found) {
+      unresolved.push(url)
+      continue
+    }
+    for (const rel of walk(found.distDir)) {
+      if (!isBrowserAsset(rel)) continue
+      emit.push({
+        fileName: `${found.urlBase}/${rel.split('\\').join('/')}`,
+        source: readFileSync(join(found.distDir, rel))
+      })
+    }
+  }
+  return { emit, unresolved }
+}

package/src/site/plugin.js

@@ -52,6 +52,7 @@ import { processCollections, writeCollectionFiles } from './collection-processor
 import { executeFetch, mergeDataIntoContent } from './data-fetcher.js'
 import { shouldSplitContent } from './split-content.js'
 import { FONT_LINKS_MARKER } from './head-markers.js'
+import { collectExtensionAssets } from './emit-extensions.js'
 
 // BCP 47 locale code pattern: en, zh-CN, zh-Hant, pt-BR, fr-CA, sr-Latn, etc.
 const LOCALE_RE = '[a-z]{2,3}(?:-[A-Za-z]{2,4})?'
@@ -1464,6 +1465,25 @@ export function siteContentPlugin(options = {}) {
       // markdown (retrieval). Free and on by default; a site opts out under
       // `agents:` in site.yml.
       emitProjections.call(this, finalContent)
+
+      // A site-relative extension (`/effects/entry.js`) is served from the
+      // site's OWN origin, so the site's build is what has to put it there.
+      // Without this the build succeeds, prerender renders the extension's
+      // sections from the workspace, and the browser then 404s and replaces
+      // them with `Component not found` on hydration.
+      const { emit, unresolved } = collectExtensionAssets(
+        finalContent.config?.extensions,
+        resolve(sitePath)
+      )
+      for (const asset of emit) {
+        this.emitFile({ type: 'asset', fileName: asset.fileName, source: asset.source })
+      }
+      for (const url of unresolved) {
+        this.warn(
+          `Extension '${url}' is site-relative but no built extension was found for it. ` +
+            `The site will 404 on it at runtime — build the extension, or reference it by URL.`
+        )
+      }
     },
 
     closeBundle() {

package/src/uwx/data-schema.js

@@ -150,6 +150,15 @@ function lowerSection(def, resolve, optResolve, path = '') {
   const out = {}
   if ((def.kind || 'single') === 'multi') out.multiple = true
   if (def.brief === true) out.brief = true
+  // Display prose IS a section key — the registry stores it and keys it for
+  // translation as `section.<name>.label` / `.description` (confirmed 2026-08-05).
+  // Note the asymmetry with a LEAF, which is the opposite way round: a leaf's
+  // `label`/`description` are accepted by the registry's parser and then DROPPED,
+  // because a field declaration has no slot for prose — field labels live in
+  // translation rows (`section.<name>.field.<key>.label`), which this producer
+  // does not emit today. So section prose arrives; leaf prose does not.
+  if (def.label) out.label = def.label
+  if (def.description) out.description = def.description
   if (def.nestable) out.self_nesting = true
   if (def.append_only) out.append_only = true
 
@@ -182,13 +191,32 @@ function lowerSection(def, resolve, optResolve, path = '') {
   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)
+//   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
@@ -224,6 +252,7 @@ function lowerField(rawField, resolve, optResolve, path = '') {
         ...lowerSection(
           {
             kind: 'multi',
+            ...sectionProse(field),
             // `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
@@ -242,7 +271,7 @@ function lowerField(rawField, resolve, optResolve, path = '') {
     }
     return {
       type: 'section',
-      ...lowerSection({ kind: 'single', fields: field.fields }, resolve, optResolve, path)
+      ...lowerSection({ kind: 'single', ...sectionProse(field), fields: field.fields }, resolve, optResolve, path)
     }
   }
   if (type === 'array') {
@@ -250,46 +279,67 @@ function lowerField(rawField, resolve, optResolve, path = '') {
     if (items && items.type === 'object') {
       return {
         type: 'section',
-        ...lowerSection({ kind: 'multi', fields: items.fields }, resolve, optResolve, path)
+        ...lowerSection({ kind: 'multi', ...sectionProse(field), fields: items.fields }, resolve, optResolve, path)
       }
     }
-    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
-    }
-    // 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'
@@ -328,6 +378,18 @@ function asField(def) {
   return typeof def === 'string' ? { type: def } : (def && typeof def === 'object' ? def : {})
 }
 
+// A nested section is authored as a FIELD (`{ type: object, description: … }`),
+// but arrives on the wire as a section — so its prose has to travel from the
+// field declaration onto the section body, where the registry has a slot for it.
+// Without this an authored `description:` on a nested object was dropped twice
+// over: once by the normalizer, then again here.
+function sectionProse(field) {
+  const out = {}
+  if (field.label) out.label = field.label
+  if (field.description) out.description = field.description
+  return out
+}
+
 function shortName(name) {
   return String(name).split('/').pop()
 }

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.'
-    )
-  }
-}