@unitninety/site-kit 0.0.0-stage → 1.6.1

package/src/elements/ids.ts

@@ -0,0 +1,50 @@
+const ALPHABET = '0123456789abcdefghijklmnopqrstuvwxyz'
+const DIGITS = '0123456789'
+
+/**
+ * `n` characters from `alphabet`, unbiased: a byte at or above the largest multiple of the alphabet's length below 256
+ * is redrawn, so every symbol is equally likely. Web Crypto, so the same code runs in Node, browsers and edge runtimes. */
+const draw = (n: number, alphabet: string): string => {
+  const limit = 256 - (256 % alphabet.length)
+  let out = ''
+  while (out.length < n) {
+    for (const byte of globalThis.crypto.getRandomValues(new Uint8Array(n * 2))) {
+      if (byte >= limit) continue
+      out += alphabet[byte % alphabet.length]
+      if (out.length === n) break
+    }
+  }
+  return out
+}
+
+/** A stored `_id`: a list item or a block. 1 to 16 lower-case letters and digits, so ids stored before the 12-character rule still read. */
+export const ID_RE = /^[a-z0-9]{1,16}$/
+/** 12 random characters (about 62 bits): an `_id`, minted by the platform. */
+export const newId = (): string => draw(12, ALPHABET)
+
+/**
+ * A page's, an entry's, a layout's, a Single's or a code draft's id: 16 characters that start with a digit and hold a
+ * letter. A declared key starts with a letter, so the two never look alike; and an id is never all digits, so nothing
+ * that reads a numeric string as a number can turn one into a number.
+ */
+export const DOCUMENT_ID_RE = /^(?=.*[a-z])[0-9][a-z0-9]{15}$/
+export const isDocumentId = (value: unknown): value is string => typeof value === 'string' && DOCUMENT_ID_RE.test(value)
+export const newDocumentId = (): string => {
+  for (;;) {
+    const id = draw(1, DIGITS) + draw(15, ALPHABET)
+    if (DOCUMENT_ID_RE.test(id)) return id
+  }
+}
+
+export const ELEMENT_IDS = [
+  'u90/text', 'u90/rich-text', 'u90/image', 'u90/video', 'u90/file', 'u90/link',
+  'u90/date', 'u90/number', 'u90/boolean', 'u90/choice',
+  'u90/relation', 'u90/selection', 'u90/query', 'u90/single',
+] as const
+export type ElementId = (typeof ELEMENT_IDS)[number]
+
+export const CONTAINER_IDS = ['u90/group', 'u90/list', 'u90/zone'] as const
+export type ContainerId = (typeof CONTAINER_IDS)[number]
+
+/** `u90/rich-text` → `rich-text`; used for fixture folders and docs anchors. */
+export const shortId = (id: ElementId | ContainerId) => id.slice('u90/'.length)

package/src/elements/index.ts

@@ -0,0 +1,35 @@
+export const MODULE = '@unitninety/site-kit/elements'
+export * from './ids'
+export * from './define'
+export { path, newId, ID_RE, type Path, type DocKind } from './path'
+export { orderedKeys, orderedEntries } from './order'
+export * from './tokens'
+export { validateLeaf, expandLeaf, parseOptions, zodIssues, hasStoredShape } from './leaf'
+export { text, TextOptions, type TextRead, type TextSegment } from './leaves/text'
+export { boolean, BooleanOptions, type BooleanRead } from './leaves/boolean'
+export { number, NumberOptions, type NumberRead } from './leaves/number'
+export { date, DateOptions, type DateRead } from './leaves/date'
+export { choice, ChoiceOptions, type ChoiceRead, type ChoiceReadValue } from './leaves/choice'
+export { link, LinkOptions, LinkTo, linkKind, hrefOf, DRAFT_LOCALE_PARAM, type LinkRead, type LinkKind } from './leaves/link'
+export { single, SingleOptions } from './leaves/single'
+export { richText, RichTextOptions, richTextToPlain, type RichTextRead } from './leaves/rich-text'
+export { image, ImageOptions, ImageConstraints, imageStored, imageSeed, expandImage, imageToStored, type ImageRead, type ImageStored, type ImageSeed, type ImageReadVariant, type ImageAsset } from './leaves/image'
+export { video, VideoOptions, mediaAssetRead, type VideoRead, type MediaAssetRead } from './leaves/video'
+export { file, FileOptions, type FileRead } from './leaves/file'
+export { relation, RelationOptions, isDerived, EntryRef, resolveEntryRef } from './leaves/relation'
+export { selection, SelectionOptions, type EntriesRead } from './leaves/selection'
+export { query, QueryOptions, QueryStored, applyQueryPicks, FILTERABLE, SORTABLE } from './leaves/query'
+export { elements, getElement, CONTRACTS, CURRENT_CONTRACT } from './registry'
+export { validateSchema, FieldDeclSchema, BlockDeclSchema, CollectionDeclSchema, SingleDeclSchema, SchemaSchema } from './declaration'
+export { containers, getContainer } from './registry'
+export { walk, walkDocument, type Visitor, type LeafNode, type ContainerNode } from './walk'
+export { validate, type ValidateOptions } from './ops/validate'
+export { collectRefs } from './ops/refs'
+export { expand, expandField, makeCtx, entryKey, queryKey, inverseKey, type Resolved } from './ops/expand'
+export { prefixedRoute } from './prefix'
+export { seed, seedItem, seedIssues, SeedError, type SeedKnown } from './ops/seed'
+export { textOf } from './ops/text'
+export { translatableParts } from './ops/translatable'
+export { overlayKey, translatableLeaves, applyOverlay, type OverlayValues } from './ops/overlay'
+export { upgrade, UpgradeError, type UpgradeOptions } from './ops/upgrade'
+export { toJSONSchema } from './jsonSchema'

