create-tanqory-theme 0.0.0-stage → 0.2.3

package/templates/nova/scripts/compiler/manifest/manifest-entry.ts

@@ -0,0 +1,386 @@
+/**
+ * Manifest source-of-truth extractor. Loaded through Vite SSR by
+ * `gen-manifest.mjs` so `import.meta.glob` and the ui/ imports resolve against
+ * the SAME files the app registers at runtime.
+ *
+ * Sections come from two places:
+ *   - the new UI's Section Registry + block schemas, through
+ *     `app/platform/manifest-sections.ts` — the same translation the runtime registers,
+ *     so the manifest cannot describe a unit the app does not ship;
+ *   - custom `sections/*.tsx` `defineSection({...})` files (what an AI build
+ *     writes). The folder may be empty or absent. A custom file whose name a
+ *     ui/ unit already owns is shadowed and listed in `warnings`.
+ *
+ * Everything here is pure data extraction: no React render, no DOM. The
+ * section components are replaced with a no-op before anything reads them.
+ */
+import { createHash } from 'node:crypto'
+import { buildCatalog, fieldToAttr, type LegacySettings } from './manifest-sections'
+import { FAMILIES } from '../contracts/index'
+import type { Field, Schema, ThemeDefinition } from '@tanqory/theme-kit'
+import type { SectionDef, AttrSpec } from '@tanqory/theme-kit/runtime'
+import type { SectionGroupDoc } from '@tanqory/theme-kit/contract'
+import {
+  CONTRACT_VERSION,
+  CURRENT_CONTENT_VERSION,
+  groupImpact,
+  resolvePage,
+  roleOf,
+  type GroupedPageDoc,
+} from '@tanqory/theme-kit/contract'
+
+type SectionModule = { default?: SectionDef }
+interface TemplateNode {
+  type?: string
+  id?: string
+  settings?: Record<string, unknown>
+  blocks?: TemplateNode[]
+}
+type TemplateJson = { sections?: TemplateNode[]; groups?: unknown; contentVersion?: number }
+
+// ── the theme being built (Vite resolves a leading '/' against its root) ─────
+const only = <T,>(m: Record<string, unknown>): T => Object.values(m)[0] as T
+const theme = only<{ default: ThemeDefinition }>(import.meta.glob('/theme.config.ts', { eager: true })).default
+const settings = only<{ default: Record<string, unknown> }>(import.meta.glob('/config/settings.json', { eager: true })).default
+const settingsSchema = only<{ default: Record<string, AttrSpec> }>(import.meta.glob('/config/settings.schema.ts', { eager: true })).default
+const pkg = only<{ default: { name?: string; version?: string } }>(import.meta.glob('/package.json', { eager: true })).default
+const legacySettings = (Object.values(import.meta.glob('/.tanqory/legacy-settings.json', { eager: true, import: 'default' }))[0] ?? {}) as LegacySettings
+// Section schema files (src/sections/<Name>/schema.ts). Blocks are NOT
+// discovered from folders: each section declares the block schemas it accepts
+// (defineSection({ blocks })). The glob below only maps a declared schema back
+// to its file, for the entry's source hash.
+const schemaMods = import.meta.glob<Record<string, unknown>>('/src/sections/*/schema.ts', { eager: true })
+const blockFiles = import.meta.glob<Record<string, unknown>>('/src/**/blocks/*.tsx', { eager: true })
+// Source text of every theme file an entry can come from, so each entry carries
+// the hash of its source: studio-api compares it with the file it sees and
+// knows whether the entry is current or stale.
+const themeSources = import.meta.glob<string>(['/src/**/*.ts', '/src/**/*.tsx'], { eager: true, query: '?raw', import: 'default' })
+// Custom sections (may be empty / missing — a glob that matches nothing is {}).
+const customMods = import.meta.glob<SectionModule>('/sections/*.tsx', { eager: true })
+const customSources = import.meta.glob<string>('/sections/*.tsx', { eager: true, query: '?raw', import: 'default' })
+const templateMods = import.meta.glob<TemplateJson>('/templates/*.json', { eager: true })
+const groupMods = import.meta.glob<{ default?: SectionGroupDoc }>('/groups/*.json', { eager: true })
+
+const isSchema = (v: unknown, kind: 'section' | 'block'): v is Schema =>
+  Boolean(v && typeof v === 'object' && (v as Schema).kind === kind && typeof (v as Schema).name === 'string' && (v as Schema).fields)
+
+/** Every block schema the theme's sections declare (deduplicated), with its file. */
+function themeBlocks(): { schema: Schema; source: string }[] {
+  const fileOf = new Map<unknown, string>()
+  for (const [path, mod] of Object.entries(blockFiles)) for (const v of Object.values(mod)) if (isSchema(v, 'block')) fileOf.set(v, path.replace(/^\//, ''))
+  const seen = new Set<Schema>()
+  const out: { schema: Schema; source: string }[] = []
+  for (const section of theme.sections)
+    for (const schema of section.blocks ?? []) {
+      if (seen.has(schema)) continue
+      seen.add(schema)
+      out.push({ schema, source: fileOf.get(schema) ?? '' })
+    }
+  return out
+}
+
+/** section id → the file that declares its schema. */
+function sectionSources(): Record<string, string> {
+  const out: Record<string, string> = {}
+  for (const [path, mod] of Object.entries(schemaMods)) for (const v of Object.values(mod)) if (isSchema(v, 'section')) out[v.name] = path.replace(/^\//, '')
+  return out
+}
+
+/** The shared settings as the platform's AttrSpecs, labelled from the contracts. */
+function sharedAttributeSpecs(): Record<string, AttrSpec> {
+  const shared = theme.sharedSettings
+  if (!shared) return {}
+  const rows = Object.values(FAMILIES).flatMap((f) => f.shared ?? [])
+  const out: Record<string, AttrSpec> = {}
+  for (const [key, f] of Object.entries(shared.fields)) {
+    const { type, ...rest } = fieldToAttr(key, f as Field, rows.find((r) => r.name === key))
+    out[key] = { type, group: shared.groups?.[key] ?? 'General', ...rest }
+  }
+  return out
+}
+
+function serializeAttr(spec: AttrSpec): Record<string, unknown> {
+  const out: Record<string, unknown> = {}
+  const entries: Array<[string, unknown]> = Object.entries(spec)
+  for (const [k, v] of entries) {
+    if (typeof v === 'function') continue
+    out[k] = v
+  }
+  return out
+}
+
+/** Presets as data: nested blocks and their settings, nothing executable. */
+function serializePresets(def: SectionDef) {
+  return (def.presets ?? []).map((p) => ({
+    ...(p.name ? { name: p.name } : {}),
+    settings: p.settings ?? {},
+    blocks: (p.blocks ?? []).map((b) => ({ type: b.type, settings: b.settings ?? {}, ...(b.blocks ? { blocks: b.blocks } : {}) })),
+  }))
+}
+
+/** sha256 of a file's bytes, shortened — the same shape studio-api uses for a revision. */
+function sourceHash(text: string): string {
+  return createHash('sha256').update(text).digest('hex').slice(0, 32)
+}
+
+function serializeSection(def: SectionDef, parentsOf: Map<string, string[]>, source?: { path: string; text: string }) {
+  const attributes: Record<string, unknown> = {}
+  for (const [key, spec] of Object.entries(def.attributes ?? {})) {
+    attributes[key] = serializeAttr(spec as AttrSpec)
+  }
+  const role = roleOf(def)
+  // Placement is derived from the same source the runtime reads: a block's
+  // parents are the sections whose `allowedBlocks` list it; a layout unit's
+  // area is the slot it declares. Never a second hand-maintained list.
+  const placement: Record<string, unknown> = { ...(def.placement ?? {}) }
+  if (role === 'block' && !placement.parents) placement.parents = parentsOf.get(def.name) ?? []
+  if (role === 'layout' && !placement.areas && def.area) placement.areas = [def.area]
+  return {
+    name: def.name,
+    title: def.title,
+    ...(def.description ? { description: def.description } : {}),
+    // Provenance: which file this entry was generated from and its hash at
+    // generation time. Lets a consumer tell a stale entry from a current one
+    // instead of trusting the manifest blindly.
+    ...(source ? { source: source.path, sourceHash: sourceHash(source.text) } : {}),
+    category: def.category ?? 'uncategorized',
+    icon: def.icon ?? null,
+    // What kind of unit this is and where it may go — the placement contract.
+    // `category` is the inserter's display grouping, not a rule.
+    role,
+    ...(def.area ? { area: def.area } : {}),
+    placement,
+    requiresContext: def.requiresContext ?? [],
+    // The controls the editor auto-renders and the AI must fill to place this
+    // section — the section's public contract.
+    attributes,
+    // What may nest inside it (empty = a leaf section).
+    allowedBlocks: def.allowedBlocks ?? [],
+    // Starting compositions, nested blocks included, so an inserter or an AI
+    // can seed a block-composed section without reading the source.
+    presets: serializePresets(def),
+  }
+}
+
+function fileStem(path: string): string {
+  return path.split('/').pop()!.replace(/\.[^.]+$/, '')
+}
+
+export function buildManifest() {
+  const catalog = buildCatalog({ theme, blocks: themeBlocks(), sectionSources: sectionSources(), legacySettings })
+  const themeNames = new Set(catalog.map((e) => e.def.name))
+  const sourceOf = (path: string | undefined) => {
+    if (!path) return undefined
+    const text = themeSources[`/${path}`]
+    if (typeof text !== 'string') throw new Error(`[theme-compiler] ${path} is not in the theme`)
+    return { path, text }
+  }
+
+  const custom = Object.entries(customMods)
+    .map(([path, m]) => ({ def: m.default, source: { path: path.replace(/^\//, ''), text: customSources[path] ?? '' } }))
+    .filter((x): x is { def: SectionDef; source: { path: string; text: string } } => !!x.def && typeof x.def.name === 'string')
+  // A custom file with a theme section's name overrides it at runtime (it
+  // registers last); the manifest lists the name once, as the theme's.
+  const shadowedCustomSections = custom
+    .filter((x) => themeNames.has(x.def.name))
+    .map((x) => ({ name: x.def.name, source: x.source.path }))
+    .sort((a, b) => a.source.localeCompare(b.source))
+
+  const defsWithSource = [
+    ...catalog.map((e) => ({ def: e.def as SectionDef, source: sourceOf(e.source) })),
+    ...custom.filter((x) => !themeNames.has(x.def.name)),
+  ]
+  const defs = defsWithSource.map((x) => x.def)
+  const parentsOf = new Map<string, string[]>()
+  for (const d of defs) for (const b of d.allowedBlocks ?? []) parentsOf.set(b, [...(parentsOf.get(b) ?? []), d.name].sort())
+  const sections = defsWithSource.map((x) => serializeSection(x.def, parentsOf, x.source)).sort((a, b) => a.name.localeCompare(b.name))
+
+  // The shared props, as data. A consumer that reads a custom section's .tsx
+  // itself (studio-api, for a file newer than this manifest) applies these the
+  // way `withShared` does: shared first, the section's own keys win, `omit`
+  // and the content slots left out.
+  const sharedAttributes: Record<string, unknown> = {}
+  for (const [key, spec] of Object.entries(sharedAttributeSpecs())) sharedAttributes[key] = serializeAttr(spec)
+
+  // Shared header/footer groups, and which templates each one reaches.
+  const groupDocs: Record<string, SectionGroupDoc> = {}
+  for (const [path, mod] of Object.entries(groupMods)) if (mod.default) groupDocs[fileStem(path)] = mod.default
+  const templateDocs: Record<string, GroupedPageDoc> = {}
+  for (const [path, json] of Object.entries(templateMods)) templateDocs[fileStem(path)] = json as GroupedPageDoc
+  const groups = Object.entries(groupDocs)
+    .map(([name, doc]) => ({
+      name,
+      type: doc.type,
+      sectionTypes: [...new Set(doc.sections.map((s) => s.type))].sort(),
+      sectionIds: doc.sections.map((s) => s.id).filter(Boolean),
+      // Every template that binds this group — the scope of an edit to it.
+      usedBy: groupImpact(name, templateDocs),
+    }))
+    .sort((a, b) => a.name.localeCompare(b.name))
+
+  const templates = Object.entries(templateMods)
+    .map(([path, json]) => {
+      const resolved = resolvePage(json as GroupedPageDoc, groupDocs)
+      const secs = Array.isArray(json.sections) ? json.sections : []
+      const sectionTypes = [...new Set(secs.map((s) => s.type).filter(Boolean))] as string[]
+      const slot = (k: 'header' | 'footer') => {
+        const r = resolved.slots[k]
+        return r.mode === 'ref' ? { mode: 'ref' as const, group: r.group } : { mode: r.mode }
+      }
+      return {
+        name: fileStem(path),
+        contentVersion: json.contentVersion ?? 1,
+        sectionCount: secs.length,
+        sectionTypes: sectionTypes.sort(),
+        // How the page fills its shared slots: `ref` (shared group), `override`
+        // (its own copy, on purpose), `inline` (legacy copy), `none`.
+        groups: { header: slot('header'), footer: slot('footer') },
+      }
+    })
+    .sort((a, b) => a.name.localeCompare(b.name))
+
+  // A template that binds a group this theme does not ship renders an empty
+  // header — as loud a failure as a dangling section ref.
+  const danglingGroupRefs = Object.entries(templateDocs)
+    .flatMap(([name, doc]) => resolvePage(doc, groupDocs).missingGroups.map((group) => ({ template: name, group })))
+
+  // The page layout lives in the theme's definition now, not in layouts/*.tsx files.
+  const layouts: string[] = []
+
+  // Every section type a template references must resolve to a known section —
+  // a mismatch means a template points at a section the theme no longer ships.
+  const known = new Set(sections.map((s) => s.name))
+  const danglingTemplateRefs = templates
+    .flatMap((t) => t.sectionTypes.map((type) => ({ template: t.name, type })))
+    .filter((ref) => !known.has(ref.type))
+
+  // Two more classes of template drift:
+  //
+  //   unknownTemplateSettings — a template sets a key the section does not
+  //     declare. The value is dropped on render and the editor never shows a
+  //     control for it, so the template appears to configure something it does
+  //     not.
+  //   disallowedTemplateBlocks — a template nests a block the parent section's
+  //     `allowedBlocks` does not permit. The editor would refuse the same
+  //     composition the theme ships.
+  const byName = new Map(sections.map((s) => [s.name, s]))
+  const unknownTemplateSettings: Array<{ template: string; type: string; setting: string }> = []
+  const disallowedTemplateBlocks: Array<{ template: string; parent: string; type: string }> = []
+
+  function validateNodes(template: string, nodes: TemplateNode[] | undefined, parent?: string): void {
+    for (const node of nodes ?? []) {
+      if (!node?.type) continue
+      const def = byName.get(node.type)
+      if (parent) {
+        const parentDef = byName.get(parent)
+        if (parentDef && !parentDef.allowedBlocks.includes(node.type)) {
+          disallowedTemplateBlocks.push({ template, parent, type: node.type })
+        }
+      }
+      if (def) {
+        for (const key of Object.keys(node.settings ?? {})) {
+          if (!(key in def.attributes)) {
+            unknownTemplateSettings.push({ template, type: node.type, setting: key })
+          }
+        }
+      }
+      validateNodes(template, node.blocks, node.type)
+    }
+  }
+
+  for (const [path, json] of Object.entries(templateMods)) {
+    validateNodes(fileStem(path), Array.isArray(json.sections) ? json.sections : undefined)
+  }
+
+  // Group sections are content too — a group that sets a setting its section
+  // does not declare is as broken as a template that does.
+  for (const [name, doc] of Object.entries(groupDocs)) {
+    validateNodes(`groups/${name}`, doc.sections as TemplateNode[])
+  }
+
+  const categories: Record<string, number> = {}
+  for (const s of sections) categories[s.category] = (categories[s.category] ?? 0) + 1
+  const roles: Record<string, number> = {}
+  for (const s of sections) roles[s.role] = (roles[s.role] ?? 0) + 1
+
+  // Theme settings, as a typed+grouped schema (settings.schema.ts) plus the
+  // current values (settings.json). Serialize each spec the same way section
+  // attributes are serialized (drop functions), and group for the editor panel.
+  const schemaKeys = Object.keys(settingsSchema)
+  const settingGroups: Record<string, Array<{ key: string } & Record<string, unknown>>> = {}
+  for (const [key, spec] of Object.entries(settingsSchema)) {
+    const s = serializeAttr(spec as AttrSpec)
+    const group = (s.group as string) ?? 'General'
+    ;(settingGroups[group] ??= []).push({ key, ...s })
+  }
+
+  const valueKeys = Object.keys(settings as Record<string, unknown>)
+  // A key with a value but no schema entry is invisible to the editor; a key in
+  // the schema with no value falls back to its declared default.
+  const settingsUndeclared = valueKeys.filter((k) => !schemaKeys.includes(k))
+  // A hidden legacy setting (config/legacy-settings.json) has no value on purpose: it only keeps saved values valid.
+  const isLegacy = (k: string) => (settingsSchema[k] as { visible_if?: string } | undefined)?.visible_if === '{{ false }}'
+  const settingsMissingValue = schemaKeys.filter((k) => !valueKeys.includes(k) && !isLegacy(k))
+
+  return {
+    $schema: 'https://tanqory.com/schemas/theme-manifest/v1',
+    theme: {
+      name: pkg.name ?? theme.name,
+      version: (pkg as { version?: string }).version ?? '0.0.0',
+    },
+    // Provenance so a reader knows this is generated, not hand-authored.
+    generatedFrom: [
+      'theme.config.ts',
+      'src/sections/*/schema.ts',
+      ...(custom.length ? ['sections/*.tsx'] : []),
+      'templates/*.json',
+      'groups/*.json',
+      'config/settings.schema.ts',
+      'config/settings.json',
+    ],
+    // Which contract this manifest speaks — a consumer compares before trusting it.
+    contract: { version: CONTRACT_VERSION, contentVersion: CURRENT_CONTENT_VERSION },
+    // `sections` below is the platform catalog: every unit the editor knows,
+    // told apart by `role`. In theme terms:
+    //   Section  = what a merchant places — role 'section', plus the header /
+    //              footer zone sections the platform marks role 'layout'
+    //   Block    = role 'block': only ever nested inside a section
+    //   Layout   = the page shell (theme.config Layout) — never in this list
+    stats: {
+      units: sections.length,
+      sections: (roles.section ?? 0) + (roles.layout ?? 0),
+      headerFooterSections: roles.layout ?? 0,
+      blocks: roles.block ?? 0,
+      blockSchemas: themeBlocks().length,
+      templates: templates.length,
+      groups: groups.length,
+      layouts: layouts.length,
+      settings: schemaKeys.length,
+      categories,
+      roles,
+    },
+    sections,
+    sharedAttributes,
+    contentSlots: [...(theme.sharedSettings?.contentSlots ?? [])],
+    templates,
+    groups,
+    layouts,
+    // Typed, grouped theme-settings schema (settings.schema.ts) — what the
+    // studio's Theme panel renders and the AI generator reads. Groups keep the
+    // order settings.schema.ts declares them in.
+    settingsSchema: Object.entries(settingGroups).map(([group, items]) => ({ group, items })),
+    // Current values (settings.json).
+    settings: settings as Record<string, unknown>,
+    // Non-fatal integrity signals for the reader / the conformance test.
+    warnings: {
+      danglingTemplateRefs,
+      danglingGroupRefs,
+      unknownTemplateSettings,
+      disallowedTemplateBlocks,
+      settingsUndeclared,
+      settingsMissingValue,
+      // Custom sections/*.tsx files whose name a ui/ unit owns — not in the catalog.
+      shadowedCustomSections,
+    },
+  }
+}

package/templates/nova/scripts/compiler/manifest/manifest-sections.ts

@@ -0,0 +1,247 @@
+/**
+ * A theme's sections and blocks, expressed as the platform's `SectionDef`
+ * shape — what `theme.manifest.json` publishes and what the editor, studio-api's
+ * save validator and the AI read.
+ *
+ * The theme's schemas are the source of truth for ids, controls, defaults and
+ * option values; this only TRANSLATES them:
+ *
+ *   field.control          → AttrSpec.type (the two vocabularies line up 1:1)
+ *   field.default          → AttrSpec.default ('' is omitted: absent = empty)
+ *   contract row label     → AttrSpec.label (fallback: the humanised key)
+ *   field.options          → AttrSpec.options [{ value, label }] with the
+ *                            contract's option labels (fallback: humanised id)
+ *   field.legacy (options) → appended to options, labelled "… (legacy)", so a
+ *                            saved legacy value still validates
+ *   field.legacyHidden     → declared (saved values validate) but never shown:
+ *                            `visible_if: '{{ false }}'`, no default
+ *   range / number         → min / max / step
+ *
+ * Wording and placement (title, description, icon, requiresContext) come from
+ * each section's definition and each block's schema; a block's parents are
+ * derived from the sections' block lists.
+ */
+import type { AttrSpec, ContentNode, SectionDef } from '@tanqory/theme-kit/runtime'
+import type { Field, Schema, SectionPreset, ThemeDefinition } from '@tanqory/theme-kit'
+import { FAMILIES, contractBlock, contractSection, type ContractRow, type FamilyId } from '../contracts/index'
+
+/** Settings stores saved that a section no longer declares (.tanqory/legacy-settings.json). */
+export type LegacySettings = Readonly<Record<string, Readonly<Record<string, AttrSpec>>>>
+
+export interface CatalogInput {
+  theme: ThemeDefinition
+  /** Every block schema the theme implements, with the file that declares it. */
+  blocks: readonly { schema: Schema; source: string }[]
+  /** The file that declares each section's schema (section id → theme path). */
+  sectionSources: Readonly<Record<string, string>>
+  legacySettings: LegacySettings
+}
+
+// ── attribute conversion ───────────────────────────────────────────────────
+
+/** 'buttonLabel' → 'Button label', 'text-first' → 'Text first'. */
+export function humanise(id: string): string {
+  const words = id
+    .replace(/([a-z0-9])([A-Z])/g, '$1 $2')
+    .replace(/[-_]+/g, ' ')
+    .trim()
+    .toLowerCase()
+  return words ? words[0]!.toUpperCase() + words.slice(1) : id
+}
+
+/** Shown on a legacy-hidden setting to a reader of the raw schema (the AI). */
+export const LEGACY_HIDDEN_INFO = 'Legacy setting: saved values keep rendering; not offered for new content.'
+/** Always false, however `visible_if` is read — the editor never shows it. */
+export const LEGACY_HIDDEN_VISIBLE_IF = '{{ false }}'
+
+function optionLabel(row: ContractRow | undefined, value: string): string {
+  if (row) {
+    const i = row.options.indexOf(value)
+    if (i >= 0 && row.optionLabels[i]) return row.optionLabels[i]!
+    const j = row.legacyOptions.indexOf(value)
+    if (j >= 0 && row.legacyOptionLabels[j]) return row.legacyOptionLabels[j]!
+  }
+  return humanise(value)
+}
+
+/** 'Background colour' → 'Background colour (legacy)', never twice. */
+const withLegacyMark = (label: string) => (/\blegacy\b/i.test(label) ? label : `${label} (legacy)`)
+
+/** One ui/ schema field → the platform's AttrSpec. */
+export function fieldToAttr(key: string, f: Field, row: ContractRow | undefined): AttrSpec {
+  const label = row?.label || humanise(key)
+  const spec: AttrSpec = { type: f.control, label }
+  if (f.legacyHidden) {
+    // Declared so a saved value still passes the save validator (an undeclared
+    // key is `unknown_setting`, an error); hidden so it is never a control.
+    spec.label = withLegacyMark(label)
+    spec.info = LEGACY_HIDDEN_INFO
+    spec.visible_if = LEGACY_HIDDEN_VISIBLE_IF
+  } else if (f.default !== '') {
+    spec.default = f.default
+  }
+  if (f.control === 'select') {
+    const opts = f.options.map((value) => ({ value, label: optionLabel(row, value) }))
+    // A saved value that is no longer an option still validates; the ui
+    // adapter renders it as the option it maps to.
+    for (const [value, to] of Object.entries(f.legacy ?? {})) {
+      if (f.options.includes(value)) continue
+      const fromContract = row?.legacyOptions.includes(value) ? optionLabel(row, value) : optionLabel(row, to)
+      opts.push({ value, label: withLegacyMark(fromContract) })
+    }
+    spec.options = opts
+  }
+  if (f.control === 'range' || f.control === 'number') {
+    spec.min = f.min
+    spec.max = f.max
+    spec.step = f.step
+  }
+  return spec
+}
+
+function sectionRow(family: FamilyId, section: string, key: string): ContractRow | undefined {
+  return contractSection(family, section)?.rows.find((r) => r.name === key) ?? FAMILIES[family]?.shared.find((r) => r.name === key)
+}
+
+function blockRow(family: FamilyId, block: string, parents: readonly string[], key: string, legacyNames: readonly string[] = []): ContractRow | undefined {
+  for (const name of [block, ...legacyNames])
+    for (const parent of [...parents, undefined]) {
+      const row = contractBlock(name, parent)?.block.rows.find((r) => r.name === key)
+      if (row) return row
+    }
+  // A section-as-block (12A newsletter has no rows of its own) is worded like the section it was named after.
+  for (const name of legacyNames)
+    for (const fam of Object.keys(FAMILIES) as FamilyId[]) {
+      const row = contractSection(fam, name)?.rows.find((r) => r.name === key)
+      if (row) return row
+    }
+  return FAMILIES[family]?.shared.find((r) => r.name === key)
+}
+
+/** Merge another declaration's attributes in: first wins, select options union. */
+function mergeAttrs(into: Record<string, AttrSpec>, extra: Record<string, AttrSpec>): void {
+  for (const [key, spec] of Object.entries(extra)) {
+    const have = into[key]
+    if (!have) {
+      into[key] = spec
+      continue
+    }
+    if (have.options && spec.options) {
+      const values = new Set(have.options.map((o) => o.value))
+      for (const o of spec.options) if (!values.has(o.value)) have.options.push(o)
+    }
+  }
+}
+
+function presetsOf(presets: readonly SectionPreset[]): SectionDef['presets'] {
+  return presets.map((p) => ({
+    name: p.label || p.name,
+    settings: { ...p.settings },
+    blocks: (p.blocks ?? []).map((b): ContentNode => ({ type: b.type, settings: { ...(b.settings ?? {}) } })),
+  }))
+}
+
+/**
+ * Settings the previous theme declared that the new sections do not have.
+ * Stores saved them, and the save validator rejects an undeclared key, so each
+ * stays declared — hidden, with no default — and the section ignores it.
+ * Generated once from the last manifest before the switch; append-only.
+ */
+function legacyAttrs(legacy: LegacySettings, section: string): Record<string, AttrSpec> {
+  const out: Record<string, AttrSpec> = {}
+  for (const [key, old] of Object.entries(legacy[section] ?? {})) {
+    out[key] = { ...old, label: withLegacyMark(humanise(key)), info: LEGACY_HIDDEN_INFO, visible_if: LEGACY_HIDDEN_VISIBLE_IF }
+  }
+  return out
+}
+
+// ── the defs ───────────────────────────────────────────────────────────────
+
+export interface CatalogEntry {
+  def: Omit<SectionDef, 'component'>
+  /** Theme path of the file that declares it (the manifest stamps its hash). */
+  source?: string
+}
+
+/**
+ * One entry per theme section, then one per block type not already a section
+ * (a type that is both — newsletter — carries both schemas' fields).
+ */
+export function buildCatalog(input: CatalogInput): CatalogEntry[] {
+  const { theme, legacySettings } = input
+  // Block schemas grouped by persisted name; the largest declaration is primary.
+  const blocks = new Map<string, { schema: Schema; source: string }[]>()
+  for (const b of input.blocks) blocks.set(b.schema.name, [...(blocks.get(b.schema.name) ?? []), b])
+  for (const [name, list] of blocks) blocks.set(name, [...list].sort((a, b) => Object.keys(b.schema.fields).length - Object.keys(a.schema.fields).length))
+
+  // A section may host a legacy block: saved pages still hold it, and the save
+  // validator would reject the nesting if allowedBlocks left it out.
+  const allowedOf = (s: ThemeDefinition['sections'][number]) => [...new Set([...(s.schema.blocks ?? []), ...(s.schema.legacyBlocks ?? [])])]
+  const parentsOf = new Map<string, string[]>()
+  for (const s of theme.sections) for (const b of allowedOf(s)) parentsOf.set(b, [...(parentsOf.get(b) ?? []), s.id].sort())
+
+  const blockAttrs = (name: string): Record<string, AttrSpec> => {
+    const attrs: Record<string, AttrSpec> = {}
+    const parents = parentsOf.get(name) ?? []
+    for (const { schema } of blocks.get(name) ?? []) {
+      const own: Record<string, AttrSpec> = {}
+      for (const [key, f] of Object.entries(schema.fields)) own[key] = fieldToAttr(key, f as Field, blockRow(schema.family as FamilyId, name, parents, key, schema.legacyNames))
+      mergeAttrs(attrs, own)
+    }
+    return attrs
+  }
+
+  const out: CatalogEntry[] = []
+  for (const s of theme.sections) {
+    const family = s.schema.family as FamilyId
+    const attributes: Record<string, AttrSpec> = {}
+    for (const [key, f] of Object.entries(s.schema.fields)) attributes[key] = fieldToAttr(key, f as Field, sectionRow(family, s.id, key))
+    if (blocks.has(s.id)) mergeAttrs(attributes, blockAttrs(s.id))
+    // A block renamed away from this section's name: saved content still nests
+    // it under the old name, which now resolves to this entry — keep its fields.
+    for (const [name, list] of blocks) if (list.some((b) => b.schema.legacyNames?.includes(s.id))) mergeAttrs(attributes, blockAttrs(name))
+    mergeAttrs(attributes, legacyAttrs(legacySettings, s.id))
+    const chrome = s.zone === 'header' || s.zone === 'footer'
+    out.push({
+      source: input.sectionSources[s.id],
+      def: {
+        name: s.id,
+        title: s.title ?? contractSection(family, s.id)?.label ?? humanise(s.id),
+        description: s.description ?? '',
+        category: s.category,
+        ...(s.icon ? { icon: s.icon } : {}),
+        role: chrome ? 'layout' : 'section',
+        ...(chrome ? { area: s.zone as 'header' | 'footer' } : {}),
+        placement: chrome ? { areas: [s.zone as 'header' | 'footer'] } : {},
+        requiresContext: (s.requiresContext ?? []) as SectionDef['requiresContext'],
+        attributes,
+        allowedBlocks: allowedOf(s),
+        presets: presetsOf(s.presets ?? []),
+      },
+    })
+  }
+
+  const sectionIds = new Set(theme.sections.map((s) => s.id))
+  for (const [name, list] of blocks) {
+    if (sectionIds.has(name)) continue
+    const primary = list[0]!.schema
+    const contract = [name, ...(primary.legacyNames ?? [])].map((n) => contractBlock(n, (parentsOf.get(name) ?? [])[0]) ?? contractBlock(n)).find(Boolean)
+    out.push({
+      source: list[0]!.source,
+      def: {
+        name,
+        title: primary.title ?? contract?.block.label ?? humanise(name),
+        description: primary.description ?? '',
+        category: 'block',
+        ...(primary.icon ? { icon: primary.icon } : {}),
+        role: 'block',
+        placement: { parents: parentsOf.get(name) ?? [] },
+        requiresContext: (primary.requiresContext ?? []) as SectionDef['requiresContext'],
+        attributes: blockAttrs(name),
+        allowedBlocks: [],
+        presets: [],
+      },
+    })
+  }
+  return out
+}