@unitninety/site-kit 0.0.0-stage → 1.6.2

package/src/elements/ops/seed.ts

@@ -0,0 +1,185 @@
+import { SLOT, isLeaf, type DocumentDecl, type FieldDecl, type Issue, type ListDecl, type Schema, type SeedCtx, type ZoneDecl } from '../define'
+import { isDocumentId } from '../ids'
+import { zodIssues } from '../leaf'
+import { path } from '../path'
+import { CURRENT_CONTRACT, getElement } from '../registry'
+import { record } from '../containers/group'
+import { orderedEntries } from '../order'
+
+export class SeedError extends Error {
+  constructor(public failures: { path: string; message: string }[]) {
+    super(failures.map((f) => `${f.path}: ${f.message}`).join('\n'))
+    this.name = 'SeedError'
+  }
+}
+type Fail = (p: string, e: unknown) => void
+const collector = () => {
+  const failures: { path: string; message: string }[] = []
+  const fail: Fail = (p, e) => failures.push({ path: p, message: e instanceof Error ? e.message : String(e) })
+  return { failures, fail }
+}
+
+/** One declared field's stored value, from an explicit seed value or its declared default. */
+async function seedField(schema: Schema, decl: FieldDecl, v: unknown, ctx: SeedCtx, here: string, fail: Fail): Promise<unknown> {
+  if (isLeaf(decl)) {
+    const entry = getElement(decl.element)
+    const parsed = entry.options.safeParse(decl.options ?? {})
+    if (!parsed.success) { fail(here, 'The field’s declared options are invalid.'); return null }
+    const o = parsed.data
+    const input = v !== undefined ? v : decl.default
+    if (input === undefined) return entry.empty(o)
+    try { return await entry.toStored(entry.seed(o).parse(input), o, ctx) } catch (e) { fail(here, e); return entry.empty(o) }
+  }
+  if (decl.container === 'u90/group') {
+    const src = record(v) ? v : {}
+    const out: Record<string, unknown> = {}
+    for (const [name, f] of orderedEntries(decl.fields, decl.order)) out[name] = await seedField(schema, f, src[name], ctx, path.child(here, name), fail)
+    return out
+  }
+  if (decl.container === 'u90/list') {
+    const out: unknown[] = []
+    for (const item of Array.isArray(v) ? v : (decl.default ?? [])) out.push(await seedListItem(schema, decl, item, ctx, here, fail))
+    return out
+  }
+  const out: unknown[] = []
+  for (const item of Array.isArray(v) ? v : (decl.default ?? []).map((name) => ({ _block: name }))) {
+    const block = await seedZoneItem(schema, decl, item, ctx, here, fail)
+    if (block) out.push(block)
+  }
+  return out
+}
+async function seedListItem(schema: Schema, decl: ListDecl, item: unknown, ctx: SeedCtx, here: string, fail: Fail): Promise<Record<string, unknown>> {
+  const _id = ctx.newId()
+  const inner = await seedField(schema, decl.item, item, ctx, path.child(here, _id), fail)
+  return isLeaf(decl.item) ? { _id, _value: inner } : { _id, ...(inner as object) }
+}
+async function seedZoneItem(schema: Schema, decl: ZoneDecl, item: unknown, ctx: SeedCtx, here: string, fail: Fail): Promise<Record<string, unknown> | null> {
+  const _id = ctx.newId()
+  const block = record(item) && typeof item._block === 'string' ? item._block : ''
+  if (block === SLOT) return { _id, _block: SLOT }
+  const declared = Object.hasOwn(schema.blocks, block) ? schema.blocks[block] : undefined
+  if (!declared) { fail(path.child(here, _id), `No block named "${block}".`); return null }
+  if (!decl.allow.includes(block)) fail(path.child(here, _id), `"${block}" is not allowed here.`)
+  const { _block: _b, ...rest } = item as Record<string, unknown>
+  return { _id, _block: block, ...((await seedField(schema, { container: 'u90/group', fields: declared.fields, order: declared.order }, rest, ctx, path.child(here, _id), fail)) as object) }
+}
+
+/** Declared defaults, or an explicit seed value, to stored JSON. Every failing path is collected before throwing. */
+export async function seed(schema: Schema, docDecl: DocumentDecl, value: unknown, ctx: SeedCtx, at: string): Promise<unknown> {
+  const { failures, fail } = collector()
+  let doc: unknown
+  switch (docDecl.kind) {
+    case 'page':
+    case 'layout': {
+      // A blocks array, or `{ blocks }` (the stored document's own shape); absent means the zone's default blocks.
+      const blocks = Array.isArray(value) ? value : record(value) && Array.isArray(value.blocks) ? value.blocks : undefined
+      if (value !== undefined && blocks === undefined)
+        throw new SeedError([{ path: path.child(at, 'blocks'), message: 'Seed a page or layout with a blocks array, or { blocks }.' }])
+      doc = { _contract: CURRENT_CONTRACT, blocks: await seedField(schema, docDecl.blocks, blocks, ctx, path.child(at, 'blocks'), fail) }
+      break
+    }
+    case 'entry': {
+      const c = Object.hasOwn(schema.collections, docDecl.collection) ? schema.collections[docDecl.collection] : undefined
+      if (!c) throw new SeedError([{ path: at, message: `No collection named "${docDecl.collection}".` }])
+      const v = record(value) ? value : {}
+      doc = {
+        _contract: CURRENT_CONTRACT,
+        fields: await seedField(schema, { container: 'u90/group', fields: c.fields, order: c.order }, v.fields, ctx, path.child(at, 'fields'), fail),
+        ...(c.template ? { blocks: await seedField(schema, c.template, v.blocks, ctx, path.child(at, 'blocks'), fail) } : {}),
+      }
+      break
+    }
+    case 'single': {
+      const s = Object.hasOwn(schema.singles, docDecl.key) ? schema.singles[docDecl.key] : undefined
+      if (!s) throw new SeedError([{ path: at, message: `No Single named "${docDecl.key}".` }])
+      doc = { _contract: CURRENT_CONTRACT, value: await seedField(schema, s.field, value, ctx, at, fail) }
+    }
+  }
+  if (failures.length) throw new SeedError(failures)
+  return doc
+}
+
+/**
+ * One new item for a list or a zone, as the write path's `insert` stores it: a fresh `_id`, and every
+ * field filled from the declared defaults unless `value` gives it. A zone item names its block with
+ * `_block`; a SLOT cannot be inserted. Every failing path is collected and thrown as one SeedError.
+ */
+export async function seedItem(schema: Schema, decl: ListDecl | ZoneDecl, value: unknown, ctx: SeedCtx, at: string): Promise<Record<string, unknown>> {
+  if (decl.container === 'u90/zone' && record(value) && value._block === SLOT) throw new SeedError([{ path: at, message: 'A SLOT cannot be inserted.' }])
+  const { failures, fail } = collector()
+  const item = decl.container === 'u90/list' ? await seedListItem(schema, decl, value, ctx, at, fail) : await seedZoneItem(schema, decl, value, ctx, at, fail)
+  if (failures.length || !item) throw new SeedError(failures.length ? failures : [{ path: at, message: 'Nothing to insert.' }])
+  return item
+}
+
+export type SeedKnown = { page(key: string): boolean; entry(collection: string, key: string): boolean }
+/** The page and entry keys a leaf's parsed seed value names: a link's `to.page` or `to.entry`, a relation's or selection's `$ref`. */
+const namedKeys = (element: string, options: Record<string, unknown>, v: unknown): ({ page: string } | { entry: [string, string] })[] => {
+  const out: ({ page: string } | { entry: [string, string] })[] = []
+  if (element === 'u90/relation' || element === 'u90/selection')
+    for (const r of Array.isArray(v) ? v : [v])
+      if (record(r) && record(r.$ref) && typeof r.$ref.key === 'string')
+        out.push({ entry: [typeof r.$ref.collection === 'string' ? r.$ref.collection : String(options.to), r.$ref.key] })
+  if (element === 'u90/link' && record(v) && record(v.to)) {
+    const to = v.to
+    if (typeof to.page === 'string' && !isDocumentId(to.page)) out.push({ page: to.page })
+    if (record(to.entry) && typeof to.entry.collection === 'string' && typeof to.entry.key === 'string') out.push({ entry: [to.entry.collection, to.entry.key] })
+  }
+  return out
+}
+/**
+ * What seeding `value` would refuse, found without seeding: each leaf's seed value against its
+ * element's seed schema, unknown fields and blocks, and page or entry keys the site does not declare.
+ * `defineSite` runs it on every declared entry, because the build cannot wait on `seed`, which
+ * imports assets. List and zone items are named by position, having no `_id` yet.
+ */
+export function seedIssues(schema: Schema, docDecl: DocumentDecl, value: unknown, at: string, known: SeedKnown): Issue[] {
+  const issues: Issue[] = []
+  const add = (p: string, code: string, message: string): void => { issues.push({ path: p, code, message, severity: 'error' }) }
+  const field = (decl: FieldDecl, v: unknown, here: string): void => {
+    if (v === undefined || v === null) return
+    if (isLeaf(decl)) {
+      const entry = getElement(decl.element)
+      const o = entry.options.safeParse(decl.options ?? {})
+      if (!o.success) return add(here, 'invalid-options', 'The field’s declared options are invalid.')
+      const r = entry.seed(o.data).safeParse(v)
+      if (!r.success) return zodIssues(r.error).forEach((i) => add(path.child(here, ...i.path), i.code, i.message))
+      for (const k of namedKeys(decl.element, o.data as Record<string, unknown>, r.data)) {
+        if ('page' in k && !known.page(k.page)) add(here, 'unknown-page', `No page with the key "${k.page}" is declared.`)
+        if ('entry' in k && !known.entry(k.entry[0], k.entry[1])) add(here, 'unknown-entry', `No entry "${k.entry[1]}" is declared in ${k.entry[0]}.`)
+      }
+      return
+    }
+    if (decl.container === 'u90/group') {
+      if (!record(v)) return add(here, 'invalid_type', 'Expected an object of fields.')
+      for (const k of Object.keys(v)) if (!Object.hasOwn(decl.fields, k)) add(path.child(here, k), 'unknown-field', `No field named "${k}".`)
+      for (const [name, f] of orderedEntries(decl.fields, decl.order)) field(f, v[name], path.child(here, name))
+      return
+    }
+    if (!Array.isArray(v)) return add(here, 'invalid_type', decl.container === 'u90/list' ? 'Expected a list.' : 'Expected a list of blocks.')
+    if (decl.container === 'u90/list') return v.forEach((item, i) => field(decl.item, item, path.child(here, i)))
+    v.forEach((item, i) => {
+      const itemAt = path.child(here, i)
+      const block = record(item) && typeof item._block === 'string' ? item._block : ''
+      if (block === SLOT) return
+      const declared = Object.hasOwn(schema.blocks, block) ? schema.blocks[block] : undefined
+      if (!declared) return add(itemAt, 'unknown-block', `No block named "${block}".`)
+      if (!decl.allow.includes(block)) add(itemAt, 'not-allowed', `"${block}" is not allowed here.`)
+      const { _block: _b, ...rest } = item as Record<string, unknown>
+      field({ container: 'u90/group', fields: declared.fields, order: declared.order }, rest, itemAt)
+    })
+  }
+  if (docDecl.kind === 'entry') {
+    const c = Object.hasOwn(schema.collections, docDecl.collection) ? schema.collections[docDecl.collection] : undefined
+    if (!c) return [{ path: at, code: 'unknown-collection', message: `No collection named "${docDecl.collection}".`, severity: 'error' }]
+    const v = record(value) ? value : {}
+    field({ container: 'u90/group', fields: c.fields, order: c.order }, v.fields, path.child(at, 'fields'))
+    if (c.template) field(c.template, v.blocks, path.child(at, 'blocks'))
+  } else if (docDecl.kind === 'single') {
+    const s = Object.hasOwn(schema.singles, docDecl.key) ? schema.singles[docDecl.key] : undefined
+    if (s) field(s.field, value, at)
+  } else {
+    field(docDecl.blocks, Array.isArray(value) ? value : record(value) ? value.blocks : undefined, path.child(at, 'blocks'))
+  }
+  return issues
+}

