create-tanqory-theme 0.0.0-stage → 0.2.2

package/templates/nova/scripts/compiler/checks/check-layout-sanity.mjs

@@ -0,0 +1,169 @@
+#!/usr/bin/env node
+/**
+ * Layout sanity — the check that was missing every time a screenshot looked
+ * wrong while every gate passed.
+ *
+ * Nothing in this repo looked at PROPORTION. A footer cell stretched to 404px
+ * around 120px of payment marks, a newsletter squeezed into a 163px column with
+ * its email field clipped and its heading broken across two lines, a question
+ * that opened onto an empty panel — all of it passed typecheck, 209 unit tests,
+ * the design-rule checker and a full accessibility audit, because none of those
+ * ask whether a block is mostly empty or a line is four words long.
+ *
+ * Three measurements, at every breakpoint the design names:
+ *   1. a laid-out box far taller than what it contains
+ *   2. a text column so narrow the copy breaks into very short lines
+ *   3. a form field too narrow to show what a person types into it
+ *
+ *   pnpm check:layout          # needs the dev server running
+ */
+import { chromium } from 'playwright-core'
+
+const BASE = process.env.THEME_URL ?? 'http://localhost:4321'
+const WIDTHS = [1440, 1280, 768, 390]
+const ROUTES = ['/', '/products/classic-double-breasted-blazer', '/collections/test-collection', '/cart']
+
+/** Space a box holds beyond its content before it reads as a gap. */
+const WASTE_PX = 120
+/** Below this, a line of prose is too short to read comfortably. */
+const MIN_CHARS_PER_LINE = 18
+/** An email field narrower than this clips what has been typed. */
+const MIN_FIELD_PX = 180
+
+/** Runs in the page. A real function, not a string — passed as a string,
+ *  Playwright read this arrow function with a destructured parameter as a
+ *  statement and returned `undefined` for every page, so the gate reported
+ *  success on a fixture built to fail three ways. */
+function probe([wastePx, minChars, minField]) {
+  const out = []
+  /** Anything inside a closed overlay is not on screen; measuring it reports
+   *  gaps nobody can see. */
+  const onScreen = (e) => {
+    for (let n = e; n; n = n.parentElement) {
+      if (n.hasAttribute?.('inert')) return false
+      const cs = getComputedStyle(n)
+      if (cs.display === 'none' || cs.visibility === 'hidden' || cs.opacity === '0') return false
+    }
+    return true
+  }
+  const boxes = [...document.querySelectorAll('main *, .site-footer *, .site-header *')]
+  for (const e of boxes) {
+    const r = e.getBoundingClientRect()
+    if (r.height < 80 || r.width < 40) continue
+    if (!onScreen(e)) continue
+    const cs = getComputedStyle(e)
+    if (cs.position === 'absolute' || cs.position === 'fixed') continue
+    // A box whose size the author SET is not a gap. A hero is 640px because
+    // the merchant chose "large" and its type sits at the bottom of the frame;
+    // a thumbnail rail is as tall as the photo beside it. This check is for
+    // space a layout leaves by accident, not space reserved on purpose.
+    // `getComputedStyle().height` is the USED value and is never 'auto' for a
+    // rendered element, so testing it disabled this check entirely — the
+    // fixture built to fail stopped failing. Only a declared minimum, a fixed
+    // ratio or a background image count as "the author asked for this space".
+    if (cs.aspectRatio !== 'auto') continue
+    if (cs.minHeight !== '0px' && cs.minHeight !== 'auto') continue
+    if (cs.backgroundImage !== 'none') continue
+    // Only overlays are excluded. Filtering on `position === 'static'` also
+    // dropped every relatively-positioned child — a product card's media is
+    // `position: relative`, so the card looked 80% empty.
+    const kids = [...e.children].filter((c) => {
+      const p = getComputedStyle(c).position
+      return p !== 'absolute' && p !== 'fixed'
+    })
+    if (!kids.length) continue
+    // The SPAN the children occupy, not the sum of their heights. Summing is
+    // only right for a vertical stack; in a grid or a row the children sit side
+    // by side, and adding their heights made a perfectly packed row of columns
+    // look like a mostly empty box.
+    const rects = kids.map((c) => c.getBoundingClientRect()).filter((b) => b.height > 0)
+    if (!rects.length) continue
+    const top = Math.min(...rects.map((b) => b.top))
+    const bottom = Math.max(...rects.map((b) => b.bottom))
+    // Padding is deliberate space, not a gap in the layout.
+    const chrome = parseFloat(cs.paddingTop) + parseFloat(cs.paddingBottom)
+    const content = bottom - top + chrome
+    if (content > 0 && r.height - content > wastePx) {
+      out.push({ kind: 'empty-space', el: (e.className || e.tagName).toString().split(' ')[0],
+                 detail: `${Math.round(r.height - content)}px of a ${Math.round(r.height)}px box holds nothing` })
+    }
+  }
+  for (const e of document.querySelectorAll('p, .lede, .newsletter__note')) {
+    if (!onScreen(e)) continue
+    const r = e.getBoundingClientRect()
+    const text = (e.textContent || '').trim()
+    if (r.height < 40 || text.length < 60) continue
+    const lh = parseFloat(getComputedStyle(e).lineHeight) || 20
+    const lines = Math.round(r.height / lh)
+    if (lines >= 3 && text.length / lines < minChars) {
+      out.push({ kind: 'cramped-text', el: (e.className || e.tagName).toString().split(' ')[0],
+                 detail: `${Math.round(text.length / lines)} characters per line over ${lines} lines` })
+    }
+  }
+  for (const e of document.querySelectorAll('input[type=email], input[type=search], input[type=text]')) {
+    if (!onScreen(e)) continue
+    const r = e.getBoundingClientRect()
+    if (r.height > 0 && r.width < minField) {
+      out.push({ kind: 'clipped-field', el: (e.className || e.type).toString().split(' ')[0],
+                 detail: `${Math.round(r.width)}px wide` })
+    }
+  }
+  const seen = new Set()
+  return out.filter((o) => {
+    const k = o.kind + o.el + o.detail
+    if (seen.has(k)) return false
+    seen.add(k)
+    return true
+  })
+}
+
+
+// `playwright-core` ships no browser binaries, so it drives the Chrome already
+// installed on the machine. Connecting over CDP to a shared Chrome was tried
+// first and silently returned nothing on every page — a gate that reports
+// success because it never looked is worse than no gate, which is why the
+// sanity assertions below exist.
+const browser = await chromium.launch({ channel: 'chrome' })
+
+let total = 0
+for (const width of WIDTHS) {
+  // A CDP connection hands back the browser's existing context; creating a new
+  // one is not supported, so the viewport is set on the page instead.
+  const context = await browser.newContext({ viewport: { width, height: 1000 } })
+  const page = await context.newPage()
+  for (const route of ROUTES) {
+    await page.goto(BASE + route, { waitUntil: 'networkidle' })
+    await page.waitForTimeout(4500)
+    try { await page.click('button:has-text("Accept")', { timeout: 1500 }) } catch { /* none */ }
+    // A silent empty result is how a gate becomes decoration: assert the page
+    // is actually loaded and sized before believing that it found nothing.
+    const sanity = await page.evaluate(() => ({
+      url: location.href,
+      width: document.documentElement.clientWidth,
+      boxes: document.querySelectorAll('main *, .site-footer *, .site-header *').length,
+    }))
+    if (sanity.boxes === 0) {
+      console.error(`  ${width}px ${route} — page produced no elements to measure (${sanity.url})`)
+      process.exitCode = 1
+      continue
+    }
+    if (Math.abs(sanity.width - width) > 40) {
+      console.error(`  asked for ${width}px, the page reports ${sanity.width}px — viewport not applied`)
+      process.exitCode = 1
+      continue
+    }
+    const found = await page.evaluate(probe, [WASTE_PX, MIN_CHARS_PER_LINE, MIN_FIELD_PX])
+    for (const f of found) {
+      total++
+      console.error(`  ${width}px ${route} — [${f.kind}] ${f.el}: ${f.detail}`)
+    }
+  }
+  await context.close()
+}
+await browser.close()
+
+if (total) {
+  console.error(`\n✗ ${total} layout problem(s)`)
+  process.exit(1)
+}
+console.log(`✓ no layout problems across ${ROUTES.length} routes x ${WIDTHS.length} widths`)

