pptx2js 0.4.0 → 0.4.3

package/README.html

@@ -536,7 +536,7 @@
     </p>
     <div class="hero-meta">
       <span><strong>运行环境</strong>Node.js ≥ 18</span>
-      <span><strong>版本</strong>v0.4.0</span>
+      <span><strong>版本</strong>v0.4.3</span>
       <span><strong>许可</strong>MIT</span>
       <span><strong>仓库</strong>GitHub 开源</span>
     </div>
@@ -585,19 +585,22 @@
 
     <!-- 转换能力 -->
     <section class="section" id="capabilities">
-      <div class="section-header"><h2 class="section-title">当前转换能力（v0.4.0）</h2></div>
+      <div class="section-header"><h2 class="section-title">当前转换能力（v0.4.3）</h2></div>
       <table>
         <thead><tr><th>元素</th><th>状态</th><th>说明</th></tr></thead>
         <tbody>
-          <tr><td>文本框（段落对齐、lvl 缩进、段距、行距、列表、超链接）</td><td><span class="badge badge-full">精确</span></td><td><code>addText()</code></td></tr>
-          <tr><td>图片</td><td><span class="badge badge-full">精确</span></td><td><code>addImage()</code></td></tr>
-          <tr><td>表格（含单元格边框）</td><td><span class="badge badge-full">精确</span></td><td><code>addTable()</code></td></tr>
-          <tr><td>图表 BAR/LINE/PIE/AREA/DOUGHNUT/SCATTER/RADAR/BUBBLE</td><td><span class="badge badge-full">精确</span></td><td><code>addChart()</code></td></tr>
-          <tr><td>形状 / 背景 / 组合</td><td><span class="badge badge-full">精确</span></td><td><code>addShape()</code> 等</td></tr>
-          <tr><td>母版/版式占位符</td><td><span class="badge badge-full">精确</span></td><td><code>placeholder.js</code></td></tr>
-          <tr><td>SmartArt</td><td><span class="badge badge-degrade">退化</span></td><td>文本列表或占位；缓存 PNG 暂不实现</td></tr>
-          <tr><td>渐变 / 未知形状</td><td><span class="badge badge-degrade">退化</span></td><td>首色标、矩形 fallback</td></tr>
-          <tr><td>不支持图表</td><td><span class="badge badge-degrade">退化</span></td><td>缓存图或占位文本</td></tr>
+          <tr><td>文本框（段落对齐、lvl、段距/行距 <code>spcPct</code>、列表、超链接）</td><td><span class="badge badge-full">精确</span></td><td><code>addText()</code>；<code>lstStyle</code>/<code>defRPr</code> 继承</td></tr>
+          <tr><td>图片</td><td><span class="badge badge-full">精确</span></td><td><code>addImage()</code>；<code>media/</code> 重名自动后缀</td></tr>
+          <tr><td>表格（含单元格边框）</td><td><span class="badge badge-full">精确</span></td><td><code>addTable()</code>；<code>text-utils.js</code></td></tr>
+          <tr><td>图表 BAR/LINE/PIE/AREA/DOUGHNUT/SCATTER/RADAR/BUBBLE</td><td><span class="badge badge-full">精确</span></td><td><code>addChart()</code>；散点图 <code>c:xVal</code></td></tr>
+          <tr><td>预设形状 / 线条（虚线、<code>flipH</code>/<code>flipV</code>）</td><td><span class="badge badge-full">精确</span></td><td><code>addShape()</code>；<code>spTree</code> 文档顺序</td></tr>
+          <tr><td>母版/版式装饰形状</td><td><span class="badge badge-full">精确</span></td><td>master → layout → slide 层叠</td></tr>
+          <tr><td>纯色 / 渐变 / <code>prstClr</code> / <code>sysClr</code> 背景</td><td><span class="badge badge-full">精确</span></td><td><code>p:bgPr</code>、<code>p:bgRef</code>；系统色修饰符</td></tr>
+          <tr><td>母版/版式占位符继承</td><td><span class="badge badge-full">精确</span></td><td>xfrm、<code>txBody</code>/<code>lstStyle</code> 合并</td></tr>
+          <tr><td>组合形状（<code>p:grpSp</code>）</td><td><span class="badge badge-full">精确</span></td><td>无 <code>p:spTree</code> 时直接展平</td></tr>
+          <tr><td>SmartArt</td><td><span class="badge badge-degrade">退化</span></td><td>文本列表或占位</td></tr>
+          <tr><td>渐变填充 / 弯曲连接线</td><td><span class="badge badge-degrade">退化</span></td><td>首色标；<code>bentConnector3</code>→直线</td></tr>
+          <tr><td>不支持图表类型</td><td><span class="badge badge-degrade">退化</span></td><td>缓存图或占位文本</td></tr>
           <tr><td>复杂动画</td><td><span class="badge badge-plan">计划</span></td><td>design.html</td></tr>
         </tbody>
       </table>
