@unitninety/site-kit 0.0.0-stage → 1.6.1

package/src/elements/leaves/text.ts

@@ -0,0 +1,103 @@
+import { z } from 'zod'
+import { TEL_RE, URL_RE, defineElement, requiredIssue } from '../define'
+import { TOKEN, resolveTokens, textOfRead, tokenKeys } from '../tokens'
+
+export const TextOptions = z.strictObject({
+  multiline: z.boolean().default(false),
+  format: z.enum(['plain', 'email', 'tel', 'url', 'code']).default('plain'),
+  maxLength: z.int().positive().optional(),
+  /** Checked here so a bad pattern is a declaration issue, never a throw from the stored schema's check. */
+  pattern: z
+    .string()
+    .refine((p) => { try { new RegExp(p); return true } catch { return false } }, 'pattern must be a valid regular expression')
+    .optional(),
+})
+type O = z.infer<typeof TextOptions>
+
+const FORMAT_MESSAGE: Record<O['format'], string> = {
+  plain: '',
+  code: '',
+  email: 'Expected an email address.',
+  tel: 'Expected a phone number.',
+  url: 'Expected an absolute URL or a root-relative path.',
+}
+const formatOk = (v: string, format: O['format']) =>
+  v === '' ||
+  format === 'plain' ||
+  format === 'code' ||
+  (format === 'email' && z.email().safeParse(v).success) ||
+  (format === 'tel' && TEL_RE.test(v)) ||
+  (format === 'url' && URL_RE.test(v))
+
+const stored = (o: O) => {
+  let s = z.string()
+  if (o.maxLength) s = s.max(o.maxLength)
+  return s.superRefine((v, ctx) => {
+    if (!o.multiline && /[\r\n]/.test(v))
+      ctx.addIssue({ code: 'custom', message: 'Line breaks are not allowed here.', params: { code: 'multiline' } })
+    if (!formatOk(v, o.format))
+      ctx.addIssue({ code: 'custom', message: FORMAT_MESSAGE[o.format], params: { code: 'format' } })
+    if (o.pattern && v !== '' && !new RegExp(o.pattern).test(v))
+      ctx.addIssue({ code: 'custom', message: 'Does not match the required pattern.', params: { code: 'pattern' } })
+  })
+}
+/** A draft read's pieces: plain text, and each resolved `{key}` token as its Single's text, so a draft render can mark it and an edit can save the token back (R38). */
+export type TextSegment = string | { key: string; text: string }
+export type TextRead = { text: string; segments?: TextSegment[]; $path?: string }
+
+const segmentsOf = (v: string, single: (key: string) => unknown): TextSegment[] | undefined => {
+  const out: TextSegment[] = []
+  let last = 0
+  let resolved = false
+  for (const m of v.matchAll(TOKEN)) {
+    const t = textOfRead(single(m[1]))
+    if (t === undefined) continue // an unknown key stays literal, inside the surrounding text
+    if (m.index! > last) out.push(v.slice(last, m.index))
+    out.push({ key: m[1], text: t })
+    resolved = true
+    last = m.index! + m[0].length
+  }
+  if (!resolved) return undefined
+  if (last < v.length) out.push(v.slice(last))
+  return out
+}
+const read = z.object({
+  text: z.string(),
+  segments: z.array(z.union([z.string(), z.object({ key: z.string(), text: z.string() })])).optional(),
+  $path: z.string().optional(),
+})
+/** A validated write can never store non-string text (the stored schema is `z.string()`); this guards a render against bad data. */
+const expand = (v: string, o: O, ctx: { at: string; draft: boolean; single(key: string): unknown }): TextRead => {
+  const marker = ctx.draft ? { $path: ctx.at } : {}
+  if (typeof v !== 'string') return { text: '', ...marker }
+  if (o.format === 'code') return { text: v, ...marker }
+  const segments = ctx.draft ? segmentsOf(v, ctx.single) : undefined
+  return { text: resolveTokens(v, ctx.single), ...(segments ? { segments } : {}), ...marker }
+}
+
+export const text = defineElement({
+  id: 'u90/text',
+  version: 1,
+  label: 'Text',
+  placement: 'any',
+  options: TextOptions,
+  seed: stored,
+  stored,
+  read: () => read,
+  complete: (v, o, field) => requiredIssue(typeof v === 'string' && v.trim() !== '', field),
+  /** Guards a non-string (bad data the stored schema rejects) so collecting refs never throws. */
+  refs: (v, o) => (o.format === 'code' || typeof v !== 'string' ? [] : tokenKeys(v).map((key) => ({ kind: 'single' as const, key }))),
+  toStored: async (seed) => seed,
+  expand,
+  expandSeed: expand,
+  toText: (v) => v,
+  translatable: (v, o) => (o.format === 'plain' && v !== '' ? [{ path: [], value: v }] : []),
+  translation: {
+    applies: (o) => o.format === 'plain',
+    value: (o) => stored(o),
+    pick: (v) => (v === '' ? null : v),
+    apply: (_base, t) => t,
+  },
+  empty: () => '',
+  upgrade: {},
+})

