@xiaobuyu/nodesign 0.0.1 → 0.0.3

package/server/lib/docx/rawzip.js

@@ -1,172 +1,172 @@
-/**
- * rawzip.js — 面向 docx 的最小 ZIP 读写器，核心卖点是「保真」：
- * 没被替换的 entry，local header + 压缩数据 + data descriptor 原样字节拷贝；
- * 只有被替换/新增的 entry 走 zlib deflateRaw 重压。
- *
- * 覆盖范围 = OOXML 容器实际会遇到的:
- *   - 方法 0 (store) / 8 (deflate)
- *   - bit3 data descriptor（流式写出的 zip）
- *   - 不支持 zip64 / 加密 / 分卷（docx 不会用；遇到即抛错，调用方退回只读）
- */
-
-import { deflateRawSync, inflateRawSync } from 'node:zlib';
-import { crc32 } from 'node:zlib';
-
-const EOCD_SIG = 0x06054b50;
-const CEN_SIG = 0x02014b50;
-const LOC_SIG = 0x04034b50;
-
-/**
- * @param {Buffer} buf
- * @returns {{ entries: Map<string, Entry>, order: string[] }}
- * Entry = { name, method, crc, csize, usize, flags, cenExtra..., locRaw:Buffer|null, replaced:Buffer|null }
- */
-export function readZip(buf) {
-  // 找 EOCD（从尾部回扫，容忍 comment）
-  let eocd = -1;
-  for (let i = buf.length - 22; i >= Math.max(0, buf.length - 22 - 65535); i--) {
-    if (buf.readUInt32LE(i) === EOCD_SIG) { eocd = i; break; }
-  }
-  if (eocd < 0) throw new Error('EOCD not found (not a zip)');
-  const count = buf.readUInt16LE(eocd + 10);
-  const cenOfs = buf.readUInt32LE(eocd + 16);
-  if (cenOfs === 0xffffffff) throw new Error('zip64 not supported');
-
-  const entries = new Map();
-  const order = [];
-  let p = cenOfs;
-  for (let i = 0; i < count; i++) {
-    if (buf.readUInt32LE(p) !== CEN_SIG) throw new Error(`bad central dir at ${p}`);
-    const flags = buf.readUInt16LE(p + 8);
-    const method = buf.readUInt16LE(p + 10);
-    const mtime = buf.readUInt16LE(p + 12);
-    const mdate = buf.readUInt16LE(p + 14);
-    const crc = buf.readUInt32LE(p + 16);
-    const csize = buf.readUInt32LE(p + 20);
-    const usize = buf.readUInt32LE(p + 24);
-    const nameLen = buf.readUInt16LE(p + 28);
-    const extraLen = buf.readUInt16LE(p + 30);
-    const commentLen = buf.readUInt16LE(p + 32);
-    const attrs = buf.readUInt32LE(p + 38);
-    const locOfs = buf.readUInt32LE(p + 42);
-    const name = buf.toString('utf8', p + 46, p + 46 + nameLen);
-    if ((flags & 0x1) !== 0) throw new Error('encrypted zip not supported');
-    if (csize === 0xffffffff || usize === 0xffffffff) throw new Error('zip64 not supported');
-
-    // local header：算出这个 entry 的完整原始片段 [local header + data (+ descriptor)]
-    if (buf.readUInt32LE(locOfs) !== LOC_SIG) throw new Error(`bad local header for ${name}`);
-    const locNameLen = buf.readUInt16LE(locOfs + 26);
-    const locExtraLen = buf.readUInt16LE(locOfs + 28);
-    const dataStart = locOfs + 30 + locNameLen + locExtraLen;
-    let rawEnd = dataStart + csize;
-    if (flags & 0x8) {
-      // data descriptor: 可带可不带签名 0x08074b50
-      if (buf.readUInt32LE(rawEnd) === 0x08074b50) rawEnd += 16; else rawEnd += 12;
-    }
-    const entry = {
-      name, flags, method, mtime, mdate, crc, csize, usize, attrs,
-      cenExtra: Buffer.from(buf.subarray(p + 46 + nameLen, p + 46 + nameLen + extraLen)),
-      comment: Buffer.from(buf.subarray(p + 46 + nameLen + extraLen, p + 46 + nameLen + extraLen + commentLen)),
-      locRaw: Buffer.from(buf.subarray(locOfs, rawEnd)),
-      dataOfs: dataStart - locOfs,
-      replaced: null,
-    };
-    entries.set(name, entry);
-    order.push(name);
-    p += 46 + nameLen + extraLen + commentLen;
-  }
-  return { entries, order };
-}
-
-export function entryData(zip, name) {
-  const e = zip.entries.get(name);
-  if (!e) return null;
-  if (e.replaced) return e.replaced;
-  const raw = e.locRaw.subarray(e.dataOfs, e.dataOfs + e.csize);
-  if (e.method === 0) return Buffer.from(raw);
-  if (e.method === 8) return inflateRawSync(raw);
-  throw new Error(`unsupported method ${e.method} for ${name}`);
-}
-
-export function replaceEntry(zip, name, content) {
-  const e = zip.entries.get(name);
-  if (!e) throw new Error(`no such entry: ${name}`);
-  e.replaced = Buffer.isBuffer(content) ? content : Buffer.from(content, 'utf8');
-}
-
-export function addEntry(zip, name, content) {
-  if (zip.entries.has(name)) return replaceEntry(zip, name, content);
-  const e = {
-    name, flags: 0x800 /* utf8 name */, method: 8, mtime: 0, mdate: 0x2100 /* 1996-08-00 stable */,
-    crc: 0, csize: 0, usize: 0, attrs: 0,
-    cenExtra: Buffer.alloc(0), comment: Buffer.alloc(0),
-    locRaw: null, dataOfs: 0,
-    replaced: Buffer.isBuffer(content) ? content : Buffer.from(content, 'utf8'),
-  };
-  zip.entries.set(name, e);
-  zip.order.push(name);
-}
-
-export function writeZip(zip) {
-  const chunks = [];
-  const cen = [];
-  let offset = 0;
-  for (const name of zip.order) {
-    const e = zip.entries.get(name);
-    let locBuf; let crc; let csize; let usize; let method; let flags;
-    if (e.replaced == null) {
-      locBuf = e.locRaw;                       // 原样拷贝（保真核心）
-      crc = e.crc; csize = e.csize; usize = e.usize; method = e.method; flags = e.flags;
-    } else {
-      const data = e.replaced;
-      const packed = deflateRawSync(data, { level: 9 });
-      method = packed.length < data.length ? 8 : 0;
-      const body = method === 8 ? packed : data;
-      crc = crc32(data) >>> 0;
-      csize = body.length; usize = data.length;
-      flags = 0x800; // utf8 filename，不用 descriptor
-      const nameBuf = Buffer.from(name, 'utf8');
-      const head = Buffer.alloc(30);
-      head.writeUInt32LE(LOC_SIG, 0);
-      head.writeUInt16LE(20, 4);       // version needed
-      head.writeUInt16LE(flags, 6);
-      head.writeUInt16LE(method, 8);
-      head.writeUInt16LE(e.mtime, 10);
-      head.writeUInt16LE(e.mdate, 12);
-      head.writeUInt32LE(crc, 14);
-      head.writeUInt32LE(csize, 18);
-      head.writeUInt32LE(usize, 22);
-      head.writeUInt16LE(nameBuf.length, 26);
-      head.writeUInt16LE(0, 28);
-      locBuf = Buffer.concat([head, nameBuf, body]);
-    }
-    const nameBuf = Buffer.from(name, 'utf8');
-    const c = Buffer.alloc(46);
-    c.writeUInt32LE(CEN_SIG, 0);
-    c.writeUInt16LE(20, 4); c.writeUInt16LE(20, 6);
-    c.writeUInt16LE(flags, 8);
-    c.writeUInt16LE(method, 10);
-    c.writeUInt16LE(e.mtime, 12); c.writeUInt16LE(e.mdate, 14);
-    c.writeUInt32LE(crc, 16);
-    c.writeUInt32LE(csize, 20); c.writeUInt32LE(usize, 24);
-    c.writeUInt16LE(nameBuf.length, 28);
-    c.writeUInt16LE(e.cenExtra.length, 30);
-    c.writeUInt16LE(e.comment.length, 32);
-    c.writeUInt32LE(e.attrs, 38);
-    c.writeUInt32LE(offset, 42);
-    cen.push(Buffer.concat([c, nameBuf, e.cenExtra, e.comment]));
-    chunks.push(locBuf);
-    offset += locBuf.length;
-  }
-  const cenStart = offset;
-  let cenSize = 0;
-  for (const c of cen) { chunks.push(c); cenSize += c.length; }
-  const eocd = Buffer.alloc(22);
-  eocd.writeUInt32LE(EOCD_SIG, 0);
-  eocd.writeUInt16LE(zip.order.length, 8);
-  eocd.writeUInt16LE(zip.order.length, 10);
-  eocd.writeUInt32LE(cenSize, 12);
-  eocd.writeUInt32LE(cenStart, 16);
-  chunks.push(eocd);
-  return Buffer.concat(chunks);
-}
+/**
+ * rawzip.js — 面向 docx 的最小 ZIP 读写器，核心卖点是「保真」：
+ * 没被替换的 entry，local header + 压缩数据 + data descriptor 原样字节拷贝；
+ * 只有被替换/新增的 entry 走 zlib deflateRaw 重压。
+ *
+ * 覆盖范围 = OOXML 容器实际会遇到的:
+ *   - 方法 0 (store) / 8 (deflate)
+ *   - bit3 data descriptor（流式写出的 zip）
+ *   - 不支持 zip64 / 加密 / 分卷（docx 不会用；遇到即抛错，调用方退回只读）
+ */
+
+import { deflateRawSync, inflateRawSync } from 'node:zlib';
+import { crc32 } from 'node:zlib';
+
+const EOCD_SIG = 0x06054b50;
+const CEN_SIG = 0x02014b50;
+const LOC_SIG = 0x04034b50;
+
+/**
+ * @param {Buffer} buf
+ * @returns {{ entries: Map<string, Entry>, order: string[] }}
+ * Entry = { name, method, crc, csize, usize, flags, cenExtra..., locRaw:Buffer|null, replaced:Buffer|null }
+ */
+export function readZip(buf) {
+  // 找 EOCD（从尾部回扫，容忍 comment）
+  let eocd = -1;
+  for (let i = buf.length - 22; i >= Math.max(0, buf.length - 22 - 65535); i--) {
+    if (buf.readUInt32LE(i) === EOCD_SIG) { eocd = i; break; }
+  }
+  if (eocd < 0) throw new Error('EOCD not found (not a zip)');
+  const count = buf.readUInt16LE(eocd + 10);
+  const cenOfs = buf.readUInt32LE(eocd + 16);
+  if (cenOfs === 0xffffffff) throw new Error('zip64 not supported');
+
+  const entries = new Map();
+  const order = [];
+  let p = cenOfs;
+  for (let i = 0; i < count; i++) {
+    if (buf.readUInt32LE(p) !== CEN_SIG) throw new Error(`bad central dir at ${p}`);
+    const flags = buf.readUInt16LE(p + 8);
+    const method = buf.readUInt16LE(p + 10);
+    const mtime = buf.readUInt16LE(p + 12);
+    const mdate = buf.readUInt16LE(p + 14);
+    const crc = buf.readUInt32LE(p + 16);
+    const csize = buf.readUInt32LE(p + 20);
+    const usize = buf.readUInt32LE(p + 24);
+    const nameLen = buf.readUInt16LE(p + 28);
+    const extraLen = buf.readUInt16LE(p + 30);
+    const commentLen = buf.readUInt16LE(p + 32);
+    const attrs = buf.readUInt32LE(p + 38);
+    const locOfs = buf.readUInt32LE(p + 42);
+    const name = buf.toString('utf8', p + 46, p + 46 + nameLen);
+    if ((flags & 0x1) !== 0) throw new Error('encrypted zip not supported');
+    if (csize === 0xffffffff || usize === 0xffffffff) throw new Error('zip64 not supported');
+
+    // local header：算出这个 entry 的完整原始片段 [local header + data (+ descriptor)]
+    if (buf.readUInt32LE(locOfs) !== LOC_SIG) throw new Error(`bad local header for ${name}`);
+    const locNameLen = buf.readUInt16LE(locOfs + 26);
+    const locExtraLen = buf.readUInt16LE(locOfs + 28);
+    const dataStart = locOfs + 30 + locNameLen + locExtraLen;
+    let rawEnd = dataStart + csize;
+    if (flags & 0x8) {
+      // data descriptor: 可带可不带签名 0x08074b50
+      if (buf.readUInt32LE(rawEnd) === 0x08074b50) rawEnd += 16; else rawEnd += 12;
+    }
+    const entry = {
+      name, flags, method, mtime, mdate, crc, csize, usize, attrs,
+      cenExtra: Buffer.from(buf.subarray(p + 46 + nameLen, p + 46 + nameLen + extraLen)),
+      comment: Buffer.from(buf.subarray(p + 46 + nameLen + extraLen, p + 46 + nameLen + extraLen + commentLen)),
+      locRaw: Buffer.from(buf.subarray(locOfs, rawEnd)),
+      dataOfs: dataStart - locOfs,
+      replaced: null,
+    };
+    entries.set(name, entry);
+    order.push(name);
+    p += 46 + nameLen + extraLen + commentLen;
+  }
+  return { entries, order };
+}
+
+export function entryData(zip, name) {
+  const e = zip.entries.get(name);
+  if (!e) return null;
+  if (e.replaced) return e.replaced;
+  const raw = e.locRaw.subarray(e.dataOfs, e.dataOfs + e.csize);
+  if (e.method === 0) return Buffer.from(raw);
+  if (e.method === 8) return inflateRawSync(raw);
+  throw new Error(`unsupported method ${e.method} for ${name}`);
+}
+
+export function replaceEntry(zip, name, content) {
+  const e = zip.entries.get(name);
+  if (!e) throw new Error(`no such entry: ${name}`);
+  e.replaced = Buffer.isBuffer(content) ? content : Buffer.from(content, 'utf8');
+}
+
+export function addEntry(zip, name, content) {
+  if (zip.entries.has(name)) return replaceEntry(zip, name, content);
+  const e = {
+    name, flags: 0x800 /* utf8 name */, method: 8, mtime: 0, mdate: 0x2100 /* 1996-08-00 stable */,
+    crc: 0, csize: 0, usize: 0, attrs: 0,
+    cenExtra: Buffer.alloc(0), comment: Buffer.alloc(0),
+    locRaw: null, dataOfs: 0,
+    replaced: Buffer.isBuffer(content) ? content : Buffer.from(content, 'utf8'),
+  };
+  zip.entries.set(name, e);
+  zip.order.push(name);
+}
+
+export function writeZip(zip) {
+  const chunks = [];
+  const cen = [];
+  let offset = 0;
+  for (const name of zip.order) {
+    const e = zip.entries.get(name);
+    let locBuf; let crc; let csize; let usize; let method; let flags;
+    if (e.replaced == null) {
+      locBuf = e.locRaw;                       // 原样拷贝（保真核心）
+      crc = e.crc; csize = e.csize; usize = e.usize; method = e.method; flags = e.flags;
+    } else {
+      const data = e.replaced;
+      const packed = deflateRawSync(data, { level: 9 });
+      method = packed.length < data.length ? 8 : 0;
+      const body = method === 8 ? packed : data;
+      crc = crc32(data) >>> 0;
+      csize = body.length; usize = data.length;
+      flags = 0x800; // utf8 filename，不用 descriptor
+      const nameBuf = Buffer.from(name, 'utf8');
+      const head = Buffer.alloc(30);
+      head.writeUInt32LE(LOC_SIG, 0);
+      head.writeUInt16LE(20, 4);       // version needed
+      head.writeUInt16LE(flags, 6);
+      head.writeUInt16LE(method, 8);
+      head.writeUInt16LE(e.mtime, 10);
+      head.writeUInt16LE(e.mdate, 12);
+      head.writeUInt32LE(crc, 14);
+      head.writeUInt32LE(csize, 18);
+      head.writeUInt32LE(usize, 22);
+      head.writeUInt16LE(nameBuf.length, 26);
+      head.writeUInt16LE(0, 28);
+      locBuf = Buffer.concat([head, nameBuf, body]);
+    }
+    const nameBuf = Buffer.from(name, 'utf8');
+    const c = Buffer.alloc(46);
+    c.writeUInt32LE(CEN_SIG, 0);
+    c.writeUInt16LE(20, 4); c.writeUInt16LE(20, 6);
+    c.writeUInt16LE(flags, 8);
+    c.writeUInt16LE(method, 10);
+    c.writeUInt16LE(e.mtime, 12); c.writeUInt16LE(e.mdate, 14);
+    c.writeUInt32LE(crc, 16);
+    c.writeUInt32LE(csize, 20); c.writeUInt32LE(usize, 24);
+    c.writeUInt16LE(nameBuf.length, 28);
+    c.writeUInt16LE(e.cenExtra.length, 30);
+    c.writeUInt16LE(e.comment.length, 32);
+    c.writeUInt32LE(e.attrs, 38);
+    c.writeUInt32LE(offset, 42);
+    cen.push(Buffer.concat([c, nameBuf, e.cenExtra, e.comment]));
+    chunks.push(locBuf);
+    offset += locBuf.length;
+  }
+  const cenStart = offset;
+  let cenSize = 0;
+  for (const c of cen) { chunks.push(c); cenSize += c.length; }
+  const eocd = Buffer.alloc(22);
+  eocd.writeUInt32LE(EOCD_SIG, 0);
+  eocd.writeUInt16LE(zip.order.length, 8);
+  eocd.writeUInt16LE(zip.order.length, 10);
+  eocd.writeUInt32LE(cenSize, 12);
+  eocd.writeUInt32LE(cenStart, 16);
+  chunks.push(eocd);
+  return Buffer.concat(chunks);
+}

