@unitninety/site-kit 0.0.0-stage → 1.6.2

package/src/site/assemble.ts

@@ -0,0 +1,109 @@
+import { elements, expand, type DocumentDecl, type FieldDecl, type Resolved, type Schema } from '../elements'
+import { replyFrom, type ReplyTarget } from './replies'
+import type { Store } from './store'
+import type { Site } from './types'
+import type { Reply, ReplyDocument } from './wire'
+
+/** A document's SEO settings as a render uses them: `ogImage` resolved to its URL. */
+export type RouteSeo = { title?: string; description?: string; ogTitle?: string; ogDescription?: string; ogImage?: string; canonical?: string; noindex?: boolean }
+/** What `u90.render` draws: a document's read values, its layouts' read values, and the tags its cache entry carries. */
+export type RouteRead = {
+  status: 'ok' | 'missing'
+  document?: { kind: 'page' | 'entry'; id: string; slug: string; collection?: string; key?: string; pageType?: string; title?: string; seo: RouteSeo | null; layoutChain: string[] }
+  read?: unknown
+  layouts?: Record<string, unknown>
+  tags: string[]
+  /** Rendered from the code's defaults, not from the platform. */
+  unavailable?: boolean
+  /** The reply's `translated`, as the platform answered it: a tenant with languages only. The metadata lists only these languages, the default and the original (ruling R2). */
+  translated?: string[]
+}
+export type AssembleOptions = {
+  draft: boolean
+  target: ReplyTarget
+  /** True when the reply's `manifest` differs from the running code's: the platform has not caught up with a deploy. */
+  stale: boolean
+  /** The code's defaults, needed only when `stale`. */
+  defaults: Store | null
+  /** Draft mode only: the language a translated frame reads in, which internal link hrefs keep. Absent, no href changes. */
+  draftLocale?: string
+  /** The address prefix of the language the reply is read in (`/fr`): page and entry routes carry it. Absent, no route changes. */
+  localePrefix?: string
+}
+const declaredCodePage = (site: Site, t: ReplyTarget) =>
+  'page' in t ? Object.hasOwn(site.pages, t.page) : 'route' in t ? Object.values(site.pages).some((p) => p.route === t.route) : false
+const declOf = (site: Site, d: ReplyDocument): DocumentDecl | null => {
+  if (d.kind === 'entry') return d.collection && Object.hasOwn(site.schema.collections, d.collection) ? { kind: 'entry', collection: d.collection } : null
+  if (d.key) return Object.hasOwn(site.pages, d.key) ? { kind: 'page', blocks: site.pages[d.key].blocks } : null
+  return d.pageType && Object.hasOwn(site.pageTypes, d.pageType) ? { kind: 'page', blocks: site.pageTypes[d.pageType].blocks } : null
+}
+
+/**
+ * A reply expanded with the running code's declarations, never the platform's copy of them, so a
+ * deploy never waits for the platform to pull its manifest. A field the stored document lacks reads
+ * as its declared default, and a `renamedFrom` field reads from its old key. Only while `stale`, a
+ * code page, layout or Single the code declares and the reply lacks comes from the code's defaults.
+ * A document the running code does not declare (a removed code page, page type or collection) is missing.
+ */
+export function assemble(site: Site, reply: Reply, opts: AssembleOptions): RouteRead {
+  if (reply.status === 'missing') {
+    if (opts.stale && opts.defaults && declaredCodePage(site, opts.target))
+      return { ...assemble(site, replyFrom(site, opts.defaults, opts.target, reply.manifest), { ...opts, stale: false, defaults: null }), unavailable: true }
+    return { status: 'missing', tags: reply.tags }
+  }
+  const d = reply.document
+  const docDecl = declOf(site, d)
+  if (!docDecl) return { status: 'missing', tags: reply.tags }
+
+  // A Single the running code declares expands with that declaration, and any other with the one the reply carries —
+  // unless the reply's declaration names an element this registry does not know (a platform newer than this site),
+  // in which case that Single is skipped and reads as absent rather than throwing on every read.
+  const resolvable = (d: FieldDecl): boolean =>
+    'element' in d ? Object.hasOwn(elements, d.element) : d.container === 'u90/group' ? Object.values(d.fields).every(resolvable) : d.container === 'u90/list' ? resolvable(d.item) : false
+  const carried = Object.fromEntries(
+    Object.entries(reply.singles).filter(([k, s]) => !Object.hasOwn(site.schema.singles, k) && s.declaration && resolvable(s.declaration)).map(([k, s]) => [k, { key: k, field: s.declaration as FieldDecl }]),
+  )
+  const schema: Schema = Object.keys(carried).length ? { ...site.schema, singles: { ...site.schema.singles, ...carried } } : site.schema
+  const base: Resolved = {
+    media: new Map(Object.entries(reply.media)),
+    pages: new Map(Object.entries(reply.pages)),
+    entries: new Map(Object.entries(reply.entries)),
+    queries: new Map(Object.entries(reply.queries)),
+    inverses: new Map(Object.entries(reply.inverses)),
+  }
+  // A draft reply of a translated language lists, by document, the overlay keys that fell back; a published reply carries none.
+  const fallbacksOf = (docKey: string) => (opts.draft ? reply.fallbacks?.[docKey] : undefined)
+  const storedSingles = new Map<string, unknown>(Object.entries(reply.singles).map(([k, s]) => [k, s.stored]))
+  if (opts.stale && opts.defaults) for (const [k, s] of opts.defaults.singles) if (!storedSingles.has(k)) storedSingles.set(k, s.doc)
+  const singles = new Map<string, unknown>()
+  for (const [key, doc] of storedSingles) if (Object.hasOwn(schema.singles, key)) singles.set(key, expand(schema, { kind: 'single', key }, doc, base, { at: `single:${key}`, draft: opts.draft, draftLocale: opts.draftLocale, localePrefix: opts.localePrefix, fallbacks: fallbacksOf(`single:${key}`) }))
+  const resolved: Resolved = { ...base, singles }
+
+  const layouts: Record<string, unknown> = {}
+  const chain: string[] = []
+  const layoutDecl: DocumentDecl = { kind: 'layout', blocks: { container: 'u90/zone', allow: Object.keys(schema.blocks) } }
+  for (const key of d.layoutChain) {
+    const l = (Object.hasOwn(reply.layouts, key) ? reply.layouts[key] : undefined) ?? (opts.stale ? opts.defaults?.layouts.get(key)?.doc : undefined)
+    if (l === undefined) continue
+    chain.push(key)
+    layouts[key] = expand(schema, layoutDecl, l, resolved, { at: `layout:${key}`, draft: opts.draft, draftLocale: opts.draftLocale, localePrefix: opts.localePrefix, fallbacks: fallbacksOf(`layout:${key}`) })
+  }
+  const s = d.seo
+  const ogImage = s?.ogImage != null ? reply.media[String(s.ogImage)]?.url : undefined
+  const seo: RouteSeo | null = s
+    ? { ...(s.title ? { title: s.title } : {}), ...(s.description ? { description: s.description } : {}), ...(s.ogTitle ? { ogTitle: s.ogTitle } : {}), ...(s.ogDescription ? { ogDescription: s.ogDescription } : {}), ...(ogImage ? { ogImage } : {}), ...(s.canonical ? { canonical: s.canonical } : {}), ...(s.noindex ? { noindex: true } : {}) }
+    : null
+  return {
+    status: 'ok',
+    document: {
+      kind: d.kind, id: d.id, slug: d.slug,
+      ...(d.collection ? { collection: d.collection } : {}), ...(d.key ? { key: d.key } : {}), ...(d.pageType ? { pageType: d.pageType } : {}), ...(d.title ? { title: d.title } : {}),
+      seo,
+      layoutChain: chain,
+    },
+    read: expand(schema, docDecl, d.stored, resolved, { at: `${d.kind}:${d.id}`, draft: opts.draft, draftLocale: opts.draftLocale, localePrefix: opts.localePrefix, fallbacks: fallbacksOf(`${d.kind}:${d.id}`) }),
+    layouts,
+    tags: reply.tags,
+    ...(reply.translated ? { translated: reply.translated } : {}),
+  }
+}

