create-tanqory-theme 0.0.0-stage → 0.2.3

package/templates/nova/scripts/compiler/contracts/index.ts

@@ -0,0 +1,125 @@
+/**
+ * A theme's approved contracts — the frozen persisted ids (sections, blocks,
+ * settings, options) with their editor labels and presets. Kept by the theme
+ * as locks in .tanqory/contracts/, written by `tanqory-theme contracts`
+ * (./extract.mjs) with their hashes in LOCK.json; never hand-edited.
+ */
+// The theme's frozen contracts (.tanqory/contracts/<theme>-<family>.json), read
+// from the theme being built — Vite resolves a leading '/' against its root.
+// LOCK.json sits beside them; it is not a family and the filter below skips it.
+const LOCKS = import.meta.glob('/.tanqory/contracts/*.json', { eager: true, import: 'default' }) as Record<string, unknown>
+
+export type ContractStatus =
+  | 'EXISTING'
+  | 'CHANGED'
+  | 'NEW'
+  | 'LEGACY-HIDDEN'
+  | 'NEEDS NEW FIELD TYPE'
+  | 'NEEDS NEW DATA SOURCE'
+  | 'DATA REQUIREMENT'
+  | 'PROPOSED'
+  | (string & {})
+
+export interface ContractRow {
+  name: string
+  label: string
+  control: string
+  options: string[]
+  optionLabels: string[]
+  legacyOptions: string[]
+  legacyOptionLabels: string[]
+  def: string | number | boolean | null
+  min: number | null
+  max: number | null
+  step: number | null
+  resp: string
+  dep: string
+  desc: string
+  status: ContractStatus
+}
+
+export interface ContractSection {
+  name: string
+  label: string
+  status: ContractStatus
+  rows: ContractRow[]
+}
+
+export interface ContractBlock {
+  name: string
+  label: string
+  parents: string[]
+  min: number
+  recommended: number
+  max: number
+  status: ContractStatus
+  resp: string
+  empty: string
+  summary: string
+  rows: ContractRow[]
+}
+
+export interface ContractPreset {
+  name: string
+  label: string
+  section: string
+  purpose: string
+  settings: Record<string, unknown>
+  blocks: { type: string; settings: Record<string, unknown> }[]
+  content: string
+}
+
+export type Applicability = 'APPLIES' | 'NOT APPLICABLE' | 'OVERRIDDEN BY SECTION-SPECIFIC BEHAVIOR' | (string & {})
+
+export interface ContractFamily {
+  sections: ContractSection[]
+  blocks: ContractBlock[]
+  presets: ContractPreset[]
+  shared: ContractRow[]
+  sharedApplicability: Record<string, string>[]
+  globals: ContractRow[]
+  ai: Record<string, unknown>[]
+  conflicts: string[]
+  placeholders?: { id: string; use: string; viewBox: string; aspect: string; tokens: string[]; density: string; a11y: string }[]
+  stateFamilies?: string[]
+}
+
+/**
+ * Every section contract family the theme ships a lock for, by family id (the
+ * `<family>` in the file name). Other locks (design tokens, page specs) share
+ * the folder and are skipped: a family is one that declares sections.
+ */
+export const FAMILIES: Readonly<Record<string, ContractFamily>> = Object.fromEntries(
+  Object.entries(LOCKS)
+    .filter(([, v]) => Array.isArray((v as Partial<ContractFamily>)?.sections) && Array.isArray((v as Partial<ContractFamily>)?.blocks))
+    .map(([k, v]) => [k.match(/-([^-/]+)\.json$/)?.[1] ?? k, v as ContractFamily]),
+)
+
+export type FamilyId = keyof typeof FAMILIES
+
+export function contractSection(family: FamilyId, name: string): ContractSection | undefined {
+  return FAMILIES[family].sections.find((s) => s.name === name)
+}
+
+/**
+ * Blocks are defined once in the family that owns them, but a block may list
+ * parents in other families (heading is a 12D block that group, a 12A
+ * section, accepts). Search every family.
+ */
+export function contractBlock(name: string, parent?: string): { family: FamilyId; block: ContractBlock } | undefined {
+  for (const [family, f] of Object.entries(FAMILIES) as [FamilyId, ContractFamily][]) {
+    const block = f.blocks.find((b) => b.name === name && (!parent || b.parents.includes(parent)))
+    if (block) return { family, block }
+  }
+  return undefined
+}
+
+export function presetsFor(section: string): ContractPreset[] {
+  return Object.values(FAMILIES).flatMap((f) => f.presets.filter((p) => p.section === section))
+}
+
+/** The contract row for a setting, falling back to the family's shared row. */
+export function contractRow(family: FamilyId, owner: { kind: 'section' | 'block'; name: string; parent?: string }, key: string): ContractRow | undefined {
+  if (owner.kind === 'block') return contractBlock(owner.name, owner.parent)?.block.rows.find((r) => r.name === key)
+  return contractSection(family, owner.name)?.rows.find((r) => r.name === key) ?? FAMILIES[family].shared.find((r) => r.name === key)
+}

