@tanqory/dev-mcp 0.0.0-stage → 0.1.0

package/src/prompts.mjs

@@ -0,0 +1,97 @@
+/**
+ * Guided workflows (prompts/list, prompts/get). Each one chains this server's tools with the CLI, and ends on the
+ * same bar: `check_theme` green on every tier.
+ */
+import { z } from 'zod'
+
+const DONE = 'Before you say done: `npm run build && npm run typecheck && npm test`, then check_theme with no tier. It must pass every tier (security, storefront, budgets). Report what you checked, not what you assume.'
+
+const user = (text) => ({ messages: [{ role: 'user', content: { type: 'text', text } }] })
+
+export function registerPrompts(server) {
+  server.registerPrompt(
+    'new-theme',
+    {
+      title: 'Design a new theme on the kit',
+      description: 'Turn the open starter into a theme of your own design: same storefront functions (from the kit), completely different look.',
+      argsSchema: {
+        name: z.string().optional().describe('Theme name'),
+        direction: z.string().optional().describe('Design direction, e.g. "editorial black-and-white with a mega menu"'),
+      },
+    },
+    ({ name, direction }) =>
+      user(`Build ${name ? `the theme "${name}"` : 'a new theme'} in this repository${direction ? `: ${direction}` : ''}.
+
+1. get_doc {path: "theme/agents"}: the rules of this repository (kit for every function, no raw fetch, data-tq-node, i18n every string, a11y, deterministic render).
+2. list_kit_components, then get_kit_example for each primitive you restyle (ProductForm, VariantPicker, CartDrawer, FacetFilters, SortSelect, SearchForm, LocalizationForm …). Keep the kit primitives; change markup around them and the CSS.
+3. Replace src/styles/theme.css with your design system. Keep 44 px touch targets, a visible :focus-visible outline and no text-transform.
+4. New sections: scaffold_section (plan, review, then confirm with the planDigest), then restyle what it wrote.
+5. Every new visible string: locales/en.json AND locales/th.json, rendered with t().
+6. Look at it: dev_server_status; if the dev server runs, screenshot mobile and desktop of /, a collection, a product, the cart, in en and th; fix what looks wrong.
+7. ${DONE}`),
+  )
+
+  server.registerPrompt(
+    'new-section',
+    {
+      title: 'Add a section',
+      description: 'Add one kit-wired section with settings, en + th strings and a test, and get the checks green.',
+      argsSchema: {
+        name: z.string().describe('Section name, e.g. "Lookbook"'),
+        purpose: z.string().describe('What it shows, e.g. "an image grid with a heading"'),
+      },
+    },
+    ({ name, purpose }) =>
+      user(`Add a "${name}" section: ${purpose}.
+
+1. search_docs for what it needs (e.g. "defineSection presets", "Image", "field.resource"); get_kit_example {name: "defineSection"} for a complete section in this kit.
+2. scaffold_section {name: "${name}", purpose: "${purpose}", template: "index"} to get the plan; read it; call again with confirm: true and the planDigest.
+3. Adjust the markup and CSS to the theme's design. Fixed strings only via t() with keys in both locale files; merchant text stays in settings. presets[0] must render with a visible height (the editor's Add-section preview).
+4. npm run build, npm test; screenshot / against the dev server when it runs.
+5. ${DONE}`),
+  )
+
+  server.registerPrompt(
+    'fix-check-report',
+    {
+      title: 'Fix a failing theme check',
+      description: 'Run the checks, fix every failure from its hint and file:line, and repeat until green.',
+      argsSchema: { tier: z.string().optional().describe('security | storefront | budgets | all (default all)') },
+    },
+    ({ tier }) =>
+      user(`Make \`tanqory theme check\`${tier ? ` --tier ${tier}` : ''} pass.
+
+1. npm run build (a build error comes first: fix it).
+2. check_theme${tier ? ` {tier: "${tier}"}` : ''}. For each failure: read its message and fix hint; open file:line when given; search_docs {query: "<checkId>"} explains what the check drives and why it fails.
+3. Fix the cause in the theme's source (never weaken a check, never edit dist/, reports/ or src/generated/). Function belongs to the kit: if a check fails because a store function is hand-written, replace it with the kit primitive (get_kit_example).
+4. Rebuild and run check_theme again. Repeat until there are no failures.
+5. ${DONE}`),
+  )
+
+  server.registerPrompt(
+    'port-from-another-template-language',
+    {
+      title: 'Port a theme written in another template language',
+      description: 'Re-implement a theme written for another template language or storefront system on Theme ABI v2 and the kit: same design, the kit for every function. Translate, never copy third-party code you have no rights to.',
+      argsSchema: {
+        source: z.string().optional().describe('Where the source theme is (a folder in this workspace)'),
+        language: z.string().optional().describe('Its template language, if known'),
+      },
+    },
+    ({ source, language }) =>
+      user(`Port the theme ${source ? `in ${source} ` : ''}${language ? `(written in ${language}) ` : ''}to this Theme ABI v2 repository.
+
+Treat the source as a design spec, not as code to keep. Only port a theme you have the rights to.
+
+1. Inventory it: its templates and the page kinds they serve, its sections/partials and their settings, its global settings, its locale strings, its assets and CSS.
+2. Map each part:
+   - page kinds → src/templates.ts route kinds + templates/<name>.json starter content (get_schema {kind: "content-document"});
+   - each section/partial → one defineSection (get_schema {kind: "section"}); its settings → field.* with the same defaults (get_schema {kind: "field-registry"});
+   - loops, filters, includes and template tags → React components and the kit's helpers (formatMoney, t(), <Image>, useCollection …);
+   - every storefront behaviour (cart, variant selection, search, filters, sort, pagination, localization, forms, consent, SEO tags) → the kit primitive for it (list_kit_components). Never port the old JavaScript for these;
+   - strings → locales/en.json and locales/th.json;
+   - CSS → src/styles/theme.css, without inline styles (the platform CSP forbids style attributes) and without text-transform.
+3. Build one page kind at a time (home, collection, product, cart, search, page, blog/article, 404), screenshot each against the dev server and compare with the original design.
+4. ${DONE}`),
+  )
+}

