@unitninety/site-kit 0.0.0-stage → 1.6.1

package/src/components/Link.tsx

@@ -0,0 +1,24 @@
+import NextLink from 'next/link'
+import { Children, createElement, type ReactNode } from 'react'
+import type { LinkRead } from '../elements'
+import { draftAttrs } from './draft'
+export const isInternal = (href: string) => href.startsWith('/') && !href.startsWith('//')
+export function Link({ value, children, ...rest }: { value: LinkRead | null | undefined; children?: ReactNode } & Record<string, unknown>) {
+  if (!value) return null
+  const attrs = { ...rest, ...draftAttrs(value) }
+  // A label has its own editable surface: replacing the anchor's text would remove icons and
+  // other children. Only wrap the actual label, never arbitrary custom or icon-only content.
+  // Published markup is unchanged. Both markers use the link path, so selection stays on the link.
+  const content = children ?? value.label
+  const label = value.$path ? Children.map(content, child =>
+    typeof child === 'string' && child === value.label
+      ? createElement('span', draftAttrs(value, 'link-label'), child)
+      : child,
+  ) : content
+  if (!value.href) return createElement('span', attrs, label)
+  // A new-tab link gets target and rel; a caller's own target or rel wins over them (§5: the
+  // element's props pass through). The href is always the value's.
+  const tab: Record<string, unknown> = value.newTab ? { target: '_blank', rel: 'noopener' } : {}
+  for (const key of ['target', 'rel'] as const) if (rest[key] !== undefined) tab[key] = rest[key]
+  return isInternal(value.href) ? createElement(NextLink, { ...attrs, href: value.href, ...tab } as never, label) : createElement('a', { ...attrs, href: value.href, ...tab }, label)
+}

package/src/components/NumberText.tsx

@@ -0,0 +1,9 @@
+import { createElement, type ElementType } from 'react'
+import type { NumberRead } from '../elements'
+import { draftAttrs } from './draft'
+export function NumberText<T extends ElementType = 'span'>({ value, as, locale, format, ...rest }: { value: NumberRead | null | undefined; as?: T; locale?: string; format?: Intl.NumberFormatOptions } & Record<string, unknown>) {
+  if (!value) return null
+  const text = new Intl.NumberFormat(locale, format).format(value.value)
+  const attrs = draftAttrs(value)
+  return as ? createElement(as, { ...rest, ...attrs }, text) : value.$path ? createElement('span', attrs, text) : text
+}

package/src/components/RichText.tsx

@@ -0,0 +1,47 @@
+import { createElement, Fragment, type ElementType, type ReactNode } from 'react'
+import type { RichTextRead } from '../elements'
+import { draftAttrs } from './draft'
+type Node = { type: string; text?: string; format?: number; tag?: string; children?: Node[]; fields?: { href?: string | null; newTab?: boolean; to?: unknown }; listType?: string; key?: string }
+const MARKS: Array<[number, string]> = [[1, 'strong'], [2, 'em'], [8, 'u'], [4, 's'], [16, 'code']]
+const inline = (n: Node, key: number, draft: boolean): ReactNode => {
+  if (n.type === 'linebreak') return createElement('br', { key })
+  if (n.type === 'link') {
+    const anchor = Boolean(n.fields?.href)
+    // In draft, a link carries the field's own `{ to, newTab }` — v1's `LinkTo` — so
+    // `lexicalDom.ts` reads an untouched link back exactly rather than reclassifying it from
+    // `href` alone. The dead-link `<span>` (a deleted page, an unrouted entry) carries it too:
+    // without it the reader sees plain text, and the next keystroke in the field drops the link.
+    const linkAttrs = draft ? { 'data-u90-link': JSON.stringify({ to: n.fields?.to, newTab: Boolean(n.fields?.newTab) }) } : {}
+    return createElement(
+      anchor ? 'a' : 'span',
+      { key, ...linkAttrs, ...(anchor ? { href: n.fields!.href, ...(n.fields!.newTab ? { target: '_blank', rel: 'noopener' } : {}) } : {}) },
+      ...(n.children ?? []).map((c, i) => inline(c, i, draft)),
+    )
+  }
+  // In draft a Single is a chip, inside its marks, so `lexicalDom.ts` reads the marks as the token's format (R38).
+  let out: ReactNode = draft && n.type === 'single' && typeof n.key === 'string'
+    ? createElement('span', { 'data-single-key': n.key, contentEditable: false, suppressContentEditableWarning: true }, n.text ?? '')
+    : n.text ?? ''
+  for (const [bit, tag] of MARKS) if ((n.format ?? 0) & bit) out = createElement(tag, null, out)
+  return createElement(Fragment, { key }, out)
+}
+/**
+ * A stored `tag` is data, not markup: only a real heading or list tag becomes an element. Anything
+ * else would throw at render (`img` is void, `h1 onclick=x` is no tag at all — a 500) or, as
+ * `plaintext`, swallow the rest of the document. A heading falls back to `h2`, a list to its
+ * `listType`.
+ */
+const HEADINGS = new Set(['h1', 'h2', 'h3', 'h4', 'h5', 'h6'])
+const LISTS = new Set(['ul', 'ol'])
+const blockOf = (n: Node, key: number, draft: boolean): ReactNode => {
+  const kids = (n.children ?? []).map((c, i) => inline(c, i, draft))
+  if (n.type === 'heading') return createElement(n.tag && HEADINGS.has(n.tag) ? n.tag : 'h2', { key }, ...kids)
+  if (n.type === 'quote') return createElement('blockquote', { key }, ...kids)
+  if (n.type === 'list') return createElement(n.tag && LISTS.has(n.tag) ? n.tag : n.listType === 'number' ? 'ol' : 'ul', { key }, ...(n.children ?? []).map((li, i) => createElement('li', { key: i }, ...(li.children ?? []).map((c, j) => inline(c, j, draft)))))
+  return createElement('p', { key }, ...kids)
+}
+export const richTextNodes = (root: unknown, draft = false): ReactNode => ((root as { children?: Node[] })?.children ?? []).map((b, i) => blockOf(b, i, draft))
+export function RichText<T extends ElementType = 'div'>({ value, as, ...rest }: { value: RichTextRead | null | undefined; as?: T } & Record<string, unknown>) {
+  if (!value) return null
+  return createElement(as ?? 'div', { ...rest, ...draftAttrs(value, 'rich') }, richTextNodes((value as { root: unknown }).root, Boolean((value as { $path?: string }).$path)))
+}

