create-tanqory-theme 0.0.0-stage → 0.2.3

package/templates/nova/scripts/compiler/migrate/migrate-content.mjs

@@ -0,0 +1,171 @@
+#!/usr/bin/env node
+/**
+ * Content migration for renamed section settings.
+ *
+ * Renaming an attribute orphans every saved value under the old key — the
+ * theme's own templates AND every merchant's customised copy. `k8s.mjs` merges
+ * theme updates by path prefix with no content version, so nothing else will
+ * carry those values across.
+ *
+ * This script migrates the theme's shipped templates. Merchant content needs
+ * the same map applied at publish time; the RENAMES table below is the record
+ * of what changed, and is intentionally append-only.
+ *
+ *   node scripts/migrate-content.mjs [--dry]
+ */
+import { readdirSync, readFileSync, writeFileSync } 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()
+const DRY = process.argv.includes('--dry')
+
+/** section/block type → { oldKey: newKey | [newKey, transform] } */
+const RENAMES = {
+  // 2026-09-18 — design conversion: semantic presets replace raw values.
+  slideshow: {
+    size: 'slideHeight',
+    intervalMs: ['interval', (ms) => (ms <= 4000 ? '4s' : ms >= 8000 ? '8s' : '6s')],
+    showDots: ['controls', (on) => (on ? 'arrows+counter' : 'none')],
+  },
+  divider: {
+    height: ['spacing', (px) => (px <= 16 ? 'sm' : px <= 48 ? 'md' : px <= 96 ? 'lg' : 'xl')],
+    showLine: ['style', (on) => (on ? 'line-subtle' : 'space')],
+    color: null, // dropped: raw colour is not a design control
+  },
+  group: {
+    gap: ['innerGap', (px) => (px <= 12 ? 'small' : px <= 24 ? 'medium' : 'large')],
+  },
+  'featured-collection': {
+    limit: ['productsToShow', (n) => Math.max(2, Math.min(12, Number(n) || 4))],
+  },
+  'main-collection': {
+    limit: ['productsPerPage', (n) => String([12, 24, 48].includes(Number(n)) ? n : 24)],
+  },
+  'rich-text': {
+    align: 'contentAlignment',
+  },
+  'image-with-text': {
+    imageRight: ['mediaPosition', (on) => (on ? 'right' : 'left')],
+  },
+  'contact-form': {
+    showPhone: ['fields', (on) => (on ? 'name,email,phone,message' : 'name,email,message')],
+  },
+  marquee: {
+    speed: ['speed', (v) => (typeof v === 'number' ? (v >= 34 ? 'slow' : v <= 16 ? 'fast' : 'standard') : v)],
+    bg: ['background', (hex) => (String(hex).toLowerCase() === '#ffffff' ? 'surface' : 'primary')],
+    fg: null,
+  },
+  newsletter: {
+    inverse: ['background', (on) => (on ? 'primary' : 'surface-secondary')],
+  },
+  'feature-highlights': {
+    textAlign: 'textAlignment',
+    background: ['background', (v) => (typeof v === 'string' && v.startsWith('#') ? 'surface' : v || 'surface')],
+  },
+  'announcement-bar': {
+    bg: ['background', (hex) => (String(hex).toLowerCase() === '#ffffff' ? 'surface-secondary' : 'primary')],
+    fg: null,
+  },
+}
+
+/**
+ * Global theme settings whose VALUE vocabulary changed, not their key.
+ * `config/settings.json` and every merchant's copy hold the old word, and a
+ * value that is no longer in the select silently falls back to the default —
+ * so a merchant who chose "Bold" icons would land on the theme default with no
+ * warning. Append-only, same as RENAMES.
+ */
+const VALUE_RENAMES = {
+  // 2026-09-20 — realigned onto the approved design package (06 Configuration
+  // System), which the theme had drifted from on both axis and vocabulary.
+  typeScale: { standard: 'default', spacious: 'large' },
+  buttonTextStyle: { sentence: 'default' },
+  // badgeStyle was a SHAPE (square|pill); the design's axis is fill.
+  badgeStyle: { square: 'filled', pill: 'filled' },
+  // iconStyle was a WEIGHT (light|regular|bold); the design's axis is family.
+  iconStyle: { light: 'outline', regular: 'outline', bold: 'filled' },
+  cardHoverEffect: { zoom: 'image-swap', border: 'image-swap' },
+  motion: { none: 'reduced', subtle: 'standard' },
+  productImageRatio: { tall: 'landscape' },
+  // buttonBorder became a role rather than an on/off.
+  buttonBorder: { true: 'default', false: 'default' },
+}
+
+let changed = 0
+const log = []
+
+function migrateNode(node) {
+  const map = RENAMES[node.type]
+  if (map && node.settings) {
+    for (const [oldKey, target] of Object.entries(map)) {
+      if (!(oldKey in node.settings)) continue
+      const value = node.settings[oldKey]
+      // A same-key entry is a VALUE rename. Once the value is already the new
+      // one there is nothing to do — counting it made every run report work.
+      if (Array.isArray(target) && target[0] === oldKey && JSON.stringify(target[1](value)) === JSON.stringify(value)) continue
+      delete node.settings[oldKey]
+      changed += 1
+      if (target === null) {
+        log.push(`  ${node.type}.${oldKey} dropped (was ${JSON.stringify(value)})`)
+        continue
+      }
+      const [newKey, transform] = Array.isArray(target) ? target : [target, (v) => v]
+      // Never clobber a value the merchant already set under the new name.
+      if (node.settings[newKey] === undefined) node.settings[newKey] = transform(value)
+      log.push(`  ${node.type}.${oldKey} → ${newKey} = ${JSON.stringify(node.settings[newKey])}`)
+    }
+  }
+  for (const child of node.blocks ?? []) migrateNode(child)
+}
+
+const dir = join(ROOT, 'templates')
+for (const file of readdirSync(dir).filter((f) => f.endsWith('.json'))) {
+  const path = join(dir, file)
+  const before = readFileSync(path, 'utf8')
+  const doc = JSON.parse(before)
+  const start = changed
+  for (const s of doc.sections ?? []) migrateNode(s)
+  if (changed > start && !DRY) writeFileSync(path, `${JSON.stringify(doc, null, 2)}\n`)
+  if (changed > start) console.log(`${file}:`)
+}
+// ── Global theme settings ───────────────────────────────────────────────────
+/**
+ * Global settings whose KEY changed. The schema follows the approved design
+ * package's names; these are the names an earlier build saved under.
+ * app/platform/safe-values.ts still reads the old key as a fallback, so a store that
+ * has not been migrated keeps its colours and fonts. Append-only.
+ */
+const SETTING_KEY_RENAMES = {
+  colorBrand: 'colorPrimary',
+  fontHeading: 'headingFont',
+  fontBody: 'bodyFont',
+}
+const settingsPath = join(ROOT, 'config', 'settings.json')
+const settings = JSON.parse(readFileSync(settingsPath, 'utf8'))
+const settingsStart = changed
+for (const [oldKey, newKey] of Object.entries(SETTING_KEY_RENAMES)) {
+  if (!(oldKey in settings)) continue
+  const value = settings[oldKey]
+  delete settings[oldKey]
+  // A value already saved under the new name wins; an empty one does not.
+  if (settings[newKey] === undefined || settings[newKey] === '') settings[newKey] = value
+  log.push(`  settings.${oldKey} → ${newKey} = ${JSON.stringify(settings[newKey])}`)
+  changed += 1
+}
+for (const [key, map] of Object.entries(VALUE_RENAMES)) {
+  if (!(key in settings)) continue
+  const next = map[String(settings[key])]
+  if (next === undefined) continue
+  log.push(`  settings.${key}: ${JSON.stringify(settings[key])} → ${JSON.stringify(next)}`)
+  settings[key] = next
+  changed += 1
+}
+if (changed > settingsStart) {
+  console.log('config/settings.json:')
+  if (!DRY) writeFileSync(settingsPath, `${JSON.stringify(settings, null, 2)}\n`)
+}
+
+console.log(log.join('\n'))
+console.log(changed === 0 ? '✓ no orphaned settings' : `${DRY ? 'would migrate' : '✓ migrated'} ${changed} setting(s)`)

