@capyclaw/ppt-workbench 0.0.0-stage → 2.4.0

package/core/chart.js

@@ -0,0 +1,199 @@
+/**
+ * 图表元素纯函数：数据归一化 + 元素构建（零 DOM，node:test 直测）。
+ *
+ * PPTist chart 元素结构（编辑器原生渲染，echarts 已内置于 bundle）：
+ *   { type:'chart', chartType:'bar'|'column'|'line'|'area'|'pie'|'ring'|'radar'|'scatter',
+ *     data:{ labels, legends, series }, options?{ lineSmooth, stack }, themeColors?, textColor? }
+ *
+ * normalizeChartData 支持多种「丢数据」格式，统一归一为 PPTist 原生结构：
+ *   1. { labels, legends, series }            原生格式直通
+ *   2. { labels, values }                     单系列
+ *   3. { headers, rows }                      表格数据：首列=类目，其余列=系列
+ *   4. { items: [[name, value]...] | [{name,value}...] }  饼图/环形图
+ *   5. { series: [{name, values}...] }        series 对象式（labels 可省，自动生成）
+ */
+
+export const CHART_TYPES = ['bar', 'column', 'line', 'area', 'pie', 'ring', 'radar', 'scatter']
+
+/** 单系列图：饼/环只取第一个系列，多余系列报错。 */
+export const SINGLE_SERIES_TYPES = ['pie', 'ring']
+
+/** 图表缺省调色板（与编辑器模板主题色 #5b9bd5 同族）。 */
+export const DEFAULT_CHART_COLORS = [
+  '#5b9bd5', '#ed7d31', '#a5a5a5', '#ffc000', '#4472c4',
+  '#70ad47', '#264478', '#9e480e', '#636363', '#997300',
+]
+
+const isNum = (v) => typeof v === 'number' && isFinite(v)
+const isNumArr = (a) => Array.isArray(a) && a.length > 0 && a.every(isNum)
+
+function fail(msg) {
+  throw new Error('图表数据格式错误：' + msg)
+}
+
+/** 归一化 series：数字数组或 {name, values} 对象数组 → [number[]] + legends。 */
+function normalizeSeriesInput(series) {
+  if (!Array.isArray(series) || series.length === 0) fail('series 不能为空')
+  const legends = []
+  const out = []
+  for (const s of series) {
+    if (isNumArr(s)) {
+      out.push(s.slice())
+      legends.push(`系列${out.length}`)
+      continue
+    }
+    if (s && isNumArr(s.values)) {
+      out.push(s.values.slice())
+      legends.push(String(s.name != null && s.name !== '' ? s.name : `系列${out.length + 1}`))
+      continue
+    }
+    fail('series 每项必须是数字数组或 {name, values}')
+  }
+  return { legends, series: out }
+}
+
+/** 生成类目名：类别1..n。 */
+const autoLabels = (n) => Array.from({ length: n }, (_, i) => `类别${i + 1}`)
+
+/**
+ * 归一化图表数据 → { labels, legends, series }。
+ * @param {object} raw 上述 5 种格式之一
+ * @param {string} chartType 用于 pie/ring 的单系列裁剪
+ */
+export function normalizeChartData(raw, chartType = 'bar') {
+  if (!raw || typeof raw !== 'object') fail('data 必须是对象')
+
+  let labels = []
+  let legends = []
+  let series = []
+
+  if (Array.isArray(raw.series)) {
+    // 格式 1 / 5：series 数组（数字数组或 {name, values}）
+    const norm = normalizeSeriesInput(raw.series)
+    legends = raw.legends && Array.isArray(raw.legends) && raw.legends.length
+      ? norm.series.map((_, i) => String(raw.legends[i] != null ? raw.legends[i] : norm.legends[i]))
+      : norm.legends
+    series = norm.series
+    labels = Array.isArray(raw.labels) && raw.labels.length
+      ? raw.labels.map(String)
+      : autoLabels(series[0].length)
+  }
+  else if (Array.isArray(raw.values)) {
+    // 格式 2：{ labels?, values } 单系列
+    if (!isNumArr(raw.values)) fail('values 必须是非空数字数组')
+    series = [raw.values.slice()]
+    legends = [String(raw.name || '值')]
+    labels = Array.isArray(raw.labels) && raw.labels.length
+      ? raw.labels.map(String)
+      : autoLabels(series[0].length)
+  }
+  else if (Array.isArray(raw.rows) || Array.isArray(raw.headers)) {
+    // 格式 3：{ headers?, rows } 表格数据：首列=类目
+    if (!Array.isArray(raw.rows) || raw.rows.length === 0) fail('rows 不能为空')
+    const width = raw.rows[0].length
+    if (width < 2) fail('rows 每行至少 2 列（首列类目 + 至少 1 列数值）')
+    const heads = Array.isArray(raw.headers) && raw.headers.length
+      ? raw.headers.map(String)
+      : null
+    labels = []
+    const cols = Array.from({ length: width - 1 }, () => [])
+    for (const row of raw.rows) {
+      if (!Array.isArray(row) || row.length !== width) fail(`rows 每行长度必须一致（${width}）`)
+      labels.push(String(row[0]))
+      for (let c = 1; c < width; c++) {
+        const v = Number(row[c])
+        if (!isFinite(v)) fail(`第 ${labels.length} 行第 ${c + 1} 列不是数字：${JSON.stringify(row[c])}`)
+        cols[c - 1].push(v)
+      }
+    }
+    legends = cols.map((_, i) => (heads && heads[i + 1]) || `系列${i + 1}`)
+    series = cols
+  }
+  else if (Array.isArray(raw.items)) {
+    // 格式 4：{ items: [[name, value]] | [{name, value}] } 饼图式
+    labels = []
+    const values = []
+    for (const it of raw.items) {
+      const [name, value] = Array.isArray(it) ? it : [it && it.name, it && it.value]
+      if (name == null || !isFinite(Number(value))) fail('items 每项必须是 [name, value] 或 {name, value}')
+      labels.push(String(name))
+      values.push(Number(value))
+    }
+    series = [values]
+    legends = [String(raw.name || '值')]
+  }
+  else {
+    fail('无法识别的 data 格式（支持 labels+series / labels+values / headers+rows / items）')
+  }
+
+  if (labels.length === 0) fail('labels 不能为空')
+  for (const s of series) {
+    if (s.length !== labels.length) {
+      fail(`系列长度(${s.length})与类目数(${labels.length})不一致`)
+    }
+  }
+
+  if (SINGLE_SERIES_TYPES.includes(chartType) && series.length > 1) {
+    fail(`${chartType} 图只支持 1 个系列（收到 ${series.length} 个），请改用 bar/line 等`)
+  }
+
+  return { labels, legends, series }
+}
+
+/** 图表 options 白名单：只透传编辑器认识的字段。 */
+const CHART_OPTION_KEYS = ['lineSmooth', 'stack', 'horizontalBars']
+
+export function normalizeChartOptions(options) {
+  if (options == null) return undefined
+  if (typeof options !== 'object') fail('options 必须是对象')
+  const out = {}
+  for (const k of CHART_OPTION_KEYS) {
+    if (options[k] != null) out[k] = Boolean(options[k])
+  }
+  return Object.keys(out).length ? out : undefined
+}
+
+/** 画布 1000 × 562.5；图表缺省居中偏上。 */
+function geometry(e) {
+  const width = Number(e.width != null ? e.width : 560)
+  const height = Number(e.height != null ? e.height : 360)
+  return {
+    width,
+    height,
+    left: Number(e.left != null ? e.left : Math.round((1000 - width) / 2)),
+    top: Number(e.top != null ? e.top : 110),
+    rotate: Number(e.rotate || 0),
+  }
+}
+
+/**
+ * 构建图表元素。
+ * @param {object} e {chartType, data, options?, colors?|themeColors?, left/top/width/height?, textColor?}
+ * @param {string[]} [deckThemeColors] 幻灯片主题色（可选兜底）
+ */
+export function makeChartElement(e, deckThemeColors) {
+  if (!e || typeof e !== 'object') fail('图表元素必须是对象')
+  const chartType = String(e.chartType || (e.type && e.type !== 'chart' ? e.type : 'bar'))
+  if (!CHART_TYPES.includes(chartType)) {
+    fail(`不支持的 chartType: ${chartType}（支持 ${CHART_TYPES.join(' / ')}）`)
+  }
+  const data = normalizeChartData(e.data, chartType)
+  const colors = Array.isArray(e.colors) && e.colors.length
+    ? e.colors.map(String)
+    : (Array.isArray(e.themeColors) && e.themeColors.length
+        ? e.themeColors.map(String)
+        : (Array.isArray(deckThemeColors) && deckThemeColors.length ? deckThemeColors : DEFAULT_CHART_COLORS))
+  const g = geometry(e)
+  const el = {
+    type: 'chart',
+    id: e.id || `chart_${Date.now()}_${Math.floor(Math.random() * 1000)}`,
+    ...g,
+    chartType,
+    data,
+    themeColors: colors,
+    textColor: String(e.textColor || '#333333'),
+  }
+  const options = normalizeChartOptions(e.options)
+  if (options) el.options = options
+  return el
+}