package/src/components/Text.tsx

@@ -0,0 +1,15 @@
+import { createElement, type ComponentProps, type ElementType, type ReactNode } from 'react'
+import type { TextRead } from '../elements'
+import { draftAttrs } from './draft'
+type Props<T extends ElementType> = { value: TextRead | null | undefined; as?: T } & Omit<ComponentProps<T>, 'value' | 'as' | 'children'>
+/** In draft, each resolved Single is a chip the caret cannot enter, which the bridge saves back as its `{key}` (R38). */
+const chips = (value: TextRead): ReactNode =>
+  value.$path && value.segments
+    ? value.segments.map((s, i) => (typeof s === 'string' ? s : createElement('span', { key: i, 'data-single-key': s.key, contentEditable: false, suppressContentEditableWarning: true }, s.text)))
+    : value.text
+export function Text<T extends ElementType = 'span'>({ value, as, ...rest }: Props<T>) {
+  if (!value) return null
+  const attrs = draftAttrs(value, 'text')
+  if (!as) return value.$path ? createElement('span', attrs, chips(value)) : value.text
+  return createElement(as, { ...rest, ...attrs }, chips(value))
+}

package/src/components/Video.tsx

@@ -0,0 +1,12 @@
+// Video.tsx (server-safe)
+import { createElement } from 'react'
+import type { VideoRead } from '../elements'
+import { draftAttrs } from './draft'
+import { videoProps } from './videoProps'
+import { VideoPlayback } from './VideoPlayback'
+export function Video({ value, ...rest }: { value: VideoRead | null | undefined } & Record<string, unknown>) {
+  if (!value || !value.asset) return null
+  const bounded = value.startTime > 0 || value.endTime !== null
+  const el = createElement('video', { ...rest, ...draftAttrs(value), ...videoProps(value), ...(bounded ? { 'data-u90-start': value.startTime, 'data-u90-end': value.endTime ?? '' } : {}) })
+  return bounded ? createElement(VideoPlayback, null, el) : el
+}

package/src/components/VideoPlayback.tsx

@@ -0,0 +1,19 @@
+'use client'
+import { useEffect, useRef, type ReactNode } from 'react'
+/** Seeks to data-u90-start on load and stops (or loops back) at data-u90-end. Renders only its child. */
+export function VideoPlayback({ children }: { children: ReactNode }) {
+  const ref = useRef<HTMLSpanElement>(null)
+  useEffect(() => {
+    const v = ref.current?.querySelector('video'); if (!v) return
+    const start = Number(v.dataset.u90Start ?? 0), end = v.dataset.u90End ? Number(v.dataset.u90End) : null
+    const onMeta = () => { v.currentTime = start }
+    const onTime = () => { if (end !== null && v.currentTime >= end) { if (v.loop) { v.currentTime = start; void v.play().catch(() => {}) } else v.pause() } }
+    const onEnded = () => { if (end === null && v.loop) v.currentTime = start }
+    v.addEventListener('loadedmetadata', onMeta); v.addEventListener('timeupdate', onTime); v.addEventListener('ended', onEnded)
+    // The server-rendered <video> starts loading before this effect runs on hydration, so its
+    // metadata may already be in (HAVE_METADATA) — `loadedmetadata` has fired and will not again.
+    if (v.readyState >= 1) onMeta()
+    return () => { v.removeEventListener('loadedmetadata', onMeta); v.removeEventListener('timeupdate', onTime); v.removeEventListener('ended', onEnded) }
+  }, [])
+  return <span ref={ref} style={{ display: 'contents' }}>{children}</span>
+}

package/src/components/draft.ts

