@dongfangw/study-kit 0.1.3 → 0.2.0

package/skills/make-mindmap/render.mjs

@@ -0,0 +1,855 @@
+#!/usr/bin/env node
+/**
+ * 零依赖思维导图渲染器：缩进大纲 → SVG。
+ *
+ * 为什么自带渲染器（而不是挂 PlantUML / mermaid-cli / Kroki）：
+ *   AI 学伴的阅读器用**裸 @asciidoctor/core** 逐页渲染（study-kit 的 ext/adoc-convert），
+ *   没有装 asciidoctor-diagram / kroki 扩展。所以 `[plantuml]`、`[mermaid]` 这些图块
+ *   在阅读器里会退化成一段等宽纯文本——正是要消灭的那种"文本路线图"。
+ *   而阅读器会把 `image::` 解析成 <img src="/aero-kb/asset?...">，asset 路由又把 .svg
+ *   当 image/svg+xml 伺服。于是路线是：**先离线渲染成 SVG 落盘，再用 image:: 引用**。
+ *   这条路不需要 Java、不需要 Chrome、不需要联网，打印时还是矢量。
+ *
+ * 输入语法 = Mermaid mindmap 的缩进子集（可以直接把 mermaid 的 mindmap 粘过来）：
+ *
+ *   ---                        ← 可选 YAML 前置配置（见 SKILL.md 的配置项总表）
+ *   title: 思维导图插图
+ *   layout: right
+ *   theme: paper
+ *   ---
+ *   mindmap                    ← 可选关键字
+ *     root((思维导图插图))
+ *       写大纲
+ *         缩进即层级
+ *       渲染成 SVG
+ *         零依赖，纯 Node
+ *
+ * 节点形状：id((圆)) / id(圆角) / id[方框] / id{{六边形}} / 裸文本（用默认形状）
+ *           其中 id 可省略；`(( ))` 之类也可以只写形状不带 id。
+ * 样式类：  行尾或下一行写 `:::强调` 引用配置里的 classes；`- ` / `* ` 项目符号会被忽略。
+ *
+ * 用法：
+ *   node render.mjs <源文件> [选项]
+ *     --out <路径>      输出 SVG（缺省与源文件同名 .svg）
+ *     --theme <名>      paper|aero|ink|warm|forest|slate|contrast
+ *     --layout <名>     right|left|both|tree
+ *     --connector <名>  curve|elbow|straight|arc
+ *     --density <名>    compact|normal|roomy
+ *     --title <文本>    覆盖标题
+ *     --transparent     无底色（深色阅读主题下更协调）
+ *     --scale <系数>    整体字号系数
+ *     --json            只打印统计（节点数 / 画布尺寸），不写文件
+ *     -h, --help
+ */
+import { mkdirSync, readFileSync, writeFileSync } from 'node:fs'
+import path from 'node:path'
+
+// ════════════════════════════════════════════════════════════════════════════
+// 0. 极简 YAML（只够读前置配置：标量 / 行内 [a,b] {a: 1} / 块级列表与映射 / 注释）
+//    不引第三方依赖：技能要能在任何机器上直接跑；解析不了就报清楚的行号。
+// ════════════════════════════════════════════════════════════════════════════
+function stripComment(line) {
+  let q = null
+  for (let i = 0; i < line.length; i += 1) {
+    const ch = line[i]
+    if (q !== null) { if (ch === q) q = null; continue }
+    if (ch === '"' || ch === "'") { q = ch; continue }
+    if (ch === '#' && (i === 0 || /\s/u.test(line[i - 1]))) return line.slice(0, i)
+  }
+  return line
+}
+
+function splitTop(text, sep) {
+  const out = []
+  let depth = 0
+  let q = null
+  let cur = ''
+  for (const ch of text) {
+    if (q !== null) { cur += ch; if (ch === q) q = null; continue }
+    if (ch === '"' || ch === "'") { q = ch; cur += ch; continue }
+    if (ch === '[' || ch === '{' || ch === '(') depth += 1
+    if (ch === ']' || ch === '}' || ch === ')') depth -= 1
+    if (ch === sep && depth === 0) { out.push(cur); cur = ''; continue }
+    cur += ch
+  }
+  out.push(cur)
+  return out.map((s) => s.trim()).filter((s) => s !== '')
+}
+
+const unquote = (s) => {
+  const t = String(s).trim()
+  if ((t.startsWith('"') && t.endsWith('"')) || (t.startsWith("'") && t.endsWith("'"))) return t.slice(1, -1)
+  return t
+}
+
+function parseScalar(raw) {
+  const s = String(raw).trim()
+  if (s === '' || s === '~' || s === 'null') return null
+  if (s === 'true') return true
+  if (s === 'false') return false
+  if (/^-?\d+(\.\d+)?$/u.test(s)) return Number(s)
+  if (s.startsWith('[') && s.endsWith(']')) return splitTop(s.slice(1, -1), ',').map(parseScalar)
+  if (s.startsWith('{') && s.endsWith('}')) {
+    const obj = {}
+    for (const part of splitTop(s.slice(1, -1), ',')) {
+      const idx = part.indexOf(':')
+      if (idx < 0) continue
+      obj[unquote(part.slice(0, idx))] = parseScalar(part.slice(idx + 1))
+    }
+    return obj
+  }
+  if (s.startsWith('"') && s.endsWith('"') && s.length > 1) return s.slice(1, -1).replace(/\\"/gu, '"').replace(/\\n/gu, '\n')
+  if (s.startsWith("'") && s.endsWith("'") && s.length > 1) return s.slice(1, -1)
+  return s
+}
+
+function keyColon(body) {
+  let q = null
+  let depth = 0
+  for (let i = 0; i < body.length; i += 1) {
+    const ch = body[i]
+    if (q !== null) { if (ch === q) q = null; continue }
+    if (ch === '"' || ch === "'") { q = ch; continue }
+    if (ch === '[' || ch === '{') depth += 1
+    if (ch === ']' || ch === '}') depth -= 1
+    if (ch === ':' && depth === 0 && (i === body.length - 1 || /\s/u.test(body[i + 1]))) return i
+  }
+  return null
+}
+
+function parseMiniYaml(text) {
+  const rows = text.split(/\r?\n/u)
+    .map((raw) => stripComment(raw).replace(/\s+$/u, ''))
+    .filter((raw) => raw.trim() !== '')
+    .map((raw) => ({ indent: raw.length - raw.trimStart().length, body: raw.trim() }))
+  let at = 0
+
+  function parseBlock(indent) {
+    if (at >= rows.length) return null
+    const isList = rows[at].body === '-' || rows[at].body.startsWith('- ')
+    if (isList) {
+      const arr = []
+      while (at < rows.length && rows[at].indent === indent && (rows[at].body === '-' || rows[at].body.startsWith('- '))) {
+        const body = rows[at].body === '-' ? '' : rows[at].body.slice(2).trim()
+        at += 1
+        if (body === '') {
+          arr.push(at < rows.length && rows[at].indent > indent ? parseBlock(rows[at].indent) : null)
+          continue
+        }
+        if (body.startsWith('{')) { arr.push(parseScalar(body)); continue }
+        const colon = keyColon(body)
+        if (colon === null) { arr.push(parseScalar(body)); continue }
+        const obj = {}
+        obj[unquote(body.slice(0, colon))] = parseScalar(body.slice(colon + 1))
+        while (at < rows.length && rows[at].indent > indent && !rows[at].body.startsWith('- ')) {
+          const b = rows[at].body
+          const c = keyColon(b)
+          at += 1
+          if (c === null) continue
+          const k = unquote(b.slice(0, c))
+          const rest = b.slice(c + 1).trim()
+          obj[k] = rest === '' && at < rows.length && rows[at].indent > indent ? parseBlock(rows[at].indent) : parseScalar(rest)
+        }
+        arr.push(obj)
+      }
+      return arr
+    }
+    const obj = {}
+    while (at < rows.length && rows[at].indent === indent) {
+      const body = rows[at].body
+      const colon = keyColon(body)
+      if (colon === null) { at += 1; continue }
+      const key = unquote(body.slice(0, colon))
+      const rest = body.slice(colon + 1).trim()
+      at += 1
+      obj[key] = rest === '' ? (at < rows.length && rows[at].indent > indent ? parseBlock(rows[at].indent) : null) : parseScalar(rest)
+    }
+    return obj
+  }
+  if (rows.length === 0) return {}
+  return parseBlock(rows[0].indent) ?? {}
+}
+
+// ════════════════════════════════════════════════════════════════════════════
+// 1. 主题 / 密度 / 枚举
+// ════════════════════════════════════════════════════════════════════════════
+const THEMES = {
+  paper: {
+    bg: '#ffffff', ink: '#1f2328', muted: '#6b7280', rule: '#d8dde5',
+    palette: ['#3b6ea5', '#b2623c', '#3f7f5f', '#7f5aa8', '#9a7b2f', '#3d7b8a'],
+    root: '#25405f',
+  },
+  aero: {
+    bg: '#fbfdff', ink: '#16233a', muted: '#5f7086', rule: '#d3dfec',
+    palette: ['#1f5fa8', '#2b8a8a', '#c2703a', '#6a4fa3', '#2f7d4f', '#a8434f'],
+    root: '#1b3a63',
+  },
+  ink: {
+    bg: '#ffffff', ink: '#111111', muted: '#5a5a5a', rule: '#cfcfcf',
+    palette: ['#3a3a3a', '#6a6a6a', '#262626', '#4f4f4f', '#7a7a7a', '#1a1a1a'],
+    root: '#111111',
+  },
+  warm: {
+    bg: '#fdf8f0', ink: '#3a3126', muted: '#8d7f68', rule: '#e4d8c2',
+    palette: ['#a8672f', '#8a6a2b', '#5f7d42', '#a84f52', '#3f6f89', '#7a5a9a'],
+    root: '#7a4a1e',
+  },
+  forest: {
+    bg: '#f5f9f3', ink: '#22301d', muted: '#77866e', rule: '#d5e2cc',
+    palette: ['#2f7d4f', '#4f8a3a', '#8a7d2f', '#2f7d7d', '#6a4fa3', '#a85a3a'],
+    root: '#1f4f33',
+  },
+  slate: {
+    bg: '#22262e', ink: '#e6ebf2', muted: '#93a1b3', rule: '#39424f',
+    palette: ['#7aa2f7', '#7dcfff', '#e0af68', '#bb9af7', '#9ece6a', '#f7768e'],
+    root: '#3d59a1',
+  },
+  contrast: {
+    bg: '#ffffff', ink: '#000000', muted: '#333333', rule: '#000000',
+    palette: ['#000000', '#8b0000', '#003f8b', '#00502a', '#5a2d82', '#8a5a00'],
+    root: '#000000',
+  },
+}
+
+const DENSITY = {
+  compact: { level: 40, sibling: 4, branch: 13, padX: 9, padY: 4 },
+  normal: { level: 66, sibling: 7, branch: 26, padX: 13, padY: 6.5 },
+  roomy: { level: 88, sibling: 13, branch: 40, padX: 17, padY: 9.5 },
+}
+
+const CONNECTORS = new Set(['curve', 'elbow', 'straight', 'arc'])
+const LAYOUTS = new Set(['right', 'left', 'both', 'tree'])
+const SHAPES = new Set(['rect', 'rounded', 'pill', 'hex', 'circle', 'underline', 'none'])
+
+// ════════════════════════════════════════════════════════════════════════════
+// 2. 颜色工具
+// ════════════════════════════════════════════════════════════════════════════
+function toRgb(color) {
+  if (typeof color !== 'string') return null
+  const s = color.trim()
+  let m = /^#([0-9a-f]{3})$/iu.exec(s)
+  if (m) return [0, 1, 2].map((i) => parseInt(m[1][i] + m[1][i], 16))
+  m = /^#([0-9a-f]{6})$/iu.exec(s)
+  if (m) return [0, 2, 4].map((i) => parseInt(m[1].slice(i, i + 2), 16))
+  m = /^rgba?\(([^)]+)\)$/iu.exec(s)
+  if (m) {
+    const p = m[1].split(',').map((v) => parseFloat(v.trim()))
+    if (p.length >= 3) return p.slice(0, 3)
+  }
+  return null
+}
+const toHex = (rgb) => `#${rgb.map((v) => Math.max(0, Math.min(255, Math.round(v))).toString(16).padStart(2, '0')).join('')}`
+function mix(a, b, t, fallback = '#888888') {
+  const x = toRgb(a) ?? toRgb(fallback)
+  const y = toRgb(b) ?? toRgb(fallback)
+  if (x === null || y === null) return typeof a === 'string' && a !== 'none' ? a : fallback
+  return toHex(x.map((v, i) => v + (y[i] - v) * t))
+}
+const isTransparent = (bg) => bg === 'transparent' || bg === 'none'
+function readableOn(color) {
+  const rgb = toRgb(color)
+  if (rgb === null) return '#ffffff'
+  const [r, g, b] = rgb.map((v) => {
+    const s = v / 255
+    return s <= 0.03928 ? s / 12.92 : ((s + 0.055) / 1.055) ** 2.4
+  })
+  const lum = 0.2126 * r + 0.7152 * g + 0.0722 * b
+  return lum > 0.45 ? '#111318' : '#ffffff'
+}
+
+// ════════════════════════════════════════════════════════════════════════════
+// 3. 源文件解析
+// ════════════════════════════════════════════════════════════════════════════
+const CIRCLED = [...'①②③④⑤⑥⑦⑧⑨⑩⑪⑫⑬⑭⑮⑯⑰⑱⑲⑳']
+
+function splitFrontMatter(text) {
+  const t = text.replace(/^\uFEFF/u, '')
+  const m = /^\s*---[ \t]*\r?\n([\s\S]*?)\r?\n---[ \t]*(\r?\n|$)/u.exec(t)
+  if (m === null) return { config: {}, body: t }
+  return { config: parseMiniYaml(m[1]), body: t.slice(m[0].length) }
+}
+
+function parseSource(body) {
+  const lines = body.split(/\r?\n/u)
+  const flat = []
+  let order = 0
+  for (const raw of lines) {
+    const line = raw.replace(/\t/gu, '    ').replace(/\s+$/u, '')
+    if (line.trim() === '') continue
+    if (/^\s*%%/u.test(line)) continue
+    if (/^\s*(mindmap|outline)\s*$/iu.test(line)) continue
+    let text = line.trim()
+    text = text.replace(/^[-*+]\s+/u, '')
+    if (text === '') continue
+    flat.push({ raw: text, indent: line.length - line.trimStart().length, order: order++ })
+  }
+  if (flat.length === 0) throw new Error('源文件里没有任何节点行')
+
+  const stack = []
+  const roots = []
+  for (const n of flat) {
+    n.children = []
+    while (stack.length > 0 && stack[stack.length - 1].indent >= n.indent) stack.pop()
+    if (stack.length === 0) roots.push(n)
+    else stack[stack.length - 1].children.push(n)
+    stack.push(n)
+  }
+  if (roots.length === 1) return { root: roots[0], multi: false }
+  const synthetic = { raw: '', indent: -1, order: -1, children: roots, synthetic: true }
+  return { root: synthetic, multi: true }
+}
+
+// `id((文本))` / `((文本))` / `id[文本]` / 裸文本
+const SHAPE_RULES = [
+  { re: /^(?:[\w-]*)(?=\()\s*\(\(([\s\S]*)\)\)$/u, shape: 'circle' },
+  { re: /^(?:[\w-]*)\{\{([\s\S]*)\}\}$/u, shape: 'hex' },
+  { re: /^(?:[\w-]*)\[([\s\S]*)\]$/u, shape: 'rect' },
+  { re: /^(?:[\w-]*)(?=\()\s*\(([\s\S]*)\)$/u, shape: 'rounded' },
+]
+
+function decorate(node, depth, top) {
+  let text = node.raw
+  let classes = []
+  const cls = /\s*:::([\w\-\s]+)$/u.exec(text)
+  if (cls !== null) {
+    classes = cls[1].trim().split(/\s+/u)
+    text = text.slice(0, cls.index).trim()
+  }
+  let shape = null
+  for (const r of SHAPE_RULES) {
+    const m = r.re.exec(text)
+    if (m !== null) {
+      // 只在括号内确有内容时才认（避免把 "详见 (a)" 这类当形状）
+      text = m[1].trim()
+      shape = r.shape
+      break
+    }
+  }
+  node.text = text.replace(/<br\s*\/?>/giu, '\n')
+  node.shape = shape
+  node.classes = classes
+  node.depth = depth
+  node.top = depth <= 1 ? node : top
+  node.index = node.index ?? 0
+  node.children.forEach((child, i) => { child.index = i; decorate(child, depth + 1, node.top) })
+  return node
+}
+
+// ════════════════════════════════════════════════════════════════════════════
+// 4. 文字测量（无 canvas：CJK / 拉丁 / 标点分别估算，确定性优先）
+// ════════════════════════════════════════════════════════════════════════════
+const CJK = /[\u2E80-\u9FFF\uF900-\uFAFF\uFE30-\uFE4F\uFF00-\uFF60\uFFE0-\uFFE6]/u
+function charWidth(ch) {
+  if (CJK.test(ch)) return 1.0
+  if (ch === ' ') return 0.32
+  // ①–⑳ 这类圈号在全角 em 上排，按 1.05em 算，否则右边缘会被字形顶出框
+  if (/[\u2460-\u24FF\u2776-\u2793]/u.test(ch)) return 1.05
+  // 希腊字母（α ε Λ β）在中文正文里按 0.66em 估，太窄会让公式行溢出
+  if (/[\u0370-\u03FF]/u.test(ch)) return 0.66
+  if (/[A-Z0-9]/u.test(ch)) return 0.62
+  if (/[a-z]/u.test(ch)) return 0.55
+  if (/[.,:;'"`|!()[\]{}]/u.test(ch)) return 0.34
+  if (/[-–—_/\\+*=<>~^%$#@&·×∈≤≥≈→←↓↑]/u.test(ch)) return 0.56
+  if ((ch.codePointAt(0) ?? 0) > 0xffff) return 1.0
+  return 0.58
+}
+const textWidth = (s, size) => {
+  let w = 0
+  for (const ch of s) w += charWidth(ch)
+  return w * size
+}
+function wrapText(text, maxWidth, size) {
+  const out = []
+  for (const para of String(text).split('\n')) {
+    if (maxWidth <= 0 || textWidth(para, size) <= maxWidth) { out.push(para); continue }
+    const tokens = []
+    let buf = ''
+    for (const ch of para) {
+      if (CJK.test(ch) || ch === ' ') {
+        if (buf !== '') { tokens.push(buf); buf = '' }
+        tokens.push(ch)
+      } else buf += ch
+    }
+    if (buf !== '') tokens.push(buf)
+    let line = ''
+    for (const tk of tokens) {
+      if (line !== '' && textWidth(line + tk, size) > maxWidth) {
+        out.push(line.trimEnd())
+        line = tk === ' ' ? '' : tk
+      } else line += tk
+    }
+    out.push(line.trimEnd())
+  }
+  return out.length === 0 ? [''] : out
+}
+
+// ════════════════════════════════════════════════════════════════════════════
+// 5. 样式
+// ════════════════════════════════════════════════════════════════════════════
+function buildStyles(cfg) {
+  const theme = THEMES[cfg.theme] ?? THEMES.paper
+  const density = DENSITY[cfg.density] ?? DENSITY.normal
+  const fs = Number(cfg.font?.size ?? 15) * Number(cfg.font?.scale ?? 1) * Number(cfg.scale ?? 1)
+  const gap = {
+    level: Number(cfg.gap?.level ?? density.level),
+    sibling: Number(cfg.gap?.sibling ?? density.sibling),
+    branch: Number(cfg.gap?.branch ?? density.branch),
+  }
+  const pad = {
+    x: Number(cfg.padding?.x ?? density.padX),
+    y: Number(cfg.padding?.y ?? density.padY),
+  }
+  const bg = isTransparent(cfg.background) ? 'transparent' : (cfg.background ?? theme.bg)
+  const paper = isTransparent(bg) ? '#ffffff' : bg
+  const palette = Array.isArray(cfg.palette) && cfg.palette.length > 0 ? cfg.palette : theme.palette
+  const defaultShape = SHAPES.has(cfg.shape) ? cfg.shape : 'rounded'
+  const base = [
+    { size: fs * 1.42, weight: 700, shape: 'pill', fill: theme.root, color: readableOn(theme.root), stroke: 'none', sw: 0, radius: 999 },
+    { size: fs * 1.1, weight: 650, shape: 'pill', fill: 'auto', color: 'auto', stroke: 'auto', sw: 1.4, radius: 999 },
+    { size: fs * 1.0, weight: 500, shape: defaultShape, fill: 'none', color: 'auto', stroke: 'none', sw: 0, radius: Number(cfg.radius ?? 9) },
+    { size: fs * 0.93, weight: 400, shape: 'none', fill: 'none', color: theme.muted, stroke: 'none', sw: 0, radius: Number(cfg.radius ?? 9) },
+  ]
+  const declared = Array.isArray(cfg.levels) ? cfg.levels : []
+  const levels = base.map((b, i) => ({ ...b, ...(declared[i] ?? {}) }))
+  const classes = cfg.classes && typeof cfg.classes === 'object' ? cfg.classes : {}
+  return { theme, paper, fs, gap, pad, bg, palette, levels, classes, defaultShape }
+}
+
+function branchColorOf(node, st) {
+  const owner = node.top === node ? node : node.top
+  return st.palette[(owner?.index ?? 0) % st.palette.length]
+}
+
+function resolveStyle(node, st) {
+  const depth = node.depth
+  const branch = branchColorOf(node, st)
+  const lt = st.levels[Math.min(depth, st.levels.length - 1)]
+  const style = {
+    size: Number(lt.size),
+    weight: Number(lt.weight),
+    shape: lt.shape === 'auto' || lt.shape === undefined ? st.defaultShape : lt.shape,
+    fill: lt.fill,
+    stroke: lt.stroke,
+    sw: Number(lt.sw ?? 0),
+    color: lt.color,
+    radius: Number(lt.radius ?? 9),
+    italic: lt.italic === true,
+    padX: lt.padX === undefined ? undefined : Number(lt.padX),
+    padY: lt.padY === undefined ? undefined : Number(lt.padY),
+    maxWidth: lt.maxWidth === undefined ? undefined : Number(lt.maxWidth),
+  }
+  if (style.fill === 'auto' || style.fill == null || style.fill === '') {
+    style.fill = depth === 0 ? st.theme.root : mix(branch, st.paper, 0.87)
+  }
+  if (style.stroke === 'auto') style.stroke = branch
+  if (style.color === 'auto' || style.color == null) {
+    style.color = depth === 0 ? readableOn(style.fill) : mix(branch, st.theme.ink, 0.42)
+  }
+  if (typeof style.fill !== 'string') style.fill = 'none'
+  if (typeof style.stroke !== 'string') style.stroke = 'none'
+  for (const name of node.classes ?? []) {
+    const c = st.classes[name]
+    if (!c) continue
+    for (const [k, v] of Object.entries(c)) {
+      if (k === 'size' || k === 'sw' || k === 'radius') style[k] = Number(v)
+      else if (k === 'italic') style[k] = v === true || v === 'true'
+      else style[k] = v
+    }
+  }
+  if (node.shape !== null) style.shape = node.shape
+  if (style.shape === 'circle') style.radius = 999
+  style.branch = branch
+  return style
+}
+
+// ════════════════════════════════════════════════════════════════════════════
+// 6. 度量 + 布局
+// ════════════════════════════════════════════════════════════════════════════
+function measure(root, cfg, st) {
+  const maxW = Number(cfg.maxNodeWidth ?? 240)
+  const rootMaxW = Number(cfg.rootMaxWidth ?? maxW * 2)
+  const lh = Number(cfg.font?.lineHeight ?? 1.32)
+  const walk = (node) => {
+    node.style = resolveStyle(node, st)
+    const padX = node.style.padX ?? st.pad.x
+    const padY = node.style.padY ?? st.pad.y
+    const budget = node.depth === 0 ? Math.max(rootMaxW, maxW) : (node.style.maxWidth ?? maxW)
+    const prefixText = node.numberPrefix ? `${node.numberPrefix} ` : ''
+    node.lines = wrapText(prefixText + node.text, Math.max(40, budget - padX * 2), node.style.size)
+    const wMax = Math.max(...node.lines.map((l) => textWidth(l, node.style.size)), 8)
+    node.tw = wMax
+    node.th = node.lines.length * node.style.size * lh
+    node.w = wMax + padX * 2
+    node.h = node.th + padY * 2
+    if (node.style.shape === 'none' || node.style.shape === 'underline') {
+      node.w = wMax + padX * 0.5
+      node.h = node.th + 2
+    } else if (node.style.shape === 'pill' || node.style.shape === 'circle') {
+      // 胶囊/圆的端头是半圆，水平内边距必须至少 h/2 才不会让字顶出弧线
+      node.w = Math.max(node.w, wMax + node.h * 1.02)
+    }
+    node.children.forEach(walk)
+  }
+  const number = (node, prefix) => {
+    node.numberPrefix = ''
+    if (cfg.numbering === 'circled' && node.depth === 1) node.numberPrefix = CIRCLED[node.index] ?? `${node.index + 1}`
+    if (cfg.numbering === 'arabic') node.numberPrefix = prefix === '' ? `${node.index + 1}` : `${prefix}.${node.index + 1}`
+    if (cfg.numbering === 'path' && node.depth >= 1) node.numberPrefix = `${prefix}${node.index + 1}`
+    node.children.forEach((c) => number(c, node.depth === 0 ? '' : (node.numberPrefix || `${node.index + 1}`)))
+  }
+  number(root, '')
+  walk(root)
+  return { lh }
+}
+
+const collect = (node, acc = []) => {
+  acc.push(node)
+  for (const c of node.children) collect(c, acc)
+  return acc
+}
+
+/**
+ * 横向布局（right / left / both）。
+ * 主轴：depth 方向（x）；副轴：兄弟方向（y）。
+ * 主轴用「父节点外侧边 + 层间距 + 自身半宽」累加，这样父宽度不影响子层对齐，
+ * 但父→子的连线不会穿进自己的框。
+ */
+function layoutHorizontal(root, st, mode) {
+  const kids = root.children
+  let groups
+  if (mode === 'both') {
+    const half = Math.ceil(kids.length / 2)
+    groups = [
+      { side: 'right', nodes: kids.slice(0, half) },
+      { side: 'left', nodes: kids.slice(half) },
+    ]
+    for (const g of groups) for (const n of g.nodes) markSide(n, g.side)
+  } else {
+    const side = mode === 'left' ? 'left' : 'right'
+    groups = [{ side, nodes: kids }]
+    for (const n of kids) markSide(n, side)
+  }
+  root.side = mode === 'left' ? 'left' : 'right'
+
+  const maxAtDepth = {}
+  for (const n of collect(root)) maxAtDepth[n.depth] = Math.max(maxAtDepth[n.depth] ?? 0, n.w)
+
+  for (const g of groups) {
+    if (g.nodes.length === 0) continue
+    const ext = (n) => {
+      const kids2 = n.children
+      const total = kids2.reduce((s, k) => s + ext(k), 0) + Math.max(0, kids2.length - 1) * st.gap.sibling
+      n.kidsTotal = total
+      n.ext = Math.max(n.h, total)
+      return n.ext
+    }
+    const groupTotal = g.nodes.reduce((s, k) => s + ext(k), 0) + Math.max(0, g.nodes.length - 1) * st.gap.branch
+    let cursor = -groupTotal / 2
+    const placeCross = (n, start) => {
+      n.cy = start + n.ext / 2
+      let c = start + (n.ext - n.kidsTotal) / 2
+      for (const k of n.children) { placeCross(k, c); c += k.ext + st.gap.sibling }
+    }
+    for (const k of g.nodes) { placeCross(k, cursor); cursor += k.ext + st.gap.branch }
+
+    const walkMain = (node, parent) => {
+      const dir = g.side === 'left' ? -1 : 1
+      if (parent === root) {
+        node.cx = dir * (root.w / 2 + st.gap.level + node.w / 2)
+      } else {
+        node.cx = parent.cx + dir * (parent.w / 2 + st.gap.level + node.w / 2)
+      }
+      node.children.forEach((c) => walkMain(c, node))
+    }
+    for (const k of g.nodes) walkMain(k, root)
+  }
+  root.cx = 0
+  root.cy = 0
+  // 上下居中：把整幅按 y 归零
+  const ys = collect(root).map((n) => n.cy)
+  const mid = (Math.min(...ys) + Math.max(...ys)) / 2
+  for (const n of collect(root)) n.cy -= mid
+  return { vertical: false }
+}
+
+function markSide(node, side) {
+  node.side = side
+  node.children.forEach((c) => markSide(c, side))
+}
+
+/** 纵向布局（tree / org）：主轴是 y，副轴是 x。文字仍然横排。 */
+function layoutVertical(root, st) {
+  for (const n of collect(root)) n.side = 'right'
+  const ext = (n) => {
+    const total = n.children.reduce((s, k) => s + ext(k), 0) + Math.max(0, n.children.length - 1) * st.gap.sibling
+    n.kidsTotal = total
+    n.ext = Math.max(n.w, total)
+    return n.ext
+  }
+  const total = ext(root)
+  const placeCross = (n, start) => {
+    n.cx = start + n.ext / 2
+    let c = start + (n.ext - n.kidsTotal) / 2
+    for (const k of n.children) { placeCross(k, c); c += k.ext + st.gap.sibling }
+  }
+  placeCross(root, -total / 2)
+  const walkMain = (node, parent) => {
+    node.cy = parent === null ? 0 : parent.cy + parent.h / 2 + st.gap.level + node.h / 2
+    node.children.forEach((c) => walkMain(c, node))
+  }
+  walkMain(root, null)
+  const xs = collect(root).map((n) => n.cx)
+  const mid = (Math.min(...xs) + Math.max(...xs)) / 2
+  for (const n of collect(root)) n.cx -= mid
+  return { vertical: true }
+}
+
+// ════════════════════════════════════════════════════════════════════════════
+// 7. SVG
+// ════════════════════════════════════════════════════════════════════════════
+const esc = (s) => String(s).replace(/&/gu, '&amp;').replace(/</gu, '&lt;').replace(/>/gu, '&gt;').replace(/"/gu, '&quot;')
+const n2 = (v) => Math.round(v * 100) / 100
+
+function nodeAttrs(n) {
+  const x = n2(n.cx - n.w / 2)
+  const y = n2(n.cy - n.h / 2)
+  return { x, y, w: n2(n.w), h: n2(n.h) }
+}
+
+function shapeMarkup(n) {
+  const s = n.style
+  const { x, y, w, h } = nodeAttrs(n)
+  if (s.shape === 'none' || s.shape === 'underline') {
+    if (s.shape !== 'underline') return ''
+    const yy = n2(n.cy + n.h / 2)
+    return `<line x1="${n2(n.cx - n.w / 2)}" y1="${yy}" x2="${n2(n.cx + n.w / 2)}" y2="${yy}" stroke="${s.branch}" stroke-width="1.1" opacity="0.5" stroke-linecap="round"/>`
+  }
+  const strokeAttr = s.sw > 0 && s.stroke !== 'none' ? ` stroke="${s.stroke}" stroke-width="${n2(s.sw)}"` : ' stroke="none"'
+  const fillAttr = ` fill="${s.fill}"`
+  let d
+  if (s.shape === 'circle' || s.shape === 'pill') {
+    const rx = w / 2
+    const ry = h / 2
+    d = `M${n2(x)},${n2(y + ry)} a${n2(rx)},${n2(ry)} 0 1 0 ${n2(w)},0 a${n2(rx)},${n2(ry)} 0 1 0 ${n2(-w)},0 Z`
+  } else if (s.shape === 'hex') {
+    const inset = Math.min(h * 0.45, w * 0.16)
+    d = `M${n2(x + inset)},${n2(y)} H${n2(x + w - inset)} L${n2(x + w)},${n2(y + h / 2)} L${n2(x + w - inset)},${n2(y + h)} H${n2(x + inset)} L${n2(x)},${n2(y + h / 2)} Z`
+  } else {
+    const r = Math.max(0, Math.min(s.shape === 'rect' ? 0 : s.radius, w / 2, h / 2))
+    if (r < 0.6) d = `M${n2(x)},${n2(y)} h${n2(w)} v${n2(h)} h${n2(-w)} Z`
+    else d = `M${n2(x + r)},${n2(y)} h${n2(w - 2 * r)} a${n2(r)},${n2(r)} 0 0 1 ${n2(r)},${n2(r)} v${n2(h - 2 * r)} a${n2(r)},${n2(r)} 0 0 1 ${n2(-r)},${n2(r)} h${n2(-(w - 2 * r))} a${n2(r)},${n2(r)} 0 0 1 ${n2(-r)},${n2(-r)} v${n2(-(h - 2 * r))} a${n2(r)},${n2(r)} 0 0 1 ${n2(r)},${n2(-r)} Z`
+  }
+  return `<path d="${d}"${fillAttr}${strokeAttr}/>`
+}
+
+function edgePath(pa, ch, connector, vertical) {
+  if (vertical) {
+    const sy = pa.cy + pa.h / 2
+    const ey = ch.cy - ch.h / 2
+    const sx = pa.cx
+    const ex = ch.cx
+    const dy = ey - sy
+    if (connector === 'straight') return `M${n2(sx)},${n2(sy)} L${n2(ex)},${n2(ey)}`
+    if (connector === 'elbow') return `M${n2(sx)},${n2(sy)} V${n2(sy + dy / 2)} H${n2(ex)} V${n2(ey)}`
+    const c = Math.max(8, Math.abs(dy) * 0.45)
+    return `M${n2(sx)},${n2(sy)} C${n2(sx)},${n2(sy + c)} ${n2(ex)},${n2(ey - c)} ${n2(ex)},${n2(ey)}`
+  }
+  const dir = ch.side === 'left' ? -1 : 1
+  const sx = pa.cx + (dir > 0 ? pa.w / 2 : -pa.w / 2)
+  const ex = ch.cx - (dir > 0 ? ch.w / 2 : -ch.w / 2)
+  const sy = pa.cy
+  const ey = ch.cy
+  const dx = ex - sx
+  if (connector === 'straight') return `M${n2(sx)},${n2(sy)} L${n2(ex)},${n2(ey)}`
+  if (connector === 'elbow') return `M${n2(sx)},${n2(sy)} H${n2(sx + dx / 2)} V${n2(ey)} H${n2(ex)}`
+  if (connector === 'arc') {
+    const r = Math.max(Math.abs(dx) * 0.9, Math.abs(ey - sy) * 1.1, 10)
+    return `M${n2(sx)},${n2(sy)} A${n2(r)},${n2(r)} 0 0 ${dir > 0 ? 1 : 0} ${n2(ex)},${n2(ey)}`
+  }
+  const c = Math.max(10, Math.abs(dx) * 0.42)
+  return `M${n2(sx)},${n2(sy)} C${n2(sx + dir * c)},${n2(sy)} ${n2(ex - dir * c)},${n2(ey)} ${n2(ex)},${n2(ey)}`
+}
+
+function render(root, cfg, st, geo) {
+  const all = collect(root)
+  const connector = CONNECTORS.has(cfg.connector) ? cfg.connector : 'curve'
+  const family = String(cfg.font?.family ?? "'PingFang SC', 'Microsoft YaHei', 'Noto Sans SC', -apple-system, 'Segoe UI', sans-serif")
+  const lh = Number(cfg.font?.lineHeight ?? 1.32)
+  const pad = Number(cfg.canvasPad ?? 26)
+
+  let minX = Infinity; let maxX = -Infinity; let minY = Infinity; let maxY = -Infinity
+  for (const n of all) {
+    minX = Math.min(minX, n.cx - n.w / 2)
+    maxX = Math.max(maxX, n.cx + n.w / 2)
+    minY = Math.min(minY, n.cy - n.h / 2)
+    maxY = Math.max(maxY, n.cy + n.h / 2)
+  }
+  const contentW = maxX - minX
+  const contentH = maxY - minY
+
+  // 页眉页脚在**绝对坐标**里画，避免与 group 平移叠算
+  const titleSize = st.fs * 1.5
+  const subSize = st.fs * 0.95
+  const hasTitle = typeof cfg.title === 'string' && cfg.title !== ''
+  const hasSub = typeof cfg.subtitle === 'string' && cfg.subtitle !== ''
+  const hasFoot = typeof cfg.footnote === 'string' && cfg.footnote !== ''
+  let header = 0
+  if (hasTitle) header += titleSize * 1.05
+  if (hasSub) header += subSize * 1.5
+  if (hasTitle || hasSub) header += pad * 0.5
+  const footH = hasFoot ? st.fs * 2.1 + pad * 0.4 : 0
+
+  const W = Math.max(contentW + pad * 2, hasTitle ? textWidth(cfg.title, titleSize) * 0.55 + pad * 2 : 0)
+  const H = contentH + pad * 2 + header + footH
+  const offsetX = (W - contentW) / 2 - minX
+  const offsetY = pad + header - minY
+
+  const out = []
+  out.push(`<svg xmlns="http://www.w3.org/2000/svg" width="${n2(W)}" height="${n2(H)}" viewBox="0 0 ${n2(W)} ${n2(H)}" role="img" aria-label="${esc(cfg.title ?? (root.text || 'mindmap'))}">`)
+  out.push(`<title>${esc(cfg.title ?? (root.text || 'mindmap'))}</title>`)
+  if (cfg.shadow === true) {
+    out.push('<defs><filter id="mm-shadow" x="-25%" y="-25%" width="150%" height="150%"><feDropShadow dx="0" dy="1.4" stdDeviation="1.8" flood-color="#0f1926" flood-opacity="0.15"/></filter></defs>')
+  }
+  if (st.bg !== 'transparent') out.push(`<rect width="${n2(W)}" height="${n2(H)}" fill="${st.bg}"/>`)
+  if (cfg.border === true) out.push(`<rect x="0.75" y="0.75" width="${n2(W - 1.5)}" height="${n2(H - 1.5)}" rx="10" fill="none" stroke="${st.theme.rule}" stroke-width="1.5"/>`)
+
+  if (hasTitle) {
+    const ty = pad * 0.9 + titleSize * 0.82
+    out.push(`<text x="${n2(W / 2)}" y="${n2(ty)}" text-anchor="middle" font-family="${esc(family)}" font-size="${n2(titleSize)}" font-weight="700" fill="${st.theme.ink}">${esc(cfg.title)}</text>`)
+    if (hasSub) {
+      out.push(`<text x="${n2(W / 2)}" y="${n2(ty + subSize * 1.55)}" text-anchor="middle" font-family="${esc(family)}" font-size="${n2(subSize)}" fill="${st.theme.muted}">${esc(cfg.subtitle)}</text>`)
+    }
+  }
+
+  out.push(`<g transform="translate(${n2(offsetX)},${n2(offsetY)})" font-family="${esc(family)}">`)
+
+  const drawEdge = (n) => {
+    for (const c of n.children) {
+      const ew = Array.isArray(cfg.edgeWidth)
+        ? Number(cfg.edgeWidth[Math.min(c.depth - 1, cfg.edgeWidth.length - 1)])
+        : (c.depth === 1 ? 3 : c.depth === 2 ? 2 : 1.35)
+      const color = c.depth === 1 ? c.style.branch : mix(c.style.branch, st.paper, c.depth === 2 ? 0.16 : 0.46)
+      out.push(`<path d="${edgePath(n, c, connector, geo.vertical)}" fill="none" stroke="${color}" stroke-width="${n2(ew)}" stroke-linecap="round" opacity="${c.depth >= 3 ? 0.85 : 1}"/>`)
+      drawEdge(c)
+    }
+  }
+  drawEdge(root)
+
+  for (const n of all) {
+    const s = n.style
+    if (s.fill !== 'none' || s.sw > 0 || s.shape === 'underline') {
+      const mark = shapeMarkup(n)
+      if (mark !== '') out.push(mark)
+    }
+    const blockH = n.lines.length * s.size * lh
+    let baseline = n.cy - blockH / 2 + s.size * (0.5 * lh + 0.34)
+    const weight = Number.isFinite(s.weight) ? s.weight : 400
+    const italic = s.italic ? ' font-style="italic"' : ''
+    const letter = s.letterSpacing !== undefined ? ` letter-spacing="${s.letterSpacing}"` : ''
+    for (const line of n.lines) {
+      out.push(`<text x="${n2(n.cx)}" y="${n2(baseline)}" text-anchor="middle" font-size="${n2(s.size)}" font-weight="${weight}"${italic}${letter} fill="${s.color}">${esc(line)}</text>`)
+      baseline += s.size * lh
+    }
+  }
+  out.push('</g>')
+
+  if (hasFoot) {
+    out.push(`<text x="${n2(W / 2)}" y="${n2(H - pad * 0.6)}" text-anchor="middle" font-family="${esc(family)}" font-size="${n2(st.fs * 0.82)}" fill="${st.theme.muted}">${esc(cfg.footnote)}</text>`)
+  }
+  out.push('</svg>')
+  return { svg: out.join('\n'), width: W, height: H }
+}
+
+// ════════════════════════════════════════════════════════════════════════════
+// 8. CLI
+// ════════════════════════════════════════════════════════════════════════════
+const HELP = `思维导图渲染器（零依赖，缩进大纲 → SVG）
+
+  node render.mjs <源文件.mmd|.txt> [选项]
+
+选项
+  --out <路径>       输出 SVG（缺省与源文件同名 .svg）
+  --theme <名>       paper | aero | ink | warm | forest | slate | contrast
+  --layout <名>      right | left | both | tree
+  --connector <名>   curve | elbow | straight | arc
+  --density <名>     compact | normal | roomy
+  --title <文本>     画布标题（覆盖前置配置）
+  --transparent      无底色（跟随阅读器主题）
+  --scale <系数>     整体字号系数（1 = 原样）
+  --json             只打印统计，不写文件
+  -h, --help         本帮助
+
+前置配置（YAML，夹在 --- 之间）见同级 SKILL.md 的「配置项总表」。`
+
+function parseArgs(argv) {
+  const opts = { file: null }
+  for (let i = 0; i < argv.length; i += 1) {
+    const a = argv[i]
+    const next = () => { i += 1; return argv[i] }
+    switch (a) {
+      case '-h': case '--help': opts.help = true; break
+      case '--out': opts.out = next(); break
+      case '--theme': opts.theme = next(); break
+      case '--layout': opts.layout = next(); break
+      case '--connector': opts.connector = next(); break
+      case '--density': opts.density = next(); break
+      case '--title': opts.title = next(); break
+      case '--scale': opts.scale = Number(next()); break
+      case '--transparent': opts.transparent = true; break
+      case '--json': opts.json = true; break
+      default:
+        if (a.startsWith('--')) throw new Error(`未知选项：${a}`)
+        if (opts.file === null) opts.file = a
+        else throw new Error(`多余参数：${a}`)
+    }
+  }
+  return opts
+}
+
+function main() {
+  let opts
+  try { opts = parseArgs(process.argv.slice(2)) } catch (e) { console.error(String(e.message ?? e)); process.exitCode = 2; return }
+  if (opts.help === true) { console.log(HELP); return }
+  if (opts.file === null) { console.error(HELP); process.exitCode = 2; return }
+
+  const abs = path.resolve(process.cwd(), opts.file)
+  const { config, body } = splitFrontMatter(readFileSync(abs, 'utf8'))
+  const cfg = { ...config }
+  for (const k of ['theme', 'layout', 'connector', 'density', 'title', 'scale']) {
+    if (opts[k] !== undefined) cfg[k] = opts[k]
+  }
+  if (opts.transparent === true) cfg.background = 'transparent'
+  if (cfg.theme !== undefined && THEMES[cfg.theme] === undefined) throw new Error(`未知 theme：${cfg.theme}（可选 ${Object.keys(THEMES).join(' / ')}）`)
+  if (cfg.layout !== undefined && !LAYOUTS.has(cfg.layout)) throw new Error(`未知 layout：${cfg.layout}（可选 ${[...LAYOUTS].join(' / ')}）`)
+  if (cfg.connector !== undefined && !CONNECTORS.has(cfg.connector)) throw new Error(`未知 connector：${cfg.connector}（可选 ${[...CONNECTORS].join(' / ')}）`)
+
+  const st = buildStyles(cfg)
+  const parsed = parseSource(body)
+  const tree = decorate(parsed.root, 0, null)
+  measure(tree, cfg, st)
+  const mode = cfg.layout ?? 'right'
+  const geo = mode === 'tree' ? layoutVertical(tree, st) : layoutHorizontal(tree, st, mode)
+  const { svg, width, height } = render(tree, cfg, st, geo)
+  const all = collect(tree)
+  const stats = {
+    nodes: all.length,
+    depth: Math.max(...all.map((n) => n.depth)) + 1,
+    width: Math.round(width),
+    height: Math.round(height),
+    theme: st.theme === THEMES[cfg.theme] ? (cfg.theme ?? 'paper') : (cfg.theme ?? 'paper'),
+    layout: mode,
+    connector: cfg.connector ?? 'curve',
+  }
+  if (opts.json === true) { console.log(JSON.stringify(stats, null, 2)); return }
+  const out = path.resolve(process.cwd(), opts.out ?? `${abs.replace(/\.[^./\\]+$/u, '')}.svg`)
+  mkdirSync(path.dirname(out), { recursive: true })
+  writeFileSync(out, svg, 'utf8')
+  console.log(`${path.basename(out)}  ${stats.width}×${stats.height}  ${stats.nodes} 节点 / ${stats.depth} 层  theme=${stats.theme} layout=${mode} connector=${stats.connector}`)
+}
+
+try {
+  main()
+} catch (error) {
+  console.error(`渲染失败：${error instanceof Error ? error.message : String(error)}`)
+  process.exitCode = 1
+}