package/templates/nova/scripts/compiler/checks/check-page-headings.mjs

@@ -0,0 +1,67 @@
+#!/usr/bin/env node
+/**
+ * Exactly one top-level heading per template.
+ *
+ * A live sweep catches this on routable pages, but `templateSuffix` variants
+ * (product.bundle, collection.featured, blog.featured) need a product or
+ * collection assigned to them and so are never visited in a local run. Three
+ * of them shipped with two `h1`s because a decorative rich-text was set to the
+ * h1 size above a section that already owns the page heading.
+ *
+ * The list below is the source of truth for which sections own an `h1`, and is
+ * asserted against the code by tests/design-system.test.ts.
+ */
+import { readFileSync, readdirSync } from 'node:fs'
+import { join, dirname } from 'node:path'
+import { fileURLToPath } from 'node:url'
+
+// The theme: the directory the command runs in.
+const ROOT = process.cwd()
+
+/** Sections that always render the page's `h1`. */
+const OWNS_H1 = new Set([
+  'product-details', 'blog-posts', 'page-body',
+  'article-body', 'cart-items', 'account', 'search-results',
+  'not-found', 'policy-page',
+])
+/** Sections that own it only in some configuration. */
+const CONDITIONAL = {
+  // Only the first slide, and only when the slideshow is the page's opener.
+  slideshow: () => true,
+  hero: () => true,
+  // Only on the /collections index route, where it is the whole page.
+  'collection-list': (_s, template) => template === 'list-collections',
+  // Only when the merchant picks the h1 size.
+  'rich-text': (s) => (s.settings ?? {}).headingSize === 'h1',
+  // Direction B: the banner carries the title only when told to, and is then
+  // paired with `main-collection.showHeader: false` (checked below).
+  'collection-banner': (s) => (s.settings ?? {}).pageHeading === true,
+  // 07B: the contact page's first section carries "Contact us" when told to.
+  'contact-form': (s) => (s.settings ?? {}).pageHeading === true,
+  // The collection page's own header can be switched off for that pairing.
+  'main-collection': (s) => (s.settings ?? {}).showHeader !== false,
+}
+
+const problems = []
+for (const file of readdirSync(join(ROOT, 'templates')).filter((f) => f.endsWith('.json'))) {
+  const doc = JSON.parse(readFileSync(join(ROOT, 'templates', file), 'utf8'))
+  const body = (doc.sections ?? []).filter(
+    (s) => s.area !== 'header' && !['header', 'footer', 'announcement-bar'].includes(s.type),
+  )
+  const owners = body.filter(
+    (s) => OWNS_H1.has(s.type) || (CONDITIONAL[s.type]?.(s, file.replace(/\.json$/, '')) ?? false),
+  )
+  if (owners.length > 1) {
+    problems.push(`${file}: ${owners.length} sections claim the page heading — ${owners.map((s) => s.type).join(', ')}`)
+  }
+  if (owners.length === 0) {
+    problems.push(`${file}: no section carries the page heading`)
+  }
+}
+
+if (problems.length) {
+  console.error('✗ page heading problems:')
+  for (const p of problems) console.error(`    ${p}`)
+  process.exit(1)
+}
+console.log('✓ every template has exactly one section carrying the page heading')

