create-tanqory-theme 0.0.0-stage → 0.2.3

package/templates/nova/package.json

@@ -0,0 +1,44 @@
+{
+  "name": "__PACKAGE_NAME__",
+  "version": "0.1.0",
+  "private": true,
+  "type": "module",
+  "description": "A Tanqory storefront theme forked from Nova V3 (Theme ABI v2) on @tanqory/theme-kit.",
+  "engines": {
+    "node": ">=22.6.0"
+  },
+  "scripts": {
+    "dev": "node scripts/dev.mjs",
+    "build": "node scripts/abi/build.mjs",
+    "check": "node scripts/check.mjs",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "manifest": "node --experimental-strip-types scripts/compiler/manifest/gen-manifest.mjs",
+    "build:abi": "node scripts/abi/build.mjs",
+    "verify": "npm run build:abi && npm run typecheck && npm run test",
+    "host": "node scripts/abi/local-host.mjs"
+  },
+  "dependencies": {
+    "@tanqory/theme-kit": "2.0.0-alpha.3",
+    "react": "18.3.1",
+    "react-dom": "18.3.1"
+  },
+  "devDependencies": {
+    "@tanqory/cli": "2.0.0-alpha.3",
+    "@tanqory/theme-abi": "2.0.0-alpha.14",
+    "@tanqory/theme-conformance": "0.1.0-alpha.15",
+    "@testing-library/jest-dom": "^6.9.1",
+    "@testing-library/react": "^16.3.0",
+    "@testing-library/user-event": "^14.6.1",
+    "@types/node": "^20.0.0",
+    "@types/react": "^18.3.12",
+    "@types/react-dom": "^18.3.1",
+    "@vitejs/plugin-react": "^4.3.4",
+    "axe-core": "^4.13.0",
+    "jsdom": "^25.0.1",
+    "playwright-core": "^1.63.0",
+    "typescript": "^5.6.3",
+    "vite": "^5.4.10",
+    "vitest": "^2.1.9"
+  }
+}

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