package/src/site/defineSite.ts

@@ -0,0 +1,132 @@
+import { seedIssues, validateSchema, type BlockDecl, type CollectionDecl, type FieldDecl, type Issue, type Schema, type SeedKnown, type ZoneDecl } from '../elements'
+import { SLOT } from './documents'
+import type { BlockDef, CollectionDef, LayoutDef, PageDef, PageTypeDef, Seo, Singles, Site, SiteManifest } from './types'
+import type { KnowledgePolicyV1 } from '../features/contracts/knowledgePolicy'
+import { SITE_KIT_VERSION } from './version'
+
+export class SiteDeclarationError extends Error {
+  constructor(public issues: Issue[]) { super(issues.map((i) => `${i.path}: ${i.message}`).join('\n')); this.name = 'SiteDeclarationError' }
+}
+const blocksOf = (decl: FieldDecl): BlockDef[] => (decl as { __blocks?: BlockDef[] }).__blocks ?? []
+/**
+ * Every block reachable from a declaration, recursively through groups, lists and nested zones.
+ * `add` records a block and says whether it is new, so a block reached twice is walked once.
+ */
+const collect = (decl: FieldDecl, add: (b: BlockDef) => boolean) => {
+  if ('element' in decl) return
+  if (decl.container === 'u90/group') return Object.values(decl.fields).forEach((f) => collect(f, add))
+  if (decl.container === 'u90/list') return collect(decl.item, add)
+  for (const b of blocksOf(decl)) if (add(b)) Object.values(b.fields).forEach((f) => collect(f as FieldDecl, add))
+}
+const issue = (path: string, code: string, message: string): Issue => ({ path, code, message, severity: 'error' })
+/**
+ * R37: v1's renderer (`server/render.tsx`) turns a block's own zone fields into rendered children and
+ * nothing else — a zone inside a `group()` or a `list()` would reach the component as raw block data
+ * and fail at request time ("Objects are not valid as a React child"), after the build had passed.
+ * The registry can express a nested zone; v1 does not render one, so it is refused here, by path.
+ * `direct` is true only for a block's own field.
+ */
+const misplacedZones = (decl: FieldDecl, at: string, direct: boolean, into: Issue[]) => {
+  if ('element' in decl) return
+  if (decl.container === 'u90/zone') { if (!direct) into.push(issue(at, 'zone-placement', 'a zone must be a direct block field in v1')); return }
+  if (decl.container === 'u90/group') return Object.entries(decl.fields).forEach(([k, f]) => misplacedZones(f, `${at}.fields.${k}`, false, into))
+  if (decl.container === 'u90/list') return misplacedZones(decl.item, `${at}.item`, false, into)
+}
+const PAGE_KEY = /^[a-z][a-zA-Z0-9_-]*$/
+const strip = (fields: Record<string, unknown>) => Object.fromEntries(Object.entries(fields).map(([k, v]) => [k, JSON.parse(JSON.stringify(v))])) as Record<string, FieldDecl>
+
+export function defineSite(input: { singles: Singles; collections: Record<string, CollectionDef>; layouts: Record<string, LayoutDef>; pages: Record<string, PageDef>; pageTypes: Record<string, PageTypeDef>; seo?: Seo; knowledge?: KnowledgePolicyV1 }): Site {
+  const defaults = Object.entries(input.layouts).filter(([, l]) => l.default)
+  if (defaults.length !== 1) throw new Error(`A site needs exactly one default layout; found ${defaults.length}.`)
+  const defaultLayout = defaults[0][0]
+  // A page reference holds a declared page's key or a stored page's id, and the two are told apart by
+  // shape alone (`isDocumentId`: a stored id starts with a digit). A key that could look like an id
+  // would be read as one, so every key starts with a letter.
+  for (const k of Object.keys(input.pages)) {
+    if (!/^[a-z]/.test(k)) throw new Error(`Page key "${k}" must start with a lower-case letter.`)
+    if (!PAGE_KEY.test(k)) throw new Error(`Page key "${k}" may hold only letters, digits, "_" and "-".`)
+  }
+  const issues: Issue[] = []
+  // Layouts are named by string, so a typo would otherwise surface only at request time — and a
+  // parent cycle would never surface at all: the layout chain would be walked forever.
+  const declared = (name: string | undefined, at: string) => { if (name !== undefined && !Object.hasOwn(input.layouts, name)) issues.push(issue(at, 'unknown-layout', `layout "${name}" is not declared`)) }
+  for (const [k, l] of Object.entries(input.layouts)) declared(l.parent, `layouts.${k}.parent`)
+  for (const [k, p] of Object.entries(input.pages)) declared(p.layout, `pages.${k}.layout`)
+  for (const [k, t] of Object.entries(input.pageTypes)) declared(t.layout, `pageTypes.${k}.layout`)
+  for (const c of Object.values(input.collections)) declared(c.template?.layout, `collections.${c.name}.template.layout`)
+  const inCycle = new Set<string>()
+  for (const [k, l] of Object.entries(input.layouts)) {
+    if (inCycle.has(k)) continue
+    const chain = [k]
+    for (let p = l.parent; p !== undefined && Object.hasOwn(input.layouts, p); p = input.layouts[p].parent) {
+      if (p === k) { issues.push(issue(`layouts.${k}.parent`, 'layout-cycle', `layout parents form a cycle: ${[...chain, k].join(' → ')}`)); chain.forEach((c) => inCycle.add(c)); break }
+      if (chain.includes(p)) break // a cycle further up, reported from one of its own layouts
+      chain.push(p)
+    }
+    // No SLOT and the page's own blocks have nowhere to go; two and they render twice.
+    const slots = l.entries.filter((e) => e === SLOT).length
+    if (slots !== 1) issues.push(issue(`layouts.${k}`, 'layout-slot', `a layout needs exactly one SLOT; found ${slots}`))
+  }
+  // Blocks are found by walking the site and keyed by name, so two different declarations under one
+  // name would otherwise resolve silently to whichever the walk met first (or last).
+  const blocks = new Map<string, BlockDef>()
+  const add = (b: BlockDef): boolean => {
+    const seen = blocks.get(b.name)
+    if (seen === b) return false
+    if (seen) { issues.push(issue(`blocks.${b.name}`, 'duplicate-block', `two blocks named "${b.name}" are declared; each block needs its own name`)); return false }
+    blocks.set(b.name, b)
+    return true
+  }
+  for (const l of Object.values(input.layouts)) for (const e of l.entries) if (e !== SLOT && add(e)) Object.values(e.fields).forEach((f) => collect(f as FieldDecl, add))
+  for (const p of [...Object.values(input.pages), ...Object.values(input.pageTypes)]) collect(p.blocks, add)
+  for (const c of Object.values(input.collections)) if (c.template) collect(c.template.zone, add)
+  for (const b of blocks.values()) for (const [f, d] of Object.entries(b.fields)) misplacedZones(d as FieldDecl, `blocks.${b.name}.fields.${f}`, true, issues)
+  for (const c of Object.values(input.collections)) for (const [f, d] of Object.entries(c.fields)) misplacedZones(d as FieldDecl, `collections.${c.name}.fields.${f}`, false, issues)
+  for (const s of Object.values(input.singles)) misplacedZones(s.decl, `singles.${s.key}.field`, false, issues)
+  if (issues.length) throw new SiteDeclarationError(issues)
+  for (const c of Object.values(input.collections)) {
+    const slugs = new Set<string>()
+    for (const e of c.entries ?? []) { if (slugs.has(e.slug)) throw new Error(`Entry "${e.slug}" is declared twice in collection ${c.name}.`); slugs.add(e.slug) }
+  }
+  const routes = new Map<string, string>()
+  const claim = (route: string, by: string) => { if (routes.has(route)) throw new Error(`Route ${route} is declared by both ${routes.get(route)} and ${by}.`); routes.set(route, by) }
+  for (const [k, p] of Object.entries(input.pages)) claim(p.route, `page ${k}`)
+  for (const [k, c] of Object.entries(input.collections)) if (c.route) claim(c.route, `collection ${k}`)
+  for (const [k, t] of Object.entries(input.pageTypes)) claim(t.route, `page type ${k}`)
+  const schema: Schema = {
+    blocks: Object.fromEntries([...blocks.values()].map((b) => [b.name, { name: b.name, label: b.label, fields: strip(b.fields), ...(b.entry ? { entry: b.entry.name } : {}), order: Object.keys(b.fields) } satisfies BlockDecl])),
+    collections: Object.fromEntries(Object.values(input.collections).map((c) => [c.name, { name: c.name, label: c.label, fields: strip(c.fields), ...(c.template ? { template: JSON.parse(JSON.stringify(c.template.zone)) } : {}), ...(c.defaultSort ? { defaultSort: c.defaultSort } : {}), order: Object.keys(c.fields) } satisfies CollectionDecl])),
+    singles: Object.fromEntries(Object.values(input.singles).map((s) => [s.key, { key: s.key, field: JSON.parse(JSON.stringify(s.decl)) }])),
+  }
+  // Finding 1: seed entries were checked only when seeded, at the platform or in the defaults store.
+  const known: SeedKnown = {
+    page: (key) => Object.hasOwn(input.pages, key),
+    entry: (collection, key) => (Object.values(input.collections).find((c) => c.name === collection)?.entries ?? []).some((e) => e.slug === key),
+  }
+  const badSeeds = Object.values(input.collections).flatMap((c) => (c.entries ?? []).flatMap((e) => seedIssues(schema, { kind: 'entry', collection: c.name }, { fields: e.fields, blocks: e.blocks }, `collections.${c.name}.entries.${e.slug}`, known)))
+  if (badSeeds.length) throw new SiteDeclarationError(badSeeds)
+  return {
+    ...(input.knowledge !== undefined ? { knowledge: input.knowledge } : {}),
+    singles: input.singles, collections: input.collections, blocks: Object.fromEntries(blocks), schema, seo: input.seo ?? {}, defaultLayout,
+    layouts: Object.fromEntries(Object.entries(input.layouts).map(([k, l]) => [k, { default: !!l.default, parent: l.parent, blocks: l.entries.map((e) => (e === SLOT ? 'SLOT' : e.name)) }])),
+    pages: Object.fromEntries(Object.entries(input.pages).map(([k, p]) => [k, { route: p.route, layout: p.layout ?? defaultLayout, blocks: JSON.parse(JSON.stringify(p.blocks)) as ZoneDecl }])),
+    pageTypes: Object.fromEntries(Object.entries(input.pageTypes).map(([k, t]) => [k, { label: t.label, route: t.route, layout: t.layout ?? defaultLayout, blocks: JSON.parse(JSON.stringify(t.blocks)) as ZoneDecl }])),
+  }
+}
+
+export function manifestFrom(site: Site): SiteManifest {
+  const r = validateSchema(site.schema)
+  if (!r.ok) throw new SiteDeclarationError(r.issues)
+  const routes = [...Object.values(site.pages).map((p) => p.route), ...Object.values(site.collections).flatMap((c) => (c.route ? [c.route] : [])), ...Object.values(site.pageTypes).map((t) => t.route)]
+  const entries = Object.fromEntries(Object.values(site.collections).flatMap((c) => (c.entries?.length ? [[c.name, c.entries]] : [])))
+  const collections = Object.fromEntries(Object.values(site.collections).map((c) => [c.name, { ...(c.route ? { route: c.route } : {}), ...(c.template?.layout ? { layout: c.template.layout } : {}) }]))
+  const order = {
+    blocks: Object.keys(site.schema.blocks),
+    collections: Object.keys(site.schema.collections),
+    singles: Object.keys(site.schema.singles),
+    pages: Object.keys(site.pages),
+    pageTypes: Object.keys(site.pageTypes),
+    layouts: Object.keys(site.layouts),
+  }
+  return { ...(site.knowledge !== undefined ? { knowledge: site.knowledge } : {}), schema: r.schema, layouts: site.layouts, pages: site.pages, pageTypes: site.pageTypes, entries, collections, routes, seo: site.seo, bridgeVersion: 4, siteKitVersion: SITE_KIT_VERSION, order }
+}