package/src/elements/leaves/video.ts

@@ -0,0 +1,108 @@
+import { z } from 'zod'
+import { Id, MediaAssetSchema, defineElement, requiredIssue, type ExpandCtx, type MediaAsset, type MediaRecord, type Ref, type SeedCtx } from '../define'
+import { ImageOptions, expandImage, image, imageSeed, imageStored, imageToStored, type ImageRead } from './image'
+
+export const VideoOptions = z.strictObject({
+  poster: z.strictObject({ label: z.string().optional(), ...ImageOptions.shape }).default({ variants: {} }),
+})
+type O = z.infer<typeof VideoOptions>
+const posterOptions = (o: O) => ImageOptions.parse({ constraints: o.poster.constraints, variants: o.poster.variants })
+
+const seconds = z.number().nonnegative()
+const settings = {
+  posterTime: seconds,
+  startTime: seconds,
+  endTime: seconds.nullable(),
+  autoplay: z.boolean(),
+  muted: z.boolean(),
+  loop: z.boolean(),
+  controls: z.boolean(),
+  playsInline: z.boolean(),
+  preload: z.enum(['none', 'metadata', 'auto']),
+}
+const rules = (v: { startTime: number; endTime: number | null; autoplay: boolean; muted: boolean }, ctx: z.RefinementCtx) => {
+  if (v.endTime !== null && v.endTime <= v.startTime)
+    ctx.addIssue({ code: 'custom', path: ['endTime'], message: 'End time must be after start time.', params: { code: 'end-before-start' } })
+  if (v.autoplay && !v.muted)
+    ctx.addIssue({ code: 'custom', path: ['muted'], message: 'Autoplay requires muted playback.', params: { code: 'autoplay-muted' } })
+}
+const stored = (o: O) => z.strictObject({ asset: Id, poster: imageStored(posterOptions(o)), ...settings }).superRefine(rules).nullable()
+type Stored = z.infer<ReturnType<typeof stored>>
+const DEFAULTS = { posterTime: 0, startTime: 0, endTime: null, autoplay: false, muted: true, loop: false, controls: true, playsInline: true, preload: 'metadata' as const }
+const seed = (o: O) =>
+  z
+    .strictObject({
+      asset: z.union([Id, z.strictObject({ source: z.string().trim().min(1) })]),
+      poster: imageSeed(posterOptions(o)).default(null),
+      posterTime: seconds.default(0),
+      startTime: seconds.default(0),
+      endTime: seconds.nullable().default(null),
+      autoplay: z.boolean().default(false),
+      muted: z.boolean().default(true),
+      loop: z.boolean().default(false),
+      controls: z.boolean().default(true),
+      playsInline: z.boolean().default(true),
+      preload: z.enum(['none', 'metadata', 'auto']).default('metadata'),
+    })
+    .superRefine(rules)
+    .nullable()
+
+export type MediaAssetRead = MediaAsset
+export const mediaAssetRead = (m: MediaRecord | undefined): { asset: MediaAssetRead | null; status: 'ready' | 'missing' } => {
+  if (!m) return { asset: null, status: 'missing' }
+  const { renditions: _r, ...asset } = m
+  return { asset, status: 'ready' }
+}
+export type VideoRead = ({ asset: MediaAssetRead | null; status: 'ready' | 'missing'; poster: ImageRead } & z.infer<z.ZodObject<typeof settings>> & { $path?: string }) | null
+const read = (o: O) => z.object({ asset: MediaAssetSchema.nullable(), status: z.enum(['ready', 'missing']), poster: image.read(posterOptions(o)), ...settings, $path: z.string().optional() }).nullable()
+const expand = (v: Stored, o: O, ctx: ExpandCtx): VideoRead => {
+  if (v === null) return null
+  const { asset, poster, ...rest } = v
+  return { ...mediaAssetRead(ctx.media(asset)), poster: expandImage(poster, posterOptions(o), { ...ctx, at: `${ctx.at}/poster` }), ...rest, ...(ctx.draft ? { $path: ctx.at } : {}) }
+}
+
+export const video = defineElement({
+  id: 'u90/video',
+  version: 1,
+  label: 'Video',
+  placement: 'any',
+  options: VideoOptions,
+  seed,
+  stored,
+  read,
+  complete: (v, o, field) => {
+    if (v == null) return requiredIssue(false, field)
+    return image.complete(v.poster, posterOptions(o), { required: false, hasDefault: false }).map((i) => ({ ...i, path: ['poster', ...i.path] }))
+  },
+  refs: (v, o) => (v ? [{ kind: 'media', id: v.asset } as Ref, ...image.refs(v.poster, posterOptions(o), '')] : []),
+  toStored: async (s, o, ctx: SeedCtx) => {
+    if (s === null) return null
+    const { asset, poster, ...rest } = s
+    return { asset: typeof asset === 'object' ? await ctx.importAsset(asset.source) : asset, poster: await imageToStored(poster, posterOptions(o), ctx), ...rest }
+  },
+  expand,
+  expandSeed: (s, o, ctx) => {
+    if (s === null) return null
+    const { asset, poster, ...rest } = s
+    const src = typeof asset === 'object' ? asset.source : null
+    const a = src ? { asset: { id: src, url: src, mimeType: '', width: null, height: null, filename: src.split('/').pop() ?? src }, status: 'ready' as const } : mediaAssetRead(ctx.media(asset as Id))
+    return { ...a, poster: image.expandSeed(poster, posterOptions(o), { ...ctx, at: `${ctx.at}/poster` }), ...DEFAULTS, ...rest, ...(ctx.draft ? { $path: ctx.at } : {}) }
+  },
+  toText: (v, o) => (v ? image.toText(v.poster, posterOptions(o)) : ''),
+  translatable: (v, o) => (v ? image.translatable(v.poster, posterOptions(o)).map((t) => ({ ...t, path: ['poster', ...t.path] })) : []),
+  // A video translates its poster's alt text and caption, through the image codec (ruling R13).
+  translation: {
+    applies: () => true,
+    // A video with no poster has nothing to translate, as an image with no value has not.
+    present: (v) => v !== null && v.poster !== null,
+    value: (o) => image.translation!.value(posterOptions(o)),
+    pick: (v, o) => (v ? image.translation!.pick(v.poster, posterOptions(o)) : null),
+    apply: (base, t, o) => {
+      if (!base) return undefined
+      const poster = image.translation!.apply(base.poster ?? undefined, t, posterOptions(o))
+      return poster === undefined ? undefined : { ...base, poster }
+    },
+  },
+  empty: () => null,
+  upgrade: {},
+})