package/templates/nova/scripts/compiler/migrate/migrate-groups.mjs

@@ -0,0 +1,159 @@
+#!/usr/bin/env node
+/**
+ * Move the per-template header/footer copies into shared groups.
+ *
+ *   node scripts/migrate-groups.mjs            # migrate, print the report
+ *   node scripts/migrate-groups.mjs --check    # exit 1 if a run would change anything
+ *   node scripts/migrate-groups.mjs --dry      # report only, write nothing
+ *   node scripts/migrate-groups.mjs --inline   # ROLLBACK: fold the groups back into every template
+ *
+ * Before: 17 of 18 templates carried their own copy of the header and footer,
+ * so "edit the header" meant editing one page. After: `groups/header.json` and
+ * `groups/footer.json` are the single source of truth, templates reference
+ * them, and a page that is deliberately different keeps its own copy as an
+ * explicit `override` — printed here, never merged away.
+ *
+ * The logic is the kit contract's `extractGroups`, which the studio-api
+ * migration path calls too. This file only reads the theme, feeds the section
+ * defaults (so `{}` and `{ sticky: 'always' }` compare equal), writes what
+ * comes back, and prints the report. Idempotent: `--check` on a migrated theme
+ * passes, which is what CI runs.
+ */
+import { readFileSync, writeFileSync, readdirSync, mkdirSync, existsSync } from 'node:fs'
+import { join, dirname } from 'node:path'
+import { fileURLToPath } from 'node:url'
+import { spawnSync } from 'node:child_process'
+
+// The contract is the theme's own TypeScript (app/platform/tanqory/contract). A plain
+// `node scripts/migrate-groups.mjs` re-executes itself with type stripping on
+// so callers (tests, CI, a developer) need no flag.
+if (!process.execArgv.some((a) => a.includes('strip-types')) && !process.features?.typescript) {
+  const r = spawnSync(process.execPath, ['--experimental-strip-types', '--no-warnings', ...process.argv.slice(1)], { stdio: 'inherit' })
+  process.exit(r.status ?? 1)
+}
+const { extractGroups, resolvePage } = await import('@tanqory/theme-kit/contract')
+
+// The theme: the directory the command runs in.
+const ROOT = process.cwd()
+const TEMPLATES = join(ROOT, 'templates')
+const GROUPS = join(ROOT, 'groups')
+const CHECK = process.argv.includes('--check')
+const DRY = process.argv.includes('--dry')
+const INLINE = process.argv.includes('--inline')
+
+const read = (p) => JSON.parse(readFileSync(p, 'utf8'))
+const stringify = (o) => JSON.stringify(o, null, 2) + '\n'
+
+// Attribute defaults per section type, from the generated manifest — the same
+// source the runtime applies at render, so the comparison is what a shopper sees.
+const manifest = read(join(ROOT, 'theme.manifest.json'))
+const defaults = {}
+for (const s of manifest.sections) {
+  defaults[s.name] = {}
+  for (const [k, spec] of Object.entries(s.attributes ?? {})) {
+    if (spec?.default !== undefined) defaults[s.name][k] = spec.default
+  }
+}
+
+const templates = {}
+for (const f of readdirSync(TEMPLATES).filter((x) => x.endsWith('.json')).sort()) {
+  templates[f.replace(/\.json$/, '')] = read(join(TEMPLATES, f))
+}
+
+// ── rollback: groups → inline copies (content version 1) ──────────────────
+// The exact inverse of the migration, through the same resolver the runtime
+// uses: every template gets the header/footer it currently RENDERS written
+// back as inline `area` nodes, the `groups` binding and `contentVersion` are
+// dropped, and groups/ is left in place (harmless to a v1 reader; delete it
+// by hand once nothing references it). Running the migration again afterwards
+// reproduces the bindings, so this is a round trip, not a one-way door.
+if (INLINE) {
+  const groupDocs = {}
+  if (existsSync(GROUPS)) {
+    for (const f of readdirSync(GROUPS).filter((x) => x.endsWith('.json'))) groupDocs[f.replace(/\.json$/, '')] = read(join(GROUPS, f))
+  }
+  let n = 0
+  for (const [slug, doc] of Object.entries(templates)) {
+    if (!doc.groups && doc.contentVersion === undefined) continue
+    const r = resolvePage(doc, groupDocs)
+    if (r.missingGroups.length) { console.error(`✗ ${slug}: binds missing group(s) ${r.missingGroups.join(', ')} — nothing written`); process.exit(1) }
+    const { groups: _g, contentVersion: _v, ...rest } = doc
+    const inlined = { ...rest, sections: r.sections.map(({ area, ...node }) => (area && area !== 'template' ? { ...node, area } : node)) }
+    if (DRY) { console.log(`would inline ${slug} (${r.sections.length} sections)`); continue }
+    writeFileSync(join(TEMPLATES, `${slug}.json`), stringify(inlined))
+    n++
+  }
+  console.log(DRY ? '(dry run — nothing written)' : `✓ folded the shared groups back into ${n} template(s); groups/ left in place`)
+  process.exit(0)
+}
+
+const { groups, templates: next, report, noop } = extractGroups(templates, { defaults })
+
+// ── report ────────────────────────────────────────────────────────────────
+for (const r of report) {
+  console.log(`\n${r.slot.toUpperCase()} → groups/${r.group}.json`)
+  if (r.alreadyBound.length) console.log(`  already bound (${r.alreadyBound.length}): ${r.alreadyBound.join(', ')}`)
+  if (r.canonical.templates.length) console.log(`  shared by (${r.canonical.templates.length}): ${r.canonical.templates.join(', ')}`)
+  for (const o of r.overrides) {
+    console.log(`  ⚠ ${o.template} DIFFERS — kept as an explicit override:`)
+    for (const d of o.differences) console.log(`      ${d}`)
+  }
+  for (const m of r.idRemaps) console.log(`  ↻ ${m.template}: id ${m.from} → ${m.to} (same content, takes the group's id)`)
+  if (r.empty.length) console.log(`  ∅ no ${r.slot} at all: ${r.empty.join(', ')}`)
+}
+
+if (CHECK) {
+  // A bound template whose group file is missing renders without its chrome.
+  // `extractGroups` has nothing to migrate in that state, so check it here.
+  const dangling = []
+  for (const [slug, doc] of Object.entries(templates)) {
+    for (const [slot, v] of Object.entries(doc.groups ?? {})) {
+      const name = typeof v === 'string' ? v : v && typeof v === 'object' && 'ref' in v ? v.ref : null
+      if (name && !existsSync(join(GROUPS, `${name}.json`))) dangling.push(`${slug}.${slot} → groups/${name}.json`)
+    }
+  }
+  if (dangling.length) {
+    console.error(`\n✗ template(s) bind a group that does not exist:\n  ${dangling.join('\n  ')}`)
+    process.exit(1)
+  }
+  if (noop) {
+    console.log('\n✓ groups are up to date — a migration run would change nothing')
+    process.exit(0)
+  }
+  console.error('\n✗ templates still carry inline header/footer copies. Run `node scripts/migrate-groups.mjs`.')
+  process.exit(1)
+}
+
+if (noop) {
+  console.log('\n✓ nothing to migrate')
+  process.exit(0)
+}
+if (DRY) {
+  console.log('\n(dry run — nothing written)')
+  process.exit(0)
+}
+
+// ── write ─────────────────────────────────────────────────────────────────
+mkdirSync(GROUPS, { recursive: true })
+for (const g of Object.values(groups)) {
+  const file = join(GROUPS, `${g.name}.json`)
+  if (existsSync(file)) {
+    // A re-run with a new canonical would overwrite a group somebody edited.
+    // extractGroups only produces a group when inline copies still exist, so
+    // reaching here means a template was un-migrated by hand; refuse rather
+    // than clobber.
+    console.error(`✗ ${file} already exists — will not overwrite a shared group. Bind the template by hand.`)
+    process.exit(1)
+  }
+  writeFileSync(file, stringify({ type: g.doc.type, name: g.name[0].toUpperCase() + g.name.slice(1), sections: g.doc.sections }))
+  console.log(`\n✓ wrote groups/${g.name}.json`)
+}
+let rewritten = 0
+for (const [slug, doc] of Object.entries(next)) {
+  const before = stringify(templates[slug])
+  const after = stringify({ contentVersion: 2, ...doc })
+  if (before === after) continue
+  writeFileSync(join(TEMPLATES, `${slug}.json`), after)
+  rewritten++
+}
+console.log(`✓ rewrote ${rewritten} template(s)`)