package/src/site/documents.ts

@@ -0,0 +1,18 @@
+import type { ZoneDecl } from '../elements'
+import type { BlockDef, CollectionDef, Decl, EntrySeed, Fields, LayoutDef, PageDef, PageTypeDef, Singles, SingleDef } from './types'
+
+export const SLOT = 'SLOT' as const
+export const humanise = (name: string) => name.replace(/([a-z])([A-Z])/g, '$1 $2').replace(/^./, (c) => c.toUpperCase())
+
+export const defineSingles = <M extends Record<string, Decl<unknown>>>(map: M): { [K in keyof M]: SingleDef<M[K] extends Decl<infer R> ? R : never> } =>
+  Object.fromEntries(Object.entries(map).map(([key, decl]) => [key, { key, decl }])) as never
+export const collection = <F extends Fields>(name: string, o: { label?: string; fields: F; route?: string; defaultSort?: CollectionDef['defaultSort']; entries?: EntrySeed[] }): CollectionDef<F> =>
+  ({ kind: 'collection', name, label: o.label ?? humanise(name), fields: o.fields, route: o.route, defaultSort: o.defaultSort, ...(o.entries ? { entries: o.entries } : {}) })
+export const withTemplate = <C extends CollectionDef>(c: C, zone: Decl<unknown>, o: { layout?: string } = {}): C =>
+  ({ ...c, template: { zone: zone as ZoneDecl, layout: o.layout } })
+export const block = <F extends Fields, C extends CollectionDef | undefined = undefined>(name: string, o: { label?: string; fields: F; component: unknown; entry?: C }): BlockDef<F, C> =>
+  ({ kind: 'block', name, label: o.label ?? humanise(name), fields: o.fields, component: o.component, entry: o.entry })
+export const layout = (o: { default?: boolean; parent?: string }, entries: Array<BlockDef | typeof SLOT>): LayoutDef => ({ kind: 'layout', ...o, entries })
+export const page = (o: { route: string; layout?: string; blocks: Decl<unknown> }): PageDef => ({ kind: 'page', route: o.route, layout: o.layout, blocks: o.blocks as ZoneDecl })
+export const pageType = (o: { label: string; route: string; layout?: string; blocks: Decl<unknown> }): PageTypeDef => ({ kind: 'pageType', ...o, blocks: o.blocks as ZoneDecl })
+export const singlesOf = (s: Singles) => s