@@ -0,0 +1,9 @@
+/** `Record<string, unknown>` (rather than a bare `{ $path?: string }`) so TS's weak-type check does not reject a
+ *  literal like `{ text: 'x' }` at call sites — every real read value has more fields than just `$path`. */
+export type Marked = ({ $path?: string; $fallback?: boolean } & Record<string, unknown>) | null | undefined
+export type DraftAttrs = { 'data-u90-field'?: string; 'data-u90-edit'?: 'text' | 'rich' | 'link-label'; 'data-u90-fallback'?: '' }
+/** The one attribute (two for editable text) a draft render adds to the element it renders, and a third on a leaf that reads in a fallback language. Nothing in production. */
+export const draftAttrs = (value: Marked, edit?: 'text' | 'rich' | 'link-label'): DraftAttrs =>
+  value && value.$path ? { 'data-u90-field': value.$path, ...(edit ? { 'data-u90-edit': edit } : {}), ...(value.$fallback ? { 'data-u90-fallback': '' as const } : {}) } : {}
+export const editable = (value: Marked): DraftAttrs => draftAttrs(value, value && 'text' in value ? 'text' : undefined)
+export const editableRich = (value: Marked): DraftAttrs => draftAttrs(value, 'rich')

package/src/components/imageProps.ts

@@ -0,0 +1,26 @@
+import type { ImageRead, ImageReadVariant } from '../elements'
+type Geometry = { focalPoint: { x: number; y: number } | null; crop: { x: number; y: number; width: number; height: number } | null }
+const clamp = (v: number) => Math.min(100, Math.max(0, v))
+/** Ported from legacy image.ts `imagePosition`: the focal point as CSS object-position, relative to the crop when there is one. */
+export const objectPosition = (g: Geometry, fallback = '50% 50%'): string => {
+  const p = g.focalPoint
+  if (!p) return fallback
+  if (g.crop) return `${clamp(((p.x - g.crop.x) / g.crop.width) * 100)}% ${clamp(((p.y - g.crop.y) / g.crop.height) * 100)}%`
+  return `${clamp(p.x)}% ${clamp(p.y)}%`
+}
+export type ImageProps = { src: string; alt: string; width?: number; height?: number; fill?: boolean; sizes?: string; priority?: boolean; unoptimized?: boolean; style: { objectPosition: string } }
+const source = (v: ImageReadVariant) => (v.status === 'ready' && v.rendition ? v.rendition : v.asset ? { url: v.asset.url, width: v.asset.width, height: v.asset.height } : null)
+/** A draft grant path (a private item on a draft page): short-lived, so the site's image cache must never keep it. */
+const GRANT = /^\/api\/u90\/media\/.+[/-]g\d{10}-[0-9a-f]{16}(?:\.webp)?$/
+export const isGrantPath = (url: string): boolean => GRANT.test(url)
+export function imageProps(value: ImageRead, opts: { sizes?: string; fill?: boolean; priority?: boolean }): ImageProps | null {
+  if (!value) return null
+  const s = source(value)
+  if (!s) return null
+  const base = { src: s.url, alt: value.decorative ? '' : value.alt, ...(opts.sizes ? { sizes: opts.sizes } : {}), ...(opts.priority ? { priority: true } : {}), ...(isGrantPath(s.url) ? { unoptimized: true } : {}), style: { objectPosition: objectPosition(value) } }
+  if (opts.fill) return { ...base, fill: true }
+  if (s.width && s.height) return { ...base, width: s.width, height: s.height }
+  throw new Error(`u90 <Image>: "${value.alt || s.url}" has no intrinsic size; pass fill inside a sized, positioned container.`)
+}
+export const pictureSources = (value: NonNullable<ImageRead>, declared: Record<string, { media: string }> = {}) =>
+  Object.entries(value.variants).flatMap(([name, v]) => { const s = source(v); const media = declared[name]?.media; return s && media ? [{ name, media, srcSet: s.url, width: s.width, height: s.height }] : [] })

package/src/components/index.ts

@@ -0,0 +1,12 @@
+export { Text } from './Text'
+export { RichText, richTextNodes } from './RichText'
+export { Link, isInternal } from './Link'
+export { File } from './File'
+export { DateText } from './DateText'
+export { NumberText } from './NumberText'
+export { Image } from './Image'
+export { imageProps, isGrantPath, objectPosition, pictureSources, type ImageProps } from './imageProps'
+export { Video } from './Video'
+export { videoProps, type VideoHTMLProps } from './videoProps'
+export { draftAttrs, editable, editableRich, type DraftAttrs } from './draft'
+export { LanguageSwitcher, useLanguage, rememberLanguage } from '../switcher/LanguageSwitcher'

package/src/components/videoProps.ts

@@ -0,0 +1,6 @@
+// videoProps.ts — port of legacy media.ts videoProps over the read shape
+import type { VideoRead } from '../elements'
+export type VideoHTMLProps = { src?: string; poster?: string; autoPlay: boolean; muted: boolean; loop: boolean; controls: boolean; playsInline: boolean; preload: 'none' | 'metadata' | 'auto' }
+export function videoProps(v: NonNullable<VideoRead>): VideoHTMLProps {
+  return { src: v.asset?.url, poster: v.poster?.status === 'ready' ? v.poster.rendition?.url : undefined, autoPlay: v.autoplay, muted: v.muted, loop: v.loop, controls: v.controls, playsInline: v.playsInline, preload: v.preload }
+}