package/templates/nova/scripts/parity/case-shim.ts

@@ -0,0 +1,14 @@
+/**
+ * tests/support/case for the parity page: the same types and helpers, without vitest or the
+ * testing library (the parity page never runs a `play`).
+ */
+export type { Meta, StoryObj, CaseModule, CaseContext, Decorator, NovaParams } from '../../tests/support/case'
+
+const noop = (..._a: unknown[]) => undefined
+export const fn = <T extends (...a: never[]) => unknown>(impl?: T) => (impl ?? noop) as T
+export const expect = noop
+export const within = noop
+export const waitFor = noop
+export const screen = {}
+export const fireEvent = {}
+export const userEvent = {}

package/templates/nova/scripts/parity/emit.ts

@@ -0,0 +1,206 @@
+/**
+ * The parity pages' content and data for the ABI host, derived from the same stories:
+ *
+ *   npx vite-node --config scripts/parity/vite.config.ts scripts/parity/emit.ts -- <outDir>
+ *
+ * writes <outDir>/wire/*.json   recorded wire answers (the local host's `--data`), the story fixtures
+ *                                converted to Theme ABI records (the inverse of @tanqory/theme-kit abi/convert.ts +
+ *                                runtime/data/to-ui.ts)
+ *        <outDir>/content.json  a ContentRevision whose section settings are the stories' args
+ *        <outDir>/cart.json     the cart story's lines as ABI cart lines (the local host's `--cart`)
+ */
+import { mkdirSync, writeFileSync } from 'node:fs'
+import { join } from 'node:path'
+import type { Collection, NovaImage, NovaMenu, NovaMenuItem, Product, Article } from '@tanqory/theme-kit'
+import { sectionRegistry } from '../../tests/support/sections'
+import * as fx from '../../tests/fixtures/index'
+import * as sc from '../../tests/support/story-content'
+import { FOOTER, HEADER, PAGES, argsOf, type Entry } from './pages'
+
+const out = process.argv.slice(2).filter((a) => a !== '--')[0]
+if (!out) throw new Error('usage: emit.ts <outDir>')
+const wireDir = join(out, 'wire')
+mkdirSync(wireDir, { recursive: true })
+
+// ── the local host's file naming (scripts/abi/local-host.mjs fileOf) ───────────────────────────
+const canon = (v: unknown): string =>
+  v === null || typeof v !== 'object' ? JSON.stringify(v) : Array.isArray(v) ? `[${v.map(canon).join(',')}]` : `{${Object.keys(v as object).sort().map((k) => `${JSON.stringify(k)}:${canon((v as Record<string, unknown>)[k])}`).join(',')}}`
+const b64 = (s: string) => Buffer.from(s).toString('base64').replace(/\+/g, '-').replace(/\//g, '_').replace(/=+$/, '')
+const put = (op: string, args: unknown[], data: unknown) =>
+  writeFileSync(join(wireDir, `${op}${args.length ? '-' + b64(canon(args)) : ''}.json`.replace(/[^A-Za-z0-9._-]/g, '_')), JSON.stringify({ ok: true, data, dataVersion: 'parity' }))
+
+// ── UI fixtures → ABI records ──────────────────────────────────────────────────────────────────
+const money = (m: { amount: number; currencyCode: string }) => ({ amount: m.amount.toFixed(m.currencyCode === 'JPY' ? 0 : 2), currencyCode: m.currencyCode })
+const img = (i: NovaImage | null | undefined) => (i ? { url: i.src, ...(i.alt ? { altText: i.alt } : {}), ...(i.width ? { width: i.width } : {}), ...(i.height ? { height: i.height } : {}) } : null)
+const conn = <T>(nodes: T[], totalCount = nodes.length) => ({ nodes, pageInfo: { hasNextPage: false, endCursor: null }, totalCount })
+const seo = { title: null, description: null }
+
+function product(p: Product) {
+  // A card fixture may state a price range its variants do not carry (the board is "From $74",
+  // every variant $74): the platform derives the range from the variants, so give the top one the max.
+  const variants = p.variants.map((v) => ({ ...v }))
+  const top = Math.max(...variants.map((v) => v.price.amount))
+  if (variants.length > 1 && p.priceRange.max.amount > top) variants[variants.length - 1].price = { ...p.priceRange.max }
+  return {
+    id: p.id, handle: p.handle, title: p.title,
+    descriptionHtml: p.descriptionHtml ?? (p.description ? `<p>${p.description}</p>` : ''),
+    vendor: p.vendor ?? '', productType: p.productType ?? '', tags: [...(p.tags ?? [])],
+    availableForSale: p.available,
+    featuredImage: img(p.featuredImage), images: p.images.map(img).filter(Boolean),
+    options: p.options.map((o) => ({ name: o.name, values: [...o.values] })),
+    variants: conn(variants.map((v) => ({
+      id: v.id, title: v.title, sku: v.sku ?? null, availableForSale: v.available,
+      price: money(v.price), compareAtPrice: v.compareAtPrice ? money(v.compareAtPrice) : null,
+      selectedOptions: v.selectedOptions.map((o) => ({ name: o.name, value: o.value })), image: null,
+      // As the platform sends it with data:inventory and stock levels shown (0–999, 999 = "999 or more").
+      ...(typeof v.quantityAvailable === 'number' ? { quantityAvailable: Math.min(999, Math.max(0, Math.floor(v.quantityAvailable))) } : {}),
+    }))),
+    priceRange: { minVariantPrice: money(p.priceRange.min), maxVariantPrice: money(p.priceRange.max) },
+    ...(p.compareAtPriceRange ? { compareAtPriceRange: { minVariantPrice: money(p.compareAtPriceRange.min), maxVariantPrice: money(p.compareAtPriceRange.max) } } : {}),
+    seo, templateSuffix: null,
+  }
+}
+function collection(c: Collection, products = c.products ?? []) {
+  return {
+    id: c.id, handle: c.handle, title: c.title, descriptionHtml: c.description ? `<p>${c.description}</p>` : '',
+    image: img(c.image), products: conn(products.map(product), c.productsCount), seo, templateSuffix: null,
+  }
+}
+let itemSeq = 0
+const menuItem = (i: NovaMenuItem): unknown => ({ id: `mi-${++itemSeq}`, title: i.title, url: i.url ?? '/', type: 'HTTP', items: (i.items ?? []).map(menuItem) })
+const menu = (m: NovaMenu) => ({ handle: m.handle, title: m.title, items: m.items.map(menuItem) })
+const article = (a: Article) => ({
+  id: a.id, handle: a.handle, title: a.title, excerpt: a.excerpt ?? null, contentHtml: (a as { contentHtml?: string }).contentHtml ?? '',
+  image: img(a.image), author: a.author ? { name: a.author } : null, publishedAt: a.publishedAt, tags: [...(a.tags ?? [])],
+  blog: { handle: a.blogHandle ?? 'journal' }, seo,
+})
+
+// ── shop + menus ───────────────────────────────────────────────────────────────────────────────
+// The platform only serves https/http image URLs for the brand logo (safe-values normalizeImageUrl
+// drops a data: URL), so the logo is written out and served by `MEDIA` (a static server on the host).
+const MEDIA = process.env.PARITY_MEDIA ?? 'http://localhost:4411'
+mkdirSync(join(out, 'media'), { recursive: true })
+const shop = fx.shopWithLogo
+writeFileSync(join(out, 'media', 'logo.svg'), decodeURIComponent(shop.logo!.src.replace(/^data:image\/svg\+xml;charset=utf-8,/, '')))
+put('shop.get', [], {
+  name: shop.name, description: null, primaryDomain: { url: '' },
+  paymentSettings: { currencyCode: 'USD', enabledPresentmentCurrencies: ['USD'] },
+  shipsToCountries: ['TH', 'JP', 'SG', 'GB', 'US'],
+  brand: { logo: { ...img(shop.logo), url: `${MEDIA}/logo.svg` } },
+})
+const menus = [fx.mainMenu, fx.footerShop, fx.footerHelp, fx.footerCompany, fx.legalMenu]
+put('shop.menus', [], menus.map(menu))
+
+// ── catalog ────────────────────────────────────────────────────────────────────────────────────
+// The collection page lists the listing story's 21 products; its first four are the featured row's.
+const kitchen = { ...fx.merchRooms[0], products: fx.merchListing }
+const collections = [kitchen, ...fx.merchRooms.slice(1), sc.storeNewSeason]
+for (const c of collections) put('catalog.collection', [c.handle, { productsFirst: 24 }], collection(c))
+put('catalog.collections', [{ first: 50 }], conn(collections.map((c) => collection(c, []))))
+const allProducts = new Map<string, Product>()
+for (const p of [...fx.merchProducts, ...fx.merchListing, fx.merchThrow, fx.merchDuvetBlend, fx.merchDuvetPercale, fx.merchSimple, ...sc.storeSearch.products]) allProducts.set(p.handle, p)
+for (const p of allProducts.values()) put('catalog.product', [p.handle], product(p))
+const recs = (argsOf(PAGES.find((p) => p.name === 'product')!.sections.find((s) => s.type === 'product-recommendations')!).products as Product[]).map(product)
+for (const n of [4, 8]) put('catalog.recommendations', [fx.merchDuvet.handle, 'related', n], recs)
+
+// ── search (the server's first page and the browser's) ─────────────────────────────────────────
+const s = sc.storeSearch
+const searchResult = {
+  query: s.query,
+  products: conn(s.products.map(product)),
+  pages: conn(s.pages.map((p, i) => ({ id: `page-${i}`, handle: p.url.split('/').pop(), title: p.title, body: `<p>${p.excerpt ?? ''}</p>`, seo }))),
+  articles: conn(s.articles.map(article)),
+  collections: conn([]),
+}
+for (const first of [24, 48]) put('catalog.search', [{ query: 'linen', first, types: ['product', 'page', 'article'] }], searchResult)
+
+// ── the size guide page (product-details sizeGuidePage) ────────────────────────────────────────
+const pd = argsOf(PAGES.find((p) => p.name === 'product')!.sections.find((x) => x.type === 'product-details')!)
+const guide = pd.sizeGuide as { title: string; html: string }
+put('content.page', ['size-guide'], { id: 'page-size-guide', handle: 'size-guide', title: guide.title, body: guide.html, seo })
+
+// ── the cart story's lines ─────────────────────────────────────────────────────────────────────
+const cartArgs = argsOf(PAGES.find((p) => p.name === 'cart')!.sections[0])
+const cartLines = (cartArgs.cart as typeof sc.storeCart).lines.map((l, i) => {
+  const full = allProducts.get(l.product.handle) ?? fx.merchCandle
+  return {
+    id: `line-${i + 1}`, quantity: l.quantity, attributes: {},
+    merchandise: {
+      id: l.variant.id, title: l.variant.title, sku: l.variant.sku ?? null, availableForSale: l.variant.available,
+      price: money(l.variant.price), compareAtPrice: l.variant.compareAtPrice ? money(l.variant.compareAtPrice) : null, image: img(l.variant.image ?? full.featuredImage),
+      product: { id: full.id, handle: l.product.handle, title: l.product.title, featuredImage: img(full.featuredImage) },
+      selectedOptions: l.variant.selectedOptions,
+    },
+  }
+})
+writeFileSync(join(out, 'cart.json'), JSON.stringify(cartLines, null, 1))
+
+// ── content: each story's args → a node ────────────────────────────────────────────────────────
+type Node = { type: string; id: string; settings: Record<string, unknown>; blocks?: Node[] }
+const handleOf = (v: unknown): string | undefined => {
+  if (typeof v === 'string') return v
+  if (v && typeof v === 'object') {
+    const o = v as { handle?: string; src?: string }
+    return o.handle ?? o.src
+  }
+  return undefined
+}
+/** Settings the schema declares: prop fields as given, adapter fields (resources) as their handle / URL. */
+function settingsOf(type: string, args: Record<string, unknown>, fieldsOf = sectionRegistry[type]?.schema.fields): Record<string, unknown> {
+  const outS: Record<string, unknown> = {}
+  for (const [k, f] of Object.entries(fieldsOf ?? {})) {
+    // "not set" is an absent key (Theme ABI v2)
+    if (!(k in args) || args[k] === undefined || args[k] === null || args[k] === '') continue
+    if ((f as { binding: string }).binding === 'adapter') {
+      const h = handleOf(args[k])
+      if (h) outS[k] = h
+    } else outS[k] = args[k]
+  }
+  return outS
+}
+const blockFields = (section: string, block: string) => sectionRegistry[section].blockSchemas.find((b) => b.name === block)?.fields
+let blockSeq = 0
+const block = (type: string, settings: Record<string, unknown>): Node => ({ type, id: `b${++blockSeq}`, settings })
+function blocksOf(e: Entry, args: Record<string, unknown>): Node[] | undefined {
+  switch (e.type) {
+    case 'footer':
+      return (args.blocks as { type: string; settings?: Record<string, unknown>; menu?: NovaMenu }[]).map((b) =>
+        block(b.type, { ...(b.settings ?? {}), ...(b.menu ? { menu: b.menu.handle } : {}) }))
+    case 'collection-list':
+      return (args.items as { settings: Record<string, unknown>; collection: Collection }[]).map((i) =>
+        block('collection-item', { ...settingsOf('', i.settings, blockFields('collection-list', 'collection-item')), collection: i.collection.handle }))
+    case 'testimonials':
+      return (args.testimonials as { settings: Record<string, unknown>; avatar?: NovaImage | null }[]).map((t) =>
+        block('testimonial', { ...settingsOf('', t.settings, blockFields('testimonials', 'testimonial')), ...(t.avatar ? { avatar: t.avatar.src } : {}) }))
+    case 'product-details':
+      return (args.blocks as { type: string; settings?: Record<string, unknown> }[]).map((b) => block(b.type, { ...(b.settings ?? {}) }))
+    case 'trust-badges':
+      return (args.badges as Record<string, unknown>[]).map((b) => block('badge', settingsOf('', b, blockFields('trust-badges', 'badge'))))
+    case 'cart-items':
+      return (args.badges as Record<string, unknown>[]).map((b) => block('badge', settingsOf('', b, blockFields('cart-items', 'badge'))))
+    default:
+      return undefined
+  }
+}
+/** Resources the story passes as data objects but the route (not a setting) supplies under the ABI. */
+const ROUTE_SUPPLIED: Record<string, string[]> = { 'main-collection': ['collection'], 'product-details': ['product'] }
+let secSeq = 0
+function nodeOf(e: Entry): Node {
+  const args = argsOf(e)
+  const settings = settingsOf(e.type, args)
+  for (const k of ROUTE_SUPPLIED[e.type] ?? []) delete settings[k]
+  if (e.type === 'header') settings.menu = (args.menu as NovaMenu).handle
+  if (e.type === 'footer') settings.legalMenu = (args.legalMenu as NovaMenu).handle
+  if (e.type === 'product-details') settings.sizeGuidePage = 'size-guide'
+  if (e.type === 'cart-items' && args.emptyCollection) settings.emptyStateCollection = (args.emptyCollection as Collection).handle
+  const blocks = blocksOf(e, args)
+  return { type: e.type, id: `${e.type}-${++secSeq}`, settings, ...(blocks ? { blocks } : {}) }
+}
+
+const content = {
+  settings: { values: {} },
+  regions: { header: { sections: [nodeOf(HEADER)] }, footer: { sections: [nodeOf(FOOTER)] } },
+  templates: Object.fromEntries(PAGES.map((p) => [p.template, { regions: { announcement: { sections: [] }, main: { sections: p.sections.map(nodeOf) } } }])),
+}
+writeFileSync(join(out, 'content.json'), JSON.stringify(content, null, 1))
+console.log(`wrote ${out}/wire, content.json, cart.json`)

package/templates/nova/scripts/parity/index.html

@@ -0,0 +1,12 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="utf-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1" />
+    <title>Nova parity — storybook render</title>
+  </head>
+  <body>
+    <div id="root"></div>
+    <script type="module" src="/scripts/parity/main.tsx"></script>
+  </body>
+</html>

package/templates/nova/scripts/parity/main.tsx

@@ -0,0 +1,23 @@
+/** The "storybook render" of a parity page: ?page=<name>. Dev-only (vite --config scripts/parity/vite.config.ts). */
+import { createRoot } from 'react-dom/client'
+import { withNova } from '../../tests/support/with-nova'
+import { FOOTER, HEADER, PAGES, drawStory } from './pages'
+
+const name = new URLSearchParams(location.search).get('page') ?? 'home'
+const page = PAGES.find((p) => p.name === name)
+const root = document.getElementById('root')!
+if (!page) root.textContent = `no parity page "${name}" — one of ${PAGES.map((p) => p.name).join(', ')}`
+else {
+  const Page = () => (
+    <>
+      {drawStory(HEADER)}
+      <main id="main">
+        {page.sections.map((e, i) => (
+          <div key={i} data-parity-section={e.type}>{drawStory(e)}</div>
+        ))}
+      </main>
+      {drawStory(FOOTER)}
+    </>
+  )
+  createRoot(root).render(withNova(Page, { args: {}, globals: {}, parameters: {}, canvasElement: root }) as JSX.Element)
+}