package/src/elements/jsonSchema.ts

@@ -0,0 +1,36 @@
+import { z } from 'zod'
+import { isLeaf, type FieldDecl, type Schema } from './define'
+import { orderedEntries } from './order'
+import { ID_RE } from './path'
+import { getElement } from './registry'
+
+type JsonSchema = Record<string, unknown>
+const id = { type: 'string', pattern: ID_RE.source }
+
+/** JSON Schema (draft 2020-12) of a declaration's STORED shape. Used for agent tool schemas and docs. */
+export function toJSONSchema(decl: FieldDecl, schema?: Schema): JsonSchema {
+  if (isLeaf(decl)) {
+    const entry = getElement(decl.element)
+    const { $schema: _s, ...rest } = z.toJSONSchema(entry.stored(entry.options.parse(decl.options ?? {}))) as JsonSchema
+    return { ...rest, ...(decl.label ? { title: decl.label } : {}), ...(decl.description ? { description: decl.description } : {}) }
+  }
+  if (decl.container === 'u90/group')
+    return { type: 'object', properties: Object.fromEntries(orderedEntries(decl.fields, decl.order).map(([n, f]) => [n, toJSONSchema(f, schema)])), additionalProperties: false }
+  if (decl.container === 'u90/list') {
+    // validateSchema rejects a list item that isn't an element or a group, so only those two shapes reach here.
+    let item: JsonSchema
+    if (isLeaf(decl.item)) {
+      item = { type: 'object', properties: { _id: id, _value: toJSONSchema(decl.item, schema) }, required: ['_id', '_value'], additionalProperties: false }
+    } else {
+      const inner = toJSONSchema(decl.item, schema)
+      item = { type: 'object', properties: { _id: id, ...(inner.properties as object) }, required: ['_id'], additionalProperties: false }
+    }
+    return { type: 'array', items: item, ...(decl.min !== undefined ? { minItems: decl.min } : {}), ...(decl.max !== undefined ? { maxItems: decl.max } : {}) }
+  }
+  const blocks = decl.allow.map((name) => {
+    const block = schema?.blocks[name]
+    const fields = block ? (toJSONSchema({ container: 'u90/group', fields: block.fields, order: block.order }, schema).properties as object) : {}
+    return { type: 'object', properties: { _id: id, _block: { const: name }, ...fields }, required: ['_id', '_block'], additionalProperties: false }
+  })
+  return { type: 'array', items: { oneOf: blocks } }
+}

package/src/elements/leaf.ts