package/src/elements/ops/expand.ts

@@ -0,0 +1,94 @@
+import { SLOT, isLeaf, type DocumentDecl, type EntryRead, type EntryRecord, type ExpandCtx, type FieldDecl, type Id, type MediaRecord, type PageRecord, type Schema } from '../define'
+import { expandLeaf } from '../leaf'
+import { path } from '../path'
+import { getContainer, getElement } from '../registry'
+import { record } from '../containers/group'
+import { prefixedRoute } from '../prefix'
+
+export type Resolved = {
+  media?: Map<string, MediaRecord>
+  pages?: Map<string, PageRecord>
+  /** Singles already expanded to their read values by the caller. */
+  singles?: Map<string, unknown>
+  entries?: Map<string, EntryRecord>
+  queries?: Map<string, { ids: Id[]; total: number }>
+  inverses?: Map<string, Id[]>
+}
+export const entryKey = (collection: string, id: Id) => `${collection}:${id}`
+export const queryKey = (collection: string, query: unknown) => `${collection}:${JSON.stringify(query ?? {})}`
+export const inverseKey = (collection: string, field: string, id: Id) => `${collection}.${field}=${id}`
+
+const MAX_DEPTH = 3
+export function makeCtx(schema: Schema, r: Resolved, at: string, draft: boolean, budget = MAX_DEPTH, fallbacks?: ReadonlySet<string>, draftLocale?: string, localePrefix?: string): ExpandCtx {
+  const under = (route: string) => (localePrefix ? prefixedRoute(localePrefix, route) : route)
+  const ctx: ExpandCtx = {
+    at,
+    draft,
+    ...(draft && fallbacks?.size ? { fallbacks } : {}),
+    ...(draftLocale ? { draftLocale } : {}),
+    media: (id) => r.media?.get(String(id)),
+    page: (id) => { const p = r.pages?.get(String(id)); return p && localePrefix ? { ...p, route: under(p.route) } : p },
+    single: (key) => r.singles?.get(key),
+    entry: (collection, id, depth): EntryRead => {
+      const rec = r.entries?.get(entryKey(collection, id))
+      if (!rec) return { id, collection, status: 'missing' }
+      const base: EntryRead = { id, collection, status: 'ready', slug: rec.slug, ...(rec.route ? { route: under(rec.route) } : {}) }
+      const decl = Object.hasOwn(schema.collections, collection) ? schema.collections[collection] : undefined
+      if (Math.min(depth, budget) <= 0 || !decl) return base
+      const inner = makeCtx(schema, r, path.child(path.doc('entry', id), 'fields'), draft, Math.min(depth, budget) - 1, undefined, draftLocale, localePrefix)
+      return { ...base, fields: expandField(schema, { container: 'u90/group', fields: decl.fields, order: decl.order }, rec.fields, inner) as Record<string, unknown> }
+    },
+    query: (collection, q) => {
+      const hit = r.queries?.get(queryKey(collection, q))
+      return hit ? { entries: hit.ids.map((id) => ctx.entry(collection, id, 1)), total: hit.total } : { entries: [], total: 0 }
+    },
+    inverse: (collection, field, id) => (r.inverses?.get(inverseKey(collection, field, id)) ?? []).map((x) => ctx.entry(collection, x, 1)),
+  }
+  return ctx
+}
+
+const withAt = (ctx: ExpandCtx, at: string): ExpandCtx => ({ ...ctx, at })
+
+export function expandField(schema: Schema, decl: FieldDecl, value: unknown, ctx: ExpandCtx): unknown {
+  if (isLeaf(decl)) return expandLeaf(getElement(decl.element), decl, value, ctx)
+  const container = getContainer(decl.container)
+  const children = container.children(decl, decl.container === 'u90/group' ? (record(value) ? value : {}) : value, schema)
+  if (decl.container === 'u90/group') return Object.fromEntries(children.map((c) => [c.key, expandField(schema, c.decl, c.value, withAt(ctx, path.child(ctx.at, c.key)))]))
+  const items = Array.isArray(value) ? value : []
+  return children.map((c, i) => {
+    const inner = expandField(schema, c.decl, c.value, withAt(ctx, path.child(ctx.at, c.key)))
+    // A leaf item reads as its element's value (which carries its own `$path`); a group item, like a zone item, carries the item's path in draft.
+    if (decl.container === 'u90/list') return isLeaf(decl.item) ? inner : { _id: c.key, ...(ctx.draft ? { $path: path.child(ctx.at, c.key) } : {}), ...(inner as object) }
+    const item = items[i]
+    const block = record(item) ? String(item._block) : ''
+    if (block === SLOT || !Object.hasOwn(schema.blocks, block)) return { _id: c.key, _block: block }
+    return { _id: c.key, _block: block, ...(ctx.draft ? { $path: path.child(ctx.at, c.key) } : {}), ...(inner as object) }
+  })
+}
+
+/**
+ * `fallbacks` are the overlay keys the platform listed for this document (draft only): a leaf at one reads with `$fallback`. An entry expanded inside this document is another document and is not marked.
+ * `draftLocale` is the language a translated frame reads in, read from a draft request's `DRAFT_LOCALE_PARAM`: internal link hrefs, here and in entries expanded inside this document, keep it. Unlike `fallbacks`, it is not gated on `draft` here.
+ * `localePrefix` is the address prefix of the language the reply is read in (`/fr`): page and entry routes carry it.
+ */
+export function expand(schema: Schema, docDecl: DocumentDecl, doc: any, resolved: Resolved, opts: { at: string; draft: boolean; fallbacks?: readonly string[]; draftLocale?: string; localePrefix?: string }): unknown {
+  const ctx = makeCtx(schema, resolved, opts.at, opts.draft, MAX_DEPTH, opts.fallbacks ? new Set(opts.fallbacks) : undefined, opts.draftLocale, opts.localePrefix)
+  switch (docDecl.kind) {
+    case 'page':
+    case 'layout':
+      return { blocks: expandField(schema, docDecl.blocks, doc?.blocks, withAt(ctx, path.child(opts.at, 'blocks'))) }
+    case 'entry': {
+      const c = Object.hasOwn(schema.collections, docDecl.collection) ? schema.collections[docDecl.collection] : undefined
+      if (!c) return null
+      return {
+        fields: expandField(schema, { container: 'u90/group', fields: c.fields, order: c.order }, doc?.fields, withAt(ctx, path.child(opts.at, 'fields'))),
+        ...(c.template ? { blocks: expandField(schema, c.template, doc?.blocks, withAt(ctx, path.child(opts.at, 'blocks'))) } : {}),
+      }
+    }
+    case 'single': {
+      const s = Object.hasOwn(schema.singles, docDecl.key) ? schema.singles[docDecl.key] : undefined
+      if (!s) return null
+      return expandField(schema, s.field, doc?.value, ctx)
+    }
+  }
+}