package/server/lib/docx/render.js

@@ -1,92 +1,92 @@
-/**
- * render.js — docx → PDF → PNG 的 QC 渲染链路。
- *
- * ⭐**必须是异步的。** 第一版写成 `execFileSync`，实测一份 55 页中文文档
- * 把事件循环**整整堵死 11.7 秒** —— 期间全站所有 HTTP、WebSocket 心跳、
- * agent 流式输出一起停摆。而触发它的不是"用户主动导出"，是**一张卡片滚进
- * 视口**：画布上有人放了一份长文档，所有人的站就冻一次。
- * node 是单线程，凡是要等外部进程的地方一律不许用 *Sync。
- *
- * 三条已实证的军规：
- *   1. per-run 独立 LO profile + 可写 HOME（多会话并发抢默认 profile 是必然事件）
- *   2. soffice 吃不下中文文件名 → 进场先拷成 ASCII 名
- *   3. FONTCONFIG_FILE 指向 fonts/nodesign-cjk.conf（中文字体替身映射，
- *      per-run 生效，不污染系统 fontconfig）
- *
- * ⚠️ 失败也要收摊：`mkdtemp` 一建出来就进 try，任何一步抛都在 finally 里删掉
- * scratch —— 第一版是"抛了就拿不到 res，调用方无从 cleanup"，每失败一次漏
- * 一个约 870KB 的目录在 /tmp（跟数据库抢同一个根分区）。
- */
-
-import { promises as fs } from 'node:fs';
-import { execFile } from 'node:child_process';
-import { promisify } from 'node:util';
-import { tmpdir } from 'node:os';
-import { join, dirname } from 'node:path';
-import { fileURLToPath } from 'node:url';
-// 二进制路径走启动探测（Mac/Win 的 LibreOffice 不在 PATH；没探到就原名让 ENOENT 原样报）
-import { resolveBinary } from '../../runtime/capabilities.js';
-
-const run = promisify(execFile);
-
-const HERE = dirname(fileURLToPath(import.meta.url));
-export const FONTCONF = join(HERE, 'fonts', 'nodesign-cjk.conf');
-
-/** 单份文档的渲染上限。超时的天花板同时也是"最坏情况占用一个 soffice 槽多久" */
-const SOFFICE_TIMEOUT = 120_000;
-const PDFTOPPM_TIMEOUT = 60_000;
-
-async function exists(p) {
-  try { await fs.access(p); return true; } catch { return false; }
-}
-
-/**
- * @param {string} docxPath
- * @param {object} opts { pngPages?: [from,to] | true, dpi?: number, timeoutMs?: number }
- * @returns {Promise<{ pdf: string, pngs: string[], scratch: string, ms: number }>}
- *   产物落在独立 scratch 目录里，**调用方成功拿到之后自己收**（cleanupRender）。
- *   失败的话这里已经收干净了，调用方不用管。
- */
-export async function renderDocx(docxPath, opts = {}) {
-  const scratch = await fs.mkdtemp(join(tmpdir(), 'ndocx-'));
-  const t0 = Date.now();
-  try {
-    const inFile = join(scratch, 'in.docx');       // 军规2：ASCII 文件名
-    await fs.copyFile(docxPath, inFile);
-    const env = {
-      ...process.env,
-      HOME: scratch,                                // 军规1：可写 HOME
-      FONTCONFIG_FILE: FONTCONF,                    // 军规3：字体替身
-    };
-    await run(resolveBinary('libreoffice', 'soffice'), [
-      `-env:UserInstallation=file://${scratch}/loprofile`,  // 军规1：独立 profile
-      '--headless', '--convert-to', 'pdf', '--outdir', scratch, inFile,
-    ], { env, timeout: opts.timeoutMs ?? SOFFICE_TIMEOUT });
-
-    const pdf = join(scratch, 'in.pdf');
-    if (!await exists(pdf)) throw new Error('soffice produced no pdf');
-
-    const pngs = [];
-    if (opts.pngPages) {
-      const args = ['-png', '-r', String(opts.dpi ?? 120)];
-      if (Array.isArray(opts.pngPages)) {
-        args.push('-f', String(opts.pngPages[0]), '-l', String(opts.pngPages[1]));
-      }
-      await run(resolveBinary('poppler', 'pdftoppm'), [...args, pdf, join(scratch, 'page')], { timeout: PDFTOPPM_TIMEOUT });
-      // pdftoppm 按总页数补零（55 页 → page-01…page-55），宽度统一，
-      // 所以字典序等于数字序 —— 这条核过，不是碰运气
-      for (const f of (await fs.readdir(scratch)).sort()) {
-        if (f.startsWith('page-') && f.endsWith('.png')) pngs.push(join(scratch, f));
-      }
-    }
-    return { pdf, pngs, scratch, ms: Date.now() - t0 };
-  } catch (err) {
-    await fs.rm(scratch, { recursive: true, force: true }).catch(() => {});
-    throw err;
-  }
-}
-
-export async function cleanupRender(res) {
-  if (!res?.scratch) return;
-  await fs.rm(res.scratch, { recursive: true, force: true }).catch(() => {});
-}
+/**
+ * render.js — docx → PDF → PNG 的 QC 渲染链路。
+ *
+ * ⭐**必须是异步的。** 第一版写成 `execFileSync`，实测一份 55 页中文文档
+ * 把事件循环**整整堵死 11.7 秒** —— 期间全站所有 HTTP、WebSocket 心跳、
+ * agent 流式输出一起停摆。而触发它的不是"用户主动导出"，是**一张卡片滚进
+ * 视口**：画布上有人放了一份长文档，所有人的站就冻一次。
+ * node 是单线程，凡是要等外部进程的地方一律不许用 *Sync。
+ *
+ * 三条已实证的军规：
+ *   1. per-run 独立 LO profile + 可写 HOME（多会话并发抢默认 profile 是必然事件）
+ *   2. soffice 吃不下中文文件名 → 进场先拷成 ASCII 名
+ *   3. FONTCONFIG_FILE 指向 fonts/nodesign-cjk.conf（中文字体替身映射，
+ *      per-run 生效，不污染系统 fontconfig）
+ *
+ * ⚠️ 失败也要收摊：`mkdtemp` 一建出来就进 try，任何一步抛都在 finally 里删掉
+ * scratch —— 第一版是"抛了就拿不到 res，调用方无从 cleanup"，每失败一次漏
+ * 一个约 870KB 的目录在 /tmp（跟数据库抢同一个根分区）。
+ */
+
+import { promises as fs } from 'node:fs';
+import { execFile } from 'node:child_process';
+import { promisify } from 'node:util';
+import { tmpdir } from 'node:os';
+import { join, dirname } from 'node:path';
+import { fileURLToPath } from 'node:url';
+// 二进制路径走启动探测（Mac/Win 的 LibreOffice 不在 PATH；没探到就原名让 ENOENT 原样报）
+import { resolveBinary } from '../../runtime/capabilities.js';
+
+const run = promisify(execFile);
+
+const HERE = dirname(fileURLToPath(import.meta.url));
+export const FONTCONF = join(HERE, 'fonts', 'nodesign-cjk.conf');
+
+/** 单份文档的渲染上限。超时的天花板同时也是"最坏情况占用一个 soffice 槽多久" */
+const SOFFICE_TIMEOUT = 120_000;
+const PDFTOPPM_TIMEOUT = 60_000;
+
+async function exists(p) {
+  try { await fs.access(p); return true; } catch { return false; }
+}
+
+/**
+ * @param {string} docxPath
+ * @param {object} opts { pngPages?: [from,to] | true, dpi?: number, timeoutMs?: number }
+ * @returns {Promise<{ pdf: string, pngs: string[], scratch: string, ms: number }>}
+ *   产物落在独立 scratch 目录里，**调用方成功拿到之后自己收**（cleanupRender）。
+ *   失败的话这里已经收干净了，调用方不用管。
+ */
+export async function renderDocx(docxPath, opts = {}) {
+  const scratch = await fs.mkdtemp(join(tmpdir(), 'ndocx-'));
+  const t0 = Date.now();
+  try {
+    const inFile = join(scratch, 'in.docx');       // 军规2：ASCII 文件名
+    await fs.copyFile(docxPath, inFile);
+    const env = {
+      ...process.env,
+      HOME: scratch,                                // 军规1：可写 HOME
+      FONTCONFIG_FILE: FONTCONF,                    // 军规3：字体替身
+    };
+    await run(resolveBinary('libreoffice', 'soffice'), [
+      `-env:UserInstallation=file://${scratch}/loprofile`,  // 军规1：独立 profile
+      '--headless', '--convert-to', 'pdf', '--outdir', scratch, inFile,
+    ], { env, timeout: opts.timeoutMs ?? SOFFICE_TIMEOUT });
+
+    const pdf = join(scratch, 'in.pdf');
+    if (!await exists(pdf)) throw new Error('soffice produced no pdf');
+
+    const pngs = [];
+    if (opts.pngPages) {
+      const args = ['-png', '-r', String(opts.dpi ?? 120)];
+      if (Array.isArray(opts.pngPages)) {
+        args.push('-f', String(opts.pngPages[0]), '-l', String(opts.pngPages[1]));
+      }
+      await run(resolveBinary('poppler', 'pdftoppm'), [...args, pdf, join(scratch, 'page')], { timeout: PDFTOPPM_TIMEOUT });
+      // pdftoppm 按总页数补零（55 页 → page-01…page-55），宽度统一，
+      // 所以字典序等于数字序 —— 这条核过，不是碰运气
+      for (const f of (await fs.readdir(scratch)).sort()) {
+        if (f.startsWith('page-') && f.endsWith('.png')) pngs.push(join(scratch, f));
+      }
+    }
+    return { pdf, pngs, scratch, ms: Date.now() - t0 };
+  } catch (err) {
+    await fs.rm(scratch, { recursive: true, force: true }).catch(() => {});
+    throw err;
+  }
+}
+
+export async function cleanupRender(res) {
+  if (!res?.scratch) return;
+  await fs.rm(res.scratch, { recursive: true, force: true }).catch(() => {});
+}