@@ -0,0 +1,98 @@
+import type { ZodError } from 'zod'
+import { overlayKey } from './path'
+import type { ElementEntry, ExpandCtx, FieldMeta, LeafDecl, LeafIssue, Mode } from './define'
+
+/** zod issues → LeafIssue. A `params.code` set by an element's own check wins over zod's generic code. */
+export const zodIssues = (error: ZodError): LeafIssue[] =>
+  error.issues.map((i) => ({
+    path: i.path as (string | number)[],
+    code: (i as { params?: { code?: string } }).params?.code ?? i.code,
+    message: i.message,
+  }))
+
+export function parseOptions(entry: ElementEntry, decl: LeafDecl) {
+  const r = entry.options.safeParse(decl.options ?? {})
+  return r.success
+    ? ({ ok: true, options: r.data } as const)
+    : ({ ok: false, issues: zodIssues(r.error).map((i) => ({ ...i, path: ['options', ...i.path] })) } as const)
+}
+
+/**
+ * zod codes meaning a value does not have its element's stored shape; any other failure (a length,
+ * a pattern, a step, a custom rule) leaves the shape intact, so the value can still be read. The
+ * check parses with the element's `shape` where it declares one, else with `stored`, and a failure
+ * with one of these codes counts whichever raised it, an element's own refinement included (a
+ * query's value-shape rules raise `invalid_type`). Under `stored`, an option that becomes an enum,
+ * a union or an integer rule would turn narrowing it into a shape failure and blank old content, so
+ * rich text, number and choice declare a `shape` without those rules: their content written before
+ * a declaration narrowed keeps rendering while `validate` reports it. `invalid_format` is a shape
+ * code too: a value whose format *is* its type (an ISO date, a link's `url`/`email`/`tel`
+ * destination) has no usable shape once the format fails. Text's own format rules (`format: 'email'`
+ * etc.) are checked as custom issues, not `invalid_format`, so a bad-format text still reads.
+ */
+const SHAPE_CODES = new Set(['invalid_type', 'invalid_union', 'invalid_value', 'invalid_key', 'invalid_element', 'unrecognized_keys', 'invalid_format'])
+/**
+ * Whether `value` has the stored shape its element's operations assume. `refs`, `expand`, `toText`
+ * and `translatable` only ever see a value that passes, so a malformed stored value is reported by
+ * `validate`, reads as the element's empty value, and never throws inside an operation.
+ */
+export const hasStoredShape = (entry: ElementEntry, options: unknown, value: unknown): boolean => {
+  const r = (entry.shape ? entry.shape(options) : entry.stored(options)).safeParse(value)
+  return r.success || r.error.issues.every((i) => !SHAPE_CODES.has(i.code))
+}
+
+/**
+ * A default stands in only for an absent value (an explicit `null` stays `null`), so only then can it
+ * satisfy `required`, and only when the default is itself complete. A blank default (`''`, a rich text
+ * with no words, a link with no label) satisfies nothing, so a required field declared with one still
+ * asks for a value before publishing.
+ */
+const completeDefault = (entry: ElementEntry, options: unknown, value: unknown): boolean => {
+  if (value === undefined || value === null) return false
+  const r = entry.stored(options).safeParse(value)
+  if (r.success) return entry.complete(r.data, options, { required: true, hasDefault: false }).length === 0
+  // A seed shape the stored schema does not take (an image's `{ source }`, an entry `$ref`): only a blank string or list is blank.
+  return !(typeof value === 'string' && value.trim() === '') && !(Array.isArray(value) && value.length === 0)
+}
+const meta = (entry: ElementEntry, decl: LeafDecl, options: unknown, absent: boolean): FieldMeta => ({
+  required: decl.required === true,
+  hasDefault: absent && decl.default !== undefined && completeDefault(entry, options, decl.default),
+})
+
+/**
+ * Strict type check in every mode; `complete` only when publishing.
+ * `undefined` means the field is absent from storage (it reads as its default), so only completeness applies.
+ */
+export function validateLeaf(entry: ElementEntry, decl: LeafDecl, value: unknown, mode: Mode): LeafIssue[] {
+  const o = parseOptions(entry, decl)
+  if (!o.ok) return o.issues
+  if (value === undefined) return mode === 'publish' ? entry.complete(undefined, o.options, meta(entry, decl, o.options, true)) : []
+  const r = entry.stored(o.options).safeParse(value)
+  if (!r.success) return zodIssues(r.error)
+  return mode === 'publish' ? entry.complete(r.data, o.options, meta(entry, decl, o.options, false)) : []
+}
+
+/**
+ * Read shape of a stored value. An absent value (`undefined`) reads as the declared default or `empty`.
+ * A stored `null` is handed to the element's `expand`, which decides what it means: nullable elements
+ * return `null`, and `u90/single` / the derived side of `u90/relation` resolve it. A value without the
+ * stored shape, or a declaration whose options or default do not parse, reads as the empty value.
+ */
+export function expandLeaf(entry: ElementEntry, decl: LeafDecl, value: unknown, ctx: ExpandCtx): unknown {
+  const read = expandLeafValue(entry, decl, value, ctx)
+  // In draft, a leaf the reply lists as a fallback is marked beside its `$path`; a published read never is.
+  if (ctx.draft && ctx.fallbacks?.size && read && typeof read === 'object' && typeof (read as { $path?: unknown }).$path === 'string' && ctx.fallbacks.has(overlayKey(ctx.at))) return { ...read, $fallback: true }
+  return read
+}
+function expandLeafValue(entry: ElementEntry, decl: LeafDecl, value: unknown, ctx: ExpandCtx): unknown {
+  const parsed = entry.options.safeParse(decl.options ?? {})
+  if (!parsed.success) return null
+  const o = parsed.data
+  if (value === undefined) {
+    if (decl.default === undefined) return entry.expand(entry.empty(o), o, ctx)
+    const seeded = entry.seed(o).safeParse(decl.default)
+    return seeded.success ? entry.expandSeed(seeded.data, o, ctx) : entry.expand(entry.empty(o), o, ctx)
+  }
+  if (value !== null && !hasStoredShape(entry, o, value)) return entry.expand(entry.empty(o), o, ctx)
+  return entry.expand(value, o, ctx)
+}