package/src/elements/ops/text.ts

@@ -0,0 +1,20 @@
+import type { DocumentDecl, Schema } from '../define'
+import { hasStoredShape } from '../leaf'
+import { walkDocument } from '../walk'
+
+/** Every leaf's text, non-empty ones joined by newlines: for search, summaries and agents. */
+export function textOf(schema: Schema, docDecl: DocumentDecl, doc: unknown, at: string): string {
+  if ((docDecl.kind === 'entry' && !Object.hasOwn(schema.collections, docDecl.collection)) || (docDecl.kind === 'single' && !Object.hasOwn(schema.singles, docDecl.key))) return ''
+  const parts: string[] = []
+  walkDocument(schema, docDecl, doc, {
+    leaf: ({ entry, decl, value }) => {
+      if (value === undefined || value === null) return
+      const o = entry.options.safeParse(decl.options ?? {})
+      if (!o.success) return
+      if (!hasStoredShape(entry, o.data, value)) return
+      const t = entry.toText(value, o.data)
+      if (t) parts.push(t)
+    },
+  }, at)
+  return parts.join('\n')
+}

package/src/elements/ops/translatable.ts

@@ -0,0 +1,19 @@
+import type { DocumentDecl, Schema } from '../define'
+import { hasStoredShape } from '../leaf'
+import { path } from '../path'
+import { walkDocument } from '../walk'
+
+export function translatableParts(schema: Schema, docDecl: DocumentDecl, doc: unknown, at: string): { path: string; value: string }[] {
+  if ((docDecl.kind === 'entry' && !Object.hasOwn(schema.collections, docDecl.collection)) || (docDecl.kind === 'single' && !Object.hasOwn(schema.singles, docDecl.key))) return []
+  const out: { path: string; value: string }[] = []
+  walkDocument(schema, docDecl, doc, {
+    leaf: ({ entry, decl, value, at: here }) => {
+      if (value === undefined || value === null) return
+      const o = entry.options.safeParse(decl.options ?? {})
+      if (!o.success) return
+      if (!hasStoredShape(entry, o.data, value)) return
+      for (const part of entry.translatable(value, o.data)) out.push({ path: path.child(here, ...part.path), value: part.value })
+    },
+  }, at)
+  return out
+}