package/src/elements/ops/overlay.ts

@@ -0,0 +1,59 @@
+import type { DocumentDecl, Schema } from '../define'
+import { hasStoredShape } from '../leaf'
+import { overlayKey } from '../path'
+import { walkDocument, type LeafNode } from '../walk'
+
+export { overlayKey }
+
+export type OverlayValues = Record<string, unknown>
+
+type Found = { node: LeafNode; options: unknown; key: string }
+
+/** Every leaf whose element has a codec that applies to its options, that is not declared `translatable: false`, and whose stored value has its element's shape and a part the codec translates. */
+function collect(schema: Schema, docDecl: DocumentDecl, doc: unknown, at: string): Found[] {
+  if ((docDecl.kind === 'entry' && !Object.hasOwn(schema.collections, docDecl.collection)) || (docDecl.kind === 'single' && !Object.hasOwn(schema.singles, docDecl.key))) return []
+  const out: Found[] = []
+  walkDocument(schema, docDecl, doc, {
+    leaf: (node) => {
+      const codec = node.entry.translation
+      if (!codec || node.decl.translatable === false) return
+      const o = node.entry.options.safeParse(node.decl.options ?? {})
+      if (!o.success || !codec.applies(o.data)) return
+      if (node.value === undefined || node.value === null || !hasStoredShape(node.entry, o.data, node.value)) return
+      if (codec.present && !codec.present(node.value, o.data)) return
+      out.push({ node, options: o.data, key: overlayKey(node.at) })
+    },
+  }, at)
+  return out
+}
+
+export function translatableLeaves(schema: Schema, docDecl: DocumentDecl, doc: unknown, at: string): { key: string; at: string; value: unknown }[] {
+  return collect(schema, docDecl, doc, at).map(({ node, options, key }) => ({ key, at: node.at, value: node.entry.translation!.pick(node.value, options) }))
+}
+
+/**
+ * Lays language overlays onto a deep copy of `doc`. For each translatable leaf the first layer holding a
+ * value that passes the codec's schema wins. A leaf no layer translates keeps its base value and its key
+ * goes in `fellBack`, unless there is nothing to translate in it. A leaf won by a later layer (the first layer is the requested language, the rest are fallbacks) is in `fellBack` too. A layer whose value the codec cannot land (`apply` answers undefined) is skipped.
+ */
+export function applyOverlay(schema: Schema, docDecl: DocumentDecl, doc: unknown, at: string, layers: OverlayValues[]): { doc: unknown; fellBack: string[] } {
+  const copy = structuredClone(doc)
+  const fellBack: string[] = []
+  for (const { node, options, key } of collect(schema, docDecl, copy, at)) {
+    const codec = node.entry.translation!
+    const schemaOf = codec.value(options)
+    let won = -1
+    for (const [i, layer] of layers.entries()) {
+      if (!Object.hasOwn(layer, key)) continue
+      const parsed = schemaOf.safeParse(layer[key])
+      if (!parsed.success) continue
+      const landed = codec.apply(node.value, parsed.data, options)
+      if (landed === undefined) continue
+      node.set(landed)
+      won = i
+      break
+    }
+    if (won > 0 || (won < 0 && codec.pick(node.value, options) !== null)) fellBack.push(key)
+  }
+  return { doc: copy, fellBack }
+}

