@unitninety/site-kit 0.0.0-stage → 1.6.2

package/src/elements/leaves/rich-text.ts

@@ -0,0 +1,155 @@
+import { z } from 'zod'
+import { defineElement, requiredIssue, type ExpandCtx, type Ref } from '../define'
+import { TOKEN, textOfRead, tokenKeys } from '../tokens'
+import { LinkTo, hrefOf } from './link'
+
+/** Lexical's inline format bits — the same values `lexical.ts` exports; restated so this module has no runtime import. */
+const BITS = { bold: 1, italic: 2, strikethrough: 4, underline: 8, code: 16 } as const
+const MARKS = ['bold', 'italic', 'underline', 'strikethrough', 'code', 'link'] as const
+const BLOCKS = ['paragraph', 'heading', 'list', 'quote'] as const
+const HEADINGS = ['h2', 'h3', 'h4'] as const
+
+export const RichTextOptions = z.strictObject({
+  inline: z.boolean().default(false),
+  blocks: z.array(z.enum(BLOCKS)).min(1).default(['paragraph', 'heading', 'list']),
+  headings: z.array(z.enum(HEADINGS)).min(1).default(['h2', 'h3']),
+  marks: z.array(z.enum(MARKS)).default(['bold', 'italic', 'underline', 'link']),
+})
+type O = z.infer<typeof RichTextOptions>
+
+const common = { direction: z.enum(['ltr', 'rtl']).nullable().default('ltr'), format: z.string().default(''), indent: z.int().default(0), version: z.int().default(1) }
+const TextNode = z.object({ type: z.literal('text'), text: z.string(), format: z.int().nonnegative().default(0), detail: z.int().default(0), mode: z.string().default('normal'), style: z.string().default('') , version: z.int().default(1) })
+const LineBreak = z.object({ type: z.literal('linebreak'), version: z.int().default(1) })
+const LinkNode = z.object({ type: z.literal('link'), fields: z.object({ to: LinkTo, newTab: z.boolean().default(false) }), children: z.array(z.union([TextNode, LineBreak])), ...common })
+const inlines = (o: O) => z.array(o.marks.includes('link') ? z.union([TextNode, LineBreak, LinkNode]) : z.union([TextNode, LineBreak]))
+const Paragraph = (o: O) => z.object({ type: z.literal('paragraph'), children: inlines(o), textFormat: z.int().default(0), ...common })
+const Heading = (o: O) => z.object({ type: z.literal('heading'), tag: z.enum(o.headings as [string, ...string[]]), children: inlines(o), ...common })
+const Quote = (o: O) => z.object({ type: z.literal('quote'), children: inlines(o), ...common })
+const ListItem = (o: O) => z.object({ type: z.literal('listitem'), children: inlines(o), value: z.int().default(1), ...common })
+const List = (o: O) => z.object({ type: z.literal('list'), listType: z.enum(['bullet', 'number']), tag: z.enum(['ul', 'ol']), start: z.int().default(1), children: z.array(ListItem(o)), ...common })
+const blockSchemas = (o: O) => {
+  const by = { paragraph: Paragraph(o), heading: Heading(o), list: List(o), quote: Quote(o) }
+  const chosen = o.blocks.map((b) => by[b])
+  return chosen.length === 1 ? chosen[0] : z.union(chosen as z.ZodTypeAny[] as [z.ZodTypeAny, z.ZodTypeAny, ...z.ZodTypeAny[]])
+}
+const allowedMask = (o: O) => o.marks.reduce((m, k) => (k === 'link' ? m : m | BITS[k]), 0)
+
+type Node = { type: string; text?: string; format?: number | string; children?: Node[]; fields?: Record<string, unknown> } & Record<string, unknown>
+const eachText = (node: Node, path: (string | number)[], f: (n: Node, path: (string | number)[]) => void) => {
+  if (node.type === 'text') f(node, path)
+  node.children?.forEach((c, i) => eachText(c, [...path, 'children', i], f))
+}
+const eachLink = (node: Node, f: (n: Node) => void) => {
+  if (node.type === 'link') f(node)
+  node.children?.forEach((c) => eachLink(c, f))
+}
+
+const stored = (o: O) =>
+  z
+    .object({ root: z.object({ type: z.literal('root'), children: z.array(blockSchemas(o)), ...common }) })
+    .superRefine((v, ctx) => {
+      const root = v.root as unknown as Node
+      if (o.inline && (root.children!.length !== 1 || root.children![0].type !== 'paragraph'))
+        ctx.addIssue({ code: 'custom', path: ['root', 'children'], message: 'Inline text is a single paragraph.', params: { code: 'inline' } })
+      const mask = allowedMask(o)
+      eachText(root, ['root'], (n, path) => {
+        if (typeof n.format === 'number' && (n.format & ~mask) !== 0)
+          ctx.addIssue({ code: 'custom', path: [...path, 'format'], message: `Only these marks are allowed: ${o.marks.join(', ')}.`, params: { code: 'marks' } })
+      })
+    })
+    .nullable()
+type Stored = z.infer<ReturnType<typeof stored>>
+/** The widest options: every block, and a link in every inline run. */
+const WIDE: O = { inline: false, blocks: [...BLOCKS], headings: [...HEADINGS], marks: [...MARKS] }
+/** The same tree with all four blocks, any heading tag and a link anywhere inline, so narrowed options never blank content. */
+const SHAPE = z
+  .object({ root: z.object({ type: z.literal('root'), children: z.array(z.union([Paragraph(WIDE), Heading(WIDE).extend({ tag: z.string() }), List(WIDE), Quote(WIDE)])), ...common }) })
+  .nullable()
+
+export const richTextToPlain = (v: Stored): string =>
+  v ? (v.root.children as unknown as Node[]).map((b) => { const parts: string[] = []; eachText(b, [], (n) => parts.push(n.text ?? '')); return parts.join('') }).join('\n') : ''
+
+export type RichTextRead = ({ root: unknown; $path?: string }) | null
+const expand = (v: Stored, o: O, ctx: ExpandCtx): RichTextRead => {
+  if (v === null) return null
+  const root = structuredClone(v.root) as unknown as Node
+  eachLink(root, (n) => { const fields = n.fields as { to: z.infer<typeof LinkTo> }; Object.assign(fields, hrefOf(fields.to, ctx)) })
+  const split = (node: Node) => {
+    if (!node.children) return
+    node.children.forEach(split)
+    node.children = node.children.flatMap((c) => {
+      if (c.type !== 'text' || typeof c.text !== 'string' || !TOKEN.test(c.text)) return [c]
+      TOKEN.lastIndex = 0
+      const out: Node[] = []
+      let last = 0
+      for (const m of c.text.matchAll(TOKEN)) {
+        if (m.index! > last) out.push({ ...c, text: c.text.slice(last, m.index) })
+        const resolved = textOfRead(ctx.single(m[1]))
+        out.push(resolved === undefined ? { ...c, text: m[0] } : { type: 'single', key: m[1], text: resolved, format: c.format ?? 0, version: 1 })
+        last = m.index! + m[0].length
+      }
+      if (last < c.text.length) out.push({ ...c, text: c.text.slice(last) })
+      return out
+    })
+  }
+  split(root)
+  return { root, ...(ctx.draft ? { $path: ctx.at } : {}) }
+}
+
+const linkNodes = (v: NonNullable<Stored>): Node[] => { const out: Node[] = []; eachLink(v.root as unknown as Node, (n) => out.push(n)); return out }
+const tokensOf = (v: NonNullable<Stored>): string => { const keys: string[] = []; eachText(v.root as unknown as Node, [], (n) => keys.push(...tokenKeys(n.text ?? ''))); return keys.sort().join(',') }
+/**
+ * A translation may reword and reformat, never repoint: it lands only when it holds as many links as the
+ * base and the same `{single}` tokens, and each link keeps the base link's fields (destination, new tab).
+ */
+const landTranslation = (base: Stored | undefined, t: Stored): Stored | undefined => {
+  if (!base || !t) return undefined
+  const from = linkNodes(base)
+  const copy = structuredClone(t)
+  const into = linkNodes(copy)
+  if (from.length !== into.length || tokensOf(base) !== tokensOf(copy)) return undefined
+  from.forEach((n, i) => { into[i].fields = structuredClone(n.fields) })
+  return copy
+}
+
+export const richText = defineElement({
+  id: 'u90/rich-text',
+  version: 1,
+  label: 'Rich text',
+  placement: 'any',
+  options: RichTextOptions,
+  seed: stored,
+  stored,
+  shape: () => SHAPE,
+  read: () => z.object({ root: z.unknown(), $path: z.string().optional() }).nullable(),
+  complete: (v, _o, field) => requiredIssue(richTextToPlain(v ?? null).trim() !== '', field),
+  refs: (v) => {
+    if (!v) return []
+    const refs: Ref[] = []
+    const root = v.root as unknown as Node
+    eachText(root, [], (n) => tokenKeys(n.text ?? '').forEach((key) => refs.push({ kind: 'single', key })))
+    eachLink(root, (n) => {
+      const to = (n.fields as { to: z.infer<typeof LinkTo> }).to
+      if ('page' in to) refs.push({ kind: 'page', id: to.page })
+      else if ('entry' in to) refs.push({ kind: 'entry', collection: to.entry.collection, id: to.entry.id, depth: 0 })
+    })
+    return refs
+  },
+  toStored: async (seed) => seed,
+  expand,
+  expandSeed: expand,
+  toText: richTextToPlain,
+  translatable: (v) => {
+    const out: { path: (string | number)[]; value: string }[] = []
+    if (v) eachText(v.root as unknown as Node, ['root'], (n, path) => { if (n.text) out.push({ path: [...path, 'text'], value: n.text }) })
+    return out
+  },
+  translation: {
+    applies: () => true,
+    value: (o) => stored(o),
+    pick: (v) => v,
+    apply: (base, t) => landTranslation(base, t),
+  },
+  empty: () => null,
+  upgrade: {},
+})

