@unitninety/site-kit 0.0.0-stage → 1.6.2

package/src/legacy/defineBlocks.ts

@@ -0,0 +1,1602 @@
+import {
+  normalizeVideoSeed,
+  normalizeFileSeed,
+  videoSeedForImport,
+  fileSeedForImport,
+  type VideoSeedValue,
+  type FileSeedValue,
+} from './media'
+import {
+  imageSeedForImport,
+  normalizeImageSeed,
+  validateImageDeclaration,
+  ImageValidationError,
+  type ImageSeedValue,
+  type ImageConstraints,
+  type ImageVariantDeclaration,
+} from './image'
+import {
+  BLOCK_ENTRY,
+  BRIDGE_VERSION,
+  type BlockEntry,
+  type CollectionRoutes,
+  type EditorBlock,
+  type EditorField,
+  type ManifestCollection,
+  type PageDeclaration,
+  type SeedSection,
+  type SiteManifest,
+  type Spec,
+  type SpecKey,
+} from './contract'
+
+/**
+ * How a site declares its own content schema.
+ *
+ * This is the piece that makes onboarding a client free. The site author writes the
+ * blocks their design actually has; the platform renders an editor from them. No
+ * migration, no deploy, no code in the platform repo.
+ *
+ *   export const blocks = defineBlocks({
+ *     hero: {
+ *       label: 'Hero',
+ *       fields: {
+ *         headline: text({ required: true }),
+ *         slides: array({ fields: { title: text(), photo: upload() } }),
+ *       },
+ *     },
+ *   })
+ *
+ * Blocks and fields are keyed by object rather than listed in arrays, which is not
+ * cosmetic: object keys are unique by construction, so two blocks cannot share a slug
+ * and two fields cannot share a name. Both of those are rejected by the platform's
+ * validator, and this way they are rejected by the type system first — a duplicate
+ * slug makes stored content unresolvable, and a duplicate name makes a dotted path
+ * ambiguous.
+ *
+ * Labels default to a humanised version of the key, because the common case is a label
+ * that just reads the key back.
+ */
+
+/** Everything a field helper accepts. Each helper narrows it. */
+type Common = {
+  /**
+   * What this field currently says on the site, as the *platform* will store it.
+   *
+   * Carried into the manifest's `seed` so a tenant's first pair populates its CMS with the
+   * site's real copy instead of blanks. Never reaches the editor as schema — the platform
+   * stores it once, at pair time, and from then on the stored content is the only truth.
+   */
+  default?: unknown
+  description?: string
+  label?: string
+  readOnly?: boolean
+  required?: boolean
+  /**
+   * What this field currently says on the site, as the *site* renders it.
+   *
+   * Identical to `default` for almost every field. The two diverge exactly where the stored
+   * form and the rendered form differ: `link()` renders `{ href, label }` and stores
+   * `{ kind: 'url', url, … }`. `upload()` carries the same repo path on both, but they mean
+   * different things about it — rendered, it is the asset; seeded, it is the key the
+   * platform's media ingestion relinks to an id.
+   *
+   * This is what `defineSite` collects into `site.values` — the object every component
+   * imports as `brand`.
+   */
+  value?: unknown
+}
+
+/** Available only on copy-bearing scalar helpers. */
+type LocalizableCommon = Common & {
+  /** Eligible copy is localized by default. Set false for identifiers and textual facts. */
+  localized?: boolean
+}
+
+/**
+ * A field before its name is known — the name comes from its object key.
+ *
+ * `V` is the type of the value this field commits, carried phantom-wise through `Spec` so
+ * that `defineSite` can read `site.values` off the helpers a site wrote. It is a property of
+ * the *helper*, not of its argument: widening the argument to `Common | V` is what would let
+ * an options object be mistaken for a bare value, which `opts` would then classify as options
+ * and `base` would spread to `{}` — the value gone, with no error anywhere.
+ */
+type Unnamed<V = unknown> = AnyField & Spec<V>
+
+/**
+ * A field of unstated value type — the shape `FieldSpec` is keyed by.
+ *
+ * Deliberately *without* `Spec`, and that is load-bearing rather than tidy. A helper's value
+ * type is inferred, and a contextual return type is an inference site like any other: were
+ * `FieldSpec` a map of `Unnamed<unknown>`, then `block({ address: group({ … }) })` would
+ * contextually type the `group` call as returning `Spec<unknown>`, `V` would infer as
+ * `unknown` from that alone, and the aggregate default would never be reached — every nested
+ * group in every site would come out `unknown`. Carrying no `VALUE` at all leaves nothing to
+ * infer from, so each helper's own reasoning stands.
+ */
+type AnyField = Omit<EditorField, 'name'> & { name?: never }
+
+/**
+ * The value a field spec commits, or `never` for one that carries nothing.
+ *
+ * `Spec`'s phantom property is optional, so every object matches `Spec<infer V>` — the
+ * `SpecKey extends keyof T` test is what tells a real carrier apart from an object that
+ * simply has no opinion. See `SpecKey`.
+ */
+type Committed<T> = SpecKey extends keyof T ? (T extends Spec<infer V> ? V : never) : never
+
+/**
+ * A non-schema marker `link()` stamps onto the field spec it returns, so that later code
+ * can recognise a link field by how it was *built* rather than guessing from its shape.
+ *
+ * `seedItem` uses this to decide whether to translate an array item's field into the
+ * platform's stored link shape. Guessing instead — e.g. "does this object have an `href`"
+ * — would misfire on a plain `group` field whose committed value happens to have an `href`
+ * alongside other keys, a realistic shape for a card with a title and a link.
+ *
+ * **A symbol, and the one non-schema key `namedFields` does not strip.** `seedItem` recurses,
+ * so it has to recognise a link at *any* depth inside an array item — and a link nested inside
+ * a group has already been through `namedFields` when that group was constructed. A string
+ * marker would have been stripped there, before anything could read it, and the item's
+ * committed `{ href }` would then be pruned as a key the schema does not declare: the button's
+ * URL gone, silently, which is worse than not pruning at all. A symbol key survives an object
+ * rest spread, and is invisible to `JSON.stringify` and `Object.keys` — so it reaches
+ * `seedItem` without reaching the platform, which receives this schema as JSON.
+ *
+ * `Symbol.for`, not `Symbol()`: the registry is keyed by string, so two *instances* of this
+ * package in one bundle — a vendored tarball beside a workspace link, which is exactly how the
+ * first site to use this consumes it — still agree on the marker. With `Symbol()` they would
+ * not, and the failure is silent and is the one this marker exists to prevent: a link built by
+ * one instance is unrecognisable to the other, its committed `href` is pruned as a key the
+ * schema does not declare, and the button is stored with no address.
+ */
+const LINK_FIELD_MARKER: unique symbol = Symbol.for('u90.linkField')
+
+/** A plain object — not null, not an array. The shape a group's committed value has. */
+const isRecord = (value: unknown): value is Record<string, unknown> =>
+  value !== null && typeof value === 'object' && !Array.isArray(value)
+
+const humanise = (key: string): string =>
+  key
+    .replace(/([a-z0-9])([A-Z])/g, '$1 $2')
+    .replace(/[-_]+/g, ' ')
+    .replace(/^./, (c) => c.toUpperCase())
+
+/*
+ * `default` is *kept* on the spec object and stripped later, in `namedFields`.
+ *
+ * It has to survive here: `seedFrom` reads the same spec the author wrote, so a value
+ * dropped at this point is gone before the seed is collected — which is exactly the
+ * bug the round-trip check caught, seed sections arriving with a `blockType` and no
+ * values at all. It must equally never reach the schema, where a field carrying its
+ * default would let a stale site config overwrite what a client typed. So: kept on the
+ * spec, removed on the way into `EditorField[]`.
+ */
+
+/**
+ * Let a scalar helper take its copy directly: `text('Building WA')`.
+ *
+ * The rule is one sentence: **a non-object argument is the value; an object is options.**
+ * It applies only to the scalar helpers, whose values are never objects. `array`, `group`,
+ * `link`, `relationship` and `blocks` keep the object-options form, because theirs are.
+ */
+const opts = (arg: unknown): Common =>
+  isRecord(arg) ? (arg as Common) : { default: arg, value: arg }
+
+const base = <V = unknown>(
+  type: EditorField['type'],
+  raw: Common & { localized?: boolean },
+): Unnamed<V> => {
+  const options: Common & { localized?: boolean } = {
+    ...raw,
+    value: 'value' in raw ? raw.value : raw.default,
+  }
+  return {
+    ...(options.default === undefined ? {} : { default: options.default }),
+    ...(options.value === undefined ? {} : { value: options.value }),
+    ...(options.description === undefined ? {} : { description: options.description }),
+    ...(options.localized === undefined ? {} : { localized: options.localized }),
+    ...(options.readOnly === undefined ? {} : { readOnly: options.readOnly }),
+    ...(options.required === undefined ? {} : { required: options.required }),
+    label: options.label ?? '',
+    type,
+  } as Unnamed<V>
+}
+
+/**
+ * What a scalar helper commits, over `B` — the type its bare form takes.
+ *
+ * Four signatures, resolved in the order `base` itself resolves the carriers: an explicit
+ * `value`, else an explicit `default`, else a bare argument, else **nothing**.
+ *
+ * That last one is the whole point of writing these as overloads. A helper handed no carrier
+ * commits no carrier: `blockValues` skips it, and `brand.pageBody.heading` is `undefined` at
+ * runtime. A signature that answered `string` there would be a type that compiles
+ * `brand.pageBody.heading.trim()` into a `TypeError` — and it would do it at exactly the
+ * fallback-render guarantee this document exists to hold up, in the direction that crashes
+ * rather than renders blank. A hand-written `Brand` said `heading?: string`; this says
+ * `undefined`, which is stricter and equally honest.
+ *
+ * The carrier signatures read the committed type back off what was written rather than
+ * pinning it, because `default` and `value` legitimately hold different shapes — richText
+ * stores a Lexical document and renders copy, an upload's committed value may be an explicit
+ * `null`. What is *not* being done is widening the argument to `Common | V`: each object
+ * signature demands a **named** carrier, so an options object stays options and
+ * `text({ label: 'Headline' })` matches the last signature rather than being read as a value
+ * that `opts` would then classify as options and drop on the floor.
+ */
+type Scalar<B, O extends Common = Common> = {
+  <V>(arg: O & { value: V }): Unnamed<V>
+  <V>(arg: O & { default: V }): Unnamed<V>
+  (arg: B): Unnamed<B>
+  (arg?: O): Unnamed<undefined>
+}
+
+export const text: Scalar<string, LocalizableCommon> = (arg: LocalizableCommon | string = {}) =>
+  base<never>('text', opts(arg) as LocalizableCommon)
+export const textarea: Scalar<string, LocalizableCommon> = (arg: LocalizableCommon | string = {}) =>
+  base<never>('textarea', opts(arg))
+export const number: Scalar<number> = (arg: Common | number = {}) =>
+  base<never>('number', opts(arg))
+export const checkbox: Scalar<boolean> = (arg: Common | boolean = {}) =>
+  base<never>('checkbox', opts(arg))
+export const email: Scalar<string> = (arg: Common | string = {}) => base<never>('email', opts(arg))
+
+/**
+ * A script URL, an embed snippet, or anything else that is code rather than prose.
+ *
+ * Identical to `textarea` in what it stores and what it commits; the type is what tells the
+ * editor to draw a monospace control with spellcheck off and to badge the row `E`. Nothing
+ * about rendering changes — the site does whatever it already did with the string.
+ *
+ * The distinction earns itself the moment a client opens the rail: `pbir`'s reviews block
+ * holds a heading, a lead, two button captions *and* the elfsight script URL, and every one
+ * of them read as plain text. A field a client should almost never touch looked exactly like
+ * the four they edit constantly.
+ */
+export const code: Scalar<string> = (arg: Common | string = {}) => base<never>('code', opts(arg))
+
+/**
+ * Long-form copy, in whichever of its forms the *site* renders.
+ *
+ * The field that made `Scalar` read its answer off the carrier rather than pin it: the
+ * platform stores a Lexical document while a site may render either plain copy or a document
+ * of its own, so `string` would be wrong for every site that renders a document and `unknown`
+ * would put a cast at every reader of a field that is a string almost every time.
+ */
+export const richText: Scalar<string, LocalizableCommon> = (arg: LocalizableCommon | string = {}) =>
+  base<never>('richText', opts(arg))
+
+/**
+ * A calendar day — a post's published date, an event, a completion date.
+ *
+ * Not localizable, unlike `text` and `richText`: a date is the same day in every language,
+ * and `validate.ts` restricts `localized` to the three copy types for that reason.
+ */
+export const date: Scalar<string> = (arg: Common | string = {}) => base<never>('date', opts(arg))
+
+/** The choices a `select` offers: a `{ label, value }` pair, or a value to humanise. */
+type SelectOptions = Common & { options: ({ label: string; value: string } | string)[] }
+
+/**
+ * One of a fixed set of choices.
+ *
+ * The same four cases as `Scalar`, except that the bare form needs the choices alongside it —
+ * a select with no `options` is a control with nothing in it. `select({ options })` on its
+ * own declares the choices and commits none of them, which is `undefined`, not the first
+ * choice: the platform holds no defaults, and a field the site never committed renders as
+ * whatever the component does with nothing.
+ */
+export const select: {
+  <V>(arg: SelectOptions & { value: V }): Unnamed<V>
+  <V>(arg: SelectOptions & { default: V }): Unnamed<V>
+  (arg: string, extra: SelectOptions): Unnamed<string>
+  (arg: SelectOptions): Unnamed<undefined>
+} = (arg: SelectOptions | string, extra?: SelectOptions) => {
+  const options = (extra ? { ...extra, default: arg, value: arg } : arg) as SelectOptions
+  return {
+    ...base<never>('select', options),
+    options: options.options.map((option) =>
+      typeof option === 'string' ? { label: humanise(option), value: option } : option,
+    ),
+  }
+}
+
+/**
+ * An image, video or document from the client's own media library.
+ *
+ * The argument is the **committed** asset the component falls back to — a path in the site
+ * repo. It is carried on both carriers: `value` is what the component renders when the
+ * platform is unreachable, and `default` is the path the platform's media ingestion relinks
+ * to the id of the media document now holding those bytes.
+ *
+ * **This used to seed nothing**, on the reasoning that a tenant's media library is empty
+ * until someone uploads to it, so a repo path stored as a media id would resolve to nothing
+ * and show a broken thumbnail on the day the client paired. That reasoning was right and its
+ * premise has expired: `importArchiveAssets` now uploads every committed path a site names,
+ * and `relinkSeedAssets` swaps the path for the id it was uploaded as. With no path in the
+ * seed there was nothing to swap, so a client paired onto a library full of their own
+ * photographs and an editor whose every image slot read "Use the site's own image".
+ *
+ * The platform is what keeps this honest, and it has to be, because a path is not an id: a
+ * seeded upload value that ingestion did not relink is **dropped** before it is stored — see
+ * `dropUnlinkedUploads` in the platform's `manifest/seed.ts`. A pair with no ingestion behind
+ * it therefore lands exactly where it landed before: an empty slot, and the committed asset
+ * still rendering underneath it.
+ *
+ * `upload()` with no argument commits nothing and is typed `undefined` — a slot the client
+ * fills, with no repo asset underneath it. Reading the carrier back rather than pinning
+ * `string` is also what keeps `upload({ value: null })` honest: an explicit null is a
+ * deliberate "no asset", and it is not a path.
+ */
+export type ImageOptions = Omit<Common, 'default' | 'value' | 'label'> & {
+  label: string
+  default?: ImageSeedValue
+  constraints?: ImageConstraints
+  variants?: Record<string, ImageVariantDeclaration>
+}
+
+/** One atomic Image placement, with upload children retained for media traversal. */
+export const image = (options: ImageOptions): Unnamed<ImageSeedValue> => {
+  const issues = validateImageDeclaration(options)
+  if (issues.length) throw new ImageValidationError(issues)
+  const normalized = normalizeImageSeed(options.default)
+  for (const key of Object.keys(normalized?.variants ?? {})) {
+    if (!Object.hasOwn(options.variants ?? {}, key))
+      throw new ImageValidationError([
+        { path: `variants.${key}`, message: 'Variant is not declared by this field.' },
+      ])
+  }
+  const structural = (): EditorField[] => [
+    { name: 'asset', label: 'Asset', type: 'upload', relationTo: 'media', localized: false },
+    {
+      name: 'focalPoint',
+      label: 'Focal point',
+      type: 'group',
+      localized: false,
+      fields: ['x', 'y'].map((name) => ({ name, label: name, type: 'number' })),
+    },
+    {
+      name: 'crop',
+      label: 'Crop',
+      type: 'group',
+      localized: false,
+      fields: ['x', 'y', 'width', 'height'].map((name) => ({ name, label: name, type: 'number' })),
+    },
+  ]
+  return {
+    ...base<ImageSeedValue>('group', {
+      ...options,
+      default: imageSeedForImport(normalized),
+      value: normalized,
+    }),
+    element: 'image',
+    contractVersion: 1,
+    ...(options.constraints ? { constraints: options.constraints } : {}),
+    ...(options.variants ? { variants: options.variants } : {}),
+    fields: [
+      ...structural(),
+      { name: 'alt', label: 'Alternative text', type: 'text' },
+      { name: 'decorative', label: 'Decorative', type: 'checkbox', localized: false },
+      { name: 'caption', label: 'Caption', type: 'text' },
+      {
+        name: 'variants',
+        label: 'Variants',
+        type: 'group',
+        localized: false,
+        fields: Object.keys(options.variants ?? {}).map((name) => ({
+          name,
+          label: name,
+          type: 'group',
+          fields: structural(),
+        })),
+      },
+    ],
+  }
+}
+
+export type VideoOptions = Omit<Common, 'default' | 'value' | 'label'> & {
+  label: string
+  default?: VideoSeedValue
+  poster?: Pick<ImageOptions, 'label' | 'constraints' | 'variants'>
+}
+export type FileOptions = Omit<Common, 'default' | 'value' | 'label'> & {
+  label: string
+  default?: FileSeedValue
+}
+export const video = (options: VideoOptions): Unnamed<VideoSeedValue> => {
+  const poster = options.poster ?? { label: 'Poster' }
+  const posterField = image(poster)
+  const normalized = normalizeVideoSeed(options.default, { posterVariants: poster.variants ?? {} })
+  return {
+    ...base<VideoSeedValue>('group', {
+      ...options,
+      default: videoSeedForImport(normalized),
+      value: normalized,
+    }),
+    element: 'video',
+    contractVersion: 1,
+    poster: {
+      label: poster.label,
+      ...(poster.constraints ? { constraints: poster.constraints } : {}),
+      ...(poster.variants ? { variants: poster.variants } : {}),
+    },
+    fields: [
+      { name: 'asset', label: 'Asset', type: 'upload', relationTo: 'media', localized: false },
+      { ...posterField, name: 'poster' },
+      ...['posterTime', 'startTime', 'endTime'].map((name) => ({
+        name,
+        label: name,
+        type: 'number' as const,
+        localized: false,
+      })),
+      ...['autoplay', 'muted', 'loop', 'controls', 'playsInline'].map((name) => ({
+        name,
+        label: name,
+        type: 'checkbox' as const,
+        localized: false,
+      })),
+      {
+        name: 'preload',
+        label: 'Preload',
+        type: 'select',
+        localized: false,
+        options: ['none', 'metadata', 'auto'].map((value) => ({ label: value, value })),
+      },
+    ],
+  }
+}
+export const file = (options: FileOptions): Unnamed<FileSeedValue> => {
+  const normalized = normalizeFileSeed(options.default)
+  return {
+    ...base<FileSeedValue>('group', {
+      ...options,
+      default: fileSeedForImport(normalized),
+      value: normalized,
+    }),
+    element: 'file',
+    contractVersion: 1,
+    fields: [
+      { name: 'asset', label: 'Asset', type: 'upload', relationTo: 'media', localized: false },
+      ...['label', 'description', 'downloadName'].map((name) => ({
+        name,
+        label: name,
+        type: 'text' as const,
+      })),
+    ],
+  }
+}
+
+export const upload: Scalar<string> = (arg: Common | string = {}) => {
+  const options = opts(arg)
+  const committed = 'value' in options ? options.value : options.default
+  return {
+    ...base<never>('upload', { ...options, default: committed, value: committed }),
+    relationTo: 'media',
+  }
+}
+
+/** Everything `relationship()` accepts beyond the common carriers. */
+type RelationshipOptions = Common & {
+  hasMany?: boolean
+  inverse?: { label: string; name: string }
+  relationTo: string
+}
+
+/**
+ * A reference to another record — one of this site's pages, or rows of one of its own
+ * collections.
+ *
+ * `relationTo: 'pages'` is the page link `link()` uses and is reserved. Anything else must
+ * name a collection this site declares in `defineCollections`, or the platform rejects the
+ * whole manifest rather than render a picker with nothing in it.
+ *
+ * `hasMany` makes it an ordered list of references; the order is the client's and is stored.
+ * `inverse` asks the target collection to show this edge from its own side — see `EditorField`.
+ *
+ * Answers `undefined` when nothing was committed, the same as every other helper. It used to
+ * answer `unknown`, on the reasoning that `unknown` refuses every dereference and so cannot
+ * crash. It can: `unknown` is not `undefined`, so a *group* holding one uncommitted reference
+ * read as present — `Aggregate` saw a member that was not `undefined` and typed the whole
+ * group as an object. The crash then lands one level up, at the group, where the members
+ * never get the chance to refuse anything. A page reference beside a caption the client fills
+ * in is an ordinary block, so this has to be exact rather than merely cautious.
+ */
+export const relationship: {
+  <V>(options: RelationshipOptions & { value: V }): Unnamed<V>
+  <V>(options: RelationshipOptions & { default: V }): Unnamed<V>
+  (options: RelationshipOptions): Unnamed<undefined>
+} = (options: RelationshipOptions) => ({
+  ...base<never>('relationship', options),
+  ...(options.hasMany === undefined ? {} : { hasMany: options.hasMany }),
+  ...(options.inverse === undefined ? {} : { inverse: options.inverse }),
+  relationTo: options.relationTo,
+})
+
+/**
+ * A field whose value lives once, in the client's Singles, and is pointed at from here.
+ *
+ * `reference('phone')` names the **default** key. The block stores nothing until a client
+ * overrides it, so a field that has never been touched still resolves — see the design note
+ * on why an unwired state is not allowed to exist.
+ *
+ * The platform resolves this on egress, so a site reads it exactly as it reads a text field
+ * and needs no concept of a Single at all.
+ *
+ * Not `relationTo`, deliberately: see `EditorFieldType`'s `'reference'` case in
+ * `contract.ts` for why sharing it with `relationship()` would put `_singles` where a
+ * client's own collections belong.
+ */
+export const reference = (
+  defaultKey: string,
+  options: { description?: string; label?: string } = {},
+) => ({ ...base<never>('reference', options), referenceKey: defaultKey })
+
+/**
+ * The committed value of every child that carries one, keyed by name.
+ *
+ * Read at construction time, before `namedFields` strips `value` from each child on its way
+ * into the group's own schema `fields`. By the time a group is walked from the outside —
+ * `defineSite`'s `blockValues`, say — its children are schema-only and carry nothing;
+ * aggregating here, once, is what lets a bare `group()` still contribute its children's
+ * committed copy. A nested group's own aggregate was already computed when *it* was built,
+ * so reading its top-level `value` here is enough — no recursion required.
+ */
+const aggregateValues = (fields: FieldSpec): Record<string, unknown> | undefined => {
+  const out: Record<string, unknown> = {}
+  for (const [name, field] of Object.entries(fields)) {
+    const value = (field as { value?: unknown }).value
+    if (value !== undefined) out[name] = value
+  }
+  return Object.keys(out).length > 0 ? out : undefined
+}
+
+/**
+ * What a group's children commit between them — or `undefined` when that is nothing at all.
+ *
+ * Mirrors `aggregateValues`, which returns `undefined` rather than an empty object when no
+ * child carries a value. A group of fields a client fills in and the site commits none of is
+ * absent from `site.values` entirely, so the type has to be absent too; saying `{ open:
+ * undefined; close: undefined }` would let `brand.contact.hours.open` compile against a
+ * `hours` that is itself `undefined`.
+ *
+ * **This rests on every helper answering `undefined` — not `unknown` — when it was handed no
+ * carrier**, and it is why `relationship` and `blocks` had to stop answering `unknown`. One
+ * member that is merely *unreadable* rather than *absent* fails the test below, and the whole
+ * group then types as present. Any new helper has to keep that bargain or this silently
+ * over-promises again, one level above where the wrong type was written.
+ */
+type Aggregate<F> =
+  { [K in keyof F]: Committed<F[K]> } extends Record<string, undefined>
+    ? undefined
+    : { [K in keyof F]: Committed<F[K]> }
+
+/** The seed default of every child that carries one, keyed by name. See `aggregateValues`. */
+const aggregateDefaults = (fields: FieldSpec): Record<string, unknown> | undefined => {
+  const out: Record<string, unknown> = {}
+  for (const [name, field] of Object.entries(fields)) {
+    const value = (field as { default?: unknown }).default
+    if (value !== undefined) out[name] = value
+  }
+  return Object.keys(out).length > 0 ? out : undefined
+}
+
+/**
+ * A named group of fields, edited together as one panel.
+ *
+ * Carries its own `default`/`value` the way every other helper does — aggregated from
+ * whichever children carry one, at construction time, before `namedFields` strips those
+ * carriers from the children on their way into this group's own schema `fields`. An
+ * explicit `default`/`value` passed to `group()` itself wins over the aggregate: `link()`
+ * hands `group()` its own translated `default`/`value`, and those must not be overwritten
+ * by an aggregate over its five schema-only children.
+ *
+ * The type follows the runtime's precedence exactly, which is why `default` and `value` are
+ * lifted out of `Common` and given parameters of their own: an explicit `value` wins, else
+ * the children's aggregate, else an explicit `default`. **A group none of whose children
+ * committed anything aggregates to nothing, and `aggregateValues` returns `undefined` rather
+ * than `{}`** — so `Aggregate` collapses to `undefined` in that case, and a reader is made to
+ * check before dereferencing something that is genuinely not there.
+ *
+ * The aggregate is computed from the *spec map* the caller wrote, never from `fields` on the
+ * returned descriptor — `namedFields` has already turned that into an `EditorField[]` with
+ * the carriers stripped, so a reader walking it from the outside would find nothing at all.
+ */
+export const group = <F extends FieldSpec, V = never, D = undefined>(
+  options: Omit<Common, 'default' | 'value'> & { default?: D; fields: F; value?: V },
+): Unnamed<[V] extends [never] ? (Aggregate<F> extends undefined ? D : Aggregate<F>) : V> => {
+  const aggregatedDefault = aggregateDefaults(options.fields)
+  const aggregatedValue = aggregateValues(options.fields)
+  const groupDefault = options.default !== undefined ? options.default : aggregatedDefault
+  const groupValue =
+    options.value !== undefined
+      ? options.value
+      : aggregatedValue !== undefined
+        ? aggregatedValue
+        : groupDefault
+
+  return {
+    ...base<never>('group', {
+      ...options,
+      ...(groupDefault === undefined ? {} : { default: groupDefault }),
+      ...(groupValue === undefined ? {} : { value: groupValue }),
+    }),
+    fields: namedFields(options.fields),
+  }
+}
+
+/**
+ * A committed button in the shape the platform stores.
+ *
+ * The site writes what it renders — `{ href, label }`, what `resolveLink(cms, fallback)`
+ * takes — while the inspector edits a group of `{ kind, url, newTab, … }`. One translation,
+ * read by `link()` for its own seed and by `seedItem` for a link inside an array item; they
+ * were two copies of the same six lines, which is one copy too many for a shape the platform
+ * stores permanently.
+ */
+const storedLink = (committed: LinkValue & { text?: string }): Record<string, unknown> => ({
+  /*
+   * A sentence's copy rides through the same translation as the link inside it, because a
+   * sentence *is* a link group with one field more — see `sentence()`. Conditional rather
+   * than always present, so an ordinary button stores exactly the four keys it always did.
+   */
+  ...(committed.text === undefined ? {} : { text: committed.text }),
+  ...(committed.label === undefined ? {} : { label: committed.label }),
+  kind: 'url',
+  newTab: committed.newTab ?? false,
+  url: committed.href,
+})
+
+/**
+ * A link `default` already in the shape the platform stores, rather than the shape a
+ * component renders. `link()` must accept either: before this file translated `{ href }`
+ * into `{ kind, url }`, a `default` passed straight through, so a site whose own helper
+ * already builds the stored shape — as jdsi's `seedLink()` does — got it stored correctly.
+ * Making `link()` translate unconditionally silently broke that site on upgrade, with no
+ * error: `committed.href` read `undefined` off an object that never had an `href`, and the
+ * button lost its address.
+ *
+ * Discriminated by a key only the stored shape carries — `kind` or `url` — never by the
+ * *absence* of `href`. A committed link legitimately written as `{ href: undefined }` for
+ * some placeholder case would otherwise be misread as already-stored.
+ */
+const isStoredLinkValue = (value: unknown): value is Record<string, unknown> =>
+  isRecord(value) && ('kind' in value || 'url' in value)
+
+/**
+ * The rendered equivalent of an already-stored link — the inverse of `storedLink`, read only
+ * to populate `value`.
+ *
+ * `value` is what `site.values` carries into the component that actually renders this link,
+ * and a component reads `{ href, label }` — see `LinkValue`. Leaving `value` empty when
+ * `default` arrives pre-stored would mean `brand.*.cta.href` silently disappears at the one
+ * carrier a component reads, even though the field's stored `url` is intact. `href` falls
+ * back to `''` rather than `undefined` for a `kind: 'page'` default with no `url` of its own
+ * — there is no resolved page address available at spec-building time, and `''` keeps
+ * `LinkValue.href` the required string a component's `resolveLink` expects rather than
+ * widening it to optional for a case no site actually writes today.
+ */
+const valueFromStored = (stored: Record<string, unknown>): LinkValue & { text?: string } => ({
+  ...(stored.text === undefined ? {} : { text: stored.text as string }),
+  ...(stored.label === undefined ? {} : { label: stored.label as string }),
+  href: (stored.url as string | undefined) ?? '',
+  ...(stored.newTab === undefined ? {} : { newTab: stored.newTab as boolean }),
+})
+
+/**
+ * The blocks a zone field may hold, from whichever form it used.
+ *
+ * **This is the third copy of this exact resolution rule**, not the second. `childBlockFor` /
+ * `childBlocksFor` in `src/dashboard/canvas/nestedBlocks.ts` is the platform's own authority;
+ * `childrenOf` in `uploads.ts` (this package) duplicates it because uploads.ts is vendored into
+ * every client's site and cannot import from the platform's `src/`. This is a third copy for
+ * the same reason — `defineBlocks.ts` cannot import from `uploads.ts` either without pulling
+ * upload-collection code into a seeding path that has nothing to do with it, and the two
+ * modules within this package are otherwise independent. Three copies, named by file in all
+ * three doc comments — say the number and every path, not "the pair" or "the only duplicate",
+ * or the count is the next thing to go stale. `verify:nested-blocks` checks all three agree,
+ * not only `nestedBlocks.ts` and `uploads.ts`; this function is not exported, so that check
+ * exercises it through observable behaviour rather than calling it directly — see the check
+ * itself for why.
+ *
+ * `field.blocks` (inline definitions) is returned as-is when present; otherwise each entry of
+ * `field.childBlocks` (slugs) is looked up in `allBlocks` — the site's full declared block
+ * library — skipping any slug that resolves to nothing.
+ */
+const childrenOf = (field: EditorField, allBlocks: EditorBlock[]): EditorBlock[] => {
+  if (field.blocks !== undefined) return field.blocks
+
+  const resolved: EditorBlock[] = []
+  for (const slug of field.childBlocks ?? []) {
+    const block = allBlocks.find((entry) => entry.slug === slug)
+    if (block !== undefined) resolved.push(block)
+  }
+  return resolved
+}
+
+/**
+ * One zone's committed items, each translated against the block it names.
+ *
+ * A zone's children are heterogeneous — every entry names its own shape by `blockType` — so
+ * unlike `group`/`array` there is no single `fields` to walk them against. Each entry is
+ * looked up in `allBlocks` by that name and walked with `seedItem` against *its own* declared
+ * fields; an entry naming a block `allBlocks` does not carry (a slug that resolves to nothing,
+ * or simply not a record) is passed through untouched, the same "prune, do not correct" rule
+ * `seedItem` applies to a value of the wrong shape.
+ *
+ * `blockType` itself is not a declared field of the child block, so `seedItem`'s own loop —
+ * which only ever copies keys present in the `fields` map it is given — would drop it. It is
+ * added back explicitly, from the resolved block's own slug rather than the entry's, for the
+ * reason `publishedBlock` refuses a slugless zone block at declaration time: the stored name
+ * and the declared name must be the same string or a later read would not find the block this
+ * write resolved against.
+ */
+const seedZone = (field: EditorField, raw: unknown[], allBlocks: EditorBlock[]): unknown[] => {
+  const nested = new Map(childrenOf(field, allBlocks).map((block) => [block.slug, block]))
+  return raw.map((entry) => {
+    if (!isRecord(entry)) return entry
+    const blockType = (entry as { blockType?: unknown }).blockType
+    const child = typeof blockType === 'string' ? nested.get(blockType) : undefined
+    if (!child) return entry
+    return { ...seedItem(namedFieldSpec(child.fields), entry, allBlocks), blockType: child.slug }
+  })
+}
+
+/**
+ * One array item, reduced to what the platform should store.
+ *
+ * Undeclared keys are dropped and a nested `link` is translated — the same rules the field
+ * helpers apply one level up, applied per item because an array's values arrive as whole
+ * objects rather than through the helpers.
+ *
+ * **Uploads used to be dropped here too**, and now ride along as the committed repo path.
+ * See `upload()` for why that flipped: the path is the only thing that tells the platform's
+ * media ingestion which uploaded file belongs in which slot, and a row's portrait is written
+ * per row — so pruning it here left `relinkSeedAssets` with nothing to relink and every
+ * seeded row imageless. The platform drops any path ingestion did not relink, which is what
+ * keeps a repo path from ever being stored as a media id.
+ *
+ * A field is translated as a link only when it carries `LINK_FIELD_MARKER` — i.e. it was
+ * built by `link()` — never by guessing from shape. A plain `group` whose committed value
+ * happens to have an `href` alongside other keys (a card with a title and a link, say) is
+ * not a link and must survive with every one of its keys intact.
+ *
+ * **`group`, `array` and `blocks` all recurse, because the rule is the field type and not the
+ * nesting level** — this used to say only `group` and `array` did, which was true right up
+ * until a site declared a zone with committed children and the missing case went unnoticed
+ * until PBIR's nav did exactly that. A `group` or `array` *inside* an item is walked against
+ * its own declared fields, which is what carries a nested `upload()`'s path through to the
+ * platform and what prunes an undeclared key a one-level walk would let ride along. A `blocks`
+ * zone recurses differently — see `seedZone` — because its children do not share one shape to
+ * walk them against; each is resolved against the block its own `blockType` names, out of
+ * `allBlocks`, the full library this call was handed.
+ *
+ * **`allBlocks` is only ever non-empty when this walk starts from `startersFrom`.** The other
+ * two callers — `array()`'s own `default` translation and `defineCollections`' row seeding —
+ * run while a site's module is still being evaluated, before `defineSite` has finished
+ * collecting every declared block into one list, so a zone nested inside an array item or a
+ * collection row cannot resolve a slug-named child (`of: [...]`) at that point and is passed
+ * through unresolved — not a regression, the same as before this case existed at all. Only a
+ * zone reached through a block's own top-level field, or nested inside another such zone's own
+ * items, resolves — which is every zone this plan's PBIR case needed.
+ *
+ * Those nested fields are an `EditorField[]` rather than the map the author wrote —
+ * `group()` and `array()` call `namedFields` on their children when they are *constructed*,
+ * long before anything seeds — so `namedFieldSpec` puts the names back on before the
+ * recursion, which is the same normalisation `defineSite`'s `validate` needs for the same
+ * reason. A committed value of the wrong shape for its field (a string where a group is
+ * declared, `null` where an array is) is passed through untouched rather than forced: this
+ * prunes, it does not correct.
+ */
+const seedItem = (
+  fields: FieldSpec,
+  item: Record<string, unknown>,
+  allBlocks: EditorBlock[],
+): Record<string, unknown> => {
+  const out: Record<string, unknown> = {}
+  for (const [name, field] of Object.entries(fields)) {
+    if (!(name in item)) continue
+    const descriptor = field as unknown as EditorField & {
+      fields?: unknown
+      [LINK_FIELD_MARKER]?: true
+    }
+    const raw = item[name]
+    if (descriptor.element === 'video' || descriptor.element === 'file') {
+      out[name] =
+        descriptor.element === 'video'
+          ? videoSeedForImport(raw, { posterVariants: descriptor.poster?.variants ?? {} })
+          : fileSeedForImport(raw)
+      continue
+    }
+    if (descriptor.element === 'image') {
+      const normalized = normalizeImageSeed(raw)
+      for (const key of Object.keys(normalized?.variants ?? {}))
+        if (!Object.hasOwn(descriptor.variants ?? {}, key))
+          throw new ImageValidationError([
+            { path: `${name}.variants.${key}`, message: 'Variant is not declared by this field.' },
+          ])
+      out[name] = imageSeedForImport(normalized)
+      continue
+    }
+    if (descriptor[LINK_FIELD_MARKER]) {
+      // Either shape, for the reason `link()` accepts either — see `isStoredLinkValue`. A
+      // row or item whose helper already built the stored form must not be translated twice,
+      // which reads `href` off an object that never had one and drops the address.
+      out[name] = isStoredLinkValue(raw) ? raw : storedLink(raw as LinkValue)
+      continue
+    }
+    if (descriptor.type === 'group' && isRecord(raw)) {
+      out[name] = seedItem(namedFieldSpec(descriptor.fields), raw, allBlocks)
+      continue
+    }
+    if (descriptor.type === 'array' && Array.isArray(raw)) {
+      const nested = namedFieldSpec(descriptor.fields)
+      out[name] = (raw as unknown[]).map((entry) =>
+        isRecord(entry) ? seedItem(nested, entry, allBlocks) : entry,
+      )
+      continue
+    }
+    if (descriptor.type === 'blocks' && Array.isArray(raw)) {
+      out[name] = seedZone(descriptor, raw as unknown[], allBlocks)
+      continue
+    }
+    out[name] = raw
+  }
+  return out
+}
+
+/**
+ * A field descriptor built by one of the helpers above, as opposed to a `FieldSpec` map.
+ *
+ * `base` always stamps a string `type` and a string `label` onto whatever it returns, so a
+ * descriptor is recognisable by that pair and a fields-map is not — a map's own `.type`
+ * property only exists when one of its fields happens to be named `type`, and that field's
+ * value is itself a descriptor object, not a string. This is what lets `array` tell its
+ * legacy form apart from a new-form field-spec that happens to declare a field named `fields`.
+ */
+const isFieldDescriptor = (value: unknown): boolean =>
+  value !== null &&
+  typeof value === 'object' &&
+  typeof (value as Record<string, unknown>).type === 'string' &&
+  typeof (value as Record<string, unknown>).label === 'string'
+
+/**
+ * A repeating set of items that all share one shape.
+ *
+ * `array(fields, items)` — the fields first, the committed items second. The items are the
+ * value the component falls back to and may carry keys the fields do not declare: a slide's
+ * `video`, a poster's `posterFallback`. Those ride along in `site.values` and are pruned out
+ * of the seed, because a key with no field is a key no client can edit and the platform has
+ * no business storing it.
+ *
+ * The legacy `array({ fields, … })` form is still accepted, so specs written for
+ * `defineBlocks` keep compiling. It is distinguished by carrying a `fields` key whose value
+ * is *not itself a field descriptor* — see `isFieldDescriptor`. The legacy branch is passed
+ * straight to `base` untouched: no `seedItem` pruning runs over it, because its `default` was
+ * already written as whole stored rows by the site author, not derived from committed items.
+ *
+ * The committed items are also where the *type* comes from: an item is a whole object, so
+ * there is nothing to read it off except the items themselves. Reading it off `fields`
+ * instead would give the wrong answer even in principle — `namedFields` runs on those at
+ * construction time, so by the time anything can look, the shape is an `EditorField[]` with
+ * neither the carriers nor the author's key names left on it.
+ *
+ * **`array(fields)` with no items commits nothing, and is typed `undefined` rather than an
+ * empty list.** This is the sharpest case of the four `Scalar` covers, because the reader is
+ * a `.map()` rather than a property access: a type saying `Record<string, unknown>[]` would
+ * compile `brand.hero.gallery.map(…)` straight into a `TypeError`. It is *not* fixed by
+ * writing `[]` at runtime — a declared-but-uncommitted array genuinely has nothing in it, and
+ * a site that means an empty list writes `array(fields, [])` and gets one. (A collection
+ * differs: `defineSite` writes `rows ?? []` there, so it reads as `[]` in both the type and
+ * at runtime.)
+ */
+export const array: {
+  <I extends Record<string, unknown>>(first: FieldSpec, items: I[], extra?: Common): Unnamed<I[]>
+  <V>(first: Common & { fields: FieldSpec; value: V }): Unnamed<V>
+  <V>(first: Common & { fields: FieldSpec; default: V }): Unnamed<V>
+  (first: Common & { fields: FieldSpec }): Unnamed<undefined>
+  (first: FieldSpec): Unnamed<undefined>
+} = (
+  first: (Common & { fields: FieldSpec }) | FieldSpec,
+  items?: Record<string, unknown>[],
+  extra: Common = {},
+) => {
+  const legacy = 'fields' in first && !isFieldDescriptor((first as { fields: unknown }).fields)
+
+  if (legacy) {
+    const options = first as Common & { fields: FieldSpec }
+    return {
+      ...base<never>('array', options),
+      fields: namedFields(options.fields),
+    }
+  }
+
+  const fields = first as FieldSpec
+  const options: Common = { ...extra, ...(items === undefined ? {} : { value: items }) }
+  const value = ('value' in options ? options.value : options.default) as
+    Record<string, unknown>[] | undefined
+
+  return {
+    ...base<never>('array', {
+      ...options,
+      /*
+       * `allBlocks: []`, not the site's full library — this runs while the site's module is
+       * still being evaluated, before `defineSite` has finished collecting every declared
+       * block into one list. A zone nested inside one of these items and named by slug
+       * (`of: [...]`) cannot resolve here for exactly that reason; see the note on
+       * `seedItem`. An inline zone (`blocks: [...]`) is unaffected — `childrenOf` reads that
+       * form straight off the field, no registry needed.
+       */
+      ...(value === undefined ? {} : { default: value.map((item) => seedItem(fields, item, [])) }),
+      ...(value === undefined ? {} : { value }),
+    }),
+    fields: namedFields(fields),
+  }
+}
+
+/**
+ * A dynamic zone: an ordered list of sections whose shapes differ from one another.
+ *
+ * The distinction from `array` is *shape*, not ownership. An array's items all have the
+ * same fields, so one field list describes every one of them. A zone's sections each name
+ * their own block in `blockType`, and are read against that block alone — which is what
+ * lets one project lead with a gallery and the next with a quote.
+ *
+ * The client adds, removes and reorders these in Canvas, and that is the point: on a row,
+ * arrangement *is* the content. Give it the blocks the section may be — usually a subset
+ * of the same `defineBlocks` call the rest of the site uses, since a block is worth
+ * writing once:
+ *
+ *   body: blocks({ label: 'Body', blocks: [gallery, quote] })
+ *
+ * Two things worth knowing before you declare one. A section is created empty — the
+ * platform holds no defaults, deliberately — so a block with a `required` field cannot be
+ * added by a client at all until they fill it, and one with no editable fields at all
+ * renders in the rail with nothing under it. Both are legal; neither is much use.
+ *
+ * A zone is created empty, so the uncommitted form is the *normal* one here rather than the
+ * exception — all the more reason for it to answer `undefined`. See `relationship` for why
+ * `unknown` was not safe.
+ *
+ * **Either form of block is accepted**: a `defineBlocks` result, or the `block()` entries a
+ * brand document writes. Without the second, a site using `defineSite` would have to keep a
+ * `defineBlocks` call beside it purely to describe its zones, which is the duplication the
+ * one-document rule exists to remove. A zone block seeds nothing whichever way it is written
+ * — only a top-level entry seeds — so `block()`'s `seed` is not read here.
+ *
+ * **A zone's children can be named two ways.** `blocks: [gallery, quote]` above embeds their
+ * definitions, which is what every zone has done until now. `of: ['navItem']` instead names
+ * slugs, resolved against the site's declared blocks when read — the only form that can
+ * express a block containing itself, since an embedded definition would have to serialise its
+ * own expansion forever. Exactly one of the two is meaningful on any call, and this constructor
+ * throws if a caller supplies neither or both — a typed call can't reach either case, but an
+ * agent-authored declaration built from a spread object or an `any`-typed value can, and a loud
+ * failure at declaration time beats an empty zone silently rendering as a section with nothing
+ * in it. The platform's manifest validator (`src/manifest/validate.ts`) enforces the same rule
+ * again on the way in, for a declaration that arrives some other way.
+ *
+ * **A zone may commit its children whichever way it names them.** `value`/`default` resolve the
+ * same for `of: [...]` as they do for `blocks: [...]` — a nav item with sub-items needs the
+ * slug form to express itself at all, and needs a starting menu just as much as any other zone
+ * does, so the carrier overloads exist for both forms rather than only the older one.
+ */
+export const blocks: {
+  <V>(options: Common & { blocks: ZoneBlock[]; value: V }): Unnamed<V>
+  <V>(options: Common & { blocks: ZoneBlock[]; default: V }): Unnamed<V>
+  (options: Common & { blocks: ZoneBlock[] }): Unnamed<undefined>
+  <V>(options: Common & { of: string[]; value: V }): Unnamed<V>
+  <V>(options: Common & { of: string[]; default: V }): Unnamed<V>
+  (options: Common & { of: string[] }): Unnamed<undefined>
+} = (options: Common & { blocks?: ZoneBlock[]; of?: string[] }) => {
+  if (options.blocks === undefined && options.of === undefined) {
+    throw new Error(
+      `A zone names no children. Give it blocks: [...] to embed their definitions, or of: [...] to name their slugs — a zone with neither is a field with nothing to render.`,
+    )
+  }
+  if (options.blocks !== undefined && options.of !== undefined) {
+    throw new Error(
+      `A zone names its children two ways at once. blocks: [...] embeds definitions and of: [...] names slugs; the two would disagree the moment a block was renamed, so exactly one is required, not both.`,
+    )
+  }
+
+  return {
+    ...base<never>('blocks', options),
+    /*
+     * One form or the other, never both — enforced above, so `options.blocks` is defined in
+     * exactly the branch that reads it.
+     */
+    ...(options.of === undefined
+      ? { blocks: options.blocks!.map(publishedBlock) }
+      : { childBlocks: options.of }),
+  }
+}
+
+/** A section a zone may hold: already published, or still as the site wrote it. */
+export type ZoneBlock = BlockEntry<FieldSpec> | EditorBlock
+
+/** Guarded like `isBlock`/`isCollection`: `in` on a `null` from a JS caller is a TypeError. */
+const isBlockEntry = (value: ZoneBlock): value is BlockEntry<FieldSpec> =>
+  value !== null && typeof value === 'object' && BLOCK_ENTRY in value
+
+/**
+ * A zone's block in the published form, from whichever form the site wrote.
+ *
+ * The conversion is `defineBlocks`'s, key for key, because the same block has to arrive at
+ * the platform the same way no matter which call built it — the schema is what stored content
+ * is read back against.
+ *
+ * A zone block has no document key to take a slug from, so it states its own. Refusing here
+ * is the whole reason this throws rather than inventing one: a slug keys stored content
+ * permanently, and a guess made at publish time would be a different guess after any edit.
+ */
+const publishedBlock = (entry: ZoneBlock): EditorBlock => {
+  if (!isBlockEntry(entry)) return entry
+  const { slug } = entry
+  if (!slug) {
+    throw new Error(
+      `A block in this zone declares no slug. A zone's blocks are not keyed by a document key, so each states its own: block({ … }, { slug: 'gallery' }). Stored sections name their block by slug, so one without a slug could never be read back.`,
+    )
+  }
+  return { fields: namedFields(entry.fields), label: entry.label ?? humanise(slug), slug }
+}
+
+/**
+ * A button as the *site* renders it — what `resolveLink(cms, fallback)` takes.
+ *
+ * Deliberately not the shape the platform stores; see `link()` for the translation between
+ * the two, and `Common.value` for why a helper may commit one shape and seed another.
+ */
+export type LinkValue = { href: string; label?: string; newTab?: boolean }
+
+/**
+ * A button: its words, where it goes, and whether it opens a new tab.
+ *
+ * The group it returns carries `button: true` into the published schema, and that flag —
+ * not the key the site happened to file it under — is what makes the inspector edit the
+ * whole thing as one panel instead of five separate fields. It used to be the name: a
+ * group called exactly `link` got the panel and anything else got five loose controls,
+ * which spent a block's one good name on its first button and left a second one with
+ * nowhere to go. Writing `cta: link({ label: 'Submit Button' })` beside `link: link({ … })`
+ * now gives two buttons, each named for what it does.
+ *
+ * `withLabel: false` is for a tile or row whose entire surface is the link, so no button
+ * text is rendered and modelling one would put a dead field in the client's editor.
+ *
+ * `link()` with no committed button commits nothing: all five of its children are declared
+ * without carriers, so the group aggregates to `undefined`. The committed type is read back
+ * off what was written, so `brand.hero.cta.label` is a `string` when a label was written and
+ * a compile error when the site never wrote one — rather than a `TypeError` in a component
+ * rendering a button that does not exist.
+ */
+/**
+ * The five fields a destination is made of, built once because two helpers need them.
+ *
+ * `link()` and `sentence()` publish the same button underneath — the inspector's panel edits
+ * `label`, `kind`, `page`, `url` and `newTab` whichever of the two declared them, and a
+ * second copy of the list here would be a second copy of the shape the platform stores.
+ */
+const linkFields = ({
+  pageCollection,
+  withLabel,
+}: {
+  pageCollection: string
+  withLabel: boolean
+}): FieldSpec => ({
+  ...(withLabel ? { label: text({ description: 'The words on the button.' }) } : {}),
+  kind: select({
+    description: 'Where the button goes.',
+    options: [
+      { label: 'A page on this site', value: 'page' },
+      { label: 'A web address', value: 'url' },
+    ],
+  }),
+  page: relationship({ description: 'Pick one of your pages.', relationTo: pageCollection }),
+  url: text({
+    description: 'A full address, a path on this site, or a mailto:/tel: link.',
+    localized: false,
+  }),
+  newTab: checkbox({ label: 'Open in a new tab' }),
+})
+
+export const link: {
+  <V extends LinkValue>(
+    options: Common & { pageCollection?: string; value: V; withLabel?: boolean },
+  ): Unnamed<V>
+  <V extends LinkValue>(
+    options: Common & { default: V; pageCollection?: string; withLabel?: boolean },
+  ): Unnamed<V>
+  (options?: Common & { pageCollection?: string; withLabel?: boolean }): Unnamed<undefined>
+} = (options: Common & { pageCollection?: string; withLabel?: boolean } = {}) => {
+  const { pageCollection = 'pages', withLabel = true } = options
+  const raw = options.default as undefined | LinkValue | Record<string, unknown>
+
+  /*
+   * A committed button is written the way the site renders it — `{ href, label }`, what
+   * `resolveLink(cms, fallback)` takes. The platform stores the group the inspector edits,
+   * which is a different shape. Translating here rather than asking each site to write
+   * `{ kind: 'url', url }` by hand is what removes jdsi's `seedLink` helper — but a site
+   * that already writes the stored shape (jdsi's own `seedLink()` did, until it was
+   * removed) must still be accepted: see `isStoredLinkValue`.
+   */
+  const alreadyStored = raw !== undefined && isStoredLinkValue(raw)
+  const stored = raw === undefined ? undefined : alreadyStored ? raw : storedLink(raw as LinkValue)
+  const committed =
+    raw === undefined ? undefined : alreadyStored ? valueFromStored(raw) : (raw as LinkValue)
+
+  return {
+    /*
+     * Schema, unlike `LINK_FIELD_MARKER` beneath it: this one is meant to be published.
+     * `namedFields` spreads whatever the descriptor carries into the field it emits, so
+     * it reaches the platform as JSON and the inspector reads it there.
+     */
+    element: 'button' as const,
+    ...group({
+      ...options,
+      ...(stored === undefined ? {} : { default: stored }),
+      ...(committed === undefined ? {} : { value: committed }),
+      fields: linkFields({ pageCollection, withLabel }),
+    }),
+    [LINK_FIELD_MARKER]: true,
+  } as Unnamed<never>
+}
+
+/** The marker that says where the link falls inside a sentence. See `sentence()`. */
+export const SENTENCE_LINK = '{link}'
+
+/**
+ * A sentence as the *site* renders it: the copy, and the link inside it.
+ *
+ * `text` holds the whole line with `{link}` standing where the link goes. One string, not
+ * two, and that is the entire point — see `sentence()`.
+ */
+export type SentenceValue = LinkValue & { text: string }
+
+/**
+ * A line of copy with one link inside it, edited as one thing.
+ *
+ *   privacyNote: sentence({
+ *     label: 'Privacy Note',
+ *     default: {
+ *       text: 'See our {link} for how we handle your details.',
+ *       href: '/privacy',
+ *       label: 'Privacy Policy',
+ *     },
+ *   })
+ *
+ * **Why this exists rather than three fields.** pbir's privacy line was `before`, `link`,
+ * `after` — a text field, a button and another text field, three rows in the rail for one
+ * sentence. It read badly and it rendered wrongly: `text()` in `shape.ts` trims what it is
+ * given, so `'See our '` came back without the space that separated it from the link, and
+ * the page said `See ourPrivacy Policyfor how we handle your details.` **Whitespace between
+ * two fields belongs to neither of them**, and no amount of care in either field can hold
+ * it. One string can, because the spaces are interior to it.
+ *
+ * The link keeps everything a button has: its words, a page on this site or a web address,
+ * and whether it opens a new tab. What it does not keep is a row of its own — the inspector
+ * draws the sentence and its destination in one panel, which `element: 'sentence'` is what
+ * asks for.
+ *
+ * `{link}` is a marker in the copy, not markup: a client types a normal sentence and the
+ * marker says where the link falls. A sentence that has lost its marker still renders its
+ * link, appended — see `resolveSentence` in `shape.ts`. A legal link that vanishes because
+ * somebody rewrote the sentence around it is a worse failure than one in an awkward place.
+ */
+export const sentence: {
+  <V extends SentenceValue>(options: Common & { default: V; pageCollection?: string }): Unnamed<V>
+  <V extends SentenceValue>(options: Common & { pageCollection?: string; value: V }): Unnamed<V>
+  (options?: Common & { pageCollection?: string }): Unnamed<undefined>
+} = (options: Common & { pageCollection?: string } = {}) => {
+  const { pageCollection = 'pages' } = options
+  const raw = options.default as undefined | Record<string, unknown> | SentenceValue
+
+  /*
+   * Translated exactly as `link()` translates its own default, and accepting either shape
+   * for the same reason: a sentence stores `{ text, label, kind, url, newTab }` and renders
+   * `{ text, href, label }`, and `storedLink`/`valueFromStored` are the one pair that knows
+   * how those two correspond. `text` rides through both.
+   */
+  const alreadyStored = raw !== undefined && isStoredLinkValue(raw)
+  const stored =
+    raw === undefined ? undefined : alreadyStored ? raw : storedLink(raw as SentenceValue)
+  const committed =
+    raw === undefined ? undefined : alreadyStored ? valueFromStored(raw) : (raw as SentenceValue)
+
+  return {
+    element: 'sentence' as const,
+    ...group({
+      ...options,
+      ...(stored === undefined ? {} : { default: stored }),
+      ...(committed === undefined ? {} : { value: committed }),
+      fields: {
+        /*
+         * `textarea`, not `text`: a sentence wraps, and a client editing one wants to see all
+         * of it. It is declared first so the inspector's panel reads in the order the client
+         * thinks in — the words, then which words are the link, then where it goes.
+         */
+        text: textarea({
+          description: `The line of copy. Put ${SENTENCE_LINK} where the link should fall.`,
+        }),
+        ...linkFields({ pageCollection, withLabel: true }),
+      },
+    }),
+    /*
+     * The same marker a button carries, because `seedItem` has the same job to do with a
+     * sentence inside an array item: translate the committed shape into the stored one. A
+     * sentence is a `group`, so without this it would take `seedItem`'s group branch, which
+     * copies only the keys the schema declares — `href` is not one of them, and the link
+     * would be seeded with no address at all.
+     */
+    [LINK_FIELD_MARKER]: true,
+  } as Unnamed<never>
+}
+
+export type FieldSpec = Record<string, AnyField>
+
+/**
+ * The tag that tells `defineSite` this entry is a layout.
+ *
+ * A symbol for the same reason `BLOCK_ENTRY` is one: a site spec is a flat object of the
+ * author's own keys, and a carrier has to be recognisable without reserving a key name that
+ * a site might legitimately want for something else.
+ */
+export const LAYOUT = Symbol('u90.layout')
+
+/** The reserved blockType marking where a page's own sections go. See `defineSite`. */
+export const SLOT_BLOCK = '_slot'
+
+/**
+ * The one entry of a layout that is not a block: the hole the page renders into.
+ *
+ * A frozen literal rather than a factory, because there is nothing to configure and two
+ * calls must be indistinguishable — the one-slot rule below counts them.
+ */
+export const SLOT = Object.freeze({ blockType: SLOT_BLOCK }) as { blockType: string }
+
+export type LayoutMeta = { default?: boolean; label: string }
+
+export type LayoutEntry = {
+  [LAYOUT]: true
+  entries: (Record<string, unknown> & { blockType: string })[]
+  meta: LayoutMeta
+}
+
+/**
+ * A named arrangement of blocks with one hole in it.
+ *
+ * The entries are the same shape a page's sections are and a block's seed is — one object
+ * per entry, keyed by `blockType` — so the manifest validator, the media walker and the
+ * seed-upload relinker all work on them unchanged. That reuse is the whole reason a layout
+ * is expressible at all without a second content pipeline.
+ *
+ * No slug: the declaration key names it, and that name is what re-seeding is keyed on.
+ */
+export const layout = (
+  meta: LayoutMeta,
+  entries: (Record<string, unknown> & { blockType: string })[],
+): LayoutEntry => ({ [LAYOUT]: true, entries, meta })
+
+/**
+ * The tag that tells `defineSite` this entry declares Singles.
+ *
+ * A symbol beside `LAYOUT`, for the reason that one is a symbol: a site spec is a flat
+ * object of the author's own keys, and a carrier has to be recognisable without reserving a
+ * key name a site might legitimately want.
+ */
+export const SINGLES = Symbol('u90.singles')
+
+/** What a site writes for one entry of `singles()`: the type, the client's name for it, and
+ * the value the site ships with. The key comes from the map. */
+export type SingleSpec = { label: string; type: 'link' | 'text'; value: string }
+
+export type SinglesEntry = {
+  [SINGLES]: true
+  declared: Record<string, SingleSpec>
+}
+
+/**
+ * The shared values this site starts with, keyed by the identifier blocks point at.
+ *
+ * A Single is one named scalar the client keeps once — a phone number, an ABN — and every
+ * block that prints it declares `reference('phone')` and reads it as an ordinary text field.
+ * A site could already *point at* one and had no way to *declare* one, so a freshly paired
+ * client opened the Singles tab to nothing: the site rendered its committed fallbacks
+ * perfectly and the values behind them were undiscoverable and uneditable, which is a worse
+ * state than a visible mistake because nothing signals it.
+ *
+ * **This is not `business()` returning.** That was a category the platform invented, with a
+ * fixed identity — a logo, a phone, an ABN, socials — so it only ever fitted the sites it
+ * had been written for, and the platform had opinions about what each field meant. This says
+ * only "the shared values this site starts with". The keys are the site's, the labels are
+ * the client's, and what is seeded becomes rows the client wholly owns: theirs to edit,
+ * rename, empty or delete, with no second opinion from here afterwards.
+ *
+ * **The declared value seeds the row; it does not replace the component's fallback.** A
+ * component still renders `text(content.phone, COMMITTED.phone)`, because a site has to draw
+ * itself when the platform is unreachable. Both read the same constant, so there is still one
+ * literal per fact:
+ *
+ *     singles({ phone: { label: 'Phone', type: 'text', value: COMMITTED.phone } })
+ *     text(content.phone, COMMITTED.phone)
+ *
+ * No slug and no meta: the map keys name the values, and that name is what re-seeding is
+ * keyed on — the same bargain `layout()` strikes with its declaration key.
+ */
+export const singles = (declared: Record<string, SingleSpec>): SinglesEntry => ({
+  [SINGLES]: true,
+  declared,
+})
+
+export type BlockSpec = Record<
+  string,
+  { fields: FieldSpec; label?: string; layoutOnly?: boolean; renders?: string[] }
+>
+
+/**
+ * Attach each field's name from its key, fill in any missing label, and drop `default`.
+ *
+ * This is the boundary: everything from here on is schema, published to the platform
+ * and rendered into a client's editor. A default is seed data and stops here.
+ *
+ * `LINK_FIELD_MARKER` is the one thing that rides through, and only because it is a symbol:
+ * the rest spread copies it, `JSON.stringify` drops it, and `seedItem` needs it to recognise
+ * a link nested inside a group. See the marker's own note.
+ */
+export const namedFields = (spec: FieldSpec): EditorField[] =>
+  Object.entries(spec).map(([name, field]) => {
+    const {
+      default: _seed,
+      value: _committed,
+      ...schema
+    } = field as Unnamed & {
+      default?: unknown
+      value?: unknown
+    }
+    return {
+      ...schema,
+      label: field.label || humanise(name),
+      name,
+    }
+  }) as EditorField[]
+
+/**
+ * A nested `fields` value, reduced to the `FieldSpec` shape a recursive walk needs.
+ *
+ * A top-level entry's `fields` is the author-written map — untouched, keyed by name. A
+ * `group()` or `array()` field's own `fields` is not: those helpers call `namedFields` on
+ * their children synchronously, at construction time, before any walk begins — so by the time
+ * `seedItem` or `defineSite`'s `validate` reaches them they have already become an
+ * `EditorField[]`, each element carrying its name as a `.name` property rather than as an
+ * object key. Walking that array with `Object.entries` would read the array's *indices*
+ * ("0", "1", …) as if they were field names, which rejects every nested group and array a
+ * site declares and prunes every nested value out of the seed. Rebuilding the map from each
+ * element's own `.name` is what lets one recursive walk pass through either shape.
+ */
+export const namedFieldSpec = (fields: unknown): FieldSpec =>
+  Array.isArray(fields)
+    ? (Object.fromEntries(
+        (fields as { name: string }[]).map((field) => [field.name, field]),
+      ) as unknown as FieldSpec)
+    : (fields as FieldSpec)
+
+export const defineBlocks = (spec: BlockSpec): EditorBlock[] =>
+  Object.entries(spec).map(([slug, block]) => ({
+    fields: namedFields(block.fields),
+    label: block.label ?? humanise(slug),
+    ...(block.layoutOnly === undefined ? {} : { layoutOnly: block.layoutOnly }),
+    ...(block.renders === undefined ? {} : { renders: block.renders }),
+    slug,
+  }))
+
+/**
+ * What a fresh instance of each block contains, keyed by slug. See `SiteManifest.starters`.
+ *
+ * Reads both carriers, and it has to. `default` is defined as what the platform stores, so it
+ * is preferred; but a site may say the same thing positionally — `text('Building WA.')` sets
+ * `value`, what the component renders — and a client adding that block should get those words
+ * rather than an empty box. `seedFrom` reads only `default` because a *seed* is written once
+ * at pair time against content the site already serves; a starter has no such history.
+ *
+ * Blocks contributing nothing are omitted rather than published empty, so the dashboard can
+ * tell "arrives ready to edit" from "arrives blank" and say so before the client commits.
+ *
+ * **`allBlocks` is why this takes a second argument `array()` and `group()` never needed.**
+ * Every other field helper translates its own `default`/`value` into the stored button shape
+ * the moment the site calls it — `link()` does this itself, and `array()` does it by calling
+ * `seedItem` on each item during its own construction. `blocksField` cannot: a zone named by
+ * slug (`of: [...]`) only says which block its children *may* be, not what that block's fields
+ * are, and the block it names may not even have been declared yet in the site's own module —
+ * see `navItem` in PBIR's `site.ts`, which names itself. The block library only exists whole
+ * once `defineSite` finishes collecting every entry, which is this function's caller and the
+ * one place that can resolve a slug zone's own committed children. A `blocks`-typed field's
+ * chosen value is therefore routed through `seedZone` here, on the way into the starter — the
+ * one translation `array`'s own construction-time pass could never have done for it.
+ */
+export const startersFrom = (
+  spec: BlockSpec,
+  allBlocks: EditorBlock[],
+): Record<string, Record<string, unknown>> => {
+  const out: Record<string, Record<string, unknown>> = {}
+
+  for (const [slug, block] of Object.entries(spec)) {
+    const fields = namedFieldSpec(block.fields)
+    const starter: Record<string, unknown> = {}
+
+    for (const [name, field] of Object.entries(fields)) {
+      const descriptor = field as unknown as EditorField
+      const carrier = field as { default?: unknown; value?: unknown }
+      const chosen = carrier.default !== undefined ? carrier.default : carrier.value
+      if (chosen === undefined) continue
+      starter[name] =
+        descriptor.type === 'blocks' && Array.isArray(chosen)
+          ? seedZone(descriptor, chosen, allBlocks)
+          : chosen
+    }
+
+    /*
+     * A zone block states its own slug and a keyed one takes the document key. Read through
+     * an optional so both forms land under the slug stored content actually names.
+     */
+    const key = (block as { slug?: string }).slug ?? slug
+    if (Object.keys(starter).length > 0) out[key] = starter
+  }
+
+  return out
+}
+
+export type CollectionSpec = Record<
+  string,
+  {
+    /** Where these rows render on the site. See `CollectionRoutes`. */
+    appearsOn?: CollectionRoutes
+    description?: string
+    detailField?: string
+    fields: FieldSpec
+    itemNoun?: string
+    label?: string
+    /** One object per committed row, in the order the site renders them. */
+    seed?: Record<string, unknown>[]
+    titleField: string
+  }
+>
+
+/**
+ * How a site declares its repeatable record types.
+ *
+ *   export const collections = defineCollections({
+ *     projects: {
+ *       titleField: 'name',
+ *       detailField: 'sector',
+ *       fields: { name: text(), sector: text(), photo: upload() },
+ *       seed: brand.projects.map(({ name, sector }) => ({ name, sector })),
+ *     },
+ *   })
+ *
+ * Keyed by object for the same reason blocks are: the key *is* the slug, so two
+ * collections cannot collide, and a collision here would make stored rows ambiguous
+ * about which record type they belong to.
+ *
+ * Unlike a block, the seed is written as whole rows rather than collected from
+ * per-field `default`s — a collection's seed is a *list*, and there is no sensible
+ * way to spell "six rows" as a default on each field.
+ *
+ * **A row is pruned exactly as an array item is**, through the same `seedItem`: undeclared
+ * keys dropped, marked links translated, uploads carried through as their committed path, at
+ * every depth `seedItem` can resolve. The rule is the field's type, never the container it
+ * sits in — a row and an item are the same problem one level apart. Left unpruned, a committed
+ * `{ href }` reached the platform as a button with no address; jdsi's migration hit that and
+ * it is what this exists to stop. A zone nested inside a row and named by slug does not
+ * resolve here — see the note on the `seedItem` call below and on `seedItem` itself.
+ */
+export const defineCollections = (spec: CollectionSpec): ManifestCollection[] =>
+  Object.entries(spec).map(([slug, entry]) => ({
+    ...(entry.appearsOn === undefined ? {} : { appearsOn: entry.appearsOn }),
+    ...(entry.description === undefined ? {} : { description: entry.description }),
+    ...(entry.detailField === undefined ? {} : { detailField: entry.detailField }),
+    ...(entry.itemNoun === undefined ? {} : { itemNoun: entry.itemNoun }),
+    /*
+     * `allBlocks: []` for the same reason `array()`'s own default carries it: a collection's
+     * rows are pruned while the site's module is still being evaluated, and `defineCollections`
+     * is a public export a site may call standalone, without ever going through `defineSite` at
+     * all — there is no site-wide block list to hand it even when one exists. A zone nested
+     * inside a row and named by slug (`of: [...]`) does not resolve here; see `seedItem`.
+     */
+    ...(entry.seed === undefined
+      ? {}
+      : { seed: entry.seed.map((row) => seedItem(entry.fields, row, [])) }),
+    fields: namedFields(entry.fields),
+    label: entry.label ?? humanise(slug),
+    slug,
+    titleField: entry.titleField,
+  }))
+
+/**
+ * Build the manifest this site publishes.
+ *
+ * `generatedAt` is stamped at call time rather than at build time, so an operator
+ * looking at a stale schema in the dashboard sees when the *running* site last
+ * reported it, not when the bundle was compiled.
+ */
+export const createManifest = ({
+  blocks,
+  collections,
+  newPage,
+  pages = [],
+  routesAllPages,
+  seed,
+}: {
+  blocks: EditorBlock[]
+  /** Repeatable record types, from `defineCollections`. Their seeds ride along. */
+  collections?: ManifestCollection[]
+  /**
+   * The sections a client-added page starts with. See `SiteManifest.newPage`.
+   *
+   * A literal `SeedSection[]`, **not** a `BlockSpec` like `seed` — there is no `seedFrom`
+   * pass over it. `seedFrom` emits one section per declared block in spec order, which is a
+   * layout for one particular page (the home page) and wrong for every other. A starting
+   * stack is a deliberate short list, so the site writes it out.
+   */
+  newPage?: SeedSection[]
+  pages?: PageDeclaration[]
+  /** True when a catch-all route serves every stored slug. See `SiteManifest.routesAllPages`. */
+  routesAllPages?: boolean
+  /**
+   * Seed content. Pass the same spec you gave `defineBlocks` and the defaults are
+   * collected automatically; pass nothing and no seed is published.
+   */
+  seed?: BlockSpec
+}): SiteManifest => ({
+  blocks,
+  bridgeVersion: BRIDGE_VERSION,
+  ...(collections ? { collections } : {}),
+  generatedAt: new Date().toISOString(),
+  ...(newPage ? { newPage } : {}),
+  pages,
+  ...(routesAllPages ? { routesAllPages } : {}),
+  ...(seed ? { seed: seedFrom(seed) } : {}),
+  /*
+   * Derived from `seed`, which is the only spec this form receives — `blocks` arrives
+   * already published as schema, with the carriers stripped. That is the honest limit of the
+   * legacy shape: a caller who passes the spec gets starters, one who passes only published
+   * blocks does not, and `defineSite` (which holds the real spec) has no such gap.
+   */
+  ...(() => {
+    if (!seed) return {}
+    const starters = startersFrom(seed, blocks)
+    return Object.keys(starters).length > 0 ? { starters } : {}
+  })(),
+})
+
+/**
+ * Collect every `default` in a block spec into one seed section per block.
+ *
+ * Blocks are emitted in spec order, which is the order the page renders them — the
+ * platform indexes sections by position, so a seed in the wrong order would address
+ * every field to the wrong section.
+ *
+ * A block whose fields have no defaults still gets a section. That is deliberate: the
+ * section's *presence* is what gives the site's bridge a `fieldBase` to hang editable
+ * markers on, and without it that block is invisible to the editor even though its
+ * schema is known.
+ *
+ * Exported for `defineSite`, which seeds the blocks it was told to seed and needs the
+ * *same* function rather than a copy of it: the two forms of the same site are asserted to
+ * publish identical output, so a second implementation drifting from this one would break
+ * that identity silently. `BlockSpec` is the wider shape — a label it never reads costs it
+ * nothing — so one signature serves both callers.
+ */
+export const seedFrom = (spec: BlockSpec): SeedSection[] =>
+  Object.entries(spec).map(([slug, block]) => ({
+    blockType: slug,
+    ...seedFields(block.fields),
+  }))
+
+/** The seed default of every field in a block, keyed by field name. See `seedFrom`. */
+const seedFields = (spec: FieldSpec): Record<string, unknown> => {
+  const out: Record<string, unknown> = {}
+  for (const [name, field] of Object.entries(spec)) {
+    const value = (field as { default?: unknown }).default
+    if (value !== undefined) out[name] = value
+  }
+  return out
+}