@@ -631,7 +634,7 @@
           <tr><td>--strict-degrade</td><td>false</td><td>任意退化项触发非零退出码</td></tr>
           <tr><td>--strict-skip</td><td>false</td><td><code>severity:error</code> 跳过项触发非零退出码</td></tr>
           <tr><td>--log-level</td><td>info</td><td><code>minimal</code> / <code>info</code> / <code>verbose</code></td></tr>
-          <tr><td>--max-file-size</td><td>50MB</td><td>超过阈值切换流式解析（实现中）</td></tr>
+          <tr><td>--max-file-size</td><td>50MB</td><td>超过阈值抛出错误（避免静默 OOM）</td></tr>
         </tbody>
       </table>
 
@@ -697,15 +700,17 @@ console.log(result.log.statistics);</pre>
         </div>
         <div class="pipeline-step">
           <div class="pipeline-connector"><div class="pipeline-dot"></div><div class="pipeline-line"></div></div>
-          <div class="pipeline-box"><strong>⑤ 代码生成器</strong> — lib/codegen.js</div>
+          <div class="pipeline-box"><strong>⑥ 资源打包器</strong> — lib/packager.js（先于代码生成，更新 IR 中 mediaPath）</div>
         </div>
         <div class="pipeline-step">
           <div class="pipeline-connector"><div class="pipeline-dot"></div></div>
-          <div class="pipeline-box"><strong>⑥ 资源打包器</strong> — lib/packager.js</div>
+          <div class="pipeline-box"><strong>⑤ 代码生成器</strong> — lib/codegen.js</div>
         </div>
         <div class="pipeline-io out">output.js + media/ + conversion.log</div>
       </div>
-      <p style="margin-top:16px;font-size:13px;color:var(--ink-faint)">辅助模块：<code>lib/presentation.js</code>、<code>lib/graphic.js</code>、<code>lib/smartart.js</code>、<code>lib/xml-utils.js</code>、<code>lib/utils/color.js</code>、<code>lib/utils/bounds.js</code></p>
+      <p style="margin-top:16px;font-size:13px;color:var(--ink-faint)">辅助模块：<code>lib/presentation.js</code>、<code>lib/graphic.js</code>、<code>lib/xml-utils.js</code>、<code>lib/color.js</code>、<code>lib/bounds.js</code>、<code>lib/text-utils.js</code>、<code>lib/run-utils.js</code>、<code>lib/table.js</code>、<code>lib/chart.js</code>、<code>lib/smartart.js</code></p>
+      <h3 style="margin-top:24px;font-size:15px;font-weight:600">XML 节点模型（OONode）</h3>
+      <p style="font-size:13px;color:var(--ink-light)">自研 <code>lib/xml-parser.js</code>，节点结构 <code>{ tag, attrs, children, text }</code>。<code>childNodes</code> 保留文档顺序（Z 轴与段落内 <code>pPr</code>/<code>r</code> 顺序）。</p>
     </section>
 
     <!-- 技术栈 -->
@@ -715,7 +720,7 @@ console.log(result.log.statistics);</pre>
         <thead><tr><th>用途</th><th>选型</th></tr></thead>
         <tbody>
           <tr><td>ZIP 处理</td><td><a href="https://www.npmjs.com/package/jszip" target="_blank" rel="noopener">JSZip</a></td></tr>
-          <tr><td>XML 解析</td><td><a href="https://www.npmjs.com/package/xml2js" target="_blank" rel="noopener">xml2js</a>（统一配置，见 <code>lib/xml-parser.js</code>）</td></tr>
+          <tr><td>XML 解析</td><td>自研 <code>lib/xml-parser.js</code>（无 xml2js 运行时依赖）</td></tr>
           <tr><td>CLI</td><td><a href="https://www.npmjs.com/package/commander" target="_blank" rel="noopener">Commander.js</a></td></tr>
           <tr><td>终端输出</td><td><a href="https://www.npmjs.com/package/chalk" target="_blank" rel="noopener">chalk</a></td></tr>
           <tr><td>测试</td><td><a href="https://jestjs.io/" target="_blank" rel="noopener">Jest</a>（单元 + 集成）</td></tr>
@@ -727,28 +732,31 @@ console.log(result.log.statistics);</pre>
     <!-- 开发 -->
     <section class="section" id="dev">
       <div class="section-header"><h2 class="section-title">开发</h2></div>