package/templates/nova/scripts/compiler/contracts/validate.ts

@@ -0,0 +1,347 @@
+/**
+ * Design → Code contract validation.
+ *
+ * Compares the code's schemas (what components, the adapter and Storybook use)
+ * with the approved contracts (generated/*.json). Every approved setting must
+ * be represented by the component API or intentionally handled by the adapter.
+ *
+ * Issue codes — each is a way the two have drifted apart:
+ *
+ *   missing-section      an in-scope contract section has no schema
+ *   missing-block        a contract block an in-scope section accepts has no schema
+ *   missing-prop         a contract row has no field
+ *   extra-prop           a field has no contract row and no stated `extension` reason
+ *   control-mismatch     the field's control differs from the contract's
+ *   unknown-option       the field offers an option the contract does not have
+ *   missing-option       the contract offers an option the field does not have
+ *   invalid-default      the field default differs from the contract default
+ *   invalid-range        range min/max/step differ from the contract
+ *   invalid-preset       a preset names an unknown setting, or a value that is not an option
+ *   invalid-block        a preset / parent names a block the section does not accept
+ *   duplicated-setting   two visible fields control the same semantic
+ *   unsupported-legacy   a LEGACY-HIDDEN row / legacy option is not handled by the field
+ *   shared-applicability a shared setting's APPLIES / NOT APPLICABLE status is not honoured
+ */
+import { FAMILIES, contractBlock, presetsFor, type ContractRow, type FamilyId } from './index'
+import type { Field, Schema } from '@tanqory/theme-kit'
+
+export type IssueCode =
+  | 'missing-section'
+  | 'missing-block'
+  | 'missing-prop'
+  | 'extra-prop'
+  | 'control-mismatch'
+  | 'unknown-option'
+  | 'missing-option'
+  | 'invalid-default'
+  | 'invalid-range'
+  | 'invalid-preset'
+  | 'invalid-block'
+  | 'duplicated-setting'
+  | 'unsupported-legacy'
+  | 'shared-applicability'
+
+export interface ContractIssue {
+  readonly code: IssueCode
+  /** `section:header` · `block:heading@group` · `preset:footer-full` */
+  readonly where: string
+  readonly key?: string
+  readonly message: string
+}
+
+/**
+ * A difference the design package itself flags as open, recorded with the
+ * reason it is accepted. The validator reports these as `accepted`, not as
+ * failures, so every exception is visible and reviewed.
+ */
+export interface AcceptedDeviation {
+  readonly code: IssueCode
+  readonly where: string
+  readonly key?: string
+  readonly reason: string
+}
+
+export interface ValidationReport {
+  readonly issues: readonly ContractIssue[]
+  readonly accepted: readonly (ContractIssue & { reason: string })[]
+  /** Rows checked, for the report header. */
+  readonly checked: { sections: number; blocks: number; rows: number; presets: number }
+}
+
+/**
+ * Contract controls that the code carries with a different (but equivalent)
+ * control. Only the vocabulary gap is mapped here — never a semantic change.
+ */
+const CONTROL_EQUIVALENTS: Record<string, readonly string[]> = {
+  text_alignment: ['select'],
+}
+
+function sameControl(contract: string, code: string): boolean {
+  return contract === code || (CONTROL_EQUIVALENTS[contract]?.includes(code) ?? false)
+}
+
+function eqDefault(row: ContractRow, f: Field): boolean {
+  const d = row.def
+  if (f.control === 'boolean') return (d === true || d === 'true') === f.default
+  if (f.control === 'range' || f.control === 'number') return d == null ? true : Number(d) === f.default
+  if (f.control === 'select') return String(d ?? '') === f.default
+  return String(d ?? '') === String(f.default ?? '')
+}
+
+function compareRow(where: string, row: ContractRow, f: Field | undefined, out: ContractIssue[]): void {
+  const key = row.name
+  if (!f) {
+    out.push({ code: 'missing-prop', where, key, message: `contract row "${key}" (${row.control}, ${row.status}) has no field` })
+    return
+  }
+  if (!sameControl(row.control, f.control)) {
+    out.push({ code: 'control-mismatch', where, key, message: `control is "${f.control}", contract says "${row.control}"` })
+  }
+  if (row.status === 'LEGACY-HIDDEN' && !f.legacyHidden) {
+    out.push({ code: 'unsupported-legacy', where, key, message: 'contract marks this LEGACY-HIDDEN; the field is not legacyHidden' })
+  }
+  if (row.status !== 'LEGACY-HIDDEN' && f.legacyHidden) {
+    out.push({ code: 'unsupported-legacy', where, key, message: `field is legacyHidden but the contract status is ${row.status}` })
+  }
+  if (f.control === 'select') {
+    const opts = f.options as readonly string[]
+    for (const o of opts) if (!row.options.includes(o)) out.push({ code: 'unknown-option', where, key, message: `option "${o}" is not in the contract (${row.options.join(' · ')})` })
+    for (const o of row.options) if (!opts.includes(o)) out.push({ code: 'missing-option', where, key, message: `contract option "${o}" is missing` })
+    for (const o of row.legacyOptions) {
+      if (!f.legacy || !(o in f.legacy)) out.push({ code: 'unsupported-legacy', where, key, message: `legacy value "${o}" is not mapped by the field` })
+    }
+  }
+  if (f.control === 'range' || f.control === 'number') {
+    if ((row.min != null && row.min !== f.min) || (row.max != null && row.max !== f.max) || (row.step != null && row.step !== f.step)) {
+      out.push({ code: 'invalid-range', where, key, message: `range ${f.min}–${f.max}/${f.step}, contract ${row.min}–${row.max}/${row.step}` })
+    }
+  }
+  if (!eqDefault(row, f)) {
+    out.push({ code: 'invalid-default', where, key, message: `default is ${JSON.stringify(f.default)}, contract says ${JSON.stringify(row.def)}` })
+  }
+}
+
+function compareFields(where: string, rows: readonly ContractRow[], schema: Schema, out: ContractIssue[], sharedKeys: ReadonlySet<string> = new Set()): number {
+  const seen = new Set<string>(sharedKeys)
+  for (const row of rows) {
+    // A row whose control is "—" is a NEEDS NEW DATA SOURCE / PROPOSED marker, not a setting.
+    if (row.control === '—' || row.control === '') continue
+    seen.add(row.name)
+    compareRow(where, row, schema.fields[row.name], out)
+  }
+  for (const [key, f] of Object.entries(schema.fields)) {
+    if (!seen.has(key) && !f.extension) out.push({ code: 'extra-prop', where, key, message: 'field has no contract row and no `extension` reason' })
+  }
+  // Two visible fields that control the same thing make a merchant choose twice.
+  const bySemantic = new Map<string, string[]>()
+  for (const [key, f] of Object.entries(schema.fields)) {
+    if (f.legacyHidden) continue
+    const s = f.semantic ?? key
+    bySemantic.set(s, [...(bySemantic.get(s) ?? []), key])
+  }
+  for (const [s, keys] of bySemantic) {
+    if (keys.length > 1) out.push({ code: 'duplicated-setting', where, key: keys.join(' + '), message: `visible fields ${keys.join(', ')} all control "${s}"` })
+  }
+  return seen.size - [...sharedKeys].filter((k) => !rows.some((r) => r.name === k)).length
+}
+
+/**
+ * The shared Nova 12 vocabulary is defined ONCE, in 12A ("00 · Shared Nova 12
+ * vocabulary"); later families list only their applicability. A family with
+ * no shared rows of its own reads 12A's.
+ */
+function sharedRowsOf(fam: FamilyId): readonly ContractRow[] {
+  return FAMILIES[fam].shared.length ? FAMILIES[fam].shared : FAMILIES['12A'].shared
+}
+
+/**
+ * The block type a section accepts for a contract block name: the name itself,
+ * or the accepted block whose schema lists it in `legacyNames` (a block renamed
+ * after the contract was locked — the contract keeps the old name).
+ */
+function acceptedBlockFor(contractName: string, schema: Schema, blocks: ReadonlyMap<string, Schema>): string | undefined {
+  if (schema.blocks?.includes(contractName)) return contractName
+  return schema.blocks?.find((b) => (blocks.get(`${b}@${schema.name}`) ?? blocks.get(b))?.legacyNames?.includes(contractName))
+}
+
+function checkPreset(preset: ReturnType<typeof presetsFor>[number], schema: Schema, blocks: ReadonlyMap<string, Schema>, out: ContractIssue[]): void {
+  const where = `preset:${preset.name}`
+  for (const [key, value] of Object.entries(preset.settings)) {
+    const f = schema.fields[key]
+    if (!f) {
+      out.push({ code: 'invalid-preset', where, key, message: `sets "${key}", which ${schema.name} does not have` })
+      continue
+    }
+    if (f.control === 'select' && !(f.options as readonly string[]).includes(String(value))) {
+      out.push({ code: 'invalid-preset', where, key, message: `value "${String(value)}" is not an option of ${schema.name}.${key}` })
+    }
+    if (f.control === 'boolean' && typeof value !== 'boolean') {
+      out.push({ code: 'invalid-preset', where, key, message: `value ${JSON.stringify(value)} is not a boolean` })
+    }
+    if (f.control === 'range' && (typeof value !== 'number' || value < (f as { min: number }).min || value > (f as { max: number }).max)) {
+      out.push({ code: 'invalid-preset', where, key, message: `value ${JSON.stringify(value)} is outside the range` })
+    }
+  }
+  for (const b of preset.blocks) {
+    const type = acceptedBlockFor(b.type, schema, blocks)
+    if (!type) {
+      out.push({ code: 'invalid-block', where, key: b.type, message: `block "${b.type}" is not accepted by ${schema.name}` })
+      continue
+    }
+    const bs = blocks.get(`${type}@${schema.name}`) ?? blocks.get(type)
+    if (!bs) {
+      out.push({ code: 'invalid-block', where, key: b.type, message: `block "${b.type}" has no schema` })
+      continue
+    }
+    for (const [key, value] of Object.entries(b.settings)) {
+      const f = bs.fields[key]
+      if (!f) out.push({ code: 'invalid-preset', where, key: `${b.type}.${key}`, message: `block setting "${key}" does not exist` })
+      else if (f.control === 'select' && !(f.options as readonly string[]).includes(String(value))) {
+        out.push({ code: 'invalid-preset', where, key: `${b.type}.${key}`, message: `value "${String(value)}" is not an option` })
+      }
+    }
+  }
+}
+
+export interface ValidateOptions {
+  /** Design families whose sections must all be implemented. */
+  readonly families: readonly FamilyId[]
+  readonly sections: readonly Schema[]
+  readonly blocks: readonly Schema[]
+  /** Theme-setting groups (kind 'global') — compared with a family's globals rows. */
+  readonly globals?: readonly Schema[]
+  readonly accepted?: readonly AcceptedDeviation[]
+}
+
+export function validateContracts(opts: ValidateOptions): ValidationReport {
+  const out: ContractIssue[] = []
+  const sectionByName = new Map(opts.sections.map((s) => [s.name, s]))
+  // A block schema is keyed by name, and by name@parent when one name has two
+  // definitions (image in 12D group vs image in 12F ugc-gallery).
+  const blockByKey = new Map<string, Schema>()
+  for (const b of opts.blocks) {
+    blockByKey.set(b.name, blockByKey.get(b.name) ?? b)
+    for (const p of b.parents ?? []) blockByKey.set(`${b.name}@${p}`, b)
+  }
+  let rows = 0
+  let presets = 0
+  let blockCount = 0
+
+  for (const fam of opts.families) {
+    const family = FAMILIES[fam]
+    // Global settings (Nova 13 popup): one global schema per family carries every globals row.
+    if (family.globals.length) {
+      const where = `global:${fam}`
+      const g = opts.globals?.find((s) => s.family === fam)
+      if (!g) out.push({ code: 'missing-section', where, message: `${fam} globals have no global schema` })
+      else {
+        rows += compareFields(where, family.globals, g, out)
+        for (const p of family.presets.filter((x) => x.section.startsWith('global:'))) {
+          presets++
+          checkPreset(p, g, blockByKey, out)
+        }
+      }
+    }
+    for (const cs of family.sections) {
+      const where = `section:${cs.name}`
+      const schema = sectionByName.get(cs.name)
+      if (!schema) {
+        out.push({ code: 'missing-section', where, message: `${fam} section "${cs.name}" has no schema` })
+        continue
+      }
+      const sharedRows = sharedRowsOf(fam)
+      // A shared setting that APPLIES is a legitimate field even without a
+      // section row (12B+ carry no per-section shared rows).
+      const applies = new Set(family.sharedApplicability.filter((a) => a[cs.name] === 'APPLIES').map((a) => a.prop))
+      rows += compareFields(where, cs.rows, schema, out, applies)
+
+      // Shared settings: APPLIES must be present with the shared vocabulary;
+      // NOT APPLICABLE must be absent unless the section's own row declares it.
+      for (const app of family.sharedApplicability) {
+        const prop = app.prop
+        const status = app[cs.name]
+        if (!status) continue
+        const own = cs.rows.find((r) => r.name === prop)
+        const f = schema.fields[prop]
+        if (status === 'APPLIES' && !f) {
+          out.push({ code: 'shared-applicability', where, key: prop, message: 'shared setting APPLIES but the section has no field for it' })
+        }
+        if (status === 'APPLIES' && f && !own) {
+          const shared = sharedRows.find((r) => r.name === prop)
+          if (shared && shared.control && !sameControl(shared.control, f.control)) {
+            out.push({ code: 'control-mismatch', where, key: prop, message: `shared "${prop}" is a ${shared.control}; the field is a ${f.control}` })
+          }
+        }
+        if (status === 'APPLIES' && f?.control === 'select') {
+          const shared = sharedRows.find((r) => r.name === prop)
+          const opts2 = f.options as readonly string[]
+          if (shared && shared.options.some((o) => !opts2.includes(o))) {
+            out.push({ code: 'shared-applicability', where, key: prop, message: `does not use the shared vocabulary (${shared.options.join(' · ')})` })
+          }
+        }
+        if (status === 'NOT APPLICABLE' && f && !own) {
+          out.push({ code: 'shared-applicability', where, key: prop, message: 'shared setting is NOT APPLICABLE here but the section exposes it' })
+        }
+        if (status.startsWith('OVERRIDDEN') && f && !own) {
+          out.push({ code: 'duplicated-setting', where, key: prop, message: `shared "${prop}" is overridden by ${app[`${cs.name}Note`] || 'a section setting'}; exposing both duplicates it` })
+        }
+      }
+
+      // Every contract block that names this section as a parent must be accepted and implemented.
+      for (const f2 of Object.values(FAMILIES)) {
+        for (const cb of f2.blocks) {
+          if (!cb.parents.includes(cs.name)) continue
+          if (!acceptedBlockFor(cb.name, schema, blockByKey) && !schema.legacyBlocks?.includes(cb.name)) {
+            out.push({ code: 'invalid-block', where, key: cb.name, message: `contract block "${cb.name}" lists ${cs.name} as a parent but the section does not accept it` })
+          }
+        }
+      }
+      for (const b of schema.blocks ?? []) {
+        const own = blockByKey.get(`${b}@${cs.name}`) ?? blockByKey.get(b)
+        const cb = contractBlock(b, cs.name) ?? (own?.legacyNames ?? []).map((n) => contractBlock(n, cs.name)).find(Boolean)
+        const where2 = `block:${b}@${cs.name}`
+        if (!cb) {
+          out.push({ code: 'invalid-block', where: where2, message: `section accepts "${b}" but no contract block lists ${cs.name} as a parent` })
+          continue
+        }
+        const bs = blockByKey.get(`${b}@${cs.name}`) ?? blockByKey.get(b)
+        if (!bs) {
+          out.push({ code: 'missing-block', where: where2, message: `block "${b}" has no schema` })
+          continue
+        }
+        blockCount++
+        rows += compareFields(where2, cb.block.rows, bs, out)
+      }
+
+      for (const p of presetsFor(cs.name)) {
+        presets++
+        checkPreset(p, schema, blockByKey, out)
+      }
+    }
+  }
+
+  const accepted: (ContractIssue & { reason: string })[] = []
+  const issues: ContractIssue[] = []
+  for (const i of out) {
+    const a = opts.accepted?.find((x) => x.code === i.code && x.where === i.where && (x.key === undefined || x.key === i.key))
+    if (a) accepted.push({ ...i, reason: a.reason })
+    else issues.push(i)
+  }
+  // Dedupe (a block reached from two parents reports once per parent — keep that; exact dupes go).
+  const uniq = (xs: ContractIssue[]) => xs.filter((x, i) => xs.findIndex((y) => y.code === x.code && y.where === x.where && y.key === x.key && y.message === x.message) === i)
+  return {
+    issues: uniq(issues),
+    accepted: uniq(accepted) as (ContractIssue & { reason: string })[],
+    checked: { sections: opts.families.reduce((n, f) => n + FAMILIES[f].sections.length, 0), blocks: blockCount, rows, presets },
+  }
+}
+
+export function formatReport(r: ValidationReport): string {
+  const lines = [
+    `Contract validation — ${r.checked.sections} sections · ${r.checked.blocks} block bindings · ${r.checked.rows} rows · ${r.checked.presets} presets`,
+  ]
+  for (const i of r.issues) lines.push(`  ✗ [${i.code}] ${i.where}${i.key ? ` · ${i.key}` : ''} — ${i.message}`)
+  for (const a of r.accepted) lines.push(`  ~ [${a.code}] ${a.where}${a.key ? ` · ${a.key}` : ''} — accepted: ${a.reason}`)
+  lines.push(r.issues.length ? `✗ ${r.issues.length} issue(s)` : `✓ no drift (${r.accepted.length} accepted deviation(s))`)
+  return lines.join('\n')
+}