@@ -0,0 +1,145 @@
+/**
+ * Build Nova as a Theme ABI v2 theme directory — the layout @tanqory/theme-conformance runs and
+ * the platform build-service packages into an artifact (theme-artifact-v1.md §1):
+ *
+ *   dist/abi/manifest.json                 ThemeManifest v2, JCS + "\n"
+ *   dist/abi/server/entry.mjs              render(request, ctx) + manifest — one file, zero imports
+ *   dist/abi/client/client-manifest.json   neutral asset manifest, sha256 digest + SRI per file
+ *   dist/abi/client/assets/*               content-hashed browser files
+ *   dist/abi/defaults/{settings.json, regions/*.json, templates/*.json}
+ *   dist/abi/locales/<lang>.json
+ *
+ * `artifact.json`, the SBOM and the signed statement are the build-service's and signer's (they
+ * bind builder identity and inputs this script cannot attest), so they are not written here.
+ *
+ *   node scripts/abi/build.mjs            build + validate; exit 1 on any contract problem
+ */
+import { execFileSync } from 'node:child_process'
+import { createRequire } from 'node:module'
+import { createHash } from 'node:crypto'
+import { cpSync, existsSync, mkdirSync, readFileSync, readdirSync, rmSync, statSync, writeFileSync } from 'node:fs'
+import { dirname, join, relative } from 'node:path'
+import { fileURLToPath } from 'node:url'
+import { gzipSync } from 'node:zlib'
+import { LIMITS } from '@tanqory/theme-abi/limits'
+import { PLATFORM_ROUTES } from '@tanqory/theme-abi'
+import { buildManifest, STARTER_ASSET_DIR } from './manifest.mjs'
+import { canonicalize } from './jcs.mjs'
+
+const theme = join(dirname(fileURLToPath(import.meta.url)), '..', '..')
+const out = join(theme, 'dist', 'abi')
+// Vite as the theme resolves it (its own node_modules, a workspace's hoisted one, or a standalone
+// checkout), run from that package's own bin — never a path that assumes the monorepo layout.
+const vitePkgJson = createRequire(join(theme, 'package.json')).resolve('vite/package.json')
+const vite = join(dirname(vitePkgJson), JSON.parse(readFileSync(vitePkgJson, 'utf8')).bin.vite)
+const fail = (msg, list = []) => {
+  console.error(`✗ ${msg}`)
+  for (const l of list) console.error(`  - ${l}`)
+  process.exit(1)
+}
+const writeJcs = (path, value) => {
+  mkdirSync(dirname(path), { recursive: true })
+  writeFileSync(path, `${canonicalize(value)}\n`)
+}
+
+// The kit's wire client (@tanqory/theme-kit, abi/wire.ts) hard-codes the two browser prefixes; they must be the contract's.
+if (PLATFORM_ROUTES.data !== '/_tq/data/' || PLATFORM_ROUTES.actions !== '/_tq/actions/') fail('PLATFORM_ROUTES changed — update @tanqory/theme-kit abi/wire.ts')
+
+// 1. the v1 catalogue is generated from the defineSection schemas — the one source of truth
+execFileSync(process.execPath, [join(theme, 'scripts', 'compiler', 'manifest', 'gen-manifest.mjs')], { cwd: theme, stdio: ['ignore', 'ignore', 'inherit'] })
+
+// 2. manifest v2 + defaults, every stored value through validateFieldValue
+const { manifest, defaults, problems, starterFiles } = buildManifest(theme)
+if (problems.length) fail(`${problems.length} contract problem(s) in the theme's schemas or starter content`, problems)
+writeJcs(join(theme, 'lib', 'abi', 'generated', 'manifest.json'), manifest)
+
+// 3. browser bundle, then the serve entry (which imports the generated manifest)
+rmSync(out, { recursive: true, force: true })
+execFileSync(process.execPath, [vite, 'build', '--config', 'vite.abi.config.ts', '--logLevel', 'warn'], { cwd: theme, stdio: 'inherit' })
+execFileSync(process.execPath, [vite, 'build', '--config', 'vite.abi-ssr.config.ts', '--logLevel', 'warn'], { cwd: theme, stdio: 'inherit' })
+
+// 4. server/entry.mjs
+mkdirSync(join(out, 'server'), { recursive: true })
+cpSync(join(theme, 'dist', 'abi-ssr', 'entry.mjs'), join(out, 'server', 'entry.mjs'))
+writeJcs(join(out, 'manifest.json'), manifest)
+
+// 5. client manifest: every emitted file, digest + SRI; one isEntry script with its css + imports
+const clientDir = join(out, 'client')
+// Starter images the defaults/presets name as `asset:client/assets/<file>` (ABI Appendix B.2): the
+// files must be in the artifact (the signer refuses an `asset:` with no matching file).
+for (const f of starterFiles) cpSync(join(theme, STARTER_ASSET_DIR, f), join(clientDir, 'assets', f))
+const viteManifestPath = join(clientDir, '.vite', 'manifest.json')
+const viteManifest = JSON.parse(readFileSync(viteManifestPath, 'utf8'))
+rmSync(join(clientDir, '.vite'), { recursive: true, force: true })
+const files = []
+const walk = (dir) => {
+  for (const name of readdirSync(dir)) {
+    const p = join(dir, name)
+    if (statSync(p).isDirectory()) walk(p)
+    else files.push(relative(clientDir, p).split('\\').join('/'))
+  }
+}
+walk(clientDir)
+const kindOf = (f) => (/\.m?js$/.test(f) ? 'script' : /\.css$/.test(f) ? 'style' : /\.(woff2?|ttf|otf)$/.test(f) ? 'font' : /\.(png|jpe?g|gif|svg|webp|avif|ico)$/.test(f) ? 'image' : 'other')
+const entryKey = Object.keys(viteManifest).find((k) => viteManifest[k].isEntry)
+if (!entryKey) fail('vite produced no entry chunk')
+const importsOf = (key, seen = new Set()) => {
+  for (const imp of viteManifest[key]?.imports ?? []) {
+    if (seen.has(imp)) continue
+    seen.add(imp)
+    importsOf(imp, seen)
+  }
+  return seen
+}
+const entryImports = [...importsOf(entryKey)].map((k) => viteManifest[k].file)
+const entryCss = [...new Set([entryKey, ...importsOf(entryKey)].flatMap((k) => viteManifest[k].css ?? []))]
+const clientManifest = {}
+for (const f of files.sort()) {
+  const bytes = readFileSync(join(clientDir, f))
+  const sha = createHash('sha256').update(bytes).digest()
+  const isEntry = f === viteManifest[entryKey].file
+  clientManifest[isEntry ? 'main' : f] = {
+    file: f,
+    kind: kindOf(f),
+    ...(isEntry ? { isEntry: true, css: entryCss, imports: entryImports } : {}),
+    size: bytes.length,
+    digest: `sha256:${sha.toString('hex')}`,
+    integrity: `sha256-${sha.toString('base64')}`,
+  }
+}
+writeJcs(join(clientDir, 'client-manifest.json'), clientManifest)
+
+// 6. defaults/ + locales/
+writeJcs(join(out, 'defaults', 'settings.json'), defaults.settings)
+for (const [name, doc] of Object.entries(defaults.regions)) writeJcs(join(out, 'defaults', 'regions', `${name}.json`), doc)
+for (const [name, doc] of Object.entries(defaults.templates)) writeJcs(join(out, 'defaults', 'templates', `${name}.json`), doc)
+for (const f of readdirSync(join(theme, 'locales')).filter((n) => n.endsWith('.json'))) {
+  const map = JSON.parse(readFileSync(join(theme, 'locales', f), 'utf8'))
+  const nonString = Object.entries(map).filter(([, v]) => typeof v !== 'string').map(([k]) => k)
+  if (nonString.length) fail(`locales/${f} is not a flat string map`, nonString)
+  writeJcs(join(out, 'locales', f), map)
+}
+
+// 7. sizes against the limits table (§8): budget warns, hard fails
+const entry = readFileSync(join(out, 'server', 'entry.mjs'))
+const gz = gzipSync(entry, { level: 9 }).length
+const manifestBytes = readFileSync(join(out, 'manifest.json')).length
+const initial = [viteManifest[entryKey].file, ...entryImports, ...entryCss].reduce((n, f) => n + gzipSync(readFileSync(join(clientDir, f)), { level: 9 }).length, 0)
+const totalRaw = files.reduce((n, f) => n + statSync(join(clientDir, f)).size, 0)
+const rows = [
+  ['ssrEntryRawBytes', entry.length],
+  ['ssrEntryGzipBytes', gz],
+  ['manifestBytes', manifestBytes],
+  ['clientInitialGzipBytes', initial],
+  ['clientTotalRawBytes', totalRaw],
+]
+let over = false
+for (const [k, v] of rows) {
+  const { budget, hard } = LIMITS[k]
+  const verdict = v > hard ? 'OVER HARD' : budget !== null && v > budget ? 'over budget' : 'ok'
+  if (v > hard) over = true
+  console.log(`${k.padEnd(24)} ${String(v).padStart(10)}  budget ${String(budget).padStart(10)}  hard ${String(hard).padStart(10)}  ${verdict}`)
+}
+if (over) fail('a hard size limit is exceeded')
+if (!existsSync(join(out, 'server', 'entry.mjs'))) fail('no server entry')
+console.log(`✓ ${relative(process.cwd(), out) || out}`)