package/src/elements/containers/group.ts

@@ -0,0 +1,33 @@
+import { defineContainer, isLeaf, type GroupDecl, type LeafIssue } from '../define'
+import { orderedEntries } from '../order'
+
+export const record = (v: unknown): v is Record<string, unknown> => !!v && typeof v === 'object' && !Array.isArray(v)
+
+export const group = defineContainer<GroupDecl>({
+  id: 'u90/group',
+  children: (decl, value) => {
+    const v = record(value) ? value : {}
+    return orderedEntries(decl.fields, decl.order).map(([name, field]) => {
+      const renamed = isLeaf(field) ? field.renamedFrom : undefined
+      const current = v[name] !== undefined ? v[name] : renamed !== undefined ? v[renamed] : undefined
+      return {
+        key: name,
+        decl: field,
+        value: current,
+        set: (next: unknown) => {
+          v[name] = next
+          if (renamed !== undefined && renamed in v) delete v[renamed]
+        },
+      }
+    })
+  },
+  enter: (decl, value) => {
+    if (value === undefined || value === null) return []
+    if (!record(value)) return [{ path: [], code: 'invalid_type', message: 'Expected an object.' }]
+    const known = new Set(['_id', '_block', ...Object.keys(decl.fields), ...Object.values(decl.fields).flatMap((f) => (isLeaf(f) && f.renamedFrom ? [f.renamedFrom] : []))])
+    const issues: LeafIssue[] = []
+    for (const key of Object.keys(value))
+      if (!known.has(key)) issues.push({ path: [key], code: 'unknown-field', message: `No field "${key}" is declared here.`, severity: 'warning' })
+    return issues
+  },
+})

package/src/elements/containers/list.ts

@@ -0,0 +1,31 @@
+import { defineContainer, isLeaf, type ListDecl, type LeafIssue } from '../define'
+import { ID_RE } from '../path'
+import { record } from './group'
+
+export const list = defineContainer<ListDecl>({
+  id: 'u90/list',
+  children: (decl, value) => {
+    if (!Array.isArray(value)) return []
+    const leaf = isLeaf(decl.item)
+    return value.map((item, i) => ({
+      key: record(item) && typeof item._id === 'string' ? item._id : `#${i}`,
+      decl: decl.item,
+      value: leaf ? (record(item) ? item._value : undefined) : item,
+      set: (next: unknown) => {
+        if (!leaf) value[i] = next
+        else if (record(item)) item._value = next
+      },
+    }))
+  },
+  enter: (decl, value) => {
+    if (value === undefined || value === null) return []
+    if (!Array.isArray(value)) return [{ path: [], code: 'invalid_type', message: 'Expected a list.' }]
+    const issues: LeafIssue[] = []
+    if (decl.min !== undefined && value.length < decl.min) issues.push({ path: [], code: 'too_small', message: `At least ${decl.min} item${decl.min === 1 ? '' : 's'}.` })
+    if (decl.max !== undefined && value.length > decl.max) issues.push({ path: [], code: 'too_big', message: `At most ${decl.max} item${decl.max === 1 ? '' : 's'}.` })
+    value.forEach((item, i) => {
+      if (!record(item) || typeof item._id !== 'string' || !ID_RE.test(item._id)) issues.push({ path: [i], code: 'missing-id', message: 'Every item needs an _id.' })
+    })
+    return issues
+  },
+})

package/src/elements/containers/zone.ts

@@ -0,0 +1,41 @@
+import { SLOT, defineContainer, type GroupDecl, type LeafIssue, type ZoneDecl } from '../define'
+import { ID_RE } from '../path'
+import { record } from './group'
+
+/** Every item becomes a group child — a known block's fields, or no fields for SLOT and unknown blocks — so order is kept and nothing under SLOT is visited. */
+export const zone = defineContainer<ZoneDecl>({
+  id: 'u90/zone',
+  children: (decl, value, schema) => {
+    if (!Array.isArray(value)) return []
+    return value.map((item, i) => {
+      const block = record(item) && typeof item._block === 'string' && item._block !== SLOT && Object.hasOwn(schema.blocks, item._block) ? schema.blocks[item._block] : undefined
+      return {
+        key: record(item) && typeof item._id === 'string' ? item._id : `#${i}`,
+        decl: { container: 'u90/group', fields: block?.fields ?? {}, order: block?.order } as GroupDecl,
+        value: item,
+        set: (next: unknown) => { value[i] = next },
+      }
+    })
+  },
+  enter: (decl, value, schema) => {
+    if (value === undefined || value === null) return []
+    if (!Array.isArray(value)) return [{ path: [], code: 'invalid_type', message: 'Expected a list of blocks.' }]
+    const issues: LeafIssue[] = []
+    value.forEach((item, i) => {
+      const id = record(item) && typeof item._id === 'string' ? item._id : i
+      if (!record(item) || typeof item._id !== 'string' || !ID_RE.test(item._id)) issues.push({ path: [id], code: 'missing-id', message: 'Every block needs an _id.' })
+      if (!record(item) || typeof item._block !== 'string') return issues.push({ path: [id], code: 'missing-block', message: 'Every item needs a _block.' })
+      if (item._block === SLOT) return
+      if (!Object.hasOwn(schema.blocks, item._block)) return issues.push({ path: [id, '_block'], code: 'unknown-block', message: `No block named "${item._block}".`, severity: 'warning' })
+      if (!decl.allow.includes(item._block)) issues.push({ path: [id, '_block'], code: 'not-allowed', message: `"${item._block}" is not allowed here.` })
+    })
+    if (decl.fixed && decl.default) {
+      // A fixed zone fixes which blocks it holds, each once; editors may still reorder them (decision 6).
+      const sorted = (names: unknown[]) => names.map(String).sort()
+      const actual = value.filter(record).map((x) => x._block).filter((b) => b !== SLOT)
+      if (JSON.stringify(sorted(actual)) !== JSON.stringify(sorted(decl.default)))
+        issues.push({ path: [], code: 'fixed', message: `This zone holds exactly these blocks, in any order: ${decl.default.join(', ')}.` })
+    }
+    return issues
+  },
+})