-      <pre class="shell"><span class="prompt">$</span>npm test              <span class="com" style="color:#666"># 24 用例（单元 + 集成）</span>
+      <pre class="shell"><span class="prompt">$</span>npm test              <span class="com" style="color:#666"># 51 用例（29 套件，单元 + 集成）</span>
 <span class="prompt">$</span>npm run test:watch    <span class="com" style="color:#666"># 监听模式</span></pre>
 
       <h3>目录结构</h3>
       <pre class="tree">pptx2js/
 ├── bin/pptx2js.js          # CLI 入口
-├── lib/
-│   ├── convert.js           # 流水线编排
-│   ├── unpacker.js          # ① 解压
-│   ├── xml-parser.js        # ② 统一 XML 解析
-│   ├── rels.js              # ② 关系索引
-│   ├── presentation.js      # 幻灯片列表 / 尺寸
-│   ├── placeholder.js       # 母版/版式占位符
-│   ├── graphic.js           # graphicFrame 识别
-│   ├── table.js             # 表格提取
-│   ├── chart.js             # 图表提取
-│   ├── smartart.js          # SmartArt 退化
-│   ├── extractor.js         # ③ 实体提取
-│   ├── mapper.js            # ④ IR 映射
-│   ├── codegen.js           # ⑤ 代码生成
-│   ├── packager.js          # ⑥ 资源打包
-│   └── utils/               # EMU、颜色
+├── lib/                    # 20 个模块（扁平布局）
+│   ├── index.js            # 库入口
+│   ├── convert.js          # 流水线编排
+│   ├── unpacker.js         # ① 解压
+│   ├── xml-parser.js       # ② OONode 解析
+│   ├── xml-utils.js        # child / children / childNodes
+│   ├── rels.js             # ② 关系索引
+│   ├── presentation.js     # 幻灯片列表 / 尺寸
+│   ├── placeholder.js      # 母版/版式继承与装饰层
+│   ├── text-utils.js       # 文本 run 提取
+│   ├── color.js            # 颜色（srgb/scheme/prst/sys）
+│   ├── bounds.js           # EMU 与 xfrm 边界
+│   ├── graphic.js          # graphicFrame 识别
+│   ├── table.js / chart.js / smartart.js
+│   ├── extractor.js        # ③ 实体提取
+│   ├── mapper.js           # ④ IR 映射
+│   ├── codegen.js          # ⑤ 代码生成
+│   ├── packager.js         # ⑥ 资源打包
+│   └── run-utils.js        # run 合并与压缩
 ├── test/
 │   ├── unit/
 │   ├── integration/
@@ -762,14 +770,14 @@ console.log(result.log.statistics);</pre>
       <div class="section-header"><h2 class="section-title">已知局限</h2></div>
       <ul class="limits-list">
         <li><span class="limit-num">L1</span><span><strong>字体</strong>依赖运行环境，不负责检测或打包嵌入字体</span></li>
-        <li><span class="limit-num">L2</span><span><strong>母版继承</strong>已实现 xfrm 与基础 txBody；复杂列表样式继承仍有限；<code>a:spcPct</code> 百分比段距/行距暂不处理</span></li>
+        <li><span class="limit-num">L2</span><span><strong>母版继承</strong>已实现装饰层与 <code>lstStyle</code>/<code>defRPr</code>；复杂列表/多主题样式仍可能不完整</span></li>
         <li><span class="limit-num">L3</span><span><strong>SmartArt</strong> 仅文本列表退化，缓存图片因 PPT 版本差异未实现</span></li>
         <li><span class="limit-num">L4</span><span><strong>动画</strong>尚未转换（设计为退化淡入，待实现）</span></li>
         <li><span class="limit-num">L5</span><span><strong>不保证</strong>往返 PPTX 二进制一致，追求视觉可接受</span></li>
         <li><span class="limit-num">L6</span><span><strong>不支持</strong>密码保护或 <code>.ppt</code> 旧格式</span></li>
         <li><span class="limit-num">L7</span><span><strong>不支持</strong>增量转换，每次全量重写</span></li>
-        <li><span class="limit-num">L8</span><span><strong>大文件</strong>流式解析仍在实现中</span></li>
-        <li><span class="limit-num">L9</span><span><strong>媒体重名</strong>同名文件可能互相覆盖（packager 待去重）</span></li>
+        <li><span class="limit-num">L8</span><span><strong>大文件</strong>超过 <code>--max-file-size</code> 会直接报错，需调高阈值或拆分</span></li>
+        <li><span class="limit-num">L9</span><span><strong>非标 OOXML</strong>无 XML 前缀的文档可能解析失败</span></li>
       </ul>
     </section>
 
@@ -777,7 +785,7 @@ console.log(result.log.statistics);</pre>
     <section class="section" id="status">
       <div class="section-header"><h2 class="section-title">项目状态</h2></div>
       <div class="status-banner">
