create-tanqory-theme 0.0.0-stage → 0.2.3

package/templates/nova/scripts/abi/manifest.mjs

@@ -0,0 +1,392 @@
+/**
+ * Theme ABI v2 manifest + starter content, derived from what the theme already declares.
+ *
+ * Inputs (all theme-owned, all generated or authored in this directory):
+ *   theme.manifest.json   v1 catalogue, generated from the `defineSection` schemas (pnpm manifest)
+ *   templates/*.json      starter page compositions (contentVersion 2)
+ *   groups/*.json         the shared header / footer
+ *   config/settings.json  global setting values
+ *
+ * Outputs (theme-abi-v2.md §7, theme-artifact-v1.md §1):
+ *   manifest             ThemeManifest v2 (`validateManifest` from @tanqory/theme-abi must accept it)
+ *   defaults.settings    { contentVersion, values }
+ *   defaults.regions     RegionDoc per `shared` region
+ *   defaults.templates   TemplateDoc per template
+ *
+ * Every stored value (spec defaults, preset settings, starter content, setting values) goes
+ * through `validateFieldValue`. A value the registry rejects is not repaired here: the build
+ * fails and the value is fixed at its source, so the theme never ships content the platform
+ * would silently drop (theme-abi-v2.md Appendix B: "a rejected value is dropped like an
+ * unknown key").
+ */
+import { existsSync, readFileSync, readdirSync } from 'node:fs'
+import { join } from 'node:path'
+import { starterAssetFor } from './starter-assets.mjs'
+import {
+  FIELD_TYPES_V1,
+  UNIVERSAL_FIELD_CONSTRAINTS,
+  isFieldTypeId,
+  validateFieldValue,
+  validateManifest,
+} from '@tanqory/theme-abi'
+
+export const CONTENT_VERSION = 3
+
+/** Server capabilities: what render() reads. No data:customer: the account area is the platform's iframe (§4 account slot). */
+export const SERVER_CAPABILITIES = [
+  'data:shop',
+  'data:localization',
+  'data:catalog',
+  'data:content',
+  'data:search',
+  'data:cart',
+  'data:products.recommendations',
+  // Opt-in (ABI 2.0.0-alpha.11): ProductVariant.quantityAvailable for the product-inventory block.
+  'data:inventory',
+  'actions:cart',
+  'actions:consent',
+  'actions:form.submit',
+]
+/** Browser capabilities: what the hydrated bundle calls through /_tq/data and /_tq/actions. */
+export const BROWSER_CAPABILITIES = [
+  'data:shop',
+  'data:localization',
+  'data:catalog',
+  'data:content',
+  'data:search',
+  'data:cart',
+  'data:products.recommendations',
+  'data:inventory',
+  'actions:cart',
+  'actions:consent',
+]
+
+/** Route kind for each template. A suffixed template `<kind>.<suffix>` is selected by templateSuffix. */
+const TEMPLATE_ROUTE = {
+  index: 'home',
+  product: 'product',
+  'product.bundle': 'product',
+  collection: 'collection',
+  'collection.featured': 'collection',
+  'list-collections': 'collections',
+  page: 'page',
+  'page.about': 'page',
+  'page.contact': 'page',
+  blog: 'blog',
+  'blog.featured': 'blog',
+  article: 'article',
+  'article.longform': 'article',
+  search: 'search',
+  cart: 'cart',
+  account: 'customer',
+  policy: 'policy',
+  404: 'not_found',
+  contact: 'custom:contact',
+}
+const ROUTES = {
+  home: 'index',
+  product: 'product',
+  collection: 'collection',
+  collections: 'list-collections',
+  page: 'page',
+  blog: 'blog',
+  article: 'article',
+  search: 'search',
+  cart: 'cart',
+  customer: 'account',
+  policy: 'policy',
+  not_found: '404',
+  'custom:contact': 'contact',
+}
+const CUSTOM_ROUTES = { contact: { path: '/contact' } }
+
+/**
+ * Regions. `header`/`footer` are shared (one doc per store), `main` is per template. The home
+ * page's v1 header group was an explicit per-page override that adds an announcement bar above
+ * the shared header; a shared region cannot be overridden per template (§7.2), so that bar
+ * lives in its own template-scoped region rendered before the header on the home template.
+ */
+const REGIONS = {
+  announcement: { title: 'Announcement', scope: 'template', accepts: ['announcement-bar'] },
+  header: { title: 'Header', scope: 'shared' },
+  main: { title: 'Template', scope: 'template' },
+  footer: { title: 'Footer', scope: 'shared' },
+}
+const AREA_TO_REGION = { header: 'header', footer: 'footer', template: 'main' }
+
+/** v1 `requiresContext` → ABI route kinds (identical vocabulary today). */
+const CONTEXT_TO_ROUTE = {
+  product: 'product', collection: 'collection', page: 'page', blog: 'blog', article: 'article',
+  search: 'search', cart: 'cart', customer: 'customer', policy: 'policy',
+}
+
+const RESOURCE_TYPES = new Set(['collection', 'product', 'page', 'blog', 'article', 'menu'])
+const FIELD_KEYS = new Set(['type', 'label', 'info', 'default', 'placeholder', 'group', 'min', 'max', 'step', 'unit', 'options', 'visible_if', 'dynamic', 'resolve', 'items', 'schema'])
+
+const readJson = (p) => JSON.parse(readFileSync(p, 'utf8'))
+
+/** Field-type registry this theme declares (engines["tanqory-field-types"]). */
+export const FIELD_TYPES_REGISTRY = '2'
+/** Theme-authored starter files shipped as `client/assets/<file>` (registry 2 `asset:` targets). */
+export const STARTER_ASSET_DIR = 'assets/starter'
+const ASSET_REF = /^asset:client\/assets\/([A-Za-z0-9._-]+)$/
+
+/**
+ * `validateFieldValue` for registry 2 (theme-abi-v2.md Appendix B.2, additive over 1).
+ * @tanqory/theme-abi 2.0.0-alpha.2 implements registry 1 only, so the two registry-2 deltas are
+ * checked here and everything else is delegated:
+ *   - text_alignment also accepts "start" | "end";
+ *   - image / video also accept `asset:client/assets/<file>` — ONLY in defaults/ and presets
+ *     (`assetAllowed`), and only for a file this theme ships under assets/starter/.
+ */
+function checkValue(type, value, spec, { assetAllowed, starterFiles }) {
+  if (type === 'text_alignment' && (value === 'start' || value === 'end')) return { ok: true }
+  if ((type === 'image' || type === 'video') && typeof value === 'string' && value.startsWith('asset:')) {
+    const m = value.match(ASSET_REF)
+    if (!m) return { ok: false, errors: [{ message: `"${value}" is not asset:client/assets/<file>`, code: 'value_invalid_url' }] }
+    if (!assetAllowed) return { ok: false, errors: [{ message: 'asset: is valid only in defaults/ and presets (Appendix B.2)', code: 'value_invalid_url' }] }
+    if (!starterFiles.has(m[1])) return { ok: false, errors: [{ message: `${m[1]} is not in ${STARTER_ASSET_DIR}/ (asset_ref_missing)`, code: 'asset_ref_missing' }] }
+    return { ok: true }
+  }
+  return validateFieldValue(type, value, spec)
+}
+
+/**
+ * A v1 attribute spec as a registry-1 FieldSpec. Only keys the registry allows for the type are
+ * carried; anything else is a defect in the section schema and is reported, not dropped.
+ */
+function fieldSpec(where, spec, problems) {
+  const type = spec.type
+  if (!isFieldTypeId(type)) {
+    problems.push(`${where}: field type "${type}" is not in tanqory-field-types@1`)
+    return null
+  }
+  const def = FIELD_TYPES_V1[type]
+  const allowed = new Set([...UNIVERSAL_FIELD_CONSTRAINTS, ...def.constraints])
+  if (def.dynamicBindable) allowed.add('dynamic')
+  if (def.resource) allowed.add('resolve')
+  const out = { type }
+  for (const [k, v] of Object.entries(spec)) {
+    if (k === 'type' || k === 'key') continue
+    if (!FIELD_KEYS.has(k) || !allowed.has(k)) {
+      problems.push(`${where}: "${k}" is not allowed on "${type}" (tanqory-field-types@1)`)
+      continue
+    }
+    out[k] = v
+  }
+  // Resource settings are resolved by the platform into snapshot.refs (§3) — the one-call path.
+  if (def.resource && type !== 'article') out.resolve = true
+  // "Not set" is an absent key (Appendix B): an empty default is no default.
+  if (out.default === '' || out.default === null) delete out.default
+  if (out.default !== undefined) {
+    const r = checkValue(type, out.default, out, { assetAllowed: false, starterFiles: new Set() })
+    if (!r.ok) problems.push(`${where}.default ${JSON.stringify(out.default)}: ${r.errors.map((e) => `${e.message} (${e.code})`).join('; ')}`)
+  }
+  return out
+}
+
+/** The starter-asset directory of the theme being built (set by buildManifest). */
+let STARTER_DIR = null
+
+/** Stored values: '' is "not set" (absent key); an inline starter SVG becomes its asset reference. */
+function cleanValues(settings) {
+  const out = {}
+  for (const [k, v] of Object.entries(settings ?? {})) {
+    if (v === '' || v === null || v === undefined) continue
+    out[k] = (STARTER_DIR && starterAssetFor(v, STARTER_DIR)) || v
+  }
+  return out
+}
+
+function contentNode(node) {
+  const out = { type: node.type, id: node.id }
+  const settings = cleanValues(node.settings)
+  if (Object.keys(settings).length) out.settings = settings
+  if (Array.isArray(node.blocks) && node.blocks.length) out.blocks = node.blocks.map(contentNode)
+  if (node.disabled === true) out.disabled = true
+  return out
+}
+
+/** Validate every stored setting value of a node tree against its component's attributes. */
+function checkNodes(where, nodes, components, problems, starterFiles, depth = 0) {
+  nodes.forEach((n, i) => {
+    const at = `${where}[${i}]`
+    const c = components[n.type]
+    if (!c) {
+      problems.push(`${at}: component "${n.type}" is not declared`)
+      return
+    }
+    if (!/^[A-Za-z0-9][A-Za-z0-9._-]*$/.test(n.id ?? '') || n.id.length > 64) problems.push(`${at}: node id ${JSON.stringify(n.id)} does not match the ABI id pattern`)
+    for (const [k, v] of Object.entries(n.settings ?? {})) {
+      const spec = c.attributes[k]
+      if (!spec) {
+        problems.push(`${at}.settings.${k}: not an attribute of "${n.type}"`)
+        continue
+      }
+      const r = checkValue(spec.type, v, spec, { assetAllowed: true, starterFiles })
+      if (!r.ok) problems.push(`${at}.settings.${k} ${JSON.stringify(v).slice(0, 80)}: ${r.errors.map((e) => `${e.message} (${e.code})`).join('; ')}`)
+    }
+    if (n.blocks) checkNodes(`${at}.blocks`, n.blocks, components, problems, starterFiles, depth + 1)
+  })
+}
+
+export function buildManifest(themeDir) {
+  const v1 = readJson(join(themeDir, 'theme.manifest.json'))
+  const pkg = readJson(join(themeDir, 'package.json'))
+  const problems = []
+  const starterDir = join(themeDir, STARTER_ASSET_DIR)
+  STARTER_DIR = starterDir
+  // Templates first: their inline starter SVGs become files here before the file list is read.
+  for (const file of readdirSync(join(themeDir, 'templates')).filter((f) => f.endsWith('.json'))) {
+    const walkValues = (nodes) => { for (const n of nodes ?? []) { cleanValues(n.settings); walkValues(n.blocks) } }
+    const doc = readJson(join(themeDir, 'templates', file))
+    walkValues(doc.sections)
+    walkValues(Array.isArray(doc.groups?.header?.override) ? doc.groups.header.override : [])
+  }
+  const starterFiles = new Set(existsSync(starterDir) ? readdirSync(starterDir) : [])
+
+  // ── components ─────────────────────────────────────────────────────────
+  const components = {}
+  const sources = {}
+  for (const s of v1.sections) {
+    const where = `sections/${s.name}`
+    const attributes = {}
+    for (const [k, spec] of Object.entries(s.attributes ?? {})) {
+      const f = fieldSpec(`${where}.attributes.${k}`, spec, problems)
+      if (f) attributes[k] = f
+    }
+    const c = { role: s.role, title: s.title, attributes }
+    if (s.description) c.description = s.description
+    if (s.category) c.category = s.category
+    if (s.icon) c.icon = s.icon
+    if (s.role === 'section' || s.role === 'layout') {
+      const areas = s.placement?.areas ?? ['template']
+      c.regions = areas.map((a) => AREA_TO_REGION[a] ?? a)
+      if (s.name === 'announcement-bar') c.regions = ['announcement', ...c.regions]
+    }
+    if (s.role === 'block' && s.placement?.parents?.length) c.parents = s.placement.parents
+    if (s.allowedBlocks?.length) c.children = s.allowedBlocks
+    const requires = (s.requiresContext ?? []).map((x) => CONTEXT_TO_ROUTE[x]).filter(Boolean)
+    if (requires.length) c.requires = requires
+    if (s.presets?.length) {
+      c.presets = s.presets.map((p, pi) => {
+        const preset = {}
+        if (p.name) preset.name = p.name
+        const ps = cleanValues(p.settings)
+        if (Object.keys(ps).length) preset.settings = ps
+        if (p.blocks?.length) preset.blocks = p.blocks.map((b, bi) => contentNode({ ...b, id: b.id ?? `${s.name}-preset${pi}-${bi}` }))
+        return preset
+      })
+    }
+    components[s.name] = c
+    sources[s.name] = { source: s.source, sourceHash: s.sourceHash }
+  }
+  for (const [cid, c] of Object.entries(components)) {
+    c.presets?.forEach((p, i) => {
+      for (const [k, v] of Object.entries(p.settings ?? {})) {
+        const spec = c.attributes[k]
+        if (!spec) { problems.push(`components.${cid}.presets[${i}].settings.${k}: not an attribute`); continue }
+        const r = checkValue(spec.type, v, spec, { assetAllowed: true, starterFiles })
+        if (!r.ok) problems.push(`components.${cid}.presets[${i}].settings.${k}: ${r.errors.map((e) => e.message).join('; ')}`)
+      }
+      if (p.blocks) checkNodes(`components.${cid}.presets[${i}].blocks`, p.blocks, components, problems, starterFiles)
+    })
+  }
+
+  // ── global settings ────────────────────────────────────────────────────
+  const settingsSchema = v1.settingsSchema.map((g) => ({
+    group: g.group,
+    items: g.items.map((it) => ({ key: it.key, ...fieldSpec(`settingsSchema.${g.group}.${it.key}`, it, problems) })),
+  }))
+  const settingSpecs = new Map(settingsSchema.flatMap((g) => g.items.map((it) => [it.key, it])))
+
+  // ── templates + starter content ────────────────────────────────────────
+  const templates = {}
+  const defaultsTemplates = {}
+  const tplDir = join(themeDir, 'templates')
+  for (const file of readdirSync(tplDir).filter((f) => f.endsWith('.json')).sort()) {
+    const name = file.replace(/\.json$/, '')
+    const route = TEMPLATE_ROUTE[name]
+    if (!route) { problems.push(`templates/${file}: no route kind mapping`); continue }
+    const doc = readJson(join(tplDir, file))
+    const regions = {}
+    const order = []
+    const header = doc.groups?.header
+    if (header && typeof header === 'object' && Array.isArray(header.override)) {
+      // v1 per-page header override: the announcement bar moves to the template-scoped region;
+      // the header section itself must match the shared header (a shared region has one doc).
+      const bar = header.override.filter((n) => n.type === 'announcement-bar')
+      const rest = header.override.filter((n) => n.type !== 'announcement-bar')
+      if (bar.length) { regions.announcement = { sections: bar.map(contentNode) }; order.push('announcement') }
+      if (rest.some((n) => n.type !== 'header')) problems.push(`templates/${file}: header override carries ${rest.map((n) => n.type).join(', ')} — only an announcement bar can be per-template`)
+    }
+    order.push('header', 'main', 'footer')
+    regions.main = { sections: doc.sections.filter((s) => !s.area || s.area === 'template').map(contentNode) }
+    if (doc.sections.some((s) => s.area && s.area !== 'template')) problems.push(`templates/${file}: inline header/footer sections`)
+    templates[name] = { route, regions: order }
+    const tdoc = { contentVersion: CONTENT_VERSION, template: name, regions }
+    defaultsTemplates[name] = tdoc
+    for (const [rid, r] of Object.entries(regions)) checkNodes(`defaults/templates/${name}.regions.${rid}.sections`, r.sections, components, problems, starterFiles)
+  }
+
+  const defaultsRegions = {}
+  for (const region of ['header', 'footer']) {
+    const g = readJson(join(themeDir, 'groups', `${region}.json`))
+    defaultsRegions[region] = { contentVersion: CONTENT_VERSION, region, sections: g.sections.map(contentNode) }
+    checkNodes(`defaults/regions/${region}.sections`, defaultsRegions[region].sections, components, problems, starterFiles)
+  }
+
+  const values = {}
+  const cfg = readJson(join(themeDir, 'config', 'settings.json'))
+  for (const [k, v] of Object.entries(cfg)) {
+    if (v === '' || v === null) continue // "not set" is an absent key
+    const spec = settingSpecs.get(k)
+    if (!spec) { problems.push(`config/settings.json.${k}: not in the settings schema`); continue }
+    const r = checkValue(spec.type, v, spec, { assetAllowed: true, starterFiles })
+    if (!r.ok) { problems.push(`config/settings.json.${k} ${JSON.stringify(v)}: ${r.errors.map((e) => `${e.message} (${e.code})`).join('; ')}`); continue }
+    values[k] = v
+  }
+
+  const manifest = {
+    abi: '2.0',
+    name: '@tanqory-theme/nova',
+    version: pkg.version,
+    engines: { 'tanqory-abi': '^2.0', 'tanqory-field-types': FIELD_TYPES_REGISTRY },
+    capabilities: { server: SERVER_CAPABILITIES, browser: BROWSER_CAPABILITIES },
+    client: { hydration: 'full' },
+    // The platform forms Nova posts (`<form data-tq-form="<id>" method="post">`, components/forms): the field names
+    // each form renders — the gateway delivers only these to the render. `website` is the honeypot.
+    // `turnstileToken` is a Turnstile widget's token (its data-response-field-name): the edge's form.submit forwards
+    // it to store-api as the `turnstile-token` header. Nova renders no widget yet, so nothing posts it today.
+    forms: {
+      contact: { title: 'Contact', fields: ['name', 'email', 'phone', 'message', 'website', 'turnstileToken'] },
+      newsletter: { title: 'Newsletter', fields: ['email', 'consent', 'website', 'turnstileToken'] },
+    },
+    contentVersion: CONTENT_VERSION,
+    routes: ROUTES,
+    customRoutes: CUSTOM_ROUTES,
+    templates,
+    regions: REGIONS,
+    components,
+    settingsSchema,
+    'x-nova': {
+      contract: v1.contract,
+      generatedFrom: v1.generatedFrom,
+      stats: v1.stats,
+      warnings: v1.warnings,
+      sharedAttributes: Object.keys(v1.sharedAttributes ?? {}),
+      contentSlots: v1.contentSlots,
+      sources,
+    },
+  }
+
+  const result = validateManifest(manifest)
+  if (!result.ok) for (const e of result.errors) problems.push(`manifest${e.path}: ${e.message} (${e.code ?? e.keyword})`)
+
+  return {
+    manifest,
+    defaults: { settings: { contentVersion: CONTENT_VERSION, values }, regions: defaultsRegions, templates: defaultsTemplates },
+    problems,
+    starterFiles: [...starterFiles].sort(),
+  }
+}

