pptx2js 0.4.0

package/README.md

@@ -0,0 +1,201 @@
+# pptx2js
+
+将 **PowerPoint `.pptx`** 文件转换为可直接运行的 **[PptxGenJS](https://github.com/gitbrent/PptxGenJS)** 生成脚本，并附带媒体资源与转换报告。
+
+> 设计文档见 [`design.html`](./design.html)，HTML 版说明见 [`README.html`](./README.html)。
+
+## 核心哲学
+
+**「PptxGenJS 能力边界即转换边界」**
+
+| 层级 | 策略 | 示例 |
+|------|------|------|
+| 精确转换 | PptxGenJS 原生支持的元素一比一映射 | 文本框、图片、基本形状、线条、纯色背景 |
+| 退化转换 | 尽力保留内容，降级为近似表示 | 渐变→纯色、未知形状→矩形 |
+| 静默跳过 | 记录日志，不中断流程 | 不支持的 graphicFrame、ActiveX、OLE、VBA |
+
+## 功能特性
+
+- 输入 `.pptx`，输出 `output.js` + `media/` + `conversion.log` + 自动生成说明
+- **CLI** 与 **编程 API** 共用同一套六模块流水线
+- 转换报告为 JSON，含 `slideIndex`、`elementBounds`、`severity`，便于 CI 集成
+- 仅支持 OOXML（`.pptx`），不做双向转换、不做 GUI
+
+## 当前转换能力（v0.4.0）
+
+| 元素 | 状态 | 说明 |
+|------|------|------|
+| 文本框（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`→矩形 |
+| 不支持图表类型 | ⚡ 退化 | 图表部件 rels 缓存图或占位文本 |
+| 复杂动画 | 🔜 计划中 | 见设计文档 |
+
+## 安装
+
+```bash
+npm install pptx2js
+```
+
+本地开发：
+
+```bash
+git clone https://github.com/yuese12333/pptx2js.git
+cd pptx2js
+npm install
+npm test
+```
+
+## 使用方式
+
+### CLI
+
+```bash
+npx pptx2js input.pptx -o ./pptx2js-output
+```
+
+常用参数：
+
+| 参数 | 默认值 | 说明 |
+|------|--------|------|
+| `input.pptx` | 必填 | 源文件路径 |
+| `-o, --output` | `./pptx2js-output` | 输出目录 |
+| `--no-media` | — | 不提取媒体，图片引用变为占位注释 |
+| `--strict-degrade` | `false` | 任意退化项触发非零退出码 |
+| `--strict-skip` | `false` | `severity:error` 跳过项触发非零退出码 |
+| `--log-level` | `info` | `minimal` / `info` / `verbose` |
+| `--max-file-size` | 50MB | 超过阈值切换流式解析（实现中） |
+
+> **注意：** Commander 的 `--no-media` 对应内部选项 `media`（默认 `true`）。传入 `--no-media` 后 `media` 为 `false`，才会跳过媒体提取。
+
+### 编程 API
+
+```javascript
+const { convert } = require('pptx2js');
+
+const result = await convert('./input.pptx', {
+  outputDir: './pptx2js-output',
+  logLevel: 'info',
+});
+
+console.log(result.scriptPath);  // .../output.js
+console.log(result.logPath);     // .../conversion.log
+console.log(result.log.statistics);
+```
+
+### 运行生成脚本
+
+`output.js` 依赖 [PptxGenJS](https://github.com/gitbrent/PptxGenJS)，需在输出目录单独安装：
+
+```bash
+cd pptx2js-output
+npm init -y
+npm install pptxgenjs
+node output.js   # 生成 output.pptx
+```
+
+## 输出目录结构
+
+```
+pptx2js-output/
+├── output.js          # 主生成脚本，可直接 node 运行
+├── media/             # 提取的图片等媒体
+├── conversion.log     # JSON 格式转换报告
+└── README.md          # 自动生成的说明
+```
+
+`conversion.log` 主要字段：`source`、`statistics`、`slides[]`、`degraded[]`、`omitted[]`、`warnings[]`。
+
+## 系统架构
+
+六模块流水线（顺序执行）：
+
+```
+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/mapper.js)
+  → ⑤ 代码生成器      (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`。
+
+## 技术栈
+
+| 用途 | 选型 |
+|------|------|
+| ZIP 处理 | [JSZip](https://www.npmjs.com/package/jszip) |
+| XML 解析 | [xml2js](https://www.npmjs.com/package/xml2js)（统一配置，见 `lib/xml-parser.js`） |
+| CLI | [Commander.js](https://www.npmjs.com/package/commander) |
+| 终端输出 | [chalk](https://www.npmjs.com/package/chalk) |
+| 测试 | [Jest](https://jestjs.io/)（单元 + 集成） |
+
+代码格式化在生成阶段自实现缩进拼接，不引入 Prettier。
+
+## 开发
+
+```bash
+npm test              # 单元测试 + 集成测试（24 用例）
+npm run test:watch    # 监听模式
+```
+
+### 目录结构
+
+```
+pptx2js/
+├── bin/pptx2js.js          # CLI 入口
+├── lib/
+│   ├── index.js            # 库入口（export convert）
+│   ├── convert.js          # 流水线编排
+│   ├── unpacker.js         # ① 解压
+│   ├── xml-parser.js       # ② 统一 XML 解析
+│   ├── rels.js             # ② 关系索引
+│   ├── presentation.js     # 幻灯片列表 / 尺寸
+│   ├── placeholder.js    # 母版/版式占位符继承
+│   ├── graphic.js          # graphicFrame URI 识别
+│   ├── table.js            # 表格提取
+│   ├── chart.js            # 图表提取
+│   ├── smartart.js         # SmartArt 退化
+│   ├── extractor.js        # ③ 实体提取
+│   ├── mapper.js           # ④ IR 映射
+│   ├── codegen.js          # ⑤ 代码生成
+│   ├── packager.js         # ⑥ 资源打包
+│   ├── xml-utils.js
+│   └── utils/              # EMU、颜色、坐标
+├── test/
+│   ├── unit/
+│   ├── integration/
+│   └── helpers/            # 最小 PPTX 构造
+├── design.html             # 完整设计文档
+└── README.html             # 本页 HTML 版
+```
+
+## 已知局限
+
+1. **字体**依赖运行环境，不负责检测或打包嵌入字体  
+2. **母版继承**已实现 xfrm 与基础 txBody 补全；复杂段落/列表样式继承仍有限；`a:spcPct` 百分比段距/行距暂不处理  
+3. **SmartArt** 仅文本列表退化，缓存图片路径因 PPT 版本差异未实现  
+4. **动画**尚未转换（设计为退化淡入，待实现）  
+5. **不保证**往返 PPTX 二进制一致，追求视觉可接受  
+6. **不支持**密码保护或 `.ppt` 旧格式  
+7. **不支持**增量转换，每次全量重写  
+8. **大文件**（200MB+）可能内存压力较大，超过 50MB 流式解析仍在实现中  
+9. **媒体重名**不同路径同名图片可能互相覆盖（`packager` 待实现去重）
+
+## 项目状态
+
+当前为 **v0.4.0**：在 v0.3.0 基础上新增段落级格式（对齐、`lvl`、段距、行距）、表格单元格边框、扩展图表类型、SmartArt 文本列表退化。复杂动画、SmartArt 缓存图、外部链接表格等按 [`design.html`](./design.html) 继续推进，欢迎贡献。
+
+## License
+
+MIT

package/bin/pptx2js.js

@@ -0,0 +1,75 @@
+#!/usr/bin/env node
+/**
+ * CLI 入口 — 对 lib/convert 的薄封装，不含独立业务逻辑。
+ */
+const path = require('path');
+const chalk = require('chalk');
+const { Command } = require('commander');
+const { convert, DEFAULT_OUTPUT, DEFAULT_MAX_FILE_SIZE } = require('../lib');
+
+const program = new Command();
+
+program
+  .name('pptx2js')
+  .description('将 .pptx 文件转换为可运行的 PptxGenJS 生成脚本')
+  .version(require('../package.json').version)
+  .argument('<input>', '源 PPTX 文件路径')
+  .option('-o, --output <dir>', '输出目录', DEFAULT_OUTPUT)
+  .option('--no-media', '不提取媒体文件')
+  .option('--strict-degrade', '任意退化项触发非零退出码')
+  .option('--strict-skip', 'severity:error 级别的跳过项触发非零退出码')
+  .option(
+    '--log-level <level>',
+    '日志详细程度：minimal / info / verbose',
+    'info'
+  )
+  .option(
+    '--max-file-size <bytes>',
+    '超过此阈值时切换为逐幻灯片流式解析',
+    String(DEFAULT_MAX_FILE_SIZE)
+  )
+  .action(async (input, opts) => {
+    const logLevel = opts.logLevel;
+    const verbose = logLevel === 'verbose';
+
+    try {
+      if (verbose) {
+        console.log(chalk.gray(`输入: ${path.resolve(input)}`));
+        console.log(chalk.gray(`输出: ${path.resolve(opts.output)}`));
+      }
+
+      const result = await convert(input, {
+        outputDir: opts.output,
+        // Commander: --no-media → opts.media（默认 true，加 --no-media 后为 false）
+        noMedia: !opts.media,
+        strictDegrade: opts.strictDegrade,
+        strictSkip: opts.strictSkip,
+        logLevel,
+        maxFileSize: parseInt(opts.maxFileSize, 10),
+      });
+
+      console.log(chalk.green('转换完成'));
+      console.log(chalk.gray(`  脚本: ${result.scriptPath}`));
+      console.log(chalk.gray(`  日志: ${result.logPath}`));
+
+      const { statistics, warnings } = result.log;
+      if (logLevel !== 'minimal') {
+        console.log(
+          chalk.gray(
+            `  统计: ${statistics.slides} 张幻灯片, ` +
+              `精确 ${statistics.full}, 退化 ${statistics.degraded}, 跳过 ${statistics.skipped}`
+          )
+        );
+      }
+      if (warnings?.length && logLevel === 'verbose') {
+        for (const w of warnings) {
+          console.log(chalk.yellow(`  ⚠ ${w.message}`));
+        }
+      }
+    } catch (err) {
+      console.error(chalk.red(err.message || String(err)));
+      process.exit(1);
+    }
+  });
+
+program.parse();

package/lib/chart.js

@@ -0,0 +1,245 @@
+/**
+ * 图表提取（design.html §4.3）
+ */
+const path = require('path');
+const { asArray, attr, child, textContent } = require('./xml-utils');
+const { getGraphicXfrm } = require('./graphic');
+const { boundsFromXfrm } = require('./utils/bounds');
+
+const CHART_NS_BAR = 'barChart';
+const CHART_NS_LINE = 'lineChart';
+const CHART_NS_PIE = 'pieChart';
+
+const PPTX_TO_PPTGEN = {
+  barChart: 'BAR',
+  lineChart: 'LINE',
+  pieChart: 'PIE',
+  areaChart: 'AREA',
+  doughnutChart: 'DOUGHNUT',
+  scatterChart: 'SCATTER',
+  radarChart: 'RADAR',
+  bubbleChart: 'BUBBLE',
+};
+
+/**
+ * @param {object} graphicFrame
+ * @param {object} ctx
+ * @returns {import('./extractor').SlideEntity|null}
+ */
+function extractChart(graphicFrame, ctx) {
+  const bounds = boundsFromGraphicFrame(graphicFrame, ctx.offset);
+  const graphicData = child(child(graphicFrame, 'a:graphic'), 'a:graphicData');
+  const chartEl = child(graphicData, 'c:chart');
+  const relId = attr(chartEl, 'r:id');
+
+  if (!relId) {
+    return chartFallback(graphicFrame, ctx, bounds, '图表缺少关系 ID');
+  }
+
+  const chartPath = ctx.relIndex.resolve(ctx.slidePath, relId);
+  if (!chartPath || !ctx.parsed[chartPath]) {
+    return chartFallback(graphicFrame, ctx, bounds, '无法解析图表 XML');
+  }
+
+  const chartDoc = ctx.parsed[chartPath];
+  const chartSpace = child(chartDoc, 'c:chartSpace') ?? chartDoc;
+  const chartRoot = child(chartSpace, 'c:chart');
+  const plotArea = child(chartRoot, 'c:plotArea');
+
+  const parsed = parseChartPlotArea(plotArea);
+  if (parsed) {
+    return {
+      slideIndex: ctx.slideIndex,
+      slidePath: ctx.slidePath,
+      decision: 'FULL',
+      kind: 'chart',
+      bounds,
+      chart: parsed,
+    };
+  }
+
+  return chartFallback(graphicFrame, ctx, bounds, '不支持的图表类型');
+}
+
+/**
+ * @param {object|null|undefined} plotArea
+ */
+function parseChartPlotArea(plotArea) {
+  if (!plotArea) return null;
+
+  for (const [xmlName, pptxType] of Object.entries(PPTX_TO_PPTGEN)) {
+    const chartNode = child(plotArea, `c:${xmlName}`);
+    if (!chartNode) continue;
+
+    const series = extractSeries(chartNode, plotArea);
+    if (!series.length) continue;
+
+    const title = extractChartTitle(plotArea);
+    return {
+      type: pptxType,
+      data: series,
+      title,
+    };
+  }
+  return null;
+}
+
+/**
+ * @param {object} chartNode c:barChart 等
+ * @param {object} plotArea
+ */
+function extractSeries(chartNode, plotArea) {
+  const result = [];
+  const seriesNodes = asArray(chartNode['c:ser']);
+
+  for (const ser of seriesNodes) {
+    const titleText = extractSeriesName(ser);
+    const cat = extractCategoryLabels(ser, plotArea);
+    const values = extractSeriesValues(ser, plotArea);
+    if (!values.length) continue;
+
+    result.push({
+      name: titleText || `Series ${result.length + 1}`,
+      labels: cat.length ? cat : values.map((_, i) => String(i + 1)),
+      values,
+    });
+  }
+  return result;
+}
+
+/**
+ * @param {object} ser
+ */
+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];
+  return pt ? textContent(child(pt, 'c:v')) : '';
+}
+
+/**
+ * @param {object} ser
+ * @param {object} plotArea
+ */
+function extractCategoryLabels(ser, plotArea) {
+  void plotArea;
+  const cat = child(ser, 'c:cat');
+  if (!cat) return [];
+  const strRef = child(cat, 'c:strRef');
+  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);
+  return [];
+}
+
+/**
+ * @param {object} ser
+ * @param {object} plotArea
+ */
+function extractSeriesValues(ser, plotArea) {
+  void plotArea;
+  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);
+}
+
+/**
+ * @param {object} refNode
+ * @param {string} cacheKey
+ * @param {string} valueKey
+ */
+function extractCachePoints(refNode, cacheKey, valueKey) {
+  const cache = child(refNode, cacheKey);
+  const pts = asArray(child(cache, '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
+ */
+function extractChartTitle(plotArea) {
+  const title = child(plotArea, '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']));
+    }
+  }
+  return parts.join('');
+}
+
+/**
+ * 缓存图片 → 图片插入；否则占位文本
+ * @param {object} graphicFrame
+ * @param {object} ctx
+ * @param {object} bounds
+ * @param {string} reason
+ */
+function chartFallback(graphicFrame, ctx, bounds, reason) {
+  const cached = findChartCacheImage(graphicFrame, ctx);
+  if (cached) {
+    return {
+      slideIndex: ctx.slideIndex,
+      slidePath: ctx.slidePath,
+      decision: 'DEGRADE',
+      kind: 'image',
+      bounds,
+      image: cached,
+      degradeReason: `${reason}，已使用缓存图片`,
+    };
+  }
+
+  return {
+    slideIndex: ctx.slideIndex,
+    slidePath: ctx.slidePath,
+    decision: 'DEGRADE',
+    kind: 'text',
+    bounds,
+    text: {
+      runs: [{ text: `[图表] ${reason}`, options: { fontSize: 12, color: '888888' } }],
+    },
+    degradeReason: reason,
+  };
+}
+
+/**
+ * @param {object} graphicFrame
+ * @param {object} ctx
+ */
+function findChartCacheImage(graphicFrame, ctx) {
+  const graphicData = child(child(graphicFrame, 'a:graphic'), 'a:graphicData');
+  const chartEl = child(graphicData, 'c:chart');
+  const chartRelId = attr(chartEl, 'r:id');
+  const chartPath =
+    chartRelId && ctx.relIndex.resolve(ctx.slidePath, chartRelId);
+  if (!chartPath) return null;
+
+  for (const rel of ctx.relIndex.list(chartPath)) {
+    if (!rel.target.match(/\.(png|jpe?g|gif)$/i)) continue;
+    if (rel.type && rel.type.includes('image')) {
+      return {
+        zipPath: rel.target,
+        fileName: path.posix.basename(rel.target),
+      };
+    }
+  }
+  return null;
+}
+
+/**
+ * @param {object} graphicFrame
+ * @param {{ x: number, y: number }} offset
+ */
+function boundsFromGraphicFrame(graphicFrame, offset) {
+  return boundsFromXfrm(getGraphicXfrm(graphicFrame), offset);
+}
+
+module.exports = { extractChart, parseChartPlotArea, PPTX_TO_PPTGEN };

package/lib/codegen.js

@@ -0,0 +1,172 @@
+/**
+ * ⑤ 代码生成器 — IR → PptxGenJS 脚本
+ */
+
+function generateScript(ir, options = {}) {
+  const lines = [];
+  const indent = (n) => '  '.repeat(n);
+
+  lines.push("const path = require('path');");
+  lines.push("const PptxGenJS = require('pptxgenjs');");
+  lines.push('');
+  lines.push('async function main() {');
+  lines.push(`${indent(1)}const pptx = new PptxGenJS();`);
+  lines.push('');
+
+  const { width = 10, height = 7.5 } = ir.layout ?? {};
+  lines.push(
+    `${indent(1)}pptx.defineLayout({ name: 'PPTX_IMPORT', width: ${width}, height: ${height} });`
+  );
+  lines.push(`${indent(1)}pptx.layout = 'PPTX_IMPORT';`);
+  lines.push('');
+
+  ir.slides.forEach((slide, i) => {
+    const varName = `slide${i}`;
+    lines.push(`${indent(1)}const ${varName} = pptx.addSlide();`);
+
+    if (slide.background?.color) {
+      lines.push(
+        `${indent(1)}${varName}.background = { color: '${escapeJs(slide.background.color)}' };`
+      );
+    }
+
+    for (const el of slide.elements) {
+      lines.push(...emitElement(el, varName, indent, options));
+    }
+    lines.push('');
+  });
+
+  lines.push(`${indent(1)}await pptx.writeFile({ fileName: 'output.pptx' });`);
+  lines.push('}');
+  lines.push('');
+  lines.push('main().catch((err) => {');
+  lines.push(`${indent(1)}console.error(err);`);
+  lines.push(`${indent(1)}process.exit(1);`);
+  lines.push('});');
+  lines.push('');
+
+  return lines.join('\n');
+}
+
+function emitElement(el, slideVar, indent, options) {
+  const { x, y, w, h } = el.bounds ?? { x: 0, y: 0, w: 0, h: 0 };
+  const pos = `x: ${x}, y: ${y}, w: ${w}, h: ${h}`;
+
+  if (el.type === 'skip') {
+    return [`${indent(1)}// [skipped] ${escapeJs(el.skipReason ?? 'unsupported')}`];
+  }
+
+  if (el.type === 'text') {
+    return [`${indent(1)}${slideVar}.addText(${formatTextRuns(el.runs)}, { ${pos} });`];
+  }
+
+  if (el.type === 'image') {
+    if (options.noMedia) {
+      return [`${indent(1)}// [no-media] ${escapeJs(el.mediaPath ?? 'image')}`];
+    }
+    const imgPath = `path.join(__dirname, '${escapeJs(el.mediaPath)}')`;
+    return [`${indent(1)}${slideVar}.addImage({ path: ${imgPath}, ${pos} });`];
+  }
+
+  if (el.type === 'table') {
+    const rowsLit = formatTableRows(el.rows);
+    const opts = [pos];
+    if (el.colWidths?.length) {
+      opts.push(`colW: [${el.colWidths.join(', ')}]`);
+    }
+    return [`${indent(1)}${slideVar}.addTable(${rowsLit}, { ${opts.join(', ')} });`];
+  }
+
+  if (el.type === 'chart') {
+    const dataLit = JSON.stringify(el.data);
+    const opts = [`${pos}`];
+    if (el.title) opts.push(`title: '${escapeJs(el.title)}'`);
+    return [
+      `${indent(1)}${slideVar}.addChart(pptx.charts.${el.chartType}, ${dataLit}, { ${opts.join(', ')} });`,
+    ];
+  }
+
+  if (el.type === 'shape') {
+    const shapeRef = `pptx.shapes.${el.shape}`;
+    const opts = [pos];
+    if (el.fill) opts.push(`fill: { color: '${escapeJs(el.fill)}' }`);
+    if (el.line) opts.push(`line: { color: '${escapeJs(el.line)}', width: 1 }`);
+    return [`${indent(1)}${slideVar}.addShape(${shapeRef}, { ${opts.join(', ')} });`];
+  }
+
+  return [];
+}
+
+function formatTableRows(rows) {
+  const mapped = rows.map((row) =>
+    row.map((cell) => {
+      const parts = [`text: '${escapeJs(cell.text ?? '')}'`];
+      const optKeys = Object.keys(cell.options ?? {});
+      if (optKeys.length) {
+        parts.push(`options: ${JSON.stringify(cell.options)}`);
+      }
+      return `{ ${parts.join(', ')} }`;
+    })
+  );
+  return `[\n    ${mapped.map((r) => `[${r.join(', ')}]`).join(',\n    ')}\n  ]`;
+}
+
+function formatTextRuns(runs) {
+  if (!runs?.length) return "''";
+
+  const parts = runs.map((run) => {
+    const text = escapeJs(run.text ?? '');
+    const opts = formatRunOptions(run.options ?? {});
+    if (opts === '{}') {
+      return `{ text: '${text}' }`;
+    }
+    return `{ text: '${text}', options: ${opts} }`;
+  });
+
+  if (parts.length === 1 && !parts[0].includes('options:')) {
+    return `'${escapeJs(runs[0].text ?? '')}'`;
+  }
+
+  return `[\n    ${parts.join(',\n    ')}\n  ]`;
+}
+
+function formatRunOptions(options) {
+  const copy = { ...options };
+  delete copy._degraded;
+  const entries = [];
+  if (copy.fontSize != null) entries.push(`fontSize: ${copy.fontSize}`);
+  if (copy.bold) entries.push('bold: true');
+  if (copy.italic) entries.push('italic: true');
+  if (copy.fontFace) entries.push(`fontFace: '${escapeJs(String(copy.fontFace))}'`);
+  if (copy.color) entries.push(`color: '${escapeJs(String(copy.color))}'`);
+  if (copy.bullet === true) entries.push('bullet: true');
+  if (copy.bullet && typeof copy.bullet === 'object') {
+    entries.push(`bullet: { type: '${copy.bullet.type ?? 'number'}' }`);
+  }
+  if (copy.hyperlink?.url) {
+    entries.push(`hyperlink: { url: '${escapeJs(copy.hyperlink.url)}' }`);
+  }
+  if (copy.align) entries.push(`align: '${escapeJs(String(copy.align))}'`);
+  if (copy.indentLevel != null && copy.indentLevel > 0) {
+    entries.push(`indentLevel: ${copy.indentLevel}`);
+  }
+  if (copy.paraSpaceBefore != null) {
+    entries.push(`paraSpaceBefore: ${copy.paraSpaceBefore}`);
+  }
+  if (copy.paraSpaceAfter != null) {
+    entries.push(`paraSpaceAfter: ${copy.paraSpaceAfter}`);
+  }
+  if (copy.lineSpacing != null) entries.push(`lineSpacing: ${copy.lineSpacing}`);
+  if (entries.length === 0) return '{}';
+  return `{ ${entries.join(', ')} }`;
+}
+
+function escapeJs(s) {
+  return String(s)
+    .replace(/\\/g, '\\\\')
+    .replace(/'/g, "\\'")
+    .replace(/\r/g, '\\r')
+    .replace(/\n/g, '\\n');
+}
+
+module.exports = { generateScript, escapeJs, formatTableRows };