-        当前为 <strong>v0.4.0</strong>：在 v0.3.0 基础上新增段落级格式、表格单元格边框、扩展图表类型、SmartArt 文本列表退化。复杂动画、SmartArt 缓存图、外部链接表格等按 <a href="./design.html" style="color:var(--accent)">design.html</a> 继续推进，欢迎贡献。
+        当前为 <strong>v0.4.3</strong>：母版/版式装饰层按 Z 轴叠加；<code>lstStyle</code>/<code>defRPr</code> 与 <code>prstClr</code>/<code>sysClr</code> 颜色；<code>spcPct</code> 段距；形状 <code>flipH</code>/<code>flipV</code>；<code>lib/utils</code> 合并为 <code>lib/color.js</code>、<code>lib/bounds.js</code>。复杂动画、部分连接器与 SmartArt 图形化按 <a href="./design.html" style="color:var(--accent)">design.html</a> 继续推进，欢迎贡献。
       </div>
       <p class="license" style="margin-top:32px;border:none;padding:0">License: MIT</p>
     </section>

package/README.md

@@ -11,7 +11,7 @@
 | 层级 | 策略 | 示例 |
 |------|------|------|
 | 精确转换 | PptxGenJS 原生支持的元素一比一映射 | 文本框、图片、基本形状、线条、纯色背景 |
-| 退化转换 | 尽力保留内容，降级为近似表示 | 渐变→纯色、未知形状→矩形 |
+| 退化转换 | 尽力保留内容，降级为近似表示 | 渐变→纯色、图案填充→前景色、未知形状→矩形 |
 | 静默跳过 | 记录日志，不中断流程 | 不支持的 graphicFrame、ActiveX、OLE、VBA |
 
 ## 功能特性
@@ -21,20 +21,22 @@
 - 转换报告为 JSON，含 `slideIndex`、`elementBounds`、`severity`，便于 CI 集成
 - 仅支持 OOXML（`.pptx`），不做双向转换、不做 GUI
 
-## 当前转换能力（v0.4.0）
+## 当前转换能力（v0.4.3）
 
 | 元素 | 状态 | 说明 |
 |------|------|------|
-| 文本框（run 格式、段落对齐、`lvl` 缩进、段前/段后距、行距、列表、超链接） | ✅ 精确 | `addText()`；`indent`（首行缩进 EMU）暂不映射 |
-| 图片（PNG/JPEG 等） | ✅ 精确 | `addImage()`，提取至 `media/` |
-| 表格（内联 `a:tbl`、单元格四边边框） | ✅ 精确 | `addTable()`，含合并单元格与 `border` |
-| 图表（BAR / LINE / PIE / AREA / DOUGHNUT / SCATTER / RADAR / BUBBLE） | ✅ 精确 | `addChart()`，从 `chartN.xml` 读数据 |
-| 预设形状 / 线条 | ✅ 精确 | `addShape()` |
-| 纯色背景 / 幻灯片尺寸 | ✅ 精确 | `background`、`defineLayout()` |
-| 组合形状（`p:grpSp`） | ✅ 精确 | 递归展平 |
-| 母版/版式占位符继承 | ✅ 精确 | `lib/placeholder.js`，按 `p:ph idx` 合并 xfrm |
-| SmartArt | ⚡ 退化 | `lib/smartart.js`：从 `dgm:data` 提取文本列表，否则占位；缓存 PNG 因 rels 差异大暂不实现 |
-| 渐变填充 / 未知形状 | ⚡ 退化 | 首色标→纯色；未知 `prstGeom`→矩形 |
+| 文本框（run 格式、段落对齐、`lvl`、段距/行距、`spcPct`、列表、超链接） | ✅ 精确 | `addText()`；`lstStyle`/`defRPr` 继承；同段多 `a:pPr` 按 XML 顺序 |
+| 图片（PNG/JPEG 等） | ✅ 精确 | `addImage()`；`media/` 重名自动 `name_2.ext` |
+| 表格（内联 `a:tbl`、单元格样式与四边边框） | ✅ 精确 | `addTable()`；文本经 `lib/text-utils.js` 提取 |
+| 图表（BAR / LINE / PIE / AREA / DOUGHNUT / SCATTER / RADAR / BUBBLE） | ✅ 精确 | `addChart()`；散点图读取 `c:xVal` |
+| 预设形状 / 线条（虚线、`flipH`/`flipV`） | ✅ 精确 | `addShape()`；`spTree` 按文档顺序渲染 |
+| 母版/版式装饰形状 | ✅ 精确 | master → layout → slide 层叠；跳过占位符定义形状 |
+| 纯色 / 渐变首色标 / 图案前景色 / `prstClr` / `sysClr` | ✅ / ⚡ | `p:bgPr`、`p:bgRef`；系统色应用 lumMod 等修饰 |
+| 幻灯片尺寸 | ✅ 精确 | `defineLayout()` |
+| 组合形状（`p:grpSp`） | ✅ 精确 | 无 `p:spTree` 包装时直接递归展平 |
+| 母版/版式占位符继承 | ✅ 精确 | xfrm、`txBody`/`lstStyle`/`defRPr` 合并 |
+| SmartArt | ⚡ 退化 | 从 `dgm:data` 提取文本列表，否则占位 |
+| 渐变填充 / 弯曲连接线 | ⚡ 退化 | 渐变文字/填充取首色标；`bentConnector3`→直线 |
 | 不支持图表类型 | ⚡ 退化 | 图表部件 rels 缓存图或占位文本 |
 | 复杂动画 | 🔜 计划中 | 见设计文档 |
 