package/src/elements/leaves/boolean.ts

@@ -0,0 +1,30 @@
+import { z } from 'zod'
+import { defineElement, type ExpandCtx } from '../define'
+
+export const BooleanOptions = z.strictObject({})
+/** How a boolean reads: its value, and `$path` in draft, so the Canvas can select it (R34). */
+export type BooleanRead = { value: boolean; $path?: string }
+const schema = z.boolean()
+const read = z.object({ value: z.boolean(), $path: z.string().optional() })
+const expand = (v: boolean, _o: unknown, ctx: ExpandCtx): BooleanRead => ({ value: v === true, ...(ctx.draft ? { $path: ctx.at } : {}) })
+
+export const boolean = defineElement({
+  id: 'u90/boolean',
+  version: 1,
+  label: 'Boolean',
+  placement: 'any',
+  options: BooleanOptions,
+  seed: () => schema,
+  stored: () => schema,
+  read: () => read,
+  complete: () => [],
+  refs: () => [],
+  toStored: async (seed) => seed,
+  expand,
+  expandSeed: expand,
+  toText: () => '',
+  translatable: () => [],
+  translation: null,
+  empty: () => false,
+  upgrade: {},
+})

package/src/elements/leaves/choice.ts

@@ -0,0 +1,53 @@
+import { z } from 'zod'
+import { defineElement, requiredIssue } from '../define'
+
+export const ChoiceOptions = z.strictObject({
+  values: z.array(z.strictObject({ value: z.string().min(1), label: z.string().min(1) })).min(1),
+  multiple: z.boolean().default(false),
+})
+type O = z.infer<typeof ChoiceOptions>
+/** One chosen value as it reads. */
+export type ChoiceRead = { value: string; label: string; $path?: string }
+/** What a choice field reads as: one item, a list of them when `multiple`, or `null` when cleared. */
+export type ChoiceReadValue = ChoiceRead | ChoiceRead[] | null
+
+const one = (o: O) => z.enum(o.values.map((v) => v.value) as [string, ...string[]])
+const stored = (o: O) =>
+  o.multiple
+    ? z.array(one(o)).superRefine((vs, ctx) => {
+        if (new Set(vs).size !== vs.length)
+          ctx.addIssue({ code: 'custom', message: 'Each value may be chosen once.', params: { code: 'duplicate' } })
+      })
+    : one(o).nullable()
+/** Any string, or a list of them: a value no longer among `values` still reads, labelled by itself. */
+const shape = (o: O) => (o.multiple ? z.array(z.string()) : z.string().nullable())
+const readOne = z.object({ value: z.string(), label: z.string(), $path: z.string().optional() })
+const read = (o: O) => (o.multiple ? z.array(readOne) : readOne.nullable())
+const label = (o: O, v: string) => o.values.find((x) => x.value === v)?.label ?? v
+const expand = (v: string | string[] | null, o: O, ctx: { at: string; draft: boolean }): ChoiceReadValue => {
+  const tag = ctx.draft ? { $path: ctx.at } : {}
+  if (Array.isArray(v)) return v.map((x) => ({ value: x, label: label(o, x), ...tag }))
+  return v === null ? null : { value: v, label: label(o, v), ...tag }
+}
+
+export const choice = defineElement({
+  id: 'u90/choice',
+  version: 1,
+  label: 'Choice',
+  placement: 'any',
+  options: ChoiceOptions,
+  seed: stored,
+  stored,
+  shape,
+  read,
+  complete: (v, _o, field) => requiredIssue(Array.isArray(v) ? v.length > 0 : typeof v === 'string', field),
+  refs: () => [],
+  toStored: async (seed) => seed,
+  expand,
+  expandSeed: expand,
+  toText: (v, o) => (Array.isArray(v) ? v.map((x) => label(o, x)).join(', ') : v === null ? '' : label(o, v)),
+  translatable: () => [],
+  translation: null,
+  empty: (o) => (o.multiple ? [] : null),
+  upgrade: {},
+})

