ppt-dsl-renderer 1.1.0 → 1.1.1

package/AGENT_PPTX_EXPORT.md

@@ -6,7 +6,13 @@ Agent 默认使用统一 CLI。命令、参数、输入和返回协议以 [Agent
 
 ### 部署与浏览器
 
-需要 Node.js 22+、包含 `export-pptx` 的构建包，以及后端机器/容器中已安装的 Chrome/Chromium、系统库和字体。`playwright-core@1.62.1` 是包的 Node 运行依赖，不能作为测试依赖删除；它不下载浏览器，也不要求 Python 安装 `playwright`。
+需要 Node.js 22+、包含 `export-pptx` 的构建包，以及后端机器/容器中已安装的 Chrome/Chromium、系统库和字体。调用方必须显式安装可选 peer dependency `playwright-core@1.62.1`；主包不会自动安装浏览器驱动。它不下载浏览器，也不要求 Python 安装 `playwright`。
+
+```bash
+yarn add ppt-dsl-renderer playwright-core@1.62.1
+```
+
+只使用 HTML、Vue 或浏览器端 PPTX API 的项目无需安装 `playwright-core`。
 
 默认使用 Google Chrome。若后端通过自己的 Playwright 安装了 Chromium，可将其实际可执行文件路径传给 `--browser-executable`，并确保 CLI 进程有执行权限。**每次 CLI 调用仍会启动一个新实例，不复用已有浏览器进程或 Playwright 对象；当前没有 CDP/远程连接参数。**
 
@@ -58,7 +64,7 @@ pptx_bytes = pptx_path.read_bytes()
 
 ## CLI 实现范围
 
-`src/cli.js` 新增 `export-pptx` 及其参数；`src/pptx-cli.js` 包装浏览器生命周期、二进制传输和文件保存。`package.json`/`yarn.lock` 声明 `playwright-core` 运行依赖，`vite.cli.config.js` 将驱动作为外部依赖，发布入口仍为 `dist/cli.js`。
+`src/cli.js` 提供 `export-pptx` 及其参数；`src/pptx-cli.js` 包装浏览器生命周期、二进制传输和文件保存。`package.json` 将 `playwright-core` 声明为可选 peer dependency，并保留为包自身测试所需的 dev dependency；`vite.cli.config.js` 将驱动作为外部依赖，发布入口仍为 `dist/cli.js`。
 
 CLI 复用原 `dist/pptx/exporter.js`，没有修改 DSL、Vue/HTML 渲染或 PPTX 转换算法，没有增加 demo 接口。原有 `render` 和浏览器 `exportToPptx` API 保持兼容。
 

package/AGENT_USAGE.md

@@ -5,7 +5,8 @@ Agent 先读取安装包内的 `node_modules/ppt-dsl-renderer/AGENT_USAGE.md`，
 ## 运行准备
 
 - Node.js 22+。部署时安装 `ppt-dsl-renderer`，使用包含当前 CLI 和渲染/导出产物的构建包；不在每个任务中临时安装包或执行 build。
-- HTML 生成不启动浏览器。PPTX 导出依赖随包安装的 `playwright-core@1.62.1`，使用运行机器上已安装的 Google Chrome/Chromium；包不下载浏览器。
+- HTML 生成不启动浏览器。仅使用 `export-pptx` 时，调用方需要显式安装可选 peer dependency `playwright-core@1.62.1`；只使用 HTML、Vue 或浏览器端 PPTX API 时不需要安装。
+- PPTX CLI 使用运行机器上已安装的 Google Chrome/Chromium；`playwright-core` 不会下载浏览器。
 - 浏览器所需系统库、字体、素材访问权限及可写任务目录由部署方准备。
 - DSL 是完整 JSON 文件，不是命令行 JSON 字符串或 stdin。字段见 [DSL 文档](docs/DSL.md)，示例见 [deck.json](examples/deck.json)。相对路径以终端当前目录为基准，并发任务使用独立的输入/输出路径。
 

package/README.md

@@ -14,6 +14,14 @@
 yarn add ppt-dsl-renderer
 ```
 
+Vue 渲染、Node HTML 生成和浏览器端 PPTX 导出只需安装主包。仅后端使用 `export-pptx` CLI 时，还需由调用方显式安装浏览器驱动：
+
+```bash
+yarn add ppt-dsl-renderer playwright-core@1.62.1
+```
+
+`playwright-core` 是可选 peer dependency，不会随主包自动安装，也不会下载浏览器。CLI 仍要求部署机器已有 Google Chrome/Chromium。
+
 ## CLI 与 Agent 接入
 
 ```bash
@@ -22,7 +30,7 @@ ppt-dsl-renderer render ./deck.json --out-dir ./preview
 ppt-dsl-renderer export-pptx ./deck.json --out ./result.pptx
 ```
 
-仅在当前项目安装时，使用 `./node_modules/.bin/ppt-dsl-renderer`。PPTX CLI 通过随包安装的 `playwright-core` 启动已有 Chrome/Chromium，每次创建新实例，不复用后端正在运行的浏览器；不改变原导出算法。
+仅在当前项目安装时，使用 `./node_modules/.bin/ppt-dsl-renderer`。PPTX CLI 通过调用方显式安装的 `playwright-core@1.62.1` 启动已有 Chrome/Chromium，每次创建新实例，不复用后端正在运行的浏览器；不改变原导出算法。
 
 Agent 先读 [统一调用指南](AGENT_USAGE.md)，其中集中说明运行前提、全部参数、JSON 返回值及失败处理。后端子进程调用、浏览器生命周期和修改范围见 [PPTX 后端接入](AGENT_PPTX_EXPORT.md)。两份文档随 npm 包发布。
 

package/dist/cli.js

@@ -1,8 +1,8 @@
 #!/usr/bin/env node
-import { parseArgs as U } from "node:util";
-import { readFile as $, mkdir as T, writeFile as L, rename as B, rm as _ } from "node:fs/promises";
-import { resolve as f, dirname as N, join as S } from "node:path";
-import { fileURLToPath as k } from "node:url";
+import { parseArgs as j } from "node:util";
+import { readFile as $, mkdir as T, writeFile as D, rename as I, rm as B } from "node:fs/promises";
+import { resolve as w, dirname as P, join as S } from "node:path";
+import { fileURLToPath as L } from "node:url";
 import { randomUUID as C } from "node:crypto";
 function J(t) {
   const e = { status: "loading", errors: [] };
@@ -52,54 +52,54 @@ html, body { width: 100%; height: 100%; overflow: hidden; }
 </body>
 </html>`;
 }