package/templates/nova/scripts/compiler/manifest/gen-manifest.mjs

@@ -0,0 +1,156 @@
+/**
+ * Emit theme.manifest.json — the single machine-readable catalog of this theme,
+ * read by the editor inserter, the AI theme generator (ai-api), and the Phase 1
+ * dashboard↔surface conformance test.
+ *
+ * It loads `manifest-entry.ts` through a Vite SSR server rather than plain Node
+ * so `import.meta.glob` resolves against the exact `sections/*.tsx` +
+ * `templates/*.json` the app registers — the manifest is generated from the
+ * same source of truth it describes, so it cannot drift.
+ *
+ *   node scripts/gen-manifest.mjs [--check]
+ *
+ * --check regenerates in memory and fails (exit 1) if the committed
+ * theme.manifest.json is stale — for CI, so a new/edited section without a
+ * regenerated manifest is caught in review.
+ */
+import { createServer } from 'vite'
+import { writeFileSync, readFileSync, existsSync, mkdirSync } from 'node:fs'
+import { fileURLToPath } from 'node:url'
+import { dirname, join } from 'node:path'
+
+const here = dirname(fileURLToPath(import.meta.url))
+// The theme being built: the directory the command runs in.
+const root = process.cwd()
+// theme.manifest.json stays at the theme root: studio-api and the editor read
+// it from a theme's files, and the runtime bundle imports it. It is committed,
+// so a clean checkout builds without regenerating it first.
+const outFile = join(root, 'theme.manifest.json')
+const readmeFile = join(root, 'README.md')
+const check = process.argv.includes('--check')
+
+const CATALOG_START = '<!-- BEGIN GENERATED CATALOG -->'
+const CATALOG_END = '<!-- END GENERATED CATALOG -->'
+
+/** Render the human-readable catalog block spliced into README.md — a view of
+ *  the same manifest, so the docs can't drift from what the theme ships. */
+function renderCatalog(m) {
+  const byCat = {}
+  for (const s of m.sections) if (s.role !== 'block') (byCat[s.category] ??= []).push(s.name)
+  const blocks = m.sections.filter((s) => s.role === 'block').map((s) => s.name).sort()
+  const lines = []
+  lines.push(
+    `**${m.stats.sections} sections (${m.stats.headerFooterSections} in the header / footer zones) · ${m.stats.blocks} block types · ${m.stats.templates} templates · ${m.stats.settings} settings**`,
+  )
+  lines.push('')
+  lines.push('### Sections by category')
+  for (const cat of Object.keys(byCat).sort()) {
+    lines.push(`- **${cat}** (${byCat[cat].length}): ${byCat[cat].sort().join(', ')}`)
+  }
+  lines.push('')
+  lines.push(`### Blocks (${blocks.length} types, nested inside sections)`)
+  lines.push(`- ${blocks.join(', ')}`)
+  lines.push('')
+  lines.push('### Shared groups')
+  for (const g of m.groups ?? []) {
+    lines.push(`- **${g.name}** (${g.type}): ${g.sectionTypes.join(', ')} — used by ${g.usedBy.length} template(s)`)
+  }
+  lines.push('')
+  lines.push('### Templates')
+  lines.push('| template | header | footer | sections |')
+  lines.push('| --- | --- | --- | --- |')
+  const slot = (s) => (s.mode === 'ref' ? `↗ ${s.group}` : s.mode)
+  for (const t of m.templates)
+    lines.push(`| \`${t.name}\` | ${slot(t.groups.header)} | ${slot(t.groups.footer)} | ${t.sectionTypes.join(', ') || '—'} |`)
+  lines.push('')
+  lines.push('### Theme settings')
+  for (const g of m.settingsSchema) {
+    lines.push(`- **${g.group}**: ${g.items.map((i) => i.key).join(', ')}`)
+  }
+  return lines.join('\n')
+}
+
+/** Splice a freshly-rendered catalog between the markers. Returns the new
+ *  README text, or throws if the markers are missing. */
+function spliceReadme(current, catalog) {
+  const a = current.indexOf(CATALOG_START)
+  const b = current.indexOf(CATALOG_END)
+  if (a === -1 || b === -1 || b < a) {
+    throw new Error(`README.md is missing the ${CATALOG_START} / ${CATALOG_END} markers`)
+  }
+  return current.slice(0, a + CATALOG_START.length) + '\n' + catalog + '\n' + current.slice(b)
+}
+
+/** Print every integrity warning the manifest carries. */
+function reportWarnings(w, log) {
+  for (const d of w.danglingTemplateRefs) log(`⚠ template ${d.template} → unknown section ${d.type}`)
+  for (const d of w.danglingGroupRefs ?? []) log(`⚠ template ${d.template} → unknown group ${d.group} (groups/${d.group}.json)`)
+  for (const u of w.unknownTemplateSettings ?? [])
+    log(`⚠ template ${u.template} → ${u.type} sets '${u.setting}', which that section does not declare`)
+  for (const b of w.disallowedTemplateBlocks ?? [])
+    log(`⚠ template ${b.template} → ${b.parent} nests '${b.type}', not in its allowedBlocks`)
+  for (const k of w.settingsUndeclared) log(`⚠ settings.json key '${k}' has no schema entry`)
+  for (const k of w.settingsMissingValue) log(`⚠ schema key '${k}' has no value in settings.json`)
+}
+
+/** Drift that must fail CI (content that cannot work as written). */
+function countDrift(w) {
+  return (
+    w.danglingTemplateRefs.length +
+    (w.danglingGroupRefs ?? []).length +
+    (w.unknownTemplateSettings ?? []).length +
+    (w.disallowedTemplateBlocks ?? []).length
+  )
+}
+
+const server = await createServer({
+  root,
+  logLevel: 'error',
+  server: { middlewareMode: true },
+  // The section files import CSS/assets; Vite SSR stubs those, so importing a
+  // section to read its static definition is safe.
+  appType: 'custom',
+})
+
+try {
+  const mod = await server.ssrLoadModule(join(here, 'manifest-entry.ts'))
+  const manifest = mod.buildManifest()
+  const json = JSON.stringify(manifest, null, 2) + '\n'
+
+  const newReadme = spliceReadme(readFileSync(readmeFile, 'utf8'), renderCatalog(manifest))
+
+  if (check) {
+    const curJson = existsSync(outFile) ? readFileSync(outFile, 'utf8') : ''
+    const curReadme = readFileSync(readmeFile, 'utf8')
+    const staleJson = curJson !== json
+    const staleReadme = curReadme !== newReadme
+    // Template drift is a CI failure, not a warning: a template that sets a
+    // setting the section does not declare, nests a block the parent forbids,
+    // or points at a section that no longer exists is broken content shipped
+    // as if it worked.
+    const drift = countDrift(manifest.warnings)
+    if (drift > 0) {
+      reportWarnings(manifest.warnings, console.error)
+      console.error(`✗ ${drift} template/settings drift problem(s). Fix the template or declare the setting.`)
+      process.exitCode = 1
+    }
+    if (staleJson || staleReadme) {
+      const what = [staleJson && 'theme.manifest.json', staleReadme && 'README.md catalog']
+        .filter(Boolean)
+        .join(' + ')
+      console.error(`✗ ${what} stale. Run \`tanqory-theme manifest\` and commit the result.`)
+      process.exitCode = 1
+    } else {
+      console.log('✓ theme.manifest.json + README catalog are up to date.')
+    }
+  } else {
+    mkdirSync(dirname(outFile), { recursive: true })
+    writeFileSync(outFile, json)
+    writeFileSync(readmeFile, newReadme)
+    const { sections, blocks, templates } = manifest.stats
+    console.log(`✓ theme.manifest.json + README catalog — ${sections} sections, ${blocks} block types, ${templates} templates`)
+    reportWarnings(manifest.warnings, console.warn)
+  }
+} finally {
+  await server.close()
+}