package/src/elements/leaves/date.ts

@@ -0,0 +1,39 @@
+import { z } from 'zod'
+import { defineElement, requiredIssue } from '../define'
+
+export const DateOptions = z.strictObject({ min: z.iso.date().optional(), max: z.iso.date().optional() })
+type O = z.infer<typeof DateOptions>
+export type DateRead = { iso: string; $path?: string } | null
+
+const stored = (o: O) =>
+  z.iso
+    .date()
+    .superRefine((v, ctx) => {
+      if ((o.min && v < o.min) || (o.max && v > o.max))
+        ctx.addIssue({ code: 'custom', message: `Must be between ${o.min ?? 'any'} and ${o.max ?? 'any'}.`, params: { code: 'range' } })
+    })
+    .nullable()
+const read = z.object({ iso: z.iso.date(), $path: z.string().optional() }).nullable()
+const expand = (v: string | null, _o: O, ctx: { at: string; draft: boolean }): DateRead =>
+  v === null ? null : { iso: v, ...(ctx.draft ? { $path: ctx.at } : {}) }
+
+export const date = defineElement({
+  id: 'u90/date',
+  version: 1,
+  label: 'Date',
+  placement: 'any',
+  options: DateOptions,
+  seed: stored,
+  stored,
+  read: () => read,
+  complete: (v, _o, field) => requiredIssue(typeof v === 'string', field),
+  refs: () => [],
+  toStored: async (seed) => seed,
+  expand,
+  expandSeed: expand,
+  toText: (v) => v ?? '',
+  translatable: () => [],
+  translation: null,
+  empty: () => null,
+  upgrade: {},
+})

package/src/elements/leaves/file.ts

@@ -0,0 +1,56 @@
+import { z } from 'zod'
+import { Id, MediaAssetSchema, defineElement, requiredIssue, type ExpandCtx, type SeedCtx } from '../define'
+import { mediaAssetRead, type MediaAssetRead } from './video'
+
+export const FileOptions = z.strictObject({
+  mimeTypes: z.array(z.string().regex(/^[a-z]+\/[a-z0-9.+-]+$/i)).min(1).optional(),
+  maxBytes: z.int().positive().optional(),
+})
+type O = z.infer<typeof FileOptions>
+const stored = () => z.strictObject({ asset: Id, label: z.string(), description: z.string().nullable(), downloadName: z.string().nullable() }).nullable()
+type Stored = z.infer<ReturnType<typeof stored>>
+const seed = () =>
+  z.strictObject({ asset: z.union([Id, z.strictObject({ source: z.string().trim().min(1) })]), label: z.string().default(''), description: z.string().nullable().default(null), downloadName: z.string().nullable().default(null) }).nullable()
+export type FileRead = { asset: MediaAssetRead | null; status: 'ready' | 'missing'; label: string; description: string | null; downloadName: string | null; $path?: string } | null
+const read = z.object({ asset: MediaAssetSchema.nullable(), status: z.enum(['ready', 'missing']), label: z.string(), description: z.string().nullable(), downloadName: z.string().nullable(), $path: z.string().optional() }).nullable()
+const expand = (v: Stored, _o: O, ctx: ExpandCtx): FileRead =>
+  v === null ? null : { ...mediaAssetRead(ctx.media(v.asset)), label: v.label, description: v.description, downloadName: v.downloadName, ...(ctx.draft ? { $path: ctx.at } : {}) }
+
+export const file = defineElement({
+  id: 'u90/file',
+  version: 1,
+  label: 'File',
+  placement: 'any',
+  options: FileOptions,
+  seed,
+  stored,
+  read: () => read,
+  complete: (v, _o, field) => {
+    if (v == null) return requiredIssue(false, field)
+    return v.label.trim() ? [] : [{ path: ['label'], code: 'blank', message: 'Give the download a label.' }]
+  },
+  refs: (v) => (v ? [{ kind: 'media', id: v.asset }] : []),
+  toStored: async (s, _o, ctx: SeedCtx) => (s === null ? null : { ...s, asset: typeof s.asset === 'object' ? await ctx.importAsset(s.asset.source) : s.asset }),
+  expand,
+  expandSeed: (s, o, ctx) => {
+    if (s === null) return null
+    if (typeof s.asset !== 'object') return expand({ ...s, asset: s.asset }, o, ctx)
+    const src = s.asset.source
+    return { asset: { id: src, url: src, mimeType: '', width: null, height: null, filename: src.split('/').pop() ?? src }, status: 'ready', label: s.label, description: s.description, downloadName: s.downloadName, ...(ctx.draft ? { $path: ctx.at } : {}) }
+  },
+  toText: (v) => (v ? [v.label, v.description ?? ''].filter(Boolean).join(' ') : ''),
+  translatable: (v) => (v ? [...(v.label ? [{ path: ['label'], value: v.label }] : []), ...(v.description ? [{ path: ['description'], value: v.description }] : [])] : []),
+  translation: {
+    applies: () => true,
+    value: () => z.object({ label: z.string().optional(), description: z.string().optional() }).refine((t) => t.label !== undefined || t.description !== undefined, 'A file translation names its label or description.'),
+    pick: (v) => {
+      if (!v) return null
+      const label = v.label ? v.label : undefined
+      const description = v.description ? v.description : undefined
+      return label === undefined && description === undefined ? null : { ...(label !== undefined ? { label } : {}), ...(description !== undefined ? { description } : {}) }
+    },
+    apply: (base, t) => (base ? { ...base, ...(t.label !== undefined ? { label: t.label } : {}), ...(t.description !== undefined ? { description: t.description } : {}) } : undefined),
+  },
+  empty: () => null,
+  upgrade: {},
+})