package/templates/nova/scripts/abi/check-content.mjs

@@ -0,0 +1,99 @@
+/**
+ * Will a store's existing content carry over to Nova v3 unchanged?
+ *
+ *   node scripts/abi/check-content.mjs <content.json | defaults-dir> [--manifest dist/abi/manifest.json]
+ *
+ * Input: a ContentRevision ({ settings: { values }, regions, templates }) — e.g. a store's live revision —
+ * or an ABI `defaults/` directory (another theme's signed starter content, read as if a store had saved
+ * all of it). Every setting key and value is checked against Nova v3's ABI manifest with the rules
+ * storefront-control's publish validator applies (content-document.ts checkFieldValue: declared key,
+ * value type, option membership, colour / URL / media rules, '' per type). Content carries over 1:1 —
+ * no key or value is rewritten — so "nothing the shop set is lost" means: zero issues here.
+ *
+ * Prints a summary and exits 1 when any value would be refused.
+ */
+import { existsSync, readFileSync, readdirSync, statSync } from 'node:fs'
+import { join, dirname } from 'node:path'
+import { fileURLToPath } from 'node:url'
+
+const theme = join(dirname(fileURLToPath(import.meta.url)), '..', '..')
+const arg = (n, d) => { const i = process.argv.indexOf(n); return i > 0 ? process.argv[i + 1] : d }
+const input = process.argv[2]
+if (!input) { console.error('usage: check-content.mjs <content.json | defaults-dir>'); process.exit(2) }
+const manifest = JSON.parse(readFileSync(arg('--manifest', join(theme, 'dist', 'abi', 'manifest.json')), 'utf8'))
+const readJson = (p) => JSON.parse(readFileSync(p, 'utf8'))
+
+function contentOf(path) {
+  if (!statSync(path).isDirectory()) return readJson(path)
+  const out = { settings: { values: readJson(join(path, 'settings.json')).values ?? {} }, regions: {}, templates: {} }
+  for (const f of readdirSync(join(path, 'regions'))) out.regions[f.replace(/\.json$/, '')] = { sections: readJson(join(path, 'regions', f)).sections }
+  for (const f of readdirSync(join(path, 'templates'))) out.templates[f.replace(/\.json$/, '')] = { regions: readJson(join(path, 'templates', f)).regions }
+  return out
+}
+
+const COLOR = /^#(?:[0-9a-fA-F]{6}|[0-9a-fA-F]{8})$/
+const urlOk = (raw, kind) => {
+  const v = raw.trim()
+  const scheme = /^([A-Za-z][A-Za-z0-9+.-]*):/.exec(v)?.[1]?.toLowerCase()
+  if (kind === 'media') return scheme === 'https' || v.startsWith('asset:client/assets/')
+  if (scheme) return ['https', 'http', 'mailto', 'tel'].includes(scheme)
+  return v === '/' || (v.length >= 2 && v[0] === '/' && v[1] !== '/' && v[1] !== '\\')
+}
+/** storefront-control content-document.ts checkFieldValue, as a predicate (null = cleared = ok). */
+function valueIssue(spec, v) {
+  if (v === null) return null
+  if (spec.dynamic === true && v && typeof v === 'object') return null
+  const s = typeof v === 'string'
+  switch (spec.type) {
+    case 'text': case 'textarea': case 'richtext': case 'html': case 'collection': case 'product': case 'page': case 'blog': case 'article': case 'menu':
+      return s ? null : 'must be text'
+    case 'number': case 'range':
+      if (typeof v !== 'number' || !Number.isFinite(v)) return 'must be a number'
+      if (typeof spec.min === 'number' && v < spec.min) return `below ${spec.min}`
+      if (typeof spec.max === 'number' && v > spec.max) return `above ${spec.max}`
+      return null
+    case 'boolean': return typeof v === 'boolean' ? null : 'must be true/false'
+    case 'color': return s && COLOR.test(v) ? null : `"${v}" is not a colour`
+    case 'select': case 'radio': return (spec.options ?? []).some((o) => o.value === v) ? null : `"${v}" is not an option`
+    case 'text_alignment': return ['left', 'center', 'right', 'start', 'end'].includes(v) ? null : `"${v}" is not an alignment`
+    case 'url': return s && urlOk(v, 'url') ? null : `"${v}" is not a link`
+    case 'image': case 'video': return s && urlOk(v, 'media') ? null : `"${v}" is not https media`
+    default: return null
+  }
+}
+
+const settingSpecs = new Map(manifest.settingsSchema.flatMap((g) => g.items.map((i) => [i.key, i])))
+const issues = []
+const stats = { settings: 0, nodes: 0, values: 0 }
+const content = contentOf(input)
+for (const [k, v] of Object.entries(content.settings?.values ?? {})) {
+  stats.settings++
+  const spec = settingSpecs.get(k)
+  if (!spec) issues.push(`settings.${k}: not a theme setting of Nova v3`)
+  else { const why = valueIssue(spec, v); if (why) issues.push(`settings.${k}: ${why}`) }
+}
+function nodes(list, at, region) {
+  for (const [i, n] of (list ?? []).entries()) {
+    stats.nodes++
+    const c = manifest.components[n.type]
+    const p = `${at}[${i}] ${n.type}#${n.id}`
+    if (!c) { issues.push(`${p}: no component "${n.type}" in Nova v3`); continue }
+    if (region && c.regions && !c.regions.includes(region) && !c.parents) issues.push(`${p}: not accepted in region ${region}`)
+    for (const [k, v] of Object.entries(n.settings ?? {})) {
+      stats.values++
+      const spec = c.attributes?.[k]
+      if (!spec) issues.push(`${p}.${k}: not a setting of "${n.type}" in Nova v3`)
+      else { const why = valueIssue(spec, v); if (why) issues.push(`${p}.${k}: ${why}`) }
+    }
+    nodes(n.blocks, `${p}.blocks`, null)
+  }
+}
+for (const [r, doc] of Object.entries(content.regions ?? {})) nodes(doc.sections, `regions.${r}`, r)
+for (const [t, doc] of Object.entries(content.templates ?? {})) {
+  if (!manifest.templates[t]) { issues.push(`templates.${t}: not a template of Nova v3`); continue }
+  for (const [r, rd] of Object.entries(doc.regions ?? {})) nodes(rd.sections, `templates.${t}.${r}`, r)
+}
+console.log(`checked ${stats.settings} global settings, ${stats.nodes} nodes, ${stats.values} node values against Nova v3 (${manifest.name}@${manifest.version})`)
+if (issues.length) { console.log(`✗ ${issues.length} value(s) Nova v3 would refuse:`); for (const i of issues) console.log(`  - ${i}`); process.exit(1) }
+console.log('✓ every key and value carries over unchanged')
+void existsSync

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