package/src/elements/leaves/selection.ts

@@ -0,0 +1,40 @@
+import { z, type ZodType } from 'zod'
+import { EntryReadSchema, Id, defineElement, requiredIssue, type EntryRead, type ExpandCtx, type Ref } from '../define'
+import { EntryRef, resolveEntryRef, uniqueIds } from './relation'
+
+export const SelectionOptions = z.strictObject({ to: z.string().min(1), many: z.boolean().default(false), max: z.int().positive().optional(), depth: z.int().min(0).max(3).default(1) })
+type O = z.infer<typeof SelectionOptions>
+/** How a selection and a query read: the entries in order, how many there are, and `$path` in draft. */
+export type EntriesRead = { entries: EntryRead[]; total: number; $path?: string; $pins?: string[] }
+export const EntriesReadSchema = z.object({ entries: z.array(EntryReadSchema), total: z.number(), $path: z.string().optional(), $pins: z.array(z.string()).optional() })
+
+const stored = (o: O) => (o.many ? (o.max ? z.array(Id).max(o.max) : z.array(Id)).superRefine(uniqueIds) : Id.nullable())
+type SeedValue = z.infer<typeof EntryRef> | z.infer<typeof EntryRef>[] | null
+const seed = (o: O): ZodType<SeedValue> => (o.many ? z.array(EntryRef) : EntryRef.nullable())
+const ids = (v: Id | Id[] | null) => (Array.isArray(v) ? v : v === null ? [] : [v])
+/** Every selected entry is read, so `total` is the number of entries — the same shape a query reads. */
+const expand = (v: Id | Id[] | null, o: O, ctx: ExpandCtx): EntriesRead => {
+  const entries = ids(v).map((id) => ctx.entry(o.to, id, o.depth))
+  return { entries, total: entries.length, ...(ctx.draft ? { $path: ctx.at } : {}) }
+}
+
+export const selection = defineElement({
+  id: 'u90/selection',
+  version: 1,
+  label: 'Selection',
+  placement: 'content',
+  options: SelectionOptions,
+  seed,
+  stored,
+  read: () => EntriesReadSchema,
+  complete: (v, _o, field) => requiredIssue(ids(v ?? null).length > 0, field),
+  refs: (v, o): Ref[] => ids(v).map((id) => ({ kind: 'entry', collection: o.to, id, depth: o.depth })),
+  toStored: async (s, o, ctx) => (Array.isArray(s) ? s.map((r) => resolveEntryRef(r, o.to, ctx)) : s === null ? null : resolveEntryRef(s, o.to, ctx)),
+  expand,
+  expandSeed: (s, o, ctx) => expand(Array.isArray(s) ? (s.filter((r) => typeof r !== 'object') as Id[]) : typeof s === 'object' ? null : s, o, ctx),
+  toText: () => '',
+  translatable: () => [],
+  translation: null,
+  empty: (o) => (o.many ? [] : null),
+  upgrade: {},
+})

package/src/elements/leaves/single.ts

@@ -0,0 +1,29 @@
+import { z } from 'zod'
+import { defineElement } from '../define'
+
+export const SingleOptions = z.strictObject({ key: z.string().regex(/^[a-z][a-zA-Z0-9_-]*$/) })
+type O = z.infer<typeof SingleOptions>
+/** Nothing is stored on the block: the declaration fixes the key. Only `null` (or absence) is valid. */
+const stored = z.null()
+
+export const single = defineElement({
+  id: 'u90/single',
+  version: 1,
+  label: 'Single',
+  placement: 'any',
+  options: SingleOptions,
+  seed: () => stored,
+  stored: () => stored,
+  read: () => z.unknown(),
+  /** `validateSchema` rejects a key that names no Single; whether the Single has a value is not checked by the registry — it needs data this leaf does not have. */
+  complete: () => [],
+  refs: (_v, o) => [{ kind: 'single', key: o.key }],
+  toStored: async () => null,
+  expand: (_v, o, ctx) => ctx.single(o.key) ?? null,
+  expandSeed: (_v, o, ctx) => ctx.single(o.key) ?? null,
+  toText: () => '',
+  translatable: () => [],
+  translation: null,
+  empty: () => null,
+  upgrade: {},
+})

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