package/src/elements/ops/upgrade.ts

@@ -0,0 +1,43 @@
+import type { DocumentDecl, ElementEntry, Schema } from '../define'
+import type { ElementId } from '../ids'
+import { CONTRACTS, CURRENT_CONTRACT, elements } from '../registry'
+import { walkDocument } from '../walk'
+
+export class UpgradeError extends Error {
+  constructor(public path: string, public from: number, public to: number, public cause: unknown) {
+    super(`Upgrading ${path} from v${from} to v${to} failed: ${cause instanceof Error ? cause.message : String(cause)}`)
+    this.name = 'UpgradeError'
+  }
+}
+export type UpgradeOptions = { registry?: Record<ElementId, ElementEntry>; contracts?: Record<number, Record<ElementId, number>>; current?: number }
+
+/**
+ * Runs each leaf's upgrade chain from the element version recorded for `fromContract` up to the
+ * registry's current version, writes the results back, and stamps `_contract`. Reads run this on
+ * the fly; writes store the result. v1 ships no upgrades, so this is a stamp unless a registry with
+ * newer versions is passed (as the tests do).
+ */
+export function upgrade(schema: Schema, docDecl: DocumentDecl, doc: any, at: string, fromContract: number, opts: UpgradeOptions = {}): unknown {
+  const registry = opts.registry ?? (elements as Record<ElementId, ElementEntry>)
+  const contracts = opts.contracts ?? CONTRACTS
+  const current = opts.current ?? CURRENT_CONTRACT
+  const versions = contracts[fromContract]
+  if (!versions) throw new Error(`Unknown contract version ${fromContract}.`)
+  walkDocument(schema, docDecl, doc, {
+    leaf: ({ decl, value, at: here, set }) => {
+      if (value === undefined) return
+      const entry = registry[decl.element]
+      let v = versions[decl.element] ?? 1
+      let upgraded: unknown = value
+      while (v < entry.version) {
+        const step = entry.upgrade[v]
+        if (!step) throw new UpgradeError(here, v, v + 1, new Error(`${decl.element} has no upgrade from v${v}.`))
+        try { upgraded = step(upgraded) } catch (cause) { throw new UpgradeError(here, v, v + 1, cause) }
+        v++
+      }
+      if (upgraded !== value) set(upgraded)
+    },
+  }, at)
+  doc._contract = current
+  return doc
+}