package/src/scaffold.mjs

@@ -0,0 +1,471 @@
+/**
+ * scaffold_section: a new kit-wired section in a theme laid out like the Blank starter (src/theme.tsx with
+ * defineTheme, src/sections/*.tsx, locales/en.json + th.json, tests/). Two steps, always: `plan` computes every file
+ * change and a digest of it; `write` applies exactly that plan, and refuses when the digest no longer matches
+ * (the theme changed in between, or the arguments differ).
+ *
+ * The generated code uses only @tanqory/theme-kit/headless, renders every fixed string through t() with en + th
+ * keys, keeps merchant text in settings, uses no inline style (the platform CSP forbids style attributes) and no
+ * text-transform, and gives links a 44 px minimum target.
+ */
+import { createHash } from 'node:crypto'
+import { existsSync, mkdirSync, readFileSync, readdirSync, writeFileSync } from 'node:fs'
+import { dirname, join } from 'node:path'
+import { insideTheme } from './theme.mjs'
+
+export const LAYOUTS = ['text', 'image-grid', 'media-text', 'product-grid']
+
+export class ScaffoldError extends Error {
+  constructor(code, message, hint, extra = {}) {
+    super(message)
+    this.code = code
+    this.hint = hint
+    Object.assign(this, extra)
+  }
+}
+
+export const kebab = (s) =>
+  String(s)
+    .normalize('NFKD')
+    .replace(/[\u0300-\u036f]/g, '')
+    .replace(/([a-z0-9])([A-Z])/g, '$1-$2')
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, '-')
+    .replace(/^-+|-+$/g, '')
+    .slice(0, 48)
+    .replace(/-+$/, '')
+const camel = (k) => k.replace(/-([a-z0-9])/g, (_m, c) => c.toUpperCase())
+const pascal = (k) => camel(k).replace(/^./, (c) => c.toUpperCase())
+const tsString = (s) => `'${String(s).replace(/\\/g, '\\\\').replace(/'/g, "\\'").replace(/\n/g, ' ')}'`
+const comment = (s) => String(s).replace(/\*\//g, '* /').replace(/\s+/g, ' ').trim()
+
+/** Deterministic layout choice from the name and purpose (no model call). */
+export function inferLayout(name, purpose) {
+  const s = `${name} ${purpose}`.toLowerCase()
+  if (/\b(products?|collections?|best ?sellers?|catalog(ue)?|shop the)\b/.test(s)) return 'product-grid'
+  if (/\b(grid|gallery|lookbook|mosaic|portfolio|images|photos|pictures)\b/.test(s)) return 'image-grid'
+  if (/\b(image|photo|picture|banner|media|split)\b/.test(s)) return 'media-text'
+  return 'text'
+}
+
+function strings(layout, title, titleTh) {
+  const th = titleTh || title
+  const base = { label: [title, th] }
+  if (layout === 'image-grid') return { ...base, empty: ['Add images to this section in the editor.', 'เพิ่มรูปภาพให้ส่วนนี้ได้ในตัวแก้ไข'] }
+  if (layout === 'product-grid') return { ...base, empty: ['No products to show yet.', 'ยังไม่มีสินค้าที่จะแสดง'], viewAll: ['View all', 'ดูทั้งหมด'] }
+  return base
+}
+
+function sectionSource({ layout, type, title, purpose, ident, comp, cls, key, aiImport }) {
+  const head = `/**
+ * ${comment(title)}: ${comment(purpose)}
+ * Scaffolded by @tanqory/dev-mcp (layout: ${layout}). The markup and the CSS are yours; the kit supplies the settings,
+ * the data-tq-node wrapper and live edit. Fixed strings come from locales/en.json and locales/th.json (${key}.*).
+ */
+`
+  const sectionOpen = (extra = '') => `    <section className={${extra ? `\`${cls}${extra}\`` : `'${cls}'`}} aria-labelledby={settings.heading ? headingId : undefined} aria-label={settings.heading ? undefined : t('${key}.label')}>
+      {settings.heading ? (
+        <h2 id={headingId} className="${cls}__title">
+          {settings.heading}
+        </h2>
+      ) : null}`
+  if (layout === 'image-grid') {
+    const block = `${type}-image`
+    return `${head}import { useId } from 'react'
+import { Image, defineBlock, defineSection, field, useTranslate, type BlockInstance } from '@tanqory/theme-kit/headless'
+
+const ${camel(block)} = defineBlock({
+  type: '${block}',
+  title: 'Image',
+  settings: {
+    image: field.resource('image', '', { label: 'Image' }),
+    caption: field.text('', { label: 'Caption' }),
+    link: field.url('', { label: 'Link' }),
+  },
+})
+
+function ${comp}({ settings, blocks }: { settings: { heading: string; columns: number }; blocks: BlockInstance[] }): JSX.Element {
+  const t = useTranslate()
+  const headingId = useId()
+  const items = blocks.filter((b) => b.type === '${block}')
+  return (
+${sectionOpen(` ${cls}--cols-\${settings.columns}`)}
+      {items.length ? (
+        <ul className="${cls}__grid">
+          {items.map((b, i) => {
+            const caption = String(b.settings.caption ?? '')
+            const link = String(b.settings.link ?? '')
+            const figure = (
+              <figure className="${cls}__figure">
+                <Image image={String(b.settings.image ?? '')} alt={caption} className="${cls}__img" sizes="(max-width: 720px) 50vw, 33vw" fallback={<span className="${cls}__img ${cls}__img--empty" />} />
+                {caption ? <figcaption className="${cls}__caption">{caption}</figcaption> : null}
+              </figure>
+            )
+            return (
+              <li key={i} className="${cls}__item">
+                {link ? (
+                  <a className="${cls}__link" href={link}>
+                    {figure}
+                  </a>
+                ) : (
+                  figure
+                )}
+              </li>
+            )
+          })}
+        </ul>
+      ) : (
+        <p className="${cls}__empty">{t('${key}.empty')}</p>
+      )}
+    </section>
+  )
+}
+
+export const ${ident} = defineSection({
+  type: '${type}',
+  title: ${tsString(title)},
+  description: ${tsString(purpose)},
+  category: 'editorial',
+  settings: {
+    heading: field.text(${tsString(title)}, { label: 'Heading' }),
+    columns: field.range(3, 2, 4, 1, { label: 'Columns' }),
+  },
+  blocks: [${camel(block)}],
+  presets: [{ name: ${tsString(title)}, settings: { heading: ${tsString(title)} }, blocks: [{ type: '${block}' }, { type: '${block}' }, { type: '${block}' }] }],
+  component: ${comp},
+})
+`
+  }
+  if (layout === 'product-grid') {
+    return `${head}import { useId } from 'react'
+import { Image, ai, defineSection, field, formatMoney, useCollection, useTranslate } from '@tanqory/theme-kit/headless'
+
+function ${comp}({ settings }: { settings: { heading: string; collection: string; count: number } }): JSX.Element {
+  const t = useTranslate()
+  const headingId = useId()
+  const c = useCollection(settings.collection)
+  const products = c.products.slice(0, settings.count)
+  return (
+${sectionOpen()}
+      {products.length ? (
+        <ul className="${cls}__grid">
+          {products.map((p) => (
+            <li key={p.id} className="${cls}__item">
+              <a className="${cls}__link" href={p.url}>
+                <Image image={p.featuredImage} alt="" className="${cls}__img" sizes="(max-width: 720px) 50vw, 25vw" fallback={<span className="${cls}__img ${cls}__img--empty" />} />
+                <span className="${cls}__name">{p.title}</span>
+                <span className="${cls}__price">{formatMoney(p.priceRange.min)}</span>
+              </a>
+            </li>
+          ))}
+        </ul>
+      ) : (
+        <p className="${cls}__empty">{t('${key}.empty')}</p>
+      )}
+      {c.collection ? (
+        <a className="${cls}__all" href={c.collection.url}>
+          {t('${key}.viewAll')}
+        </a>
+      ) : null}
+    </section>
+  )
+}
+
+export const ${ident} = defineSection({
+  type: '${type}',
+  title: ${tsString(title)},
+  description: ${tsString(purpose)},
+  category: 'products',
+  settings: {
+    heading: field.text(${tsString(title)}, { label: 'Heading' }),
+    collection: field.resource('collection', 'all', { label: 'Collection' }),
+    count: field.range(8, 4, 16, 4, { label: 'Products to show' }),
+  },
+  presets: [{ name: ${tsString(title)}, settings: { heading: ${tsString(title)}, collection: 'all' } }],
+  ai: ai.productGrid('collection', { heading: 'heading' }),
+  component: ${comp},
+})
+`
+  }
+  if (layout === 'media-text') {
+    return `${head}import { useId } from 'react'
+import { Image, defineSection, field, useTranslate } from '@tanqory/theme-kit/headless'
+
+function ${comp}({ settings }: { settings: { heading: string; body: string; image: string; buttonLabel: string; buttonLink: string; imageFirst: boolean } }): JSX.Element {
+  const t = useTranslate()
+  const headingId = useId()
+  return (
+    <section className={\`${cls}\${settings.imageFirst ? '' : ' ${cls}--image-last'}\`} aria-labelledby={settings.heading ? headingId : undefined} aria-label={settings.heading ? undefined : t('${key}.label')}>
+      <div className="${cls}__media">
+        <Image image={settings.image} alt="" className="${cls}__img" sizes="(max-width: 720px) 100vw, 50vw" fallback={<span className="${cls}__img ${cls}__img--empty" />} />
+      </div>
+      <div className="${cls}__copy">
+        {settings.heading ? (
+          <h2 id={headingId} className="${cls}__title">
+            {settings.heading}
+          </h2>
+        ) : null}
+        {settings.body ? <div className="${cls}__body" dangerouslySetInnerHTML={{ __html: settings.body }} /> : null}
+        {settings.buttonLabel && settings.buttonLink ? (
+          <a className="${cls}__button" href={settings.buttonLink}>
+            {settings.buttonLabel}
+          </a>
+        ) : null}
+      </div>
+    </section>
+  )
+}
+
+export const ${ident} = defineSection({
+  type: '${type}',
+  title: ${tsString(title)},
+  description: ${tsString(purpose)},
+  category: 'editorial',
+  settings: {
+    heading: field.text(${tsString(title)}, { label: 'Heading' }),
+    body: field.richtext('', { label: 'Text' }),
+    image: field.resource('image', '', { label: 'Image' }),
+    buttonLabel: field.text('', { label: 'Button label' }),
+    buttonLink: field.url('/collections/all', { label: 'Button link' }),
+    imageFirst: field.boolean(true, { label: 'Image first' }),
+  },
+  presets: [{ name: ${tsString(title)}, settings: { heading: ${tsString(title)} } }],
+  component: ${comp},
+})
+`
+  }
+  return `${head}import { useId } from 'react'
+import { ${aiImport ? 'ai, ' : ''}defineSection, field, useTranslate } from '@tanqory/theme-kit/headless'
+
+function ${comp}({ settings }: { settings: { heading: string; body: string } }): JSX.Element {
+  const t = useTranslate()
+  const headingId = useId()
+  return (
+${sectionOpen()}
+      {settings.body ? <div className="${cls}__body" dangerouslySetInnerHTML={{ __html: settings.body }} /> : null}
+    </section>
+  )
+}
+
+export const ${ident} = defineSection({
+  type: '${type}',
+  title: ${tsString(title)},
+  description: ${tsString(purpose)},
+  category: 'editorial',
+  settings: {
+    heading: field.text(${tsString(title)}, { label: 'Heading' }),
+    body: field.richtext('<p>${comment(purpose).replace(/[<>'\\]/g, '')}</p>', { label: 'Text' }),
+  },
+  presets: [{ name: ${tsString(title)}, settings: { heading: ${tsString(title)} } }],
+  ai: ai.richText({ heading: 'heading', body: 'body' }),
+  component: ${comp},
+})
+`
+}
+
+function cssSource(layout, cls, type) {
+  const lines = [`/* ${type} (scaffolded by @tanqory/dev-mcp): restyle freely; keep 44 px link targets and no text-transform. */`, `.${cls} { padding: 48px var(--t-gutter, 16px); }`, `.${cls}__title { margin: 0 0 24px; }`]
+  if (layout === 'image-grid' || layout === 'product-grid')
+    lines.push(
+      `.${cls}__grid { display: grid; gap: 16px; grid-template-columns: repeat(2, minmax(0, 1fr)); list-style: none; margin: 0; padding: 0; }`,
+      layout === 'image-grid'
+        ? `@media (min-width: 720px) { .${cls}--cols-3 .${cls}__grid { grid-template-columns: repeat(3, minmax(0, 1fr)); } .${cls}--cols-4 .${cls}__grid { grid-template-columns: repeat(4, minmax(0, 1fr)); } }`
+        : `@media (min-width: 720px) { .${cls}__grid { grid-template-columns: repeat(4, minmax(0, 1fr)); } }`,
+      `.${cls}__figure { margin: 0; }`,
+      `.${cls}__img { display: block; width: 100%; height: auto; aspect-ratio: 3 / 4; object-fit: cover; }`,
+      `.${cls}__img--empty { background: var(--t-panel, #f3f3f3); }`,
+      `.${cls}__link { display: block; min-height: 44px; color: inherit; text-decoration: none; }`,
+      `.${cls}__caption, .${cls}__name, .${cls}__price { display: block; margin-top: 8px; }`,
+      `.${cls}__all { display: inline-flex; align-items: center; min-height: 44px; min-width: 44px; margin-top: 16px; }`,
+    )
+  if (layout === 'media-text')
+    lines.push(
+      `.${cls} { display: grid; gap: 24px; align-items: center; }`,
+      `@media (min-width: 720px) { .${cls} { grid-template-columns: 1fr 1fr; } .${cls}--image-last .${cls}__media { order: 2; } }`,
+      `.${cls}__img { display: block; width: 100%; height: auto; aspect-ratio: 4 / 3; object-fit: cover; }`,
+      `.${cls}__img--empty { background: var(--t-panel, #f3f3f3); }`,
+      `.${cls}__button { display: inline-flex; align-items: center; min-height: 44px; min-width: 44px; padding: 0 16px; border: 1px solid currentColor; }`,
+    )
+  lines.push(`.${cls}__empty { margin: 0; }`)
+  return `\n${lines.join('\n')}\n`
+}
+
+function testSource({ type, ident, file, keys }) {
+  return `/** ${type}: scaffolded by @tanqory/dev-mcp. Extend it with what the section must guarantee. */
+import { readFileSync } from 'node:fs'
+import { join } from 'node:path'
+import { fileURLToPath } from 'node:url'
+import { describe, expect, it } from 'vitest'
+import theme from '../../src/theme'
+import { ${ident} } from '../../src/sections/${file}'
+
+const root = fileURLToPath(new URL('../..', import.meta.url))
+const locale = (lang: string) => JSON.parse(readFileSync(join(root, 'locales', \`\${lang}.json\`), 'utf8')) as Record<string, string>
+
+describe('section ${type}', () => {
+  it('is declared and registered in the theme', () => {
+    expect(${ident}).toBeTruthy()
+    expect(theme.sections.map((s) => s.id)).toContain('${type}')
+  })
+  it('every fixed string it renders exists in en and th', () => {
+    for (const key of ${JSON.stringify(keys)}) {
+      expect(locale('en')[key], key).toBeTruthy()
+      expect(locale('th')[key], key).toBeTruthy()
+    }
+  })
+})
+`
+}
+
+/** Add `ident` to defineTheme({ sections: [...] }) before `footer` (else at the end); add its import. */
+function patchTheme(text, ident, file) {
+  const m = /(sections\s*:\s*\[)([^\]]*)(\])/.exec(text)
+  if (!m) return null
+  const items = m[2].split(',').map((s) => s.trim()).filter(Boolean)
+  if (items.includes(ident)) return null
+  const at = items.indexOf('footer')
+  at >= 0 ? items.splice(at, 0, ident) : items.push(ident)
+  let out = text.slice(0, m.index) + m[1] + items.join(', ') + m[3] + text.slice(m.index + m[0].length)
+  const importLine = `import { ${ident} } from './sections/${file}'`
+  const lines = out.split('\n')
+  let last = -1
+  let lastSection = -1
+  lines.forEach((l, i) => {
+    if (/^import\b/.test(l)) last = i
+    if (/^import\b.*from '\.\/sections\//.test(l)) lastSection = i
+  })
+  lines.splice((lastSection >= 0 ? lastSection : last) + 1, 0, importLine)
+  out = lines.join('\n')
+  return { text: out, importLine, sectionsLine: `sections: [${items.join(', ')}]` }
+}
+
+const readJson = (p) => JSON.parse(readFileSync(p, 'utf8'))
+const jsonText = (v) => `${JSON.stringify(v, null, 2)}\n`
+
+/** Section types already declared anywhere under src/ (so a new one never collides). */
+function declaredTypes(root) {
+  const types = new Set()
+  const walk = (d) => {
+    if (!existsSync(d)) return
+    for (const n of readdirSync(d, { withFileTypes: true })) {
+      if (n.name === 'generated' || n.name === 'node_modules') continue
+      const p = join(d, n.name)
+      if (n.isDirectory()) walk(p)
+      else if (/\.(tsx?|jsx?)$/.test(n.name)) for (const m of readFileSync(p, 'utf8').matchAll(/\btype:\s*'([a-z0-9-]+)'/g)) types.add(m[1])
+    }
+  }
+  walk(join(root, 'src'))
+  return types
+}
+
+/**
+ * @param {{ root: string|null, layout: string }} theme
+ * @param {{ name: string, purpose: string, layout?: string, template?: string, titleTh?: string }} input
+ */
+export function planSection(theme, input) {
+  if (!theme.root) throw new ScaffoldError('no_theme', 'No theme is open: the server was not started inside a theme folder.', 'Start the agent (and this server) in the theme root, the folder with tanqory.config.json.')
+  if (theme.layout !== 'kit-headless')
+    throw new ScaffoldError(
+      'unsupported_theme_layout',
+      theme.layout === 'nova-fork'
+        ? 'This theme is a Nova fork (theme.config.ts); scaffold_section only knows the Blank layout (src/theme.tsx with defineTheme) today.'
+        : 'This theme has no src/theme.tsx with defineTheme(); scaffold_section only knows the Blank layout today.',
+      'Write the section by hand: get_kit_example {name: "defineSection"} shows a complete one, get_schema {kind: "section"} the declaration shape. Nothing was written.',
+    )
+  const root = theme.root
+  const title = String(input.name ?? '').trim()
+  const purpose = String(input.purpose ?? '').trim()
+  if (!title) throw new ScaffoldError('invalid_name', 'name is empty.', 'Pass a human name, e.g. "Lookbook".')
+  if (!purpose) throw new ScaffoldError('invalid_purpose', 'purpose is empty.', 'Say in one sentence what the section shows, e.g. "an image grid with a heading".')
+  const type = kebab(title)
+  if (!/^[a-z][a-z0-9-]*$/.test(type)) throw new ScaffoldError('invalid_name', `"${title}" does not give a usable section type (got "${type}").`, 'Use a name that starts with a Latin letter, e.g. "Lookbook".')
+  const layout = input.layout ?? inferLayout(title, purpose)
+  if (!LAYOUTS.includes(layout)) throw new ScaffoldError('invalid_layout', `layout "${layout}" is not one of ${LAYOUTS.join(', ')}.`, 'Omit it to infer one from the purpose.')
+  if (declaredTypes(root).has(type)) throw new ScaffoldError('section_exists', `A section or block of type "${type}" is already declared in src/.`, 'Choose another name, or edit the existing section.')
+  const file = type
+  const sectionPath = `src/sections/${file}.tsx`
+  const testPath = `tests/sections/${file}.test.ts`
+  for (const p of [sectionPath, testPath]) if (existsSync(join(root, p))) throw new ScaffoldError('file_exists', `${p} already exists.`, 'Choose another name; nothing was written.')
+
+  const ident = `${camel(type)}Section`
+  const comp = `${pascal(type)}Section`
+  const css = join(root, 'src', 'styles', 'theme.css')
+  const prefix = existsSync(css) && /\.t-[a-z]/.test(readFileSync(css, 'utf8')) ? 't-' : ''
+  const cls = `${prefix}${type}`
+  const key = `theme.${camel(type)}`
+  const str = strings(layout, title, input.titleTh?.trim())
+  const keys = Object.keys(str).map((k) => `${key}.${k}`)
+
+  const changes = []
+  changes.push({ path: sectionPath, action: 'create', content: sectionSource({ layout, type, title, purpose, ident, comp, cls, key, aiImport: layout === 'text' }), summary: `defineSection "${type}" (${layout})` })
+
+  const themeFile = join(root, 'src', 'theme.tsx')
+  const patched = patchTheme(readFileSync(themeFile, 'utf8'), ident, file)
+  if (!patched) throw new ScaffoldError('theme_not_patchable', 'src/theme.tsx has no `sections: [...]` list this tool can extend.', `Add \`import { ${ident} } from './sections/${file}'\` and put ${ident} in defineTheme({ sections }) yourself after writing the section.`)
+  changes.push({ path: 'src/theme.tsx', action: 'modify', content: patched.text, summary: `import ${ident}; ${patched.sectionsLine}` })
+
+  for (const [lang, idx] of [['en', 0], ['th', 1]]) {
+    const p = join(root, 'locales', `${lang}.json`)
+    if (!existsSync(p)) throw new ScaffoldError('locale_missing', `locales/${lang}.json does not exist.`, 'The theme needs locales/en.json and locales/th.json.')
+    const map = readJson(p)
+    const added = {}
+    for (const [k, v] of Object.entries(str)) if (!(`${key}.${k}` in map)) added[`${key}.${k}`] = v[idx]
+    changes.push({ path: `locales/${lang}.json`, action: 'modify', content: jsonText({ ...map, ...added }), summary: `add ${Object.keys(added).join(', ') || 'nothing (keys exist)'}`, added })
+  }
+
+  if (existsSync(css)) changes.push({ path: 'src/styles/theme.css', action: 'modify', content: readFileSync(css, 'utf8').replace(/\n*$/, '\n') + cssSource(layout, cls, type), summary: `append .${cls} rules` })
+
+  changes.push({ path: testPath, action: 'create', content: testSource({ type, ident, file, keys }), summary: 'vitest: registered, en + th strings exist' })
+
+  if (input.template) {
+    const tname = String(input.template)
+    const tp = insideTheme(root, join('templates', `${tname}.json`))
+    if (!tp || !existsSync(tp)) throw new ScaffoldError('unknown_template', `templates/${tname}.json does not exist.`, `Pass one of: ${readdirSync(join(root, 'templates')).filter((f) => f.endsWith('.json')).map((f) => f.slice(0, -5)).join(', ')}; or omit template.`)
+    const doc = readJson(tp)
+    const main = doc.regions?.main
+    if (!main || !Array.isArray(main.sections)) throw new ScaffoldError('template_not_patchable', `templates/${tname}.json has no regions.main.sections list.`, 'Add the section to the template yourself.')
+    const ids = new Set(main.sections.map((s) => s.id))
+    let n = 1
+    while (ids.has(`${type}-${n}`)) n++
+    const id = `${type}-${n}`
+    const node = { id, type, settings: { heading: title } }
+    if (layout === 'image-grid') node.blocks = [1, 2, 3].map((i) => ({ id: `${id}-image-${i}`, type: `${type}-image` }))
+    const next = { ...doc, regions: { ...doc.regions, main: { ...main, sections: [...main.sections, node] } } }
+    changes.push({ path: `templates/${tname}.json`, action: 'modify', content: jsonText(next), summary: `append node "${id}" to regions.main` })
+  }
+
+  const planDigest = `sha256:${createHash('sha256')
+    .update(JSON.stringify(changes.map((c) => [c.path, c.action, c.content])))
+    .digest('hex')}`
+  return {
+    type,
+    title,
+    layout,
+    localeKeys: keys,
+    translationTodo: input.titleTh ? [] : [`${key}.label (th): the Thai name equals the English one ("${title}"); translate it, or pass titleTh`],
+    changes,
+    planDigest,
+    nextSteps: [
+      'Restyle the markup and the appended CSS to your design.',
+      ...(input.template ? [] : ['Place the section: add it in the editor, or call again with template: "index" to put it in the home page starter content.']),
+      'npm test, then screenshot the page with the section (desktop and mobile; the dev server rebuilds on save), then check_theme until it passes.',
+    ],
+  }
+}
+
+/** Apply a plan whose digest the caller confirmed. Returns the files written. */
+export function writeSection(theme, input, planDigest) {
+  const plan = planSection(theme, input)
+  if (plan.planDigest !== planDigest)
+    throw new ScaffoldError('plan_changed', 'The plan no longer matches the digest you confirmed: the theme or the arguments changed since the plan was made. Nothing was written.', 'Call scaffold_section again without confirm, review the new plan, then confirm its planDigest.', { planDigest: plan.planDigest })
+  const written = []
+  for (const c of plan.changes) {
+    const abs = insideTheme(theme.root, c.path)
+    if (!abs) throw new ScaffoldError('path_outside_theme', `${c.path} is outside the theme.`, 'Nothing more was written.', { written })
+    if (c.action === 'create' && existsSync(abs)) throw new ScaffoldError('file_exists', `${c.path} appeared after planning.`, 'Nothing more was written.', { written })
+    mkdirSync(dirname(abs), { recursive: true })
+    writeFileSync(abs, c.content)
+    written.push({ path: c.path, action: c.action, bytes: Buffer.byteLength(c.content) })
+  }
+  return { ...plan, written }
+}