@@ -0,0 +1,27 @@
+/**
+ * RFC 8785 JSON Canonicalization Scheme for the values a manifest and its defaults can hold
+ * (null, boolean, string, finite number, array, plain object). theme-artifact-v1.md §1 requires
+ * manifest.json to be JCS + "\n"; the runner compares the `manifest` export the same way (S3).
+ *
+ * Keys are sorted by UTF-16 code units (JCS §3.2.3), which is what Array.prototype.sort does on
+ * strings. Numbers use ECMAScript Number::toString, which is what JCS §3.2.2.3 prescribes.
+ */
+export function canonicalize(value) {
+  if (value === null) return 'null'
+  switch (typeof value) {
+    case 'boolean':
+      return value ? 'true' : 'false'
+    case 'number':
+      if (!Number.isFinite(value)) throw new TypeError(`JCS: non-finite number ${value}`)
+      return JSON.stringify(value)
+    case 'string':
+      return JSON.stringify(value)
+    case 'object': {
+      if (Array.isArray(value)) return `[${value.map(canonicalize).join(',')}]`
+      const keys = Object.keys(value).filter((k) => value[k] !== undefined).sort()
+      return `{${keys.map((k) => `${JSON.stringify(k)}:${canonicalize(value[k])}`).join(',')}}`
+    }
+    default:
+      throw new TypeError(`JCS: unsupported ${typeof value}`)
+  }
+}

package/templates/nova/scripts/abi/local-host.mjs