package/src/elements/ops/validate.ts

@@ -0,0 +1,56 @@
+import { SLOT, type DocumentDecl, type Issue, type LeafIssue, type Mode, type Schema } from '../define'
+import { hasStoredShape, validateLeaf } from '../leaf'
+import { path } from '../path'
+import { walkDocument } from '../walk'
+import { record } from '../containers/group'
+
+export type ValidateOptions = { mode: Mode; previous?: unknown }
+
+const valueAtPointer = (doc: unknown, pointer: string): unknown =>
+  pointer === '' ? doc : pointer.slice(1).split('/').reduce<any>((n, seg) => (n == null ? undefined : n[seg.replace(/~1/g, '/').replace(/~0/g, '~')]), doc)
+const dig = (v: unknown, sub: string) => sub.split('.').reduce<any>((n, k) => (n == null ? undefined : n[k]), v)
+const slots = (v: unknown) => (Array.isArray(v) ? v.filter((x) => record(x) && x._block === SLOT).length : 0)
+
+export function validate(schema: Schema, docDecl: DocumentDecl, doc: unknown, at: string, opts: ValidateOptions): Issue[] {
+  const issues: Issue[] = []
+  const push = (base: string, i: LeafIssue) => issues.push({ path: path.child(base, ...i.path), code: i.code, message: i.message, severity: i.severity ?? 'error' })
+  const ids = new Map<string, string>()
+  const layoutRoot = docDecl.kind === 'layout' ? path.child(at, 'blocks') : null
+  const root = (p: string, code: string, message: string): Issue[] => [{ path: p, code, message, severity: 'error' }]
+  if (!record(doc)) return root(at, 'invalid_type', 'A stored document is an object.')
+  if (docDecl.kind === 'entry' && !Object.hasOwn(schema.collections, docDecl.collection)) return root(at, 'unknown-collection', `No collection named "${docDecl.collection}".`)
+  if (docDecl.kind === 'single' && !Object.hasOwn(schema.singles, docDecl.key)) return root(at, 'unknown-single', `No Single named "${docDecl.key}".`)
+  if (docDecl.kind === 'entry' && doc.fields !== undefined && !record(doc.fields)) return root(path.child(at, 'fields'), 'invalid_type', 'An entry stores its fields as an object.')
+  walkDocument(schema, docDecl, doc, {
+    enter: ({ container, decl, value, at: here }) => {
+      container.enter(decl, value, schema).forEach((i) => push(here, i))
+      if (container.id === 'u90/zone' && slots(value) !== (here === layoutRoot ? 1 : 0))
+        push(here, { path: [], code: 'slot', message: here === layoutRoot ? 'A layout holds exactly one SLOT.' : 'Only a layout may hold a SLOT.' })
+      if (Array.isArray(value))
+        for (const item of value)
+          if (record(item) && typeof item._id === 'string') {
+            if (ids.has(item._id)) push(here, { path: [], code: 'duplicate-id', message: `The id "${item._id}" is already used at ${ids.get(item._id)}.` })
+            else ids.set(item._id, here)
+          }
+    },
+    leaf: ({ entry, decl, value, at: here }) => {
+      validateLeaf(entry, decl, value, opts.mode).forEach((i) => push(here, i))
+      if (decl.lock?.length && opts.previous !== undefined) {
+        const pointer = path.toPointer(opts.previous, here)
+        const before = pointer === null ? undefined : valueAtPointer(opts.previous, pointer)
+        if (before !== undefined)
+          for (const sub of decl.lock)
+            if (JSON.stringify(dig(before, sub)) !== JSON.stringify(dig(value, sub)))
+              push(here, { path: sub.split('.'), code: 'locked', message: 'This part is set by the site and cannot be changed here.' })
+      }
+      if (value !== undefined && value !== null) {
+        const o = entry.options.safeParse(decl.options ?? {})
+        if (o.success && hasStoredShape(entry, o.data, value))
+          for (const ref of entry.refs(value, o.data, here))
+            if (ref.kind === 'single' && !Object.hasOwn(schema.singles, ref.key))
+              push(here, { path: [], code: 'unknown-single', message: `No Single named "${ref.key}".`, severity: 'warning' })
+      }
+    },
+  }, at)
+  return issues
+}

