dsh-ppt-studio 1.1.0

package/lib/pptd/layout.js

@@ -0,0 +1,209 @@
+/**
+ * 布局数学：文本度量估算 + 元素归一化（渲染器/导出器/验证器共用）。
+ * 估算档精度（v0.3 保守档，反馈 D4/E2：混合文本按偏宽估算，宁可误报不可漏报）：
+ * CJK 全角 1em / Latin 0.6em / 数字 0.6em / 空格 0.4em / 其他 0.65em，
+ * 行高 = fontSize × lineHeight；wrap 采用词级贪心切行。
+ * 渲染（浏览器）与导出（pptd）共用本度量 → verify 通过 ⇒ 导出不再缩字。
+ */
+
+const CJK_RE = /[\u1100-\u11ff\u2e80-\u303f\u3040-\u30ff\u31f0-\u31ff\u3200-\u4dbf\u4e00-\u9fff\uac00-\ud7af\uf900-\ufaff\ufe30-\ufe4f\uff00-\uffef]/
+
+export function charWidth(ch, fontSize, bold = false) {
+  const code = ch.codePointAt(0)
+  // A6 修复（反馈二）：CJK 加粗实测 ≈1.03–1.07em（微软雅黑粗体；报告案例 12.8/12=1.066）——计入 1.06
+  // 避免"估算通过但 PowerPoint 真实排版溢出"的系统差（宁可误报不可漏报，D4 原则）。
+  const boldCJK = bold ? 1.06 : 1
+  if (CJK_RE.test(ch)) return fontSize * boldCJK
+  if (code === 0x20) return fontSize * 0.4
+  if (code >= 0x30 && code <= 0x39) return fontSize * 0.6
+  if (code >= 0x41 && code <= 0x5a || code >= 0x61 && code <= 0x7a) return fontSize * (bold ? 0.63 : 0.6)
+  if (code >= 0x3000 && code <= 0x303f) return fontSize * boldCJK
+  return fontSize * (bold ? 0.69 : 0.65)
+}
+
+export function textWidth(text, style) {
+  const fs = style.fontSize ?? 18
+  let w = 0
+  for (const ch of String(text)) w += charWidth(ch, fs, !!style.bold)
+  return w
+}
+
+const NO_HEAD_START = /^[，。、！？；：）》】〕…—～]"?$/u
+const NO_LINE_END = /^[（《【〔“‘]/u
+
+/** 词级贪心换行（CJK 字符级 + 标点禁则）；返回 [lineWidths]。 */
+export function wrapLines(text, style, maxWidth) {
+  const fs = style.fontSize ?? 18
+  const lines = []
+  const paragraphs = String(text).split(/\n/)
+  for (const para of paragraphs) {
+    if (para === '') { lines.push(0); continue }
+    // 拆 token：CJK 逐字；拉丁/数字/空白 词级
+    const tokens = []
+    for (const m of para.matchAll(/[\u1100-\u11ff\u2e80-\u303f\u3040-\u30ff\u31f0-\u31ff\u3200-\u4dbf\u4e00-\u9fff\uac00-\ud7af\uf900-\ufaff\ufe30-\ufe4f\uff00-\uffef]|[^\s\u1100-\u11ff\u2e80-\u303f\u3040-\u30ff\u31f0-\u31ff\u3200-\u4dbf\u4e00-\u9fff\uac00-\ud7af\uf900-\ufaff\ufe30-\ufe4f\uff00-\uffef]+/gu)) {
+      tokens.push(m[0])
+    }
+    let cur = 0
+    let lineText = ''
+    for (const token of tokens) {
+      const ww = textWidth(token, style)
+      // 禁则：行首不落标点（挤入当前行）
+      if (cur + ww > maxWidth && cur > 0) {
+        const isNoHead = NO_HEAD_START.test(token)
+        if (isNoHead) {
+          cur += ww
+          lineText += token
+          continue
+        }
+        lines.push(cur)
+        cur = ww
+        lineText = token
+        continue
+      }
+      cur += ww
+      lineText += token
+    }
+    lines.push(cur)
+  }
+  return lines
+}
+
+/**
+ * 文本渲染估算：返回 { widthPx, heightPx, lines, overflow }。
+ * overflow = 估算高度超出容器时的放大系数（供验证器/渲染器参考）。
+ */
+export function measureText(text, style, boxW) {
+  const fs = style.fontSize ?? 18
+  const lh = fs * (style.lineHeight ?? 1.2)
+  const wrap = style.wrap !== false
+  const widthPx = textWidth(text, style)
+  if (!wrap) return { widthPx, heightPx: lh, lines: 1, lineWidths: [widthPx], overflow: widthPx > boxW ? widthPx / boxW : 1 }
+  if (boxW <= 0) return { widthPx, heightPx: lh, lines: String(text).split(/\n/).length, lineWidths: [widthPx], overflow: 1 }
+  const ws = wrapLines(text, style, boxW)
+  return {
+    widthPx,
+    heightPx: lh * ws.length,
+    lines: ws.length,
+    lineWidths: ws,
+    overflow: ws.length > 0 && lh * ws.length > 0 ? (lh * ws.length) / Math.max(fs, 1) / (fs / 1) : 1,
+  }
+}
+
+/** 元素的 text 估算摘要（渲染时用于溢出显示与文本高度回填）。 */
+export function textMetricsOf(content, style, boxW, boxH) {
+  const m = measureText(content?.text ?? '', style, boxW)
+  return {
+    textW: m.widthPx,
+    textH: m.heightPx,
+    lines: m.lines,
+    lineWidths: m.lineWidths,
+    // 溢出量：文本高超过了容器高（正数溢出 px）
+    overflowY: Math.max(0, Math.round(m.heightPx - boxH)),
+    overflowX: Math.max(0, Math.round(m.widthPx - boxW)),
+  }
+}
+
+export const TABLE_CELL_PT = 11 // 表格 cell 默认字号（pt）
+
+/** 表格 cell 的**有效**字号：默认 11pt，但不得低于用户声明的下限 theme.minFontSize。
+ *  为什么必须有这条下限（2026-09-18 修）：导出侧原本硬编码 11pt，而 audit 档的回读断言扫**全 slide XML**
+ *  取全局最小 sz 与 minFontSize 比 —— 只要工程里有表且用户下限 ≥ 12，audit 就**永远 ✗**，
+ *  而 DSL 里没有任何手段能改表格字号（"把用户逼到无法满足的门禁"）。
+ *  算在这里（一次），由 normalizePage 挂到元素上，预览与成品共用 ⇒ 三层不可能再各写一个数。 */
+export function tableCellFontPt(ctx) {
+  const floor = typeof ctx?.minFontSize === 'number' && ctx.minFontSize > 0 ? ctx.minFontSize : 0
+  return Math.max(TABLE_CELL_PT, floor)
+}
+
+export const TABLE_CELL_PAD_X = 7.2 // cell 左右内边距合计（pt；导出侧 marL/marR = 45720 EMU = 3.6pt ×2）
+export const TABLE_CELL_PAD_Y = 3.6 // cell 上下内边距合计（pt；导出侧 marT/marB = 22860 EMU = 1.8pt ×2）
+
+/** 元素包围盒：bounds 优先；line 缺省时由 points 的 AABB 推导（w/h ≥ 1px）。 */
+function boundsOf(el) {
+  if (el.bounds) {
+    return { x: el.bounds[0], y: el.bounds[1], w: el.bounds[2], h: el.bounds[3] }
+  }
+  const pts = el.points ?? [[el.x1, el.y1], [el.x2, el.y2]]
+  const xs = pts.map((p) => p[0])
+  const ys = pts.map((p) => p[1])
+  const x = Math.min(...xs)
+  const y = Math.min(...ys)
+  return { x, y, w: Math.max(1, Math.max(...xs) - x), h: Math.max(1, Math.max(...ys) - y) }
+}
+
+/** 归一化一个页面：元素 → 统一对象（含解析样式与文本度量）。 */
+export function normalizePage(page, ctx) {
+  const { resolveColor, styleOf } = ctx
+  const elements = []
+  for (const el of page.page.elements ?? []) {
+    const b = boundsOf(el)
+    const base = {
+      id: el.elementId,
+      type: el.elementType,
+      bounds: b,
+      ...(el.role ? { role: el.role } : {}),
+    }
+    switch (el.elementType) {
+      case 'text': {
+        const style = styleOf(el.content ?? {})
+        const m = textMetricsOf(el.content ?? {}, style, b.w, b.h)
+        elements.push({ ...base, type: 'text', content: el.content, style, metrics: m })
+        break
+      }
+      case 'shape': {
+        const fill = el.fill !== undefined ? resolveColor(el.fill) : undefined
+        const line = el.line ? {
+          color: resolveColor(el.line.color ?? '#000'),
+          width: el.line.width ?? 1,
+        } : undefined
+        // v0.11 候选 C：custGeom path 随归一化透传（render/export 消费）
+        elements.push({ ...base, type: 'shape', kind: el.kind ?? 'rect', fill, line, ...(el.path ? { path: el.path } : {}), rotation: el.rotation ?? 0 })
+        break
+      }
+      case 'line': {
+        const pts = el.points ? el.points.map((p) => p) : [[el.x1, el.y1], [el.x2, el.y2]]
+        const line = { color: resolveColor(el.line?.color ?? '#000'), width: el.line?.width ?? 1 }
+        elements.push({ ...base, type: 'line', points: pts, arrow: !!el.arrow, line })
+        break
+      }
+      case 'image':
+        elements.push({ ...base, type: 'image', src: el.src, fit: el.fit ?? 'cover' })
+        break
+      case 'table': {
+        // 【2026-09-18】表格内容进快照并给出**溢出估算**：此前快照只有 cols/rows 的**长度**，
+        // verify 的溢出判定只认 kind==='text' ⇒ 表格内文字溢出**既无门禁也无警告**——
+        // 而表格是 role:content 的内容元素，"内容溢出"恰恰是硬底线要管的（该严的地方没严）。
+        // 度量与正文同源（同一 wrapLines / 同一字号）⇒ "估算保守、宁可误报"这一性质对表格同样成立。
+        const fontPt = tableCellFontPt(ctx)
+        const rowsAll = [el.header !== false ? el.cols : null, ...(el.rows ?? [])].filter(Boolean)
+        const ncols = Math.max(1, ...rowsAll.map((r) => r.length))
+        const style = { fontSize: fontPt, lineHeight: 1.2 }
+        const usable = Math.max(1, b.w / ncols - TABLE_CELL_PAD_X)
+        let need = 0
+        let totalLines = 0
+        for (const r of rowsAll) {
+          let rl = 1
+          for (let ci = 0; ci < ncols; ci++) {
+            const t = String(r[ci] ?? '')
+            if (!t) continue
+            rl = Math.max(rl, wrapLines(t, style, usable).length)
+          }
+          totalLines += rl
+          need += rl * fontPt * 1.2 + TABLE_CELL_PAD_Y
+        }
+        elements.push({ ...base, type: 'table', cols: el.cols, rows: el.rows ?? [], header: el.header !== false, fontPt,
+          metrics: { overflowY: Math.round((need - b.h) * 10) / 10, lines: totalLines, textH: Math.round(need) } })
+        break
+      }
+      case 'chart': {
+        const chart = { ...el.chart }
+        if (Array.isArray(chart.colors)) chart.colors = chart.colors.map((c) => resolveColor(c))
+        elements.push({ ...base, type: 'chart', chart })
+        break
+      }
+      default:
+        elements.push(base)
+    }
+  }
+  return elements
+}