package/templates/nova/scripts/abi/starter-assets.mjs

@@ -0,0 +1,32 @@
+/**
+ * Starter images as theme assets (theme-abi-v2.md Appendix B.2).
+ *
+ * The redesign's starter templates carry inline `data:image/svg+xml,…` placeholders. Content may
+ * hold only https media, and defaults/presets may hold `asset:client/assets/<file>` naming a file
+ * the artifact ships. So, at build time, each distinct inline SVG becomes a file under
+ * assets/starter/ named by the platform's one asset rule (`<stem>-<h8>.svg`, self-hashed:
+ * build-service asset-naming.mjs), and the default value becomes its `asset:` reference.
+ *
+ * The source templates keep the inline form on purpose: they are also the editor workspace's base,
+ * and merchant content may never carry `asset:` (studio-api drops a `data:` value on export, and
+ * the edge then renders this default).
+ */
+import { createHash } from 'node:crypto'
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs'
+import { join } from 'node:path'
+
+const PREFIX = 'data:image/svg+xml,'
+const h8 = (bytes) => createHash('sha256').update(bytes).digest('hex').slice(0, 8)
+
+/** `data:image/svg+xml,…` → `asset:client/assets/<file>`, writing the file into `dir` when absent. */
+export function starterAssetFor(value, dir) {
+  if (typeof value !== 'string' || !value.startsWith(PREFIX)) return null
+  const svg = Buffer.from(decodeURIComponent(value.slice(PREFIX.length)), 'utf8')
+  const dims = /\bwidth="(\d+)"\s+height="(\d+)"/.exec(svg.toString('utf8'))
+  const stem = dims ? `starter-art-${dims[1]}x${dims[2]}` : 'starter-image'
+  const file = `${stem}-${h8(svg)}.svg`
+  mkdirSync(dir, { recursive: true })
+  const path = join(dir, file)
+  if (!existsSync(path) || !readFileSync(path).equals(svg)) writeFileSync(path, svg)
+  return `asset:client/assets/${file}`
+}