@@ -0,0 +1,294 @@
+/**
+ * A laptop host for the built ABI theme (dist/abi): renders pages through the real
+ * `server/entry.mjs` with a RenderContext built the way the platform builds it, serves the client
+ * bundle, answers the browser wire (`/_tq/data/*`, `/_tq/actions/*`) and sends the platform's CSP
+ * (`style-src-attr 'none'`, hashed `style-src-elem`). For looking at the theme in a browser and for
+ * the parity screenshots — not a conformance runner (scripts/abi/conformance.mjs is).
+ *
+ *   node scripts/abi/local-host.mjs --data <dir> [--origin https://<store host>] [--content <file.json>] [--cart <lines.json>] [--port 4401] [--preview]
+ *
+ *   --data     a directory of recorded wire answers (`<op>-<base64url args>.json`, envelope form)
+ *   --origin   a live storefront to fill a missing answer from (its public /_tq/data wire, paced)
+ *   --content  a ContentRevision ({ settings: { values }, regions, templates }); default: the theme's own defaults
+ *   --preview  render with ctx.mode = 'preview' (the editor canvas)
+ *   --cart     a JSON file of ABI cart lines the in-memory cart starts with (`{ id, quantity, merchandise, attributes }`)
+ */
+import { createServer } from 'node:http'
+import { createHash } from 'node:crypto'
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs'
+import { extname, join, dirname, normalize } from 'node:path'
+import { fileURLToPath, pathToFileURL } from 'node:url'
+
+const theme = join(dirname(fileURLToPath(import.meta.url)), '..', '..')
+const abi = join(theme, 'dist', 'abi')
+const arg = (name, dflt = null) => {
+  const i = process.argv.indexOf(`--${name}`)
+  return i > 0 ? process.argv[i + 1] : dflt
+}
+const DATA = arg('data')
+const ORIGIN = arg('origin')
+const PORT = Number(arg('port', '4401'))
+const PREVIEW = process.argv.includes('--preview')
+if (!DATA) throw new Error('--data <dir> is required')
+mkdirSync(DATA, { recursive: true })
+
+const entry = await import(pathToFileURL(join(abi, 'server', 'entry.mjs')).href)
+const manifest = JSON.parse(readFileSync(join(abi, 'manifest.json'), 'utf8'))
+const clientManifest = JSON.parse(readFileSync(join(abi, 'client', 'client-manifest.json'), 'utf8'))
+const readDefaults = (rel) => JSON.parse(readFileSync(join(abi, 'defaults', rel), 'utf8'))
+const content = arg('content') ? JSON.parse(readFileSync(arg('content'), 'utf8')) : {}
+
+// ── the wire: recorded answers, else (with --origin) the live store's, paced and recorded ─────────
+const canon = (v) => (v === null || typeof v !== 'object' ? JSON.stringify(v) : Array.isArray(v) ? `[${v.map(canon).join(',')}]` : `{${Object.keys(v).sort().map((k) => `${JSON.stringify(k)}:${canon(v[k])}`).join(',')}}`)
+const b64 = (s) => Buffer.from(s).toString('base64').replace(/\+/g, '-').replace(/\//g, '_').replace(/=+$/, '')
+const fileOf = (op, args) => join(DATA, `${op}${args.length ? '-' + b64(canon(args)) : ''}.json`.replace(/[^A-Za-z0-9._-]/g, '_'))
+let live = null
+async function liveSession() {
+  const r = await fetch(ORIGIN + '/')
+  live = { cookie: (r.headers.getSetCookie?.() ?? []).map((c) => c.split(';')[0]).join('; '), token: /name="tq-csrf" content="([^"]*)"/.exec(await r.text())?.[1] ?? '', last: 0 }
+}
+async function wire(op, args = []) {
+  const file = fileOf(op, args)
+  if (existsSync(file)) return JSON.parse(readFileSync(file, 'utf8'))
+  if (!ORIGIN) return { ok: true, data: null, dataVersion: 'local' }
+  if (!live) await liveSession()
+  for (let i = 0; i < 6; i++) {
+    const wait = Math.max(0, live.last + 3500 - Date.now())
+    if (wait) await new Promise((r) => setTimeout(r, wait))
+    live.last = Date.now()
+    const qs = args.length ? `?a=${b64(canon(args))}` : ''
+    const res = await fetch(`${ORIGIN}/_tq/data/${op}${qs}`, { headers: { cookie: live.cookie, 'x-tq-csrf': live.token, 'sec-fetch-site': 'same-origin', 'sec-fetch-mode': 'cors', origin: ORIGIN, referer: ORIGIN + '/', accept: 'application/json' } })
+    if (res.status === 429) { await new Promise((r) => setTimeout(r, Number(res.headers.get('retry-after') ?? 30) * 1000 + 500)); continue }
+    const env = await res.json()
+    if (!env.ok && env.error?.code === 'csrf_failed') { await liveSession(); continue }
+    writeFileSync(file, JSON.stringify(env))
+    return env
+  }
+  return { ok: false, error: { code: 'unavailable', requestId: 'local' } }
+}
+const get = async (op, args = []) => {
+  const env = await wire(op, args)
+  return env.ok ? env.data : null
+}
+
+// ── routing (the platform's built-in kinds, theme-abi-v2 §2.1) ────────────────────────────────
+function route(url) {
+  const p = decodeURIComponent(url.pathname).replace(/\/+$/, '') || '/'
+  const m = (re) => re.exec(p)
+  let r
+  if (p === '/') r = { kind: 'home' }
+  else if (m(/^\/products\/([^/]+)$/)) r = { kind: 'product', handle: m(/^\/products\/([^/]+)$/)[1] }
+  else if (p === '/collections') r = { kind: 'collections' }
+  else if (m(/^\/collections\/([^/]+)$/)) r = { kind: 'collection', handle: m(/^\/collections\/([^/]+)$/)[1] }
+  else if (m(/^\/pages\/([^/]+)$/)) r = { kind: 'page', handle: m(/^\/pages\/([^/]+)$/)[1] }
+  else if (m(/^\/blogs\/([^/]+)\/([^/]+)$/)) { const x = m(/^\/blogs\/([^/]+)\/([^/]+)$/); r = { kind: 'article', blogHandle: x[1], handle: x[2] } }
+  else if (m(/^\/blogs\/([^/]+)$/)) r = { kind: 'blog', handle: m(/^\/blogs\/([^/]+)$/)[1] }
+  else if (p === '/search') r = { kind: 'search' }
+  else if (p === '/cart') r = { kind: 'cart' }
+  else if (p === '/account' || p.startsWith('/account/')) r = { kind: 'customer' }
+  else if (m(/^\/policies\/([^/]+)$/)) r = { kind: 'policy', handle: m(/^\/policies\/([^/]+)$/)[1] }
+  else if (p === '/contact') r = { kind: 'custom:contact' }
+  else r = { kind: 'not_found' }
+  const params = {}
+  if (r.kind === 'search' && url.searchParams.has('q')) params.q = url.searchParams.get('q')
+  r.template = manifest.routes[r.kind] ?? '404'
+  if (r.kind === 'page' && manifest.templates[`page.${r.handle}`]) r.template = `page.${r.handle}`
+  return { ...r, params, canonical: `${url.origin}${p === '/' ? '/' : p}` }
+}
+
+// ── content: the store's revision over the theme's signed defaults; asset: → this host's URL ──────
+const ASSET_BASE = (origin) => `${origin}/__assets`
+function resolveAssets(v, origin) {
+  if (typeof v === 'string' && v.startsWith('asset:client/')) return `${ASSET_BASE(origin)}/${v.slice('asset:client/'.length)}`
+  if (Array.isArray(v)) return v.map((x) => resolveAssets(x, origin))
+  if (v && typeof v === 'object') return Object.fromEntries(Object.entries(v).map(([k, x]) => [k, resolveAssets(x, origin)]))
+  return v
+}
+function pageDoc(template, origin) {
+  const t = manifest.templates[template]
+  const regions = []
+  for (const id of t.regions) {
+    const def = manifest.regions[id]
+    let sections
+    if (def.scope === 'shared') sections = content.regions?.[id]?.sections ?? readDefaults(`regions/${id}.json`).sections
+    else {
+      const own = content.templates?.[template]?.regions?.[id]?.sections
+      sections = own ?? readDefaults(`templates/${template}.json`).regions?.[id]?.sections
+    }
+    if (sections) regions.push({ region: id, sections: resolveAssets(sections, origin) })
+  }
+  return { contentVersion: manifest.contentVersion, template, regions }
+}
+const settingValues = () => ({ ...readDefaults('settings.json').values, ...(content.settings?.values ?? {}) })
+
+// ── ctx.data: the snapshot the platform composes, from the wire ─────────────────────────────────
+async function snapshot(r, page) {
+  const [shop, menuList] = await Promise.all([get('shop.get'), get('shop.menus')])
+  const menus = Object.fromEntries((menuList ?? []).map((m) => [m.handle, m]))
+  let resource = { kind: r.kind }
+  if (r.kind === 'product') resource = { kind: 'product', product: await get('catalog.product', [r.handle]) }
+  else if (r.kind === 'collection') resource = { kind: 'collection', collection: await get('catalog.collection', [r.handle, { productsFirst: 24 }]) }
+  else if (r.kind === 'collections') resource = { kind: 'collections', collections: await get('catalog.collections', [{ first: 50 }]) }
+  else if (r.kind === 'page') resource = { kind: 'page', page: await get('content.page', [r.handle]) }
+  else if (r.kind === 'blog') resource = { kind: 'blog', blog: await get('content.blog', [r.handle]) }
+  else if (r.kind === 'article') resource = { kind: 'article', article: await get('content.article', [r.blogHandle, r.handle]), blog: await get('content.blog', [r.blogHandle]) }
+  else if (r.kind === 'policy') resource = { kind: 'policy', policy: await get('content.policy', [r.handle]) }
+  else if (r.kind === 'search') resource = { kind: 'search', result: await get('catalog.search', [{ query: r.params.q ?? '', first: 48, types: ['product', 'page', 'article'] }]) }
+  else if (r.kind === 'cart') resource = { kind: 'cart', cart: cartView() }
+  const refs = {}
+  const walk = (nodes) => {
+    for (const n of nodes ?? []) {
+      const attrs = manifest.components[n.type]?.attributes ?? {}
+      for (const [k, spec] of Object.entries(attrs)) {
+        if (!spec.resolve) continue
+        const v = n.settings?.[k] ?? spec.default
+        if (typeof v === 'string' && v.trim()) refs[`${n.id}.${k}`] = { type: spec.type, handle: v.trim() }
+      }
+      walk(n.blocks)
+    }
+  }
+  for (const reg of page.regions) walk(reg.sections)
+  for (const [key, { type, handle }] of Object.entries(refs)) {
+    refs[key] =
+      type === 'collection' ? await get('catalog.collection', [handle, { productsFirst: 24 }])
+      : type === 'product' ? await get('catalog.product', [handle])
+      : type === 'menu' ? menus[handle] ?? null
+      : type === 'page' ? await get('content.page', [handle])
+      : type === 'blog' ? await get('content.blog', [handle])
+      : null
+  }
+  return { shop, menus, resource, refs, pixels: [], denied: [] }
+}
+
+// ── a cart the actions change (in memory, one shopper) ─────────────────────────────────────────
+let cart = { id: 'cart-local', version: 1, lines: arg('cart') ? JSON.parse(readFileSync(arg('cart'), 'utf8')) : [], note: null, discountCodes: [] }
+const money = (n, c) => ({ amount: n.toFixed(2), currencyCode: c })
+function cartView() {
+  const cur = cart.lines[0]?.merchandise.price.currencyCode ?? 'USD'
+  const sub = cart.lines.reduce((s, l) => s + Number(l.merchandise.price.amount) * l.quantity, 0)
+  return {
+    ...cart,
+    checkoutUrl: '/checkout',
+    totalQuantity: cart.lines.reduce((s, l) => s + l.quantity, 0),
+    attributes: {},
+    lines: cart.lines.map((l) => ({ ...l, cost: { subtotalAmount: money(Number(l.merchandise.price.amount) * l.quantity, cur), totalAmount: money(Number(l.merchandise.price.amount) * l.quantity, cur) } })),
+    cost: { subtotalAmount: money(sub, cur), totalAmount: money(sub, cur), totalTaxAmount: money(0, cur) },
+  }
+}
+async function variantById(id) {
+  for (const f of (await import('node:fs')).readdirSync(DATA).filter((x) => x.startsWith('catalog.product-'))) {
+    const p = JSON.parse(readFileSync(join(DATA, f), 'utf8')).data
+    const v = p?.variants?.nodes?.find((x) => x.id === id)
+    if (v) return { ...v, product: { id: p.id, handle: p.handle, title: p.title, featuredImage: p.featuredImage } }
+  }
+  return null
+}
+async function cartAction(name, args) {
+  const addLines = async (lines) => {
+    for (const l of lines ?? []) {
+      const v = await variantById(l.merchandiseId)
+      if (!v) continue
+      const have = cart.lines.find((x) => x.merchandise.id === v.id)
+      if (have) have.quantity += l.quantity ?? 1
+      else cart.lines.push({ id: `line-${cart.lines.length + 1}`, quantity: l.quantity ?? 1, merchandise: { id: v.id, title: v.title, price: v.price, image: v.image ?? null, product: v.product, selectedOptions: v.selectedOptions ?? [] }, attributes: {} })
+    }
+  }
+  if (name === 'cart.create') await addLines(args[0]?.lines)
+  else if (name === 'cart.addLines') await addLines(args[0])
+  else if (name === 'cart.updateLines') { for (const l of args[0] ?? []) { const x = cart.lines.find((y) => y.id === l.id); if (x) x.quantity = l.quantity } cart.lines = cart.lines.filter((l) => l.quantity > 0) }
+  else if (name === 'cart.removeLines') { const ids = new Set(args[0] ?? []); cart.lines = cart.lines.filter((l) => !ids.has(l.id)) }
+  else if (name === 'cart.updateNote') cart.note = args[0] ?? null
+  cart.version++
+  return { ok: true, data: { ok: true, cart: cartView() }, dataVersion: 'local' }
+}
+
+// ── the platform's response policy ─────────────────────────────────────────────────────────────
+function csp(styleHashes) {
+  return [
+    "default-src 'self'", "script-src 'self'", `style-src-elem 'self' ${styleHashes.map((h) => `'${h}'`).join(' ')}`, "style-src-attr 'none'",
+    "connect-src 'self'", 'img-src https: data: blob: http://localhost:*', 'media-src https: data: blob:', "font-src 'self' https: data:",
+    "frame-src 'none'", "object-src 'none'", "base-uri 'self'", "form-action 'self'",
+  ].join('; ')
+}
+const TYPES = { '.js': 'text/javascript', '.css': 'text/css', '.woff2': 'font/woff2', '.svg': 'image/svg+xml', '.png': 'image/png', '.json': 'application/json' }
+
+createServer(async (req, res) => {
+  try {
+    const origin = `http://${req.headers.host}`
+    const url = new URL(req.url, origin)
+    if (url.pathname.startsWith('/__assets/')) {
+      const rel = normalize(url.pathname.slice('/__assets/'.length))
+      const file = join(abi, 'client', rel)
+      if (rel.startsWith('..') || !existsSync(file)) return res.writeHead(404).end()
+      res.writeHead(200, { 'content-type': TYPES[extname(file)] ?? 'application/octet-stream', 'cache-control': 'no-cache' })
+      return res.end(readFileSync(file))
+    }
+    if (url.pathname.startsWith('/_tq/data/')) {
+      const op = url.pathname.slice('/_tq/data/'.length)
+      const a = url.searchParams.get('a')
+      const args = a ? JSON.parse(Buffer.from(a.replace(/-/g, '+').replace(/_/g, '/'), 'base64').toString('utf8')) : []
+      const env = op === 'cart.get' ? { ok: true, data: cartView(), dataVersion: 'local' } : op === 'consent.get' ? { ok: true, data: { known: false, analytics: false, marketing: false, functional: true, bannerRequired: false }, dataVersion: 'local' } : await wire(op, args)
+      res.writeHead(200, { 'content-type': 'application/json' })
+      return res.end(JSON.stringify(env))
+    }
+    if (url.pathname.startsWith('/_tq/actions/')) {
+      let body = ''
+      for await (const c of req) body += c
+      const name = url.pathname.slice('/_tq/actions/'.length)
+      const args = JSON.parse(body || '{}').args ?? []
+      const env = name.startsWith('cart.') ? await cartAction(name, args) : { ok: true, data: null, dataVersion: 'local' }
+      res.writeHead(200, { 'content-type': 'application/json' })
+      return res.end(JSON.stringify(env))
+    }
+    const r = route(url)
+    const page = pageDoc(r.template, origin)
+    const logs = []
+    const ctx = {
+      abi: '2.0',
+      mode: PREVIEW ? 'preview' : 'serve',
+      request: { method: req.method === 'POST' ? 'POST' : 'GET', url: url.href, headers: {}, hasCart: cart.lines.length > 0, isSignedIn: false, isPreview: PREVIEW },
+      route: { kind: r.kind, ...(r.handle ? { handle: r.handle } : {}), ...(r.blogHandle ? { blogHandle: r.blogHandle } : {}), template: r.template, params: r.params, canonical: r.canonical },
+      locale: { language: 'en', country: 'US', market: 'us', currency: 'USD', availableLanguages: ['en'], timeZone: 'UTC' },
+      consent: { known: false, analytics: false, marketing: false, functional: true },
+      content: { revision: 'sha256:local', contentVersion: manifest.contentVersion, page, settings: resolveAssets(settingValues(), origin) },
+      assets: { base: ASSET_BASE(origin), manifest: clientManifest },
+      signal: new AbortController().signal,
+      data: {
+        dataVersion: 'local',
+        snapshot: () => snapshot(r, page),
+        shop: { get: () => get('shop.get'), menus: async (h) => { const all = (await get('shop.menus')) ?? []; return h ? all.filter((m) => h.includes(m.handle)) : all }, policies: async () => [], pixels: async () => [] },
+        localization: { strings: async () => ({}) },
+        catalog: {
+          product: (h) => get('catalog.product', [h]),
+          products: () => get('catalog.products', [{}]),
+          collection: (h, o) => get('catalog.collection', [h, o ?? { productsFirst: 24 }]),
+          collections: (a) => get('catalog.collections', [a ?? { first: 50 }]),
+          search: (a) => get('catalog.search', [a]),
+          predictive: (q, l) => get('catalog.predictive', [q, l ?? 4]),
+          recommendations: async (h, i, l) => (await get('catalog.recommendations', [h, i ?? 'related', l ?? 8])) ?? [],
+        },
+        content: { page: (h) => get('content.page', [h]), blog: (h) => get('content.blog', [h]), article: (b, h) => get('content.article', [b, h]), policy: (h) => get('content.policy', [h]), template: async () => null, metaobjects: async () => ({ nodes: [], pageInfo: { hasNextPage: false } }) },
+        cart: { get: async () => cartView() },
+        customer: { current: async () => null, loginUrl: () => '/account/login', logoutUrl: () => '/account/logout', accountUrl: (p) => `/account${p ? '/' + p : ''}`, registerUrl: () => '/account/register', recoverUrl: () => '/account/recover' },
+      },
+      actions: undefined,
+      cache: { hint() {} },
+      log: { debug() {}, info: (m, f) => logs.push(['info', m, f]), warn: (m, f) => logs.push(['warn', m, f]), error: (m, f) => logs.push(['error', m, f]) },
+      now: () => Date.UTC(2026, 9, 13, 12),
+      release: { id: 'local', artifactDigest: 'local' },
+      capabilities: new Set(manifest.capabilities.server),
+    }
+    const out = await entry.render(new Request(url.href), ctx)
+    for (const l of logs) if (l[0] !== 'info') console.error(`[${l[0]}] ${url.pathname}: ${l[1]} ${JSON.stringify(l[2] ?? '')}`)
+    const hashes = out.headers.getAll ? out.headers.getAll('x-tq-csp-style-hash') : (out.headers.get('x-tq-csp-style-hash') ?? '').split(',').map((s) => s.trim()).filter(Boolean)
+    let html = await out.text()
+    html = html.replace('<head>', '<head>\n    <meta name="tq-csrf" content="local">')
+    res.writeHead(out.status, { 'content-type': 'text/html; charset=utf-8', 'content-security-policy': csp(hashes), 'cache-control': 'no-store' })
+    res.end(html)
+  } catch (e) {
+    console.error(e)
+    res.writeHead(500, { 'content-type': 'text/plain' }).end(String(e?.stack ?? e))
+  }
+}).listen(PORT, () => console.log(`nova-v3 local host on http://localhost:${PORT} (${PREVIEW ? 'preview' : 'serve'})`))
+
+export const _sha = (s) => createHash('sha256').update(s).digest('base64')