package/core/color.js

@@ -0,0 +1,80 @@
+/**
+ * 颜色域：中文色名、颜色解析、亮度与对比色。
+ *
+ * 这是整个仓库唯一的颜色实现；core/text、core/quick、core/audit 与
+ * MCP 的 domains/color 都从这里取，避免多份色表/亮度公式漂移。
+ */
+
+export const COLORS = {
+  蓝: '#5b9bd5', 蓝色: '#5b9bd5', 天蓝: '#87ceeb', 淡蓝: '#add8e6', 浅蓝: '#b3e5fc', 深蓝: '#1e3a8a',
+  白: '#ffffff', 白色: '#ffffff', 黑: '#000000', 黑色: '#000000',
+  灰: '#cccccc', 灰色: '#cccccc', 深灰: '#333333', 浅灰: '#f2f2f2',
+  黄: '#ffe066', 淡黄: '#fffacd', 浅黄: '#fffacd', 米色: '#f5f5dc',
+  红: '#d14424', 红色: '#d14424', 绿: '#2e7d32', 绿色: '#2e7d32',
+  紫: '#7e57c2', 紫色: '#7e57c2', 橙: '#f0a030', 橙色: '#f0a030',
+  粉: '#ffc0cb', 粉色: '#ffc0cb', 青: '#20b2aa', 青色: '#20b2aa',
+  棕: '#8d6e63', 棕色: '#8d6e63',
+}
+
+/** 中文色名 / CSS 颜色 → hex；最长匹配，同长度取更早出现。 */
+export function resolveColor(v) {
+  const s = String(v || '').trim()
+  if (COLORS[s]) return COLORS[s]
+  let best = null
+  for (const k of Object.keys(COLORS)) {
+    const idx = s.indexOf(k)
+    if (idx < 0) continue
+    if (!best || k.length > best.k.length || (k.length === best.k.length && idx < best.idx)) {
+      best = { k, idx }
+    }
+  }
+  return best ? COLORS[best.k] : s
+}
+
+/** #rgb / #rrggbb / rgb() / rgba() → [r,g,b]；非法返回 null。 */
+export function parseColor(v) {
+  const s = String(v || '').trim()
+  let m = /^#([0-9a-f]{3}|[0-9a-f]{6})$/i.exec(s)
+  if (m) {
+    const h = m[1].length === 3 ? m[1].split('').map(c => c + c).join('') : m[1]
+    return [parseInt(h.slice(0, 2), 16), parseInt(h.slice(2, 4), 16), parseInt(h.slice(4, 6), 16)]
+  }
+  m = /^rgba?\(\s*(\d+)\s*,\s*(\d+)\s*,\s*(\d+)/i.exec(s)
+  if (m) return [+m[1], +m[2], +m[3]]
+  return null
+}
+
+/** 0-255 加权亮度（WCAG 系数）。 */
+export function luminance(rgb) {
+  return 0.2126 * rgb[0] + 0.7152 * rgb[1] + 0.0722 * rgb[2]
+}
+
+/** WCAG 相对亮度（sRGB → 线性）。 */
+function relativeChannel(c) {
+  const s = c / 255
+  return s <= 0.04045 ? s / 12.92 : ((s + 0.055) / 1.055) ** 2.4
+}
+
+export function relativeLuminanceRgb(rgb) {
+  return 0.2126 * relativeChannel(rgb[0]) + 0.7152 * relativeChannel(rgb[1]) + 0.0722 * relativeChannel(rgb[2])
+}
+
+/** 两色 WCAG 对比度（1–21，审计用）。 */
+export function contrastRatio(a, b) {
+  const l1 = relativeLuminanceRgb(a)
+  const l2 = relativeLuminanceRgb(b)
+  const hi = Math.max(l1, l2)
+  const lo = Math.min(l1, l2)
+  return (hi + 0.05) / (lo + 0.05)
+}
+
+/** 背景相对亮度（0-1）；无法解析时按白色处理。 */
+export function relativeLuminance(bg) {
+  const rgb = parseColor(bg)
+  return rgb ? luminance(rgb) / 255 : 1
+}
+
+/** 浅底深字 / 深底白字。 */
+export function contrastColor(bg) {
+  return relativeLuminance(bg) > 0.62 ? '#1f2d3d' : '#ffffff'
+}

package/core/deck-layout.js

@@ -0,0 +1,195 @@
+/** 排版引擎（7 版式 × 4 预设）：大纲 → 专业排版 slides（纯 deck 域）。 */
+/* ===================== 设计系统与排版引擎（2026-10-21） =====================
+ * 目标：一次 ppt_deck 调用产出「结构完整、版式统一、对比度正确」的 deck。
+ * 约束内置：60px 网格边距、标题/正文/注释三级字号、要点数自适应、
+ * 强调色只用于标题装饰与关键数字。 */
+export const PRESETS = {
+  clean:    { bg:'#ffffff', fg:'#1f2d3d', muted:'#5b6472', card:'#f3f4f6', accent:'#2563eb', accent2:'#c2410c' },
+  business: { bg:'#0f2740', fg:'#ffffff', muted:'#b8c4d0', card:'#16324f', accent:'#e0a33a', accent2:'#5aa9e6' },
+  /* warm：muted/accent 经对比度求解固化（2026-11-01 进化轮发现原值对 bg/card
+   * 只有 3.86-4.00:1，低于 WCAG 4.5:1，导致 compose 产出被自家 ppt_audit 打 block）。 */
+  warm:     { bg:'#fbf7f0', fg:'#3b2f2a', muted:'#67594f', card:'#f2e9dd', accent:'#a6431f', accent2:'#2e7d32' },
+  tech:     { bg:'#0b1020', fg:'#e8efff', muted:'#93a4c4', card:'#141b31', accent:'#22d3ee', accent2:'#a78bfa' },
+}
+const GRID = { W: 1000, H: 562.5, pad: 60, titleTop: 46, bodyTop: 150 }
+const tidy = (s, max) => {
+  const t = String(s == null ? '' : s).replace(/\s+/g, ' ').trim()
+  return t.length > max ? t.slice(0, max - 1) + '…' : t
+}
+const textEl = (id, x, y, w, h, html, opts = {}) => ({
+  type: 'text', id, left: x, top: y, width: w, height: h,
+  content: `<p style="font-size: ${opts.size || 20}px;${opts.color ? ' color:' + opts.color + ';' : ''}${opts.align ? ' text-align:' + opts.align + ';' : ''}">${opts.bold ? '<strong>' + html + '</strong>' : html}</p>`,
+  defaultColor: opts.color || '#333333', defaultFontName: '', fixedRatio: false, rotate: 0,
+})
+const shapeEl = (id, x, y, w, h, fill, rotate = 0) => ({
+  type: 'shape', id, left: x, top: y, width: w, height: h,
+  path: 'M 0 0 L 200 0 L 200 200 L 0 200 Z', viewBox: [200, 200],
+  fill, fixedRatio: false, rotate,
+})
+const bgOf = (P) => ({ type: 'solid', color: P.bg })
+
+function layoutCover(P, s, i) {
+  const W = GRID.W, pad = GRID.pad
+  return {
+    id: `lt_cover_${i}`, background: bgOf(P), elements: [
+      shapeEl(`lt_cover_bar_${i}`, 0, 0, W, 14, P.accent),
+      textEl(`lt_cover_kicker_${i}`, pad, 120, W - pad * 2, 30,
+        escapeHtml(tidy(s.kicker || '', 40)), { size: 16, color: P.accent, bold: true }),
+      textEl(`lt_cover_title_${i}`, pad, 160, W - pad * 2, 120,
+        escapeHtml(tidy(s.title || '', 30)), { size: 50, color: P.fg, bold: true }),
+      textEl(`lt_cover_sub_${i}`, pad, 300, W - pad * 2, 70,
+        escapeHtml(tidy(s.subtitle || '', 60)), { size: 21, color: P.muted }),
+      shapeEl(`lt_cover_line_${i}`, pad, 400, 120, 4, P.accent),
+      textEl(`lt_cover_foot_${i}`, pad, 470, W - pad * 2, 30,
+        escapeHtml(tidy(s.foot || '', 50)), { size: 13, color: P.muted }),
+    ],
+  }
+}
+
+function layoutSection(P, s, i) {
+  const W = GRID.W, pad = GRID.pad
+  const n = String(s.index != null ? s.index : '').padStart(2, '0')
+  return {
+    id: `lt_section_${i}`, background: bgOf(P), elements: [
+      textEl(`lt_sec_num_${i}`, pad, 120, 160, 120, escapeHtml(n || '—'),
+        { size: 72, color: P.accent, bold: true }),
+      textEl(`lt_sec_title_${i}`, pad, 250, W - pad * 2, 90,
+        escapeHtml(tidy(s.title || '', 30)), { size: 40, color: P.fg, bold: true }),
+      shapeEl(`lt_sec_line_${i}`, pad, 350, 100, 4, P.accent),
+      textEl(`lt_sec_sub_${i}`, pad, 380, W - pad * 2, 60,
+        escapeHtml(tidy(s.subtitle || '', 70)), { size: 18, color: P.muted }),
+    ],
+  }
+}
+
+function layoutBullets(P, s, i) {
+  const W = GRID.W, pad = GRID.pad
+  const items = (s.bullets || []).slice(0, 6).map(b =>
+    typeof b === 'string' ? { text: b } : b)
+  const size = items.length <= 3 ? 22 : items.length === 4 ? 20 : 18
+  const els = [
+    textEl(`lt_b_title_${i}`, pad, GRID.titleTop, W - pad * 2, 70,
+      escapeHtml(tidy(s.title || '', 28)), { size: 32, color: P.fg, bold: true }),
+    shapeEl(`lt_b_line_${i}`, pad, 128, 90, 4, P.accent),
+  ]
+  items.forEach((b, k) => {
+    const y = GRID.bodyTop + 8 + k * (b.detail ? 74 : 62)
+    els.push(shapeEl(`lt_b_dot_${i}_${k}`, pad + 2, y + 9, 8, 8, P.accent))
+    /* 单行框（34px）按 22px 字号最多容纳 ~36 个 CJK 字符：上限从 40 收紧到 36，
+     * 否则满长度纯中文要点会折行溢出，被 ppt_audit 判 text-overflow（2026-11-01）。 */
+    els.push(textEl(`lt_b_txt_${i}_${k}`, pad + 26, y, W - pad * 2 - 26, 34,
+      escapeHtml(tidy(b.text || '', 36)), { size, color: P.fg }))
+    if (b.detail) {
+      els.push(textEl(`lt_b_det_${i}_${k}`, pad + 26, y + 32, W - pad * 2 - 26, 28,
+        escapeHtml(tidy(b.detail, 60)), { size: 14, color: P.muted }))
+    }
+  })
+  return { id: `lt_bullets_${i}`, background: bgOf(P), elements: els }
+}
+
+function layoutTwo(P, s, i) {
+  const W = GRID.W, pad = GRID.pad
+  const cw = (W - pad * 2 - 24) / 2
+  const col = (side, data, x) => {
+    const els = [
+      shapeEl(`lt_two_card_${i}_${side}`, x, 150, cw, 330, P.card),
+      textEl(`lt_two_h_${i}_${side}`, x + 24, 172, cw - 48, 40,
+        escapeHtml(tidy((data && data.heading) || '', 20)), { size: 22, color: P.accent, bold: true }),
+    ]
+    ;((data && data.bullets) || []).slice(0, 4).forEach((b, k) => {
+      els.push(textEl(`lt_two_b_${i}_${side}_${k}`, x + 24, 226 + k * 56, cw - 48, 48,
+        escapeHtml(tidy(b, 30)), { size: 17, color: P.fg }))
+    })
+    return els
+  }
+  return {
+    id: `lt_two_${i}`, background: bgOf(P), elements: [
+      textEl(`lt_two_title_${i}`, pad, GRID.titleTop, W - pad * 2, 70,
+        escapeHtml(tidy(s.title || '', 26)), { size: 30, color: P.fg, bold: true }),
+      ...col('l', s.left, pad),
+      ...col('r', s.right, pad + cw + 24),
+    ],
+  }
+}
+
+function layoutStat(P, s, i) {
+  const W = GRID.W, pad = GRID.pad
+  const stats = (s.stats || []).slice(0, 3)
+  const n = Math.max(1, stats.length)
+  const cw = (W - pad * 2 - (n - 1) * 24) / n
+  const els = [
+    textEl(`lt_st_title_${i}`, pad, GRID.titleTop, W - pad * 2, 70,
+      escapeHtml(tidy(s.title || '', 26)), { size: 30, color: P.fg, bold: true }),
+  ]
+  stats.forEach((st, k) => {
+    const x = pad + k * (cw + 24)
+    els.push(shapeEl(`lt_st_card_${i}_${k}`, x, 150, cw, 260, P.card))
+    els.push(textEl(`lt_st_val_${i}_${k}`, x, 190, cw, 110,
+      escapeHtml(tidy(st.value || '', 10)), { size: 60, color: P.accent, bold: true, align: 'center' }))
+    els.push(textEl(`lt_st_lab_${i}_${k}`, x, 310, cw, 60,
+      escapeHtml(tidy(st.label || '', 20)), { size: 16, color: P.muted, align: 'center' }))
+  })
+  if (s.note) {
+    els.push(textEl(`lt_st_note_${i}`, pad, 450, W - pad * 2, 40,
+      escapeHtml(tidy(s.note, 80)), { size: 14, color: P.muted }))
+  }
+  return { id: `lt_stat_${i}`, background: bgOf(P), elements: els }
+}
+
+function layoutQuote(P, s, i) {
+  const W = GRID.W, pad = GRID.pad
+  return {
+    id: `lt_quote_${i}`, background: bgOf(P), elements: [
+      shapeEl(`lt_q_bar_${i}`, pad, 150, 6, 200, P.accent),
+      textEl(`lt_q_txt_${i}`, pad + 30, 150, W - pad * 2 - 30, 200,
+        escapeHtml(tidy(s.quote || '', 120)), { size: 28, color: P.fg }),
+      textEl(`lt_q_author_${i}`, pad + 30, 380, W - pad * 2 - 30, 40,
+        escapeHtml(tidy(s.author || '', 30)), { size: 16, color: P.muted }),
+    ],
+  }
+}
+
+function layoutEnd(P, s, i) {
+  const W = GRID.W
+  const pad = GRID.pad
+  return {
+    id: `lt_end_${i}`, background: bgOf(P), elements: [
+      shapeEl(`lt_end_bar_${i}`, 0, GRID.H - 14, W, 14, P.accent),
+      textEl(`lt_end_title_${i}`, pad, 200, W - pad * 2, 90,
+        escapeHtml(tidy(s.title || '谢谢观看', 20)), { size: 44, color: P.fg, bold: true, align: 'center' }),
+      textEl(`lt_end_sub_${i}`, pad, 300, W - pad * 2, 60,
+        escapeHtml(tidy(s.subtitle || '', 60)), { size: 18, color: P.muted, align: 'center' }),
+    ],
+  }
+}
+
+export function buildDeck(input) {
+  const presetName = PRESETS[input.preset] ? input.preset : 'clean'
+  const P = PRESETS[presetName]
+  const slides = (input.slides || []).slice(0, 30).map((s, i) => buildSlide(P, s, i))
+  if (!slides.length) throw new Error('slides 不能为空')
+  return {
+    title: tidy(input.title || '未命名演示', 40),
+    slides,
+    theme: { themeColors: [P.accent, P.accent2, P.fg], fontColor: P.fg, backgroundColor: P.bg },
+  }
+}
+
+/** 构建单页 slide（ppt_page 用），跳过 deck 级 theme/title 构建。 */
+export function buildSlide(P, spec, index) {
+  const presetName = typeof P === 'string' ? (PRESETS[P] ? P : 'clean') : null
+  const preset = presetName ? PRESETS[presetName] : P
+  switch (spec.layout) {
+    case 'cover': return layoutCover(preset, spec, index)
+    case 'section': return layoutSection(preset, spec, index)
+    case 'two': return layoutTwo(preset, spec, index)
+    case 'stat': return layoutStat(preset, spec, index)
+    case 'quote': return layoutQuote(preset, spec, index)
+    case 'end': return layoutEnd(preset, spec, index)
+    default: return layoutBullets(preset, spec, index)
+  }
+}
+
+export function escapeHtml(s) {
+  return String(s).replace(/[&<>"']/g, c => ({ '&': '&amp;', '<': '&lt;', '>': '&gt;', '"': '&quot;', "'": '&#39;' }[c]))
+}

package/core/formula.js

@@ -0,0 +1,80 @@
+/**
+ * 公式（latex 元素）纯函数：hfmath 渲染 + 元素组装。
+ *
+ * PPTist latex 元素（编辑器以 stroke 渲染，非填充）：
+ *   { type:'latex', latex, path, color, strokeWidth, viewBox:[w,h], fixedRatio:true }
+ * path 坐标空间 = viewBox（hfmath 输出的单线笔画，空格分隔多子路径）。
+ *
+ * 渲染引擎 hfmath 是 PPTist 的 fork（零依赖 Hershey 单线字体），
+ * 源码转译在 core/hfmath/*.js，node:test 直测。
+ */
+
+import { hfmath } from './hfmath/index.js'
+
+/** hfmath 默认渲染 padding（path 坐标与 viewBox 同坐标系）。 */
+const HF_PADDING = 16
+
+/**
+ * 渲染 TeX 公式 → stroke path。
+ * @param {string} latex TeX 语法的数学公式（如 E=mc^2、\frac{a}{b}、x_i^2）
+ * @returns {{ path: string, viewBox: [number, number], width: number, height: number }}
+ */
+export function renderFormula(latex) {
+  const src = String(latex == null ? '' : latex).trim()
+  if (!src) throw new Error('公式内容不能为空')
+  let f
+  try {
+    f = new hfmath(src)
+    f.pathd()
+  } catch (err) {
+    throw new Error('公式解析失败：' + String((err && err.message) || err) + '（请检查 TeX 语法）')
+  }
+  const d = f.pathd()
+  if (!d || !d.trim()) throw new Error('公式渲染结果为空：请检查公式内容')
+  const box = f.box()
+  const vw = Math.ceil(box.x + box.w + HF_PADDING)
+  const vh = Math.ceil(box.y + box.h + HF_PADDING)
+  if (!isFinite(vw) || !isFinite(vh) || vw <= 0 || vh <= 0) {
+    throw new Error('公式渲染尺寸异常：' + JSON.stringify(box))
+  }
+  return { path: d, viewBox: [vw, vh], width: vw, height: vh }
+}
+
+/**
+ * 构建 latex 元素（path 必须已渲染——没有 path 的公式在编辑器里不可见）。
+ * @param {object} e { latex, path?, viewBox?, color?, strokeWidth?, width?, height?, left?, top?, rotate? }
+ */
+export function makeFormulaElement(e) {
+  if (!e || typeof e !== 'object') throw new Error('公式元素必须是对象')
+  const latex = String(e.latex == null ? '' : e.latex).trim()
+  if (!latex) throw new Error('公式内容 latex 不能为空')
+  let path = e.path
+  let viewBox = e.viewBox
+  if (!path) {
+    const rendered = renderFormula(latex)
+    path = rendered.path
+    viewBox = rendered.viewBox
+  }
+  const vw = Number(viewBox && viewBox[0] != null ? viewBox[0] : 200)
+  const vh = Number(viewBox && viewBox[1] != null ? viewBox[1] : 200)
+  if (!isFinite(vw) || !isFinite(vh) || vw <= 0 || vh <= 0) {
+    throw new Error('viewBox 无效：应为 [宽, 高] 正数')
+  }
+  const width = Number(e.width != null ? e.width : vw)
+  const height = Number(e.height != null ? e.height : vh)
+  return {
+    type: 'latex',
+    id: e.id || `formula_${Date.now()}_${Math.floor(Math.random() * 1000)}`,
+    left: Number(e.left != null ? e.left : Math.round((1000 - width) / 2)),
+    top: Number(e.top != null ? e.top : 140),
+    width,
+    height,
+    rotate: Number(e.rotate || 0),
+    fixedRatio: true,
+    latex,
+    path: String(path),
+    color: e.color ? String(e.color) : '#333333',
+    strokeWidth: Number(e.strokeWidth != null ? e.strokeWidth : 2),
+    viewBox: [vw, vh],
+  }
+}