@troshab/slidev-theme-troshab 0.1.4 → 0.1.7

package/scripts/generate-component-docs.mjs

@@ -0,0 +1,759 @@
+#!/usr/bin/env node
+/**
+ * generate-component-docs.mjs — Sync component API docs from `.vue` source
+ *
+ * Reads `components/*.vue` entry stubs, extracts:
+ *   1. JSDoc header comment before `defineProps` (component description + prop @params)
+ *   2. `defineProps<{...}>()` / `withDefaults(defineProps<{...}>(), {...})` — props
+ *   3. `<slot name="X" />` usages in template + `useSlots()` refs — slot list
+ *
+ * Updates the matching `.md` file in the visualise-content skill (by default,
+ * `~/.claude/plugins/marketplaces/troshab-own-claude-code/plugins/troshab-own/skills/
+ *  slidev-visualise-content/components/{Name}.md`) between auto-markers:
+ *
+ *   <!-- BEGIN AUTO PROPS -->  …generated Props table…  <!-- END AUTO PROPS -->
+ *   <!-- BEGIN AUTO SLOTS -->  …generated Slots table…  <!-- END AUTO SLOTS -->
+ *   <!-- SCHEMA  …JSON…  -->
+ *
+ * Human-authored sections (## Usage, ## Notes, ## Examples in theme) are never
+ * touched. Missing .md → skeleton is created. Orphan .md (no matching .vue) →
+ * warning printed.
+ *
+ * Flags:
+ *   --theme-dir DIR     (default ~/slidev-theme-troshab)
+ *   --skill-dir DIR     (default visualise-content components folder)
+ *   --check-only        Exit 1 if any .md would change; print diff summary.
+ *   --only NAMES        Comma-separated component names (e.g. Stepper,Callout).
+ *                       Handy when debugging a single component.
+ *   --no-write          Print intended changes to stdout; don't touch files.
+ *
+ * Exit codes:
+ *   0 — all docs in sync (or write succeeded)
+ *   1 — drift detected with --check-only, or orphan/missing component
+ *   2 — fatal parsing error
+ */
+
+import { readFileSync, writeFileSync, existsSync, readdirSync, mkdirSync } from 'node:fs'
+import { join, resolve, dirname, basename } from 'node:path'
+import { homedir } from 'node:os'
+import { fileURLToPath } from 'node:url'
+
+const __dirname = dirname(fileURLToPath(import.meta.url))
+
+// ─── CLI ──────────────────────────────────────────────────────────────────────
+
+const argv = process.argv.slice(2)
+function flag(name) { return argv.includes(name) }
+function opt(name, fallback) {
+  const i = argv.indexOf(name)
+  return i >= 0 && i + 1 < argv.length ? argv[i + 1] : fallback
+}
+function expandTilde(p) { return p.startsWith('~') ? join(homedir(), p.slice(1)) : p }
+
+const THEME_DIR = resolve(expandTilde(opt('--theme-dir', join(__dirname, '..'))))
+const DEFAULT_SKILL_DIR = join(
+  homedir(),
+  '.claude', 'plugins', 'marketplaces', 'troshab-own-claude-code',
+  'plugins', 'troshab-own', 'skills', 'slidev-visualise-content', 'components',
+)
+const SKILL_DIR = resolve(expandTilde(opt('--skill-dir', DEFAULT_SKILL_DIR)))
+const CHECK_ONLY = flag('--check-only')
+const NO_WRITE = flag('--no-write')
+const ONLY = opt('--only', null)
+const ONLY_SET = ONLY ? new Set(ONLY.split(',').map(s => s.trim())) : null
+
+// ─── .vue parser ──────────────────────────────────────────────────────────────
+
+/**
+ * Extract the `<script setup lang="ts">` or plain `<script>` block, the template,
+ * and any top-of-file HTML comment (acts like JSDoc on entry-stub files).
+ * Returns { scriptSrc, templateSrc, headerComment } or null.
+ */
+function splitSfc(src) {
+  const scriptSetupMatch = src.match(/<script\s+setup(?:\s+[^>]*)?>([\s\S]*?)<\/script>/)
+  const plainScriptMatch = src.match(/<script(?:\s+[^>]*)?>([\s\S]*?)<\/script>/)
+  const scriptSrc = scriptSetupMatch ? scriptSetupMatch[1] : (plainScriptMatch ? plainScriptMatch[1] : '')
+  // Greedy + last `</template>` — avoids truncation at inner `<template v-if>`.
+  const templateMatch = src.match(/<template(?:\s[^>]*)?>([\s\S]*)<\/template>/)
+  const headerMatch = src.match(/^\s*<!--([\s\S]*?)-->/)
+  if (!scriptSrc && !headerMatch) return null
+  return {
+    scriptSrc,
+    templateSrc: templateMatch ? templateMatch[1] : '',
+    headerComment: headerMatch ? headerMatch[1] : '',
+    isSetup: !!scriptSetupMatch,
+  }
+}
+
+/**
+ * If the entry-stub does `import X from '../components_base/X.vue'; export default X`,
+ * return the resolved path to the real implementation .vue. Otherwise null.
+ */
+function resolveReExport(scriptSrc, currentFile) {
+  const importMatch = scriptSrc.match(/import\s+\w+\s+from\s+['"]([^'"]+\.vue)['"]/)
+  if (!importMatch) return null
+  const exportMatch = scriptSrc.match(/export\s+default\s+\w+/)
+  if (!exportMatch) return null
+  const rel = importMatch[1]
+  return resolve(dirname(currentFile), rel)
+}
+
+/**
+ * Extract the JSDoc header block right before the first `defineProps` or
+ * `withDefaults(defineProps`. Returns { description, paramDocs } where paramDocs
+ * maps propName → description string.
+ *
+ * If `fallbackHtmlComment` is provided (from an entry-stub <!-- … -->), it's
+ * parsed with the same Props:/Slots:/Usage: rules.
+ */
+function extractHeaderDoc(scriptSrc, fallbackHtmlComment) {
+  const defineIdx = scriptSrc.search(/(?:withDefaults\s*\(\s*)?defineProps\s*</)
+
+  let raw = ''
+  if (defineIdx >= 0) {
+    // Look backward for /** … */ ending just before defineProps.
+    const before = scriptSrc.slice(0, defineIdx)
+    const jsdocMatch = before.match(/\/\*\*[\s\S]*?\*\/(?=\s*(?:const\s+\w+\s*=\s*)?(?:withDefaults\s*\(\s*)?defineProps\s*<|\s*$)/)
+    const allMatches = [...before.matchAll(/\/\*\*[\s\S]*?\*\//g)]
+    raw = jsdocMatch ? jsdocMatch[0] : (allMatches.length ? allMatches[allMatches.length - 1][0] : '')
+  }
+  if (!raw && fallbackHtmlComment) {
+    // Treat the HTML comment as a JSDoc body (lines already look like " * foo"
+    // but may also just be plain lines — normalise accordingly).
+    raw = `/**\n${fallbackHtmlComment}\n*/`
+  }
+  if (!raw) return { description: '', paramDocs: {} }
+
+  // Clean leading " * " and trailing "*/".
+  const lines = raw
+    .replace(/^\s*\/\*\*\s*/, '')
+    .replace(/\*\/\s*$/, '')
+    .split('\n')
+    .map(l => l.replace(/^\s*\*\s?/, '').trimEnd())
+
+  const paramDocs = {}
+  const descLines = []
+  let inDescription = true
+
+  for (const line of lines) {
+    const paramMatch = line.match(/^@param\s+\{?[^}]*\}?\s*(\w+)\s*[-—]?\s*(.*)$/)
+    if (paramMatch) {
+      inDescription = false
+      paramDocs[paramMatch[1]] = paramMatch[2].trim()
+      continue
+    }
+    // Some JSDocs list props inline like "value: number — Target number".
+    const inlineParamMatch = line.match(/^\s*(\w+):\s*[^—\-]+[—\-]\s+(.+)$/)
+    if (inlineParamMatch && !inDescription) {
+      paramDocs[inlineParamMatch[1]] = inlineParamMatch[2].trim()
+      continue
+    }
+    // "Props:" section header switches into prop-list mode.
+    if (/^\s*Props:\s*$/i.test(line)) { inDescription = false; continue }
+    if (/^\s*Slots?:\s*$/i.test(line)) { inDescription = false; continue }
+    if (/^\s*Usage:?\s*$/i.test(line)) { inDescription = false; continue }
+    // Stop accumulating once we see a usage example, a code block, or a blank
+    // followed by an HTML-tag line — otherwise multi-line descriptions get
+    // concatenated with embedded `<Component …>` examples.
+    if (inDescription) {
+      const trimmed = line.trim()
+      if (!trimmed) { if (descLines.length) inDescription = false; continue }
+      if (/^</.test(trimmed)) { inDescription = false; continue }
+      descLines.push(trimmed)
+    }
+  }
+
+  // Pass 2 for "Props:" block style ("value: number — description").
+  const propsSectionMatch = raw.match(/Props:\s*\n([\s\S]*?)(?:\n\s*(?:Slots?|Usage|Notes?|Example)s?:|\*\/)/i)
+  if (propsSectionMatch) {
+    for (const line of propsSectionMatch[1].split('\n')) {
+      const m = line.replace(/^\s*\*\s?/, '').match(/^\s*(\w+)[?!:]?\s*(?:[:\-]\s*)?[^—\-]*[—\-]\s+(.+)$/)
+      if (m && !paramDocs[m[1]]) paramDocs[m[1]] = m[2].trim()
+    }
+  }
+
+  return {
+    description: descLines.join(' ').replace(/\s+/g, ' ').trim(),
+    paramDocs,
+  }
+}
+
+/**
+ * Find defineProps<{...}>() or withDefaults(defineProps<{...}>(), {...}).
+ * Returns { propsBlock: string, defaultsBlock: string | null }.
+ */
+function extractPropsBlocks(scriptSrc) {
+  // Locate `defineProps<`.
+  const propsStart = scriptSrc.indexOf('defineProps<')
+  if (propsStart < 0) return null
+
+  // Balanced `<...>` extraction starting at the `<` after defineProps.
+  const openAngle = scriptSrc.indexOf('<', propsStart)
+  if (openAngle < 0) return null
+  let depth = 0
+  let typeStart = openAngle + 1
+  let typeEnd = -1
+  for (let i = openAngle; i < scriptSrc.length; i++) {
+    const c = scriptSrc[i]
+    if (c === '<') depth++
+    else if (c === '>') {
+      depth--
+      if (depth === 0) { typeEnd = i; break }
+    }
+  }
+  if (typeEnd < 0) return null
+  const typeLiteral = scriptSrc.slice(typeStart, typeEnd).trim()
+
+  // Check if wrapped in withDefaults(..., {...}).
+  const withDefaultsIdx = scriptSrc.lastIndexOf('withDefaults', propsStart)
+  let defaultsBlock = null
+  if (withDefaultsIdx >= 0 && withDefaultsIdx < propsStart) {
+    // Locate the comma after defineProps<...>() and the { that starts defaults.
+    const afterClose = scriptSrc.indexOf(')', typeEnd)
+    if (afterClose > 0) {
+      const commaIdx = scriptSrc.indexOf(',', afterClose)
+      if (commaIdx > 0) {
+        const defBraceStart = scriptSrc.indexOf('{', commaIdx)
+        if (defBraceStart > 0) {
+          let bDepth = 0
+          let defEnd = -1
+          for (let i = defBraceStart; i < scriptSrc.length; i++) {
+            const c = scriptSrc[i]
+            if (c === '{') bDepth++
+            else if (c === '}') {
+              bDepth--
+              if (bDepth === 0) { defEnd = i; break }
+            }
+          }
+          if (defEnd > 0) defaultsBlock = scriptSrc.slice(defBraceStart + 1, defEnd).trim()
+        }
+      }
+    }
+  }
+
+  return { propsBlock: typeLiteral, defaultsBlock }
+}
+
+/**
+ * Parse `propName?: type` entries from the props-type literal. Handles union
+ * types (a|b|c), generics, nested arrays.
+ * Returns [{ name, type, required }].
+ */
+function parsePropsBlock(block) {
+  // Strip single-line "// …" and multi-line "/* … */" comments.
+  let stripped = block
+    .replace(/\/\*[\s\S]*?\*\//g, '')
+    .replace(/(^|\s)\/\/[^\n]*/g, (_, p) => p)
+    .trim()
+
+  // Remove outer `{...}` if present — defineProps<{ ... }>() passes the literal
+  // as `{ type?: '...'; title?: string }`; we need to walk inside the object.
+  if (stripped.startsWith('{') && stripped.endsWith('}')) {
+    stripped = stripped.slice(1, -1)
+  }
+
+  const entries = []
+  let depth = 0
+  let current = ''
+  for (let i = 0; i < stripped.length; i++) {
+    const c = stripped[i]
+    if (c === '[' || c === '{' || c === '(') depth++
+    else if (c === ']' || c === '}' || c === ')') depth--
+    // `<` / `>` are tricky: `<T>` increases/decreases depth, but `|`/`>` in
+    // union/comparison contexts would too. For our case the prop-type literal
+    // usually stays balanced with the existing depth tracking.
+    if (c === '<' && /\w/.test(stripped[i - 1] || '')) depth++
+    else if (c === '>' && depth > 0 && stripped[i + 1] !== '=' && stripped[i - 1] !== '=') depth--
+    if ((c === ',' || c === ';' || c === '\n') && depth === 0) {
+      const piece = current.trim()
+      if (piece) entries.push(piece)
+      current = ''
+      continue
+    }
+    current += c
+  }
+  if (current.trim()) entries.push(current.trim())
+
+  const props = []
+  for (const entry of entries) {
+    // propName?: type
+    const m = entry.match(/^(\w+)(\??)\s*:\s*([\s\S]+)$/)
+    if (!m) continue
+    const [, name, optional, rawType] = m
+    props.push({ name, type: rawType.trim(), required: optional !== '?' })
+  }
+  return props
+}
+
+/**
+ * Parse defaults block. Returns propName → default-value (as raw string).
+ */
+function parseDefaultsBlock(block) {
+  if (!block) return {}
+  const out = {}
+  let depth = 0
+  let current = ''
+  for (let i = 0; i < block.length; i++) {
+    const c = block[i]
+    if (c === '<' || c === '[' || c === '{' || c === '(') depth++
+    else if (c === '>' || c === ']' || c === '}' || c === ')') depth--
+    if ((c === ',' || c === '\n') && depth === 0) {
+      addDefault(out, current)
+      current = ''
+      continue
+    }
+    current += c
+  }
+  addDefault(out, current)
+  return out
+}
+function addDefault(out, piece) {
+  const trimmed = piece.trim().replace(/^\/\/.*$/gm, '').trim()
+  if (!trimmed) return
+  const m = trimmed.match(/^(\w+)\s*:\s*([\s\S]+?)$/)
+  if (!m) return
+  out[m[1]] = m[2].trim()
+}
+
+/**
+ * Slots: grep static `<slot name="X" />` + dynamic `<slot :name="`step${i}`" />` +
+ * `slots.XXX` / `slots[`step${i}`]` refs. Dynamic names are emitted in their
+ * raw template form (e.g. "step${i}") so collapseSlots() can render them.
+ * Returns sorted array of unique slot names.
+ */
+function extractSlots(scriptSrc, templateSrc) {
+  const slots = new Set()
+  const staticSlotRe = /<slot(?:\s+name=["']([\w-]+)["'])?[\s\S]*?(?:\/>|>)/g
+  let m
+  while ((m = staticSlotRe.exec(templateSrc))) {
+    slots.add(m[1] || 'default')
+  }
+
+  // Dynamic: <slot :name="`step${...}`" /> or <slot :name="'step' + idx" />.
+  const dynSlotRe = /<slot\s+:name=["']\s*`?([^`"'$]+)(?:\$\{[^}]+\}|[+\s]+[\w.]+)/g
+  while ((m = dynSlotRe.exec(templateSrc))) {
+    slots.add(`${m[1].trim()}N`)
+  }
+
+  // slots[`stepN`] / slots.stepN / $slots.stepN access patterns in script.
+  const accessRe = /(?:\$?slots)[\s]*\[[\s]*`([^`${]+)(?:\$\{[^}]+\})?`[\s]*\]/g
+  while ((m = accessRe.exec(scriptSrc))) {
+    slots.add(`${m[1].trim()}N`)
+  }
+  const dotRe = /(?:\$?slots)\.(\w+)/g
+  while ((m = dotRe.exec(scriptSrc))) slots.add(m[1])
+
+  const noise = new Set(['name', 'value', 'length', 'forEach', 'map'])
+  return [...slots].filter(s => !noise.has(s)).sort()
+}
+
+// ─── Collapse long slot lists (e.g. step1..stepN) ────────────────────────────
+
+function collapseSlots(slots) {
+  // Group patterns like step1, step2, step3 → "step1..step3".
+  const groups = new Map()
+  const singles = []
+  for (const s of slots) {
+    const m = s.match(/^([a-zA-Z]+)(\d+)$/)
+    if (!m) { singles.push(s); continue }
+    const [, prefix, num] = m
+    const arr = groups.get(prefix) || []
+    arr.push(parseInt(num, 10))
+    groups.set(prefix, arr)
+  }
+  const out = [...singles]
+  for (const [prefix, nums] of groups) {
+    nums.sort((a, b) => a - b)
+    if (nums.length === 1) out.push(`${prefix}${nums[0]}`)
+    else out.push(`${prefix}${nums[0]}..${prefix}${nums[nums.length - 1]}`)
+  }
+  return out.sort()
+}
+
+// ─── Markdown table renderers ────────────────────────────────────────────────
+
+function renderPropsTable(props, paramDocs, defaults) {
+  if (!props.length) return '_No props._'
+  const rows = props.map(p => {
+    const def = defaults[p.name] ?? (p.required ? '—' : '—')
+    const desc = (paramDocs[p.name] || '').replace(/\|/g, '\\|')
+    return `| \`${p.name}\` | \`${p.type.replace(/\|/g, '\\|')}\` | \`${def.replace(/\|/g, '\\|')}\` | ${p.required ? 'yes' : 'no'} | ${desc} |`
+  })
+  return [
+    '| Prop | Type | Default | Required | Description |',
+    '|------|------|---------|----------|-------------|',
+    ...rows,
+  ].join('\n')
+}
+
+/**
+ * Scan example_slides/*.md for usages of `<ComponentName`. Returns sorted
+ * array of { file, heading } tuples. `file` is relative to example_slides/.
+ */
+function findExamplesInTheme(themeDir, componentName) {
+  const dir = join(themeDir, 'example_slides')
+  if (!existsSync(dir)) return []
+  const out = []
+  for (const f of readdirSync(dir).sort()) {
+    if (!f.endsWith('.md')) continue
+    let src
+    try { src = readFileSync(join(dir, f), 'utf8') } catch { continue }
+    // Component tag: `<ComponentName` followed by whitespace, `/`, `>`, or end.
+    // Must not be inside a code fence — example_slides occasionally ship
+    // snippets showing wrong usage, but in practice the files are ~10-20 lines
+    // and any occurrence is a demo. So simple match is good enough.
+    const re = new RegExp('<' + componentName + '[\\s/>]', 'm')
+    if (!re.test(src)) continue
+    const headingMatch = src.match(/^#\s+(.+?)\s*$/m)
+    out.push({ file: f, heading: headingMatch ? headingMatch[1] : '(no heading)' })
+  }
+  return out
+}
+
+function renderExamplesTable(examples) {
+  if (!examples.length) return '_No theme example slides reference this component yet._'
+  const rows = examples.map(e => `| [\`${e.file}\`](@../../../../slidev-theme-troshab/example_slides/${e.file}) | ${e.heading.replace(/\|/g, '\\|')} |`)
+  return [
+    '| File | Heading |',
+    '|------|---------|',
+    ...rows,
+  ].join('\n')
+}
+
+function renderSlotsTable(slots, slotDescs = {}) {
+  if (!slots.length) return '_No slots._'
+  const rows = slots.map(s => {
+    const desc = (slotDescs[s] || '').replace(/\|/g, '\\|')
+    return `| \`${s}\` | ${desc} |`
+  })
+  return [
+    '| Slot | Description |',
+    '|------|-------------|',
+    ...rows,
+  ].join('\n')
+}
+
+function renderSchema(name, props, defaults, slots) {
+  const obj = {
+    name,
+    props: Object.fromEntries(props.map(p => {
+      const item = { type: p.type, required: p.required }
+      // Detect pure literal-union enum: `'a' | 'b' | 'c'` (no mixed `string` etc.).
+      const literalMatches = [...p.type.matchAll(/['"]([^'"]+)['"]/g)].map(x => x[1])
+      const residue = p.type.replace(/['"][^'"]+['"]/g, '').replace(/\s*\|\s*/g, '').trim()
+      if (literalMatches.length > 0 && residue === '') {
+        item.enum = literalMatches
+      }
+      if (defaults[p.name] !== undefined) item.default = defaults[p.name]
+      return [p.name, item]
+    })),
+    slots,
+  }
+  return JSON.stringify(obj, null, 2)
+}
+
+// ─── .md updating ────────────────────────────────────────────────────────────
+
+const MARKERS = {
+  propsBegin: '<!-- BEGIN AUTO PROPS -->',
+  propsEnd:   '<!-- END AUTO PROPS -->',
+  slotsBegin: '<!-- BEGIN AUTO SLOTS -->',
+  slotsEnd:   '<!-- END AUTO SLOTS -->',
+  examplesBegin: '<!-- BEGIN AUTO EXAMPLES -->',
+  examplesEnd:   '<!-- END AUTO EXAMPLES -->',
+  schemaBegin: '<!-- SCHEMA',
+  schemaEnd:  '-->',
+}
+
+function replaceBetween(src, begin, end, replacement) {
+  const s = src.indexOf(begin)
+  const e = src.indexOf(end, s + begin.length)
+  if (s < 0 || e < 0) return null
+  return src.slice(0, s + begin.length) + '\n' + replacement + '\n' + src.slice(e)
+}
+
+function upsertSchema(src, jsonBody) {
+  const block = `${MARKERS.schemaBegin}\n${jsonBody}\n${MARKERS.schemaEnd}`
+  const idx = src.indexOf(MARKERS.schemaBegin)
+  if (idx < 0) return src.trimEnd() + '\n\n' + block + '\n'
+  // Replace from schemaBegin up to the next `-->` line.
+  const afterBegin = src.indexOf('\n', idx)
+  const endIdx = src.indexOf(MARKERS.schemaEnd, afterBegin)
+  if (endIdx < 0) return src.trimEnd() + '\n\n' + block + '\n'
+  const trail = src.slice(endIdx + MARKERS.schemaEnd.length)
+  return src.slice(0, idx) + block + trail
+}
+
+function generateSkeleton(name, description, propsTable, slotsTable, examplesTable, schema) {
+  return `# ${name}
+${description ? `\n${description}\n` : ''}
+## Props
+
+${MARKERS.propsBegin}
+${propsTable}
+${MARKERS.propsEnd}
+
+## Slots
+
+${MARKERS.slotsBegin}
+${slotsTable}
+${MARKERS.slotsEnd}
+
+## Usage
+
+_TODO: add representative usage example(s)._
+
+## Notes
+
+_TODO: add constraints, common mistakes, layout tips._
+
+## Examples in theme
+
+${MARKERS.examplesBegin}
+${examplesTable}
+${MARKERS.examplesEnd}
+
+${MARKERS.schemaBegin}
+${schema}
+${MARKERS.schemaEnd}
+`
+}
+
+/**
+ * Pull `| propName | type | default | ... | Description |` tables out of an
+ * existing `.md` so we can preserve the hand-written Description column even
+ * when the schema otherwise gets regenerated.
+ * Returns { propName → description }. Empty if no table found.
+ */
+function readExistingPropDescriptions(md, heading) {
+  const headingIdx = md.search(new RegExp(`^##\\s+${heading}\\s*$`, 'm'))
+  if (headingIdx < 0) return {}
+  const lines = md.slice(headingIdx).split('\n')
+  const out = {}
+  // Find the first header row: `| Prop | ... | Description |`
+  for (let i = 0; i < lines.length; i++) {
+    const row = lines[i]
+    if (!/^\|.*Description\s*\|?$/i.test(row) && !/^\|.*Description\s*\|/i.test(row)) continue
+    // Header row found at i; data rows start at i+2 (i+1 is `|---|---|` separator).
+    for (let j = i + 2; j < lines.length; j++) {
+      const r = lines[j].trim()
+      if (!r.startsWith('|')) break
+      const cells = r.split('|').map(c => c.trim()).filter(c => c.length > 0 || true)
+      // Leading and trailing | create empty cells; strip them.
+      const inner = r.replace(/^\|/, '').replace(/\|$/, '').split('|').map(c => c.trim())
+      if (inner.length < 2) continue
+      const propName = inner[0].replace(/^`|`$/g, '').trim()
+      const desc = inner[inner.length - 1]
+      if (propName && desc) out[propName] = desc
+    }
+    break
+  }
+  return out
+}
+
+function readExistingSlotDescriptions(md) {
+  const headingIdx = md.search(/^##\s+Slots\s*$/m)
+  if (headingIdx < 0) return {}
+  const lines = md.slice(headingIdx).split('\n')
+  const out = {}
+  for (let i = 0; i < lines.length; i++) {
+    if (!/^\|\s*Slot\s*\|/i.test(lines[i])) continue
+    for (let j = i + 2; j < lines.length; j++) {
+      const r = lines[j].trim()
+      if (!r.startsWith('|')) break
+      const inner = r.replace(/^\|/, '').replace(/\|$/, '').split('|').map(c => c.trim())
+      if (inner.length < 2) continue
+      const slotName = inner[0].replace(/^`|`$/g, '').trim()
+      const desc = inner[inner.length - 1]
+      if (slotName && desc) out[slotName] = desc
+    }
+    break
+  }
+  return out
+}
+
+function updateMd(currentMd, name, description, props, paramDocs, defaults, slots, slotDescs, examples, schema) {
+  const mergedParamDocs = { ...paramDocs }
+  const mergedSlotDescs = { ...slotDescs }
+  if (currentMd) {
+    const prev = readExistingPropDescriptions(currentMd, 'Props')
+    for (const [k, v] of Object.entries(prev)) {
+      if (!mergedParamDocs[k] || mergedParamDocs[k].length < v.length) mergedParamDocs[k] = v
+    }
+    const prevSlots = readExistingSlotDescriptions(currentMd)
+    for (const [k, v] of Object.entries(prevSlots)) {
+      if (!mergedSlotDescs[k] || mergedSlotDescs[k].length < v.length) mergedSlotDescs[k] = v
+    }
+  }
+
+  const propsTable = renderPropsTable(props, mergedParamDocs, defaults)
+  const slotsTable = renderSlotsTable(slots, mergedSlotDescs)
+  const examplesTable = renderExamplesTable(examples)
+
+  if (!currentMd) return generateSkeleton(name, description, propsTable, slotsTable, examplesTable, schema)
+
+  let out = currentMd
+  out = upsertTableBlock(out, 'Props', MARKERS.propsBegin, MARKERS.propsEnd, propsTable)
+  out = upsertTableBlock(out, 'Slots', MARKERS.slotsBegin, MARKERS.slotsEnd, slotsTable)
+  out = upsertTableBlock(out, 'Examples in theme', MARKERS.examplesBegin, MARKERS.examplesEnd, examplesTable)
+  out = upsertSchema(out, schema)
+  return out
+}
+
+/**
+ * Replace an existing `## Heading` table (|-rows) with a managed BEGIN/END block
+ * that contains the freshly-rendered table. Leaves non-table prose inside the
+ * section untouched (e.g. Stepper's `StepperItem: { … }` note lives on).
+ *
+ * If the markers already exist — simple replace-between.
+ * If the heading exists but no markers — find the first consecutive |-row run
+ * and wrap it with markers, replacing just those lines.
+ * If the heading is missing — append a new section after the previous managed
+ * block (or at EOF).
+ */
+function upsertTableBlock(md, heading, beginMarker, endMarker, table) {
+  // Fast path: markers exist.
+  const replaced = replaceBetween(md, beginMarker, endMarker, table)
+  if (replaced !== null) return replaced
+
+  const headingRe = new RegExp(`^##\\s+${heading}\\s*$`, 'm')
+  const headingMatch = md.match(headingRe)
+  if (headingMatch) {
+    const headingIdx = md.indexOf(headingMatch[0])
+    const afterHeading = md.indexOf('\n', headingIdx) + 1
+    const rest = md.slice(afterHeading)
+    const lines = rest.split('\n')
+    // Find start of the table (first line starting with `|`).
+    let tableStart = -1
+    let tableEnd = -1
+    for (let i = 0; i < lines.length; i++) {
+      const trimmed = lines[i].trim()
+      if (trimmed.startsWith('##')) break
+      if (tableStart < 0 && trimmed.startsWith('|')) tableStart = i
+      if (tableStart >= 0 && !trimmed.startsWith('|') && tableEnd < 0) {
+        tableEnd = i
+        break
+      }
+    }
+    if (tableStart >= 0) {
+      if (tableEnd < 0) tableEnd = lines.length
+      const before = lines.slice(0, tableStart).join('\n')
+      const after = lines.slice(tableEnd).join('\n')
+      const block = `${beginMarker}\n${table}\n${endMarker}`
+      const rebuilt = [before.trimEnd(), block, after.trimStart()].filter(Boolean).join('\n\n')
+      return md.slice(0, afterHeading) + rebuilt
+    }
+    // Heading exists but no table — inject block right after heading line.
+    const block = `\n${beginMarker}\n${table}\n${endMarker}\n`
+    return md.slice(0, afterHeading) + block + rest
+  }
+
+  // No heading — append at EOF (before any schema comment) as a new section.
+  const schemaIdx = md.indexOf(MARKERS.schemaBegin)
+  const newSection = `\n## ${heading}\n\n${beginMarker}\n${table}\n${endMarker}\n`
+  if (schemaIdx < 0) return md.trimEnd() + '\n' + newSection
+  return md.slice(0, schemaIdx).trimEnd() + '\n' + newSection + '\n' + md.slice(schemaIdx)
+}
+
+// ─── Orchestrate ─────────────────────────────────────────────────────────────
+
+function listVueComponents() {
+  const dir = join(THEME_DIR, 'components')
+  if (!existsSync(dir)) { console.error(`[gen-docs] missing ${dir}`); process.exit(2) }
+  return readdirSync(dir).filter(f => f.endsWith('.vue')).map(f => ({
+    name: basename(f, '.vue'),
+    path: join(dir, f),
+  }))
+}
+
+function listMdDocs() {
+  if (!existsSync(SKILL_DIR)) { mkdirSync(SKILL_DIR, { recursive: true }) }
+  return readdirSync(SKILL_DIR).filter(f => f.endsWith('.md'))
+}
+
+function diffSummary(oldSrc, newSrc) {
+  if (oldSrc === newSrc) return null
+  const oldLines = (oldSrc || '').split('\n').length
+  const newLines = newSrc.split('\n').length
+  return `${oldLines} → ${newLines} lines`
+}
+
+function main() {
+  const components = listVueComponents()
+  const existingMds = new Set(listMdDocs())
+  let changed = 0
+  let errors = 0
+  const orphans = []
+
+  for (const { name, path } of components) {
+    if (ONLY_SET && !ONLY_SET.has(name)) continue
+    const vueSrc = readFileSync(path, 'utf8')
+    const parts = splitSfc(vueSrc)
+    if (!parts) {
+      console.error(`[gen-docs] ${name}: could not parse SFC`)
+      errors++
+      continue
+    }
+
+    // Parse props from this file; if missing and it's a re-export, follow the
+    // import to the real implementation (components_base/X.vue).
+    let propsBlocks = extractPropsBlocks(parts.scriptSrc)
+    let slotsScriptSrc = parts.scriptSrc
+    let slotsTemplateSrc = parts.templateSrc
+    if (!propsBlocks) {
+      const reExport = resolveReExport(parts.scriptSrc, path)
+      if (reExport && existsSync(reExport)) {
+        const baseSrc = readFileSync(reExport, 'utf8')
+        const baseParts = splitSfc(baseSrc)
+        if (baseParts) {
+          propsBlocks = extractPropsBlocks(baseParts.scriptSrc)
+          slotsScriptSrc = baseParts.scriptSrc
+          slotsTemplateSrc = baseParts.templateSrc
+        }
+      }
+    }
+
+    const { description, paramDocs } = extractHeaderDoc(parts.scriptSrc, parts.headerComment)
+    const props = propsBlocks ? parsePropsBlock(propsBlocks.propsBlock) : []
+    const defaults = propsBlocks ? parseDefaultsBlock(propsBlocks.defaultsBlock) : {}
+    const slotsRaw = extractSlots(slotsScriptSrc, slotsTemplateSrc)
+    const slots = collapseSlots(slotsRaw)
+    const examples = findExamplesInTheme(THEME_DIR, name)
+
+    const schema = renderSchema(name, props, defaults, slots)
+
+    const mdPath = join(SKILL_DIR, `${name}.md`)
+    const existingMd = existsSync(mdPath) ? readFileSync(mdPath, 'utf8') : ''
+    existingMds.delete(`${name}.md`)
+
+    const newMd = updateMd(existingMd, name, description, props, paramDocs, defaults, slots, {}, examples, schema)
+    const diff = diffSummary(existingMd, newMd)
+    if (diff) {
+      changed++
+      if (CHECK_ONLY) console.log(`[drift] ${name}.md — ${diff}`)
+      else if (NO_WRITE) console.log(`[would-write] ${name}.md — ${diff}`)
+      else { writeFileSync(mdPath, newMd, 'utf8'); console.log(`[write] ${name}.md — ${diff}`) }
+    }
+  }
+
+  // Orphans — .md files in skill-dir with no matching .vue.
+  for (const md of existingMds) {
+    if (ONLY_SET) continue
+    orphans.push(md)
+  }
+  if (orphans.length) {
+    console.log(`[orphan] ${orphans.length} .md file(s) without matching .vue in theme:`)
+    for (const o of orphans) console.log(`  ${o}`)
+  }
+
+  if (CHECK_ONLY) {
+    if (changed > 0 || errors > 0 || orphans.length > 0) process.exit(1)
+    console.log('[gen-docs] All docs in sync')
+    process.exit(0)
+  }
+
+  console.log(`[gen-docs] ${components.length} components, ${changed} updated, ${errors} error(s), ${orphans.length} orphan(s)`)
+  process.exit(errors > 0 ? 2 : 0)
+}
+
+main()