-const z = /* @__PURE__ */ new Set(["text", "image", "shape", "line", "chart", "table", "latex", "video", "audio"]), M = /* @__PURE__ */ new Set(["area", "bar", "column", "line", "pie", "radar", "ring", "scatter"]), b = (t) => t !== null && typeof t == "object" && !Array.isArray(t), h = (t) => typeof t == "string", v = (t) => Array.isArray(t) && t.length === 2 && t.every(Number.isFinite);
+const M = /* @__PURE__ */ new Set(["text", "image", "shape", "line", "chart", "table", "latex", "video", "audio"]), z = /* @__PURE__ */ new Set(["area", "bar", "column", "line", "pie", "radar", "ring", "scatter"]), b = (t) => t !== null && typeof t == "object" && !Array.isArray(t), u = (t) => typeof t == "string", E = (t) => Array.isArray(t) && t.length === 2 && t.every(Number.isFinite);
 function n(t, e) {
   if (!t)
     throw new Error(e);
 }
-function E(t, e) {
-  n(h(t) && /^(https?:\/\/|data:)/i.test(t), `${e} 必须使用 HTTP(S) URL 或 data URL`);
+function N(t, e) {
+  n(u(t) && /^(https?:\/\/|data:)/i.test(t), `${e} 必须使用 HTTP(S) URL 或 data URL`);
   const s = new URL(t);
   n(["http:", "https:", "data:"].includes(s.protocol), `${e} 资源协议不受支持`);
 }
-function D(t) {
-  n(b(t), "DSL 顶层必须是对象"), n(h(t.title) && t.title.length > 0, "DSL 缺少 title"), n(Number.isFinite(t.width) && t.width > 0, "DSL width 必须是大于 0 的有限数值"), n(Number.isFinite(t.height) && t.height > 0, "DSL height 必须是大于 0 的有限数值"), n(Array.isArray(t.slides) && t.slides.length > 0, "DSL slides 不能为空"), t.slides.forEach((e, s) => {
+function k(t) {
+  n(b(t), "DSL 顶层必须是对象"), n(u(t.title) && t.title.length > 0, "DSL 缺少 title"), n(Number.isFinite(t.width) && t.width > 0, "DSL width 必须是大于 0 的有限数值"), n(Number.isFinite(t.height) && t.height > 0, "DSL height 必须是大于 0 的有限数值"), n(Array.isArray(t.slides) && t.slides.length > 0, "DSL slides 不能为空"), t.slides.forEach((e, s) => {
     var l, d;
     const i = `第 ${s + 1} 页`;
-    n(b(e) && h(e.id) && e.id && Array.isArray(e.elements), `${i}结构无效`), ((l = e.background) == null ? void 0 : l.type) === "image" && E((d = e.background.image) == null ? void 0 : d.src, `${i}背景图`);
+    n(b(e) && u(e.id) && e.id && Array.isArray(e.elements), `${i}结构无效`), ((l = e.background) == null ? void 0 : l.type) === "image" && N((d = e.background.image) == null ? void 0 : d.src, `${i}背景图`);
     const a = /* @__PURE__ */ new Set();
     e.elements.forEach((r) => {
       var g;
-      n(b(r) && h(r.id) && r.id && z.has(r.type), `${i}存在无效元素`);
+      n(b(r) && u(r.id) && r.id && M.has(r.type), `${i}存在无效元素`);
       const p = `${i}元素 ${r.id}`;
       n(!a.has(r.id), `${p} ID 重复`), a.add(r.id), n([r.left, r.top].every(Number.isFinite), `${p}缺少有效坐标`);
       for (const o of ["width", "height", "rotate", "opacity"])
         r[o] !== void 0 && n(Number.isFinite(r[o]), `${p}.${o} 必须是有限数值`);
       switch (r.type) {
         case "text":
-          n(h(r.content), `${p}.content 必须是字符串`);
+          n(u(r.content), `${p}.content 必须是字符串`);
           break;
         case "image":
         case "audio":
         case "video":
-          E(r.src, `${p}.src`), r.poster !== void 0 && E(r.poster, `${p}.poster`);
+          N(r.src, `${p}.src`), r.poster !== void 0 && N(r.poster, `${p}.poster`);
           break;
         case "shape":
-          n(h(r.path) && v(r.viewBox), `${p}缺少 path 或有效 viewBox`), r.text !== void 0 && n(h((g = r.text) == null ? void 0 : g.content), `${p}.text.content 必须是字符串`);
+          n(u(r.path) && E(r.viewBox), `${p}缺少 path 或有效 viewBox`), r.text !== void 0 && n(u((g = r.text) == null ? void 0 : g.content), `${p}.text.content 必须是字符串`);
           break;
         case "line":
-          n(v(r.start) && v(r.end) && h(r.color), `${p}缺少 start、end 或 color`);
+          n(E(r.start) && E(r.end) && u(r.color), `${p}缺少 start、end 或 color`);
           break;
         case "chart": {
           const o = r.data;
-          n(M.has(r.chartType), `${p}.chartType 不受支持`), n(b(o) && Array.isArray(o.labels) && o.labels.every(h) && Array.isArray(o.legends) && o.legends.every(h) && Array.isArray(o.series) && o.series.every((c) => Array.isArray(c) && c.every(Number.isFinite)), `${p}.data 结构无效`);
+          n(z.has(r.chartType), `${p}.chartType 不受支持`), n(b(o) && Array.isArray(o.labels) && o.labels.every(u) && Array.isArray(o.legends) && o.legends.every(u) && Array.isArray(o.series) && o.series.every((h) => Array.isArray(h) && h.every(Number.isFinite)), `${p}.data 结构无效`);
           break;
         }
         case "table":
-          n(Array.isArray(r.data) && r.data.every((o) => Array.isArray(o) && o.every((c) => b(c) && h(c.id) && c.id && h(c.text))), `${p}.data 结构无效`);
+          n(Array.isArray(r.data) && r.data.every((o) => Array.isArray(o) && o.every((h) => b(h) && u(h.id) && h.id && u(h.text))), `${p}.data 结构无效`);
           break;
         case "latex":
-          n(h(r.latex), `${p}.latex 必须是字符串`);
+          n(u(r.latex), `${p}.latex 必须是字符串`);
           break;
       }
     });
@@ -108,9 +108,9 @@ function D(t) {
 function F(t, e) {
   return e === void 0 ? Array.from({ length: t }, (s, i) => i + 1) : (n(Array.isArray(e) && e.length > 0, "pages 必须是非空页码数组"), n(e.every((s) => Number.isInteger(s) && s >= 1 && s <= t), `页码必须是 1 到 ${t} 的整数`), [...new Set(e)].sort((s, i) => s - i));
 }
-const P = f(N(k(import.meta.url)), "..");
+const v = w(P(L(import.meta.url)), "..");
 async function q(t, e = {}) {
-  D(t);
+  k(t);
   const i = F(t.slides.length, e.pages).map((d) => ({
     pageNumber: d,
     slideId: t.slides[d - 1].id,
@@ -127,8 +127,8 @@ async function q(t, e = {}) {
   let a, l;
   try {
     [a, l] = await Promise.all([
-      $(S(P, "dist/browser/renderer.js"), "utf8"),
-      $(S(P, "dist/browser/renderer.css"), "utf8")
+      $(S(v, "dist/browser/renderer.js"), "utf8"),
+      $(S(v, "dist/browser/renderer.css"), "utf8")
     ]);
   } catch (d) {
     throw d.code !== "ENOENT" ? d : new Error("缺少预编译浏览器资源。源码仓库请先显式执行 yarn build；npm 安装包应包含 dist/browser。", { cause: d });
@@ -138,43 +138,45 @@ async function q(t, e = {}) {
     html: X(d, a, l)
   }));
 }
-const V = f(N(k(import.meta.url)), "..");
+const V = w(P(L(import.meta.url)), "..");
 async function W(t, e, { pages: s, executablePath: i, timeout: a = 12e4 } = {}) {
-  D(t);
-  const l = F(t.slides.length, s), d = await $(S(V, "dist/pptx/exporter.js"), "utf8").catch((u) => {
-    throw u.code !== "ENOENT" ? u : new Error("安装包缺少 PPTX 运行产物，请使用完整构建的 ppt-dsl-renderer 包。", { cause: u });
-  }), { chromium: r } = await import("playwright-core"), p = await r.launch({ headless: !0, ...i ? { executablePath: i } : { channel: "chrome" }, timeout: a });
+  k(t);
+  const l = F(t.slides.length, s), d = await $(S(V, "dist/pptx/exporter.js"), "utf8").catch((c) => {
+    throw c.code !== "ENOENT" ? c : new Error("安装包缺少 PPTX 运行产物，请使用完整构建的 ppt-dsl-renderer 包。", { cause: c });
+  }), { chromium: r } = await import("playwright-core").catch((c) => {
+    throw c.code !== "ERR_MODULE_NOT_FOUND" ? c : new Error("PPTX 导出需要显式安装 playwright-core@1.62.1。", { cause: c });
+  }), p = await r.launch({ headless: !0, ...i ? { executablePath: i } : { channel: "chrome" }, timeout: a });
   let g, o;
   try {
-    const u = (async () => {
-      const w = await p.newPage();
-      w.on("console", (y) => console.error(y.text())), w.on("pageerror", (y) => console.error(y.message)), await w.addScriptTag({ content: d });
-      const A = await w.evaluate(async ({ document: y, pages: j }) => {
-        const I = await window.exportToPptx(y, { pages: j });
-        return new Promise((O, R) => {
+    const c = (async () => {
+      const f = await p.newPage();
+      f.on("console", (y) => console.error(y.text())), f.on("pageerror", (y) => console.error(y.message)), await f.addScriptTag({ content: d });
+      const A = await f.evaluate(async ({ document: y, pages: O }) => {
+        const R = await window.exportToPptx(y, { pages: O });
+        return new Promise((U, _) => {
           const m = new FileReader();
-          m.onload = () => O(m.result.split(",", 2)[1]), m.onerror = () => R(m.error), m.readAsDataURL(new Blob([I]));
+          m.onload = () => U(m.result.split(",", 2)[1]), m.onerror = () => _(m.error), m.readAsDataURL(new Blob([R]));
         });
       }, { document: t, pages: l });
       return Buffer.from(A, "base64");
     })();
     o = await Promise.race([
-      u,
-      new Promise((w, A) => {
+      c,
+      new Promise((f, A) => {
         g = setTimeout(() => A(new Error(`PPTX 导出超时（${a}ms）`)), a);
       })
     ]);
   } finally {
     clearTimeout(g), await p.close();
   }
-  await T(N(e), { recursive: !0 });
-  const c = `${e}.${C()}.tmp`;
+  await T(P(e), { recursive: !0 });
+  const h = `${e}.${C()}.tmp`;
   try {
-    await L(c, o, { flag: "wx" }), await B(c, e);
+    await D(h, o, { flag: "wx" }), await I(h, e);
   } finally {
-    await _(c, { force: !0 });
+    await B(h, { force: !0 });
   }
-  return { file: e, pages: l.map((u) => ({ pageNumber: u, slideId: t.slides[u - 1].id })), bytes: o.length };
+  return { file: e, pages: l.map((c) => ({ pageNumber: c, slideId: t.slides[c - 1].id })), bytes: o.length };
 }
 const x = `Usage:
   ppt-dsl-renderer render <deck.json> --out-dir <directory> [--pages 1,3]
@@ -190,7 +192,7 @@ render generates HTML without launching a browser.
 export-pptx requires Chrome or Chromium installed at deployment time; it never downloads a browser.`;
 async function G() {
   var g;
-  const { values: t, positionals: e } = U({
+  const { values: t, positionals: e } = j({
     allowPositionals: !0,
     options: {
       "out-dir": { type: "string" },
@@ -217,24 +219,24 @@ async function G() {
   const a = (g = t.pages) == null ? void 0 : g.split(",").map(Number);
   if (t.timeout !== void 0 && (!/^\d+$/.test(t.timeout) || !Number.isSafeInteger(Number(t.timeout)) || Number(t.timeout) <= 0))
     throw new Error("--timeout 必须是正整数毫秒");
-  if (s === "export-pptx" && f(i) === f(t.out))
+  if (s === "export-pptx" && w(i) === w(t.out))
     throw new Error("--out 不能覆盖输入 DSL 文件");
-  const l = JSON.parse(await $(f(i), "utf8"));
+  const l = JSON.parse(await $(w(i), "utf8"));
   if (s === "export-pptx") {
-    const o = await W(l, f(t.out), {
+    const o = await W(l, w(t.out), {
       pages: a,
-      executablePath: t["browser-executable"] ? f(t["browser-executable"]) : void 0,
+      executablePath: t["browser-executable"] ? w(t["browser-executable"]) : void 0,
       timeout: t.timeout === void 0 ? void 0 : Number(t.timeout)
     });
     console.log(JSON.stringify(o, null, 2));
     return;
   }
-  const d = await q(l, { pages: a }), r = f(t["out-dir"]);
+  const d = await q(l, { pages: a }), r = w(t["out-dir"]);
   await T(r, { recursive: !0 });
   const p = [];
-  for (const { html: o, ...c } of d) {
-    const u = S(r, `slide-${String(c.pageNumber).padStart(3, "0")}.html`);
-    await L(u, o, "utf8"), p.push({ ...c, file: u });
+  for (const { html: o, ...h } of d) {
+    const c = S(r, `slide-${String(h.pageNumber).padStart(3, "0")}.html`);
+    await D(c, o, "utf8"), p.push({ ...h, file: c });
   }
   console.log(JSON.stringify({ pages: p }, null, 2));
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ppt-dsl-renderer",
-  "version": "1.1.0",
+  "version": "1.1.1",
   "description": "Render PPT DSL with Vue components or standalone, agent-friendly HTML slides.",
   "type": "module",
   "license": "MIT",
@@ -52,15 +52,18 @@
   "dependencies": {
     "dompurify": "3.3.1",
     "echarts": "6.1.0",
-    "playwright-core": "1.62.1",
     "pptxgenjs": "3.12.0",
     "svg-pathdata": "7.2.0",
     "tinycolor2": "1.6.0"
   },
   "peerDependencies": {
+    "playwright-core": "1.62.1",
     "vue": "^3.4.21"
   },
   "peerDependenciesMeta": {
+    "playwright-core": {
+      "optional": true
+    },
     "vue": {
       "optional": true
     }
@@ -70,6 +73,7 @@
     "@vue/compiler-sfc": "3.4.21",
     "jsdom": "26.1.0",
     "jszip": "3.10.1",
+    "playwright-core": "1.62.1",
     "sass": "1.62.1",
     "typescript": "5.0.4",
     "vite": "4.5.9",