package/src/site/fields.ts

@@ -0,0 +1,59 @@
+import type { BooleanRead, ChoiceReadValue, DateRead, EntriesRead, EntryRead, FileRead, ImageRead, LinkRead, NumberRead, RichTextRead, TextRead, VideoRead } from '../elements'
+import type { BlockDef, Decl, Fields, Read, SingleDef, Simplify, ZoneNode } from './types'
+
+type Common = { label?: string; description?: string; required?: boolean; translatable?: boolean; lock?: string[]; renamedFrom?: string }
+/** Options that are part of the field declaration itself go top-level; the rest is the element's `options`. */
+const leaf = <R>(element: string, common: Common & { default?: unknown }, options: Record<string, unknown>): Decl<R> => {
+  const clean = Object.fromEntries(Object.entries(options).filter(([, v]) => v !== undefined))
+  const decl: Record<string, unknown> = { element }
+  for (const k of ['label', 'description', 'required', 'translatable', 'default', 'lock', 'renamedFrom'] as const) if (common[k] !== undefined) decl[k] = common[k]
+  if (Object.keys(clean).length) decl.options = clean
+  return decl as Decl<R>
+}
+
+export const text = (o: Common & { default?: string; multiline?: boolean; format?: 'plain' | 'email' | 'tel' | 'url' | 'code'; maxLength?: number; pattern?: string } = {}) =>
+  leaf<TextRead>('u90/text', o, { multiline: o.multiline, format: o.format, maxLength: o.maxLength, pattern: o.pattern })
+export const richText = (o: Common & { default?: unknown; inline?: boolean; blocks?: string[]; headings?: string[]; marks?: string[] } = {}) =>
+  leaf<RichTextRead>('u90/rich-text', o, { inline: o.inline, blocks: o.blocks, headings: o.headings, marks: o.marks })
+export const image = (o: Common & { default?: unknown; constraints?: unknown; variants?: Record<string, { media: string; constraints?: unknown }> } = {}) =>
+  leaf<ImageRead>('u90/image', o, { constraints: o.constraints, variants: o.variants })
+export const video = (o: Common & { default?: unknown; poster?: unknown } = {}) => leaf<VideoRead>('u90/video', o, { poster: o.poster })
+export const file = (o: Common & { default?: unknown; mimeTypes?: string[]; maxBytes?: number } = {}) => leaf<FileRead>('u90/file', o, { mimeTypes: o.mimeTypes, maxBytes: o.maxBytes })
+export const link = (o: Common & { default?: unknown; allow?: Array<'page' | 'entry' | 'url' | 'email' | 'tel'> } = {}) => leaf<LinkRead>('u90/link', o, { allow: o.allow })
+export const date = (o: Common & { default?: string; min?: string; max?: string } = {}) => leaf<DateRead>('u90/date', o, { min: o.min, max: o.max })
+export const number = (o: Common & { default?: number; integer?: boolean; min?: number; max?: number; step?: number } = {}) => leaf<NumberRead>('u90/number', o, { integer: o.integer, min: o.min, max: o.max, step: o.step })
+export const boolean = (o: Common & { default?: boolean } = {}) => leaf<BooleanRead>('u90/boolean', o, {})
+export const choice = (values: Array<string | { value: string; label: string }>, o: Common & { default?: string | string[]; multiple?: boolean } = {}) =>
+  leaf<ChoiceReadValue>('u90/choice', o, { values: values.map((v) => (typeof v === 'string' ? { value: v, label: v[0].toUpperCase() + v.slice(1) } : v)), multiple: o.multiple })
+export const relation = (to: string, o: Common & { default?: unknown; many?: boolean; unique?: boolean; inverseOf?: string; depth?: number } = {}) =>
+  leaf<EntryRead | EntryRead[] | null>('u90/relation', o, {
+    to, inverseOf: o.inverseOf, depth: o.depth,
+    cardinality: o.inverseOf ? (o.many ? 'many-to-many' : o.unique ? 'one-to-one' : 'one-to-many') : o.many ? 'many-to-many' : o.unique ? 'one-to-one' : 'many-to-one',
+  })
+export const selection = (to: string, o: Common & { default?: unknown; many?: boolean; max?: number; depth?: number } = {}) =>
+  leaf<EntriesRead>('u90/selection', o, { to, many: o.many, max: o.max, depth: o.depth })
+export const query = (to: string, o: Common & { default?: unknown } = {}) => leaf<EntriesRead>('u90/query', o, { to })
+export const single = <R>(s: SingleDef<R>, o: Common = {}): Decl<R> => leaf<R>('u90/single', o, { key: s.key })
+
+export const group = <F extends Fields>(fields: F, o: { label?: string } = {}): Decl<{ [K in keyof F]: Read<F[K]> }> & { readonly __group: true } =>
+  ({ container: 'u90/group', ...(o.label ? { label: o.label } : {}), fields, order: Object.keys(fields) }) as never
+export const list = <D extends Decl<unknown>>(
+  item: D,
+  o: { label?: string; min?: number; max?: number; default?: unknown[] } = {},
+): Decl<Array<D extends { __group: true } ? Simplify<{ _id: string } & Read<D>> : Read<D>>> =>
+  ({ container: 'u90/list', item, ...Object.fromEntries(Object.entries(o).filter(([, v]) => v !== undefined)) }) as never
+/**
+ * The registry's `allow`/`default` are block NAMES (`string[]`); `defineSite` needs the actual
+ * `BlockDef` objects to walk the site and collect every reachable block, so the zone builders
+ * stash them out of band on a non-enumerable `__blocks` property. Non-enumerable so `deepEqual`
+ * (own enumerable properties only) and `JSON.stringify` both ignore it — the wire format this
+ * produces is exactly the registry's `ZoneDecl`, nothing extra.
+ */
+const withBlocks = <T extends object>(decl: T, blocks: BlockDef[]): T => {
+  Object.defineProperty(decl, '__blocks', { value: blocks })
+  return decl
+}
+export const zone = (o: { label?: string; allow: BlockDef[]; default?: BlockDef[] }): Decl<ZoneNode> =>
+  withBlocks({ container: 'u90/zone', ...(o.label ? { label: o.label } : {}), allow: o.allow.map((b) => b.name), ...(o.default ? { default: o.default.map((b) => b.name) } : {}) }, o.allow) as never
+export const fixed = (blocks: BlockDef[], o: { label?: string } = {}): Decl<ZoneNode> =>
+  withBlocks({ container: 'u90/zone', ...(o.label ? { label: o.label } : {}), allow: blocks.map((b) => b.name), default: blocks.map((b) => b.name), fixed: true }, blocks) as never

