@tanqory/dev-mcp 0.0.0-stage → 0.1.0

package/src/docs.mjs

@@ -0,0 +1,329 @@
+/**
+ * The documentation corpus: the platform contract, the kit API, the storefront-tier spec, schemas and registry
+ * tables. Every document is read from the theme's own node_modules first, so it matches the versions the theme
+ * builds against; when the installed package does not ship that file (or no theme is open) the copy bundled in
+ * this package is used and the answer says so.
+ */
+import { existsSync, readFileSync } from 'node:fs'
+import { dirname, join } from 'node:path'
+import { fileURLToPath, pathToFileURL } from 'node:url'
+import { Bm25 } from './bm25.mjs'
+import { installedPackageDir } from './theme.mjs'
+
+export const BUNDLED_DIR = join(dirname(fileURLToPath(import.meta.url)), '..', 'bundled')
+export const BUNDLED_VERSIONS = JSON.parse(readFileSync(join(BUNDLED_DIR, 'versions.json'), 'utf8'))
+
+const ABI = '@tanqory/theme-abi'
+const KIT = '@tanqory/theme-kit'
+const CONF = '@tanqory/theme-conformance'
+const short = (pkg) => pkg.split('/')[1]
+
+/** Every document, in the order search ties are broken. `file` is relative to the package root. */
+export const DOCS = [
+  { id: 'kit/headless-api', pkg: KIT, file: 'docs/headless-api.md', kind: 'markdown', title: 'Kit headless API (@tanqory/theme-kit/headless)', summary: 'Hooks, primitives, defineSection/defineBlock/defineTheme, field.*, t(), formatMoney, <Seo>, <Image>, ai.* roles, buildManifest and the data-tq-* hooks the kit emits.' },
+  { id: 'kit/section-types', pkg: KIT, file: 'dist/headless/theme.d.ts', kind: 'typescript', title: 'defineSection / defineBlock / defineTheme types', summary: 'The TypeScript declarations of a section, block, preset and headless theme.' },
+  { id: 'kit/field-helpers', pkg: KIT, file: 'dist/sdk/schema.d.ts', kind: 'typescript', title: 'field.* helpers and settings schema types', summary: 'The field.text/richtext/select/range/resource… helpers and how settings resolve.' },
+  { id: 'kit/exports', pkg: KIT, file: 'dist/headless/index.d.ts', kind: 'typescript', title: 'Kit headless exports', summary: 'Every name @tanqory/theme-kit/headless exports.', searchable: false },
+  { id: 'kit/strings', pkg: KIT, generated: 'kit-strings', kind: 'markdown', title: 'Kit strings (KIT_STRINGS, en + th)', summary: 'Every locale key the kit primitives already translate; a theme adds its own keys on top.' },
+  { id: 'conformance/storefront-tier', pkg: CONF, file: 'docs/storefront-tier.md', kind: 'markdown', title: 'Storefront-ready and budgets tiers (tanqory theme check)', summary: 'Every storefront and budgets check, what it drives, the hooks it reads, the locale-key patterns, fix hints.' },
+  { id: 'abi/contract', pkg: ABI, file: 'contracts/theme-abi-v2.md', kind: 'markdown', title: 'Theme ABI v2 contract', summary: 'The platform contract: entry module, RenderContext, ctx.data, ctx.actions, responses, manifest and editor protocol, limits, versioning, conformance, allowed globals, field-type registry.' },
+  { id: 'abi/render-context', pkg: ABI, file: 'contracts/render-context.v2.d.ts', kind: 'typescript', title: 'RenderContext v2 types (render-context.v2.d.ts)', summary: 'The normative TypeScript of render(request, ctx): request, route, data, actions, content, assets.' },
+  { id: 'abi/field-types', pkg: ABI, generated: 'field-types', kind: 'markdown', title: 'Field-type registry (setting types)', summary: 'Every setting type a section or theme setting may use, its stored value, constraints and editor control.' },
+  { id: 'abi/limits', pkg: ABI, generated: 'limits', kind: 'markdown', title: 'Limits table (budgets and hard limits)', summary: 'Every size, count and time limit with its budget and hard value.' },
+  { id: 'abi/capabilities', pkg: ABI, generated: 'capabilities', kind: 'markdown', title: 'Capabilities', summary: 'Which data and action capabilities exist, which are implicit, default-granted, opt-in, browser-allowed, preview-allowed.' },
+  { id: 'abi/manifest-schema', pkg: ABI, file: 'schemas/theme-manifest.v2.schema.json', kind: 'json', title: 'Theme manifest v2 JSON Schema', summary: 'The JSON Schema every manifest.json is validated against.' },
+  { id: 'abi/artifact-schema', pkg: ABI, file: 'schemas/theme-artifact.v1.schema.json', kind: 'json', title: 'Theme artifact v1 JSON Schema', summary: 'The built artifact description (artifact.json).' },
+  { id: 'abi/conformance-report-schema', pkg: ABI, file: 'schemas/conformance-report.v2.schema.json', kind: 'json', title: 'Conformance report v2 JSON Schema', summary: 'The security tier report (the nine ABI suites).' },
+  { id: 'conformance/storefront-report-schema', pkg: CONF, file: 'schema/storefront-report.v1.schema.json', kind: 'json', title: 'Storefront report v1 JSON Schema', summary: 'The storefront and budgets tier report.' },
+  { id: 'conformance/x-tanqory-ai-schema', pkg: CONF, file: 'schema/x-tanqory-ai.v0.schema.json', kind: 'json', title: 'x-tanqory-ai profile v0 JSON Schema', summary: 'The AI-compat profile a manifest declares (draft, warn only).' },
+]
+
+const ABI_DIST = { 'field-types': 'dist/field-types.js', limits: 'dist/limits.js', capabilities: 'dist/capabilities.js' }
+const BUNDLED_JSON = {
+  'field-types': 'theme-abi/generated/field-types.json',
+  limits: 'theme-abi/generated/limits.json',
+  capabilities: 'theme-abi/generated/capabilities.json',
+  'kit-strings': 'theme-kit/generated/kit-strings.json',
+}
+
+const sets = (m) => Object.fromEntries(Object.entries(m).filter(([, v]) => v instanceof Set).map(([k, v]) => [k, [...v].sort()]))
+
+/** The registry data behind a generated document: from the installed package's exports, else the bundled snapshot. */
+async function generatedData(kind, dir) {
+  if (dir) {
+    try {
+      if (kind === 'kit-strings') {
+        const p = join(dir, 'dist', 'headless', 'strings.js')
+        if (existsSync(p)) return (await import(pathToFileURL(p).href)).KIT_STRINGS
+      } else if (existsSync(join(dir, ABI_DIST[kind]))) {
+        const m = await import(pathToFileURL(join(dir, ABI_DIST[kind])).href)
+        if (kind === 'field-types')
+          return {
+            registryVersions: m.FIELD_REGISTRY_VERSIONS,
+            universalConstraints: m.UNIVERSAL_FIELD_CONSTRAINTS,
+            requiredConstraints: m.FIELD_TYPE_REQUIRED_CONSTRAINTS,
+            types: m.FIELD_TYPES_BY_REGISTRY,
+            valueShapes: m.FIELD_VALUE_SHAPES_BY_REGISTRY,
+          }
+        if (kind === 'limits') return { version: m.LIMITS_VERSION, limits: m.LIMITS }
+        if (kind === 'capabilities') return sets(m)
+      }
+    } catch {
+      // fall through to the bundled snapshot
+    }
+  }
+  return null
+}
+
+const cell = (v) => (v === null || v === undefined ? '—' : Array.isArray(v) ? v.join(', ') || '—' : String(v)).replace(/\|/g, '\\|')
+
+function renderGenerated(kind, data) {
+  if (kind === 'field-types') {
+    const latest = String(data.registryVersions[data.registryVersions.length - 1])
+    const types = data.types[latest] ?? {}
+    const shapes = data.valueShapes?.[latest] ?? {}
+    const lines = [
+      `# Field-type registry (tanqory-field-types@${latest})`,
+      '',
+      'Every setting (section, block or theme setting) has one of these types. The kit helpers map to them: `field.text` → text, `field.textarea` → textarea, `field.richtext` → richtext, `field.url` → url, `field.color` → color, `field.boolean` → boolean, `field.select` → select, `field.range` → range, `field.number` → number, `field.resource(kind)` → image / video / menu / collection / product / page / blog / article.',
+      '',
+      `Universal constraint keys (any type): ${data.universalConstraints.map((c) => `\`${c}\``).join(', ')}.`,
+      '',
+      '## Types',
+      '',
+      '| Type | Stored value | Editor control | Extra constraints | Required constraints | Resource / media | Notes |',
+      '|---|---|---|---|---|---|---|',
+      ...Object.values(types).map((t) => {
+        const s = shapes[t.id]
+        const value = s ? [s.kind, s.enum ? `one of ${s.enum.join(' / ')}` : '', s.schemes ? `schemes ${s.schemes.join(' ')}` : '', s.siteRelative ? 'or a site-relative /path' : '', s.assetRef ? 'or asset:client/assets/<file> in defaults and presets' : '', s.note ?? ''].filter(Boolean).join('; ') : t.value
+        return `| \`${t.id}\` | ${cell(value)} | ${cell(t.control)} | ${cell(t.constraints)} | ${cell(data.requiredConstraints?.[t.id])} | ${cell(t.resource ?? t.media)} | ${cell(t.doc)} |`
+      }),
+      '',
+      `Registry versions this package implements: ${data.registryVersions.join(', ')}. A theme names its version in \`engines["tanqory-field-types"]\` (the kit's buildManifest writes "2").`,
+    ]
+    return lines.join('\n')
+  }
+  if (kind === 'limits') {
+    return [
+      `# Limits (table version ${data.version})`,
+      '',
+      'Over **budget** is a warning; over **hard** fails the build or the render. `—` means no value in that column. Static limits are measured on the built theme; runtime limits per render or request.',
+      '',
+      '## Table',
+      '',
+      '| Key | Budget | Hard | Class |',
+      '|---|---|---|---|',
+      ...Object.entries(data.limits).map(([k, v]) => `| \`${k}\` | ${cell(v.budget)} | ${cell(v.hard)} | ${cell(v.class)} |`),
+    ].join('\n')
+  }
+  if (kind === 'capabilities') {
+    return [
+      '# Capabilities',
+      '',
+      'A theme declares the capabilities it uses in `manifest.capabilities.server` and `.browser`. The kit declares what its runtime calls (and always `data:shop`); add `data:inventory` for stock counts. A capability not declared is refused at runtime.',
+      '',
+      ...Object.entries(data).flatMap(([k, v]) => [`## ${k}`, '', v.map((c) => `- \`${c}\``).join('\n') || '- (none)', '']),
+    ].join('\n')
+  }
+  if (kind === 'kit-strings') {
+    const en = data.en ?? {}
+    const th = data.th ?? {}
+    return [
+      '# Kit strings (en + th)',
+      '',
+      "Keys the kit's primitives already render with `t()`. Use them as they are; add your theme's own keys (prefix `theme.`) to `locales/en.json` **and** `locales/th.json`. Lookup order: merchant wording → your locale file → these → English → the key.",
+      '',
+      '## Keys',
+      '',
+      '| Key | en | th |',
+      '|---|---|---|',
+      ...Object.keys(en).sort().map((k) => `| \`${k}\` | ${cell(en[k])} | ${cell(th[k])} |`),
+    ].join('\n')
+  }
+  throw new Error(`unknown generated document ${kind}`)
+}
+
+const slug = (s) =>
+  s
+    .toLowerCase()
+    .replace(/`/g, '')
+    .replace(/[^\p{L}\p{N}]+/gu, '-')
+    .replace(/^-+|-+$/g, '')
+
+/** Split a document into sections: markdown headings, top-level TypeScript declarations, JSON Schema members. */
+function chunk(doc, text) {
+  const out = []
+  const add = (title, start, level) => out.push({ title, start, level })
+  if (doc.kind === 'markdown') {
+    let fence = false
+    let pos = 0
+    for (const line of text.split('\n')) {
+      if (/^\s*```/.test(line)) fence = !fence
+      const m = !fence && /^(#{1,3})\s+(.+?)\s*$/.exec(line)
+      if (m) add(m[2], pos, m[1].length)
+      pos += line.length + 1
+    }
+  } else if (doc.kind === 'typescript') {
+    const lines = text.split('\n')
+    let pos = 0
+    let commentStart = null
+    for (const line of lines) {
+      if (/^\/\*\*/.test(line)) commentStart = pos
+      const m = /^export\s+(?:declare\s+)?(?:type\s+)?(interface|type|function|const|class|enum|\{)\s*([A-Za-z0-9_$]*)/.exec(line)
+      if (m) {
+        add(m[1] === '{' ? `export { … } (line ${out.length + 1})` : `${m[1]} ${m[2]}`, commentStart ?? pos, 2)
+        commentStart = null
+      } else if (!/^\s*\*|^\/\*\*/.test(line) && line.trim() !== '') commentStart = null
+      pos += line.length + 1
+    }
+  } else if (doc.kind === 'json') {
+    add(doc.title, 0, 1)
+  }
+  if (!out.length || out[0].start > 0) out.unshift({ title: doc.title, start: 0, level: 1 })
+  // ids unique within the document
+  const seen = new Map()
+  return out.map((c, i) => {
+    const end = out.slice(i + 1).find((n) => n.level <= c.level)?.start ?? text.length
+    const ownEnd = out[i + 1]?.start ?? text.length
+    let id = i === 0 && c.start === 0 && c.level === 1 ? '' : slug(c.title) || `part-${i}`
+    if (id && seen.has(id)) id = `${id}-${seen.get(id) + 1}`
+    seen.set(id, (seen.get(id) ?? 0) + 1)
+    return { ...c, id, end, ownEnd }
+  })
+}
+
+/** For a JSON Schema: one searchable section per top-level property and $defs entry (search only). */
+function jsonSections(doc, text) {
+  let schema
+  try {
+    schema = JSON.parse(text)
+  } catch {
+    return []
+  }
+  const out = []
+  for (const [k, v] of Object.entries(schema.properties ?? {})) out.push({ title: `${doc.title}: property ${k}`, text: JSON.stringify(v, null, 2) })
+  for (const [k, v] of Object.entries(schema.$defs ?? schema.definitions ?? {})) out.push({ title: `${doc.title}: $defs ${k}`, text: JSON.stringify(v, null, 2) })
+  return out
+}
+
+export class DocCorpus {
+  constructor(theme) {
+    this.theme = theme
+    this.loaded = null
+  }
+
+  /** Resolve one document's text and where it came from. */
+  async read(doc) {
+    if (doc.theme) {
+      const p = this.theme.root && join(this.theme.root, doc.file)
+      return p && existsSync(p) ? { text: readFileSync(p, 'utf8'), source: 'theme', version: null, installedVersion: null } : null
+    }
+    const installedVersion = this.theme.versions?.[doc.pkg] ?? null
+    const dir = installedPackageDir(this.theme.root, doc.pkg)
+    if (doc.generated) {
+      const live = await generatedData(doc.generated, dir)
+      if (live) return { text: renderGenerated(doc.generated, live), source: 'installed', version: installedVersion, installedVersion }
+      const data = JSON.parse(readFileSync(join(BUNDLED_DIR, BUNDLED_JSON[doc.generated]), 'utf8'))
+      return { text: renderGenerated(doc.generated, data), source: 'bundled', version: BUNDLED_VERSIONS[doc.pkg], installedVersion }
+    }
+    if (dir && existsSync(join(dir, doc.file))) return { text: readFileSync(join(dir, doc.file), 'utf8'), source: 'installed', version: installedVersion, installedVersion }
+    // bundled/ keeps .d.ts files under types/, not dist/ (dist/ is git-ignored repo-wide)
+    const b = join(BUNDLED_DIR, short(doc.pkg), doc.file.replace(/^dist\//, 'types/'))
+    if (existsSync(b)) return { text: readFileSync(b, 'utf8'), source: 'bundled', version: BUNDLED_VERSIONS[doc.pkg], installedVersion }
+    return null
+  }
+
+  async load() {
+    if (this.loaded) return this.loaded
+    const docs = [...DOCS]
+    if (this.theme.root && existsSync(join(this.theme.root, 'AGENTS.md')))
+      docs.unshift({ id: 'theme/agents', theme: true, file: 'AGENTS.md', kind: 'markdown', title: "This theme's agent instructions (AGENTS.md)", summary: 'The rules, commands and layout of the open theme.' })
+    const entries = []
+    const sections = []
+    for (const doc of docs) {
+      const r = await this.read(doc)
+      if (!r) continue
+      const chunks = chunk(doc, r.text)
+      const entry = { ...doc, ...r, chunks }
+      entries.push(entry)
+      if (doc.searchable === false) continue
+      for (const c of chunks) {
+        const path = c.id ? `${doc.id}#${c.id}` : doc.id
+        const body = r.text.slice(c.start, c.ownEnd)
+        sections.push({ doc: entry, path, title: c.title, text: body })
+        // each row of a long table is findable on its own (check ids, hooks, primitives)
+        if (doc.kind === 'markdown' && !doc.generated)
+          for (const row of body.split('\n').filter((l) => /^\|\s*`/.test(l)))
+            sections.push({ doc: entry, path, title: `${c.title}: ${row.split('|')[1].replace(/`/g, '').trim()}`, text: row })
+      }
+      if (doc.kind === 'json') for (const s of jsonSections(doc, r.text)) sections.push({ doc: entry, path: doc.id, title: s.title, text: s.text })
+    }
+    this.loaded = { entries, sections, index: new Bm25(sections) }
+    return this.loaded
+  }
+
+  async list() {
+    const { entries } = await this.load()
+    return entries.map((e) => ({
+      path: e.id,
+      title: e.title,
+      summary: e.summary,
+      source: e.source,
+      package: e.pkg ?? null,
+      version: e.version,
+      sections: e.chunks.filter((c) => c.id).length,
+      uri: `tanqory://docs/${e.id}`,
+    }))
+  }
+
+  async search(query, limit = 8) {
+    const { sections, index } = await this.load()
+    const terms = new Set(query.toLowerCase().split(/[^\p{L}\p{N}]+/u).filter((t) => t.length > 1))
+    const seen = new Set()
+    const hits = index.search(query, limit * 4).filter(({ index: i }) => !seen.has(sections[i].path) && seen.add(sections[i].path)).slice(0, limit)
+    return hits.map(({ index: i, score }) => {
+      const s = sections[i]
+      const lines = s.text.split('\n').filter((l) => l.trim() !== '')
+      const scored = lines.map((l, n) => ({ n, hits: [...terms].filter((t) => l.toLowerCase().includes(t)).length }))
+      const best = scored.sort((a, b) => b.hits - a.hits || a.n - b.n)[0]
+      const at = best ? best.n : 0
+      const snippet = lines.slice(Math.max(0, at - 1), at + 2).join('\n').slice(0, 400)
+      return { path: s.path, title: s.title, document: s.doc.title, score: Math.round(score * 1000) / 1000, snippet, source: s.doc.source, version: s.doc.version }
+    })
+  }
+
+  /**
+   * One document or one section of it (`doc#section`), paginated by character offset so a long contract can be
+   * read in pieces.
+   */
+  async get(path, { offset = 0, maxChars = 12000 } = {}) {
+    const { entries } = await this.load()
+    const [id, section] = String(path).replace(/^tanqory:\/\/docs\//, '').split('#')
+    const entry = entries.find((e) => e.id === id)
+    if (!entry) return { error: 'unknown_doc', known: entries.map((e) => e.id) }
+    let text = entry.text
+    let title = entry.title
+    if (section) {
+      const c = entry.chunks.find((x) => x.id === section)
+      if (!c) return { error: 'unknown_section', known: entry.chunks.filter((x) => x.id).map((x) => `${id}#${x.id}`) }
+      text = entry.text.slice(c.start, c.end)
+      title = c.title
+    }
+    const start = Math.max(0, Math.min(offset, text.length))
+    const body = text.slice(start, start + maxChars)
+    const next = start + body.length < text.length ? start + body.length : null
+    return {
+      path: section ? `${id}#${section}` : id,
+      title,
+      source: entry.source,
+      package: entry.pkg ?? null,
+      version: entry.version,
+      installedVersion: entry.installedVersion,
+      totalChars: text.length,
+      offset: start,
+      nextOffset: next,
+      text: body,
+      sections: section ? undefined : entry.chunks.filter((x) => x.id && x.level <= 3).map((x) => `${id}#${x.id}`).slice(0, 120),
+    }
+  }
+}

package/src/index.mjs

@@ -0,0 +1,33 @@
+/**
+ * @tanqory/dev-mcp — the local stdio MCP server for Tanqory theme development.
+ *
+ *   npx -y @tanqory/dev-mcp           (or `tanqory mcp`, which starts this with the CLI that launched it)
+ *
+ * Programmatic: `createTanqoryMcpServer({ cwd, cli })` returns the McpServer (not connected); `main()` connects it
+ * to stdio. Only MCP messages go to stdout; every log line goes to stderr.
+ */
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js'
+import { VERSION, createTanqoryMcpServer } from './server.mjs'
+
+export { VERSION, createTanqoryMcpServer }
+
+/**
+ * @param {{ cwd?: string, cli?: { command: string, args?: string[], via?: string } }} [options]
+ */
+export async function main(options = {}) {
+  const log = (m) => process.stderr.write(`[tanqory-mcp] ${m}\n`)
+  const { server, theme } = createTanqoryMcpServer({ ...options, log })
+  const transport = new StdioServerTransport()
+  let closing = false
+  const shutdown = async () => {
+    if (closing) return
+    closing = true
+    await server.close().catch(() => {})
+    process.exit(0)
+  }
+  process.stdin.on('end', shutdown)
+  process.on('SIGINT', shutdown)
+  process.on('SIGTERM', shutdown)
+  await server.connect(transport)
+  log(`v${VERSION} on stdio · theme: ${theme.root ?? '(none: started outside a theme folder)'}${theme.root ? ` · layout ${theme.layout}` : ''}`)
+}

package/src/kit.mjs

@@ -0,0 +1,150 @@
+/**
+ * The kit's public API as a catalogue (from the installed kit's docs/headless-api.md and its export list), and real
+ * usage snippets for any entry: from the open theme's own source, then from the Blank starter bundled here
+ * (the starter `npm create tanqory-theme` writes, so the snippet is code that builds and passes the checks).
+ */
+import { existsSync, readFileSync, readdirSync, statSync } from 'node:fs'
+import { join, relative } from 'node:path'
+import { BUNDLED_DIR } from './docs.mjs'
+
+const KIND_BY_HEADING = [
+  [/data hooks/i, 'hook'],
+  [/primitives/i, 'primitive'],
+  [/ai compatibility/i, 'ai-role'],
+]
+
+/** Entries the docs describe in prose rather than in a table. */
+const PROSE = [
+  { name: 'defineTheme', kind: 'declaration', signature: 'defineTheme({ name, sections, Layout?, Provider?, stylesheets?, shippedCopy? })', summary: 'The theme: every section in picker order and the Layout around every page (put <CartDrawer> and <ConsentBanner> there).' },
+  { name: 'defineSection', kind: 'declaration', signature: "defineSection({ type, title, description?, category?, zone?, settings, blocks?, presets?, requires?, ai?, component })", summary: 'A section with its settings schema. `type` is persisted: never rename it. The kit wraps it in its data-tq-node element and live-edits it.' },
+  { name: 'defineBlock', kind: 'declaration', signature: 'defineBlock({ type, title, description?, settings, parents?, requires? })', summary: 'A block a section accepts; the section component receives blocks in the merchant order as { type, settings }.' },
+  { name: 'defineSettings', kind: 'declaration', signature: 'defineSettings({ key: field.*(…, { group }) })', summary: "The theme's global settings (the editor's Theme panel), read with useSettings()." },
+  { name: 'field', kind: 'declaration', signature: "field.text | textarea | richtext | url | color | boolean | select(options, default) | range(default, min, max, step) | number | resource('image' | 'video' | 'menu' | 'collection' | 'product' | 'page' | 'blog' | 'article', default?)", summary: 'Setting field helpers; every field takes { label, info, placeholder, group }.' },
+  { name: 'useTranslate', kind: 'helper', signature: "const t = useTranslate(); t('product.addToCart'); t('cart.cartCount', { count })", summary: "i18n: merchant wording → locales/<lang>.json → the kit's strings → English → the key." },
+  { name: 'formatMoney', kind: 'helper', signature: 'formatMoney(money, { display, trimZeros })', summary: "Money in the market currency with the currency's own minor units, identical on server and browser." },
+  { name: 'Image', kind: 'primitive', signature: '<Image image alt fallback? loading? sizes?>', summary: 'An image from the data or an image setting (https: or asset:client/<file>); anything else renders `fallback`.' },
+  { name: 'Seo', kind: 'primitive', signature: '<Seo title description image noindex jsonLd>', summary: "Overrides for the page head; canonical, Open Graph, hreflang and the Product/Collection/Breadcrumb JSON-LD are printed already." },
+  { name: 'SkipLink', kind: 'primitive', signature: '<SkipLink className>', summary: 'Skip link to #main (the <main> the section renderer wraps the page body in).' },
+  { name: 'createRender', kind: 'entry', signature: "createRender({ manifest, bundle, storefront: {} })", summary: 'The ABI render(request, ctx) (import from @tanqory/theme-kit/server); entry.server.tsx, leave as scaffolded.', importFrom: '@tanqory/theme-kit/server' },
+  { name: 'hydrate', kind: 'entry', signature: 'hydrate({ bundle })', summary: 'The browser entry with live edit on the editor canvas (import from @tanqory/theme-kit/client).', importFrom: '@tanqory/theme-kit/client' },
+  { name: 'buildManifest', kind: 'build', signature: 'buildManifest({ name, version, theme, settings, templates, forms, capabilities, checkValue })', summary: 'The manifest from your declarations (import from @tanqory/theme-kit/build); scripts/build.mjs calls it.', importFrom: '@tanqory/theme-kit/build' },
+]
+
+/** `<ProductForm product?>` → ProductForm; `useProduct(x?)` → useProduct; `ai.hero({…})` → ai.hero. */
+function namesOf(cell) {
+  const names = []
+  for (const m of cell.matchAll(/`([^`]+)`/g)) {
+    const raw = m[1].trim()
+    const n = /^<\s*([A-Za-z][\w.]*)/.exec(raw)?.[1] ?? /^([A-Za-z_$][\w$.]*)\s*\(/.exec(raw)?.[1] ?? null
+    if (n) names.push({ name: n, signature: raw })
+  }
+  return names
+}
+
+export function parseKitDoc(markdown) {
+  const out = []
+  let kind = null
+  let header = null
+  for (const line of markdown.split('\n')) {
+    const h = /^##\s+(.+)$/.exec(line)
+    if (h) {
+      kind = KIND_BY_HEADING.find(([re]) => re.test(h[1]))?.[1] ?? null
+      header = null
+      continue
+    }
+    if (!kind || !line.startsWith('|')) continue
+    const cells = line.split(/(?<!\\)\|/).slice(1, -1).map((c) => c.trim())
+    if (!header) {
+      header = cells
+      continue
+    }
+    if (cells.every((c) => /^-+$/.test(c))) continue
+    const rest = cells.slice(1).filter(Boolean).join(' — ')
+    for (const { name, signature } of namesOf(cells[0])) out.push({ name, kind, signature, summary: rest })
+  }
+  return out
+}
+
+/** Every name in `export { … }` lists of a .d.ts (types excluded). */
+export function exportedNames(dts) {
+  const names = new Set()
+  for (const m of dts.matchAll(/export\s*\{([^}]*)\}/g))
+    for (const part of m[1].split(','))
+      if (part.trim() && !/^\s*type\s/.test(part)) names.add(part.trim().split(/\s+as\s+/).pop().trim())
+  return names
+}
+
+export function kitCatalogue({ docText, exportsDts, installedVersion, source }) {
+  const exported = exportsDts ? exportedNames(exportsDts) : null
+  const byName = new Map()
+  for (const e of [...parseKitDoc(docText ?? ''), ...PROSE]) {
+    if (byName.has(e.name)) continue
+    const root = e.name.split('.')[0]
+    byName.set(e.name, {
+      ...e,
+      importFrom: e.importFrom ?? '@tanqory/theme-kit/headless',
+      exported: e.importFrom ? null : exported ? exported.has(root) : null,
+    })
+  }
+  const undocumented = exported ? [...exported].filter((n) => ![...byName.keys()].some((k) => k.split('.')[0] === n)).sort() : []
+  return { kitVersion: installedVersion ?? null, docSource: source, components: [...byName.values()], undocumentedExports: undocumented }
+}
+
+const SOURCE_EXT = /\.(tsx?|jsx?|mjs)$/
+
+function walk(dir, out = []) {
+  if (!existsSync(dir)) return out
+  for (const name of readdirSync(dir).sort()) {
+    if (name === 'node_modules' || name === 'generated' || name.startsWith('.')) continue
+    const p = join(dir, name)
+    if (statSync(p).isDirectory()) walk(p, out)
+    else if (SOURCE_EXT.test(name)) out.push(p)
+  }
+  return out
+}
+
+function usageRegex(name) {
+  const esc = name.replace(/[.$]/g, (c) => `\\${c}`)
+  if (name === 'field') return /\bfield\.\w+\(/
+  if (/^[A-Z]/.test(name)) return new RegExp(`<${esc}[\\s/>]`)
+  return new RegExp(`\\b${esc}\\s*[(<]`)
+}
+
+/** The top-level declaration around line `at` (column-0 `function` / `const` / `export` … to its closing line). */
+function enclosing(lines, at, maxLines = 70) {
+  let start = at
+  while (start > 0 && !/^(export\s+)?(default\s+)?(async\s+)?(function|const|let|class)\b/.test(lines[start])) start--
+  while (start > 0 && /^\s*(\/\/|\/\*\*|\*)/.test(lines[start - 1])) start--
+  let end = at
+  while (end < lines.length - 1 && !/^\}\)?;?\s*$/.test(lines[end])) end++
+  if (end - start + 1 > maxLines) {
+    start = Math.max(start, at - Math.floor(maxLines / 2))
+    end = Math.min(lines.length - 1, start + maxLines - 1)
+  }
+  return { start, end }
+}
+
+function snippetsIn(files, base, name, origin, limit) {
+  const re = usageRegex(name)
+  const out = []
+  for (const file of files) {
+    const text = readFileSync(file, 'utf8')
+    const lines = text.split('\n')
+    const at = lines.findIndex((l) => re.test(l) && !/^\s*(import|\*|\/\/)/.test(l))
+    if (at < 0) continue
+    const { start, end } = enclosing(lines, at)
+    const importLine = lines.find((l) => /^import\b.*from '@tanqory\/theme-kit/.test(l) && new RegExp(`\\b${name.split('.')[0]}\\b`).test(l)) ?? null
+    out.push({ origin, file: relative(base, file).split('\\').join('/'), startLine: start + 1, endLine: end + 1, import: importLine, code: lines.slice(start, end + 1).join('\n') })
+    if (out.length >= limit) break
+  }
+  return out
+}
+
+export function kitExamples({ name, themeRoot, limit = 2 }) {
+  const out = []
+  if (themeRoot) out.push(...snippetsIn(walk(join(themeRoot, 'src')), themeRoot, name, 'theme', limit))
+  const blank = join(BUNDLED_DIR, 'examples', 'blank')
+  for (const s of snippetsIn(walk(join(blank, 'src')), blank, name, 'blank-starter', limit))
+    if (!out.some((o) => o.code === s.code) && out.length < limit * 2) out.push(s)
+  return out
+}

package/src/manifest.mjs

@@ -0,0 +1,82 @@
+/**
+ * validate_manifest: dist/abi/manifest.json against the theme's own @tanqory/theme-abi (`validateManifest`) and the
+ * JCS byte rule (RFC 8785 bytes + one trailing LF). Component errors are traced back to the src/ declaration.
+ */
+import { existsSync, readFileSync, readdirSync } from 'node:fs'
+import { join, relative } from 'node:path'
+import { pathToFileURL } from 'node:url'
+import { installedPackageDir } from './theme.mjs'
+
+export const MANIFEST_PATH = 'dist/abi/manifest.json'
+
+/** RFC 8785 for JSON parsed by JSON.parse: keys sorted by UTF-16 code units, ECMAScript number serialisation. */
+export const jcs = (v) =>
+  v === null || typeof v !== 'object'
+    ? JSON.stringify(v)
+    : Array.isArray(v)
+      ? `[${v.map(jcs).join(',')}]`
+      : `{${Object.keys(v)
+          .sort()
+          .map((k) => `${JSON.stringify(k)}:${jcs(v[k])}`)
+          .join(',')}}`
+
+/** Where `type: '<name>'` is declared under src/ (file:line), or null. */
+export function findDeclaration(root, name) {
+  const re = new RegExp(`\\btype:\\s*['"]${name.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')}['"]`)
+  const walk = (d) => {
+    if (!existsSync(d)) return null
+    for (const n of readdirSync(d, { withFileTypes: true }).sort((a, b) => a.name.localeCompare(b.name))) {
+      if (n.name === 'generated' || n.name === 'node_modules') continue
+      const p = join(d, n.name)
+      if (n.isDirectory()) {
+        const r = walk(p)
+        if (r) return r
+      } else if (/\.(tsx?|jsx?)$/.test(n.name)) {
+        const lines = readFileSync(p, 'utf8').split('\n')
+        const i = lines.findIndex((l) => re.test(l))
+        if (i >= 0) return { file: relative(root, p).split('\\').join('/'), line: i + 1 }
+      }
+    }
+    return null
+  }
+  return walk(join(root, 'src'))
+}
+
+export async function validateManifestFile(root, abiVersion) {
+  const path = join(root, MANIFEST_PATH)
+  if (!existsSync(path)) return { error: { code: 'manifest_not_built', message: `${MANIFEST_PATH} does not exist.`, hint: 'Run `npm run build` in the theme first (it writes the manifest from your declarations).' } }
+  const dir = installedPackageDir(root, '@tanqory/theme-abi')
+  if (!dir) return { error: { code: 'abi_not_installed', message: '@tanqory/theme-abi is not installed in this theme.', hint: 'Run `npm install` in the theme.' } }
+  const pkg = JSON.parse(readFileSync(join(dir, 'package.json'), 'utf8'))
+  const entry = typeof pkg.exports?.['.'] === 'object' ? pkg.exports['.'].default ?? pkg.exports['.'].import : pkg.main ?? 'dist/index.js'
+  const abi = await import(pathToFileURL(join(dir, entry)).href)
+  if (typeof abi.validateManifest !== 'function') return { error: { code: 'abi_too_old', message: `@tanqory/theme-abi ${pkg.version} has no validateManifest.`, hint: 'Update @tanqory/theme-abi in the theme.' } }
+
+  const bytes = readFileSync(path, 'utf8')
+  let manifest
+  try {
+    manifest = JSON.parse(bytes)
+  } catch (e) {
+    return { valid: false, manifestPath: MANIFEST_PATH, abiVersion: abiVersion ?? pkg.version, errors: [{ path: '', message: `not JSON: ${e.message}`, code: 'json', hint: 'Rebuild with `npm run build`; never edit the manifest by hand.' }] }
+  }
+  const errors = []
+  const canonical = `${jcs(manifest)}\n`
+  if (bytes !== canonical)
+    errors.push({
+      path: '',
+      code: 'jcs',
+      message: bytes === canonical.slice(0, -1) ? 'the JCS bytes are not followed by exactly one trailing newline' : 'the file is not the JCS (RFC 8785) serialisation of its content',
+      hint: 'The build writes `canonicalize(manifest) + "\\n"`; rebuild with `npm run build`, never edit the file.',
+    })
+  const r = abi.validateManifest(manifest)
+  for (const e of r.ok ? [] : r.errors ?? []) {
+    const p = e.path ?? e.instancePath ?? ''
+    const out = { path: p || '/', message: e.message ?? String(e), code: e.code ?? e.keyword }
+    const m = /^\/components\/([^/]+)/.exec(p)
+    const decl = m ? findDeclaration(root, decodeURIComponent(m[1].replace(/~1/g, '/').replace(/~0/g, '~'))) : null
+    if (decl) Object.assign(out, decl, { hint: `Fix the declaration of "${m[1]}" (defineSection/defineBlock) at ${decl.file}:${decl.line}, then \`npm run build\`.` })
+    else out.hint = 'The manifest is generated by scripts/build.mjs (buildManifest) from src/ declarations, settings and templates: fix those, then `npm run build`.'
+    errors.push(out)
+  }
+  return { valid: errors.length === 0, manifestPath: MANIFEST_PATH, abiVersion: abiVersion ?? pkg.version, errors }
+}