package/src/elements/order.ts

@@ -0,0 +1,10 @@
+/** A record's keys in declared order: the listed keys that exist, then any others in their stored order. */
+export function orderedKeys(record: Record<string, unknown>, order?: readonly string[]): string[] {
+  const keys = Object.keys(record)
+  if (!order?.length) return keys
+  const listed = order.filter((k, i) => Object.hasOwn(record, k) && order.indexOf(k) === i)
+  return [...listed, ...keys.filter((k) => !listed.includes(k))]
+}
+export function orderedEntries<T>(record: Record<string, T>, order?: readonly string[]): [string, T][] {
+  return orderedKeys(record, order).map((k) => [k, record[k]])
+}

package/src/elements/path.ts

@@ -0,0 +1,43 @@
+export { ID_RE, newId } from './ids'
+const KINDS = ['page', 'entry', 'layout', 'single'] as const
+export type DocKind = (typeof KINDS)[number]
+export type Path = string
+
+const doc = (kind: DocKind, id: string | number): Path => `${kind}:${id}`
+const child = (p: Path, ...segments: (string | number)[]): Path =>
+  segments.length ? `${p}/${segments.join('/')}` : p
+const parse = (p: Path): { kind: DocKind; id: string; segments: string[] } => {
+  const m = /^(page|entry|layout|single):([^/]+)(?:\/(.*))?$/.exec(p)
+  if (!m) throw new Error(`Not a u90 path: ${p}`)
+  return { kind: m[1] as DocKind, id: m[2], segments: m[3] ? m[3].split('/') : [] }
+}
+/**
+ * JSON Pointer (RFC 6901) of a path inside its document. Arrays are addressed by `_id`,
+ * and a leaf list item resolves to its `_value`. Returns null when a segment does not exist.
+ */
+const toPointer = (document: unknown, p: Path): string | null => {
+  const { kind, segments } = parse(p)
+  // A Single document is `{ value }`; its leaf sits at the document path itself.
+  let node: any = kind === 'single' ? (document as any)?.value : document
+  let pointer = kind === 'single' ? '/value' : ''
+  for (const seg of segments) {
+    if (Array.isArray(node)) {
+      const i = node.findIndex((item) => item && typeof item === 'object' && item._id === seg)
+      if (i < 0) return null
+      node = node[i]
+      pointer += `/${i}`
+      if (node && typeof node === 'object' && '_value' in node) {
+        node = node._value
+        pointer += '/_value'
+      }
+    } else if (node && typeof node === 'object' && seg in node) {
+      node = node[seg]
+      pointer += `/${seg.replace(/~/g, '~0').replace(/\//g, '~1')}`
+    } else return null
+  }
+  return pointer
+}
+export const path = { doc, child, parse, toPointer }
+
+/** A leaf's key in an overlay: its path inside the document, `blocks/<blockId>/headline`; '' for a Single's own leaf. */
+export const overlayKey = (at: Path): string => parse(at).segments.join('/')