package/src/site/index.ts

@@ -0,0 +1,14 @@
+/** The v1 authoring model: builders, documents, `defineSite` and `manifestFrom`. */
+export * from './types'
+export * from './fields'
+export * from './documents'
+export { defineSite, manifestFrom, SiteDeclarationError } from './defineSite'
+export { SITE_KIT_VERSION } from './version'
+export * from './wire'
+export { assemble, type AssembleOptions, type RouteRead, type RouteSeo } from './assemble'
+export { replyFrom, layoutChain, type ReplyTarget } from './replies'
+export { applyTitleTemplate } from '../seo/title'
+export { metadataFor, type PageSeoInput } from '../seo/metadata'
+export { organisationJsonLd } from '../seo/jsonLd'
+export { robotsFor } from '../seo/robots'
+export { sitemapFor } from '../seo/sitemap'

package/src/site/replies.ts

@@ -0,0 +1,118 @@
+import { applyQueryPicks, collectRefs, entryKey, inverseKey, path, queryKey, type DocumentDecl, type EntryRecord, type Id, type MediaRecord, type PageRecord, type QueryStored, type Ref } from '../elements'
+import type { Store, StoredPage } from './store'
+import type { Site } from './types'
+import type { DocumentReply, Reply, ReplyDocument, StoredSingle } from './wire'
+
+/** What a read asks for: a route, a code page by key, or an entry by collection and slug. */
+export type ReplyTarget = { route: string } | { page: string } | { entry: { collection: string; slug: string } }
+
+const routeToRegex = (route: string) => new RegExp('^' + route.replace(/\/:([a-zA-Z]+)/g, '/(?<$1>[^/]+)') + '$')
+/** A layout and its parents, outermost first, from the running code's declarations. */
+export const layoutChain = (site: Site, key: string): string[] => {
+  const chain: string[] = []
+  let k: string | undefined = key
+  while (k) {
+    if (!site.layouts[k]) throw new Error(`Layout "${k}" is not declared.`)
+    chain.unshift(k)
+    k = site.layouts[k].parent
+  }
+  return chain
+}
+const tagOf = (r: Ref): string =>
+  r.kind === 'media' ? `media:${r.id}` : r.kind === 'page' ? `page:${r.id}` : r.kind === 'single' ? `single:${r.key}` : r.kind === 'entry' ? `entry:${r.id}` : `collection:${r.collection}`
+
+/** A query over the store: `where` (eq, neq, in, not-in, is-set), a field `sort`, then the placement's picks and `limit`, which `applyQueryPicks` applies. */
+function runQuery(store: Store, collection: string, q: QueryStored): { ids: Id[]; total: number } {
+  let rows = [...store.entries.values()].filter((e) => e.collection === collection)
+  for (const w of q.where ?? [])
+    rows = rows.filter((e) => {
+      const v = e.fields[w.field]
+      return w.op === 'eq' ? v === w.value : w.op === 'neq' ? v !== w.value : w.op === 'in' ? (w.value as unknown[]).includes(v) : w.op === 'not-in' ? !(w.value as unknown[]).includes(v) : v != null
+    })
+  const sort = q.sort
+  if (sort && sort !== 'manual') rows.sort((a, b) => String(a.fields[sort.field]).localeCompare(String(b.fields[sort.field])) * (sort.dir === 'desc' ? -1 : 1))
+  return applyQueryPicks(rows.map((r) => r.id), q, (id) => store.entries.has(entryKey(collection, id)))
+}
+
+type Found = { doc: ReplyDocument; decl: DocumentDecl }
+const pageFound = (site: Site, p: StoredPage): Found | null => {
+  const blocks = p.key ? site.pages[p.key]?.blocks : p.pageType ? site.pageTypes[p.pageType]?.blocks : undefined
+  if (!blocks) return null
+  return {
+    decl: { kind: 'page', blocks },
+    doc: { kind: 'page', id: p.id, slug: p.slug, route: p.route, ...(p.key ? { key: p.key } : {}), ...(p.pageType ? { pageType: p.pageType } : {}), ...(p.title ? { title: p.title } : {}), seo: p.seo ?? null, layoutChain: layoutChain(site, p.layout), stored: p.doc },
+  }
+}
+const entryFound = (site: Site, store: Store, collection: string, slug: string): Found | null => {
+  const e = [...store.entries.values()].find((x) => x.collection === collection && x.slug === slug)
+  if (!e) return null
+  const c = Object.values(site.collections).find((x) => x.name === collection)
+  return {
+    decl: { kind: 'entry', collection },
+    doc: { kind: 'entry', id: String(e.id), slug: e.slug, collection, ...(e.route ? { route: e.route } : {}), seo: e.seo ?? null, layoutChain: layoutChain(site, c?.template?.layout ?? site.defaultLayout), stored: { fields: e.fields, blocks: e.blocks } },
+  }
+}
+
+/**
+ * The reply a platform gives for `target`, built from a store: the document and its layouts as
+ * stored, every media record, page, entry and Single the store holds, the queries and inverse
+ * lookups they ask for, and the tags the read depends on. The fake answers with it, and a site
+ * reading its own defaults goes through it too, so every read is assembled the same way.
+ */
+export function replyFrom(site: Site, store: Store, target: ReplyTarget, manifest: string): Reply {
+  let found: Found | null = null
+  if ('route' in target) {
+    const p = [...store.pages.values()].find((x) => x.route === target.route)
+    if (p) found = pageFound(site, p)
+    else
+      for (const c of Object.values(site.collections)) {
+        const slug = c.route ? routeToRegex(c.route).exec(target.route)?.groups?.slug : undefined
+        if (slug) { found = entryFound(site, store, c.name, slug); break }
+      }
+  } else if ('page' in target) {
+    const p = store.pages.get(target.page)
+    found = p ? pageFound(site, p) : null
+  } else found = entryFound(site, store, target.entry.collection, target.entry.slug)
+  if (!found) return { status: 'missing', manifest, tags: ['site'] }
+
+  const { doc, decl } = found
+  const layouts: Record<string, unknown> = {}
+  const tags = new Set<string>([`${doc.kind}:${doc.id}`])
+  const refs: Ref[] = collectRefs(site.schema, decl, doc.stored, path.doc(doc.kind, doc.id))
+  const layoutDecl: DocumentDecl = { kind: 'layout', blocks: { container: 'u90/zone', allow: Object.keys(site.schema.blocks) } }
+  for (const key of doc.layoutChain) {
+    const l = store.layouts.get(key)
+    if (!l) continue
+    layouts[key] = l.doc
+    tags.add(`layout:${key}`)
+    refs.push(...collectRefs(site.schema, layoutDecl, l.doc, `layout:${key}`))
+  }
+  for (const r of refs) tags.add(tagOf(r))
+  tags.add('site')
+
+  // The queries and inverse lookups the document, its layouts and every stored entry ask for.
+  const lookups: Ref[] = [...refs]
+  for (const e of store.entries.values()) lookups.push(...collectRefs(site.schema, { kind: 'entry', collection: e.collection }, { fields: e.fields, blocks: e.blocks }, path.doc('entry', e.id)))
+  const queries: DocumentReply['queries'] = {}
+  const inverses: DocumentReply['inverses'] = {}
+  for (const r of lookups) {
+    if (r.kind === 'query') queries[queryKey(r.collection, r.query)] ??= runQuery(store, r.collection, r.query as QueryStored)
+    if (r.kind === 'inverse')
+      inverses[inverseKey(r.collection, r.field, r.id)] ??= [...store.entries.values()]
+        .filter((e) => e.collection === r.collection && (Array.isArray(e.fields[r.field]) ? (e.fields[r.field] as unknown[]) : [e.fields[r.field]]).some((v) => String(v) === String(r.id)))
+        .map((e) => e.id)
+  }
+  return {
+    status: 'ok',
+    manifest,
+    document: doc,
+    layouts,
+    singles: Object.fromEntries([...store.singles].map(([k, s]) => [k, { stored: s.doc } satisfies StoredSingle])),
+    media: Object.fromEntries(store.media) as Record<string, MediaRecord>,
+    pages: Object.fromEntries([...store.pages.values()].map((p) => [String(p.id), { id: p.id, route: p.route, title: p.title } satisfies PageRecord])),
+    entries: Object.fromEntries([...store.entries].map(([k, e]) => [k, { id: e.id, slug: e.slug, ...(e.route ? { route: e.route } : {}), fields: e.fields, ...(e.blocks ? { blocks: e.blocks } : {}) } satisfies EntryRecord])),
+    queries,
+    inverses,
+    tags: [...tags],
+  }
+}