package/src/elements/declaration.ts

@@ -0,0 +1,118 @@
+import { z } from 'zod'
+import type { BlockDecl, CollectionDecl, FieldDecl, Issue, LeafDecl, Schema, SingleDecl, ZoneDecl } from './define'
+import { isLeaf } from './define'
+import { ELEMENT_IDS, type ElementId } from './ids'
+import { zodIssues } from './leaf'
+import { getElement } from './registry'
+
+const NAME = /^[a-z][a-zA-Z0-9]*$/
+/**
+ * zod reports a bad record key through its own `invalid_key` issue rather than surfacing a `params.code`
+ * set on the key schema (verified against zod 4.4.3), so field names are checked in a `superRefine` instead,
+ * adding a `custom` issue with `params.code: 'field-name'` per bad key.
+ */
+const nameRecord = <T extends z.ZodTypeAny>(v: T) =>
+  z.record(z.string(), v).superRefine((obj, ctx) => {
+    for (const key of Object.keys(obj))
+      if (!NAME.test(key)) ctx.addIssue({ code: 'custom', message: 'Field names are camelCase identifiers.', params: { code: 'field-name' }, path: [key] })
+  })
+/** `order` sits beside `fields`, never inside it: it lists a permutation of `fields`' own keys, each once. */
+const checkOrder = (fields: Record<string, unknown>, order: string[] | undefined, ctx: z.RefinementCtx) => {
+  if (!order) return
+  const seen = new Set<string>()
+  for (const name of order) {
+    if (!Object.hasOwn(fields, name)) ctx.addIssue({ code: 'custom', message: `"${name}" is not a field here.`, path: ['order'] })
+    else if (seen.has(name)) ctx.addIssue({ code: 'custom', message: `"${name}" is listed twice.`, path: ['order'] })
+    seen.add(name)
+  }
+}
+
+const LeafDeclSchema = z.strictObject({
+  element: z.enum(ELEMENT_IDS),
+  label: z.string().optional(),
+  description: z.string().optional(),
+  required: z.boolean().optional(),
+  translatable: z.boolean().optional(),
+  default: z.unknown().optional(),
+  lock: z.array(z.string().min(1)).optional(),
+  renamedFrom: z.string().regex(NAME).optional(),
+  options: z.record(z.string(), z.unknown()).optional(),
+})
+export const FieldDeclSchema: z.ZodType<FieldDecl> = z.lazy(() =>
+  z.union([
+    LeafDeclSchema,
+    z.strictObject({ container: z.literal('u90/group'), label: z.string().optional(), fields: nameRecord(FieldDeclSchema), order: z.array(z.string()).optional() })
+      .superRefine((obj, ctx) => checkOrder(obj.fields, obj.order, ctx)),
+    z.strictObject({ container: z.literal('u90/list'), label: z.string().optional(), item: FieldDeclSchema, min: z.int().nonnegative().optional(), max: z.int().positive().optional(), default: z.array(z.unknown()).optional() }),
+    z.strictObject({ container: z.literal('u90/zone'), label: z.string().optional(), allow: z.array(z.string().min(1)).min(1), default: z.array(z.string().min(1)).optional(), fixed: z.boolean().optional() }),
+  ]),
+) as z.ZodType<FieldDecl>
+const ZoneDeclSchema = z.strictObject({ container: z.literal('u90/zone'), label: z.string().optional(), allow: z.array(z.string().min(1)).min(1), default: z.array(z.string().min(1)).optional(), fixed: z.boolean().optional() })
+export const BlockDeclSchema = z.strictObject({ name: z.string().regex(NAME), label: z.string(), fields: nameRecord(FieldDeclSchema), entry: z.string().optional(), order: z.array(z.string()).optional() })
+  .superRefine((obj, ctx) => checkOrder(obj.fields, obj.order, ctx))
+export const CollectionDeclSchema = z.strictObject({
+  name: z.string().regex(NAME), label: z.string(), fields: nameRecord(FieldDeclSchema), template: ZoneDeclSchema.optional(),
+  defaultSort: z.union([z.strictObject({ field: z.string(), dir: z.enum(['asc', 'desc']) }), z.literal('manual')]).optional(),
+  order: z.array(z.string()).optional(),
+}).superRefine((obj, ctx) => checkOrder(obj.fields, obj.order, ctx))
+export const SingleDeclSchema = z.strictObject({ key: z.string().regex(/^[a-z][a-zA-Z0-9_-]*$/), field: FieldDeclSchema })
+export const SchemaSchema = z.strictObject({ blocks: z.record(z.string(), BlockDeclSchema), collections: z.record(z.string(), CollectionDeclSchema), singles: z.record(z.string(), SingleDeclSchema) })
+
+type Where = 'block' | 'collection' | 'single'
+const issue = (path: string[], code: string, message: string): Issue => ({ path: path.join('.'), code, message, severity: 'error' })
+
+/** Parses, then checks everything the zod shape cannot: placement, cross-references, options, defaults, and fills query targetFields. */
+export function validateSchema(input: unknown): { ok: true; schema: Schema } | { ok: false; issues: Issue[] } {
+  const parsed = SchemaSchema.safeParse(input)
+  if (!parsed.success) return { ok: false, issues: zodIssues(parsed.error).map((i) => issue(i.path.map(String), i.code, i.message)) }
+  const schema = parsed.data as Schema
+  const issues: Issue[] = []
+  const targetFields = (collection: string) => Object.fromEntries(Object.entries(schema.collections[collection]?.fields ?? {}).filter(([, d]) => isLeaf(d)).map(([n, d]) => [n, (d as LeafDecl).element]))
+
+  const leaf = (d: LeafDecl, at: string[], where: Where) => {
+    const entry = getElement(d.element)
+    if ((entry.placement === 'collection' && where !== 'collection') || (entry.placement === 'content' && where !== 'block'))
+      issues.push(issue(at, 'placement', `${d.element} may only be declared in ${entry.placement === 'collection' ? 'a collection' : 'a block'}.`))
+    if (d.element === 'u90/query' && d.options?.to && schema.collections[String(d.options.to)]) d.options = { ...d.options, targetFields: targetFields(String(d.options.to)) }
+    const o = entry.options.safeParse(d.options ?? {})
+    if (!o.success) { zodIssues(o.error).forEach((i) => issues.push(issue([...at, 'options', ...i.path.map(String)], i.code, i.message))); return }
+    const opts = o.data as Record<string, unknown>
+    if ((d.element === 'u90/relation' || d.element === 'u90/selection' || d.element === 'u90/query') && !schema.collections[String(opts.to)])
+      issues.push(issue([...at, 'options', 'to'], 'unknown-collection', `No collection named "${opts.to}".`))
+    if (d.element === 'u90/relation' && opts.inverseOf) {
+      const target = schema.collections[String(opts.to)]?.fields[String(opts.inverseOf)]
+      if (!target || !isLeaf(target) || target.element !== 'u90/relation') issues.push(issue([...at, 'options', 'inverseOf'], 'unknown-inverse', `"${opts.to}" has no relation field "${opts.inverseOf}".`))
+    }
+    if (d.element === 'u90/single' && !schema.singles[String(opts.key)]) issues.push(issue([...at, 'options', 'key'], 'unknown-single', `No Single named "${opts.key}".`))
+    if (d.default !== undefined) {
+      const s = entry.seed(o.data).safeParse(d.default)
+      if (!s.success) zodIssues(s.error).forEach((i) => issues.push(issue([...at, 'default', ...i.path.map(String)], i.code, i.message)))
+      else d.default = s.data
+    }
+  }
+  const zone = (d: ZoneDecl, at: string[]) => {
+    d.allow.forEach((b, i) => { if (!schema.blocks[b]) issues.push(issue([...at, 'allow', String(i)], 'unknown-block', `No block named "${b}".`)) })
+    d.default?.forEach((b, i) => { if (!d.allow.includes(b)) issues.push(issue([...at, 'default', String(i)], 'not-allowed', `"${b}" is not in allow.`)) })
+    if (d.fixed && !d.default) issues.push(issue(at, 'fixed-needs-default', 'A fixed zone must list its blocks in default.'))
+  }
+  const field = (d: FieldDecl, at: string[], where: Where) => {
+    if (isLeaf(d)) return leaf(d, at, where)
+    if (d.container === 'u90/group') return Object.entries(d.fields).forEach(([n, f]) => field(f, [...at, 'fields', n], where))
+    if (d.container === 'u90/list') {
+      if (!isLeaf(d.item) && d.item.container !== 'u90/group')
+        issues.push(issue(at, 'list-item-kind', 'A list item must be an element or a group; wrap a list or a zone in a group.'))
+      return field(d.item, [...at, 'item'], where)
+    }
+    zone(d, at)
+  }
+  for (const [n, b] of Object.entries(schema.blocks)) {
+    if (b.entry && !schema.collections[b.entry]) issues.push(issue(['blocks', n, 'entry'], 'unknown-collection', `No collection named "${b.entry}".`))
+    Object.entries(b.fields).forEach(([f, d]) => field(d, ['blocks', n, 'fields', f], 'block'))
+  }
+  for (const [n, c] of Object.entries(schema.collections)) {
+    Object.entries(c.fields).forEach(([f, d]) => field(d, ['collections', n, 'fields', f], 'collection'))
+    if (c.template) zone(c.template, ['collections', n, 'template'])
+  }
+  for (const [n, s] of Object.entries(schema.singles)) field(s.field, ['singles', n, 'field'], 'single')
+  return issues.length ? { ok: false, issues } : { ok: true, schema }
+}