package/src/elements/leaves/image.ts

@@ -0,0 +1,160 @@
+import { z } from 'zod'
+import { Id, MediaAssetSchema, defineElement, requiredIssue, type ExpandCtx, type ImageCrop, type MediaAsset, type MediaRecord, type Ref, type SeedCtx } from '../define'
+
+const pct = z.number().min(0).max(100)
+export const FocalPoint = z.strictObject({ x: pct, y: pct })
+export const Crop = z
+  .strictObject({ x: z.number().min(0), y: z.number().min(0), width: z.number().positive(), height: z.number().positive() })
+  .refine((c) => c.x + c.width <= 100 && c.y + c.height <= 100, { message: 'Crop must be a finite positive rectangle inside the original image.', params: { code: 'crop' } })
+const insideCrop = (p: { x: number; y: number }, c: ImageCrop) => p.x >= c.x && p.x <= c.x + c.width && p.y >= c.y && p.y <= c.y + c.height
+/**
+ * The two cross-field rules shared by every geometry-shaped schema: a stored/seeded `geometry()`, the
+ * top-level of `imageStored`/`imageSeed`, and (via nesting) each of their variants. Nesting a schema that
+ * calls this from its own `superRefine` auto-prefixes the issue path with that field's key, so a variant
+ * built from `geometry(Id)` or `seedGeometry` reports at `variants.<name>.focalPoint` with no extra work here.
+ */
+const crossFieldRules = (v: { focalPoint: { x: number; y: number } | null; crop: ImageCrop | null; alt?: string; decorative?: boolean }, ctx: z.RefinementCtx) => {
+  if (v.focalPoint && v.crop && !insideCrop(v.focalPoint, v.crop))
+    ctx.addIssue({ code: 'custom', path: ['focalPoint'], message: 'Focal point must lie inside the crop.', params: { code: 'focal-outside-crop' } })
+  if (v.decorative && v.alt !== '')
+    ctx.addIssue({ code: 'custom', path: ['alt'], message: 'Decorative images must have empty alternative text.', params: { code: 'decorative-alt' } })
+}
+
+const positiveInt = z.int().positive()
+export const ImageConstraints = z.strictObject({
+  mimeTypes: z.array(z.string().regex(/^image\/[a-z0-9.+-]+$/i)).min(1).optional(),
+  maxBytes: positiveInt.optional(),
+  minWidth: positiveInt.optional(),
+  minHeight: positiveInt.optional(),
+  cropAspectRatios: z.array(z.number().positive()).min(1).optional(),
+})
+const VariantKey = z.string().regex(/^[a-zA-Z][a-zA-Z0-9_]*$/).refine((k) => !['constructor', 'prototype', '__proto__'].includes(k), 'Variant needs a safe name.')
+export const ImageOptions = z.strictObject({
+  constraints: ImageConstraints.optional(),
+  variants: z.record(VariantKey, z.strictObject({ media: z.string().trim().min(1), constraints: ImageConstraints.optional() })).default({}),
+})
+type O = z.infer<typeof ImageOptions>
+
+const geometry = <A extends z.ZodTypeAny>(asset: A) =>
+  z.strictObject({ asset, crop: Crop.nullable(), focalPoint: FocalPoint.nullable() }).superRefine((v, ctx) => crossFieldRules(v, ctx))
+const variantsShape = <V extends z.ZodTypeAny>(o: O, variant: V) =>
+  z.strictObject(Object.fromEntries(Object.keys(o.variants).map((k) => [k, variant.optional()])))
+
+export const imageStored = (o: O) =>
+  z
+    .strictObject({
+      ...geometry(Id).shape,
+      alt: z.string(),
+      decorative: z.boolean(),
+      caption: z.string().nullable(),
+      variants: variantsShape(o, geometry(Id)),
+    })
+    .superRefine((v, ctx) => crossFieldRules(v, ctx))
+    .nullable()
+export type ImageStored = z.infer<ReturnType<typeof imageStored>>
+
+const SeedAsset = z.union([Id, z.strictObject({ source: z.string().trim().min(1) })])
+const seedGeometry = z
+  .strictObject({ asset: SeedAsset, crop: Crop.nullable().default(null), focalPoint: FocalPoint.nullable().default(null) })
+  .superRefine((v, ctx) => crossFieldRules(v, ctx))
+export const imageSeed = (o: O) =>
+  z
+    .strictObject({
+      ...seedGeometry.shape,
+      alt: z.string().default(''),
+      decorative: z.boolean().default(false),
+      caption: z.string().nullable().default(null).transform((c) => (c === '' ? null : c)),
+      variants: variantsShape(o, seedGeometry).default({}),
+    })
+    .superRefine((v, ctx) => crossFieldRules(v, ctx))
+    .nullable()
+export type ImageSeed = z.infer<ReturnType<typeof imageSeed>>
+
+export type ImageAsset = MediaAsset
+export type ImageReadVariant = { asset: ImageAsset | null; crop: ImageCrop | null; focalPoint: { x: number; y: number } | null; rendition: { url: string; width: number | null; height: number | null; blurDataURL?: string } | null; status: 'ready' | 'missing' | 'processing' | 'error' }
+export type ImageRead = (ImageReadVariant & { alt: string; decorative: boolean; caption: string | null; variants: Record<string, ImageReadVariant>; $path?: string }) | null
+const renditionRead = z.object({ url: z.string(), width: z.number().nullable(), height: z.number().nullable(), blurDataURL: z.string().optional() })
+const variantRead = z.object({ asset: MediaAssetSchema.nullable(), crop: Crop.nullable(), focalPoint: FocalPoint.nullable(), rendition: renditionRead.nullable(), status: z.enum(['ready', 'missing', 'processing', 'error']) })
+const imageRead = z.object({ ...variantRead.shape, alt: z.string(), decorative: z.boolean(), caption: z.string().nullable(), variants: z.record(z.string(), variantRead), $path: z.string().optional() }).nullable()
+
+const sameCrop = (a: ImageCrop | null, b: ImageCrop | null) => (a === null && b === null) || (!!a && !!b && a.x === b.x && a.y === b.y && a.width === b.width && a.height === b.height)
+const pick = (m: MediaRecord): ImageAsset => { const { renditions: _r, ...asset } = m; return asset }
+const readVariant = (v: { asset: Id; crop: ImageCrop | null; focalPoint: { x: number; y: number } | null }, ctx: ExpandCtx): ImageReadVariant => {
+  const m = ctx.media(v.asset)
+  if (!m) return { asset: null, crop: v.crop, focalPoint: v.focalPoint, rendition: null, status: 'missing' }
+  const r = m.renditions?.find((x) => sameCrop(x.crop, v.crop))
+  if (r) return { asset: pick(m), crop: v.crop, focalPoint: v.focalPoint, rendition: r.status === 'ready' ? { url: r.url, width: r.width, height: r.height, ...(r.blurDataURL ? { blurDataURL: r.blurDataURL } : {}) } : null, status: r.status }
+  if (v.crop === null) return { asset: pick(m), crop: null, focalPoint: v.focalPoint, rendition: { url: m.url, width: m.width, height: m.height, ...(m.blurDataURL ? { blurDataURL: m.blurDataURL } : {}) }, status: 'ready' }
+  return { asset: pick(m), crop: v.crop, focalPoint: v.focalPoint, rendition: null, status: 'processing' }
+}
+export const expandImage = (v: ImageStored, _o: O, ctx: ExpandCtx): ImageRead =>
+  v === null
+    ? null
+    : {
+        ...readVariant(v, ctx),
+        alt: v.alt,
+        decorative: v.decorative,
+        caption: v.caption,
+        variants: Object.fromEntries(Object.entries(v.variants).filter(([, x]) => x).map(([k, x]) => [k, readVariant(x!, ctx)])),
+        ...(ctx.draft ? { $path: ctx.at } : {}),
+      }
+
+/** A seed's `{ source }` reads as an asset served from that path, until seeding imports it. */
+const sourceCtx = (ctx: ExpandCtx, sources: Map<string, string>): ExpandCtx => ({
+  ...ctx,
+  media: (id) => {
+    const source = sources.get(String(id))
+    return source ? { id, url: source, mimeType: '', width: null, height: null, filename: source.split('/').pop() ?? source } : ctx.media(id)
+  },
+})
+const toSeedStored = (s: NonNullable<ImageSeed>, sources: Map<string, string>): NonNullable<ImageStored> => {
+  const lower = (g: { asset: Id | { source: string }; crop: ImageCrop | null; focalPoint: { x: number; y: number } | null }) => {
+    if (typeof g.asset === 'object') { const key = `seed:${g.asset.source}`; sources.set(key, g.asset.source); return { ...g, asset: key } }
+    return g as { asset: Id; crop: ImageCrop | null; focalPoint: { x: number; y: number } | null }
+  }
+  return { ...lower(s), alt: s.alt, decorative: s.decorative, caption: s.caption, variants: Object.fromEntries(Object.entries(s.variants).filter(([, g]) => g).map(([k, g]) => [k, lower(g!)])) }
+}
+
+export const imageToStored = async (s: ImageSeed, o: O, ctx: SeedCtx): Promise<ImageStored> => {
+  if (s === null) return null
+  const resolve = async (g: { asset: Id | { source: string }; crop: ImageCrop | null; focalPoint: { x: number; y: number } | null }) => ({ ...g, asset: typeof g.asset === 'object' ? await ctx.importAsset(g.asset.source) : g.asset })
+  const variants: Record<string, { asset: Id; crop: ImageCrop | null; focalPoint: { x: number; y: number } | null }> = {}
+  for (const [k, g] of Object.entries(s.variants)) if (g) variants[k] = await resolve(g)
+  return imageStored(o).parse({ ...(await resolve(s)), alt: s.alt, decorative: s.decorative, caption: s.caption, variants })
+}
+
+const mediaRefs = (v: ImageStored): Ref[] => (v ? [{ kind: 'media', id: v.asset }, ...Object.values(v.variants).filter((x) => x).map((x) => ({ kind: 'media' as const, id: x!.asset }))] : [])
+
+export const image = defineElement({
+  id: 'u90/image',
+  version: 1,
+  label: 'Image',
+  placement: 'any',
+  options: ImageOptions,
+  seed: imageSeed,
+  stored: imageStored,
+  read: () => imageRead,
+  complete: (v, _o, field) => {
+    if (v == null) return requiredIssue(false, field)
+    return !v.decorative && !v.alt.trim() ? [{ path: ['alt'], code: 'alt', message: 'Meaningful images need alternative text for publication.' }] : []
+  },
+  refs: mediaRefs,
+  toStored: imageToStored,
+  expand: expandImage,
+  expandSeed: (s, o, ctx) => { if (s === null) return null; const sources = new Map<string, string>(); return expandImage(toSeedStored(s, sources), o, sourceCtx(ctx, sources)) },
+  toText: (v) => (v ? [v.decorative ? '' : v.alt, v.caption ?? ''].filter(Boolean).join(' ') : ''),
+  translatable: (v) => (v ? [...(!v.decorative && v.alt ? [{ path: ['alt'], value: v.alt }] : []), ...(v.caption ? [{ path: ['caption'], value: v.caption }] : [])] : []),
+  translation: {
+    applies: () => true,
+    value: () => z.object({ alt: z.string().min(1).optional(), caption: z.string().optional() }).refine((t) => t.alt !== undefined || t.caption !== undefined, 'An image translation names its alt text or caption.'),
+    pick: (v) => {
+      if (!v) return null
+      const alt = !v.decorative && v.alt ? v.alt : undefined
+      const caption = v.caption ? v.caption : undefined
+      return alt === undefined && caption === undefined ? null : { ...(alt !== undefined ? { alt } : {}), ...(caption !== undefined ? { caption } : {}) }
+    },
+    apply: (base, t) => (base ? { ...base, ...(t.alt !== undefined && !base.decorative ? { alt: t.alt } : {}), ...(t.caption !== undefined ? { caption: t.caption } : {}) } : undefined),
+  },
+  empty: () => null,
+  upgrade: {},
+})