package/src/site/store.ts

@@ -0,0 +1,45 @@
+import { entryKey, seed, newId, type DocumentDecl, type EntryRecord, type MediaRecord, type SeedCtx } from '../elements'
+import type { Site } from './types'
+import type { ReplySeo } from './wire'
+
+export type StoredPage = { id: string; slug: string; route: string; layout: string; key?: string; pageType?: string; title: string; doc: any; seo?: ReplySeo }
+export type Store = {
+  pages: Map<string, StoredPage> // by key (code pages) or by id (platform pages)
+  layouts: Map<string, { id: string; parent?: string; doc: any }>
+  singles: Map<string, { doc: { value: unknown } }>
+  entries: Map<string, EntryRecord & { collection: string; seo?: ReplySeo }> // key `${collection}:${id}`
+  media: Map<string, MediaRecord>
+}
+/** `home` → `Home`, `caseStudies` → `Case studies`: a label for a declared page's key, exactly as the platform humanises a page's own key (`src/content/schema.ts`'s `humanise`), so the fake and the platform agree. */
+const humanise = (key: string): string => {
+  const words = key.replace(/([a-z])([A-Z])/g, '$1 $2').replace(/[-_]+/g, ' ').trim().toLowerCase()
+  return words.charAt(0).toUpperCase() + words.slice(1)
+}
+/** Keys are ids; a `{ source }` asset becomes media `seed:<source>` served from the source path. */
+export const seedCtx = (media: Map<string, MediaRecord>): SeedCtx => ({
+  importAsset: async (source) => { const id = `seed:${source}`; media.set(id, { id, url: source, mimeType: '', width: null, height: null, filename: source.split('/').pop() ?? source }); return id },
+  resolvePage: (key) => key,
+  resolveEntry: (collection, key) => `${key}`,
+  newId,
+})
+/** Seeds one entry into the store — a declared seed entry (`seedSite`) or the fake's `addEntry`. Its id is its slug. */
+export async function seedEntry(site: Site, store: Store, ctx: SeedCtx, collection: string, slug: string, fields?: Record<string, unknown>, blocks?: unknown[]): Promise<void> {
+  const c = site.collections[collection]
+  const doc = (await seed(site.schema, { kind: 'entry', collection }, { fields, blocks }, ctx, `entry:${slug}`)) as { fields: Record<string, unknown>; blocks?: unknown[] }
+  store.entries.set(entryKey(collection, slug), { id: slug, collection, slug, route: c?.route?.replace(':slug', slug), fields: doc.fields, blocks: doc.blocks })
+}
+export async function seedSite(site: Site): Promise<Store> {
+  const store: Store = { pages: new Map(), layouts: new Map(), singles: new Map(), entries: new Map(), media: new Map() }
+  const ctx = seedCtx(store.media)
+  for (const [key, l] of Object.entries(site.layouts)) {
+    const decl: DocumentDecl = { kind: 'layout', blocks: { container: 'u90/zone', allow: l.blocks.filter((b) => b !== 'SLOT'), default: l.blocks } }
+    store.layouts.set(key, { id: key, parent: l.parent, doc: await seed(site.schema, decl, undefined, ctx, `layout:${key}`) })
+  }
+  for (const [key, s] of Object.entries(site.schema.singles)) store.singles.set(key, { doc: await seed(site.schema, { kind: 'single', key }, undefined, ctx, `single:${key}`) as any })
+  for (const [key, p] of Object.entries(site.pages)) {
+    const doc = await seed(site.schema, { kind: 'page', blocks: p.blocks }, undefined, ctx, `page:${key}`)
+    store.pages.set(key, { id: key, key, slug: p.route === '/' ? '' : p.route.replace(/^\//, ''), route: p.route, layout: p.layout, title: humanise(key), doc })
+  }
+  for (const c of Object.values(site.collections)) for (const e of c.entries ?? []) await seedEntry(site, store, ctx, c.name, e.slug, e.fields, e.blocks)
+  return store
+}

package/src/site/types.ts

@@ -0,0 +1,75 @@
+import type { KnowledgePolicyV1 } from '../features/contracts/knowledgePolicy'
+import type { ReactNode } from 'react'
+import type { BlockDecl, CollectionDecl, FieldDecl, GroupDecl, LeafDecl, ListDecl, Schema, SingleDecl, ZoneDecl } from '../elements'
+
+/** A wire-format declaration carrying its read type at the type level only. */
+export type Decl<R> = FieldDecl & { readonly __read?: R }
+export type Read<D> = D extends Decl<infer R> ? R : never
+export type Fields = Record<string, Decl<unknown>>
+/**
+ * Flattens an intersection into a single mapped object type. The strict `Equal` check used by
+ * `types.test-d.ts` treats an intersection (`{ _id: string } & Read<D>`) as distinct from the
+ * equivalent plain object literal type, so `list()`'s group-item type and `BlockProps`'s result
+ * are run through this before being handed back.
+ */
+export type Simplify<T> = { [K in keyof T]: T[K] } & {}
+/**
+ * A zone prop arrives rendered. The import is type-only, so `verbatimModuleSyntax` erases it
+ * entirely at build time — `site/` still imports no React at runtime — and `ReactNode` is the
+ * real read type here rather than `unknown`, narrowed no further by `server/render`.
+ */
+export type ZoneNode = ReactNode
+
+export type SingleDef<R = unknown> = { key: string; decl: Decl<R> }
+export type Singles = Record<string, SingleDef>
+/**
+ * An entry a collection starts with: its slug (also the key a seed's `{ $ref: { key } }` names it
+ * by) and seed values for its fields and template blocks. Seeded like any default — the site
+ * renders it without a platform, and the manifest carries it for the platform to seed on pairing.
+ */
+export type EntrySeed = { slug: string; fields?: Record<string, unknown>; blocks?: unknown[] }
+export type CollectionDef<F extends Fields = Fields> = {
+  kind: 'collection'; name: string; label: string; fields: F
+  route?: string; defaultSort?: CollectionDecl['defaultSort']
+  template?: { zone: ZoneDecl; layout?: string }
+  entries?: EntrySeed[]
+}
+export type BlockDef<F extends Fields = Fields, C extends CollectionDef | undefined = CollectionDef | undefined> = {
+  kind: 'block'; name: string; label: string; fields: F; component: unknown; entry?: C
+}
+export type LayoutDef = { kind: 'layout'; default?: boolean; parent?: string; entries: Array<BlockDef | 'SLOT'> }
+export type PageDef = { kind: 'page'; route: string; layout?: string; blocks: ZoneDecl }
+export type PageTypeDef = { kind: 'pageType'; label: string; route: string; layout?: string; blocks: ZoneDecl }
+export type Seo = { titleTemplate?: string; defaultImage?: string; organisation?: { name: string; url?: string; logo?: string } }
+
+export type Site = {
+  knowledge?: KnowledgePolicyV1
+  singles: Singles; collections: Record<string, CollectionDef>
+  layouts: Record<string, { default: boolean; parent?: string; blocks: string[] }>
+  pages: Record<string, { route: string; layout: string; blocks: ZoneDecl }>
+  pageTypes: Record<string, { label: string; route: string; layout: string; blocks: ZoneDecl }>
+  blocks: Record<string, BlockDef>; schema: Schema; seo: Seo; defaultLayout: string
+}
+export type SiteManifest = {
+  knowledge?: KnowledgePolicyV1
+  schema: Schema
+  layouts: Site['layouts']; pages: Site['pages']; pageTypes: Site['pageTypes']
+  /** Each collection's declared seed entries, by collection name; collections that declare none are absent. */
+  entries: Record<string, EntrySeed[]>
+  /** Each collection's entry route pattern and template layout, by collection name, where the code declares them. */
+  collections: Record<string, { route?: string; layout?: string }>
+  routes: string[]; seo: Seo; bridgeVersion: 4; siteKitVersion: string
+  /** Each record's declared order, since jsonb storage loses key order. */
+  order?: { blocks: string[]; collections: string[]; singles: string[]; pages: string[]; pageTypes: string[]; layouts: string[] }
+}
+/**
+ * The `entry` a block declared with `entry:` receives, exactly as `server/render.tsx` builds it: the
+ * entry page's own id, slug and route (from the collection's pattern), and its fields typed from the
+ * collection's declaration. Not `EntryRead`: an entry page's entry has no `collection` or `status`
+ * (finding 21).
+ */
+export type EntryReadOf<C> = C extends CollectionDef<infer F> ? { id: string; slug: string; route?: string; fields: { [K in keyof F]: Read<F[K]> } } : never
+export type BlockProps<B> = B extends BlockDef<infer F, infer C>
+  ? Simplify<{ [K in keyof F]: Read<F[K]> } & (C extends CollectionDef ? { entry: EntryReadOf<C> } : {})>
+  : never
+export type { FieldDecl, LeafDecl, GroupDecl, ListDecl, ZoneDecl, BlockDecl, CollectionDecl, SingleDecl, Schema }

package/src/site/version.ts

@@ -0,0 +1 @@
+export const SITE_KIT_VERSION = '1.6.2'