package/templates/nova/scripts/compiler/checks/check-a11y.mjs

@@ -0,0 +1,88 @@
+#!/usr/bin/env node
+/**
+ * Accessibility gate — the real engine, not a hand-rolled probe.
+ *
+ * Every accessibility check in this repo before this one was written by hand,
+ * so it only ever looked for what someone thought to look for.
+ * `@accesslint/cli` runs the rule set a specialist audit would: on its first
+ * run it found 195 violations across ten routes, none of which the 209 unit
+ * tests could see — a button nested inside a link, duplicate ARIA ids, an
+ * accessible name that contradicted its visible label, a video with no
+ * captions, two banner landmarks per page.
+ *
+ * EACH ROUTE IS SCANNED TWICE and only violations present in BOTH runs are
+ * reported. Scanning a client-rendered page races the render: the same route
+ * came back with two, three or four violations run to run, and a footer
+ * disclosure that plainly has a name was reported empty 27 times. A finding
+ * that survives two independent scans is about the page; one that does not is
+ * about the scanner.
+ *
+ *   pnpm check:a11y          # needs the dev server running
+ *   THEME_URL=... pnpm check:a11y
+ */
+import { execFileSync } from 'node:child_process'
+
+const BASE = process.env.THEME_URL ?? 'http://localhost:4321'
+const ROUTES = {
+  home: '/',
+  product: '/products/classic-double-breasted-blazer',
+  collection: '/collections/test-collection',
+  collections: '/collections',
+  cart: '/cart',
+  contact: '/contact',
+  search: '/search?q=blazer',
+  account: '/account',
+  policy: '/policies/privacy-policy',
+  'not-found': '/no-such-page',
+}
+/** The last thing on the page to get its content, so the scan starts after the
+ *  menus have resolved rather than during. */
+const SETTLED = '.site-footer__col-title'
+
+function scan(url) {
+  let out
+  try {
+    out = execFileSync(
+      'npx',
+      ['-y', '@accesslint/cli@latest', 'scan', url,
+       '--wait-for', SETTLED, '--wait-timeout', '20000', '--format', 'json'],
+      { encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'], maxBuffer: 64 * 1024 * 1024 },
+    )
+  } catch (e) {
+    out = e.stdout || ''
+  }
+  try {
+    return JSON.parse(out).violations ?? []
+  } catch {
+    // The scanner truncates its own JSON on very large reports; that is itself
+    // worth surfacing rather than silently passing.
+    return [{ ruleId: 'scanner/unreadable-output', impact: 'serious', html: url }]
+  }
+}
+
+/** What identifies one finding, so two runs can be compared. */
+const key = (v) => `${v.ruleId ?? v.id}|${(v.selector ?? '').slice(0, 120)}`
+
+let total = 0
+const byRule = new Map()
+for (const [name, route] of Object.entries(ROUTES)) {
+  const url = BASE + route
+  const first = new Map(scan(url).map((v) => [key(v), v]))
+  const second = new Map(scan(url).map((v) => [key(v), v]))
+  const stable = [...first.keys()].filter((k) => second.has(k)).map((k) => first.get(k))
+  const flaky = first.size + second.size - stable.length * 2
+  for (const v of stable) {
+    total++
+    const id = v.ruleId ?? v.id
+    byRule.set(id, (byRule.get(id) ?? 0) + 1)
+    console.error(`  ${name}: [${v.impact}] ${id}\n      ${(v.html ?? '').replace(/\s+/g, ' ').slice(0, 100)}`)
+  }
+  if (flaky > 0) console.error(`  ${name}: ${flaky} finding(s) appeared in only one of two scans — ignored`)
+}
+
+if (total) {
+  console.error(`\n✗ ${total} accessibility violation(s) reproducible across two scans`)
+  for (const [id, n] of [...byRule].sort((a, b) => b[1] - a[1])) console.error(`    ${n}x ${id}`)
+  process.exit(1)
+}
+console.log(`✓ no reproducible accessibility violations across ${Object.keys(ROUTES).length} routes`)