minimal-agent 0.8.2 → 0.10.0

package/skills/ui-design/scripts/export_pptx_from_html.mjs

@@ -0,0 +1,2367 @@
+#!/usr/bin/env node
+/**
+ * Export ui-design HTML artifacts to PPTX —— 三层模型（背景 / 前景 / 文本）。
+ *
+ * 用 Playwright 做视觉捕获、PptxGenJS 生成 PPTX。**用 Node 跑，不要 Bun。**
+ *
+ * 三层（hybrid 模式）：
+ *   1) 背景：页面底板/渐变/氛围底图（B 路线 background-image + scrim）—— 整页截图，垫 slide 最底层。
+ *   2) 前景：除背景与文本外的**所有**离散视觉块（img/svg/canvas/图表/卡片/色块/图标），标
+ *      `data-pptx-layer="foreground"`。**取最外层**（去嵌套）逐个元素截图 → PPT 独立可编辑图片对象（中层）。
+ *   3) 文本：**自动提取全部可见文本到顶层可编辑框，不依赖逐个标注**（tagAutoText 在任何截图前，
+ *      按结构识别「块级且子元素全为行内的文本容器」+ 全部 SVG `<text>`，打 `data-pptx-auto-text`）。
+ *      背景截图 / 前景切图两态都隐藏 `[data-pptx-auto-text]` → 切图**永不含字**、文字**永远可编辑且在顶层**。
+ *      旧的 `data-pptx-kind="text"` / `data-pptx-layer="text"` 标注仍兼容（结构识别已覆盖，标了也不冲突）；
+ *      要让某段文字**保留烧进图**（如嵌在图形里的艺术字）用 `data-pptx-export="ignore"` 显式排除。
+ * 导出时额外落 3 个 HTML 中间产物（pure-background/foreground/text.html）供检视。
+ * flat 模式：整页一张大图，不可编辑（最保真）。
+ *
+ * 已知边界（如实声明，刻意不改——改了弊大于利）：
+ *   - 切图按元素 **border-box** 取（page.screenshot + clip），几何同源 getBoundingClientRect → 摆放精确。
+ *     代价：**超出 border-box 的 box-shadow / 溢出子内容会被裁掉**。不扩边是有意的——扩了切图就比
+ *     记录的几何大，摆进 PPT 必然错位/糊边；宁可丢一点投影，也要保「切图尺寸 == 摆放尺寸」。
+ *     需要保留投影感就在 HTML 里把阴影做进 border-box 内（inset shadow / 给容器留 padding）。
+ *   - 背景层 = 隐掉所有前景块(auto-fg/foreground) + 文本后剩下的：**全幅基底**（AI 底图 / 纯色 / 渐变 /
+ *     scrim / 透明）。**半幅渐变带**（非全幅、有盒样式）会被当离散块切入中层；**极小装饰**
+ *     （最小边 <24px 或面积 <2500px²）留在背景层烧进底图（不单独切，可接受）。
+ */
+
+import { spawnSync } from 'node:child_process';
+import { createHash } from 'node:crypto';
+import { copyFile, mkdir, readFile, unlink, writeFile } from 'node:fs/promises';
+import { dirname, resolve, basename, extname } from 'node:path';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+import { createRequire } from 'node:module';
+
+const SLIDE_W = 10;
+const SLIDE_H = 5.625;
+
+function usage() {
+  return `导出 ui-design HTML 为 PPTX（三层：背景/前景/文本）
+
+Usage:
+  node scripts/export_pptx_from_html.mjs <html_file> --out <output.pptx> [options]
+
+Options:
+  --mode <flat|hybrid|native>   导出模式，默认 flat
+                                flat   = 整页大图，不可编辑（最保真）
+                                hybrid = 三层：背景底图 + 前景逐元素切图 + 文本原生框（可编辑）
+  --slides <selector>           slide 选择器，默认 [data-screen-label]
+  --width <px>                  浏览器视口宽度，默认 1920
+  --height <px>                 浏览器视口高度，默认 1080
+  --workdir <dir>               截图、切图、3 个 HTML 中间产物、manifest、报告输出目录
+  --node-modules <dir>          额外 Node 包目录，用于 Codex 内置运行时或本地依赖
+  --python <cmd>                Python 命令，默认 python3
+  --no-opc-check                跳过 OPC 校验，不推荐
+  --measure-only                只渲染量构图（写 layout-report.json），不截图/不切图/不出 pptx。
+                                供「构图闸门前置到 HTML 层」用：秒级、零打包，循环复用同批图。
+                                此模式下 --out 可省（只需 --workdir 落 layout-report.json）。
+  --help                        显示帮助
+`;
+}
+
+function parseArgs(argv) {
+  const args = {
+    htmlFile: null,
+    out: null,
+    mode: 'flat',
+    slides: '[data-screen-label]',
+    width: 1920,
+    height: 1080,
+    workdir: null,
+    nodeModules: [],
+    python: 'python3',
+    opcCheck: true,
+    measureOnly: false,
+    withBgShots: false,
+  };
+
+  for (let i = 0; i < argv.length; i += 1) {
+    const arg = argv[i];
+    if (arg === '--help' || arg === '-h') {
+      args.help = true;
+    } else if (arg === '--out') {
+      args.out = argv[++i];
+    } else if (arg === '--mode') {
+      args.mode = argv[++i];
+    } else if (arg === '--slides') {
+      args.slides = argv[++i];
+    } else if (arg === '--width') {
+      args.width = Number(argv[++i]);
+    } else if (arg === '--height') {
+      args.height = Number(argv[++i]);
+    } else if (arg === '--workdir') {
+      args.workdir = argv[++i];
+    } else if (arg === '--node-modules') {
+      args.nodeModules.push(argv[++i]);
+    } else if (arg === '--python') {
+      args.python = argv[++i];
+    } else if (arg === '--no-opc-check') {
+      args.opcCheck = false;
+    } else if (arg === '--measure-only') {
+      args.measureOnly = true;
+    } else if (arg === '--with-bg-shots') {
+      // measure-only 时顺带落 slide-NN-background.png（背景态：隐前景+隐文字）+ slide-NN-foreground.png
+      // （foreground 态：隐文字、其余原样渲染，2026-07-03 新增）两张整页截图，不切图不出 pptx。
+      // 供 ppt 视觉门的像素级文字可读性检查（text_readability_pixel.py）采样文字底下的真实像素——
+      // 前者给 fgParent=null（直接压背景层）的文字用，后者给 fgParent 非空（卡内/前景块内）的文字用。
+      // 默认关：既有调用（webppt/导出）行为与产物不变。
+      args.withBgShots = true;
+    } else if (!args.htmlFile) {
+      args.htmlFile = arg;
+    } else {
+      throw new Error(`未知参数: ${arg}`);
+    }
+  }
+
+  if (args.help) {
+    return args;
+  }
+  if (!args.htmlFile) {
+    throw new Error('缺少 html_file。');
+  }
+  // measure-only 不出 pptx，--out 可省（只需 --workdir 落 layout-report.json）；其余模式必须给 --out。
+  if (!args.out && !args.measureOnly) {
+    throw new Error('缺少 --out output.pptx。');
+  }
+  if (!['flat', 'hybrid', 'native'].includes(args.mode)) {
+    throw new Error('--mode 必须是 flat、hybrid 或 native。');
+  }
+  if (args.mode === 'native') {
+    throw new Error('native 模式仍是实验方向，首版请使用 flat 或 hybrid。');
+  }
+  if (!Number.isFinite(args.width) || !Number.isFinite(args.height)) {
+    throw new Error('--width 和 --height 必须是数字。');
+  }
+  return args;
+}
+
+function maskBlocksKeepNewlines(content, regex) {
+  return content.replace(regex, (match) => match.replace(/[^\n]/g, ' '));
+}
+
+function htmlStaticPreflight(content) {
+  const errors = [];
+  const headCount = (content.match(/<head\b/gi) || []).length;
+  const bodyCount = (content.match(/<body\b/gi) || []).length;
+  if (headCount > 1) {
+    errors.push(`发现 ${headCount} 个 <head> 标签：HTML 很可能被拼接坏了，禁止导出 PPTX。`);
+  }
+  if (bodyCount > 1) {
+    errors.push(`发现 ${bodyCount} 个 <body> 标签：HTML 很可能被拼接坏了，禁止导出 PPTX。`);
+  }
+
+  let masked = content;
+  masked = maskBlocksKeepNewlines(masked, /<style\b[^>]*>.*?<\/style>/gis);
+  masked = maskBlocksKeepNewlines(masked, /<script\b[^>]*>.*?<\/script>/gis);
+  masked = maskBlocksKeepNewlines(masked, /<!--.*?-->/gs);
+  if (/^\s*\/\*\s*=.{10,}/m.test(masked)) {
+    errors.push('发现裸露在 <style> 外的 CSS 注释块：它会作为页面文字被截图进 PPT 背景。');
+  }
+  if (/^\s*(?:\.[A-Za-z_-][\w-]*|#[A-Za-z_-][\w-]*|[A-Za-z_-][\w-]*\s+[.#A-Za-z_-][^{\n]*)[^{\n]{0,120}\{\s*$/m.test(masked)) {
+    errors.push('发现裸露在 <style> 外的 CSS 选择器：请先修复 HTML，再导出 PPTX。');
+  }
+  return errors;
+}
+
+// ---------------------------------------------------------------------------
+// 纯函数（无 DOM/IO 依赖）：导出供单测，main() 末尾做「直接运行才执行」守卫。
+// ---------------------------------------------------------------------------
+
+function pxToIn(value, totalPx, totalIn) {
+  return (value / totalPx) * totalIn;
+}
+
+function pxToPt(value, totalPx, totalIn) {
+  return Math.max(6, Math.round((value / totalPx) * totalIn * 72 * 10) / 10);
+}
+
+// px 矩形 → PPT 英寸矩形（归一化等比映射；1920×1080→10×5.625 两轴比例相等）。
+function normalizeRect(rect, totalWidthPx, totalHeightPx) {
+  return {
+    x: pxToIn(rect.x, totalWidthPx, SLIDE_W),
+    y: pxToIn(rect.y, totalHeightPx, SLIDE_H),
+    w: pxToIn(rect.w, totalWidthPx, SLIDE_W),
+    h: pxToIn(rect.h, totalHeightPx, SLIDE_H),
+  };
+}
+
+// 前景切图文件名编码左上角 xy + 宽高（px 取整）——文件名即几何，便于人工核对/排错。
+function geometryFilename(slideNo, fgNo, rect) {
+  const r = (n) => Math.round(n);
+  return `slide-${String(slideNo).padStart(2, '0')}-fg-${String(fgNo).padStart(2, '0')}`
+    + `-x${r(rect.x)}-y${r(rect.y)}-w${r(rect.w)}-h${r(rect.h)}.png`;
+}
+
+// ---------------------------------------------------------------------------
+// 构图均衡的确定性指标（纯函数，供 layout_balance.py 闸门 + 单测）。
+// 思路：把内容（**文本 + 已成功切图的前景块**，不含背景图）投到 16×8 网格，按「格中心是否落进
+// 某内容框」算占用 → 覆盖率 / 四半区占用率 / 内容包围盒与质心 / 跨框显著重叠。背景渐变与全幅氛围
+// 图**故意不计入**（用户的诉求正是「即便有底图，内容只占半张也算失衡」）；全幅图是否铺满另由
+// hasBgImage 标记，交由 Python 闸门按页型放宽。
+// ---------------------------------------------------------------------------
+const BALANCE_GRID_COLS = 16;
+const BALANCE_GRID_ROWS = 8;
+// 放映级字号下限（屏上视觉 px）：低于此的文本段计入 balance.smallText，交 layout_balance.py 报 WARNING。
+// 与 layout-composition.md §0.85 阶梯配套（正文 38 / 注释 30 / 药丸 26…）；24 作下限只抓「明显偏小」的漏网。
+const FONT_FLOOR_PX = 24;
+
+function computeSlideBalance(slide, width, height) {
+  const boxes = [];
+  for (const r of slide.textRuns || []) {
+    const textRect = r.pptPxRect || pptTextBoxPx(r, width, height);
+    if (textRect.w > 1 && textRect.h > 1) {
+      boxes.push({
+        x: textRect.x, y: textRect.y, w: textRect.w, h: textRect.h, kind: 'text',
+        name: (r.text || 'text').slice(0, 16),
+        fgParent: r.fgParent || null,
+      });
+    }
+  }
+  for (const f of slide.foreground || []) {
+    // 只计入真正切出图的前景块（imagePath 在）；截图失败的块不会出现在 PPT 里。
+    if (f.imagePath && f.w > 1 && f.h > 1) {
+      boxes.push({ x: f.x, y: f.y, w: f.w, h: f.h, kind: 'fg', name: f.fgId || 'fg' });
+    }
+  }
+
+  const cols = BALANCE_GRID_COLS;
+  const rows = BALANCE_GRID_ROWS;
+  const cellW = width / cols;
+  const cellH = height / rows;
+  const occupied = new Array(cols * rows).fill(false);
+  for (let cy = 0; cy < rows; cy += 1) {
+    for (let cx = 0; cx < cols; cx += 1) {
+      const px = (cx + 0.5) * cellW;
+      const py = (cy + 0.5) * cellH;
+      for (const b of boxes) {
+        if (px >= b.x && px <= b.x + b.w && py >= b.y && py <= b.y + b.h) {
+          occupied[cy * cols + cx] = true;
+          break;
+        }
+      }
+    }
+  }
+  const totalCells = cols * rows;
+  const occCount = occupied.reduce((n, v) => n + (v ? 1 : 0), 0);
+  const coverage = totalCells ? occCount / totalCells : 0;
+
+  const halfFrac = (test) => {
+    let total = 0;
+    let occ = 0;
+    for (let cy = 0; cy < rows; cy += 1) {
+      for (let cx = 0; cx < cols; cx += 1) {
+        if (!test(cx, cy)) continue;
+        total += 1;
+        if (occupied[cy * cols + cx]) occ += 1;
+      }
+    }
+    return total ? occ / total : 0;
+  };
+  const midCol = cols / 2;
+  const midRow = rows / 2;
+  const halfOccupancy = {
+    top: halfFrac((_cx, cy) => cy < midRow),
+    bottom: halfFrac((_cx, cy) => cy >= midRow),
+    left: halfFrac((cx) => cx < midCol),
+    right: halfFrac((cx) => cx >= midCol),
+  };
+
+  let bbox = null;
+  let centroid = null;
+  if (boxes.length) {
+    let minX = Infinity;
+    let minY = Infinity;
+    let maxX = -Infinity;
+    let maxY = -Infinity;
+    let areaSum = 0;
+    let cxSum = 0;
+    let cySum = 0;
+    for (const b of boxes) {
+      minX = Math.min(minX, b.x);
+      minY = Math.min(minY, b.y);
+      maxX = Math.max(maxX, b.x + b.w);
+      maxY = Math.max(maxY, b.y + b.h);
+      const a = b.w * b.h;
+      areaSum += a;
+      cxSum += (b.x + b.w / 2) * a;
+      cySum += (b.y + b.h / 2) * a;
+    }
+    bbox = { x: minX, y: minY, w: maxX - minX, h: maxY - minY };
+    centroid = areaSum ? { x: cxSum / areaSum, y: cySum / areaSum } : null;
+  }
+
+  // 跨框显著重叠（专抓封面那种「标签/副标题压在大标题上」）：排除包含关系（卡内文字属正常）。
+  // 归一化坐标 = 像素 ÷ 画布宽高（原点左上、范围 0–1），供闸门精确报「哪两个元素 × 重叠区在哪」。
+  const norm = (bx, by, bw, bh) => ({
+    x: Math.round((bx / width) * 1000) / 1000,
+    y: Math.round((by / height) * 1000) / 1000,
+    w: Math.round((bw / width) * 1000) / 1000,
+    h: Math.round((bh / height) * 1000) / 1000,
+  });
+  const overlaps = [];
+  for (let i = 0; i < boxes.length; i += 1) {
+    for (let j = i + 1; j < boxes.length; j += 1) {
+      const a = boxes[i];
+      const b = boxes[j];
+      const ix = Math.max(a.x, b.x);
+      const iy = Math.max(a.y, b.y);
+      const ix2 = Math.min(a.x + a.w, b.x + b.w);
+      const iy2 = Math.min(a.y + a.h, b.y + b.h);
+      if (ix2 <= ix || iy2 <= iy) continue;
+      const aInB = a.x >= b.x && a.y >= b.y && a.x + a.w <= b.x + b.w && a.y + a.h <= b.y + b.h;
+      const bInA = b.x >= a.x && b.y >= a.y && b.x + b.w <= a.x + a.w && b.y + b.h <= a.y + a.h;
+      // 三层 PPT 导出中，文本层覆盖其承载前景块是正常结构（卡片底图 + 可编辑文字），
+      // 不能当成视觉碰撞；文本框为避免 Office 孤字换行会略宽于 HTML 原框，更不能只靠包含关系判断。
+      if (a.kind === 'text' && b.kind === 'fg' && a.fgParent && a.fgParent === b.name) continue;
+      if (b.kind === 'text' && a.kind === 'fg' && b.fgParent && b.fgParent === a.name) continue;
+      // 包含关系**仅当外层是前景卡片(fg)**才算正常（卡内文字/图标）；text-on-text、text-on-image
+      // 这类「小框压在大框上」是真碰撞（封面小标签压大标题即此），照常标记、不豁免。
+      if (aInB && b.kind === 'fg') continue;
+      if (bInA && a.kind === 'fg') continue;
+      // 同一前景块内的两段文本互叠 = 图内固有间距（如 SVG 架构图密排标签）→ 豁免，不算缺陷。
+      if (a.kind === 'text' && b.kind === 'text' && a.fgParent && a.fgParent === b.fgParent) continue;
+      const interIn = pxToIn(ix2 - ix, width, SLIDE_W) * pxToIn(iy2 - iy, height, SLIDE_H);
+      const smallerPx = Math.min(a.w * a.h, b.w * b.h);
+      const fracOfSmaller = smallerPx ? ((ix2 - ix) * (iy2 - iy)) / smallerPx : 0;
+      if (interIn > 0.02 && fracOfSmaller > 0.08) {
+        overlaps.push({
+          a: a.name,
+          b: b.name,
+          aKind: a.kind,
+          bKind: b.kind,
+          areaIn: Math.round(interIn * 1000) / 1000,
+          fracOfSmaller: Math.round(fracOfSmaller * 1000) / 1000,
+          // 归一化坐标（0–1，原点左上）：两元素各自外框 + 相交区，供闸门精确报位置/范围。
+          aRect: norm(a.x, a.y, a.w, a.h),
+          bRect: norm(b.x, b.y, b.w, b.h),
+          rect: norm(ix, iy, ix2 - ix, iy2 - iy),
+        });
+      }
+    }
+  }
+
+  // ── 卡片/分组填充度：非媒体前景卡（hasMedia=false，含递归切的底板 plate）的「卡内内容面积 ÷ 卡面积」。
+  // 内容面积 = 卡内**文本** + 卡内**其它 auto-fg 子块**（递归切后子块独立成块）。
+  // 媒体卡（含 img/svg/底图）豁免。供闸门抓「大卡装一句话」**与**「图元挤一角、旁边大片留白」（crammed group）。
+  const cards = [];
+  for (const f of slide.foreground || []) {
+    if (!f.imagePath || f.w <= 1 || f.h <= 1 || f.hasMedia) continue;
+    const cardArea = f.w * f.h;
+    let contentArea = 0;
+    const addInside = (b) => {
+      const cx = b.x + b.w / 2;
+      const cy = b.y + b.h / 2;
+      if (cx < f.x || cx > f.x + f.w || cy < f.y || cy > f.y + f.h) return; // 中心在卡内才计
+      const ix = Math.max(b.x, f.x);
+      const iy = Math.max(b.y, f.y);
+      const ix2 = Math.min(b.x + b.w, f.x + f.w);
+      const iy2 = Math.min(b.y + b.h, f.y + f.h);
+      if (ix2 > ix && iy2 > iy) contentArea += (ix2 - ix) * (iy2 - iy); // 裁到卡内，防越界高估
+    };
+    for (const r of slide.textRuns || []) {
+      if (r.w > 1 && r.h > 1) addInside(r); // 卡内文本
+    }
+    for (const g of slide.foreground || []) {
+      if (g === f || !g.imagePath || g.w <= 1 || g.h <= 1) continue;
+      addInside(g); // 卡内其它切图子块（递归切的圆/层/节点等）
+    }
+    cards.push({
+      fgId: f.fgId || 'fg',
+      fill: cardArea ? Math.round((contentArea / cardArea) * 1000) / 1000 : 0,
+      rect: norm(f.x, f.y, f.w, f.h),
+    });
+  }
+
+  // ── 文本溢出（仅报**显著裁切**）：内容超出自身框 > 框高一半且 > 10px，才算真裁切。
+  // 单行标题普遍 +4px 是行盒 vs 内容盒舍入噪声（line-height/降部），用占比阈值滤掉，避免满屏误报。
+  const overflowRuns = [];
+  for (const r of slide.textRuns || []) {
+    const o = r.overflow || 0;
+    if (o > 10 && r.h > 0 && o > r.h * 0.5) {
+      overflowRuns.push({
+        text: (r.text || 'text').slice(0, 16),
+        overflowPx: Math.round(o),
+        rect: norm(r.x, r.y, r.w, r.h),
+      });
+    }
+  }
+
+  // ── 超出画布：文本/前景块右/下越界（x+w>宽 或 y+h>高，留 8px 容差）→ 内容比页面大、会被裁出可视区。
+  //   抓「一列层块/节点堆到 >1080」这类（slide13 架构图 1267px）。供闸门 WARNING + 提示拆页/分栏。
+  const OFF_TOL = 8;
+  const offCanvas = [];
+  const offers = (x, y, w, h) =>
+    x + w > width + OFF_TOL || y + h > height + OFF_TOL || x < -OFF_TOL || y < -OFF_TOL;
+  for (const r of slide.textRuns || []) {
+    if (r.w > 1 && r.h > 1 && offers(r.x, r.y, r.w, r.h)) {
+      offCanvas.push({ kind: 'text', name: (r.text || 'text').slice(0, 16), rect: norm(r.x, r.y, r.w, r.h) });
+    }
+  }
+  for (const f of slide.foreground || []) {
+    if (f.imagePath && f.w > 1 && f.h > 1 && offers(f.x, f.y, f.w, f.h)) {
+      offCanvas.push({ kind: 'fg', name: f.fgId || 'fg', rect: norm(f.x, f.y, f.w, f.h) });
+    }
+  }
+
+  // ── 文字/背景对比度（WCAG）：text.color vs 解析出的 text.bgColor。ratio < 3.0（放映级大字 AA 阈）才收。
+  //   治「深紫底 + 黑字」（实测对比 ~1.1 不可读）。bgSolid=true 是高置信纯底（闸门可硬拦），渐变/图底低置信只提示。
+  const parseRGB = (c) => {
+    if (!c) return null;
+    const m = /rgba?\(([^)]+)\)/.exec(c);
+    if (m) {
+      const p = m[1].split(',').map((s) => parseFloat(s));
+      return p.length >= 3 && p.every((n) => Number.isFinite(n)) ? [p[0], p[1], p[2]] : null;
+    }
+    const h = /^#([0-9a-f]{3}|[0-9a-f]{6})$/i.exec((c || '').trim());
+    if (h) {
+      const x = h[1].length === 3 ? h[1].split('').map((d) => d + d).join('') : h[1];
+      return [parseInt(x.slice(0, 2), 16), parseInt(x.slice(2, 4), 16), parseInt(x.slice(4, 6), 16)];
+    }
+    return null;
+  };
+  const relLum = (rgb) => {
+    const f = (v) => {
+      const c = v / 255;
+      return c <= 0.03928 ? c / 12.92 : ((c + 0.055) / 1.055) ** 2.4;
+    };
+    return 0.2126 * f(rgb[0]) + 0.7152 * f(rgb[1]) + 0.0722 * f(rgb[2]);
+  };
+  const lowContrast = [];
+  for (const r of slide.textRuns || []) {
+    if (!(r.w > 1 && r.h > 1)) continue;
+    const fgc = parseRGB(r.color);
+    const bgc = parseRGB(r.bgColor);
+    if (!fgc || !bgc) continue;
+    const l1 = relLum(fgc);
+    const l2 = relLum(bgc);
+    const ratio = Math.round(((Math.max(l1, l2) + 0.05) / (Math.min(l1, l2) + 0.05)) * 100) / 100;
+    if (ratio < 3.0) {
+      lowContrast.push({
+        text: (r.text || 'text').slice(0, 16),
+        ratio,
+        color: r.color,
+        bgColor: r.bgColor,
+        bgSolid: !!r.bgSolid,
+        rect: norm(r.x, r.y, r.w, r.h),
+      });
+    }
+  }
+
+  // ── 字号下限：低于放映级下限的文本段（投影上偏小）。供闸门 WARNING + 督促设计阶段把字号做大。
+  //   run.fontSize 已是屏上视觉 px（SVG 已乘 viewBox→视口缩放，见 extractLayers），直接比下限。
+  const smallText = [];
+  let minFontSize = null;
+  for (const r of slide.textRuns || []) {
+    const fs = r.fontSize || 0;
+    if (fs > 0) minFontSize = minFontSize == null ? fs : Math.min(minFontSize, fs);
+    if (fs > 0 && fs < FONT_FLOOR_PX && r.w > 1 && r.h > 1) {
+      smallText.push({
+        text: (r.text || 'text').slice(0, 16),
+        fontSize: Math.round(fs * 10) / 10,
+        rect: norm(r.x, r.y, r.w, r.h),
+      });
+    }
+  }
+
+  // ── 截图夹带文本：背景截图态下「仍可见且未被标注隐藏」的 HTML/SVG 文本（含带文字的 ::before/::after）。
+  //   由 renderSlides 的背景态探针 probeBakedText 采集后挂在 slide.bakedText；此处仅透传给闸门。
+  //   底图/中层切图**绝不能带 HTML 文字**（用户硬要求）——有命中 = 该文字会烧进截图且不可编辑 → 闸门 ERROR。
+  const bakedText = Array.isArray(slide.bakedText) ? slide.bakedText : [];
+
+  // 本页是否有「前景视觉填充块」（切出图的 img/svg/图标/大视觉块，hasMedia=true）。
+  // 供构图闸门「有图不算空」放宽用：纯文本/色块卡片不算（hasMedia=false），唯有真视觉元素才让
+  // 「页面过空 / 空半」降级——与「每页 ≥1 视觉元素」的设计同向（有图标/图表的页天然不空）。
+  const hasForegroundVisual = (slide.foreground || []).some(
+    (f) => f.imagePath && f.hasMedia,
+  );
+
+  // ── 媒体块矩形（加性字段）：hasMedia 前景块的归一化外框，供 layout_balance --ppt-strict 判
+  // 「大空卡是否其实被图盖着」、以及按 sourceFile 反查 min_canvas_fraction 是否达标（真实渲染框，
+  // 非静态正则估算）。默认闸门不读此字段（webppt 行为不变）。
+  // BARE_MEDIA_TAGS 兜底（2026-07-07 真机 p8 复盘坐实）：hasMedia = node.querySelector('img,...')
+  // 只查**后代**，裸 <img>/<svg> 自身作前景块（无 div 包裹）时恒 false（与 layout_balance.py 的
+  // PPT_STRICT_MEDIA_TAGS 同一个已知盲区，那边在别的检查里已用 tag 兜底）——不改 hasMedia 本体
+  // （它驱动默认档空心卡/有图不算空判定，动了会漂移 webppt 行为），只在 mediaRects 这个加性字段的
+  // 判定里额外认 tag 本身是媒体标签的情况，否则这类图永远不会被计入 mediaRects。
+  const BARE_MEDIA_TAGS = new Set(['img', 'svg', 'picture', 'video', 'canvas']);
+  const mediaRects = [];
+  for (const f of slide.foreground || []) {
+    const isMedia = f.hasMedia || BARE_MEDIA_TAGS.has(f.tag);
+    if (f.imagePath && isMedia && f.w > 1 && f.h > 1) {
+      mediaRects.push({ ...norm(f.x, f.y, f.w, f.h), sourceFile: f.sourceFile || null });
+    }
+  }
+
+  // ── 全部前景块矩形（加性字段）：含媒体卡。供 layout_balance --ppt-strict 的
+  // 【文字溢出卡片】containment 检查按 textRun.fgParent 反查父卡外框——cards[] 排除了
+  // 媒体卡（hasMedia 跳过），文字溢出「带图卡片」时在 cards 里查不到父 rect。
+  // 默认闸门不读此字段（webppt 行为不变）。
+  const fgRects = [];
+  for (const f of slide.foreground || []) {
+    if (f.imagePath && f.w > 1 && f.h > 1) {
+      fgRects.push({
+        name: f.fgId || 'fg',
+        rect: norm(f.x, f.y, f.w, f.h),
+        hasMedia: !!f.hasMedia,
+        // tag（加性）：hasMedia 的 querySelector 只查后代——裸 <img>/<svg> 自身作前景块时
+        // 恒 false（2026-07-03 真机 03 页图卡案）。--ppt-strict 侧靠 tag 识别媒体块，
+        // 不改 hasMedia 本体（它驱动默认档空心卡/有图不算空判定，动了会漂移 webppt 行为）。
+        tag: f.tag || null,
+      });
+    }
+  }
+
+  const round3 = (n) => (n == null ? null : Math.round(n * 1000) / 1000);
+  return {
+    grid: { cols, rows },
+    contentBoxes: boxes.length,
+    hasBgImage: !!slide.hasBgImage,
+    hasForegroundVisual,
+    coverage: round3(coverage),
+    halfOccupancy: {
+      top: round3(halfOccupancy.top),
+      bottom: round3(halfOccupancy.bottom),
+      left: round3(halfOccupancy.left),
+      right: round3(halfOccupancy.right),
+    },
+    bbox: bbox
+      ? { x: Math.round(bbox.x), y: Math.round(bbox.y), w: Math.round(bbox.w), h: Math.round(bbox.h) }
+      : null,
+    centroid: centroid ? { x: Math.round(centroid.x), y: Math.round(centroid.y) } : null,
+    cards,
+    overflowRuns,
+    overlaps,
+    offCanvas,
+    lowContrast,
+    minFontSize: minFontSize == null ? null : Math.round(minFontSize * 10) / 10,
+    smallText,
+    bakedText,
+    mediaRects,
+    fgRects,
+  };
+}
+
+async function imageInfo(path) {
+  const buffer = await readFile(path);
+  const hash = createHash('sha256').update(buffer).digest('hex');
+  let width = null;
+  let height = null;
+  let colorType = null; // PNG IHDR 第 25 字节：6 = truecolor+alpha（切图应带 alpha 通道）
+  if (
+    buffer.length >= 26
+    && buffer[0] === 0x89
+    && buffer[1] === 0x50
+    && buffer[2] === 0x4e
+    && buffer[3] === 0x47
+  ) {
+    width = buffer.readUInt32BE(16);
+    height = buffer.readUInt32BE(20);
+    colorType = buffer[25];
+  }
+  return { hash, width, height, colorType };
+}
+
+function colorDistance(a, b) {
+  return Math.max(
+    Math.abs(a[0] - b[0]),
+    Math.abs(a[1] - b[1]),
+    Math.abs(a[2] - b[2]),
+  );
+}
+
+function parseRgbColor(c) {
+  if (!c) return null;
+  const m = /rgba?\(([^)]+)\)/.exec(c);
+  if (m) {
+    const p = m[1].split(',').map((s) => Number.parseFloat(s));
+    return p.length >= 3 && p.slice(0, 3).every((n) => Number.isFinite(n))
+      ? [p[0], p[1], p[2]]
+      : null;
+  }
+  const h = /^#([0-9a-f]{3}|[0-9a-f]{6})$/i.exec(String(c).trim());
+  if (!h) return null;
+  const x = h[1].length === 3 ? h[1].split('').map((d) => d + d).join('') : h[1];
+  return [parseInt(x.slice(0, 2), 16), parseInt(x.slice(2, 4), 16), parseInt(x.slice(4, 6), 16)];
+}
+
+function contrastRatio(a, b) {
+  const f = (v) => {
+    const c = v / 255;
+    return c <= 0.03928 ? c / 12.92 : ((c + 0.055) / 1.055) ** 2.4;
+  };
+  const relLum = (rgb) => 0.2126 * f(rgb[0]) + 0.7152 * f(rgb[1]) + 0.0722 * f(rgb[2]);
+  const l1 = relLum(a);
+  const l2 = relLum(b);
+  return (Math.max(l1, l2) + 0.05) / (Math.min(l1, l2) + 0.05);
+}
+
+function hasVisibleTextRisk(textRuns = []) {
+  return textRuns.some((run) => {
+    if (!(run.w > 1 && run.h > 1)) return false;
+    const fg = parseRgbColor(run.color);
+    const bg = parseRgbColor(run.bgColor);
+    // 低置信图底/渐变底无法精确判断，交给 bakedText 与真实截图检查；这里不误杀透明/图片底夹具。
+    if (!fg || !bg || !run.bgSolid) return false;
+    return contrastRatio(fg, bg) >= 1.5;
+  });
+}
+
+async function transparentizeCornerBackground(path, extraPaths = []) {
+  const { PNG } = await importPackage('pngjs', extraPaths);
+  const buffer = await readFile(path);
+  const png = PNG.sync.read(buffer);
+  const { width, height, data } = png;
+  if (!width || !height) return false;
+
+  const pixelAt = (x, y) => {
+    const i = (y * width + x) * 4;
+    return [data[i], data[i + 1], data[i + 2], data[i + 3]];
+  };
+  const corner = pixelAt(0, 0);
+  const center = pixelAt(Math.floor(width / 2), Math.floor(height / 2));
+  // 若中心与角落几乎同色，通常是普通矩形白卡/同底色卡，透明化会误挖整块，直接跳过。
+  if (colorDistance(corner, center) < 8) return false;
+
+  const tolerance = 14;
+  const seen = new Uint8Array(width * height);
+  const stack = [
+    [0, 0],
+    [width - 1, 0],
+    [0, height - 1],
+    [width - 1, height - 1],
+  ];
+  let changed = false;
+  while (stack.length) {
+    const [x, y] = stack.pop();
+    if (x < 0 || y < 0 || x >= width || y >= height) continue;
+    const key = y * width + x;
+    if (seen[key]) continue;
+    seen[key] = 1;
+    const i = key * 4;
+    const px = [data[i], data[i + 1], data[i + 2], data[i + 3]];
+    if (px[3] === 0 || colorDistance(px, corner) <= tolerance) {
+      if (data[i + 3] !== 0) {
+        data[i + 3] = 0;
+        changed = true;
+      }
+      stack.push([x + 1, y], [x - 1, y], [x, y + 1], [x, y - 1]);
+    }
+  }
+  if (changed) {
+    await writeFile(path, PNG.sync.write(png, { colorType: 6 }));
+  }
+  return changed;
+}
+
+function cssColorToPpt(color) {
+  const transparent = { color: 'FFFFFF', transparency: 100 };
+  if (!color || color === 'transparent') return transparent;
+
+  const rgba = color.match(/rgba?\(([^)]+)\)/i);
+  if (!rgba) {
+    const hex = color.match(/^#([0-9a-f]{3}|[0-9a-f]{6})$/i);
+    if (!hex) return transparent;
+    const raw = hex[1].length === 3
+      ? hex[1].split('').map((char) => char + char).join('')
+      : hex[1];
+    return { color: raw.toUpperCase(), transparency: 0 };
+  }
+
+  const parts = rgba[1].split(',').map((part) => part.trim());
+  const r = Number(parts[0]);
+  const g = Number(parts[1]);
+  const b = Number(parts[2]);
+  const alpha = parts.length > 3 ? Number(parts[3]) : 1;
+  if (![r, g, b, alpha].every(Number.isFinite)) return transparent;
+  const hex = [r, g, b]
+    .map((num) => Math.max(0, Math.min(255, Math.round(num))).toString(16).padStart(2, '0'))
+    .join('')
+    .toUpperCase();
+  return {
+    color: hex,
+    transparency: Math.max(0, Math.min(100, Math.round((1 - alpha) * 100))),
+  };
+}
+
+function normalizeText(text) {
+  return text.replace(/\s+/g, ' ').trim();
+}
+
+// 按导出机器平台选「中文兜底字体」：写进 PPTX 的 fontFace 必须是该机器**真实存在**的字体名，
+// 否则 PowerPoint 打开时缺字 → 自动替换 → 可编辑文字与背景截图（Chromium 用本机字体渲染）字体/
+// 度量错位。曾固定返回 Mac 专有的 'Hiragino Sans GB'，在 Windows（绿色版主要分发面）上必被替换。
+// 与 createPptx 里 theme 的 headFontFace/bodyFontFace 保持同一套默认。
+const CJK_FALLBACK = process.platform === 'win32'
+  ? 'Microsoft YaHei'
+  : process.platform === 'darwin'
+    ? 'Hiragino Sans GB'
+    : 'Noto Sans CJK SC';
+
+function pickFontFace(fontFamily = '') {
+  const normalized = fontFamily.toLowerCase();
+  // PingFang 是 Mac 专有名；非 Mac 机器上落地为本平台 CJK 兜底。
+  if (normalized.includes('pingfang')) {
+    return process.platform === 'darwin' ? 'Hiragino Sans GB' : CJK_FALLBACK;
+  }
+  // 显式命中的具体字体名按命中返回（含西文 Aptos/Arial）；CJK 名命中也尊重 CSS 声明。
+  const candidates = [
+    'Hiragino Sans GB',
+    'Microsoft YaHei',
+    'Noto Sans CJK SC',
+    'Source Han Sans SC',
+    'Aptos',
+    'Arial',
+  ];
+  for (const candidate of candidates) {
+    if (normalized.includes(candidate.toLowerCase())) {
+      return candidate;
+    }
+  }
+  return CJK_FALLBACK;
+}
+
+// ---------------------------------------------------------------------------
+// 模块加载（playwright-core / pptxgenjs；支持额外 node_modules 搜索路径）
+// ---------------------------------------------------------------------------
+
+function packageSearchPaths(extraPaths = []) {
+  const scriptDir = dirname(fileURLToPath(import.meta.url));
+  const envPaths = (process.env.NODE_PATH || '')
+    .split(':')
+    .map((item) => item.trim())
+    .filter(Boolean);
+  return [
+    process.cwd(),
+    scriptDir,
+    ...extraPaths.map((item) => resolve(item)),
+    ...envPaths,
+  ];
+}
+
+async function importPackage(name, extraPaths = []) {
+  try {
+    return await import(name);
+  } catch (firstError) {
+    const require = createRequire(import.meta.url);
+    try {
+      const resolved = require.resolve(name, { paths: packageSearchPaths(extraPaths) });
+      return await import(pathToFileURL(resolved).href);
+    } catch {
+      throw firstError;
+    }
+  }
+}
+
+async function loadModules(extraPaths = []) {
+  let chromium;
+  let pptxgenModule;
+  try {
+    ({ chromium } = await importPackage('playwright-core', extraPaths));
+  } catch (error) {
+    // 优雅降级：deck/PPT 导出是可选能力（playwright-core 列 optionalDependencies）。缺它时给可操作指引，不裸抛。
+    throw new Error(
+      'deck/PPT 导出需要 playwright-core（渲染截图）。请安装：\n' +
+        '  npm i playwright-core pptxgenjs   （或 bun add playwright-core pptxgenjs）\n' +
+        '  npx playwright install chromium   （playwright-core 不含浏览器二进制，须单独装；或用系统 Chrome：launch({channel:"chrome"})）\n' +
+        `原始错误: ${error.message}`,
+    );
+  }
+  try {
+    pptxgenModule = await importPackage('pptxgenjs', extraPaths);
+  } catch (error) {
+    throw new Error(
+      'deck/PPT 导出需要 pptxgenjs（生成 .pptx）。请安装：npm i pptxgenjs（或 bun add pptxgenjs），并用 Node 运行。' +
+        `原始错误: ${error.message}`,
+    );
+  }
+  const PptxGenJS = pptxgenModule.default ?? pptxgenModule;
+  return { chromium, PptxGenJS };
+}
+
+// ---------------------------------------------------------------------------
+// 导出态 CSS：data-export-mode 取值 full / background / foreground / text
+//   full       —— 仅隐 ignore 控件（flat 整页截图、量几何都在此态）
+//   background —— 隐前景 + 隐文本 → 纯背景整页截图
+//   foreground —— 隐文本（保留前景块自身底色）→ 逐元素切图（再叠 solo 隔离只显当前块）
+//   text       —— 隐前景、底透明 → 仅用于落 pure-text.html 快照
+// 文本选择器统一吃 data-pptx-kind="text" 与 data-pptx-layer="text" 两种写法。
+// ---------------------------------------------------------------------------
+function exportCss(width, height) {
+  return `
+    html[data-ui-pptx-export="true"],
+    html[data-ui-pptx-export="true"] body {
+      width: ${width}px !important;
+      height: ${height}px !important;
+      min-width: ${width}px !important;
+      min-height: ${height}px !important;
+      margin: 0 !important;
+      overflow: hidden !important;
+    }
+    html[data-ui-pptx-export="true"] .stage-shell {
+      width: ${width}px !important;
+      height: ${height}px !important;
+      min-height: ${height}px !important;
+      display: block !important;
+      overflow: hidden !important;
+    }
+    html[data-ui-pptx-export="true"] .scaled-stage {
+      width: ${width}px !important;
+      height: ${height}px !important;
+      position: relative !important;
+      inset: auto !important;
+      margin: 0 !important;
+      transform: none !important;
+      transform-origin: top left !important;
+    }
+    html[data-ui-pptx-export="true"] [data-ui-export-hidden="true"] {
+      display: none !important;
+      visibility: hidden !important;
+    }
+    html[data-ui-pptx-export="true"] [data-ui-export-stray="true"] {
+      display: none !important;
+      visibility: hidden !important;
+      opacity: 0 !important;
+    }
+    /* 流式 deck 适配：deck.html 现在是「每页 position:relative 纵向排开、人可滚动审阅」（像 PPT 导出的 PDF）。
+       导出时 prepare() 逐页隐藏其余页（data-ui-export-hidden="true"），这里把「当前页」（未隐藏的那张，
+       data-ui-export-hidden="false"）钉回视口左上、清零外边距/缩放 —— 不论 deck 浏览版式如何（流式/居中/页间距），
+       导出都按真实 1920×1080 截这一页、几何零偏移（getBoundingClientRect 仍落在 0..宽/0..高，构图门/切图代码一行不改）。 */
+    html[data-ui-pptx-export="true"] [data-ui-export-hidden="false"] {
+      position: fixed !important;
+      top: 0 !important;
+      left: 0 !important;
+      margin: 0 !important;
+      transform: none !important;
+    }
+    /* 任意导出态都隐藏浏览器专用控件/调试条 */
+    html[data-export-mode] [data-pptx-export="ignore"] {
+      visibility: hidden !important;
+    }
+    /* 背景态：隐前景（中层离散块）+ 隐文本 → 纯背景（= AI 底图 / CSS 纯色渐变页级基底 / scrim，垫底）。
+       前景以 [data-pptx-auto-fg]（tagLayers 自动标的离散块）+ [data-pptx-layer="foreground"]（显式）为准；
+       文本以 [data-pptx-auto-text]（含 SVG <text>）为准，兼容旧 kind/layer 标注。 */
+    html[data-export-mode="background"] [data-pptx-auto-fg],
+    html[data-export-mode="background"] [data-pptx-layer="foreground"],
+    html[data-export-mode="background"] [data-pptx-auto-text],
+    html[data-export-mode="background"] [data-pptx-kind="text"],
+    html[data-export-mode="background"] [data-pptx-layer="text"] {
+      visibility: hidden !important;
+      opacity: 0 !important;
+      color: transparent !important;
+      -webkit-text-fill-color: transparent !important;
+      text-shadow: none !important;
+    }
+    /* 前景态：**只显前景块**（隐背景/文本/其余一切 + 底透明）→ 真正的「纯前景」快照。
+       前景块内的文字仍隐（交文本层还原）。 */
+    html[data-export-mode="foreground"] body * {
+      visibility: hidden !important;
+    }
+    html[data-export-mode="foreground"] [data-pptx-auto-fg],
+    html[data-export-mode="foreground"] [data-pptx-auto-fg] *,
+    html[data-export-mode="foreground"] [data-pptx-layer="foreground"],
+    html[data-export-mode="foreground"] [data-pptx-layer="foreground"] * {
+      visibility: visible !important;
+    }
+    html[data-export-mode="foreground"] [data-pptx-auto-fg] [data-pptx-auto-text],
+    html[data-export-mode="foreground"] [data-pptx-layer="foreground"] [data-pptx-auto-text],
+    html[data-export-mode="foreground"] [data-pptx-layer="foreground"] [data-pptx-kind="text"],
+    html[data-export-mode="foreground"] [data-pptx-layer="foreground"] [data-pptx-layer="text"] {
+      visibility: hidden !important;
+      opacity: 0 !important;
+      color: transparent !important;
+      -webkit-text-fill-color: transparent !important;
+      text-shadow: none !important;
+    }
+    html[data-export-mode="foreground"] body {
+      background: transparent !important;
+    }
+    /* 切图态（逐元素）：**只显当前块**（data-fg-current）及其子树 + 底透明，隐其内文字 →
+       配 locator.screenshot({omitBackground}) 切出纯净、透明区真透明的 PNG。与 foreground 态分开，
+       避免「显所有前景」与「只显当前块」两套规则优先级互搏。 */
+    html[data-export-mode="fg-cut"] body * {
+      visibility: hidden !important;
+    }
+    /* 根 + body 都置透明（不止 body）：omitBackground 只去 Playwright 默认白底，作者写在 html/:root 上的
+       底色会从圆角/圆形切图的透明区透出 → 暗角/黑角。这里把根底色一并清掉，切图四角真透明。 */
+    html[data-export-mode="fg-cut"],
+    html[data-export-mode="fg-cut"] body {
+      background: transparent !important;
+      background-image: none !important;
+    }
+    html[data-export-mode="fg-cut"] [data-fg-current="true"],
+    html[data-export-mode="fg-cut"] [data-fg-current="true"] * {
+      visibility: visible !important;
+    }
+    /* 递归切图：切「当前块」时隐藏其**后代切图块**（各自有 data-pptx-fg-id）及其子树 →
+       底板 plate 的切图只含自身底色/边框，子块在原位透出 plate 底、由各自切图还原 → 零重复、各自可拖。
+       叶子块无后代切图块、此规则不影响（照常整切）。 */
+    html[data-export-mode="fg-cut"] [data-fg-current="true"] [data-pptx-fg-id],
+    html[data-export-mode="fg-cut"] [data-fg-current="true"] [data-pptx-fg-id] * {
+      visibility: hidden !important;
+    }
+    /* 隐藏当前块内的文本——**必须带子树 ` *`**，否则上面 [data-fg-current] *(规格 0,2,0) 会把
+       「auto-text 容器」的子元素重新显示出来（真机：药丸 .pill 套在无样式 wrapper 里、wrapper 被标 auto-text，
+       hide 了 wrapper 但 .pill 子被 * 规则复显 → 文字+药丸底烧进中层切图，就是用户反复反馈的 4/16 页残留文字）。
+       带 ` *` 的规格 (0,3,0) > [data-fg-current] *(0,2,0) → 容器及其整棵子树都隐藏。probe 查不到此类（DOM 上文字确已标
+       auto-text，只是切图态被 * 复显）——靠这条 CSS 子树规则根治。 */
+    html[data-export-mode="fg-cut"] [data-fg-current="true"] [data-pptx-auto-text],
+    html[data-export-mode="fg-cut"] [data-fg-current="true"] [data-pptx-auto-text] *,
+    html[data-export-mode="fg-cut"] [data-fg-current="true"] [data-pptx-kind="text"],
+    html[data-export-mode="fg-cut"] [data-fg-current="true"] [data-pptx-kind="text"] *,
+    html[data-export-mode="fg-cut"] [data-fg-current="true"] [data-pptx-layer="text"],
+    html[data-export-mode="fg-cut"] [data-fg-current="true"] [data-pptx-layer="text"] * {
+      visibility: hidden !important;
+      opacity: 0 !important;
+      color: transparent !important;
+      -webkit-text-fill-color: transparent !important;
+      text-shadow: none !important;
+    }
+    /* 文本态：**只显文本**（隐前景/背景/其余一切 + 底透明）→ 真正的「纯文本」快照 */
+    html[data-export-mode="text"] body * {
+      visibility: hidden !important;
+    }
+    html[data-export-mode="text"] [data-pptx-auto-text],
+    html[data-export-mode="text"] [data-pptx-auto-text] *,
+    html[data-export-mode="text"] [data-pptx-kind="text"],
+    html[data-export-mode="text"] [data-pptx-layer="text"],
+    html[data-export-mode="text"] [data-pptx-kind="text"] *,
+    html[data-export-mode="text"] [data-pptx-layer="text"] * {
+      visibility: visible !important;
+    }
+    html[data-export-mode="text"],
+    html[data-export-mode="text"] body {
+      background: transparent !important;
+      background-image: none !important;
+    }
+  `;
+}
+
+// 落「纯背景/前景/文本」HTML 中间产物：序列化当前 mode 的 documentElement，
+// 注 <base> 指回原 HTML 目录（相对 assets/、url(...) 都能在单独打开时解析）。
+async function writeLayerSnapshot(page, mode, outPath, htmlDir) {
+  await page.evaluate((m) => {
+    document.documentElement.setAttribute('data-export-mode', m);
+    document.documentElement.setAttribute('data-ui-pptx-export', 'true');
+  }, mode);
+  const html = await page.evaluate(() => `<!DOCTYPE html>\n${document.documentElement.outerHTML}`);
+  const baseHref = `${pathToFileURL(htmlDir).href}/`;
+  const baseTag = `<base href="${baseHref}">`;
+  const withBase = /<head(\s[^>]*)?>/i.test(html)
+    ? html.replace(/<head(\s[^>]*)?>/i, (m) => `${m}\n${baseTag}`)
+    : html.replace(/<html(\s[^>]*)?>/i, (m) => `${m}\n<head>${baseTag}</head>`);
+  await writeFile(outPath, withBase, 'utf8');
+}
+
+async function renderSlides({ chromium, htmlPath, selector, width, height, workdir, mode, measureOnly = false, withBgShots = false, nodeModules = [] }) {
+  let browser;
+  try {
+    browser = await chromium.launch({ headless: true });
+  } catch (error) {
+    try {
+      browser = await chromium.launch({ headless: true, channel: 'chrome' });
+    } catch (fallbackError) {
+      // playwright-core 装了但缺浏览器二进制——优雅降级给可操作指引（绿色版须把 chromium 打进分发）。
+      throw new Error(
+        '无法启动 Chromium：playwright-core 已装但缺浏览器二进制，且系统 Chrome fallback 也不可用。' +
+          '请跑 `npx playwright install chromium`，或安装 Google Chrome。绿色版需把 chromium 一并打进分发。' +
+          `原始错误: ${error.message}; fallback: ${fallbackError.message}`,
+      );
+    }
+  }
+  const page = await browser.newPage({ viewport: { width, height }, deviceScaleFactor: 1 });
+  const consoleErrors = [];
+  page.on('console', (message) => {
+    if (message.type() === 'error') {
+      consoleErrors.push(message.text());
+    }
+  });
+  page.on('pageerror', (error) => {
+    consoleErrors.push(error.message);
+  });
+
+  await page.goto(pathToFileURL(htmlPath).href, { waitUntil: 'networkidle' });
+  await page.addStyleTag({ content: String(exportCss(width, height)) });
+  await page.evaluate(() => {
+    document.documentElement.setAttribute('data-ui-pptx-export', 'true');
+  });
+
+  const layerSnapshots = {};
+  let wroteLayerSnapshots = false;
+
+  const slideMeta = await page.evaluate((slideSelector) => {
+    const nodes = Array.from(document.querySelectorAll(slideSelector));
+    if (nodes.length) {
+      const nodeSet = new Set(nodes);
+      for (const child of Array.from(document.body.childNodes)) {
+        if (child.nodeType === Node.TEXT_NODE && child.textContent.trim()) {
+          const span = document.createElement('span');
+          span.setAttribute('data-ui-export-stray', 'true');
+          child.parentNode.insertBefore(span, child);
+          span.appendChild(child);
+        } else if (
+          child.nodeType === Node.ELEMENT_NODE
+          && !nodeSet.has(child)
+          && !child.matches('script,style,template,noscript')
+          && !child.querySelector(slideSelector)
+        ) {
+          child.setAttribute('data-ui-export-stray', 'true');
+        }
+      }
+    }
+    if (!nodes.length) {
+      const label = document.body.getAttribute('data-screen-label') || document.title || '01 页面';
+      return [{ index: 0, label, fallback: true }];
+    }
+    return nodes.map((node, index) => ({
+      index,
+      label: node.getAttribute('data-screen-label') || `${String(index + 1).padStart(2, '0')} 页面`,
+      fallback: false,
+    }));
+  }, selector);
+
+  const slides = [];
+  for (const meta of slideMeta) {
+    // 逐页进度（stderr）：导出多页时不再「无声」，便于看到卡在哪一页/哪一阶段。
+    console.error(`[export] slide ${meta.index + 1}/${slideMeta.length}：${meta.label} 渲染中…`);
+    const fullPath = resolve(workdir, `slide-${String(meta.index + 1).padStart(2, '0')}-full.png`);
+    const backgroundPath = resolve(workdir, `slide-${String(meta.index + 1).padStart(2, '0')}-background.png`);
+    // foreground 态整页截图（仅 --with-bg-shots 时补拍）：文字隐藏、卡片/SVG/渐变/图片原样渲染——
+    // 给「卡内文字」对比度采样提供真实像素背衬，绕开 CSS resolveBg 猜色的局限（渐变/SVG fill 猜不准）。
+    const foregroundShotPath = resolve(workdir, `slide-${String(meta.index + 1).padStart(2, '0')}-foreground.png`);
+
+    async function prepare(exportMode, options = {}) {
+      const visibleCount = await page.evaluate(({ slideSelector, index, exportMode: exportModeValue }) => {
+        const INLINE_PROPS = [
+          'visibility',
+          'opacity',
+          'color',
+          '-webkit-text-fill-color',
+          'text-shadow',
+          'pointer-events',
+        ];
+        const restoreInlineExportStyles = () => {
+          for (const el of document.querySelectorAll('[data-ui-pptx-inline-hidden="true"]')) {
+            for (const prop of INLINE_PROPS) {
+              const key = prop.replace(/[^a-z]/gi, '_');
+              const value = el.getAttribute(`data-ui-pptx-prev-${key}`) || '';
+              const priority = el.getAttribute(`data-ui-pptx-prev-${key}-priority`) || '';
+              if (value) el.style.setProperty(prop, value, priority);
+              else el.style.removeProperty(prop);
+              el.removeAttribute(`data-ui-pptx-prev-${key}`);
+              el.removeAttribute(`data-ui-pptx-prev-${key}-priority`);
+            }
+            el.removeAttribute('data-ui-pptx-inline-hidden');
+          }
+        };
+        const forceHide = (el) => {
+          if (!el || el.nodeType !== 1 || el.getAttribute('data-pptx-export') === 'ignore') return;
+          if (el.getAttribute('data-ui-pptx-inline-hidden') !== 'true') {
+            el.setAttribute('data-ui-pptx-inline-hidden', 'true');
+            for (const prop of INLINE_PROPS) {
+              const key = prop.replace(/[^a-z]/gi, '_');
+              el.setAttribute(`data-ui-pptx-prev-${key}`, el.style.getPropertyValue(prop) || '');
+              el.setAttribute(`data-ui-pptx-prev-${key}-priority`, el.style.getPropertyPriority(prop) || '');
+            }
+          }
+          el.style.setProperty('visibility', 'hidden', 'important');
+          el.style.setProperty('opacity', '0', 'important');
+          el.style.setProperty('color', 'transparent', 'important');
+          el.style.setProperty('-webkit-text-fill-color', 'transparent', 'important');
+          el.style.setProperty('text-shadow', 'none', 'important');
+          el.style.setProperty('pointer-events', 'none', 'important');
+        };
+        const forceHideTree = (node) => {
+          forceHide(node);
+          for (const child of node.querySelectorAll?.('*') || []) forceHide(child);
+        };
+        const hideTextIn = (root) => {
+          for (const el of root.querySelectorAll([
+            '[data-pptx-auto-text]',
+            '[data-pptx-kind="text"]',
+            '[data-pptx-layer="text"]',
+          ].join(','))) {
+            forceHideTree(el);
+          }
+        };
+        restoreInlineExportStyles();
+        document.documentElement.setAttribute('data-export-mode', exportModeValue);
+        document.documentElement.setAttribute('data-ui-pptx-export', 'true');
+        // 进任意 mode 先清掉上一轮切图的 current 标记，避免残留影响可见性。
+        for (const el of document.querySelectorAll('[data-fg-current]')) {
+          el.removeAttribute('data-fg-current');
+        }
+        for (const el of document.querySelectorAll('[data-fg-child-hidden]')) {
+          el.style.visibility = el.getAttribute('data-fg-prev-visibility') || '';
+          el.removeAttribute('data-fg-prev-visibility');
+          el.removeAttribute('data-fg-child-hidden');
+        }
+        const nodes = Array.from(document.querySelectorAll(slideSelector));
+        if (nodes.length > 1) {
+          nodes.forEach((node, nodeIndex) => {
+            const shouldHide = nodeIndex !== index;
+            node.hidden = shouldHide;
+            node.setAttribute('data-ui-export-hidden', shouldHide ? 'true' : 'false');
+          });
+        } else if (nodes.length === 1) {
+          nodes[0].hidden = false;
+          nodes[0].setAttribute('data-ui-export-hidden', 'false');
+        }
+        const root = nodes.length ? nodes[index] : document.body;
+        if (exportModeValue === 'background') {
+          for (const el of root.querySelectorAll([
+            '[data-pptx-auto-fg]',
+            '[data-pptx-layer="foreground"]',
+            '[data-pptx-auto-text]',
+            '[data-pptx-kind="text"]',
+            '[data-pptx-layer="text"]',
+          ].join(','))) {
+            forceHideTree(el);
+          }
+        } else if (exportModeValue === 'foreground') {
+          hideTextIn(root);
+        } else if (exportModeValue === 'fg-cut') {
+          hideTextIn(root);
+          for (const el of root.querySelectorAll('[data-pptx-auto-text], [data-pptx-kind="text"], [data-pptx-layer="text"]')) {
+            forceHideTree(el);
+          }
+        } else if (exportModeValue === 'full') {
+          // full 态用于量几何和最终对照图，必须恢复作者原始视觉。
+          restoreInlineExportStyles();
+        }
+        window.dispatchEvent(new Event('resize'));
+        const visibleNodes = nodes.filter((node) => {
+          const style = window.getComputedStyle(node);
+          const rect = node.getBoundingClientRect();
+          return !node.hidden
+            && node.getAttribute('data-ui-export-hidden') !== 'true'
+            && style.display !== 'none'
+            && style.visibility !== 'hidden'
+            && rect.width > 1
+            && rect.height > 1;
+        });
+        return nodes.length ? visibleNodes.length : 1;
+      }, { slideSelector: selector, index: meta.index, exportMode });
+      await page.evaluate(async () => {
+        if (document.fonts?.ready) {
+          await document.fonts.ready;
+        }
+        await new Promise((resolveFrame) => requestAnimationFrame(() => requestAnimationFrame(resolveFrame)));
+      });
+      await page.waitForTimeout(120);
+      return visibleCount;
+    }
+
+    const fullVisibleCount = await prepare('full');
+    if (!measureOnly) {
+      await page.screenshot({ path: fullPath, fullPage: false });
+    }
+    // measure-only 不截图：fullInfo 用画布尺寸占位（构图量不依赖它，仅 manifest 校验用）。
+    const fullInfo = measureOnly ? { width, height, hash: '' } : await imageInfo(fullPath);
+    console.error(`[export]   slide ${meta.index + 1} ${measureOnly ? '量构图（measure-only）' : 'full 截图完成'}`);
+
+    let foreground = [];
+    let textRuns = [];
+    let hasBgImage = false;
+    let backgroundInfo = null;
+    let backgroundVisibleCount = null;
+    let bakedText = [];
+    // hybrid 走全套三层；measure-only 也抽几何（不论 mode），但跳过截图/切图。
+    if (mode === 'hybrid' || measureOnly) {
+      // 0) 自动分层打标（**必须早于背景/前景截图**）：按结构标离散块(data-pptx-auto-fg→中层切图)
+      //    与文本(data-pptx-auto-text→顶层可编辑)，背景态隐藏二者 → 底图只剩 AI 图/CSS 纯色渐变基底。
+      await prepare('full');
+      await tagLayers(page, selector, meta.index);
+
+      // 0.5) 文本夹带探针（**full 态查标注覆盖率**，与截图态无关 → 同时覆盖背景层与中层切图的夹带；
+      //      旧版只在 background 态查、看不到隐藏前景块内的文本，漏检中层切图夹带——这正是 16 页老毛病根因）。
+      bakedText = await probeBakedText(page, selector, meta.index);
+
+      // 1) 抽取三层几何（在 full 态量 bbox，layout 不受 visibility 影响）。
+      // 必须早于 background / fg-cut 截图：后续截图态需要知道哪些节点是文本、哪些节点是前景块。
+      await prepare('full');
+      const layers = await extractLayers(page, selector, meta.index);
+      foreground = layers.foregroundBlocks;
+      textRuns = layers.textRuns;
+      hasBgImage = !!layers.hasBgImage;
+
+      // hybrid 下落 3 个整文档层快照（中间产物，仅供检视；功能截图取自实时页面各 mode）。
+      // 必须在 tagLayers + extractLayers 之后生成，否则 pure-*.html 看不到 fgId 与自动分层结果，排查会被误导。
+      // 只保存首个导出页的分层 HTML 快照；每页真实截图仍由 slide-XX-*.png 与 fg 切图承担。
+      if (mode === 'hybrid' && !measureOnly && !wroteLayerSnapshots) {
+        const htmlDir = dirname(htmlPath);
+        for (const m of ['background', 'foreground', 'text']) {
+          const snapPath = resolve(workdir, `pure-${m}.html`);
+          try {
+            await prepare(m);
+            await writeLayerSnapshot(page, m, snapPath, htmlDir);
+            layerSnapshots[m] = snapPath;
+          } catch (error) {
+            layerSnapshots[m] = null;
+            consoleErrors.push(`落 pure-${m}.html 失败：${error.message}`);
+          }
+        }
+        await prepare('full');
+        wroteLayerSnapshots = true;
+      }
+
+      // 2) 纯背景整页截图（隐前景 + 隐全部文本）—— measure-only 默认跳过；
+      //    --with-bg-shots 时补拍（像素可读性门要采样文字底下的真实背景像素）。
+      backgroundVisibleCount = await prepare('background');
+      if (!measureOnly) {
+        await page.screenshot({ path: backgroundPath, fullPage: false });
+        backgroundInfo = await imageInfo(backgroundPath);
+      } else if (withBgShots) {
+        await page.screenshot({ path: backgroundPath, fullPage: false });
+      }
+      // 2.5) foreground 态整页截图（隐文字，其余原样渲染）—— 仅 measure-only + --with-bg-shots；
+      //      供像素可读性门给 fgParent 非空的文本（卡内/前景块内文字）采样真实背衬。
+      if (measureOnly && withBgShots) {
+        await prepare('foreground');
+        await page.screenshot({ path: foregroundShotPath, fullPage: false });
+        await prepare('background');
+      }
+      console.error(
+        `[export]   slide ${meta.index + 1} ${measureOnly ? '几何' : 'background 截图完成、'}前景 ${foreground.length} 块、文本 ${textRuns.length} 段`,
+      );
+
+      if (measureOnly) {
+        // 不切图，但声明的前景块都将进 PPT；标 imagePath 哨兵让 computeSlideBalance 按几何计入内容
+        //（full 导出里 imagePath 是「切图成功」证据，measure-only 用哨兵等价表达「该块占位」）。
+        for (const item of foreground) {
+          item.imagePath = '<measure-only>';
+        }
+      } else if (foreground.length) {
+        // 3) 切图态（fg-cut）逐元素切图：每块只显当前块（data-fg-current）→ omitBackground 截图 → 独立可编辑图片。
+        await prepare('fg-cut');
+        let fgIndex = 0;
+        for (const item of foreground) {
+          fgIndex += 1;
+          const fgImagePath = resolve(workdir, geometryFilename(meta.index + 1, fgIndex, item));
+          try {
+            await page.evaluate((fgId) => {
+              for (const el of document.querySelectorAll('[data-fg-child-hidden]')) {
+                el.style.visibility = el.getAttribute('data-fg-prev-visibility') || '';
+                el.removeAttribute('data-fg-prev-visibility');
+                el.removeAttribute('data-fg-child-hidden');
+              }
+              for (const el of document.querySelectorAll('[data-pptx-fg-id]')) {
+                if (el.getAttribute('data-pptx-fg-id') === fgId) {
+                  el.setAttribute('data-fg-current', 'true');
+                  for (const child of el.querySelectorAll('[data-pptx-fg-id]')) {
+                    child.setAttribute('data-fg-prev-visibility', child.style.visibility || '');
+                    child.setAttribute('data-fg-child-hidden', 'true');
+                    child.style.visibility = 'hidden';
+                  }
+                } else {
+                  el.removeAttribute('data-fg-current');
+                }
+              }
+              void document.body.offsetHeight; // 强制同步重排，确保 data-fg-current 引发的样式重算立即生效
+            }, item.fgId);
+            // 消竞态（治偶发「文字还没隐藏就被切进图」=中层切图残留文字）：文本已由 fg-cut 全局规则一次性隐藏、
+            // 全程不变（见 exportCss）；这里再等字体就绪 + 2 帧 + 80ms，保证当前块内容重绘落定再截图。
+            await page.evaluate(async () => {
+              if (document.fonts?.ready) await document.fonts.ready;
+              await new Promise((r) => requestAnimationFrame(() => requestAnimationFrame(r)));
+            });
+            await page.waitForTimeout(80);
+            await page.screenshot({
+              path: fgImagePath,
+              clip: {
+                x: Math.max(0, item.x),
+                y: Math.max(0, item.y),
+                width: Math.max(1, Math.min(item.w, width - Math.max(0, item.x))),
+                height: Math.max(1, Math.min(item.h, height - Math.max(0, item.y))),
+              },
+              omitBackground: true,
+            });
+            if (item.needsAlphaMask) {
+              item.alphaMaskApplied = await transparentizeCornerBackground(fgImagePath, nodeModules);
+            }
+            item.imagePath = fgImagePath;
+            item.imageFile = basename(fgImagePath);
+          } catch (error) {
+            item.imageError = error.message;
+          }
+        }
+        await prepare('full'); // prepare 会清掉 data-fg-current
+      }
+    }
+
+    // 讲稿（speaker notes）：build 步按 design.speaker_notes 写入 <aside class="speaker-notes" hidden>。
+    // display:none 不渲染、不进 textRuns/前景切图；此处取纯文本 → createPptx 写进 PPT 备注栏（演讲者视图）。
+    // 无 aside 的 deck（webppt/旧产物）取到空串，导出行为与现状一致。
+    const speakerNotes = await page.evaluate(({ slideSelector, slideIndex, fallback }) => {
+      const node = fallback
+        ? document.body
+        : Array.from(document.querySelectorAll(slideSelector))[slideIndex];
+      const aside = node && node.querySelector && node.querySelector('aside.speaker-notes');
+      if (!aside) return '';
+      return (aside.textContent || '').replace(/[ \t]+/g, ' ').replace(/\s*\n\s*/g, '\n').trim();
+    }, { slideSelector: selector, slideIndex: meta.index, fallback: meta.fallback });
+
+    slides.push({
+      ...meta,
+      fullPath,
+      backgroundPath: mode === 'hybrid' ? backgroundPath : null,
+      fullInfo,
+      backgroundInfo,
+      fullVisibleCount,
+      backgroundVisibleCount,
+      hasBgImage,
+      foreground,
+      textRuns,
+      bakedText,
+      speakerNotes,
+    });
+  }
+
+  await browser.close();
+  const validationErrors = [];
+  const validationWarnings = [];
+  const hashGroups = new Map();
+  // measure-only 不产截图，跳过所有截图相关校验（占位 hash 全为空会误报「重复截图」）。
+  if (!measureOnly) for (const slide of slides) {
+    if (slide.fullVisibleCount !== 1) {
+      validationErrors.push(`${slide.label} 导出 full 截图时可见 slide 数量为 ${slide.fullVisibleCount}，应该为 1。`);
+    }
+    if (slide.fullInfo.width !== width || slide.fullInfo.height !== height) {
+      validationErrors.push(`${slide.label} full 截图尺寸为 ${slide.fullInfo.width}x${slide.fullInfo.height}，应该为 ${width}x${height}。`);
+    }
+    if (mode === 'hybrid') {
+      if (slide.backgroundVisibleCount !== 1) {
+        validationErrors.push(`${slide.label} 导出 background 截图时可见 slide 数量为 ${slide.backgroundVisibleCount}，应该为 1。`);
+      }
+      if (slide.bakedText?.length) {
+        const samples = slide.bakedText
+          .slice(0, 4)
+          .map((item) => `「${String(item.text || '').slice(0, 24)}」/${item.source || 'text'}`)
+          .join('、');
+        validationErrors.push(
+          `${slide.label} 检测到 ${slide.bakedText.length} 段 HTML/SVG/伪元素文字会被截图夹带：${samples}。`
+          + '这会导致图片文字不可编辑并与 PPT 文本层重影，必须先修 HTML 分层或用 data-pptx-export="ignore" 明确保留。',
+        );
+      }
+      if (slide.backgroundInfo?.hash === slide.fullInfo.hash) {
+        const riskyText = hasVisibleTextRisk(slide.textRuns || []);
+        const riskyForeground = (slide.foreground || []).some((item) =>
+          !['img', 'svg', 'canvas', 'video', 'picture'].includes(String(item.tag || '').toLowerCase()));
+        const hasEditableLayers = riskyText || riskyForeground;
+        const message = `${slide.label} background 截图与 full 截图完全相同，说明文本/前景没有从截图层剥离。`;
+        if (hasEditableLayers) {
+          const textClause = riskyText
+            ? `本页有 ${slide.textRuns?.length || 0} 段可能可见文本`
+            : '本页主要风险来自非媒体类前景块';
+          validationErrors.push(`${message} ${textClause}、${slide.foreground?.length || 0} 个前景块；继续导出可能造成图片文字/前景与 PPT 顶层重影，已阻断。`);
+        } else {
+          validationWarnings.push(`${message} 但未检测到可见文本风险，可能是纯色/透明测试页。`);
+        }
+      }
+      for (const item of slide.foreground) {
+        if (item.imageError) {
+          validationWarnings.push(`${slide.label} 前景块 ${item.fgId} 元素截图失败：${item.imageError}（该块未插入）。`);
+        }
+      }
+    }
+    const group = hashGroups.get(slide.fullInfo.hash) || [];
+    group.push(slide.label);
+    hashGroups.set(slide.fullInfo.hash, group);
+  }
+  for (const labels of hashGroups.values()) {
+    if (labels.length > 1 && slides.length > 1) {
+      validationErrors.push(`检测到重复截图 hash：${labels.join('、')} 完全相同。`);
+    }
+  }
+  return { slides, consoleErrors, validationErrors, validationWarnings, layerSnapshots };
+}
+
+// 自动分层打标（**必须在任何截图前跑**）：按结构把一页分成三层，不再依赖作者逐个标注——
+// 标注漏一个，过去就会烧进底图、不可编辑（真机：序号/方框/色块/选项卡进底图、卡内文字烧死）。
+//   ① 前景（中层）：离散视觉块——replaced 内容（img/svg/canvas/video）或有「盒样式」（实色底/位图底/
+//      边框/阴影/圆角实色）的块，且**非全幅**（全幅=页/章节基底，留背景）、**够大**（滤掉点/线装饰）。
+//      打 data-pptx-auto-fg；去嵌套（命中即停，内层块烘进外层切图）。每块按 HTML 元素范围单独切图、
+//      可在 PPT 单独拖拽/复制/删除。**显式 data-pptx-layer="foreground" 一律视为块（用户 override）。**
+//   ② 文本（顶层）：「有文字 && 子元素全行内」的最紧容器 → 永远提成可编辑框、永不烧进图。
+//      纯文本元素整体打 data-pptx-auto-text；**带盒样式的 chip（如药丸 .card-tag）则把文字搬进内层
+//      span[data-pptx-auto-text]**——这样切图里 chip 底色还在、只有文字被隐藏并提到顶层（修「色块上面
+//      文字」分层不清：过去整 chip 被当文本隐藏，连底色一起丢）。SVG `<text>` 各成一段。
+//   ③ 背景（底层）：其余一切——AI 底图、CSS 纯色/透明/渐变页级背景、scrim、纯布局空壳——整页截图垫底。
+//   data-pptx-export="ignore" 子树全程跳过（显式保留烧进图，如嵌进图形的艺术字）。
+async function tagLayers(page, selector, index) {
+  return page.evaluate(({ slideSelector, slideIndex }) => {
+    const slideNodes = Array.from(document.querySelectorAll(slideSelector));
+    const root = slideNodes.length ? slideNodes[slideIndex] : document.body;
+    const rootRect = root.getBoundingClientRect();
+    const SLIDE_W = rootRect.width || window.innerWidth;
+    const SLIDE_H = rootRect.height || window.innerHeight;
+
+    const INLINE = /^(inline|inline-block|inline-flex|inline-grid|contents|ruby)/;
+    const norm = (s) => (s || '').replace(/\s+/g, ' ').trim();
+    const isSvgNs = (el) => el.namespaceURI === 'http://www.w3.org/2000/svg';
+    const isIgnored = (el) => el.getAttribute && el.getAttribute('data-pptx-export') === 'ignore';
+    const isMarkedFg = (el) => el.getAttribute && el.getAttribute('data-pptx-layer') === 'foreground';
+    const NON_CONTENT_TAGS = new Set([
+      'SCRIPT', 'STYLE', 'TEMPLATE', 'NOSCRIPT',
+      'HEAD', 'TITLE', 'META', 'LINK', 'BASE',
+    ]);
+    const isNonContent = (el) => {
+      if (!el || el.nodeType !== 1) return false;
+      const tag = (el.tagName || '').toUpperCase();
+      return NON_CONTENT_TAGS.has(tag) || !!el.closest?.('script,style,template,noscript,head,title,meta,link,base');
+    };
+    const REPLACED = new Set(['IMG', 'SVG', 'CANVAS', 'VIDEO', 'PICTURE']);
+    const isReplaced = (el) => REPLACED.has((el.tagName || '').toUpperCase());
+
+    function visible(el, style, rect) {
+      return style.display !== 'none' && style.visibility !== 'hidden'
+        && rect.width > 1 && rect.height > 1;
+    }
+    function allChildrenInline(el) {
+      for (const c of el.children) {
+        if (!INLINE.test(getComputedStyle(c).display)) return false;
+      }
+      return true;
+    }
+    function bgAlpha(c) {
+      const m = /rgba?\(([^)]+)\)/.exec(c || '');
+      if (!m) return c && c !== 'transparent' ? 1 : 0;
+      const p = m[1].split(',');
+      return p.length >= 4 ? parseFloat(p[3]) : 1;
+    }
+    // 「盒样式」= 实色底 / 位图或渐变底 / 可见边框 / 阴影。背景裁切到文字（背景渐变当字色）不算盒。
+    function hasBoxStyling(style) {
+      const clipText = style.webkitBackgroundClip === 'text' || style.backgroundClip === 'text';
+      const bgImg = !clipText && style.backgroundImage && style.backgroundImage !== 'none';
+      const opaqueBg = bgAlpha(style.backgroundColor) > 0.1;
+      const shadow = style.boxShadow && style.boxShadow !== 'none';
+      const border = ['Top', 'Right', 'Bottom', 'Left'].some((s) =>
+        parseFloat(style['border' + s + 'Width']) > 0 && style['border' + s + 'Style'] !== 'none');
+      return bgImg || opaqueBg || shadow || border;
+    }
+    const isFullBleed = (rect) => rect.width >= SLIDE_W * 0.9 && rect.height >= SLIDE_H * 0.9;
+    const sizeOK = (rect) => Math.min(rect.width, rect.height) >= 24 && rect.width * rect.height >= 2500;
+
+    // 一个元素是否「够格做独立切图块」（replaced 图，或盒样式块），且非全幅、够大。
+    function isBlockEl(el) {
+      if (!el || el.nodeType !== 1 || isIgnored(el)) return false;
+      const t = el.tagName;
+      if (isNonContent(el) || isSvgNs(el)) return false;
+      const s = getComputedStyle(el);
+      const r = el.getBoundingClientRect();
+      if (!visible(el, s, r)) return false;
+      if (isReplaced(el)) return !isFullBleed(r) && sizeOK(r);
+      return hasBoxStyling(s) && !isFullBleed(r) && sizeOK(r);
+    }
+    // 数 el 子树里「最外层」的独立块后代个数（命中块即不再深入，透过非块容器继续数）：
+    // ≥2 → el 是「底板 plate」（递归切其子块）；≤1 → el 叶子整切（防过碎，原行为）。
+    function blockKidCount(el) {
+      let n = 0;
+      for (const c of el.children) {
+        if (c.nodeType !== 1 || isIgnored(c)) continue;
+        if (isBlockEl(c)) n += 1;        // 最外层块 → 计 1、不深入（c 内更深的块归 c 自己决策）
+        else n += blockKidCount(c);      // 非块容器（透明 wrapper/grid）→ 透传其内最外层块数
+      }
+      return n;
+    }
+
+    let fgCount = 0;
+    let textCount = 0;
+
+    // ── 趟 1：标离散块（中层）——按 HTML 结构「递归切到底」：底板 plate 标记后继续切其子块 ──
+    function walkFg(el) {
+      if (!el || el.nodeType !== 1 || isIgnored(el)) return;
+      if (isNonContent(el)) return;
+      const style = getComputedStyle(el);
+      const rect = el.getBoundingClientRect();
+      if (!visible(el, style, rect)) return;
+      if (isMarkedFg(el)) return; // 显式前景：用户 override=整切，停（extractLayers 对显式祖先去嵌套）
+      if (isReplaced(el)) {
+        if (!isFullBleed(rect) && sizeOK(rect)) { el.setAttribute('data-pptx-auto-fg', '1'); fgCount += 1; }
+        return; // svg/img 是叶子、整切不拆（矢量/位图无法拆节点）；svg <text> 由趟2提取
+      }
+      if (isSvgNs(el)) return;
+      if (hasBoxStyling(style) && !isFullBleed(rect) && sizeOK(rect)) {
+        el.setAttribute('data-pptx-auto-fg', '1');
+        fgCount += 1;
+        // ≥2 个独立块后代 → 这是底板 plate：继续递归把子块各自标成块（可多层嵌套）。
+        // 切图时 fg-cut CSS 会在切 plate 时隐藏其后代切图块 → plate 只含自身底色/边框，子块各自切、零重复。
+        // ≤1 → 叶子，整切（命中即停，防过碎；单子块的卡照旧吸收）。
+        if (blockKidCount(el) >= 2) {
+          for (const c of el.children) walkFg(c);
+        }
+        return;
+      }
+      for (const c of el.children) walkFg(c);
+    }
+    for (const c of root.children) walkFg(c);
+
+    // ── 趟 2：标/包裹文本（顶层）──
+    // SVG <text> 各成一段（不下探 tspan）。
+    for (const t of root.querySelectorAll('svg text')) {
+      if ((t.closest && t.closest('[data-pptx-export="ignore"]')) || isNonContent(t) || !norm(t.textContent)) continue;
+      t.setAttribute('data-pptx-auto-text', '1');
+      textCount += 1;
+    }
+    function wrapText(el) {
+      // 把 el 的子节点搬进 inline span[data-pptx-auto-text]：chip 底色留在 el、文字交给 span（可隐藏/提取）。
+      if (el.querySelector('[data-pptx-auto-text]')) return;
+      const span = document.createElement('span');
+      span.setAttribute('data-pptx-auto-text', '1');
+      span.style.display = 'inline';
+      while (el.firstChild) span.appendChild(el.firstChild);
+      el.appendChild(span);
+    }
+    function wrapStrayTextNodes(el) {
+      // 把 el 的【直接挂的】非空文本节点各包进 inline span[data-pptx-auto-text]：
+      // 图标/媒体或块级元素与文字混排时（如选项卡 <div><svg/>概览</div>、标签 <div><i></i>新功能</div>），
+      // 这些裸文本既非元素子（walkText 的 el.children 遍历不到）、又因 hasMedia 跳过整体提取 → 过去烧进切图、不可编辑。
+      // 这里把它们提到顶层可编辑文本，不影响同级图标/媒体（仍各自成块切图）。
+      for (const node of Array.from(el.childNodes)) {
+        if (node.nodeType === 3 && norm(node.textContent)) { // TEXT_NODE 且有可见文字
+          if (isNonContent(node.parentElement)) continue;
+          const span = document.createElement('span');
+          span.setAttribute('data-pptx-auto-text', '1');
+          span.style.display = 'inline';
+          el.insertBefore(span, node);
+          span.appendChild(node);
+          textCount += 1;
+        }
+      }
+    }
+    function walkText(el) {
+      if (!el || el.nodeType !== 1 || isIgnored(el)) return;
+      if (el.getAttribute('data-pptx-auto-text') === '1') return; // 已提取（防御 + 不重复处理新插的 span）
+      if (isNonContent(el)) return;
+      if (isSvgNs(el)) return; // svg <text> 已处理
+      const style = getComputedStyle(el);
+      const rect = el.getBoundingClientRect();
+      if (!visible(el, style, rect)) return;
+      const hasMedia = !!el.querySelector('img, svg, canvas, video, picture');
+      if (norm(el.textContent) && allChildrenInline(el) && !hasMedia) {
+        if (hasBoxStyling(style)) {
+          wrapText(el); // 带底色的 chip：文字进内层 span，底色留 el（切图保留底色、文字提顶层）
+        } else {
+          el.setAttribute('data-pptx-auto-text', '1'); // 纯文本：整体提为可编辑框
+        }
+        textCount += 1;
+        return; // 命中即停
+      }
+      // 混排（含媒体/块级子，未整体命中）：先提本元素【直接挂的】裸文本（图标+文字、容器直挂的说明），
+      // 再下探【原有】元素子（快照，避免把刚插入的 auto-text span 又处理一遍）。
+      const elemChildren = Array.from(el.children);
+      wrapStrayTextNodes(el);
+      for (const c of elemChildren) walkText(c);
+    }
+    for (const c of root.children) walkText(c);
+
+    // ── 趟 2.5 兜底（穷尽标注）：凡 root 下仍未被 auto-text 覆盖的可见文本节点，一律包进 span[data-pptx-auto-text]。
+    // 堵 walkText 条件分支可能漏标的边角（深层混排/异常结构）→ 保证「任何截图（背景/中层切图）都绝不夹带 HTML 文本」。
+    // svg <text> 已在趟 2 标过（其文本节点的 closest auto-text 命中）；ignore 子树显式保留烧图，跳过。
+    const strayNodes = [];
+    const walker = document.createTreeWalker(root, NodeFilter.SHOW_TEXT, null);
+    let tnode;
+    while ((tnode = walker.nextNode())) {
+      if (!norm(tnode.textContent)) continue;
+      const el = tnode.parentElement;
+      if (!el || isSvgNs(el) || isNonContent(el)) continue;
+      if (el.closest('[data-pptx-auto-text]') || el.closest('[data-pptx-export="ignore"]')) continue;
+      const st = getComputedStyle(el);
+      const r = el.getBoundingClientRect();
+      if (!visible(el, st, r)) continue;
+      strayNodes.push(tnode);
+    }
+    for (const tnode of strayNodes) {
+      const span = document.createElement('span');
+      span.setAttribute('data-pptx-auto-text', '1');
+      span.style.display = 'inline';
+      tnode.parentNode.insertBefore(span, tnode);
+      span.appendChild(tnode);
+      textCount += 1;
+    }
+
+    return { fgCount, textCount };
+  }, { slideSelector: selector, slideIndex: index });
+}
+
+// 文本夹带探针（**在 full 态调，查「标注覆盖率」——与具体截图态无关，故同时覆盖背景层与中层切图**）：
+// 不变量「标了 data-pptx-auto-text 的文本在 background / fg-cut 两态都被隐藏 → 不会烧进任何截图；没标且可见的文本
+// 必会烧进某张截图（背景层 或 它所在前景块的中层切图）」。所以只需查：root 下**有没有可见、却未被 auto-text 覆盖、
+// 且不在 ignore 子树**的文本——有就是会夹带（旧版只在 background 态查，看不到隐藏的前景块内文本 → 漏检中层切图夹带）。
+//   ① 真实 DOM 文本节点：未被 auto-text 覆盖（tagLayers 漏标，含前景块内的）→ 会烧进图。
+//   ② `::before/::after` 伪元素可读文字 = 无法标注/隐藏/提取，**必**烧进图（应改成真实 DOM 文本）。
+// ignore 子树（data-pptx-export="ignore"）是显式保留烧图（如嵌图形的艺术字），跳过。AI `<img>` 无文本节点、不误报。
+// 返回归一化坐标，挂到 slide.bakedText → computeSlideBalance 透传 → layout_balance.py 报 ERROR。
+async function probeBakedText(page, selector, index) {
+  return page.evaluate(({ slideSelector, slideIndex }) => {
+    const slideNodes = Array.from(document.querySelectorAll(slideSelector));
+    const root = slideNodes.length ? slideNodes[slideIndex] : document.body;
+    const vw = window.innerWidth;
+    const vh = window.innerHeight;
+    const norm = (s) => (s || '').replace(/\s+/g, ' ').trim();
+    const nrect = (r) => ({
+      x: Math.round((r.left / vw) * 1000) / 1000,
+      y: Math.round((r.top / vh) * 1000) / 1000,
+      w: Math.round((r.width / vw) * 1000) / 1000,
+      h: Math.round((r.height / vh) * 1000) / 1000,
+    });
+    // full 态可见 = 渲染出非零区域且在视口内（不看 visibility——查的是「未隐藏前是否有这段文本」）。
+    const isShown = (el) => {
+      const st = getComputedStyle(el);
+      if (st.display === 'none' || parseFloat(st.opacity) === 0) return false;
+      const r = el.getBoundingClientRect();
+      return r.width > 1 && r.height > 1 && r.right > 0 && r.bottom > 0 && r.left < vw && r.top < vh;
+    };
+    const covered = (el) =>
+      el.closest('[data-pptx-auto-text]') || el.closest('[data-pptx-export="ignore"]');
+    const out = [];
+    const seen = new Set();
+    // ① 未被 auto-text 覆盖的可见真实文本节点（含前景块内的 → 会烧进中层切图）。
+    const walker = document.createTreeWalker(root, NodeFilter.SHOW_TEXT, null);
+    let node;
+    while ((node = walker.nextNode())) {
+      const t = norm(node.textContent);
+      if (!t) continue;
+      const el = node.parentElement;
+      if (!el || covered(el) || !isShown(el)) continue;
+      const r = el.getBoundingClientRect();
+      const key = `${t}@${Math.round(r.left)},${Math.round(r.top)}`;
+      if (seen.has(key)) continue;
+      seen.add(key);
+      out.push({ text: t.slice(0, 24), source: 'dom', rect: nrect(r) });
+    }
+    // ② ::before/::after 伪元素的可读文字（仅抓含字母/数字/CJK 且 ≥2 字符的真实文字，放过 •·—→ 等装饰符号）。
+    for (const el of [root, ...root.querySelectorAll('*')]) {
+      if (el.closest('[data-pptx-export="ignore"]') || !isShown(el)) continue;
+      for (const pe of ['::before', '::after']) {
+        const c = getComputedStyle(el, pe).content;
+        if (!c || c === 'none' || c === 'normal') continue;
+        const m = /^["'](.*)["']$/.exec(c);
+        const txt = m ? norm(m[1]) : '';
+        if (txt.length < 2 || !/[\p{L}\p{N}]/u.test(txt)) continue;
+        out.push({ text: txt.slice(0, 24), source: 'pseudo', rect: nrect(el.getBoundingClientRect()) });
+      }
+    }
+    return out.slice(0, 12);
+  }, { slideSelector: selector, slideIndex: index });
+}
+
+// 抽取三层几何：
+//   foregroundBlocks —— 最外层 foreground（祖先链无另一 foreground，去嵌套），打稳定 fgId 供 locator。
+//   textRuns         —— 最外层 text（data-pptx-kind="text" 或 data-pptx-layer="text"），带文字与样式。
+// 几何用 raw getBoundingClientRect（不做视口钳制 → 切图与摆放同源一致；isVisible 仅做相交门控）。
+async function extractLayers(page, selector, index) {
+  return page.evaluate(({ slideSelector, slideIndex }) => {
+    const slideNodes = Array.from(document.querySelectorAll(slideSelector));
+    const root = slideNodes.length ? slideNodes[slideIndex] : document.body;
+    const viewport = { width: window.innerWidth, height: window.innerHeight };
+
+    function isVisible(node, rect, style) {
+      return rect.width > 1
+        && rect.height > 1
+        && rect.right > 0
+        && rect.bottom > 0
+        && rect.left < viewport.width
+        && rect.top < viewport.height
+        && style.visibility !== 'hidden'
+        && style.display !== 'none'
+        && node.getAttribute('data-pptx-export') !== 'ignore';
+    }
+
+    const isText = (node) => node.getAttribute('data-pptx-kind') === 'text'
+      || node.getAttribute('data-pptx-layer') === 'text';
+    // 只对**显式** data-pptx-layer="foreground" 祖先去嵌套（用户 override=整切，子块烘进它）；
+    // auto-fg 之间的嵌套**保留**（递归切图：plate 与子块各自成块、各自 fgId、切 plate 时隐后代块）。
+    const isExplicitFg = (node) => node.getAttribute('data-pptx-layer') === 'foreground';
+
+    // 去嵌套：node 的祖先链（到 root 为止）里是否已有同类标注元素。
+    function hasAncestorMatching(node, predicate) {
+      let parent = node.parentElement;
+      while (parent && parent !== root.parentElement) {
+        if (parent === root) return false;
+        if (predicate(parent)) return true;
+        parent = parent.parentElement;
+      }
+      return false;
+    }
+
+    // --- 前景块：最外层 foreground（显式 layer="foreground" ∪ tagLayers 自动标的 auto-fg）---
+    const fgCandidates = Array.from(
+      root.querySelectorAll('[data-pptx-layer="foreground"], [data-pptx-auto-fg]'),
+    );
+    const foregroundBlocks = [];
+    let nodeIndex = 0;
+    for (const node of fgCandidates) {
+      const rect = node.getBoundingClientRect();
+      const style = getComputedStyle(node);
+      if (!isVisible(node, rect, style)) continue;
+      // 文本优先：标了 text 或被 tagLayers 认成纯文本 run 的元素归文本层（顶层原生框），不当前景切图。
+      if (isText(node) || node.getAttribute('data-pptx-auto-text') === '1') continue;
+      if (hasAncestorMatching(node, isExplicitFg)) continue; // 仅显式 foreground 祖先去嵌套；auto-fg 嵌套保留（递归切）
+      const fgId = `fg-${slideIndex}-${nodeIndex}`;
+      nodeIndex += 1;
+      node.setAttribute('data-pptx-fg-id', fgId);
+      // hasMedia：块内有「实质视觉填充」→ 是「媒体/图显卡」，空心卡片闸门豁免它（视觉在填版面、文字少属正常）；
+      // 纯文本框/色块卡（无视觉填充）才量文字填充率。视觉填充 = 含 img/svg/canvas/video/底图，
+      // **或含一个覆盖 ≥40% 卡面积的带样式子块**（如深色 code-block、内嵌图显示区——只数文字会误判其为空心）。
+      // 注意：只看**子块**的样式底，卡自身的纯色底不算（白卡装一句话正是要抓的空心）；卡内小药丸/标签太小不触发。
+      const cardArea = rect.width * rect.height;
+      const _alpha = (c) => {
+        const m = /rgba?\(([^)]+)\)/.exec(c || '');
+        if (!m) return c && c !== 'transparent' ? 1 : 0;
+        const p = m[1].split(',');
+        return p.length >= 4 ? parseFloat(p[3]) : 1;
+      };
+      const _boxFill = (s) => /url\(/i.test(s.backgroundImage) || _alpha(s.backgroundColor) > 0.1
+        || (s.boxShadow && s.boxShadow !== 'none')
+        || ['Top', 'Right', 'Bottom', 'Left'].some((k) =>
+          parseFloat(s['border' + k + 'Width']) > 0 && s['border' + k + 'Style'] !== 'none');
+      let bigInnerVisual = false;
+      for (const d of node.querySelectorAll('*')) {
+        if (d.getAttribute('data-pptx-auto-text') === '1') continue; // 文字不算视觉填充
+        const ds = getComputedStyle(d);
+        if (ds.display === 'none' || ds.visibility === 'hidden' || !_boxFill(ds)) continue;
+        const dr = d.getBoundingClientRect();
+        if (dr.width * dr.height >= cardArea * 0.4) { bigInnerVisual = true; break; }
+      }
+      const hasMedia = !!node.querySelector('img, svg, canvas, video, picture')
+        || /url\(/i.test(style.backgroundImage)
+        || bigInnerVisual;
+      const radiusText = [
+        style.borderTopLeftRadius,
+        style.borderTopRightRadius,
+        style.borderBottomRightRadius,
+        style.borderBottomLeftRadius,
+      ].join(' ');
+      const needsAlphaMask = radiusText !== '0px 0px 0px 0px'
+        || (style.clipPath && style.clipPath !== 'none')
+        || (style.webkitClipPath && style.webkitClipPath !== 'none');
+      // sourceFile（加性字段）：客户图溯源。优先 data-source-file（少数页会标），
+      // 真机绝大多数页未标注此属性——回落取内部 <img> 的 src 文件名（如
+      // "assets/enhanced_src_8.png" → "enhanced_src_8.png"，Python 侧再按 stem 去
+      // "enhanced_" 前缀比对，与 source_usage_check.py::_derived_candidates 同一套约定）。
+      // 供 layout_balance --ppt-strict 的 min_canvas_fraction 检查反查真实渲染槽位宽度
+      // 是否达标（webppt 无客户图/无 source_layout_plan.json，此字段恒 null 不影响其行为）。
+      const sourceImg = node.matches('img') ? node : node.querySelector('img');
+      const sourceFile = node.getAttribute('data-source-file')
+        || sourceImg?.getAttribute('data-source-file')
+        || (sourceImg?.getAttribute('src') ? sourceImg.getAttribute('src').split('/').pop() : null)
+        || null;
+      foregroundBlocks.push({
+        fgId,
+        x: rect.left,
+        y: rect.top,
+        w: rect.width,
+        h: rect.height,
+        tag: node.tagName.toLowerCase(),
+        kind: node.getAttribute('data-pptx-kind') || null,
+        hasMedia,
+        needsAlphaMask,
+        sourceFile,
+      });
+    }
+
+    // --- 文本段：tagAutoText 已按结构打全 data-pptx-auto-text（含 SVG <text>），这里只取几何+样式 ---
+    const isAutoText = (node) => node.getAttribute('data-pptx-auto-text') === '1';
+    // 解析文本背后的「有效背景色」（供对比度门）：向上找第一个不透明 backgroundColor 的祖先——
+    // 白卡上的字→白卡色、深底页直接字→页底深色；纯渐变(无不透明底)继续上找（渐变多是 tint）；
+    // 位图底(AI 图)解析不出纯色→低置信(bgSolid=false，闸门只 WARNING 不误杀)；走到根回退 body 底色。
+    const _bgAlpha = (c) => {
+      const m = /rgba?\(([^)]+)\)/.exec(c || '');
+      if (!m) return c && c !== 'transparent' ? 1 : 0;
+      const p = m[1].split(',');
+      return p.length >= 4 ? parseFloat(p[3]) : 1;
+    };
+    const resolveBg = (el) => {
+      let p = el;
+      while (p && p !== document.documentElement) {
+        const s = getComputedStyle(p);
+        if (_bgAlpha(s.backgroundColor) > 0.5) return { color: s.backgroundColor, solid: true };
+        if (s.backgroundImage && s.backgroundImage !== 'none' && !/gradient/i.test(s.backgroundImage)) {
+          return { color: null, solid: false }; // 位图底（AI 图）→ 解析不出纯色
+        }
+        p = p.parentElement;
+      }
+      const bs = getComputedStyle(document.body);
+      return { color: _bgAlpha(bs.backgroundColor) > 0.5 ? bs.backgroundColor : 'rgb(255,255,255)', solid: true };
+    };
+    const textNodes = Array.from(root.querySelectorAll('[data-pptx-auto-text]'));
+    const textRuns = [];
+    for (const node of textNodes) {
+      const rect = node.getBoundingClientRect();
+      const style = getComputedStyle(node);
+      if (!isVisible(node, rect, style)) continue;
+      // 讲稿 aside（display:none，isVisible 已天然排除）——显式再拦一道，保证讲稿绝不变成幻灯片上的文本框。
+      if (node.closest && node.closest('aside.speaker-notes')) continue;
+      // 打标已保证 run 间不嵌套；防御性再去一次（极端手写 HTML）。
+      if (hasAncestorMatching(node, isAutoText)) continue;
+      const text = (node.getAttribute('aria-label') || node.textContent || '').replace(/\s+/g, ' ').trim();
+      if (!text) continue;
+      const isSvgText = node.namespaceURI === 'http://www.w3.org/2000/svg';
+      let fontSize = Number.parseFloat(style.fontSize) || 16;
+      let align = style.textAlign;
+      let color = style.color;
+      let fontWeight = style.fontWeight;
+      if (isSvgText) {
+        // SVG 字号是 user-unit，须乘 viewBox→视口缩放才是视觉像素；text-anchor 决定对齐；颜色取 fill。
+        const ownerSvg = node.ownerSVGElement || (node.closest && node.closest('svg'));
+        let scale = 1;
+        if (ownerSvg && ownerSvg.viewBox && ownerSvg.viewBox.baseVal && ownerSvg.viewBox.baseVal.height > 0) {
+          const svgRect = ownerSvg.getBoundingClientRect();
+          if (svgRect.height > 0) scale = svgRect.height / ownerSvg.viewBox.baseVal.height;
+        }
+        fontSize *= scale;
+        const anchor = style.textAnchor || node.getAttribute('text-anchor') || 'start';
+        align = anchor === 'middle' ? 'center' : anchor === 'end' ? 'right' : 'left';
+        color = style.fill || style.color;
+        fontWeight = style.fontWeight || node.getAttribute('font-weight') || '400';
+      }
+      // 溢出量（像素）：内容比框高/宽出多少——HTML 受限框（fixed height + overflow）才 >0，
+      // SVG/内容自适应框为 0。供构图闸门「文本溢出」硬门用（HTML 阶段就保证装得下，导出不靠缩字）。
+      const overflow = Math.max(
+        0,
+        (node.scrollHeight || 0) - (node.clientHeight || 0),
+        (node.scrollWidth || 0) - (node.clientWidth || 0),
+      );
+      // 文本所属前景块（如 SVG 图框/卡片）：同一前景块内的文本互相重叠是「图内固有间距」（如
+      // 架构图标签密排），不算缺陷 → 闸门豁免同 fgParent 的 text-text 重叠（跨块/无块的真重叠仍报）。
+      const fgAnc = node.closest && node.closest('[data-pptx-fg-id]');
+      const fgParent = fgAnc ? fgAnc.getAttribute('data-pptx-fg-id') : null;
+      const bg = resolveBg(node);
+      textRuns.push({
+        text,
+        x: rect.left,
+        y: rect.top,
+        w: rect.width,
+        h: rect.height,
+        fontSize,
+        lineHeight: Number.parseFloat(style.lineHeight) || null,
+        letterSpacing: Number.parseFloat(style.letterSpacing) || null, // normal/0 → null（不强加字距）
+        fontWeight,
+        fontFamily: style.fontFamily,
+        color,
+        bgColor: bg.color,
+        bgSolid: bg.solid,
+        textAlign: align,
+        overflow,
+        fgParent,
+      });
+    }
+
+    // --- 是否有「真实图片填满背景」（B 路线全幅氛围图 / 大幅未标 foreground 的 <img>）---
+    // 用于构图闸门区分「靠大图铺满的稀疏文字页（合法）」与「纯文字/卡片却空半的页（缺陷）」。
+    // 渐变/纯色背景不算（只认 url(...) 的位图与足够大的裸 <img>）。
+    let hasBgImage = false;
+    const bgScan = [root, ...root.querySelectorAll('*')];
+    for (const el of bgScan) {
+      const bg = getComputedStyle(el).backgroundImage;
+      if (bg && /url\(/i.test(bg)) { hasBgImage = true; break; }
+    }
+    if (!hasBgImage) {
+      const rootR = root.getBoundingClientRect();
+      const tolX = rootR.width * 0.02;
+      const tolY = rootR.height * 0.02;
+      for (const img of root.querySelectorAll('img')) {
+        let p = img;
+        let inFg = false;
+        while (p && p !== root.parentElement) {
+          if (p.getAttribute && p.getAttribute('data-pptx-layer') === 'foreground') { inFg = true; break; }
+          p = p.parentElement;
+        }
+        if (inFg) continue; // A 路线插图已算前景，不算背景
+        const r = img.getBoundingClientRect();
+        if (!(r.width > 200 && r.height > 200)) continue;
+        // Gap A 修复（s5/s9/s10 事故）：撑爆 grid/flex 轨道或越出画布的大图**不是背景**，而是布局缺陷本身
+        //（.fig-contain 内 <img> 无 min-width:0，原始像素撑爆 .85fr 轨道，图与内容一起被挤出画布）。
+        // 真背景图应铺在页内、不显著超出画布或其容器 —— 越界的大图若被误当"有背景"，会让 layout_balance
+        // 据此把"内容全飞出的空页"误判为"纯图封面"降级放行（Gap B）。故此处排除越界大图，不计为背景。
+        const overflowsCanvas =
+          r.width > rootR.width + tolX ||
+          r.height > rootR.height + tolY ||
+          r.left < rootR.left - tolX ||
+          r.top < rootR.top - tolY ||
+          r.right > rootR.right + tolX ||
+          r.bottom > rootR.bottom + tolY;
+        if (overflowsCanvas) continue;
+        hasBgImage = true;
+        break;
+      }
+    }
+
+    return { foregroundBlocks, textRuns, hasBgImage };
+  }, { slideSelector: selector, slideIndex: index });
+}
+
+async function createPptx({ PptxGenJS, slides, outPath, mode, width, height }) {
+  const pptx = new PptxGenJS();
+  pptx.author = 'ui-design export-pptx';
+  pptx.subject = 'ui-design HTML 导出（三层：背景/前景/文本）';
+  pptx.title = basename(outPath, extname(outPath));
+  pptx.company = 'ui-design';
+  pptx.lang = 'zh-CN';
+  pptx.defineLayout({ name: 'UI_DESIGN_16_9', width: SLIDE_W, height: SLIDE_H });
+  pptx.layout = 'UI_DESIGN_16_9';
+  pptx.theme = {
+    headFontFace: CJK_FALLBACK,
+    bodyFontFace: CJK_FALLBACK,
+    lang: 'zh-CN',
+  };
+
+  for (const item of slides) {
+    const slide = pptx.addSlide();
+    slide.background = { color: 'FFFFFF' };
+    // ① 背景：底图整页（flat 用 full 整图，hybrid 用纯背景截图）。
+    const imagePath = mode === 'hybrid' ? item.backgroundPath : item.fullPath;
+    slide.addImage({ path: imagePath, x: 0, y: 0, w: SLIDE_W, h: SLIDE_H });
+
+    if (mode === 'hybrid') {
+      // ② 前景：逐元素切图（独立可编辑图片对象，中层）。
+      addForegroundCutouts(slide, item.foreground, width, height);
+      // ③ 文本：原生可编辑文本框（顶层；后插即在上 → 压住前景/背景）。
+      addTextRuns(slide, item.textRuns, width, height);
+    }
+    // 讲稿进 PPT 备注栏（演讲者视图可见）；无讲稿的 deck 保持原样只写溯源。
+    slide.addNotes(
+      item.speakerNotes ? `${item.speakerNotes}\n\n导出来源: ${item.label}` : `导出来源: ${item.label}`,
+    );
+  }
+
+  await pptx.writeFile({ fileName: outPath });
+}
+
+// 前景切图 → PPT 独立图片对象，归一化等比摆放（位置/大小相对页面比例不变）。
+function addForegroundCutouts(slide, blocks, width, height) {
+  for (const block of blocks) {
+    if (!block.imagePath) continue; // 截图失败的块跳过（已记 warning）
+    const { x, y, w, h } = normalizeRect(block, width, height);
+    if (w <= 0 || h <= 0) continue;
+    slide.addImage({ path: block.imagePath, x, y, w, h });
+  }
+}
+
+function estimateTextWidthPx(text, fontSize) {
+  const size = fontSize || 16;
+  let units = 0;
+  for (const char of text || '') {
+    // Latin/\u6570\u5b57/\u7a7a\u683c/\u5176\u5b83\u7cfb\u6570\u8f83\u65e7\u503c\u7565\u4e0a\u8c03\uff08\u7559\u5b89\u5168\u4f59\u91cf\uff09\uff1aOffice \u7aef\u66ff\u6362\u5b57\u4f53\uff08\u5fae\u8f6f\u96c5\u9ed1\u7b49\uff09\u6e32\u67d3\u897f\u6587\u5e38\u6bd4
+    // \u5bfc\u51fa\u7aef\u5b57\u4f53\u5bbd \u2192 \u4f30\u7a84\u4f1a\u8ba9\u5355\u884c\u672b\u5c3e\u5b57\u88ab\u91cd\u6298\uff1bCJK \u4fdd\u6301 1.0\uff08\u4e2d\u6587\u6807\u9898\u91cc CJK \u5360\u591a\u6570\uff0c\u4e0a\u8c03\u4f1a\u8fc7\u5ea6\u6269\u6846\u81f4\u5047\u91cd\u53e0\uff09\u3002
+    if (/\s/.test(char)) units += 0.4;
+    else if (/[\u3400-\u9fff\u3000-\u303f\uff00-\uffef]/u.test(char)) units += 1;
+    else if (/[A-Z0-9]/.test(char)) units += 0.7;
+    else if (/[a-z]/.test(char)) units += 0.6;
+    else units += 0.55;
+  }
+  return units * size;
+}
+
+// \u884c\u8ddd\u500d\u6570\uff1aCSS line-height(px) / fontSize(px) \u2192 PPT lineSpacingMultiple\uff0c\u5939\u5230 [0.8, 2.2]\u3002\u7eaf\u51fd\u6570\uff08\u5bfc\u51fa\u4f9b\u5355\u6d4b\uff09\u3002
+// \u6cbb\u300cline-height \u63d0\u53d6\u4e86\u5374\u6ca1\u5199\u8fdb addText \u2192 Office \u7528\u9ed8\u8ba4\u884c\u8ddd \u2192 \u4e0e web 1.4~1.8 \u884c\u9ad8\u4e0d\u7b26\u3001\u591a\u884c\u6846\u7b97\u4e0d\u51c6\u300d\u3002
+// normal/\u7f3a\u5931\uff08run.lineHeight \u4e3a null\uff09\u8fd4\u56de undefined \u2192 \u7528 Office \u9ed8\u8ba4\uff0c\u4e0d\u5f3a\u52a0\u3002
+function lineSpacingMultipleFor(run) {
+  if (!run || !run.lineHeight || !run.fontSize) return undefined;
+  const ratio = run.lineHeight / run.fontSize;
+  if (!Number.isFinite(ratio) || ratio <= 0) return undefined;
+  return Math.min(2.2, Math.max(0.8, Math.round(ratio * 100) / 100));
+}
+
+// \u5b57\u8ddd\uff1aCSS letter-spacing(px) \u2192 PPT charSpacing(pt)\uff0c\u4e0e\u5b57\u53f7\u540c\u4e00 px\u2192pt \u7cfb\u6570\uff08\u00d7totalIn\u00d772/totalPx\uff09\uff0c\u65e0\u4e0b\u9650\u94b3\u3002
+// \u7eaf\u51fd\u6570\uff08\u5bfc\u51fa\u4f9b\u5355\u6d4b\uff09\u3002normal/0/\u7f3a\u5931\u8fd4\u56de undefined\uff1b\u8d1f\u503c\uff08\u7d27\u6392\uff09\u900f\u4f20\u3002\u6cbb\u300c\u5b57\u8ddd\u4e22\u5931\u81f4 PPT \u6298\u884c\u70b9\u4e0e web \u4e0d\u4e00\u81f4\u300d\u3002
+function charSpacingPt(letterSpacingPx, totalPx, totalIn) {
+  if (!letterSpacingPx || !totalPx) return undefined;
+  return Math.round((letterSpacingPx / totalPx) * totalIn * 72 * 10) / 10;
+}
+
+function expandTextBoxXW({ x, w }, targetW, align) {
+  const desiredW = Math.max(w, Math.min(targetW, SLIDE_W));
+  const slack = Math.max(0, desiredW - w);
+  let xBox = x;
+  if (align === 'center') xBox = x - slack / 2;
+  else if (align === 'right') xBox = x - slack;
+  // 只防左越界；右越界改「缩框宽」而非把 xBox 往左拽——否则左对齐的整宽标题/副标框（w≈整页）被加宽
+  // 后会触发 `SLIDE_W - desiredW < x` 把左边拽到 ≈0，导出成标题贴画布最左甚至被裁（真机事故：
+  // HTML x=112px → 导出 x=0）。左对齐 x 永远不左移；超宽只在右侧封顶（左对齐文本用不到右侧余量、不可见）。
+  xBox = Math.max(0, xBox);
+  return { x: xBox, w: Math.min(desiredW, SLIDE_W - xBox) };
+}
+
+// 文本框横向余量（纯函数，导出供单测）——治 Office/PowerPoint 用本机字体重排后
+// 「最后只换行一个字」的问题。Chromium 量到的是 HTML 视觉框；PPT 会重新按字体度量折行，
+// 如果框太贴，会把末尾 1–2 个字挤到下一行。策略：
+// - 单行：尽量按估算文本全长留足宽度，最低也保留旧版 12% 余量。
+// - 多行：至少给「估算全文宽度 × 60%」的框宽，让折行更接近中间，而不是末尾孤字。
+// 扩展按对齐锚点进行，并夹到 slide 边界内。
+// 入参 rect={x,w}（英寸，已 normalizeRect），run 带 text/w/h/lineHeight/fontSize/textAlign（px）。
+function textBoxXW({ x, w }, run) {
+  const lineHpx = run.lineHeight || (run.fontSize ? run.fontSize * 1.4 : (run.h || 0));
+  const isSingleLine = run.h > 0 && lineHpx > 0 && run.h <= lineHpx * 1.5;
+  const align = ['left', 'center', 'right', 'justify'].includes(run.textAlign) ? run.textAlign : 'left';
+  const pxToInScale = run.w > 0 ? w / run.w : 0;
+  const estimatedW = pxToInScale
+    ? estimateTextWidthPx(run.text || '', run.fontSize || 16) * pxToInScale
+    : w;
+  const targetW = isSingleLine
+    ? Math.max(w * 1.18, estimatedW * 1.12) // 单行（尤标题）多留余量抗 Office 字体替换重折，扩宽只在本行、几乎不撞邻块
+    : Math.max(w * 1.12, estimatedW * 0.6);
+  return expandTextBoxXW({ x, w }, targetW, align);
+}
+
+function textBoxHeight(h, y, run) {
+  const lineHpx = run.lineHeight || (run.fontSize ? run.fontSize * 1.4 : (run.h || 0));
+  const isSingleLine = run.h > 0 && lineHpx > 0 && run.h <= lineHpx * 1.5;
+  const multiplier = isSingleLine ? 1.18 : 2;
+  return Math.min(h * multiplier, Math.max(h, SLIDE_H - y));
+}
+
+function pptTextBoxIn(run, width, height) {
+  const { x, y, w, h } = normalizeRect(run, width, height);
+  if (w <= 0 || h <= 0) return { x, y, w, h };
+  const { x: xBox, w: wBox } = textBoxXW({ x, w }, run);
+  const hBox = textBoxHeight(h, y, run);
+  return { x: xBox, y, w: wBox, h: hBox };
+}
+
+function pptTextBoxPx(run, width, height) {
+  const rect = pptTextBoxIn(run, width, height);
+  return {
+    x: rect.x / SLIDE_W * width,
+    y: rect.y / SLIDE_H * height,
+    w: rect.w / SLIDE_W * width,
+    h: rect.h / SLIDE_H * height,
+  };
+}
+
+// 文本 → PPT 原生可编辑文本框，还原字体/字号/颜色/粗细/对齐，归一化定位。
+function addTextRuns(slide, runs, width, height) {
+  for (const run of runs) {
+    const text = normalizeText(run.text || '');
+    if (!text) continue;
+    const { x, y, w, h } = normalizeRect(run, width, height);
+    if (w <= 0 || h <= 0) continue;
+    // 字号保真：HTML 用 Chromium 度量、Office 用本机字体度量**重新折行**，同样文字 Office 常多折一行。
+    // 过去文本框按 Chromium 紧贴定高 → Office 多一行即溢出 → 'shrink' 把整段字号大幅缩小（真机 10 页
+    // 「卡内字太小」根因）。对策：给框**下向留 ~18% 余量**（封顶到页底），吸收一行折行余量——常规内容
+    // 在 Office 折行后仍装得下、shrink **不触发**、字号按 pxToPt 原值保真；余量透明、仅真溢出才用，不造成
+    // 视觉重叠。'shrink' 只留作极端兜底（内容远超框时微缩，胜过外溢压住下方元素）。
+    // 治本仍是 HTML 阶段「文本溢出」闸门保证文字装得下（见 layout_balance.py），导出只忠实搬运。
+    const pptRect = pptTextBoxIn(run, width, height);
+    const color = cssColorToPpt(run.color);
+    const align = ['left', 'center', 'right', 'justify'].includes(run.textAlign)
+      ? run.textAlign
+      : 'left';
+    // 保真：把 web 的行距/字距映射进 PPT（缺失→undefined 用 Office 默认，不强加）。
+    const lineSpacingMultiple = lineSpacingMultipleFor(run);
+    const charSpacing = charSpacingPt(run.letterSpacing, height, SLIDE_H);
+    slide.addText(text, {
+      x: pptRect.x,
+      y: pptRect.y,
+      w: pptRect.w,
+      h: pptRect.h,
+      fontFace: pickFontFace(run.fontFamily),
+      fontSize: pxToPt(run.fontSize, height, SLIDE_H),
+      color: color.color,
+      transparency: color.transparency,
+      bold: Number.parseInt(run.fontWeight, 10) >= 600 || run.fontWeight === 'bold',
+      align,
+      valign: 'top',
+      margin: 0,
+      breakLine: true,
+      fit: 'shrink',
+      ...(lineSpacingMultiple ? { lineSpacingMultiple } : {}),
+      ...(charSpacing !== undefined ? { charSpacing } : {}),
+    });
+  }
+}
+
+function runOpcCheck({ outPath, python, skillsRoot }) {
+  const checker = resolve(skillsRoot, 'pptx/scripts/opc_check.py');
+  const result = spawnSync(python, [checker, outPath], { encoding: 'utf8' });
+  const combined = `${result.stdout || ''}${result.stderr || ''}`.trim();
+  if (result.status === 0) {
+    return { ok: true, checker, output: combined || 'OPC check passed.' };
+  }
+
+  const fixedPath = outPath.replace(/\.pptx$/i, '.fixed.pptx');
+  const repack = spawnSync(python, [checker, outPath, '--repack', fixedPath], { encoding: 'utf8' });
+  const repackText = `${repack.stdout || ''}${repack.stderr || ''}`.trim();
+  if (repack.status === 0) {
+    return { ok: true, repacked: true, fixedPath, checker, output: `${combined}\n${repackText}`.trim() };
+  }
+  return { ok: false, checker, output: `${combined}\n${repackText}`.trim() };
+}
+
+function buildReport({ args, slides, consoleErrors, opc, scale, layerSnapshots = {}, validationErrors = [], validationWarnings = [] }) {
+  const editableTextCount = slides.reduce((sum, slide) => sum + slide.textRuns.length, 0);
+  const editableImageCount = slides.reduce(
+    (sum, slide) => sum + slide.foreground.filter((item) => item.imagePath).length,
+    0,
+  );
+  const modeLabel = args.mode === 'flat'
+    ? '高保真图片版：每页为完整截图，基本不可编辑。'
+    : '三层可编辑版：背景为整页底图（不可编辑），前景每个元素是独立可编辑图片对象，文本是原生可编辑文本框。';
+
+  const lines = [
+    '# PPTX 导出报告（三层：背景 / 前景 / 文本）',
+    '',
+    `- 输入 HTML：${args.htmlFile}`,
+    `- 输出 PPTX：${args.out}`,
+    `- 导出模式：${args.mode}`,
+    `- 可编辑边界：${modeLabel}`,
+    `- 截图→PPT 缩放比例：${scale ? scale.toFixed(6) : 'n/a'} in/px（${args.width}×${args.height} → ${SLIDE_W}×${SLIDE_H} in）`,
+    `- 幻灯片数量：${slides.length}`,
+    `- 可编辑文本段数量：${editableTextCount}`,
+    `- 前景独立图片对象数量：${editableImageCount}`,
+    `- 中间产物：${['background', 'foreground', 'text'].map((m) => layerSnapshots[m] ? `pure-${m}.html` : `pure-${m}.html(缺)`).join('、')}`,
+    `- OPC 校验：${opc?.ok ? (opc.repacked ? '初始未通过，已重打包通过' : '通过') : '未通过或已跳过'}`,
+    `- 导出错误：${validationErrors.length}`,
+    `- 导出警告：${validationWarnings.length}`,
+    '',
+    '## 页面',
+    ...slides.map((slide) => `- ${String(slide.index + 1).padStart(2, '0')}：${slide.label}；前景 ${slide.foreground.length} 块 / 文本 ${slide.textRuns.length} 段；截图 ${slide.fullInfo.width}x${slide.fullInfo.height}；hash ${slide.fullInfo.hash.slice(0, 12)}`),
+    '',
+    '## 导出诊断',
+    validationErrors.length ? validationErrors.map((item) => `- ERROR: ${item}`).join('\n') : '- 未发现阻断性导出错误。',
+    validationWarnings.length ? validationWarnings.map((item) => `- WARNING: ${item}`).join('\n') : '- 未发现导出警告。',
+    '',
+    '## 构图均衡指标（确定性；交 layout_balance.py 闸门判定）',
+    args.mode === 'hybrid'
+      ? slides
+          .map((slide) => {
+            const b = computeSlideBalance(slide, args.width, args.height);
+            const empties = ['top', 'bottom', 'left', 'right'].filter((k) => (b.halfOccupancy[k] ?? 1) < 0.06);
+            return `- ${String(slide.index + 1).padStart(2, '0')}：覆盖率 ${(b.coverage * 100).toFixed(0)}%`
+              + `；半区占用 上${(b.halfOccupancy.top * 100).toFixed(0)}/下${(b.halfOccupancy.bottom * 100).toFixed(0)}/左${(b.halfOccupancy.left * 100).toFixed(0)}/右${(b.halfOccupancy.right * 100).toFixed(0)}`
+              + `${empties.length ? `；空半区[${empties.join('/')}]` : ''}`
+              + `${b.overlaps.length ? `；⚠重叠 ${b.overlaps.length} 处` : ''}`
+              + `；底图${b.hasBgImage ? '有' : '无'}；内容块 ${b.contentBoxes}`;
+          })
+          .join('\n')
+      : '- flat 模式整页一张图，无构图均衡指标。',
+    '',
+    '## 浏览器检查',
+    consoleErrors.length ? consoleErrors.map((item) => `- Console error: ${item}`).join('\n') : '- 未发现 console error。',
+    '',
+    '## 注意',
+    '- `flat` 版最保真，但不可编辑。',
+    '- `hybrid` 三层会自动分层：离散视觉块自动切前景图片，文字自动提为顶层可编辑文本框，页面级底色/渐变/氛围图留在背景。',
+    '- `data-pptx-layer="foreground"` 和 `data-pptx-export="ignore"` 只作为 override 使用；不要为了导出而给所有元素手工乱标。',
+    '- 文本在背景截图/前景切图阶段会被隐藏，再在顶层还原为原生文本框；若导出报告出现截图夹带文本，应先修 HTML 或分层规则。',
+    '- 导出后仍需抽查 PowerPoint 中的中文字体、断行、背景裁切和前景切图边界。',
+  ];
+  if (opc?.output) {
+    lines.push('', '## OPC 输出', '```', opc.output, '```');
+  }
+  return `${lines.join('\n')}\n`;
+}
+
+async function main() {
+  const args = parseArgs(process.argv.slice(2));
+  if (args.help) {
+    process.stdout.write(usage());
+    return;
+  }
+
+  args.htmlFile = resolve(args.htmlFile);
+  // measure-only 可无 --out：workdir 默认落 html 同级的 <html名>-layout/。
+  if (args.out) {
+    args.out = resolve(args.out);
+  }
+  const defaultWorkdir = args.out
+    ? resolve(dirname(args.out), `${basename(args.out, extname(args.out))}-export`)
+    : resolve(dirname(args.htmlFile), `${basename(args.htmlFile, extname(args.htmlFile))}-layout`);
+  args.workdir = resolve(args.workdir || defaultWorkdir);
+  await mkdir(args.workdir, { recursive: true });
+
+  const htmlContent = await readFile(args.htmlFile, 'utf8');
+  const preflightErrors = htmlStaticPreflight(htmlContent);
+  if (preflightErrors.length) {
+    throw new Error(`HTML 静态预检失败，已停止 PPTX 导出：\n- ${preflightErrors.join('\n- ')}`);
+  }
+
+  const scriptDir = dirname(fileURLToPath(import.meta.url));
+  const uiSkillRoot = resolve(scriptDir, '..');
+  const skillsRoot = resolve(uiSkillRoot, '..');
+
+  const { chromium, PptxGenJS } = await loadModules(args.nodeModules);
+  const { slides, consoleErrors, validationErrors, validationWarnings, layerSnapshots } = await renderSlides({
+    chromium,
+    htmlPath: args.htmlFile,
+    selector: args.slides,
+    width: args.width,
+    height: args.height,
+    workdir: args.workdir,
+    mode: args.mode,
+    measureOnly: args.measureOnly,
+    withBgShots: args.withBgShots,
+    nodeModules: args.nodeModules,
+  });
+
+  // ── measure-only：只写 layout-report.json（构图闸门前置到 HTML 层），不出 pptx、不切图、不 OPC ──
+  // layout_balance.py 既能读 export-manifest.json 也能读这份（同 schema：mode + slides[].balance）。
+  if (args.measureOnly) {
+    const report = {
+      mode: 'hybrid', // 量了三层几何 → 按 hybrid 交 layout_balance.py 判（flat 不闸门）
+      measureOnly: true,
+      input: args.htmlFile,
+      width: args.width,
+      height: args.height,
+      slides: slides.map((slide) => ({
+        index: slide.index + 1,
+        label: slide.label,
+        balance: computeSlideBalance(slide, args.width, args.height),
+        // 加性字段：文本段原始几何+颜色（HTML 实测 px 矩形，非 Office 加宽框）。
+        // 供 text_readability_pixel.py 按矩形采样文字底下的真实像素：fgParent=null 从
+        // slide-NN-background.png 采（直接压背景层），fgParent 非空从 slide-NN-foreground.png 采
+        // （卡内/前景块内文字）——CSS 对比度检查两类都测不准（图片背衬/渐变/SVG fill）。
+        // layout_balance.py 只读 balance，不受影响。
+        textRuns: (slide.textRuns || []).map((run) => ({
+          text: (run.text || '').slice(0, 24),
+          x: Math.round(run.x),
+          y: Math.round(run.y),
+          w: Math.round(run.w),
+          h: Math.round(run.h),
+          fontSize: Math.round((run.fontSize || 0) * 10) / 10,
+          color: run.color || null,
+          bgColor: run.bgColor || null,
+          bgSolid: !!run.bgSolid,
+          fgParent: run.fgParent || null,
+        })),
+      })),
+      consoleErrors,
+    };
+    const reportPath = resolve(args.workdir, 'layout-report.json');
+    await writeFile(reportPath, `${JSON.stringify(report, null, 2)}\n`, 'utf8');
+    console.log(`构图量完成（measure-only，未出 pptx）: ${reportPath}`);
+    if (consoleErrors.length) {
+      console.error(`渲染中 ${consoleErrors.length} 个 console error（见 layout-report.json）。`);
+    }
+    return;
+  }
+
+  await createPptx({
+    PptxGenJS,
+    slides,
+    outPath: args.out,
+    mode: args.mode,
+    width: args.width,
+    height: args.height,
+  });
+
+  let opc = null;
+  if (args.opcCheck) {
+    opc = runOpcCheck({ outPath: args.out, python: args.python, skillsRoot });
+    if (opc.repacked) {
+      // 把合规版内容写回 args.out，再删掉中间的 *.fixed.pptx——最终目录只留干净的
+      // args.out，绝不留带 "fixed" 字样的文件（产品交付时这种文件名很不专业）。
+      await copyFile(opc.fixedPath, args.out);
+      await unlink(opc.fixedPath).catch(() => {});
+    }
+  }
+
+  // 缩放比例（「记住缩放比例」）：两轴应相等（16:9 → 10:5.625）。
+  const scaleX = SLIDE_W / args.width;
+  const scaleY = SLIDE_H / args.height;
+  const scale = scaleX;
+  if (Math.abs(scaleX - scaleY) > 1e-6) {
+    validationWarnings.push(`缩放比例两轴不一致（x=${scaleX.toFixed(6)} y=${scaleY.toFixed(6)}）：--width/--height 不是 16:9，前景切图会非等比拉伸。`);
+  }
+
+  const manifest = {
+    input: args.htmlFile,
+    output: args.out,
+    mode: args.mode,
+    width: args.width,
+    height: args.height,
+    scale,
+    scaleAxes: { x: scaleX, y: scaleY },
+    layerSnapshots,
+    slides: slides.map((slide) => ({
+      index: slide.index + 1,
+      label: slide.label,
+      fullScreenshot: slide.fullPath,
+      backgroundScreenshot: slide.backgroundPath,
+      foregroundCount: slide.foreground.length,
+      editableImageCount: slide.foreground.filter((item) => item.imagePath).length,
+      textRunCount: slide.textRuns.length,
+      // 构图均衡指标（仅 hybrid 有意义：flat 是整页一张图，无前景/文本几何可量）。
+      balance: args.mode === 'hybrid' ? computeSlideBalance(slide, args.width, args.height) : null,
+      foreground: slide.foreground.map((item) => ({
+        fgId: item.fgId,
+        file: item.imageFile || null,
+        kind: item.kind,
+        tag: item.tag,
+        needsAlphaMask: !!item.needsAlphaMask,
+        alphaMaskApplied: !!item.alphaMaskApplied,
+        pxRect: { x: item.x, y: item.y, w: item.w, h: item.h },
+        inRect: normalizeRect(item, args.width, args.height),
+        error: item.imageError || null,
+      })),
+      textRuns: slide.textRuns.map((run) => ({
+        text: run.text,
+        pxRect: { x: run.x, y: run.y, w: run.w, h: run.h },
+        inRect: normalizeRect(run, args.width, args.height),
+        pptPxRect: pptTextBoxPx(run, args.width, args.height),
+        pptInRect: pptTextBoxIn(run, args.width, args.height),
+        fontSize: run.fontSize,
+        fontWeight: run.fontWeight,
+        color: run.color,
+        textAlign: run.textAlign,
+      })),
+      fullVisibleCount: slide.fullVisibleCount,
+      backgroundVisibleCount: slide.backgroundVisibleCount,
+      fullInfo: slide.fullInfo,
+      backgroundInfo: slide.backgroundInfo,
+    })),
+    consoleErrors,
+    validationErrors,
+    validationWarnings,
+    opc,
+  };
+
+  await writeFile(resolve(args.workdir, 'export-manifest.json'), `${JSON.stringify(manifest, null, 2)}\n`, 'utf8');
+  await writeFile(
+    resolve(args.workdir, 'export-report.md'),
+    buildReport({ args, slides, consoleErrors, opc, scale, layerSnapshots, validationErrors, validationWarnings }),
+    'utf8',
+  );
+
+  if (consoleErrors.length) {
+    console.error(`导出完成，但发现 ${consoleErrors.length} 个 console error。详情见 export-report.md。`);
+  } else {
+    console.log(`导出完成: ${args.out}`);
+  }
+  console.log(`报告目录: ${args.workdir}`);
+  if (opc && !opc.ok) {
+    console.error('OPC 校验未通过。');
+    process.exitCode = 1;
+  }
+  if (validationErrors.length) {
+    console.error(`导出诊断发现 ${validationErrors.length} 个阻断问题。详情见 export-report.md。`);
+    process.exitCode = 1;
+  }
+}
+
+// 「直接运行才跑 main」守卫：被测试 import 时不自跑（process.argv[1] 是测试 runner 而非本脚本）。
+const invokedDirectly = process.argv[1]
+  && import.meta.url === pathToFileURL(process.argv[1]).href;
+if (invokedDirectly) {
+  main().catch((error) => {
+    console.error(error.message);
+    process.exit(1);
+  });
+}
+
+export {
+  pxToIn,
+  pxToPt,
+  normalizeRect,
+  geometryFilename,
+  cssColorToPpt,
+  pickFontFace,
+  normalizeText,
+  computeSlideBalance,
+  htmlStaticPreflight,
+  textBoxXW,
+  lineSpacingMultipleFor,
+  charSpacingPt,
+  CJK_FALLBACK,
+};