package/src/elements/ops/refs.ts

@@ -0,0 +1,45 @@
+import type { DocumentDecl, ExpandCtx, Ref, Schema } from '../define'
+import { hasStoredShape } from '../leaf'
+import { walkDocument } from '../walk'
+
+/** An ExpandCtx that resolves nothing and records each lookup as the ref that would answer it. */
+const recorder = (at: string, add: (ref: Ref) => void): ExpandCtx => ({
+  at,
+  draft: false,
+  media: (id) => { add({ kind: 'media', id }); return undefined },
+  page: (id) => { add({ kind: 'page', id }); return undefined },
+  single: (key) => { add({ kind: 'single', key }); return undefined },
+  entry: (collection, id, depth) => { add({ kind: 'entry', collection, id, depth }); return { id, collection, status: 'missing' } },
+  query: (collection, query) => { add({ kind: 'query', collection, query }); return { entries: [], total: 0 } },
+  inverse: (collection, field, id) => { add({ kind: 'inverse', collection, field, id }); return [] },
+})
+
+/**
+ * Everything the document's read needs fetched, each once. A stored value (a `null` counts as the element's
+ * empty value) asks for its element's `refs`. An absent field reads as its declared default, so it asks for
+ * exactly the lookups reading that default makes: ids, tokens and queries do; a `{ source }` asset, a `$ref`
+ * or a page or entry named by key reads as missing until seeded and asks for nothing.
+ */
+export function collectRefs(schema: Schema, docDecl: DocumentDecl, doc: unknown, at: string): Ref[] {
+  if ((docDecl.kind === 'entry' && !Object.hasOwn(schema.collections, docDecl.collection)) || (docDecl.kind === 'single' && !Object.hasOwn(schema.singles, docDecl.key))) return []
+  const seen = new Set<string>()
+  const refs: Ref[] = []
+  const add = (ref: Ref) => {
+    const key = JSON.stringify(ref)
+    if (!seen.has(key)) { seen.add(key); refs.push(ref) }
+  }
+  walkDocument(schema, docDecl, doc, {
+    leaf: ({ entry, decl, value, at: here }) => {
+      const o = entry.options.safeParse(decl.options ?? {})
+      if (!o.success) return
+      if (value === undefined && decl.default !== undefined) {
+        const seed = entry.seed(o.data).safeParse(decl.default)
+        if (seed.success) entry.expandSeed(seed.data, o.data, recorder(here, add))
+        return
+      }
+      if (value !== undefined && value !== null && !hasStoredShape(entry, o.data, value)) return
+      entry.refs(value ?? entry.empty(o.data), o.data, here).forEach(add)
+    },
+  }, at)
+  return refs
+}

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
+}