package/lib/pptd/render-html.js

@@ -0,0 +1,254 @@
+/**
+ * PPTD → HTML 预览渲染器 + layout.json（渲染器同源快照）。
+ * 产出 preview/<n>_<name>.html（单页）、preview/deck.html（整览）、preview/layout.json。
+ */
+import { writeFile, mkdir } from 'node:fs/promises'
+import { join } from 'node:path'
+import { normalizePage } from './layout.js'
+import { chartSvg, chartIssue } from './svgCharts.js'
+
+const esc = (s) => String(s).replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;').replace(/"/g, '&quot;')
+
+/**
+ * v0.9.1 常见 prst → clip-path polygon（百分比点，近似 OOXML prst 几何）。
+ */
+const SHAPE_POLY = {
+  triangle: '50% 0,0 100%,100% 100%',
+  rightArrow: '0 30%,55% 30%,55% 0,100% 50%,55% 100%,55% 70%,0 70%',
+  leftArrow: '100% 30%,45% 30%,45% 0,0 50%,45% 100%,45% 70%,100% 70%',
+  upArrow: '30% 100%,30% 45%,0 45%,50% 0,100% 45%,70% 45%,70% 100%',
+  downArrow: '30% 0,30% 55%,0 55%,50% 100%,100% 55%,70% 55%,70% 0',
+  leftRightArrow: '0 50%,25% 25%,25% 40%,75% 40%,75% 25%,100% 50%,75% 75%,75% 60%,25% 60%,25% 75%',
+  pentagon: '50% 0,100% 38%,82% 100%,18% 100%,0 38%',
+  hexagon: '25% 0,75% 0,100% 50%,75% 100%,25% 100%,0 50%',
+  chevron: '0 0,80% 0,100% 50%,80% 100%,0 100%,20% 50%',
+  parallelogram: '20% 0,100% 0,80% 100%,0 100%',
+  diamond: '50% 0,100% 50%,50% 100%,0 50%',
+  octagon: '30% 0,70% 0,100% 30%,100% 70%,70% 100%,30% 100%,0 70%,0 30%',
+  star5: '50% 0,61% 36%,98% 35%,68% 57%,79% 92%,50% 70%,21% 92%,32% 57%,2% 35%,39% 36%',
+  flowchartDecision: '50% 0,100% 50%,50% 100%,0 50%',
+  flowchartData: '20% 0,100% 0,80% 100%,0 100%',
+}
+
+/** fill：'#hex' | {color, alpha} | {type: gradient, stops(可含 alpha), angle} → CSS background/fill。 */
+function fillCss(fill) {
+  if (typeof fill === 'string') return fill
+  if (fill && typeof fill === 'object') {
+    if (fill.type === 'gradient') {
+      const stops = (fill.stops ?? []).map((s) => `${s.alpha !== undefined ? hexToRgba(s.color, s.alpha) : s.color} ${s.pos}%`).join(', ')
+      if (!stops) return '#CCCCCC'
+      const ang = fill.angle ?? 90 // OOXML 0°=左→右；CSS 0deg=下→上 → +90 归一
+      return `linear-gradient(${(ang + 90) % 360}deg, ${stops})`
+    }
+    if (fill.color && fill.alpha !== undefined) return hexToRgba(fill.color, fill.alpha)
+    if (fill.color) return fill.color
+  }
+  return '#CCCCCC'
+}
+
+/** hex + alpha(0-100) → rgba()。 */
+function hexToRgba(hex, alpha) {
+  const s = String(hex).replace('#', '').padEnd(6, '0')
+  const r = parseInt(s.slice(0, 2), 16)
+  const g = parseInt(s.slice(2, 4), 16)
+  const b = parseInt(s.slice(4, 6), 16)
+  return `rgba(${r},${g},${b},${Math.max(0, Math.min(1, Number(alpha) / 100)).toFixed(3)})`
+}
+
+/** custGeom path.commands → SVG path d（arcTo 弧转换：OOXML stAng 0=3 点钟，y 向下正角顺时针）。 */
+function svgPathD(path) {
+  const d = []
+  let cur = null
+  for (const c of path.commands ?? []) {
+    if (c.cmd === 'moveTo') { cur = c.pts[0]; d.push(`M ${cur[0]} ${cur[1]}`) }
+    else if (c.cmd === 'lnTo') { cur = c.pts[0]; d.push(`L ${cur[0]} ${cur[1]}`) }
+    else if (c.cmd === 'quadBezTo') { const [p, e] = c.pts; cur = e; d.push(`Q ${p[0]} ${p[1]} ${e[0]} ${e[1]}`) }
+    else if (c.cmd === 'cubicBezTo') { const [p1, p2, e] = c.pts; cur = e; d.push(`C ${p1[0]} ${p1[1]} ${p2[0]} ${p2[1]} ${e[0]} ${e[1]}`) }
+    else if (c.cmd === 'arcTo' && cur) {
+      const st = (Number(c.stAng) / 60000) * Math.PI / 180
+      const sw = (Number(c.swAng) / 60000) * Math.PI / 180
+      const cx = cur[0] - Number(c.wR) * Math.cos(st)
+      const cy = cur[1] - Number(c.hR) * Math.sin(st)
+      const ex = cx + Number(c.wR) * Math.cos(st + sw)
+      const ey = cy + Number(c.hR) * Math.sin(st + sw)
+      d.push(`A ${Number(c.wR)} ${Number(c.hR)} 0 ${Math.abs(sw) > Math.PI ? 1 : 0} ${sw >= 0 ? 1 : 0} ${ex.toFixed(2)} ${ey.toFixed(2)}`)
+      cur = [ex, ey]
+    }
+    else if (c.cmd === 'close') d.push('Z')
+  }
+  return d.join(' ')
+}
+
+function slug(name, index) {
+  const s = String(name).replace(/[^\w\u4e00-\u9fff-]+/g, '_').slice(0, 40) || 'page'
+  return `${String(index + 1).padStart(2, '0')}_${s}`
+}
+
+/** 单个元素的 HTML + 快照记录。 */
+function elementHtml(el, ctx, debug) {
+  const { x, y, w, h } = el.bounds
+  const pos = `position:absolute;left:${x}px;top:${y}px;width:${w}px;height:${h}px`
+  // 相对路径修正：HTML 在 <outDir>/ 下，media 在 deck 根（src 约定相对 deck 根 → 加 ../）
+  const mediaSrc = (src) => {
+    if (/^(https?:|data:|file:)/.test(src)) return src
+    return src.startsWith('./') ? '../' + src.slice(2) : '../' + src
+  }
+  const snap = (extra) => ({ id: el.id, kind: el.type, bounds: el.bounds, ...(el.role ? { role: el.role } : {}), ...extra })
+  switch (el.type) {
+    case 'text': {
+      const s = el.style
+      const style = [
+        pos,
+        `font-size:${s.fontSize}px;line-height:${s.lineHeight};color:${s.color ?? '#111'}`,
+        s.fontFamily ? `font-family:${s.fontFamily}` : '',
+        s.bold ? 'font-weight:bold' : '',
+        s.italic ? 'font-style:italic' : '',
+        s.align ? `text-align:${s.align}` : '',
+        debug ? 'outline:1px dashed rgba(220,38,38,0.5)' : '',
+        'overflow:visible;white-space:pre-wrap;word-break:break-word',
+      ].filter(Boolean).join(';')
+      return { html: `<div class="el" id="${esc(el.id)}" data-kind="text" style="${style}">${esc(el.content?.text ?? '')}</div>`, snap: snap({ style: s, metrics: el.metrics, text: el.content?.text ?? '' }) }
+    }
+    case 'shape': {
+      // v0.11 候选 C：custGeom → SVG path（任意几何；fill 支持 solid/rgba，渐变归主色近似——诚实降级）
+      if (el.kind === 'custGeom' && el.path?.commands?.length) {
+        const view = [Number(el.path.w ?? 100000), Number(el.path.h ?? 100000)]
+        const solid = typeof el.fill === 'string' ? el.fill
+          : el.fill?.type === 'gradient' ? (el.fill.stops?.[el.fill.stops.length - 1]?.color ?? '#CCCCCC')
+            : (el.fill?.color ?? '#CCCCCC')
+        const fillVal = el.fill?.alpha !== undefined || (el.fill?.type === 'gradient' && el.fill.stops?.some((s) => s.alpha !== undefined))
+          ? fillCss(el.fill) : solid
+        const stroke = el.line ? `${el.line.width}px solid ${el.line.color}` : 'none'
+        const svg = `<svg class="el" id="${esc(el.id)}" data-kind="shape" data-shape="custGeom" style="${pos};overflow:visible" viewBox="0 0 ${view[0]} ${view[1]}" preserveAspectRatio="none"><path d="${svgPathD(el.path)}" fill="${fillVal}" stroke="${el.line?.color ?? 'none'}" stroke-width="${el.line?.width ?? 0}"/></svg>`
+        return { html: svg, snap: snap({ shape: el.kind, fill: el.fill, path: el.path, rotation: el.rotation }) }
+      }
+      let css = pos
+      if (el.kind === 'ellipse') css += ';border-radius:50%'
+      else if (el.kind === 'roundRect' || el.kind === 'flowchartTerminator') css += ';border-radius:8px'
+      else if (el.kind === 'flowchartProcess') { /* rect */ }
+      else {
+        const poly = SHAPE_POLY[el.kind]
+        if (poly) css += `;clip-path:polygon(${poly})`
+      }
+      if (el.fill) css += `;background:${fillCss(el.fill)}`
+      if (el.line) css += `;border:${el.line.width}px solid ${el.line.color}`
+      if (el.rotation) css += `;transform:rotate(${el.rotation}deg)`
+      return { html: `<div class="el" id="${esc(el.id)}" data-kind="shape" data-shape="${el.kind}" style="${css}"></div>`, snap: snap({ shape: el.kind, fill: el.fill, rotation: el.rotation }) }
+    }
+    case 'line': {
+      const [p1, p2] = el.points
+      const [x1, y1] = p1
+      const [x2, y2] = p2
+      const svg = `<svg style="position:absolute;left:${x}px;top:${y}px;width:${w}px;height:${h}px;pointer-events:none" viewBox="${x} ${y} ${w} ${h}" xmlns="http://www.w3.org/2000/svg"><defs><marker id="arr" markerWidth="8" markerHeight="8" refX="7" refY="4" orient="auto"><path d="M0,0 L8,4 L0,8 z" fill="${el.line.color}"/></marker></defs><line x1="${x1}" y1="${y1}" x2="${x2}" y2="${y2}" stroke="${el.line.color}" stroke-width="${el.line.width}"${el.arrow ? ` marker-end="url(#arr)"` : ''}/></svg>`
+      return { html: svg, snap: snap({ points: el.points }) }
+    }
+    case 'image': {
+      const fit = { cover: 'cover', contain: 'contain', fill: '100% 100%' }[el.fit] ?? 'cover'
+      return { html: `<img class="el" id="${esc(el.id)}" data-kind="image" style="${pos};object-fit:${fit}" src="${esc(mediaSrc(el.src))}" />`, snap: snap({ src: el.src, fit: el.fit }) }
+    }
+    case 'table': {
+      const rows = [el.header ? el.cols : null, ...el.rows].filter(Boolean)
+      // 字号取 normalizePage 算好的 fontPt（= max(11, theme.minFontSize)）——预览与成品同一来源。
+      // 此前这里硬编码 12px、成品硬编码 11pt：同一份内容两层不一致，且都绕开了 audit 的字号下限。
+      const cellPt = Number(el.fontPt) || 11
+      const html = `<table class="el" id="${esc(el.id)}" data-kind="table" style="${pos};border-collapse:collapse"><tbody>${rows.map((r) => `<tr>${r.map((c) => `<td style="border:1px solid #cbd5e1;padding:4px 8px;font-size:${cellPt}px">${esc(c ?? '')}</td>`).join('')}</tr>`).join('')}</tbody></table>`
+      return { html, snap: snap({ cols: el.cols.length, rows: el.rows.length, fontPt: cellPt, metrics: el.metrics }) }
+    }
+    case 'chart': {
+      const svg = chartSvg(el.chart, w, h)
+      // colors 进快照（2026-09-14）：verify 的"图表显式配色 vs theme.colors"建议必须能看到它，
+      // 否则 layout.json 里只有 chartType，那条建议永远不会触发。
+      return { html: `<div class="el" id="${esc(el.id)}" data-kind="chart" style="${pos}">${svg}</div>`, snap: snap({ chartType: el.chart.type, ...(el.chart.colors ? { colors: el.chart.colors } : {}) }) }
+    }
+    default:
+      return { html: `<div class="el" id="${esc(el.id)}" data-kind="unknown" style="${pos};border:1px solid #f00">${el.type}</div>`, snap: snap({}) }
+  }
+}
+
+/** 渲染整个 deck。debug=true 时给文本元素加描边。返回 { outDir, htmlFiles, layout }。 */
+/** 页面背景解析：'#hex' | {type: solid, color} | {type: image, src, fit} → { css, record }
+ * v0.6.1（P7）：string 分支同样 resolveColor（$themeRef → 实际 hex），渲染与 layout 记录一致。 */
+function resolveBackground(bg, ctx) {
+  if (typeof bg === 'string') {
+    const c = ctx.resolveColor(bg)
+    return { css: c, record: { type: 'solid', color: c } }
+  }
+  if (bg?.type === 'solid') {
+    const c = ctx.resolveColor(bg.color ?? '#FFFFFF')
+    return { css: c, record: { type: 'solid', color: c } }
+  }
+  if (bg?.type === 'image') {
+    const src = bg.src
+    const uri = /^(https?:|data:|file:)/.test(src) ? src : '../' + (src.startsWith('./') ? src.slice(2) : src)
+    const fit = bg.fit === 'fill' ? '100% 100%' : bg.fit ?? 'cover'
+    return { css: `url("${uri}") center / ${fit} no-repeat`, record: { type: 'image', src, fit: bg.fit ?? 'cover' } }
+  }
+  return { css: '#FFFFFF', record: { type: 'solid', color: '#FFFFFF' } }
+}
+
+export async function renderDeck(ctx, { out = 'preview', debug = false } = {}) {
+  const outDir = join(ctx.dir, out)
+  await mkdir(outDir, { recursive: true })
+  const layout = {
+    size: ctx.size,
+    theme: {
+      colors: ctx.colors ?? {},
+      textStyles: ctx.textStyles ?? {},
+      grid: ctx.deck.theme?.grid ?? { base: 8 },
+      safeArea: ctx.deck.theme?.safeArea ?? null,
+      minFontSize: ctx.minFontSize,
+      themeConformance: ctx.deck.theme?.themeConformance ?? 'strict',
+    },
+    pages: [],
+  }
+  const pageFiles = []
+  const bodyHtml = []
+  const chartWarnings = [] // P1 修复：图表静默失败显式化
+  let sharedStyle = null
+  for (const page of ctx.pages) {
+    const els = normalizePage(page, ctx)
+    const bgRes = resolveBackground(page.page.background, ctx)
+    const sa = ctx.safeAreaOf(page.page)
+    const hasSa = sa.top > 0 || sa.bottom > 0 || sa.left > 0 || sa.right > 0
+    const parts = []
+    const snaps = []
+    for (const el of els) {
+      const r = elementHtml(el, ctx, debug)
+      parts.push(r.html)
+      snaps.push(r.snap)
+      if (el.type === 'chart') {
+        const issue = chartIssue(el.chart)
+        if (issue) chartWarnings.push(`第 ${page.index + 1} 页（${page.name}）${el.id}: ${issue}`)
+      }
+    }
+    // debug 模式：绘制安全区参考框（模板背景非内容区边界）
+    if (debug && hasSa) {
+      parts.push(`<div class="el sa-guide" style="position:absolute;left:${sa.left}px;top:${sa.top}px;width:${Math.max(0, ctx.size.width - sa.left - sa.right)}px;height:${Math.max(0, ctx.size.height - sa.top - sa.bottom)}px;border:2px dashed rgba(0,150,255,.75);pointer-events:none"></div>`)
+    }
+    const name = slug(page.name, page.index)
+    const html = `<!doctype html><html><head><meta charset="utf-8"><style>*{box-sizing:border-box;margin:0}body{background:#64748b} .slide{position:relative;width:${ctx.size.width}px;height:${ctx.size.height}px;background:${bgRes.css};box-shadow:0 2px 12px rgba(0,0,0,.3);overflow:hidden}</style></head><body><div class="slide">${parts.join('')}</div></body></html>`
+    await writeFile(join(outDir, `${name}.html`), html)
+    pageFiles.push(`${name}.html`)
+    if (!sharedStyle) sharedStyle = html.match(/<style>[\s\S]*?<\/style>/)?.[0] ?? ''
+    const slideOnly = html.replace(/<!doctype html>[\s\S]*?<head><meta charset="utf-8">/, '').replace(/<style>[\s\S]*?<\/style>/, '').replace(/<\/head>[\s\S]*?<body>/, '').replace(/<\/body><\/html>$/, '')
+      .replace('<div class="slide">', `<div class="slide" style='background:${bgRes.css.replace(/'/g, '\\\'')}'>`)
+    bodyHtml.push(`<section style="margin:0 auto 24px;width:${ctx.size.width}px;padding:4px 0"><div style="font:12px monospace;color:#e2e8f0;padding:2px 8px">${page.index + 1}. ${esc(page.name)}</div>${slideOnly}</section>`)
+    layout.pages.push({
+      index: page.index, // 内部数组下标（0 基）
+      pageNo: page.index + 1, // **跨档配对键**：1 基人类页号；measured.json 写同名字段（见 measurement.js）
+      file: page.ref,
+      name: page.name,
+      background: bgRes.record,
+      safeArea: sa,
+      expectedOverlaps: page.page.expectedOverlaps ?? [],
+      expectedOutOfSafeArea: page.page.expectedOutOfSafeArea ?? [],
+      contrastExempt: page.page.contrastExempt ?? [],
+      overlapMode: page.page.overlapMode ?? 'declared',
+      elements: snaps,
+    })
+  }
+  const deckHtml = `<!doctype html><html><head><meta charset="utf-8"><title>${esc(ctx.deck.title ?? 'deck')}</title>${sharedStyle}<style>body{background:#334155;padding:16px}</style></head><body style="background:#334155">${bodyHtml.join('')}</body></html>`
+  await writeFile(join(outDir, 'deck.html'), deckHtml)
+  await writeFile(join(outDir, 'layout.json'), JSON.stringify(layout, null, 2))
+  return { outDir, htmlFiles: pageFiles, layout, chartWarnings }
+}