@@ -71,7 +73,7 @@ npx pptx2js input.pptx -o ./pptx2js-output
 | `--strict-degrade` | `false` | 任意退化项触发非零退出码 |
 | `--strict-skip` | `false` | `severity:error` 跳过项触发非零退出码 |
 | `--log-level` | `info` | `minimal` / `info` / `verbose` |
-| `--max-file-size` | 50MB | 超过阈值切换流式解析（实现中） |
+| `--max-file-size` | 50MB | 超过阈值抛出错误（避免静默 OOM） |
 
 > **注意：** Commander 的 `--no-media` 对应内部选项 `media`（默认 `true`）。传入 `--no-media` 后 `media` 为 `false`，才会跳过媒体提取。
 
@@ -106,7 +108,7 @@ node output.js   # 生成 output.pptx
 ```
 pptx2js-output/
 ├── output.js          # 主生成脚本，可直接 node 运行
-├── media/             # 提取的图片等媒体
+├── media/             # 提取的图片等媒体（重名自动加后缀）
 ├── conversion.log     # JSON 格式转换报告
 └── README.md          # 自动生成的说明
 ```
@@ -121,21 +123,38 @@ pptx2js-output/
 input.pptx
   → ① 解压与索引      (lib/unpacker.js)
   → ② XML 预解析      (lib/xml-parser.js, lib/rels.js)
-  → ③ 实体提取器      (lib/extractor.js, lib/placeholder.js, lib/table.js, lib/chart.js, lib/smartart.js)
+  → ③ 实体提取器      (lib/extractor.js, lib/text-utils.js, lib/placeholder.js, …)
   → ④ 映射引擎        (lib/mapper.js)
+  → ⑥ 资源打包器      (lib/packager.js)   ← 先于代码生成，就地更新 IR 中 mediaPath
   → ⑤ 代码生成器      (lib/codegen.js)
-  → ⑥ 资源打包器      (lib/packager.js)
   → output.js + media/ + conversion.log
 ```
 
-辅助模块：`lib/presentation.js`、`lib/graphic.js`、`lib/xml-utils.js`、`lib/utils/color.js`、`lib/utils/bounds.js`、`lib/smartart.js`。
+辅助模块：`lib/presentation.js`、`lib/graphic.js`、`lib/xml-utils.js`、`lib/color.js`、`lib/bounds.js`、`lib/run-utils.js`、`lib/table.js`、`lib/chart.js`、`lib/smartart.js`。
+
+### XML 节点模型（v0.4.2+）
+
+自研轻量解析器（`lib/xml-parser.js`），统一为 **OONode**：
+
+```js
+{ tag: 'a:r', attrs: { … }, children: [ … ], text: '' }
+```
+
+`lib/xml-utils.js` 提供：
+
+| API | 用途 |
+|-----|------|
+| `child(node, tag)` | 第一个子节点 |
+| `children(node, tag)` | 所有同名子节点（始终为数组） |
+| `childNodes(node)` | 有序子节点列表（Z 轴顺序、`pPr`/`r` 顺序） |
+| `documentRoot(doc, …tags)` | 兼容 parseXml 直接返回根节点 |
 
 ## 技术栈
 
 | 用途 | 选型 |
 |------|------|
 | ZIP 处理 | [JSZip](https://www.npmjs.com/package/jszip) |
-| XML 解析 | [xml2js](https://www.npmjs.com/package/xml2js)（统一配置，见 `lib/xml-parser.js`） |
+| XML 解析 | 自研 `lib/xml-parser.js`（无 xml2js 运行时依赖） |
 | CLI | [Commander.js](https://www.npmjs.com/package/commander) |
 | 终端输出 | [chalk](https://www.npmjs.com/package/chalk) |
 | 测试 | [Jest](https://jestjs.io/)（单元 + 集成） |
@@ -145,7 +164,7 @@ input.pptx
 ## 开发
 
 ```bash