package/src/elements/define.ts

@@ -0,0 +1,195 @@
+import { z, type ZodType } from 'zod'
+import type { ContainerId, ElementId } from './ids'
+
+export type Mode = 'draft' | 'publish'
+export type Severity = 'error' | 'warning'
+export type Id = string | number
+/** A media, page or entry id as stored: a positive integer or a non-empty string. */
+export const Id: ZodType<Id> = z.union([z.int().positive(), z.string().trim().min(1)])
+
+/**
+ * An absolute http(s) URL, or a root-relative path. The character after the leading `/` may be
+ * neither `/` nor `\`: a browser reads `//host` and `/\host` alike as another host. Text and Link
+ * share it.
+ */
+export const URL_RE = /^(https?:\/\/\S+|\/(?:[^\/\\\s]\S*)?)$/
+/** A phone number: an optional leading `+`, a digit, then at least five more digits, spaces, parentheses or hyphens. */
+export const TEL_RE = /^\+?[0-9][0-9 ()\-]{5,}$/
+
+/** An issue relative to one leaf value; the walker prefixes the leaf's path. */
+export type LeafIssue = { path: (string | number)[]; code: string; message: string; severity?: Severity }
+/** An issue at a full path such as `page:4f2/blocks/b1/photo/alt`. */
+export type Issue = { path: string; code: string; message: string; severity: Severity }
+
+export type Ref =
+  | { kind: 'media'; id: Id }
+  | { kind: 'page'; id: Id }
+  | { kind: 'entry'; collection: string; id: Id; depth: number }
+  | { kind: 'single'; key: string }
+  | { kind: 'query'; collection: string; query: unknown }
+  | { kind: 'inverse'; collection: string; field: string; id: Id }
+
+export type ImageCrop = { x: number; y: number; width: number; height: number }
+export type Rendition = {
+  crop: ImageCrop | null
+  url: string
+  width: number | null
+  height: number | null
+  blurDataURL?: string
+  status: 'ready' | 'processing' | 'error'
+}
+export type MediaRecord = {
+  id: Id
+  url: string
+  mimeType: string
+  width: number | null
+  height: number | null
+  filename: string
+  blurDataURL?: string
+  /** Renditions the platform has produced for this asset, one per crop. Absent means none yet. */
+  renditions?: Rendition[]
+}
+/** A media record as a read value carries it: everything but the platform's renditions. Image, Video and File share it. */
+export type MediaAsset = Omit<MediaRecord, 'renditions'>
+export const MediaAssetSchema = z.object({ id: Id, url: z.string(), mimeType: z.string(), width: z.number().nullable(), height: z.number().nullable(), filename: z.string(), blurDataURL: z.string().optional() })
+export type PageRecord = { id: Id; route: string; title: string }
+/** A stored entry as the platform hands it to `expand`. */
+export type EntryRecord = { id: Id; slug: string; route?: string; fields: Record<string, unknown>; blocks?: unknown[] }
+export type EntryRead = {
+  id: Id
+  collection: string
+  status: 'ready' | 'missing'
+  slug?: string
+  route?: string
+  /** Present when expanded to depth ≥ 1. */
+  fields?: Record<string, unknown>
+}
+/** Read schema of an entry reached through a relation, selection or query. */
+export const EntryReadSchema = z.object({ id: Id, collection: z.string(), status: z.enum(['ready', 'missing']), slug: z.string().optional(), route: z.string().optional(), fields: z.record(z.string(), z.unknown()).optional() })
+
+/** Everything `expand` may ask for. Built by `ops/expand` from pre-fetched data; the leaf never fetches. */
+export type ExpandCtx = {
+  at: string
+  draft: boolean
+  /** Draft only: the overlay keys (`overlayKey(at)`) of this document's leaves that read in another language than the one asked for. */
+  fallbacks?: ReadonlySet<string>
+  /** The language a translated frame reads in, read from a draft request's `DRAFT_LOCALE_PARAM`, which internal link hrefs keep as that parameter. */
+  draftLocale?: string
+  media(id: Id): MediaRecord | undefined
+  page(id: Id): PageRecord | undefined
+  /** The Single's read value, already expanded by the caller. */
+  single(key: string): unknown
+  entry(collection: string, id: Id, depth: number): EntryRead
+  query(collection: string, query: unknown): { entries: EntryRead[]; total: number }
+  inverse(collection: string, field: string, id: Id): EntryRead[]
+}
+export type SeedCtx = {
+  importAsset(source: string): Promise<Id>
+  resolvePage(key: string): Id
+  resolveEntry(collection: string, key: string): Id
+  newId(): string
+}
+/** `hasDefault` is true only when the value is absent and a declared default reads in its place. */
+export type FieldMeta = { required: boolean; hasDefault: boolean }
+
+export type LeafDecl = {
+  element: ElementId
+  /** When `false`, the field is never translated. */
+  translatable?: boolean
+  label?: string
+  description?: string
+  required?: boolean
+  /** Seed shape. */
+  default?: unknown
+  /** Sub-paths a client may not change, e.g. `['to']` on a link. */
+  lock?: string[]
+  renamedFrom?: string
+  options?: Record<string, unknown>
+}
+export type GroupDecl = { container: 'u90/group'; label?: string; fields: Record<string, FieldDecl>; order?: string[] }
+export type ListDecl = { container: 'u90/list'; label?: string; item: FieldDecl; min?: number; max?: number; default?: unknown[] }
+export type ZoneDecl = { container: 'u90/zone'; label?: string; allow: string[]; default?: string[]; fixed?: boolean }
+export type FieldDecl = LeafDecl | GroupDecl | ListDecl | ZoneDecl
+export const isLeaf = (d: FieldDecl): d is LeafDecl => 'element' in d
+
+export type BlockDecl = { name: string; label: string; fields: Record<string, FieldDecl>; entry?: string; order?: string[] }
+export type CollectionDecl = {
+  name: string
+  label: string
+  fields: Record<string, FieldDecl>
+  template?: ZoneDecl
+  defaultSort?: { field: string; dir: 'asc' | 'desc' } | 'manual'
+  order?: string[]
+}
+export type SingleDecl = { key: string; field: FieldDecl }
+export type Schema = {
+  blocks: Record<string, BlockDecl>
+  collections: Record<string, CollectionDecl>
+  singles: Record<string, SingleDecl>
+}
+export type DocumentDecl =
+  | { kind: 'page'; blocks: ZoneDecl }
+  | { kind: 'layout'; blocks: ZoneDecl }
+  | { kind: 'entry'; collection: string }
+  | { kind: 'single'; key: string }
+
+export const SLOT = 'SLOT'
+
+/**
+ * What a language overlay holds for this leaf, and how it lands on the stored value. Destinations,
+ * media and structure never travel in an overlay: a link's overlay is its label, an image's its alt
+ * text and caption. `apply` answers undefined when there is no base value to translate.
+ */
+export type TranslationCodec<O, V, T> = {
+  applies(o: O): boolean
+  value(o: O): ZodType<T>
+  pick(v: V, o: O): T | null
+  apply(base: V | undefined, t: T, o: O): V | undefined
+  /** Whether a stored value has a part an overlay could land on, such as a video's poster. Absent, every stored value has. */
+  present?(v: V, o: O): boolean
+}
+
+export type ElementEntry<O = any, S = unknown, V = unknown, R = unknown> = {
+  id: ElementId
+  version: number
+  label: string
+  placement: 'any' | 'collection' | 'content'
+  options: ZodType<O>
+  seed(o: O): ZodType<S>
+  stored(o: O): ZodType<V>
+  /**
+   * The lenient shape a stored value must have to be read; defaults to `stored(o)`. An element whose
+   * options narrow `stored` into an enum, a union or an integer declares one without those rules, so
+   * content written under wider options keeps reading while `validate` reports it.
+   */
+  shape?(o: O): ZodType
+  read(o: O): ZodType<R>
+  /** Publish-only completeness. `v` is undefined when the field is absent from storage. */
+  complete(v: V | undefined, o: O, field: FieldMeta): LeafIssue[]
+  refs(v: V, o: O, at: string): Ref[]
+  toStored(seed: S, o: O, ctx: SeedCtx): Promise<V>
+  expand(v: V, o: O, ctx: ExpandCtx): R
+  /** Read shape of a seed value, for defaults of fields absent from storage. */
+  expandSeed(seed: S, o: O, ctx: ExpandCtx): R
+  toText(v: V, o: O): string
+  translatable(v: V, o: O): { path: (string | number)[]; value: string }[]
+  /** What a language overlay holds for this element; null where nothing translates. */
+  translation: TranslationCodec<O, V, any> | null
+  empty(o: O): V
+  upgrade: Record<number, (old: unknown) => unknown>
+}
+export const defineElement = <O, S, V, R>(e: ElementEntry<O, S, V, R>) => e
+
+export type Child = { key: string; decl: FieldDecl; value: unknown; set(v: unknown): void }
+export type ContainerEntry<D extends FieldDecl = FieldDecl> = {
+  id: ContainerId
+  children(decl: D, value: unknown, schema: Schema): Child[]
+  /** Structural checks on the container's own value; the walker prefixes the path. */
+  enter(decl: D, value: unknown, schema: Schema): LeafIssue[]
+}
+export const defineContainer = <D extends FieldDecl>(c: ContainerEntry<D>) => c
+
+export const requiredIssue = (present: boolean, field: FieldMeta): LeafIssue[] =>
+  !present && field.required && !field.hasDefault
+    ? [{ path: [], code: 'required', message: 'A value is required to publish.' }]
+    : []