package/src/elements/prefix.ts

@@ -0,0 +1,2 @@
+/** `route` under a language's address prefix (`/fr`): the home page is the prefix itself. It imports nothing, so the languages proxy can load it without the element registry. */
+export const prefixedRoute = (prefix: string, route: string): string => (route === '/' ? prefix : `${prefix}${route}`)

package/src/elements/registry.ts

@@ -0,0 +1,48 @@
+import type { ContainerEntry, ElementEntry, FieldDecl } from './define'
+import { ELEMENT_IDS, type ContainerId, type ElementId } from './ids'
+import { boolean } from './leaves/boolean'
+import { choice } from './leaves/choice'
+import { date } from './leaves/date'
+import { file } from './leaves/file'
+import { image } from './leaves/image'
+import { link } from './leaves/link'
+import { number } from './leaves/number'
+import { query } from './leaves/query'
+import { relation } from './leaves/relation'
+import { richText } from './leaves/rich-text'
+import { selection } from './leaves/selection'
+import { single } from './leaves/single'
+import { text } from './leaves/text'
+import { video } from './leaves/video'
+import { group } from './containers/group'
+import { list } from './containers/list'
+import { zone } from './containers/zone'
+
+/** Every element. `satisfies` fails the build if an id has no entry. */
+export const elements = {
+  'u90/text': text,
+  'u90/rich-text': richText,
+  'u90/image': image,
+  'u90/video': video,
+  'u90/file': file,
+  'u90/link': link,
+  'u90/date': date,
+  'u90/number': number,
+  'u90/boolean': boolean,
+  'u90/choice': choice,
+  'u90/relation': relation,
+  'u90/selection': selection,
+  'u90/query': query,
+  'u90/single': single,
+} satisfies Record<ElementId, ElementEntry>
+
+export const getElement = (id: ElementId): ElementEntry => elements[id] as ElementEntry
+
+export const CURRENT_CONTRACT = 1
+/** Which element version each contract version was written with. Add a row when any element's version changes. */
+export const CONTRACTS: Record<number, Record<ElementId, number>> = {
+  1: Object.fromEntries(ELEMENT_IDS.map((id) => [id, 1])) as Record<ElementId, number>,
+}
+
+export const containers = { 'u90/group': group, 'u90/list': list, 'u90/zone': zone } satisfies Record<ContainerId, ContainerEntry<any>>
+export const getContainer = (id: ContainerId): ContainerEntry<FieldDecl> => containers[id] as unknown as ContainerEntry<FieldDecl>