-npm test              # 单元测试 + 集成测试（24 用例）
+npm test              # 单元测试 + 集成测试（51 用例）
 npm run test:watch    # 监听模式
 ```
 
@@ -154,47 +173,48 @@ npm run test:watch    # 监听模式
 ```
 pptx2js/
 ├── bin/pptx2js.js          # CLI 入口
-├── lib/
+├── lib/                    # 20 个模块文件（扁平布局）
 │   ├── index.js            # 库入口（export convert）
 │   ├── convert.js          # 流水线编排
 │   ├── unpacker.js         # ① 解压
-│   ├── xml-parser.js       # ② 统一 XML 解析
+│   ├── xml-parser.js       # ② OONode XML 解析
+│   ├── xml-utils.js        # child / children / childNodes
 │   ├── rels.js             # ② 关系索引
 │   ├── presentation.js     # 幻灯片列表 / 尺寸
-│   ├── placeholder.js    # 母版/版式占位符继承
+│   ├── placeholder.js      # 母版/版式继承与装饰层
+│   ├── text-utils.js       # 文本 run 提取
+│   ├── color.js            # 颜色规范化（srgb/scheme/prst/sys）
+│   ├── bounds.js           # EMU 换算与 xfrm 边界
 │   ├── graphic.js          # graphicFrame URI 识别
-│   ├── table.js            # 表格提取
-│   ├── chart.js            # 图表提取
-│   ├── smartart.js         # SmartArt 退化
+│   ├── table.js / chart.js / smartart.js
 │   ├── extractor.js        # ③ 实体提取
 │   ├── mapper.js           # ④ IR 映射
 │   ├── codegen.js          # ⑤ 代码生成
 │   ├── packager.js         # ⑥ 资源打包
-│   ├── xml-utils.js
-│   └── utils/              # EMU、颜色、坐标
+│   └── run-utils.js        # run 合并与选项压缩
 ├── test/
 │   ├── unit/
 │   ├── integration/
