@unitninety/site-kit 0.0.0-stage → 1.6.2

package/src/legacy/defineSite.ts

@@ -0,0 +1,623 @@
+import {
+  defineBlocks,
+  startersFrom,
+  defineCollections,
+  LAYOUT,
+  namedFieldSpec,
+  seedFrom,
+  SINGLES,
+  SLOT_BLOCK,
+  type CollectionSpec,
+  type FieldSpec,
+  type LayoutEntry,
+  type SinglesEntry,
+} from './defineBlocks'
+import { BLOCK_ENTRY, BRIDGE_VERSION } from './contract'
+import type {
+  BlockEntry,
+  CollectionRoutes,
+  EditorBlock,
+  FormDeclaration,
+  FormFieldDeclaration,
+  LayoutDeclaration,
+  ManifestCollection,
+  PageDeclaration,
+  SeedSection,
+  SingleDeclaration,
+  SiteManifest,
+  Spec,
+  SpecKey,
+} from './contract'
+
+/**
+ * How a site states its content once.
+ *
+ * `brand.ts` holds what the site says; `blocks.ts` used to hold how a client may change it;
+ * a hand-written `Brand` type held the shape a third time. This collapses the three into one
+ * document, on one rule:
+ *
+ *   **A wrapped entry is modelled. A bare entry is committed and never modelled.**
+ *
+ *   By default every homepage section is a `block()`, and a repeating record the
+ *   page names (people, projects, stories) is a `collection()` plus a
+ *   `relationship` on the block that renders it (`renders: ['people']`). Header,
+ *   nav and footer stay bare chrome.
+ *
+ *   export const site = defineSite({
+ *     hero: block({ headline: text('Building Western Australia.') }),
+ *     logo: { src: '/brand/logo-mark.png', ratio: 241 / 105 },
+ *   })
+ *
+ *   export const brand = site.values      // every component imports this, unchanged
+ *
+ * `brand.ts`'s values are **not** seed. Components render `text(cms, committed)` — CMS over
+ * committed — and the contract guarantees that an unreachable platform renders the site
+ * exactly as it does with no CMS at all. The values stay compiled into the bundle forever.
+ * The database is the truth for edits; this is the floor underneath them.
+ */
+
+/** `Symbol.for`, so two instances of this package agree on it. See `BLOCK_ENTRY`. */
+const COLLECTION: unique symbol = Symbol.for('u90.collection')
+
+/*
+ * `BLOCK_ENTRY` and `BlockEntry` live in `contract.ts` rather than here, because
+ * `blocksField()` has to recognise a `block()` — a zone's blocks are written with it and held
+ * in a plain const — and `defineBlocks.ts` importing this module would make the two circular.
+ * Re-exported so a site still reads the type from where it reads `block()`.
+ */
+export type { BlockEntry } from './contract'
+
+export type CollectionOptions<R extends Record<string, unknown>[] = Record<string, unknown>[]> = {
+  appearsOn?: CollectionRoutes
+  description?: string
+  detailField?: string
+  itemNoun?: string
+  label?: string
+  /** One object per committed row, in the order the site renders them. */
+  rows?: R
+  /**
+   * Stored slug, when it must differ from the document key. Mirrors `block()`'s override and
+   * exists for the same reason, one level along.
+   *
+   * A collection's rows and a site's *committed* array of the same records are routinely not
+   * the same shape: jdsi's `brand.projects` carries the photograph and the href its
+   * components render, while the `projects` collection's rows carry the write-up, the
+   * standfirst and the page slug. Neither derives from the other, both must exist, and only
+   * one can own the document key. **A slug keys stored rows, so it is permanent** — move the
+   * key and pin the slug.
+   */
+  slug?: string
+  titleField: string
+}
+
+export type CollectionEntry<
+  F extends FieldSpec = FieldSpec,
+  R extends Record<string, unknown>[] = Record<string, unknown>[],
+> = CollectionOptions<R> & {
+  [COLLECTION]: true
+  fields: F
+}
+
+/**
+ * A section of a page.
+ *
+ * Declaration order is the home page's section order: the platform indexes stored sections
+ * by position, so the order these are written in is the order `page.tsx` renders them.
+ *
+ * `{ seed: false }` publishes the block without putting it on the home page — `pageHeader`
+ * and `pageBody` are available to every page and seeded onto none. That is also what makes
+ * them usable as `newPage`: a block absent from the home seed is what a *new* page starts as.
+ *
+ * `{ layoutOnly: true }` keeps the block out of the page picker too, which `seed: false`
+ * alone does not — a client could still add a chrome block, like a header, as an ordinary
+ * page section and end up with two. See `EditorBlock.layoutOnly`.
+ *
+ * `{ slug }` overrides the stored slug when it must differ from the document key. Two
+ * entries cannot share a key in one object, but a site may legitimately have a *block* and a
+ * *collection* of the same name — jdsi's home page has an empty `projects` section and a
+ * `projects` collection of records. **A slug keys stored content, so it is permanent**; the
+ * key is only how the brand document addresses the entry. When they must diverge, move the
+ * key and pin the slug.
+ */
+export const block = <F extends FieldSpec>(
+  fields: F,
+  options: {
+    label?: string
+    layoutOnly?: boolean
+    renders?: string[]
+    seed?: boolean
+    slug?: string
+  } = {},
+): BlockEntry<F> => ({
+  [BLOCK_ENTRY]: true,
+  fields,
+  ...(options.label === undefined ? {} : { label: options.label }),
+  ...(options.layoutOnly === undefined ? {} : { layoutOnly: options.layoutOnly }),
+  ...(options.renders === undefined ? {} : { renders: options.renders }),
+  seed: options.seed ?? true,
+  ...(options.slug === undefined ? {} : { slug: options.slug }),
+})
+
+/**
+ * A repeatable record type — projects, team, sectors.
+ *
+ * Rows are a list, so they attach here rather than to any one field; there is no sensible
+ * way to spell "six rows" as a value on each field. Rows are frequently derived from data a
+ * block also uses, which inside one `defineSite` call would be circular — hoist the shared
+ * array to a const above the call and read it from both places.
+ */
+export const collection = <
+  F extends FieldSpec,
+  R extends Record<string, unknown>[] = Record<string, unknown>[],
+>(
+  fields: F,
+  options: CollectionOptions<R>,
+): CollectionEntry<F, R> => ({
+  [COLLECTION]: true,
+  fields,
+  ...options,
+})
+
+export type FormEntry = {
+  __kind: 'form'
+  fields: FormFieldDeclaration[]
+  label: string
+  recipients?: string[]
+  slug?: string
+}
+
+/**
+ * A form this site collects — a contact form, a careers application.
+ *
+ * Unlike `block()` and `collection()`, a form commits no copy to `site.values`: there is
+ * nothing for a component to render, only a field schema the platform validates submissions
+ * against and a mailing list it seeds once. Marked with a plain `__kind` rather than a
+ * shared symbol like `BLOCK_ENTRY` — nothing outside this module ever needs to recognise a
+ * `form()` entry the way `blocksField()` needs to recognise a `block()` inside a zone, so
+ * there is no circular-import reason to hoist the tag into `contract.ts`.
+ */
+export const form = (declaration: {
+  fields: FormFieldDeclaration[]
+  label: string
+  recipients?: string[]
+  slug?: string
+}): FormEntry => ({ ...declaration, __kind: 'form' as const })
+
+export type SiteSpec = Record<string, unknown>
+
+/**
+ * The committed value of one entry — what it contributes to `site.values`.
+ *
+ * A block resolves to an object of its fields' values. A collection resolves to its rows,
+ * and to `[]` when it has none, matching `values[key] = rows ?? []` below. A field helper
+ * resolves to the value it carries. Anything else — a bare entry — is carried through
+ * exactly as written, which is what makes `mark.ratio` a `number` rather than something the
+ * CMS has an opinion about.
+ *
+ * That a carrier keeps its field map is not decoration: this recovers a carrier's committed
+ * shape by inferring the parameter, so a carrier that had thrown its map away would resolve
+ * `site.values.hero` to the carrier itself. A site reading one of its own fields would then
+ * get `TS2339` on the field and a clean typecheck on `.fields`, which is `undefined` at
+ * runtime — the wrong half of the pair being the one that compiles.
+ *
+ * A layout resolves to `never`, and so does a form, for the same reason: the loop in
+ * `defineSite` diverts a layout entry into `layouts` and a form entry into `forms`, and
+ * never writes `values[key]` for either, so there is no committed value to name a type for.
+ * `never` alone does not make `site.values.standard` a compile error — TypeScript happily reads
+ * a property typed `never` — so `SiteValues` below drops the key entirely rather than leaning
+ * on this branch to do that work.
+ *
+ * **It reads carriers, never nested `fields`.** A block's own `fields` is still the map the
+ * author wrote, so that one is walked. A `group()`'s or `array()`'s is not: both call
+ * `namedFields` on their children at construction time, so what survives on the descriptor
+ * is an `EditorField[]` — no carriers, and the author's key names demoted to a `name`
+ * property. Those helpers state the type they commit on the way out, and this reads it from
+ * there. Recursing into a nested `fields` would infer the shape of the editor's schema
+ * instead of the shape of the site's content.
+ */
+export type Value<S> =
+  S extends BlockEntry<infer F>
+    ? { [K in keyof F]: Value<F[K]> }
+    : S extends CollectionEntry<FieldSpec, infer R>
+      ? R
+      : S extends LayoutEntry | SinglesEntry | FormEntry
+        ? never
+        : SpecKey extends keyof S
+          ? S extends Spec<infer V>
+            ? V
+            : never
+          : S
+
+/**
+ * Every entry of a site spec, resolved to its committed value. See `Value`.
+ *
+ * The `as` clause drops a layout or form key rather than leaving it mapped to `Value`'s
+ * `never`: a property typed `never` still typechecks to read (`{ x: never }`'s `x` is legal
+ * to access, just impossible to produce), so keeping the key would leave `site.values.careers`
+ * compiling clean and then reading `undefined` at runtime — the exact failure `Value`'s
+ * carrier branches exist to avoid, reintroduced for a form key. Removing the key instead
+ * makes that access `TS2339: Property does not exist`, which is what `defineSite`'s loop
+ * actually does: a form entry is diverted into `forms` and `values[key]` is never written.
+ */
+export type SiteValues<S> = {
+  [K in keyof S as S[K] extends LayoutEntry | SinglesEntry | FormEntry ? never : K]: Value<S[K]>
+}
+
+export type Site<V = Record<string, unknown>> = {
+  blocks: EditorBlock[]
+  collections: ManifestCollection[]
+  /** Forms this site collects. Absent on a site that declares none. */
+  forms?: FormDeclaration[]
+  /** Named arrangements of blocks with one content slot. Absent on a site that declares none. */
+  layouts?: LayoutDeclaration[]
+  seed: SeedSection[]
+  /** The shared values this site starts with. Absent on a site that declares none. */
+  singles?: SingleDeclaration[]
+  /** What one fresh instance of each block contains. See `SiteManifest.starters`. */
+  starters: Record<string, Record<string, unknown>>
+  values: V
+}
+
+/*
+ * `LayoutDeclaration` lives in `contract.ts` rather than here, for the same reason
+ * `BlockEntry` does: it belongs to `SiteManifest`, the platform's own half of the contract,
+ * not just to `Site`. Re-exported so a site still reads the type from where it reads
+ * `layout()`.
+ */
+export type {
+  FormDeclaration,
+  FormFieldDeclaration,
+  LayoutDeclaration,
+  SingleDeclaration,
+} from './contract'
+
+/** `FieldSpec` restated, because `contract.ts` cannot name it. See `BlockEntry`. */
+const isBlock = (entry: unknown): entry is BlockEntry<FieldSpec> =>
+  entry !== null && typeof entry === 'object' && BLOCK_ENTRY in entry
+
+const isCollection = (entry: unknown): entry is CollectionEntry =>
+  entry !== null && typeof entry === 'object' && COLLECTION in entry
+
+const isForm = (entry: unknown): entry is FormEntry =>
+  entry !== null && typeof entry === 'object' && (entry as { __kind?: unknown }).__kind === 'form'
+
+export const isLayout = (entry: unknown): entry is LayoutEntry =>
+  entry !== null && typeof entry === 'object' && LAYOUT in entry
+
+export const isSingles = (entry: unknown): entry is SinglesEntry =>
+  entry !== null && typeof entry === 'object' && SINGLES in entry
+
+/** The two a Single may be. Restated here rather than imported for the reason
+ * `dashboard/singles/store.ts` restates it: this polices what a *site* declares. */
+const SINGLE_TYPES = ['link', 'text']
+
+const IDENTIFIER = /^[A-Za-z][A-Za-z0-9_]*$/
+
+/**
+ * Refuse to build rather than serve a manifest the platform will reject.
+ *
+ * A site that fails to build is recoverable in minutes. A site that builds and serves a
+ * manifest the platform rejects shows the client an empty editor, which they read as "my
+ * content has vanished" — the failure the platform's own schema notes single out as the one
+ * worth any amount of noise to avoid.
+ *
+ * Every rule here is re-checked by `src/manifest/validate.ts` on the platform. This is not
+ * a substitute for that; it moves the same failure from a client's screen to a build log.
+ */
+const validate = (spec: SiteSpec, collections: CollectionSpec): void => {
+  const declared = new Set(Object.keys(collections))
+
+  const walkFields = (fields: FieldSpec, where: string): void => {
+    for (const [name, field] of Object.entries(fields)) {
+      if (!IDENTIFIER.test(name)) {
+        throw new Error(
+          `${where}: field name "${name}" is not an identifier. A name becomes part of a dotted path (\`0.slides.1.title\`), so a name containing a "." addresses a different field than it claims to.`,
+        )
+      }
+      const nested = (field as { fields?: unknown }).fields
+      const relationTo = (field as { relationTo?: string }).relationTo
+      if (
+        relationTo !== undefined &&
+        relationTo !== 'pages' &&
+        relationTo !== 'media' &&
+        !declared.has(relationTo)
+      ) {
+        throw new Error(
+          `${where}.${name}: relationTo "${relationTo}" names no collection this site declares. Declare it with collection(), or the platform rejects the whole manifest rather than render a picker with nothing in it.`,
+        )
+      }
+      if (nested !== undefined) walkFields(namedFieldSpec(nested), `${where}.${name}`)
+    }
+  }
+
+  for (const [key, entry] of Object.entries(spec)) {
+    if (isBlock(entry)) walkFields(entry.fields, key)
+    if (isCollection(entry)) {
+      walkFields(entry.fields, key)
+      if (!(entry.titleField in entry.fields)) {
+        throw new Error(
+          `${key}: titleField "${entry.titleField}" names no field on this collection. The CMS list would render a blank first column and no row would be nameable.`,
+        )
+      }
+    }
+  }
+
+  for (const [key, entry] of Object.entries(spec)) {
+    if (!isBlock(entry)) continue
+
+    for (const slug of entry.renders ?? []) {
+      if (!declared.has(slug)) {
+        throw new Error(
+          `${key}: renders "${slug}", which names no collection this site declares. The rail would show nothing under this block, which reads to a client as their content having gone.`,
+        )
+      }
+    }
+  }
+}
+
+export const defineSite = <S extends SiteSpec>(spec: S): Site<SiteValues<S>> => {
+  const blockSpec: Record<
+    string,
+    { fields: FieldSpec; label?: string; layoutOnly?: boolean; renders?: string[] }
+  > = {}
+  const seedSpec: Record<
+    string,
+    { fields: FieldSpec; label?: string; layoutOnly?: boolean; renders?: string[] }
+  > = {}
+  const collectionSpec: CollectionSpec = {}
+  const forms: FormDeclaration[] = []
+  const values: Record<string, unknown> = {}
+  const layouts: LayoutDeclaration[] = []
+  const singles: SingleDeclaration[] = []
+  const singleKeys = new Set<string>()
+
+  for (const [key, entry] of Object.entries(spec)) {
+    if (isBlock(entry)) {
+      const declared = {
+        fields: entry.fields,
+        ...(entry.label === undefined ? {} : { label: entry.label }),
+        ...(entry.layoutOnly === undefined ? {} : { layoutOnly: entry.layoutOnly }),
+        ...(entry.renders === undefined ? {} : { renders: entry.renders }),
+      }
+      // The slug keys stored content; the document key is only how `brand` addresses it.
+      const slug = entry.slug ?? key
+      if (slug in blockSpec) {
+        throw new Error(
+          `Two blocks resolve to the slug "${slug}". A slug keys stored content, so two sections sharing one would be unresolvable.`,
+        )
+      }
+      blockSpec[slug] = declared
+      if (entry.seed) seedSpec[slug] = declared
+      values[key] = blockValues(entry.fields)
+      continue
+    }
+
+    if (isCollection(entry)) {
+      const { fields, rows, slug: override, ...rest } = entry
+      // The slug keys stored rows; the document key is only how `brand` addresses them.
+      const slug = override ?? key
+      if (slug in collectionSpec) {
+        throw new Error(
+          `Two collections resolve to the slug "${slug}". A slug keys stored rows, so two record types sharing one would be unresolvable.`,
+        )
+      }
+      collectionSpec[slug] = {
+        ...rest,
+        fields,
+        ...(rows === undefined ? {} : { seed: rows }),
+      }
+      values[key] = rows ?? []
+      continue
+    }
+
+    if (isForm(entry)) {
+      const { fields, label, recipients, slug: override } = entry
+      // The slug keys stored submissions; the document key is only how `brand` addresses it.
+      const slug = override ?? key
+      // Match the platform manifest identifier grammar before it could discard a declaration.
+      const identifier = /^[a-zA-Z][a-zA-Z0-9_]*$/
+      if (typeof slug !== 'string' || !identifier.test(slug)) {
+        throw new Error(
+          `Invalid form slug "${slug}" for "${key}". Use a letter followed by letters, digits or underscores.`,
+        )
+      }
+      for (const field of fields) {
+        if (typeof field.name !== 'string' || !identifier.test(field.name)) {
+          throw new Error(
+            `Invalid field name "${field.name}" in form "${slug}". Use a letter followed by letters, digits or underscores.`,
+          )
+        }
+      }
+      if (forms.some((declared) => declared.slug === slug)) {
+        throw new Error(
+          `Two forms resolve to the slug "${slug}". A slug keys stored submissions, so two forms sharing one would be unresolvable.`,
+        )
+      }
+      forms.push({ fields, label, slug, ...(recipients === undefined ? {} : { recipients }) })
+      continue
+    }
+
+    if (isLayout(entry)) {
+      const slots = entry.entries.filter((item) => item.blockType === SLOT_BLOCK).length
+      if (slots === 0) {
+        throw new Error(
+          `Layout "${key}" has no content slot. Put SLOT where the page's own sections go — without one the layout renders the chrome and none of the page, which is silent at runtime.`,
+        )
+      }
+      if (slots > 1) {
+        throw new Error(
+          `Layout "${key}" has two content slots. A page's sections are one list, so there is no answer to which slot they go in until multi-slot exists.`,
+        )
+      }
+      layouts.push({ ...entry.meta, entries: entry.entries, name: key })
+      continue
+    }
+
+    if (isSingles(entry)) {
+      /*
+       * Refused at build time rather than left for the platform, for the reason `validate`
+       * below gives: a site that fails to build is recoverable in minutes, and a site that
+       * builds and publishes a declaration the platform drops leaves a client with a value
+       * they cannot see and no line anywhere saying so. Each of these mirrors a rule
+       * `dashboard/singles/store.ts` enforces on a key a client types, because a seeded row
+       * and a typed one are the same row.
+       */
+      for (const [key, spec] of Object.entries(entry.declared)) {
+        if (!IDENTIFIER.test(key)) {
+          throw new Error(
+            `singles: "${key}" is not a name a block can point at. A key is what a reference() names, so it starts with a letter and holds only letters, numbers and underscores.`,
+          )
+        }
+        if (singleKeys.has(key)) {
+          throw new Error(
+            `Two declarations resolve to the single "${key}". Two rows answering one key would leave it undecided which one a block is showing, and the client editing one would be shown the other.`,
+          )
+        }
+        if (!SINGLE_TYPES.includes((spec as { type?: string } | undefined)?.type ?? '')) {
+          throw new Error(
+            `singles.${key}: type "${(spec as { type?: string } | undefined)?.type}" is neither "text" nor "link". An image is not a Single — it lives in the media library, pointed at by an upload field on the block that draws it.`,
+          )
+        }
+        if (typeof spec.label !== 'string' || spec.label.trim() === '') {
+          throw new Error(
+            `singles.${key}: no label. The label is what the client recognises this value by in a list of them, and a row without one is unnameable.`,
+          )
+        }
+        singleKeys.add(key)
+        singles.push({
+          key,
+          label: spec.label.trim(),
+          type: spec.type,
+          value: typeof spec.value === 'string' ? spec.value : '',
+        })
+      }
+      continue
+    }
+
+    values[key] = entry
+  }
+
+  validate(spec, collectionSpec)
+
+  /*
+   * Computed once, ahead of the return, because `startersFrom` needs the same full block
+   * library `blocks` below publishes — a slug zone (`of: [...]`) only names which block its
+   * children may be, and resolving that name to the block's own fields needs every block this
+   * site declared, not just the one the zone sits on. `blockSpec` alone is not enough for
+   * that: it is this function's own author-facing map, still keyed by field maps rather than
+   * the published `EditorField[]` shape `seedZone` walks.
+   */
+  const allBlocks = defineBlocks(blockSpec)
+
+  return {
+    blocks: allBlocks,
+    collections: defineCollections(collectionSpec),
+    ...(forms.length === 0 ? {} : { forms }),
+    ...(layouts.length === 0 ? {} : { layouts }),
+    // `defineBlocks`'s own seed collector, not a copy of it: it emits one section per block
+    // in spec order, which is what `seedSpec`'s insertion order carries, and the two ways of
+    // writing one site are asserted to seed identically. Two implementations of that could
+    // only drift.
+    seed: seedFrom(seedSpec),
+    ...(singles.length === 0 ? {} : { singles }),
+    /*
+     * `blockSpec`, not `seedSpec`: a starter belongs to every block a client can add, and
+     * `seedSpec` holds only the ones that seed — `block({…}, { seed: false })` is excluded
+     * there and must not be excluded here. `allBlocks` alongside it is what lets a zone
+     * field's own committed children (a slug-named one included) come out translated into
+     * the shape the platform stores rather than passed through as the site's own literal.
+     */
+    starters: startersFrom(blockSpec, allBlocks),
+    // Every branch above writes exactly what `Value` says it writes; the loop is keyed by a
+    // runtime tag and there is no way to say that to the checker.
+    values: values as SiteValues<S>,
+  }
+}
+
+/**
+ * Build the published manifest from a site, plus the things a site knows and a spec cannot.
+ *
+ * `pages` comes from `pagesFromNav(brand.nav)`, which reads `site.values` — so it cannot be
+ * an entry in the spec without being circular. `newPage` is a deliberate short list of
+ * starting sections rather than anything derivable: the seed emits one section per block in
+ * declaration order, which is the home page's layout and wrong for every other page.
+ */
+export const manifestFrom = ({
+  newPage,
+  pages = [],
+  routesAllPages,
+  site,
+}: {
+  newPage?: SeedSection[]
+  pages?: PageDeclaration[]
+  routesAllPages?: boolean
+  site: Site<unknown>
+}): SiteManifest => {
+  const declared = new Set(site.blocks.map((entry) => entry.slug))
+  for (const section of newPage ?? []) {
+    if (!declared.has(section.blockType)) {
+      throw new Error(
+        `newPage names block "${section.blockType}", which this site does not declare. A page created from it renders as nothing at all.`,
+      )
+    }
+  }
+
+  /*
+   * The same guard for a page that commits its own content, and it matters more here.
+   *
+   * `newPage` is wrong in front of the client the first time they add a page, which is at
+   * least loud. A page seed is written once, on a tenant's first pair, and the platform drops
+   * a section it cannot validate rather than refusing the page — so a `blockType` this site
+   * does not declare would arrive as a page that is simply missing its words, months after
+   * anyone looked at this file. Raised at module load, where the call is.
+   */
+  for (const page of pages) {
+    for (const section of page.seed ?? []) {
+      if (!declared.has(section.blockType)) {
+        throw new Error(
+          `page "${page.slug}" seeds block "${section.blockType}", which this site does not declare. It would be dropped on pairing and the page would arrive empty.`,
+        )
+      }
+    }
+  }
+
+  return {
+    blocks: site.blocks,
+    bridgeVersion: BRIDGE_VERSION,
+    ...(site.collections.length > 0 ? { collections: site.collections } : {}),
+    ...(site.forms === undefined ? {} : { forms: site.forms }),
+    generatedAt: new Date().toISOString(),
+    ...(site.layouts === undefined ? {} : { layouts: site.layouts }),
+    ...(newPage ? { newPage } : {}),
+    pages,
+    ...(routesAllPages ? { routesAllPages } : {}),
+    ...(site.seed.length > 0 ? { seed: site.seed } : {}),
+    ...(site.singles === undefined ? {} : { singles: site.singles }),
+    ...(Object.keys(site.starters).length > 0 ? { starters: site.starters } : {}),
+  }
+}
+
+/**
+ * The committed value of every field in a block, keyed by field name.
+ *
+ * Reads exactly one carrier — `value` — and nothing else. A group carries its own `value`
+ * already: `group()` aggregates it from its children at construction time, before
+ * `namedFields` strips `value` from those children on their way into the group's schema. By
+ * the time this walks a group's `fields`, they are schema-only, so there is nothing left
+ * there to recurse into.
+ *
+ * **Near-identical to `defineBlocks`'s `seedFields`, and deliberately not the same function.**
+ * They read different carriers, and that difference is the whole design: `value` is what the
+ * component renders when the platform is unreachable, `default` is what the platform stores
+ * once at pair time. `upload()` and `link()` exist precisely because the two diverge. Folding
+ * them into one function taking a carrier name would put the two halves of that distinction
+ * behind one argument, and the next reader would have to guess which call meant which.
+ */
+const blockValues = (fields: FieldSpec): Record<string, unknown> => {
+  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 out
+}