package/src/elements/tokens.ts

@@ -0,0 +1,14 @@
+/** `{key}` inside copy points at a Single. Keys are lower-case identifiers. */
+export const TOKEN = /\{([a-z][a-zA-Z0-9_-]*)\}/g
+export const tokenKeys = (s: string): string[] => [...s.matchAll(TOKEN)].map((m) => m[1])
+/** The text a Single's read value contributes inline: Text gives `text`, Link gives `label`. */
+export const textOfRead = (read: unknown): string | undefined => {
+  if (!read || typeof read !== 'object') return undefined
+  const r = read as Record<string, unknown>
+  if (typeof r.text === 'string') return r.text
+  if (typeof r.label === 'string') return r.label
+  return undefined
+}
+/** Unknown keys stay literal; `validate` reports them as `unknown-single` warnings. */
+export const resolveTokens = (s: string, single: (key: string) => unknown): string =>
+  s.replace(TOKEN, (match, key: string) => textOfRead(single(key)) ?? match)

package/src/elements/walk.ts

@@ -0,0 +1,42 @@
+import { isLeaf, type ContainerEntry, type DocumentDecl, type ElementEntry, type FieldDecl, type GroupDecl, type LeafDecl, type ListDecl, type Schema, type ZoneDecl } from './define'
+import { path } from './path'
+import { getContainer, getElement } from './registry'
+
+export type LeafNode = { entry: ElementEntry; decl: LeafDecl; value: unknown; at: string; set(v: unknown): void }
+export type ContainerNode = { container: ContainerEntry<FieldDecl>; decl: GroupDecl | ListDecl | ZoneDecl; value: unknown; at: string; set(v: unknown): void }
+export type Visitor = { leaf?(n: LeafNode): void; enter?(n: ContainerNode): void; exit?(n: ContainerNode): void }
+const noop = () => {}
+
+/** The only traversal. Depth first; containers are entered, their children walked, then exited. */
+export function walk(schema: Schema, decl: FieldDecl, value: unknown, visitor: Visitor, at: string, set: (v: unknown) => void = noop): void {
+  if (isLeaf(decl)) {
+    visitor.leaf?.({ entry: getElement(decl.element), decl, value, at, set })
+    return
+  }
+  const container = getContainer(decl.container)
+  const node: ContainerNode = { container, decl, value, at, set }
+  visitor.enter?.(node)
+  for (const child of container.children(decl, value, schema)) walk(schema, child.decl, child.value, visitor, path.child(at, child.key), child.set)
+  visitor.exit?.(node)
+}
+
+/** Stored document shapes: page/layout `{ blocks }`, entry `{ fields, blocks? }`, single `{ value }`. */
+export function walkDocument(schema: Schema, docDecl: DocumentDecl, doc: any, visitor: Visitor, at: string): void {
+  switch (docDecl.kind) {
+    case 'page':
+    case 'layout':
+      return walk(schema, docDecl.blocks, doc?.blocks, visitor, path.child(at, 'blocks'), (v) => { doc.blocks = v })
+    case 'entry': {
+      const collection = Object.hasOwn(schema.collections, docDecl.collection) ? schema.collections[docDecl.collection] : undefined
+      if (!collection) throw new Error(`No collection named "${docDecl.collection}".`)
+      walk(schema, { container: 'u90/group', fields: collection.fields, order: collection.order }, doc?.fields, visitor, path.child(at, 'fields'), (v) => { doc.fields = v })
+      if (collection.template) walk(schema, collection.template, doc?.blocks, visitor, path.child(at, 'blocks'), (v) => { doc.blocks = v })
+      return
+    }
+    case 'single': {
+      const single = Object.hasOwn(schema.singles, docDecl.key) ? schema.singles[docDecl.key] : undefined
+      if (!single) throw new Error(`No Single named "${docDecl.key}".`)
+      return walk(schema, single.field, doc?.value, visitor, at, (v) => { doc.value = v })
+    }
+  }
+}