-│   └── helpers/            # 最小 PPTX 构造
-├── design.html             # 完整设计文档
-└── README.html             # 本页 HTML 版
+│   └── helpers/
+├── design.html
+└── README.html
 ```
 
 ## 已知局限
 
 1. **字体**依赖运行环境，不负责检测或打包嵌入字体  
-2. **母版继承**已实现 xfrm 与基础 txBody 补全；复杂段落/列表样式继承仍有限；`a:spcPct` 百分比段距/行距暂不处理  
+2. **母版继承**已实现装饰层与 `lstStyle`/`defRPr`；复杂列表/多主题/嵌套样式仍可能不完整  
 3. **SmartArt** 仅文本列表退化，缓存图片路径因 PPT 版本差异未实现  
 4. **动画**尚未转换（设计为退化淡入，待实现）  
 5. **不保证**往返 PPTX 二进制一致，追求视觉可接受  
 6. **不支持**密码保护或 `.ppt` 旧格式  
 7. **不支持**增量转换，每次全量重写  
-8. **大文件**（200MB+）可能内存压力较大，超过 50MB 流式解析仍在实现中  
-9. **媒体重名**不同路径同名图片可能互相覆盖（`packager` 待实现去重）
+8. **大文件**超过 `--max-file-size` 会直接报错，超大 PPT 需调高阈值或拆分  
+9. **默认命名空间**无 XML 前缀的非标 OOXML 可能解析失败  
 
 ## 项目状态
 
-当前为 **v0.4.0**：在 v0.3.0 基础上新增段落级格式（对齐、`lvl`、段距、行距）、表格单元格边框、扩展图表类型、SmartArt 文本列表退化。复杂动画、SmartArt 缓存图、外部链接表格等按 [`design.html`](./design.html) 继续推进，欢迎贡献。
+当前为 **v0.4.3**：母版/版式装饰层按 Z 轴叠加；`lstStyle`/`defRPr` 与 `prstClr`/`sysClr` 颜色；`spcPct` 段距；形状 `flipH`/`flipV`；`lib/utils` 合并为 `lib/color.js`、`lib/bounds.js`。复杂动画、部分连接器与 SmartArt 图形化等待 [`design.html`](./design.html) 继续推进，欢迎贡献。
 
 ## License
 

package/lib/{utils/bounds.js → bounds.js}

@@ -1,8 +1,26 @@
 /**
- * 形状坐标：a:xfrm → 英寸边界
+ * EMU 换算与形状坐标：a:xfrm → 英寸边界
  */
-const { attr, child } = require('../xml-utils');
-const { emuToInch } = require('./emu');
+const { attr, child } = require('./xml-utils');
+
+/** EMU（English Metric Units）与英寸换算，1 英寸 = 914400 EMU */
+const EMU_PER_INCH = 914400;
+
+/**
+ * @param {number} emu
+ * @returns {number}
+ */
+function emuToInch(emu) {
+  return emu / EMU_PER_INCH;
+}
+
+/**
+ * @param {number} inch
+ * @returns {number}
+ */
+function inchToEmu(inch) {
+  return inch * EMU_PER_INCH;
+}
 
 /**
  * @param {object|null|undefined} xfrm
@@ -31,4 +49,9 @@ function round3(n) {
   return Math.round(n * 1000) / 1000;
 }
 
-module.exports = { boundsFromXfrm };
+module.exports = {
+  EMU_PER_INCH,
+  emuToInch,
+  inchToEmu,
+  boundsFromXfrm,
+};

package/lib/chart.js

@@ -2,9 +2,9 @@
  * 图表提取（design.html §4.3）
  */
 const path = require('path');
-const { asArray, attr, child, textContent } = require('./xml-utils');
+const { attr, child, children, documentRoot, textContent } = require('./xml-utils');
 const { getGraphicXfrm } = require('./graphic');
-const { boundsFromXfrm } = require('./utils/bounds');
+const { boundsFromXfrm } = require('./bounds');
 
 const CHART_NS_BAR = 'barChart';
 const CHART_NS_LINE = 'lineChart';
@@ -42,12 +42,13 @@ function extractChart(graphicFrame, ctx) {
   }
 
   const chartDoc = ctx.parsed[chartPath];
-  const chartSpace = child(chartDoc, 'c:chartSpace') ?? chartDoc;
+  const chartSpace = documentRoot(chartDoc, 'c:chartSpace') ?? chartDoc;
   const chartRoot = child(chartSpace, 'c:chart');
   const plotArea = child(chartRoot, 'c:plotArea');
 
   const parsed = parseChartPlotArea(plotArea);
   if (parsed) {
+    parsed.title = extractChartTitle(chartRoot);
     return {
       slideIndex: ctx.slideIndex,
       slidePath: ctx.slidePath,
@@ -71,14 +72,13 @@ function parseChartPlotArea(plotArea) {
     const chartNode = child(plotArea, `c:${xmlName}`);
     if (!chartNode) continue;
 
-    const series = extractSeries(chartNode, plotArea);
+    const series = extractSeries(chartNode, plotArea, xmlName);
     if (!series.length) continue;
 
-    const title = extractChartTitle(plotArea);
     return {
       type: pptxType,
       data: series,
-      title,
+      title: '',
     };
   }
   return null;
@@ -88,16 +88,30 @@ function parseChartPlotArea(plotArea) {
  * @param {object} chartNode c:barChart 等
  * @param {object} plotArea
  */
-function extractSeries(chartNode, plotArea) {
+function extractSeries(chartNode, plotArea, chartXmlName) {
   const result = [];
-  const seriesNodes = asArray(chartNode['c:ser']);
+  const seriesNodes = children(chartNode, 'c:ser');
+  const isScatter = chartXmlName === 'scatterChart';
 
   for (const ser of seriesNodes) {
     const titleText = extractSeriesName(ser);
-    const cat = extractCategoryLabels(ser, plotArea);
-    const values = extractSeriesValues(ser, plotArea);
+    const cat = extractCategoryLabels(ser);
+    const values = extractSeriesValues(ser);
     if (!values.length) continue;
 
+    if (isScatter) {
+      const xs = extractSeriesXValues(ser);
+      const pairs = values.map((y, i) => [
+        xs[i] != null && !Number.isNaN(xs[i]) ? xs[i] : i,
+        y,
+      ]);
+      result.push({
+        name: titleText || `Series ${result.length + 1}`,
+        values: pairs,
+      });
+      continue;
+    }
+
     result.push({
       name: titleText || `Series ${result.length + 1}`,
       labels: cat.length ? cat : values.map((_, i) => String(i + 1)),
@@ -113,64 +127,124 @@ function extractSeries(chartNode, plotArea) {
 function extractSeriesName(ser) {
   const tx = child(child(ser, 'c:tx'), 'c:strRef');
   const cache = child(tx, 'c:strCache');
-  const pt = asArray(child(cache, 'c:pt'))[0];
+  const pt = children(cache, 'c:pt')[0];
   return pt ? textContent(child(pt, 'c:v')) : '';
 }
 
 /**
  * @param {object} ser
- * @param {object} plotArea
  */
-function extractCategoryLabels(ser, plotArea) {
-  void plotArea;
+function extractCategoryLabels(ser) {
   const cat = child(ser, 'c:cat');
   if (!cat) return [];
+
   const strRef = child(cat, 'c:strRef');
+  if (strRef) {
+    const pts = extractCachePoints(strRef, 'c:strCache', 'c:v');
+    if (pts.length) return pts;
+  }
+
+  const multiRef = child(cat, 'c:multiLvlStrRef');
+  if (multiRef) {
+    const pts = extractMultiLvlStrLabels(multiRef);
+    if (pts.length) return pts;
+  }
+
   const numRef = child(cat, 'c:numRef');
-  if (strRef) return extractCachePoints(strRef, 'c:strCache', 'c:v');
-  if (numRef) return extractCachePoints(numRef, 'c:numCache', 'c:v').map(String);
+  if (numRef) {
+    const pts = extractCachePoints(numRef, 'c:numCache', 'c:v').map(String);
+    if (pts.length) return pts;
+  }
+
+  const strLit = child(cat, 'c:strLit');
+  if (strLit) {
+    return extractCachePoints(strLit, null, 'c:v').filter(Boolean);
+  }
+
   return [];
 }
 
+/**
+ * PptxGenJS 常用 multiLvlStrRef 缓存分类标签
+ * @param {object} multiRef
+ */
+function extractMultiLvlStrLabels(multiRef) {
+  const cache = child(multiRef, 'c:multiLvlStrCache');
+  if (!cache) return [];
+  const lvl = child(cache, 'c:lvl');
+  if (!lvl) return [];
+  const pts = children(lvl, 'c:pt');
+  return pts
+    .sort(
+      (a, b) =>
+        parseInt(attr(a, 'idx') ?? '0', 10) - parseInt(attr(b, 'idx') ?? '0', 10)
+    )
+    .map((pt) => textContent(child(pt, 'c:v')))
+    .filter(Boolean);
+}
+
 /**
  * @param {object} ser
- * @param {object} plotArea
  */
-function extractSeriesValues(ser, plotArea) {
-  void plotArea;
+function extractSeriesValues(ser) {
   const val = child(ser, 'c:val');
   if (!val) return [];
   const numRef = child(val, 'c:numRef');
-  if (!numRef) return [];
-  return extractCachePoints(numRef, 'c:numCache', 'c:v').map((v) => parseFloat(v) || 0);
+  if (numRef) {
+    return extractCachePoints(numRef, 'c:numCache', 'c:v').map((v) => parseFloat(v) || 0);
+  }
+  const numLit = child(val, 'c:numLit');
+  if (numLit) {
+    return extractCachePoints(numLit, null, 'c:v').map((v) => parseFloat(v) || 0);
+  }
+  return [];
+}
+
+/**
+ * 散点图 X 轴（c:xVal）
+ * @param {object} ser
+ */
+function extractSeriesXValues(ser) {
+  const xVal = child(ser, 'c:xVal');
+  if (!xVal) return [];
+  const numRef = child(xVal, 'c:numRef');
+  if (numRef) {
+    return extractCachePoints(numRef, 'c:numCache', 'c:v').map((v) => parseFloat(v) || 0);
+  }
+  const numLit = child(xVal, 'c:numLit');
+  if (numLit) {
+    return extractCachePoints(numLit, null, 'c:v').map((v) => parseFloat(v) || 0);
+  }
+  return [];
 }
 
 /**
  * @param {object} refNode
- * @param {string} cacheKey
+ * @param {string|null} cacheKey null 时直接在 refNode 上找 c:pt（如 strLit）
  * @param {string} valueKey
  */
 function extractCachePoints(refNode, cacheKey, valueKey) {
-  const cache = child(refNode, cacheKey);
-  const pts = asArray(child(cache, 'c:pt'));
+  const container = cacheKey ? child(refNode, cacheKey) : refNode;
+  if (!container) return [];
+  const pts = children(container, 'c:pt');
   return pts
     .sort((a, b) => parseInt(attr(a, 'idx') ?? '0', 10) - parseInt(attr(b, 'idx') ?? '0', 10))
     .map((pt) => textContent(child(pt, valueKey)));
 }
 
 /**
- * @param {object} plotArea
+ * @param {object} chartRoot c:chart
  */
-function extractChartTitle(plotArea) {
-  const title = child(plotArea, 'c:title');
+function extractChartTitle(chartRoot) {
+  const title = child(chartRoot, 'c:title');
   if (!title) return '';
   const tx = child(title, 'c:tx');
   const rich = child(tx, 'c:rich');
   if (!rich) return '';
   const parts = [];
-  for (const p of asArray(rich['a:p'])) {
-    for (const r of asArray(p['a:r'])) {
-      parts.push(textContent(r['a:t']));
+  for (const p of children(rich, 'a:p')) {
+    for (const r of children(p, 'a:r')) {
+      parts.push(textContent(child(r, 'a:t')));
     }
   }
   return parts.join('');