@unitninety/site-kit 0.0.0-stage → 1.6.2

package/src/legacy/contract.ts

@@ -0,0 +1,664 @@
+/**
+ * The contract between a UnitNinety site and the platform.
+ *
+ * These types are **canonical here**, and the platform imports them from this
+ * package rather than the other way round. That direction is the whole point: a site
+ * repo declaring its own content schema must not depend on platform internals, or
+ * every site is coupled to the dashboard's file layout.
+ *
+ * Changing anything in this file changes what every site repo has to emit, so it is a
+ * breaking change to the contract even when TypeScript doesn't say so. The platform
+ * re-validates everything at runtime (`src/manifest/validate.ts`), which is what
+ * actually enforces it — these types only make it pleasant to get right.
+ */
+
+declare const VALUE: unique symbol
+
+/**
+ * A field spec, carrying the type of the value it committed.
+ *
+ * Phantom — `VALUE` is never assigned and the property never exists at runtime. It is here
+ * so `defineSite` can infer `site.values` from the helpers a site wrote, which is what
+ * retires the hand-written `Brand` type.
+ *
+ * It lives in this file because `defineBlocks.ts` and `defineSite.ts` both need it and both
+ * already import from here; declaring it in either of them would make the two import each
+ * other.
+ */
+export type Spec<V> = { [VALUE]?: V }
+
+/**
+ * The phantom key itself, so a reader can ask whether a type carries a value *at all*.
+ *
+ * `Spec`'s property is optional, which makes it a *weak type*: an object sharing none of its
+ * properties is refused, so `logo: { ratio: 241 / 105 }` does not match `Spec<infer V>` and
+ * needs no help from here.
+ *
+ * **An object with an index signature does.** Weak-type detection is relaxed for one, and a
+ * string index signature says nothing about a symbol key, so `Record<string, number>` matches
+ * `Spec<infer V>` with `V` inferred as `unknown` — a bare entry read from a lookup table
+ * would arrive in `site.values` as `unknown`, which is the widening a hand-written `Brand`
+ * type existed to avoid. `SpecKey extends keyof S` is the test that tells "carries nothing"
+ * apart from "carries `unknown`", and that case is the one that needs it.
+ */
+export type SpecKey = typeof VALUE
+
+/**
+ * The runtime tag that tells a `block()` entry from any other value.
+ *
+ * Here for the same reason `Spec` is: `defineSite` stamps it and `defineBlocks` reads it —
+ * `blocksField()` takes the blocks of a dynamic zone, and those are written with `block()` and
+ * held in a plain const, so it must be able to recognise one. Declared in either module, the
+ * two would have to import each other.
+ *
+ * A symbol rather than a property name, so a site's own data cannot be mistaken for an entry
+ * and `JSON.stringify` never carries it anywhere. `Symbol.for` rather than `Symbol()`, so two
+ * instances of this package in one bundle — a vendored tarball beside a workspace link — still
+ * recognise each other's entries; the registry is keyed by this string.
+ */
+export const BLOCK_ENTRY: unique symbol = Symbol.for('u90.block')
+
+/**
+ * A page section as a site writes it, before `defineSite` knows what it is called.
+ *
+ * The slug is optional because the document key normally supplies it — `hero: block({…})` is
+ * stored as `hero`. A zone's blocks have no document key, so those name their own; see
+ * `block()` for when the two must diverge.
+ *
+ * `F` is left unconstrained here, because `FieldSpec` is declared in `defineBlocks.ts` and
+ * this file is upstream of both modules. Every caller restates the constraint it needs.
+ */
+export type BlockEntry<F = Record<string, unknown>> = {
+  [BLOCK_ENTRY]: true
+  fields: F
+  label?: string
+  /** This block belongs to a layout, not to a page. See `EditorBlock.layoutOnly`. */
+  layoutOnly?: boolean
+  /** Collections this block draws, by slug. See `EditorBlock.renders`. */
+  renders?: string[]
+  seed: boolean
+  /** Stored slug, when it must differ from the document key. See `block()`. */
+  slug?: string
+}
+
+/**
+ * Field types the dashboard's editors can render.
+ *
+ * Deliberately a closed set. A site declaring something outside it gets its whole
+ * manifest rejected rather than a field that silently can't be edited — the platform
+ * would otherwise fall through to a `default` branch, render nothing, and leave a
+ * client unable to change something they can see on their own page.
+ */
+export type EditorFieldType =
+  | 'array'
+  | 'blocks'
+  | 'checkbox'
+  /**
+   * A script, an embed snippet, or anything else that is code rather than prose.
+   *
+   * Stored as a string exactly like `textarea`, and separate from it for the editor's sake
+   * alone: a code field gets a monospace control with spellcheck, autocorrect and
+   * autocapitalise off, and the rail badges it so a client can tell the one field that
+   * configures a third-party widget from the fields that hold their own words.
+   *
+   * **Badged `E`, for embed, and not `C`.** `C` is the collection badge, and this file's
+   * neighbour in the rail already carries the scar from reusing a letter: `B` for a button
+   * exists because a button once shared `L` with a list, which made the two rows a client is
+   * most likely to be hunting for the only two that looked alike.
+   *
+   * It changes nothing about rendering. A site decides what to do with the string, the same
+   * as it always did — `pbir` passes its reviews script straight to `next/script`.
+   */
+  | 'code'
+  /**
+   * A calendar day, stored as `YYYY-MM-DD`.
+   *
+   * Date-only rather than a timestamp, and that is a decision rather than a simplification:
+   * the field exists for a post's published date, which has no timezone, and date-only ISO
+   * sorts lexicographically so a site can order by it without parsing. Adding a time
+   * component later is additive; taking one away is not.
+   */
+  | 'date'
+  | 'email'
+  | 'group'
+  | 'number'
+  | 'relationship'
+  /**
+   * A field whose value lives once, in the client's Singles, and is pointed at from here
+   * rather than stored on this block. See `reference()` in `defineBlocks.ts`.
+   *
+   * Not folded into `relationship`: a relationship's `relationTo` names a *collection*, and
+   * the dashboard reads it to load picker options. A reference names a **row key inside one
+   * reserved collection**, `_singles`, and there is nothing to pick — the client keeps one
+   * value per key, not a list of rows to choose among. Sharing the type would put `_singles`
+   * into the relationship machinery, offering every client's Single as a relationship
+   * target and storing an id where a key belongs.
+   */
+  | 'reference'
+  | 'richText'
+  | 'select'
+  | 'text'
+  | 'textarea'
+  | 'upload'
+
+export type EditorField = {
+  blocks?: EditorBlock[]
+  /**
+   * The block slugs a zone's children may be, when the site named them instead of embedding
+   * them — resolved against the site's declared blocks when read.
+   *
+   * The alternative to `blocks` above, and the reason both exist: a block whose children may
+   * include its own type cannot embed their definitions, because the manifest is serialised and
+   * the expansion never terminates. Naming defers the lookup to read time, which is what lets
+   * one element contain itself. A slug naming no declared block is carried through the manifest
+   * unrebuilt, not dropped — it resolves to nothing once read, where the full block list is
+   * known. That keeps the manifest non-lossy: a block declared later, or renamed back, comes
+   * good on its own the next time the zone is read, with nothing to republish. In the meantime,
+   * a zone offering one fewer choice still beats an editor that will not open.
+   */
+  childBlocks?: string[]
+  /**
+   * What a `group` **is**, when its fields are one thing the client edits rather than
+   * several — the site *saying so*, rather than the platform inferring it from a name.
+   *
+   * A group carrying this gets one row in the rail and one panel in the inspector, in
+   * place of a row per child. Two of them exist:
+   *
+   *  - `'button'` — its words, where it goes, and whether it opens a new tab. Stamped by
+   *    `link()`.
+   *  - `'sentence'` — a line of copy with one link inside it, stamped by `sentence()`.
+   *    The sentence carries a `{link}` marker saying where the link falls, so the words
+   *    either side of it are one editable string rather than two.
+   *
+   * Which groups got the button panel used to be decided by a rule written in the
+   * platform — *a group whose name is literally `link`* — and a site could only opt in by
+   * choosing that name. That rule spends the name, so a block got **one** button: pbir's
+   * reviews band has two, a Submit call to action and a link out to Google, and under the
+   * naming rule the second could only be loose fields with nothing saying they were one
+   * control.
+   *
+   * `'sentence'` is what that generalisation bought. pbir's privacy line was three rows —
+   * `Before`, `Link`, `After` — because the link falls in the middle of it, and the split
+   * was worse than untidy: `text()` in `shape.ts` trims what it is given, so `'See our '`
+   * lost the space that separated it from the link and the page rendered
+   * `See ourPrivacy Policyfor how we handle your details.` A sentence whose parts are
+   * separate fields cannot hold the whitespace between them.
+   *
+   * **A manifest published before this existed carries no flag**, and the platform's
+   * validator is where the old convention still lives: a group named `link` arriving
+   * without one is marked a button on the way in. That keeps the compatibility in the one
+   * place a stale manifest is already being read, and leaves everything downstream with a
+   * single rule — this property, and not a name.
+   */
+  element?: 'button' | 'sentence' | 'image' | 'video' | 'file'
+  poster?: {
+    label: string
+    constraints?: import('./image').ImageConstraints
+    variants?: Record<string, import('./image').ImageVariantDeclaration>
+  }
+  contractVersion?: 1
+  constraints?: import('./image').ImageConstraints
+  variants?: Record<string, import('./image').ImageVariantDeclaration>
+  /** Shown under the control in the inspector. */
+  description?: string
+  /**
+   * What the empty choice on a single-value `relationship` control is called.
+   *
+   * Optional, and the platform's own wording — "Nothing selected" — stands when it is
+   * absent, because that option is shared by every relationship field and renaming it
+   * globally would mislabel all of them. This exists for the fields where empty *means*
+   * something: a page's Layout is `null` for "inherit from the page above", so an option
+   * reading "Nothing selected" says the opposite of what choosing it does, and the cascade
+   * becomes something a client discovers by accident rather than something they were told.
+   */
+  emptyLabel?: string
+  /** Nested fields, for `group` and `array`. */
+  fields?: EditorField[]
+  hasMany?: boolean
+  /**
+   * Present when the **target** collection should show this edge from its own side.
+   *
+   * The edge is stored once, on the side that declares it. This only asks the dashboard
+   * to derive a panel over there — "Sector › Capabilities" is a filter over rows the
+   * dashboard has already loaded, never a second copy of the reference. Two copies of one
+   * fact is the bug that reports itself as "I removed it and it's still showing".
+   *
+   * `name` may not collide with a real field on the target collection, or the derived
+   * panel and a stored value would fight over one key.
+   */
+  inverse?: { label: string; name: string }
+  label: string
+  /** Eligible website copy is localized by default; false opts this field out. */
+  localized?: boolean
+  /**
+   * Becomes part of a dotted path (`0.slides.1.title`), so it must be an identifier:
+   * letters, digits and underscores, starting with a letter. A name containing a `.`
+   * would address a different field than it claims to.
+   */
+  name: string
+  options?: { label: string; value: string }[]
+  /**
+   * Renders the control read-only. Never *grants* anything — permissions come from
+   * the platform, and omitting this cannot widen them.
+   */
+  readOnly?: boolean
+  relationTo?: string
+  /**
+   * The key of the Single this field points at, present only on a `type: 'reference'` field.
+   *
+   * **Not `relationTo`.** `relationTo` names a collection the dashboard's relationship
+   * control loads options from; this names a row inside `_singles`, which is not a
+   * collection a client picks from — it is the one place a scalar like a phone number or
+   * an ABN is kept, reused wherever a block points at it. Reusing `relationTo` here would
+   * make every client's Singles selectable as a relationship target, and would store an id
+   * where this needs a stable key instead.
+   *
+   * The site names the **default** key; nothing here resolves it to a value yet — that is
+   * later work, on egress. See `reference()` in `defineBlocks.ts`.
+   */
+  referenceKey?: string
+  required?: boolean
+  type: EditorFieldType
+}
+
+export type EditorBlock = {
+  fields: EditorField[]
+  label: string
+  /**
+   * This block belongs to a layout, not to a page.
+   *
+   * `seed: false` keeps a block out of the seed; it does not keep it out of the picker, so a
+   * client could add their own header as a page section and get two of them. The platform
+   * still learns nothing about what this block *is* — only that the site says it is not a
+   * page section, which is the site's call in exactly the way every other declaration is.
+   */
+  layoutOnly?: boolean
+  /**
+   * Collections this block draws, by slug.
+   *
+   * The block is the thing rendering, so it is the thing that declares it — and a list,
+   * because one block legitimately draws more than one: a "What we do" section whose columns
+   * are `sectors` and whose lists inside them are `capabilities`.
+   *
+   * What it buys is the editor knowing where rows belong. Without it the dashboard appends
+   * every declared collection to the end of the rail at the same level as the page's own
+   * sections, which says nothing true: those rows are drawn *by* a section, and a client
+   * clicking the section that draws them found none of them there.
+   *
+   * Absent rather than empty when a block draws nothing, so a site that never declares one
+   * publishes exactly the manifest it published before.
+   */
+  renders?: string[]
+  /** Stored on every section as `blockType`. Must be an identifier. */
+  slug: string
+}
+
+/**
+ * A repeatable set of rows the client manages as records rather than as page copy —
+ * projects, team members, testimonials.
+ *
+ * The distinction from a block's `array` field is *ownership*, not shape. An array
+ * belongs to the section it sits in: reordering the page moves it, and deleting the
+ * section deletes it. A collection's rows are their own records, listed in the CMS,
+ * addressable individually, and rendered by whichever sections ask for them.
+ *
+ * Rows are stored one per database row, all collections of all tenants in the same
+ * table, keyed by this `slug` — so declaring one here costs no migration on the
+ * platform, exactly like declaring a block.
+ */
+/**
+ * Where a collection's rows are rendered on the site.
+ *
+ * **The platform cannot work this out.** A row is a record in a jsonb column; whether
+ * it also has a page of its own, and at what address, is the site's own routing and
+ * lives nowhere else. Without this the dashboard can offer "edit this project" and have
+ * no idea which screen to open — which is the whole difference between a CMS list and
+ * editing a thing where it actually appears.
+ *
+ * Same bargain as `pages` and the block schema one level up: the site declares it, the
+ * platform renders from the declaration, and adding a detail route is a site deploy
+ * rather than a platform change.
+ */
+export type CollectionRoutes = {
+  /**
+   * Routes that render rows of this collection alongside other content — a home page
+   * carousel, an index. Rows appear here without having a page to themselves.
+   */
+  alsoOn?: string[]
+  /**
+   * The address of a single row's own page, with `:slug` standing in for the value of
+   * `slugField` — e.g. `/projects/:slug`. Omitted when rows have no page of their own.
+   */
+  detailPath?: string
+  /**
+   * Which of `fields` fills `:slug`. Required if `detailPath` uses one.
+   *
+   * **A row with nothing in that field falls back to its `titleField`, slugified** —
+   * lowercased, non-alphanumerics collapsed to hyphens. That is declared behaviour rather
+   * than a platform guess, and it is load-bearing: a collection's seed is captured only on
+   * a tenant's first pair, so rows predating a later-added slug field hold nothing in it
+   * and would otherwise all resolve to `/projects/`. A site whose addresses come from
+   * anything else should populate the slug field.
+   */
+  slugField?: string
+}
+
+export type ManifestCollection = {
+  /** Where these rows show up on the site. See `CollectionRoutes`. */
+  appearsOn?: CollectionRoutes
+  /** Shown under the row list in the CMS. */
+  description?: string
+  /**
+   * Second column in the CMS list — the field that best distinguishes one row from
+   * another at a glance. Omitted, the column is blank.
+   */
+  detailField?: string
+  fields: EditorField[]
+  /** Singular noun for buttons and empty states, e.g. "project". */
+  itemNoun?: string
+  label: string
+  /** Stored on every row as its `collection`. Must be an identifier. */
+  slug: string
+  /**
+   * The site's committed rows, for seeding a tenant on its first pair — the same
+   * bargain as a block's `default`, one level up. Each entry is one row's values.
+   */
+  seed?: Record<string, unknown>[]
+  /**
+   * Which field titles a row in the CMS list. Must name one of `fields`; a row whose
+   * value there is empty falls back to a positional label.
+   */
+  titleField: string
+}
+
+/**
+ * The types a form field may declare. A closed set, on the same reasoning as
+ * `EditorFieldType`: the platform's submission validator and the dashboard's renderer both
+ * switch on it, and a site inventing a tenth type gets that field silently dropped rather
+ * than mis-rendered.
+ */
+export type FormFieldType =
+  'checkbox' | 'date' | 'email' | 'number' | 'select' | 'tel' | 'text' | 'textarea'
+
+/**
+ * One field of a form, as the platform stores and validates against it.
+ *
+ * `role` promotes a field into the column of that name on every submission — `email`,
+ * `name` or `phone` — so the inbox can sort and search leads without unpacking every row's
+ * free-form data. A form free to declare none of these falls back to a field literally
+ * named `email`/`name`/`phone`; see `promote()` on the platform.
+ */
+export type FormFieldDeclaration = {
+  label: string
+  name: string
+  options?: string[]
+  required?: boolean
+  role?: 'email' | 'name' | 'phone'
+  type: FormFieldType
+}
+
+/**
+ * What a site declares about one form it collects — a contact form, a careers application.
+ *
+ * Mirrors `ManifestCollection`'s bargain one level along: the site says what it collects and
+ * who should hear about it, the platform stores submissions against the declaration and
+ * validates every write to `POST /api/u90/forms/[slug]` against this `fields` snapshot.
+ */
+export type FormDeclaration = {
+  fields: FormFieldDeclaration[]
+  label: string
+  /**
+   * Seeds the handling half — who is emailed — on first sight only, and never again. A
+   * client who repoints the recipients in the dashboard keeps their choice across every
+   * later redeploy; this is only ever read once, the moment the form is first synced.
+   */
+  recipients?: string[]
+  /** Stored on every submission as its `form`. Must be an identifier. */
+  slug: string
+}
+
+/**
+ * One route this site serves, and where it sits in the site's own structure.
+ *
+ * The platform draws its sitemap from these, so a client can see their whole site as a
+ * tree and add a page inside any branch of it. Which means the *shape* has to come from
+ * here: a path is not a hierarchy. JDSi's `/infrastructure` is a top-level route that
+ * belongs under "What We Do" in the menu, and `/about-us/our-team` is nested in both — no
+ * rule over paths gets both right, because the answer is the site's information
+ * architecture and that lives in the site's own nav.
+ *
+ * Same bargain as the block schema: the site declares, the platform renders what it is
+ * given, and changing the structure is a site deploy rather than a platform change. Use
+ * `pagesFromNav` rather than writing these by hand — the nav is already the tree.
+ */
+export type PageDeclaration = {
+  label: string
+  /**
+   * What this page starts with, if the site commits content for it.
+   *
+   * The top-level `seed` on the manifest is the *home* page's, and for a long time it was the
+   * only one a site could send — every other declared route arrived at a new tenant empty,
+   * however much committed copy the repo held for it. That is right for a route the client is
+   * meant to write, and wrong for one the site already renders in full: a legal page whose
+   * words live in the repo seeded as a blank, so pairing produced a page that said nothing
+   * where the site said plenty.
+   *
+   * Optional and additive. A site that sends none behaves exactly as before, and the home
+   * page keeps arriving through the top-level `seed` — this does not replace it, and a page
+   * carrying both is seeded from this one, because the specific beats the general.
+   */
+  seed?: (Record<string, unknown> & { blockType: string })[]
+  /**
+   * The slug of the page this one sits under.
+   *
+   * Must be another declared page's `slug`. Omitted means top level, which the sitemap
+   * hangs off the landing page. A parent naming a page that isn't declared, or a cycle,
+   * rejects the whole manifest — a tree the platform can't lay out is not a tree.
+   */
+  parent?: string
+  /**
+   * Route path with no leading slash — `about-us`, `about-us/our-team`. The landing page
+   * is `home`, matching the slug the platform's own page documents use.
+   */
+  slug: string
+}
+
+/**
+ * The postMessage protocol version between a site and the dashboard.
+ *
+ * The dashboard refuses to render its editor when a site reports a version it doesn't
+ * speak, because the alternative is edits appearing to save and never showing up. Bump
+ * this only alongside a change to the message shapes in `bridge.tsx`, and expect every
+ * site to need a `site-kit` update — that is exactly what it is for.
+ *
+ * **2 — `u90:content` carries `entries`.** Collection rows are editable on Canvas, so the
+ * dashboard pushes the rows alongside the page's sections and `useLiveContent` returns
+ * them. A site on version 1 renders its rows from the server fetch and ignores the push:
+ * a client's keystrokes into a project would do nothing while the page around them
+ * updated live, which is exactly what this version number exists to refuse loudly.
+ *
+ * **3 — `u90:content` carries `layout`.** The chrome a page is drawn inside — its header,
+ * its footer — is its own document, and the dashboard now pushes its blocks beside the
+ * page's sections so a tagline in a header edits live like anything else on the screen.
+ *
+ * That much is additive, and on its own would not have moved this number: a site on 2
+ * ignores a key it does not read. It bumps because of the other half of the feature, which
+ * ships *here* — a site marks its chrome by calling `layoutField`, so a site on 2 marks no
+ * layout field at all and its Canvas would show a header the client can see and cannot
+ * touch, with nothing saying why. Refusing that site and naming both versions says what
+ * has to happen, which is that this package needs re-vendoring. The refusal is a choice to
+ * keep the two halves in step, not a wire format they truly disagree about.
+ */
+export const BRIDGE_VERSION = 3
+
+/**
+ * The browsing-context name Canvas gives every site iframe.
+ *
+ * `window.parent !== window` is the ordinary framed check, but Vercel Sandbox previews run in a
+ * sandboxed cross-origin iframe whose child can report itself as its own parent. The name is an
+ * explicit identity that survives the preview route's redirects without leaking a secret into
+ * the URL. It only enables the bridge; every inbound message is still restricted to the site's
+ * configured platform origin.
+ */
+export const CANVAS_FRAME_NAME = 'u90-canvas'
+
+/** A named arrangement of blocks with one content slot. Absent on a site that declares none. */
+export type LayoutDeclaration = {
+  default?: boolean
+  entries: (Record<string, unknown> & { blockType: string })[]
+  label: string
+  /** The declaration key. Stable across re-seeds; the label is not. */
+  name: string
+}
+
+/**
+ * One shared scalar a site says its client starts with.
+ *
+ * Not a category the platform invented and not a shape it understands: the label is the
+ * client's word for the fact, the value is whatever the site shipped with, and the platform
+ * learns nothing about what any of them mean beyond whether it is a piece of text or a URL.
+ * That is the whole difference from `business()`, which named the facts itself and so could
+ * only ever describe the sites it had been written for.
+ *
+ * The key is the identifier a block's `referenceKey` points at, so it obeys the rule field
+ * names obey — see `singles()` in `defineBlocks.ts`.
+ */
+export type SingleDeclaration = {
+  /** The identifier a `reference()` names. Stable across re-seeds; the label is not. */
+  key: string
+  /** What the client recognises the value by in their Singles tab. Theirs to change. */
+  label: string
+  type: 'link' | 'text'
+  /** What the site ships with, and what the seeded row starts as. */
+  value: string
+}
+
+/**
+ * What a site publishes at `GET /api/u90/manifest`.
+ *
+ * The platform fetches this, validates it, and renders its editor from it. It is never
+ * accepted over any other route: one authenticated way in is what makes validation
+ * worth having.
+ */
+export type SiteManifest = {
+  blocks: EditorBlock[]
+  bridgeVersion: number
+  /**
+   * Repeatable record types this site renders from. Optional: a site with none is
+   * exactly the site this contract described before they existed.
+   */
+  collections?: ManifestCollection[]
+  /** ISO 8601. Only shown to an operator, to judge how fresh a schema is. */
+  generatedAt: string
+  /**
+   * The sections a page starts with when a client adds one in the dashboard.
+   *
+   * Distinct from `seed`, which is the copy this site already serves and is captured once on
+   * a tenant's first pair. This is applied on **every** create, forever, and lands as a
+   * draft. The platform cannot invent it: it has no way to know which of a site's blocks
+   * belong on a page it did not design — a client-added page should not open with a hero
+   * carousel — so the site says, and a site that says nothing gets a blank page.
+   *
+   * **Position is the address.** An editable element is `${sectionIndex}.${fieldPath}`, so
+   * this array's order is the identity of every field on the new page. Reordering it changes
+   * what existing pages' stored content means.
+   *
+   * Give the leaves literal placeholder words rather than leaving them empty. Everywhere else
+   * in this contract a blank field means "keep the copy the component ships with", but a
+   * brand-new page has no committed copy underneath it — so blank means nothing renders, and
+   * an element with no text is one the editing bridge cannot make clickable.
+   */
+  newPage?: SeedSection[]
+  /**
+   * What one fresh instance of each block contains, keyed by block slug.
+   *
+   * Read when a client adds a section in the dashboard. The platform stores exactly this,
+   * then lets them edit it.
+   *
+   * **The platform cannot invent it, and an empty section is worse than none.** A section
+   * whose leaves are blank renders nothing, and an element with no text is one the editing
+   * bridge cannot make clickable — so appending a hollow block would add an invisible
+   * section a client can neither see nor select. The same reasoning `newPage` carries, per
+   * block rather than per page.
+   *
+   * **Here rather than on `EditorBlock`, and that is not filing.** `EditorBlock` is schema,
+   * and schema is carrier-independent: a site may declare a default through `default` or
+   * through the positional `value` form, and `defineSite` and `defineBlocks` must publish
+   * the same fields either way — `verify:define-site` asserts exactly that. Content hung off
+   * a block would make its schema depend on which carrier the site happened to use. So this
+   * sits beside `seed` and `newPage`, with the other content, and is validated like them.
+   *
+   * A block absent from this map declares no defaults. The dashboard still offers it and
+   * says it will arrive empty, rather than hiding a block the site can render.
+   */
+  starters?: Record<string, Record<string, unknown>>
+  /**
+   * Routes the site serves, offered to clients as link targets and drawn as the sitemap.
+   *
+   * `parent` is what makes it a tree rather than a list; see `PageDeclaration`.
+   */
+  pages: PageDeclaration[]
+  /**
+   * True when the site serves a page at **every** slug the platform stores — a catch-all
+   * route rather than one hand-built route per address.
+   *
+   * The dashboard's page tree marks a page it holds that this manifest does not declare as
+   * "Not routed", which is the honest thing to say when each address needs its own file and
+   * a deploy. With a catch-all it is false, and telling a client the page they just added is
+   * unreachable — when it is live — is worse than saying nothing at all.
+   *
+   * It does not replace `pages`: those are still what the nav lists, what a link picker
+   * offers, and what the tree's shape comes from. This only changes what an *undeclared*
+   * page is called.
+   */
+  routesAllPages?: boolean
+  /**
+   * The site's own committed content, for seeding a tenant on its first pair.
+   *
+   * Optional, and only ever read once: a tenant that already has a page keeps it.
+   * The point is that a client's first session shows their real copy rather than a
+   * grid of empty fields — the site looks finished, so the editor should too.
+   *
+   * It has to come from the site because nothing else can know it. The manifest
+   * describes field *names and types*; the values live in the site's own config, and
+   * the rendered page cannot be scraped for them either — the editable-field markers
+   * only appear once content exists, so a fresh site emits none.
+   */
+  seed?: SeedSection[]
+  /**
+   * The site's starting layouts. Seeded once per tenant, client-owned after that — so this
+   * is a *starting set*, not a description of what the tenant currently has. See the
+   * layouts design on why re-seeding is additive and keyed on `name`.
+   */
+  layouts?: LayoutDeclaration[]
+  /**
+   * The shared values this site starts with. Seeded once per tenant, client-owned after
+   * that — so this is a *starting set*, like `layouts`, and never a description of what the
+   * tenant currently holds.
+   *
+   * A site that points at a Single with `reference()` and declares nothing here is legal and
+   * renders correctly off its committed fallbacks; what it costs the client is discovery,
+   * which is the whole reason this key exists. The reverse is legal too: a value declared
+   * here that no block references yet is seeded and left alone.
+   */
+  singles?: SingleDeclaration[]
+  /**
+   * The forms this site collects, declared once and maintained afterwards by the platform's
+   * own sync — a redeploy replaces `fields` on the stored row, and leaves the label, the
+   * recipients and whether the client switched it off alone. Optional, on the same terms as
+   * `collections`: a site with none is exactly the site this contract described before forms
+   * existed.
+   */
+  forms?: FormDeclaration[]
+}
+
+/** One seeded section: a block slug plus values matching that block's fields. */
+export type SeedSection = Record<string, unknown> & { blockType: string }
+
+/** The three values a site needs, as returned by `POST /api/u90/pair`. */
+export type PairedCredentials = {
+  apiKey: string
+  platformUrl: string
+  revalidateSecret: string
+  tenantSlug: string
+}