package/templates/nova/scripts/compiler/checks/check-product-jsonld.mjs

@@ -0,0 +1,80 @@
+#!/usr/bin/env node
+/**
+ * `pnpm check:jsonld` — the BUILT theme must ship schema.org Product/Offer JSON-LD in the SERVER html of a product
+ * page (crawlers and AI answer engines do not run JS) and nothing on non-product pages.
+ *
+ * Runs the real SSR entry (`dist/ssr/entry.mjs`, so build first) against the theme's mock catalog and checks what
+ * Google's Product snippet requires: `name`, an absolute `url`, and an `offers` block with a numeric `price`, an
+ * ISO-4217 `priceCurrency` and a schema.org `availability` URL. Per-market currency and availability logic is
+ * unit-tested in tests/structured-data.test.ts; this guards the wiring (build -> render -> head).
+ */
+import { access } from 'node:fs/promises'
+import { join, resolve } from 'node:path'
+import { pathToFileURL } from 'node:url'
+
+const root = resolve(process.argv[2] ?? '.')
+const entry = join(root, 'dist', 'ssr', 'entry.mjs')
+try {
+  await access(entry)
+} catch {
+  console.error('error dist/ssr/entry.mjs is missing: run `pnpm build` first')
+  process.exit(1)
+}
+
+const mod = await import(pathToFileURL(entry).href)
+const ctx = { mode: 'serve', assets: { base: '', manifest: {} }, content: { templates: {}, groups: {}, settings: {} } }
+const errors = []
+const CURRENCIES = new Set(Intl.supportedValuesOf('currency'))
+const AVAILABILITY = new Set(['InStock', 'OutOfStock', 'PreOrder', 'BackOrder', 'SoldOut', 'LimitedAvailability', 'Discontinued', 'InStoreOnly', 'OnlineOnly'].map((a) => `https://schema.org/${a}`))
+const page = async (path) => {
+  const res = await mod.render(new Request(`https://shop.example.com${path}`), ctx)
+  return { status: res.status, html: await res.text() }
+}
+const blocks = (html) => [...html.matchAll(/<script type="application\/ld\+json">([\s\S]*?)<\/script>/g)].map((m) => m[1])
+/** The Product blocks only: sections add their own types (BreadcrumbList, FAQPage), which are not duplicates. */
+const productBlocks = (html) =>
+  blocks(html).filter((b) => {
+    try {
+      return JSON.parse(b)['@type'] === 'Product'
+    } catch {
+      return true // unparseable counts, so the check below reports it
+    }
+  })
+
+const product = await page('/products/example-product-1')
+const found = productBlocks(product.html)
+if (product.status !== 200) errors.push(`product page answered ${product.status}`)
+if (found.length !== 1) errors.push(`expected exactly one Product JSON-LD block on the product page, found ${found.length}`)
+else {
+  let ld
+  try {
+    ld = JSON.parse(found[0])
+  } catch (e) {
+    errors.push(`JSON-LD is not valid JSON: ${e.message}`)
+  }
+  if (ld) {
+    if (ld['@context'] !== 'https://schema.org') errors.push('@context must be https://schema.org')
+    if (ld['@type'] !== 'Product') errors.push('@type must be Product')
+    if (!ld.name) errors.push('name is required')
+    if (!/^https?:\/\//.test(ld.url ?? '')) errors.push('url must be absolute')
+    const o = ld.offers
+    if (!o) errors.push('offers is required')
+    else {
+      const price = o['@type'] === 'AggregateOffer' ? o.lowPrice : o.price
+      if (!/^\d+(?:\.\d+)?$/.test(String(price ?? ''))) errors.push(`offers price is not numeric: ${price}`)
+      if (!CURRENCIES.has(o.priceCurrency)) errors.push(`offers priceCurrency is not ISO-4217: ${o.priceCurrency}`)
+      if (o.availability !== undefined && !AVAILABILITY.has(o.availability)) errors.push(`offers availability is not a schema.org URL: ${o.availability}`)
+    }
+    for (const img of ld.image ?? []) if (!/^https?:\/\//.test(img)) errors.push(`image is not absolute: ${img}`)
+  }
+}
+if (/<\/script><script/.test(found[0] ?? '')) errors.push('JSON-LD must not contain a raw script terminator')
+
+const home = await page('/')
+if (productBlocks(home.html).length) errors.push('the home page must not carry a Product block')
+
+if (errors.length) {
+  for (const e of errors) console.error(`error ${e}`)
+  process.exit(1)
+}
+console.log('✓ product page ships one valid schema.org Product/Offer JSON-LD block in the server html; home has none')

package/templates/nova/scripts/compiler/checks/theme-spec/check.mjs

@@ -0,0 +1,88 @@
+#!/usr/bin/env node
+/**
+ * `pnpm check` — validate this BUILT theme against Tanqory theme spec v1.
+ *
+ * The theme owns all of its code, so it carries its own copy of the spec
+ * checker (the platform keeps the canonical one in `packages/theme-spec`);
+ * a clone of this repository alone can run every gate.
+ */
+import { readFile, stat, access } from 'node:fs/promises'
+import { join, resolve } from 'node:path'
+import { pathToFileURL } from 'node:url'
+
+const SPEC_VERSION = 1
+
+const CANVAS_PROTOCOL = Object.freeze({
+  fromTheme: Object.freeze(['tq:ready', 'tq:select', 'tanqory-section-selected', 'tanqory-block-selected', 'tanqory-content-changed', 'tanqory-content', 'tanqory-collections', 'tanqory-menus', 'tanqory-products', 'tq-preview-height']),
+  toTheme: Object.freeze(['tq:set-content', 'tq:select', 'tq:theme-settings', 'tanqory-preview-update-section', 'tanqory-preview-select', 'tanqory-preview-reorder-sections', 'tanqory-preview-remove-section', 'tanqory-preview-insert-section', 'tanqory-get-content', 'tanqory-request-collections', 'tanqory-request-menus', 'tanqory-request-products']),
+})
+
+const LIMITS = Object.freeze({
+  ssrBundleBytes: 10 * 1024 * 1024,   // Workers script limit
+  clientBundleBytes: 25 * 1024 * 1024,
+  renderMs: 50,                       // CPU budget per render (isolate)
+})
+
+const SETTING_TYPES = new Set(['text', 'textarea', 'richtext', 'html', 'url', 'number', 'range', 'boolean', 'select', 'radio', 'color', 'text_alignment', 'image', 'video', 'collection', 'product', 'page', 'blog', 'article', 'menu', 'header', 'paragraph', 'link_list', 'inline_richtext', 'font_picker', 'checkbox'])
+
+/** Errors in a manifest object; [] when valid. */
+function validateManifest(m) {
+  const errors = []
+  if (!m || typeof m !== 'object') return ['manifest is not an object']
+  if (m.spec !== SPEC_VERSION) errors.push(`manifest.spec must be ${SPEC_VERSION}`)
+  if (typeof m.name !== 'string' || !m.name) errors.push('manifest.name is required')
+  if (!Array.isArray(m.sections)) errors.push('manifest.sections must be an array')
+  else {
+    const seen = new Set()
+    m.sections.forEach((s, i) => {
+      if (!s || typeof s.name !== 'string' || !/^[a-z0-9-]+$/.test(s.name)) { errors.push(`sections[${i}].name must be kebab-case`); return }
+      if (seen.has(s.name)) errors.push(`duplicate section "${s.name}"`)
+      seen.add(s.name)
+      if (s.role && !['layout', 'section', 'block'].includes(s.role)) errors.push(`sections[${i}] "${s.name}": role must be layout|section|block`)
+      for (const [id, spec] of Object.entries(s.attributes ?? {})) {
+        if (!spec || typeof spec.type !== 'string') errors.push(`section "${s.name}" attribute "${id}" has no type`)
+        else if (!SETTING_TYPES.has(spec.type)) errors.push(`section "${s.name}" attribute "${id}": unknown type "${spec.type}"`)
+      }
+    })
+  }
+  if (!Array.isArray(m.templates) || !m.templates.includes('index')) errors.push('manifest.templates must include "index"')
+  if (m.groups !== undefined && !Array.isArray(m.groups)) errors.push('manifest.groups must be an array')
+  return errors
+}
+
+const FORBIDDEN_IMPORTS = /(?:^|[^\w])(?:from|import)\s*\(?\s*["'](node:[a-z_]+|fs|path|os|child_process|crypto|net|http|https|worker_threads|vm)["']/g
+
+/** Validate a BUILT theme directory. Never throws for a theme error — reports it. */
+async function checkTheme(themeDir) {
+  const errors = [], warnings = []
+  const entry = join(themeDir, 'dist', 'ssr', 'entry.mjs')
+  const clientDir = join(themeDir, 'dist', 'client')
+  const exists = async (p) => { try { await access(p); return true } catch { return false } }
+  if (!(await exists(entry))) errors.push('dist/ssr/entry.mjs is missing — the theme must build an SSR entry that exports render() and manifest')
+  if (!(await exists(join(clientDir, '.vite', 'manifest.json')))) errors.push('dist/client/.vite/manifest.json is missing — build the client with `build.manifest: true`')
+  let manifest
+  if (errors.length === 0) {
+    const size = (await stat(entry)).size
+    if (size > LIMITS.ssrBundleBytes) errors.push(`dist/ssr/entry.mjs is ${size} bytes, over the ${LIMITS.ssrBundleBytes}-byte isolate limit`)
+    const src = await readFile(entry, 'utf8')
+    const bad = [...src.matchAll(FORBIDDEN_IMPORTS)].map((m) => m[1])
+    if (bad.length) errors.push(`SSR bundle imports Node built-ins (${[...new Set(bad)].join(', ')}) — not available in the isolate; bundle everything (ssr.noExternal) and avoid Node APIs`)
+    if (/\brequire\s*\(/.test(src)) warnings.push('SSR bundle contains require() — it must be pure ESM for the isolate')
+    try {
+      const mod = await import(pathToFileURL(entry).href)
+      if (typeof mod.render !== 'function') errors.push('entry does not export render()')
+      if (!mod.manifest || typeof mod.manifest !== 'object') errors.push('entry does not export manifest')
+      else { manifest = mod.manifest; errors.push(...validateManifest(manifest)) }
+    } catch (e) {
+      errors.push(`entry failed to load: ${e?.message || e}`)
+    }
+  }
+  return { ok: errors.length === 0, errors, warnings, manifest }
+}
+
+const dir = resolve(process.argv[2] || '.')
+const r = await checkTheme(dir)
+for (const w of r.warnings) console.log('warn ', w)
+for (const e of r.errors) console.log('error', e)
+if (r.ok) console.log(`✓ theme "${r.manifest.name}" v${r.manifest.version ?? '?'} passes spec v1 (${r.manifest.sections.length} sections, ${r.manifest.templates.length} templates)`)
+process.exit(r.ok ? 0 : 1)

package/templates/nova/scripts/compiler/contracts/extract.mjs

@@ -0,0 +1,188 @@
+#!/usr/bin/env node
+/**
+ * `tanqory-theme contracts` — writes and checks the theme's contract locks,
+ * `.tanqory/contracts/`. Compiler-managed: theme authors never edit them.
+ *
+ * The approved design package (`*.dc.html`) carries its data in a
+ * `<script type="text/x-dc">` block whose `renderVals()` returns the tables the
+ * canvas renders. Executing that block is the only faithful way to read it.
+ * Each design family becomes one lock, `<theme>-<family>.json`: the persisted
+ * ids (sections, blocks, settings, options), labels, presets and shared
+ * settings. `LOCK.json` records, per lock, the design file it came from and the
+ * sha256 of both — so a hand edit, or a design change nobody re-locked, fails.
+ *
+ *   tanqory-theme contracts --check                 locks match LOCK.json (no hand edits)
+ *   tanqory-theme contracts --design <dir> --check  …and still match the design package
+ *   tanqory-theme contracts --design <dir> --write  re-extract from the design package
+ */
+import { createHash } from 'node:crypto'
+import { existsSync, mkdirSync, readFileSync, readdirSync, writeFileSync } from 'node:fs'
+import { join, resolve } from 'node:path'
+
+const THEME = process.cwd()
+const OUT = join(THEME, '.tanqory', 'contracts')
+const LOCK = join(OUT, 'LOCK.json')
+const args = process.argv.slice(2)
+const WRITE = args.includes('--write')
+const designAt = args.indexOf('--design')
+const DESIGN = designAt >= 0 ? resolve(args[designAt + 1] ?? '') : null
+
+/** The families a theme locks, by default (Nova's): design file → family id. */
+const DEFAULT_SOURCES = {
+  '01': 'Nova 01 Style System.dc.html',
+  '12A': 'Nova 12A - Chrome and Structure.dc.html',
+  '12B': 'Nova 12B - Heroes and Promotion.dc.html',
+  '12C': 'Nova 12C - Product and Merchandising.dc.html',
+  '12D': 'Nova 12D - Content and Storytelling.dc.html',
+  '12E': 'Nova 12E - Editorial and Long-form.dc.html',
+  '12F': 'Nova 12F - Trust and Advanced Commerce.dc.html',
+  '12G': 'Nova 12G - Utility and Customer Experience.dc.html',
+  '13': 'Nova 13 - Overlays and Feedback.dc.html',
+  '14': 'Nova 14 - Media and System States.dc.html',
+}
+
+const sha256 = (text) => createHash('sha256').update(text).digest('hex')
+const themeName = () => {
+  const name = JSON.parse(readFileSync(join(THEME, 'package.json'), 'utf8')).name ?? 'theme'
+  return name.split('/').pop()
+}
+
+// ── extraction (the design package → one JSON per family) ────────────────────
+
+const DISPLAY_ONLY = new Set(['sbg', 'sfg', 'optDisp', 'legacyDisp', 'legacyLblDisp', 'defDisp', 'defRange', 'rowNames', 'counts'])
+
+function renderVals(src, file) {
+  const m = src.match(/<script type="text\/x-dc"[^>]*>([\s\S]*?)<\/script>/)
+  if (!m) throw new Error(`${file}: no x-dc logic block`)
+  class DCLogic {
+    constructor() {
+      this.props = {}
+      this.state = {}
+    }
+    setState() {}
+  }
+  return new Function('DCLogic', `${m[1]}; return new Component().renderVals()`)(DCLogic)
+}
+
+/** `a · b · c` → ['a', 'b', 'c']; '' → []. */
+const ids = (s) => (typeof s === 'string' && s.trim() ? s.split('·').map((x) => x.trim()).filter(Boolean) : [])
+
+/** Booleans and numbers arrive as strings in some tables ("false", "32"). */
+function normaliseDefault(row) {
+  const d = row.def
+  if (row.control === 'boolean') return d === true || d === 'true'
+  if (row.control === 'range' || row.control === 'number') return d === '' || d == null ? null : Number(d)
+  return d == null ? '' : d
+}
+
+function row(r) {
+  const out = {}
+  for (const [k, v] of Object.entries(r)) if (!DISPLAY_ONLY.has(k)) out[k] = v
+  out.options = ids(r.options)
+  out.optionLabels = ids(r.optionLabels)
+  out.legacyOptions = ids(r.legacyOptions)
+  out.legacyOptionLabels = ids(r.legacyOptionLabels)
+  out.def = normaliseDefault(r)
+  return out
+}
+
+/** A foundations table set (Nova 01) is kept whole, not as a section contract. */
+const FOUNDATION_KEYS = ['tokens', 'colors', 'brandDerive', 'families', 'typeScale', 'typeRules', 'radii', 'radiusMap', 'gaps', 'sectionSpace', 'containers', 'ratios', 'motion', 'dark', 'principles']
+
+function family(v) {
+  if (v.typeScale && v.radii) return Object.fromEntries(FOUNDATION_KEYS.map((k) => [k, v[k] ?? []]))
+  const out = {
+    sections: (v.sections ?? []).map((s) => ({ name: s.name, label: s.label, status: s.status, rows: s.rows.map(row) })),
+    blocks: (v.blocks ?? []).map((b) => ({
+      name: b.name,
+      label: b.label,
+      parents: [...new Set(b.parents ?? [])],
+      min: b.min,
+      recommended: b.recommended,
+      max: b.max,
+      status: b.status,
+      resp: b.resp,
+      empty: b.empty,
+      summary: b.summary ?? '',
+      rows: (b.rows ?? []).map(row),
+    })),
+    presets: v.presets ?? [],
+    shared: (v.shared ?? []).map(row),
+    sharedApplicability: v.sharedApplicability ?? [],
+    globals: (v.globals ?? []).map(row),
+    ai: v.ai ?? [],
+    conflicts: v.conflicts ?? [],
+  }
+  if (v.placeholders) out.placeholders = v.placeholders
+  if (v.stateFamilies) out.stateFamilies = v.stateFamilies
+  return out
+}
+
+// ── the lock ─────────────────────────────────────────────────────────────────
+
+const readLock = () => (existsSync(LOCK) ? JSON.parse(readFileSync(LOCK, 'utf8')) : null)
+const sourcesOf = (lock) => (lock ? Object.fromEntries(Object.values(lock.files).map((f) => [f.family, f.design])) : DEFAULT_SOURCES)
+
+function extract(sources) {
+  const present = new Set(readdirSync(DESIGN))
+  const out = {}
+  for (const [id, file] of Object.entries(sources)) {
+    if (!present.has(file)) throw new Error(`${file} is not in ${DESIGN}`)
+    const design = readFileSync(join(DESIGN, file), 'utf8')
+    out[`${themeName()}-${id}.json`] = { family: id, design: file, designSha256: sha256(design), json: JSON.stringify(family(renderVals(design, file)), null, 2) + '\n' }
+  }
+  return out
+}
+
+function lockDoc(files) {
+  return {
+    $comment: 'Generated by `tanqory-theme contracts`. Do not edit — neither this file nor the locks beside it. Re-lock from the approved design package with `tanqory-theme contracts --design <dir> --write`.',
+    generator: '@tanqory/theme-compiler contracts',
+    files: Object.fromEntries(
+      Object.entries(files)
+        .sort(([a], [b]) => a.localeCompare(b))
+        .map(([name, f]) => [name, { family: f.family, design: f.design, designSha256: f.designSha256, sha256: sha256(f.json) }]),
+    ),
+  }
+}
+
+let failures = 0
+const fail = (msg) => {
+  console.error(`✗ ${msg}`)
+  failures++
+}
+
+if (WRITE) {
+  if (!DESIGN) {
+    console.error('usage: tanqory-theme contracts --design <dir> --write')
+    process.exit(2)
+  }
+  const files = extract(sourcesOf(readLock()))
+  mkdirSync(OUT, { recursive: true })
+  for (const [name, f] of Object.entries(files)) writeFileSync(join(OUT, name), f.json)
+  writeFileSync(LOCK, JSON.stringify(lockDoc(files), null, 2) + '\n')
+  console.log(`✓ .tanqory/contracts — ${Object.keys(files).length} locks written from ${DESIGN}`)
+} else {
+  const lock = readLock()
+  if (!lock) {
+    console.error('✗ .tanqory/contracts/LOCK.json is missing — run `tanqory-theme contracts --design <dir> --write`')
+    process.exit(1)
+  }
+  // 1. No hand edits: every lock matches the hash the compiler recorded.
+  const onDisk = new Set(readdirSync(OUT).filter((f) => f.endsWith('.json') && f !== 'LOCK.json'))
+  for (const [name, f] of Object.entries(lock.files)) {
+    if (!onDisk.has(name)) fail(`${name} is missing`)
+    else if (sha256(readFileSync(join(OUT, name), 'utf8')) !== f.sha256) fail(`${name} was edited by hand — locks are compiler-managed`)
+    onDisk.delete(name)
+  }
+  for (const name of onDisk) fail(`${name} is not in LOCK.json — locks are compiler-managed`)
+  // 2. With the design package at hand: the locks still say what it says.
+  if (DESIGN) {
+    const files = extract(sourcesOf(lock))
+    for (const [name, f] of Object.entries(files)) {
+      if (lock.files[name]?.sha256 !== sha256(f.json)) fail(`${name} no longer matches ${f.design} — re-lock with --write`)
+    }
+  }
+  if (failures) process.exit(1)
+  console.log(`✓ .tanqory/contracts — ${Object.keys(lock.files).length} locks intact${DESIGN ? ' and match the design package' : ''}`)
+}